feat: Shadow Run Design Phase — 252+ trading-day validation framework
Implements foundation for model evaluation per AGENTS.md v16.0: - Domain models: ShadowRunCommand, ShadowRunResult, ValidationGates - Data backfiller: OHLCV + fee schedule collection from KRX API - Replay engine: Historical model simulation with signal/order/fill tracking - Metrics calculator: Sharpe, Calmar, PBO, DSR, Max Drawdown, Win Rate - Hangfire job orchestrator: Async shadow run execution (q-research queue) - Integration tests: 4/4 passing (backfill, replay, metrics, validation) Contract validation: - Input: Model ID, date window, market phase filter - Output: Immutable result with phase breakdown, gate status - Gates: PBO ≤ 20%, DSR ≥ 95%, cost 2x positive Architecture adherence: - SOLID: Single responsibility (backfiller, replay, calculator separation) - Complexity: Cyclomatic < 10 per method - Safety: Idempotent replay via deterministic price/order fills - Necessity: Grounded in CLAUDE.md § "Validation Gates" - Pattern: Vertical Slice (Command → Handler → Queries) Not included (future): - Full 252-day rehearsal (requires market data backfill) - Downstream inbox consumers (event delivery mechanisms) - Phase segmentation logic (Bull/Bear/Sideways attribution) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,86 @@
|
||||
namespace KArtSell.Modules.ModelOperations.ShadowRun;
|
||||
|
||||
/// <summary>
|
||||
/// Immutable result of shadow run evaluation.
|
||||
/// Includes performance metrics, phase attribution, and validation gates.
|
||||
/// </summary>
|
||||
public sealed record ShadowRunResult(
|
||||
Guid RunId,
|
||||
Guid ModelId,
|
||||
DateOnly WindowStartDate,
|
||||
DateOnly WindowEndDate,
|
||||
ShadowRunStatus Status,
|
||||
ShadowRunMetrics Metrics,
|
||||
PhaseBreakdown PhaseAnalysis,
|
||||
CostAnalysis CostAnalysis,
|
||||
FalseExitAnalysis FalseExitAnalysis,
|
||||
ValidationGates ValidationGates,
|
||||
string? ErrorMessage = null,
|
||||
DateTimeOffset CreatedAt = default);
|
||||
|
||||
/// <summary>
|
||||
/// Execution status of shadow run.
|
||||
/// </summary>
|
||||
public enum ShadowRunStatus
|
||||
{
|
||||
Pending = 0,
|
||||
DataBackfill = 1,
|
||||
Replay = 2,
|
||||
EvaluationComplete = 3,
|
||||
Failed = 4
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Performance metrics for shadow run period.
|
||||
/// </summary>
|
||||
public sealed record ShadowRunMetrics(
|
||||
decimal TotalReturn, // % return over period
|
||||
decimal SharpeRatio, // Daily Sharpe ratio
|
||||
decimal CalmurRatio, // Calmar ratio (return / max drawdown)
|
||||
decimal MaximumDrawdown, // Peak-to-trough % loss
|
||||
decimal WinRate, // % of profitable days
|
||||
decimal ProbOfBacktestOverfit, // PBO score (must be ≤ 20%)
|
||||
decimal DailySharePercentile, // DSR percentile (must be ≥ 95%)
|
||||
int TradingDays); // Actual trading days in period
|
||||
|
||||
/// <summary>
|
||||
/// Market phase segmentation: Bull, Bear, Sideways, Volatility.
|
||||
/// </summary>
|
||||
public sealed record PhaseBreakdown(
|
||||
PhaseMetrics BullMarket,
|
||||
PhaseMetrics BearMarket,
|
||||
PhaseMetrics Sideways,
|
||||
PhaseMetrics HighVolatility);
|
||||
|
||||
public sealed record PhaseMetrics(
|
||||
int TradingDays,
|
||||
decimal Return,
|
||||
decimal Sharpe,
|
||||
decimal WinRate,
|
||||
decimal MaxDrawdown);
|
||||
|
||||
/// <summary>
|
||||
/// Cost analysis: base scenario vs. 2x cost scenario.
|
||||
/// </summary>
|
||||
public sealed record CostAnalysis(
|
||||
decimal BaseScenarioReturn,
|
||||
decimal TwoXCostReturn,
|
||||
bool PassesTwoXPositive); // TwoXCostReturn > 0
|
||||
|
||||
/// <summary>
|
||||
/// False exit analysis: reentry success rate, duration out of position.
|
||||
/// </summary>
|
||||
public sealed record FalseExitAnalysis(
|
||||
int FalseExitCount,
|
||||
int ReentrySuccessCount,
|
||||
decimal ReentrySuccessRate,
|
||||
decimal AverageDaysOutOfPosition);
|
||||
|
||||
/// <summary>
|
||||
/// Validation gates: pass/fail for production readiness.
|
||||
/// </summary>
|
||||
public sealed record ValidationGates(
|
||||
bool PboUnder20, // PBO ≤ 20%
|
||||
bool DsrAbove95, // DSR ≥ 95th percentile
|
||||
bool CostTwoXPositive, // 2x cost scenario profitable
|
||||
bool AllGatesPassed); // AND of all above
|
||||
Reference in New Issue
Block a user