@tradejs/cli 3.1.29-beta.289 → 3.1.29-beta.291

package/dist/scripts/replayRunner.js

@@ -4990,7 +4990,13 @@ var loadReplayRuntimeEvidenceMetadata = async (params) => {
     userName: artifact.userName,
     startTime: artifact.startTime,
     endTime: artifact.endTime,
-    deployment: artifact.deployment
+    deployment: artifact.deployment,
+    decisionTraceTargets: unwrapRows(
+      artifact.runtime.trades,
+      "trade"
+    ).flatMap(
+      ({ strategy, symbol, signalTimestamp }) => typeof signalTimestamp === "number" && Number.isFinite(signalTimestamp) && artifact.startTime != null && artifact.endTime != null && signalTimestamp >= artifact.startTime && signalTimestamp < artifact.endTime ? [{ strategy, symbol, signalTimestamp }] : []
+    )
   };
 };
 var buildRuntimeEvidenceLineageScopes = ({
@@ -5182,6 +5188,9 @@ var createPortfolioReplayConnector = (connector) => {
   let executionTimestamp = null;
   const positionsBySymbol = /* @__PURE__ */ new Map();
   const currentPriceBySymbol = /* @__PURE__ */ new Map();
+  const markedAtBySymbol = /* @__PURE__ */ new Map();
+  const entryFacts = /* @__PURE__ */ new Map();
+  let portfolioObserved = false;
   const orderLog = [];
   const positionLog = [];
   const orderLogByStrategy = /* @__PURE__ */ new Map();
@@ -5419,14 +5428,51 @@ var createPortfolioReplayConnector = (connector) => {
       const { strategyName: _strategyName, ...nextPosition } = position;
       return nextPosition;
     }),
+    getPortfolioObservation: async (asOf, reservations) => {
+      portfolioObserved = true;
+      const pendingIds = new Set(reservations.map((r) => r.id));
+      for (const id of entryFacts.keys())
+        if (!pendingIds.has(id)) entryFacts.delete(id);
+      return {
+        asOf,
+        positions: Array.from(positionsBySymbol.values()).map(
+          ({ position, stopLossPrice }) => ({
+            id: position.orderId ?? `${position.strategyName}:${position.symbol}:${position.timestamp}`,
+            strategy: position.strategyName === UNKNOWN_STRATEGY ? null : position.strategyName,
+            symbol: position.symbol,
+            direction: position.direction,
+            qty: position.qty,
+            entryPrice: position.price,
+            markPrice: currentPriceBySymbol.get(position.symbol) ?? null,
+            markedAt: markedAtBySymbol.get(position.symbol) ?? null,
+            stopLossPrice
+          })
+        ),
+        orders: reservations.map(
+          (r) => entryFacts.get(r.id) ?? {
+            id: r.id,
+            status: "pending",
+            filledQty: 0
+          }
+        )
+      };
+    },
     getOpenPositionPnl: async () => Array.from(positionsBySymbol.values()).map(
-      ({ position }) => getPositionPnlSnapshot({
-        position,
-        currentPrice: currentPriceBySymbol.get(position.symbol) ?? position.price
+      ({ position, stopLossPrice }) => ({
+        ...getPositionPnlSnapshot({
+          position,
+          currentPrice: currentPriceBySymbol.get(position.symbol) ?? position.price
+        }),
+        observedAt: markedAtBySymbol.get(position.symbol),
+        stopLossPrice
       })
     ),
     placeOrder: async (order) => {
-      const { beforeSubmit, ...submittedOrder } = order;
+      const {
+        beforeSubmit,
+        onRejected: _onRejected,
+        ...submittedOrder
+      } = order;
       if (positionsBySymbol.has(order.symbol)) {
         return false;
       }
@@ -5470,6 +5516,14 @@ var createPortfolioReplayConnector = (connector) => {
         stopLossPrice: null
       };
       positionsBySymbol.set(order.symbol, positionState);
+      markedAtBySymbol.set(order.symbol, executionTimestamp ?? order.timestamp);
+      if (portfolioObserved && order.orderId)
+        entryFacts.set(order.orderId, {
+          id: order.orderId,
+          status: "filled",
+          filledQty: order.qty,
+          positionId: order.orderId
+        });
       logOrder({
         positionState,
         data: {
@@ -5553,6 +5607,7 @@ var createPortfolioReplayConnector = (connector) => {
     getTickers: connector.getTickers,
     advanceMarket: async ({ symbol, candle }) => {
       executionTimestamp = candle.timestamp;
+      markedAtBySymbol.set(symbol, candle.timestamp);
       currentPriceBySymbol.set(symbol, candle.close);
       await checkSl({ symbol, candle });
       await checkTp({ symbol, candle });
@@ -5593,6 +5648,73 @@ var invokeAfterSignalsHooks = async (hooks, params) => {
   }
 };
 
+// src/lib/replay/historicalSignalsReplayDecisionTrace.ts
+var replayDecisionTraceKey = ({
+  strategy,
+  symbol,
+  signalTimestamp
+}) => JSON.stringify([strategy, symbol, signalTimestamp]);
+var describeOutcome = (result) => {
+  if (typeof result === "string") {
+    return {
+      stage: result.startsWith("BACKTEST_ENTRY_DELAY_") ? "entry_delay" : /(?:NO_PATTERN|POSITION_EXISTS)$/.test(result) ? "core" : "evaluation",
+      reason: result
+    };
+  }
+  if (!result) return { stage: "evaluation", reason: "NO_SIGNAL" };
+  const reason = result.orderSkipReason || result.orderFailureReason || result.orderStatus || "SIGNAL";
+  const patternContext = result.additionalIndicators?.tradingPatternsContext;
+  return {
+    stage: result.riskDecision?.status === "rejected" || /^ENTRY_(?:RR_BELOW|RISK_EXCEEDS)/.test(reason) ? "risk" : /^(?:AI_|ML_|HOOK_BEFORE_ENTRY_GATE|RESEARCH_ENTRY_POLICY)/.test(
+      reason
+    ) ? "gate" : result.orderStatus ? "execution" : "evaluation",
+    reason,
+    direction: result.direction,
+    orderStatus: result.orderStatus,
+    ...typeof patternContext?.selectedPattern === "string" ? { pattern: patternContext.selectedPattern } : {},
+    ...typeof patternContext?.sourceCode === "string" ? { patternCode: patternContext.sourceCode } : {}
+  };
+};
+var createReplayDecisionTrace = (targets = []) => {
+  const traces = /* @__PURE__ */ new Map();
+  const symbols = new Set(targets.map(({ symbol }) => symbol));
+  for (const target of targets) {
+    traces.set(replayDecisionTraceKey(target), {
+      ...target,
+      decision: {
+        stage: "not_evaluated",
+        reason: "REPLAY_CANDLE_NOT_EVALUATED"
+      }
+    });
+  }
+  const record = (strategy, symbol, candle, result, notEvaluatedReason) => {
+    if (!symbols.has(symbol)) return;
+    const { timestamp, open, high, low, close, volume } = candle;
+    const trace = traces.get(
+      replayDecisionTraceKey({ strategy, symbol, signalTimestamp: timestamp })
+    );
+    if (result && typeof result !== "string" && result.timestamp !== timestamp) {
+      const original = traces.get(
+        replayDecisionTraceKey({
+          strategy,
+          symbol,
+          signalTimestamp: result.timestamp
+        })
+      );
+      if (original)
+        original.followUp = {
+          ...describeOutcome(result),
+          candleTimestamp: timestamp
+        };
+      notEvaluatedReason = "REPLAY_PROCESSED_DELAYED_ENTRY";
+    }
+    if (!trace) return;
+    trace.candle = { timestamp, open, high, low, close, volume };
+    trace.decision = notEvaluatedReason ? { stage: "not_evaluated", reason: notEvaluatedReason } : describeOutcome(result);
+  };
+  return { record, values: () => [...traces.values()] };
+};
+
 // src/lib/replay/historicalSignalsReplaySkipEvidence.ts
 var import_data2 = require("@tradejs/core/data");
 var replayScopeKey = (strategy, symbol) => `${strategy}::${symbol}`;
@@ -5703,6 +5825,7 @@ var executeHistoricalReplay = async (context, adapters) => {
     context.plan.runtimeLineages,
     context.collectSkipEvidence
   );
+  const decisionTrace = createReplayDecisionTrace(context.decisionTraceTargets);
   const reportProgress = (timestamp) => {
     if (adapters.progress.enabled === false) return;
     adapters.progress.tick({
@@ -5731,6 +5854,20 @@ var executeHistoricalReplay = async (context, adapters) => {
           status: "completed",
           durationMs: adapters.clock.now() - cycleStartedAt
         });
+        if (context.decisionTraceTargets?.length) {
+          for (const symbolRuntime of cycleSymbols) {
+            const candle = symbolRuntime.replayData[symbolRuntime.currentIndex];
+            for (const strategy of symbolRuntime.strategies) {
+              decisionTrace.record(
+                strategy.strategyName,
+                symbolRuntime.symbol,
+                candle,
+                void 0,
+                "REPLAY_CYCLE_ABORTED"
+              );
+            }
+          }
+        }
         advanceAbortedCycle(cycleSymbols, timestamp);
         reportProgress(timestamp);
         continue;
@@ -5741,6 +5878,17 @@ var executeHistoricalReplay = async (context, adapters) => {
         const btcCandle = symbolRuntime.btcReplayData[symbolRuntime.currentIndex];
         const ethCandle = symbolRuntime.ethReplayData[symbolRuntime.currentIndex];
         if (!candle || !btcCandle || candle.timestamp + (symbolRuntime.timestampOffsetMs ?? 0) !== timestamp || btcCandle.timestamp !== candle.timestamp) {
+          if (candle && context.decisionTraceTargets?.length) {
+            for (const strategy of symbolRuntime.strategies) {
+              decisionTrace.record(
+                strategy.strategyName,
+                symbolRuntime.symbol,
+                candle,
+                void 0,
+                "REPLAY_CANDLE_OR_REFERENCE_NOT_ALIGNED"
+              );
+            }
+          }
           continue;
         }
         for (const strategyRuntime of symbolRuntime.strategies) {
@@ -5749,6 +5897,12 @@ var executeHistoricalReplay = async (context, adapters) => {
             btcCandle,
             ethCandle?.timestamp === candle.timestamp ? ethCandle : void 0
           );
+          decisionTrace.record(
+            strategyRuntime.strategyName,
+            symbolRuntime.symbol,
+            candle,
+            result
+          );
           skipEvidence.record({
             strategyName: strategyRuntime.strategyName,
             symbol: symbolRuntime.symbol,
@@ -5780,7 +5934,8 @@ var executeHistoricalReplay = async (context, adapters) => {
   return {
     signals,
     abortedCycles,
-    replayLineageScopes: skipEvidence.values()
+    replayLineageScopes: skipEvidence.values(),
+    replayDecisionTraces: decisionTrace.values()
   };
 };
 
@@ -5831,7 +5986,8 @@ var collectHistoricalReplayResult = (context) => ({
   cycleCount: context.cycleCount,
   abortedCycles: context.abortedCycles,
   runtimeLineages: context.runtimeLineages,
-  replayLineageScopes: context.replayLineageScopes
+  replayLineageScopes: context.replayLineageScopes,
+  ...context.replayDecisionTraces?.length ? { replayDecisionTraces: context.replayDecisionTraces } : {}
 });
 var compactHistoricalReplayResultForPortfolio = (result) => ({
   ...result,
@@ -5877,7 +6033,10 @@ var mergeHistoricalReplayResults = (parts) => {
     cycleCount: parts.reduce((sum, part) => sum + part.cycleCount, 0),
     abortedCycles: parts.reduce((sum, part) => sum + part.abortedCycles, 0),
     runtimeLineages: parts.flatMap((part) => part.runtimeLineages),
-    replayLineageScopes: parts.flatMap((part) => part.replayLineageScopes)
+    replayLineageScopes: parts.flatMap((part) => part.replayLineageScopes),
+    replayDecisionTraces: parts.flatMap(
+      (part) => part.replayDecisionTraces ?? []
+    )
   };
 };
 
@@ -6028,7 +6187,8 @@ var runHistoricalSignalsReplay = async ({
   references,
   showProgress = true,
   collectSkipEvidence = true,
-  collectSignals = true
+  collectSignals = true,
+  decisionTraceTargets
 }) => {
   const memory = createReplayMemoryProfile();
   memory?.("prepare:start");
@@ -6115,6 +6275,7 @@ var runHistoricalSignalsReplay = async ({
       connector: replayConnector,
       collectSkipEvidence,
       collectSignals,
+      decisionTraceTargets,
       hooks: projectHooks,
       hookContext
     },
@@ -6151,7 +6312,8 @@ var runHistoricalSignalsReplay = async ({
     cycleCount: plan.orderedTimestamps.length,
     abortedCycles: execution.abortedCycles,
     runtimeLineages: plan.runtimeLineages,
-    replayLineageScopes: execution.replayLineageScopes
+    replayLineageScopes: execution.replayLineageScopes,
+    replayDecisionTraces: execution.replayDecisionTraces
   });
   memory?.("result:collected");
   return result;
@@ -6379,6 +6541,7 @@ var extractRuntimeParityEntries = (trades) => trades.filter(
   direction: trade.direction,
   qty: toFiniteNumberOrNull2(trade.qty),
   timestamp: trade.entryTimestamp,
+  ...Number.isFinite(trade.signalTimestamp) ? { signalTimestamp: trade.signalTimestamp } : {},
   price: toFiniteNumberOrNull2(trade.entryPrice),
   orderId: trade.orderId,
   signalId: typeof trade.signalId === "string" ? trade.signalId : void 0,
@@ -7124,6 +7287,7 @@ var toRuntimeParityDetail = (entry) => ({
   direction: entry.direction,
   qty: entry.qty ?? null,
   timestamp: entry.timestamp,
+  ...entry.signalTimestamp != null ? { signalTimestamp: entry.signalTimestamp } : {},
   price: entry.price,
   exitType: entry.exitType ?? null,
   exitTimestamp: entry.exitTimestamp ?? null,
@@ -7197,7 +7361,8 @@ var findNearestEvaluation = ({
   evaluations,
   toleranceMs,
   timestampOffsetMs,
-  entryTimestampOffsetMs = 0
+  entryTimestampOffsetMs = 0,
+  matchDirection = false
 }) => {
   const entryStrategy2 = getEntryStrategy(entry);
   if (!entryStrategy2) {
@@ -7207,7 +7372,7 @@ var findNearestEvaluation = ({
   let bestDiff = Number.POSITIVE_INFINITY;
   const entryTimestamp = entry.timestamp + entryTimestampOffsetMs;
   for (const evaluation of evaluations) {
-    if (evaluation.strategy !== entryStrategy2 || evaluation.symbol !== entry.symbol) {
+    if (evaluation.strategy !== entryStrategy2 || evaluation.symbol !== entry.symbol || matchDirection && evaluation.direction != null && evaluation.direction !== entry.direction) {
       continue;
     }
     const diff = Math.abs(
@@ -7553,6 +7718,7 @@ var buildReplayMismatchDrilldown = ({
   replaySignals = [],
   replaySignalEvaluations = [],
   replayLineageScopes = [],
+  replayDecisionTraces = [],
   runtimeLineageScopes = [],
   toleranceMs,
   backtestTimestampOffsetMs,
@@ -7561,48 +7727,66 @@ var buildReplayMismatchDrilldown = ({
   const nearestByEntry = new Map(
     nearestCandidates.map((candidate) => [candidate.entry, candidate])
   );
+  const traceByCandle = new Map(
+    replayDecisionTraces.map((trace) => [replayDecisionTraceKey(trace), trace])
+  );
   const artifactLimit = Math.min(limit, resolveReplayParityArtifactLimit());
   let runtimeOnlyArtifactsIncluded = 0;
   let backtestOnlyArtifactsIncluded = 0;
   const runtimeOnlyDiagnostics = runtimeOnly.map((entry, index) => {
-    const entryOffsetMs = resolveTradeParityTimestampOffset(
-      getEntryStrategy(entry) ?? "",
-      backtestTimestampOffsetMs
-    );
+    const isRuntimeTrade = entry.source === "runtime";
+    const decisionEntry = isRuntimeTrade ? entry.signalTimestamp == null ? null : { ...entry, timestamp: entry.signalTimestamp } : entry;
+    const decisionClock = {
+      toleranceMs: isRuntimeTrade ? 0 : toleranceMs,
+      timestampOffsetMs: isRuntimeTrade ? 0 : resolveTradeParityTimestampOffset(
+        getEntryStrategy(entry) ?? "",
+        backtestTimestampOffsetMs
+      )
+    };
     const includeArtifacts = index < artifactLimit;
     const nearestCandidate = nearestByEntry.get(entry);
-    const nearestReplaySignal = findNearestSignal({
-      entry,
+    const nearestReplaySignal = decisionEntry && findNearestSignal({
+      entry: decisionEntry,
       signals: replaySignals,
-      toleranceMs,
-      timestampOffsetMs: entryOffsetMs
+      ...decisionClock
     });
-    const nearestReplayEvaluation = findNearestEvaluation({
-      entry,
+    const nearestReplayEvaluation = decisionEntry && findNearestEvaluation({
+      entry: decisionEntry,
       evaluations: replaySignalEvaluations,
-      toleranceMs,
-      timestampOffsetMs: entryOffsetMs
+      matchDirection: isRuntimeTrade,
+      ...decisionClock
     });
-    const nearestReplayEvaluationOutcome = findNearestReplayEvaluationOutcome({
-      entry,
+    const nearestReplayEvaluationOutcome = decisionEntry && findNearestReplayEvaluationOutcome({
+      entry: decisionEntry,
       lineageScopes: replayLineageScopes,
-      toleranceMs,
-      timestampOffsetMs: entryOffsetMs
+      ...decisionClock
     });
+    const strategy = getEntryStrategy(entry);
+    const replayDecisionTrace = isRuntimeTrade && strategy && decisionEntry ? traceByCandle.get(
+      replayDecisionTraceKey({
+        strategy,
+        symbol: entry.symbol,
+        signalTimestamp: decisionEntry.timestamp
+      })
+    ) : void 0;
+    const unavailableReason = !isRuntimeTrade ? "no_replay_signal_or_backtest_candidate" : !decisionEntry ? "replay_signal_timestamp_unavailable" : replayDecisionTrace?.decision.stage === "not_evaluated" ? replayDecisionTrace.decision.reason : "replay_evaluation_unavailable";
     const classification = nearestReplaySignal ? classifySignalDiagnostic(nearestReplaySignal.signal) : nearestReplayEvaluation ? classifyEvaluationDiagnostic(nearestReplayEvaluation.evaluation) : nearestReplayEvaluationOutcome ? {
-      classification: "core_skipped",
+      classification: nearestReplayEvaluationOutcome.reason.startsWith(
+        "BACKTEST_ENTRY_DELAY_"
+      ) ? "entry_delayed" : "core_skipped",
       reason: nearestReplayEvaluationOutcome.reason
-    } : nearestCandidate?.nearest ? {
+    } : !isRuntimeTrade && nearestCandidate?.nearest ? {
       classification: "timing_or_price_drift",
       reason: nearestCandidate.reason
     } : {
       classification: "no_replay_candidate",
-      reason: "no_replay_signal_or_backtest_candidate"
+      reason: unavailableReason
     };
     return {
       entry,
       ...classification,
       ...nearestCandidate ? { nearestCandidate } : {},
+      ...replayDecisionTrace ? { replayDecisionTrace } : {},
       ...nearestReplaySignal ? {
         replaySignal: toSignalDiagnostic({
           signal: nearestReplaySignal.signal,
@@ -7728,6 +7912,7 @@ var buildReplayRuntimeComparisonDetails = ({
   replaySignals,
   replaySignalEvaluations,
   replayLineageScopes,
+  replayDecisionTraces,
   runtimeLineageScopes
 }) => {
   const runtimeDetails = runtimeEntries.map(toRuntimeParityDetail);
@@ -7788,6 +7973,7 @@ var buildReplayRuntimeComparisonDetails = ({
       replaySignals,
       replaySignalEvaluations,
       replayLineageScopes,
+      replayDecisionTraces,
       runtimeLineageScopes,
       toleranceMs,
       backtestTimestampOffsetMs,
@@ -8813,6 +8999,7 @@ var saveAndPrintReplayRuntimeComparison = async ({
   replaySignals,
   replayLineages,
   replayLineageScopes,
+  replayDecisionTraces,
   runtimeEvidencePath
 }) => {
   const { connector, connectorName, window } = getRuntimeCompareContext();
@@ -8964,7 +9151,8 @@ var saveAndPrintReplayRuntimeComparison = async ({
     replaySignals,
     replaySignalEvaluations,
     runtimeLineageScopes: comparable.runtimeLineageScopes,
-    replayLineageScopes
+    replayLineageScopes,
+    replayDecisionTraces
   });
   const parityRows = summarizeTradeParityByStrategy({
     runtimeEntries: runtimeDedupe.entries,
@@ -9891,6 +10079,7 @@ var finishReplay = async ({
     replaySignals: replayResult.signals,
     replayLineages: replayResult.runtimeLineages,
     replayLineageScopes: replayResult.replayLineageScopes,
+    replayDecisionTraces: replayResult.replayDecisionTraces,
     runtimeEvidencePath: replayRuntimeEvidencePath
   });
   const finishedAt = /* @__PURE__ */ new Date();
@@ -10240,7 +10429,8 @@ var replayBacktest = async () => {
       references: historicalReplayReferences,
       showProgress: !replayFlags.portfolioReport,
       collectSkipEvidence: !replayFlags.portfolioReport,
-      collectSignals: !replayFlags.portfolioReport
+      collectSignals: !replayFlags.portfolioReport,
+      decisionTraceTargets: replayFlags.portfolioReport ? void 0 : evidenceMetadata?.decisionTraceTargets
     });
     return replayFlags.portfolioReport ? compactHistoricalReplayResultForPortfolio(result) : result;
   };