@tradejs/cli 1.0.9 → 1.0.10

package/dist/scripts/executionCalibration.js

@@ -0,0 +1,792 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/scripts/executionCalibration.ts
+var executionCalibration_exports = {};
+__export(executionCalibration_exports, {
+  executionCalibration: () => executionCalibration,
+  main: () => main
+});
+module.exports = __toCommonJS(executionCalibration_exports);
+var import_promises = __toESM(require("fs/promises"));
+var import_node_path = __toESM(require("path"));
+var import_args = __toESM(require("args"));
+var import_chalk = __toESM(require("chalk"));
+
+// src/lib/executionCalibration.ts
+var import_constants = require("@tradejs/core/constants");
+var import_data = require("@tradejs/core/data");
+var import_trade = require("@tradejs/core/trade");
+var roundMetric = (value, decimals = 6) => typeof value === "number" && Number.isFinite(value) ? Number(value.toFixed(decimals)) : null;
+var asRecord = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : null;
+var asArray = (value) => Array.isArray(value) ? value : [];
+var finiteNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
+var finiteString = (value) => typeof value === "string" && value.trim() ? value.trim() : null;
+var finiteDirection = (value) => value === "LONG" || value === "SHORT" ? value : null;
+var metricValues = (samples, key) => samples.map((sample) => sample[key]).filter(
+  (value) => typeof value === "number" && Number.isFinite(value)
+);
+var quantile = (values, probability) => {
+  if (!values.length) {
+    return null;
+  }
+  const sorted = [...values].sort((left, right) => left - right);
+  const index = (sorted.length - 1) * probability;
+  const lowerIndex = Math.floor(index);
+  const upperIndex = Math.ceil(index);
+  const lower = sorted[lowerIndex];
+  const upper = sorted[upperIndex];
+  if (lower == null || upper == null) {
+    return null;
+  }
+  if (lowerIndex === upperIndex) {
+    return lower;
+  }
+  return lower + (upper - lower) * (index - lowerIndex);
+};
+var summarizeNumbers = (values) => {
+  const finite = values.filter((value) => Number.isFinite(value));
+  if (!finite.length) {
+    return {
+      count: 0,
+      min: null,
+      max: null,
+      avg: null,
+      p50: null,
+      p75: null,
+      p90: null,
+      p95: null
+    };
+  }
+  const total = finite.reduce((sum, value) => sum + value, 0);
+  return {
+    count: finite.length,
+    min: roundMetric(Math.min(...finite)),
+    max: roundMetric(Math.max(...finite)),
+    avg: roundMetric(total / finite.length),
+    p50: roundMetric(quantile(finite, 0.5)),
+    p75: roundMetric(quantile(finite, 0.75)),
+    p90: roundMetric(quantile(finite, 0.9)),
+    p95: roundMetric(quantile(finite, 0.95))
+  };
+};
+var getIntervalMs = (interval) => {
+  if (!interval) {
+    return null;
+  }
+  try {
+    return (0, import_data.intervalToMs)(interval);
+  } catch {
+    return null;
+  }
+};
+var getSignalKey = ({
+  strategy,
+  symbol,
+  timestamp
+}) => strategy && symbol && timestamp != null ? `${strategy}:${symbol}:${timestamp}` : null;
+var addSignalToMap = (signalsById, signalsByShape, signal) => {
+  if (!signal) {
+    return;
+  }
+  const signalId = finiteString(signal.signalId);
+  if (signalId) {
+    signalsById.set(signalId, signal);
+  }
+  const shapeKey = getSignalKey({
+    strategy: finiteString(signal.strategy),
+    symbol: finiteString(signal.symbol),
+    timestamp: finiteNumber(signal.timestamp)
+  });
+  if (shapeKey) {
+    signalsByShape.set(shapeKey, signal);
+  }
+};
+var getRuntimePayload = ({
+  runtimeArtifact,
+  replayEvidenceArtifact
+}) => {
+  const explicitRuntime = asRecord(runtimeArtifact);
+  if (explicitRuntime) {
+    return asRecord(explicitRuntime.runtime) ?? explicitRuntime;
+  }
+  const replayEvidence = asRecord(replayEvidenceArtifact);
+  return asRecord(replayEvidence?.runtime);
+};
+var extractRuntimeTradeRows = (runtimePayload) => {
+  if (!runtimePayload) {
+    return [];
+  }
+  const signalsById = /* @__PURE__ */ new Map();
+  const signalsByShape = /* @__PURE__ */ new Map();
+  for (const signalRow of asArray(runtimePayload.signals)) {
+    const record = asRecord(signalRow);
+    addSignalToMap(
+      signalsById,
+      signalsByShape,
+      asRecord(record?.signal) ?? record
+    );
+  }
+  return asArray(runtimePayload.trades).map((row) => {
+    const record = asRecord(row);
+    if (!record) {
+      return null;
+    }
+    const redisValues = asRecord(record.redisValues);
+    const trade = asRecord(record.trade) ?? asRecord(redisValues?.trade) ?? record;
+    const signalId = finiteString(trade.signalId);
+    const shapeKey = getSignalKey({
+      strategy: finiteString(trade.strategy),
+      symbol: finiteString(trade.symbol),
+      timestamp: finiteNumber(trade.signalTimestamp ?? trade.entryTimestamp)
+    });
+    const signal = asRecord(redisValues?.signal) ?? (signalId ? signalsById.get(signalId) ?? null : null) ?? (shapeKey ? signalsByShape.get(shapeKey) ?? null : null);
+    return {
+      trade,
+      signal
+    };
+  }).filter((row) => row != null);
+};
+var normalizeReplayMatch = (value) => {
+  const item = asRecord(value);
+  if (!item) {
+    return null;
+  }
+  const runtime = asRecord(item.runtime);
+  const backtest = asRecord(item.backtest);
+  return {
+    orderId: finiteString(
+      item.orderId ?? runtime?.orderId ?? backtest?.orderId
+    ),
+    orderLinkId: finiteString(item.orderLinkId ?? runtime?.orderLinkId),
+    signalId: finiteString(item.signalId ?? backtest?.signalId),
+    strategy: finiteString(
+      item.strategy ?? backtest?.strategy ?? runtime?.inferredStrategy
+    ),
+    symbol: finiteString(item.symbol ?? backtest?.symbol ?? runtime?.symbol),
+    direction: finiteDirection(
+      item.direction ?? backtest?.direction ?? runtime?.direction
+    ),
+    backtestPrice: finiteNumber(item.backtestPrice ?? backtest?.price),
+    runtimePrice: finiteNumber(item.runtimePrice ?? runtime?.price)
+  };
+};
+var extractReplayMatches = (replayEvidenceArtifact) => {
+  const artifact = asRecord(replayEvidenceArtifact);
+  if (!artifact) {
+    return [];
+  }
+  const replay = asRecord(artifact.replay) ?? artifact;
+  const runtimeComparison = asRecord(replay.runtimeComparison);
+  const details = asRecord(runtimeComparison?.details);
+  const matched = asArray(runtimeComparison?.matched).length ? asArray(runtimeComparison?.matched) : asArray(details?.matched);
+  return matched.map(normalizeReplayMatch).filter((match) => match != null);
+};
+var buildReplayMatchMaps = (matches) => {
+  const maps = {
+    byOrderId: /* @__PURE__ */ new Map(),
+    bySignalId: /* @__PURE__ */ new Map()
+  };
+  for (const match of matches) {
+    for (const orderId of [match.orderLinkId, match.orderId]) {
+      if (orderId) {
+        maps.byOrderId.set(orderId, match);
+      }
+    }
+    if (match.signalId) {
+      maps.bySignalId.set(match.signalId, match);
+    }
+  }
+  return maps;
+};
+var getSignalCandles = (signal, interval) => {
+  const indicators = asRecord(signal?.indicators);
+  if (!indicators) {
+    return null;
+  }
+  const intervalKey = (() => {
+    switch (interval) {
+      case "15":
+        return "candles15m";
+      case "60":
+        return "candles1h";
+      case "240":
+        return "candles4h";
+      case "D":
+        return "candles1d";
+      default:
+        return null;
+    }
+  })();
+  const keys = [
+    intervalKey,
+    "candles15m",
+    "candles1h",
+    "candles4h",
+    "candles1d",
+    "candles"
+  ].filter((key) => Boolean(key));
+  for (const key of keys) {
+    const value = indicators[key];
+    if (Array.isArray(value) && value.length > 1) {
+      return value;
+    }
+  }
+  const candle = indicators.candle;
+  const prevCandle = indicators.prevCandle;
+  return prevCandle && candle ? [prevCandle, candle] : null;
+};
+var adverseEntryBps = ({
+  direction,
+  expectedPrice,
+  actualPrice
+}) => {
+  if (!direction || expectedPrice == null || actualPrice == null || expectedPrice <= 0 || actualPrice <= 0) {
+    return null;
+  }
+  const value = direction === "LONG" ? (actualPrice / expectedPrice - 1) * 1e4 : (expectedPrice / actualPrice - 1) * 1e4;
+  return roundMetric(value);
+};
+var feeBps = ({
+  fee,
+  fillAvgPrice,
+  qty
+}) => {
+  const notional = fillAvgPrice != null && qty != null && fillAvgPrice > 0 && qty > 0 ? fillAvgPrice * qty : null;
+  return fee != null && notional != null && notional > 0 ? roundMetric(fee / notional * 1e4) : null;
+};
+var latencyDelta = (end, start) => end != null && start != null ? roundMetric(end - start, 3) : null;
+var resolveTelemetryQuality = ({
+  signalClosePrice,
+  arrivalMid,
+  orderSubmitTime,
+  orderAckTime,
+  fillAvgPrice,
+  fillTime
+}) => {
+  if (signalClosePrice != null && arrivalMid != null && orderSubmitTime != null && orderAckTime != null && fillAvgPrice != null && fillTime != null) {
+    return "full";
+  }
+  if (fillAvgPrice != null && (arrivalMid != null || orderSubmitTime != null)) {
+    return "partial";
+  }
+  if (fillAvgPrice != null) {
+    return "price_only";
+  }
+  return "none";
+};
+var finiteTelemetryQuality = (value) => {
+  const raw = finiteString(value);
+  return raw === "full" || raw === "partial" || raw === "price_only" || raw === "none" ? raw : null;
+};
+var countBy = (samples, keyGetter) => {
+  const counts = /* @__PURE__ */ new Map();
+  for (const sample of samples) {
+    const key = keyGetter(sample) ?? "unknown";
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return Object.fromEntries(
+    [...counts.entries()].sort(([left], [right]) => left.localeCompare(right))
+  );
+};
+var toLatencyBucket = (sample) => {
+  const latencyMs = sample.signalCloseToSubmitMs ?? sample.signalToSubmitMs;
+  if (latencyMs == null || !Number.isFinite(latencyMs)) return "unknown";
+  if (latencyMs <= 1e3) return "0-1s";
+  if (latencyMs <= 5e3) return "1-5s";
+  if (latencyMs <= 3e4) return "5-30s";
+  if (latencyMs <= 12e4) return "30-120s";
+  return "120s+";
+};
+var toSpreadBucket = (sample) => {
+  const spreadBps = sample.spreadBps;
+  if (spreadBps == null || !Number.isFinite(spreadBps)) return "unknown";
+  if (spreadBps <= 5) return "0-5bps";
+  if (spreadBps <= 20) return "5-20bps";
+  if (spreadBps <= 50) return "20-50bps";
+  return "50bps+";
+};
+var buildSample = ({
+  row,
+  match
+}) => {
+  const { trade, signal } = row;
+  const strategy = finiteString(trade.strategy ?? signal?.strategy);
+  const symbol = finiteString(trade.symbol ?? signal?.symbol);
+  const interval = finiteString(trade.interval ?? signal?.interval);
+  const direction = finiteDirection(trade.direction ?? signal?.direction);
+  const orderId = finiteString(trade.orderId);
+  const signalId = finiteString(trade.signalId ?? signal?.signalId);
+  const qty = finiteNumber(trade.qty);
+  const signalTimestamp = finiteNumber(
+    trade.signalTimestamp ?? signal?.timestamp
+  );
+  const intervalMs = getIntervalMs(interval);
+  const signalCloseTimestamp = signalTimestamp != null && intervalMs != null ? signalTimestamp + intervalMs : signalTimestamp;
+  const signalClosePrice = finiteNumber(trade.signalClosePrice);
+  const arrivalSnapshotTime = finiteNumber(trade.arrivalSnapshotTime);
+  const arrivalSource = finiteString(trade.arrivalSource);
+  const arrivalMid = finiteNumber(trade.arrivalMid);
+  const bid = finiteNumber(trade.bid);
+  const ask = finiteNumber(trade.ask);
+  const spreadBps = finiteNumber(trade.spreadBps);
+  const orderSubmitTime = finiteNumber(trade.orderSubmitTime);
+  const orderAckTime = finiteNumber(trade.orderAckTime);
+  const fillAvgPrice = finiteNumber(trade.fillAvgPrice);
+  const fillSource = finiteString(trade.fillSource);
+  const fillTime = finiteNumber(trade.fillTime);
+  const telemetryQuality = finiteTelemetryQuality(trade.telemetryQuality) ?? resolveTelemetryQuality({
+    signalClosePrice,
+    arrivalMid,
+    orderSubmitTime,
+    orderAckTime,
+    fillAvgPrice,
+    fillTime
+  });
+  const fee = finiteNumber(trade.fee ?? trade.openFee);
+  const arrivalSnapshotAgeMs = latencyDelta(
+    orderSubmitTime,
+    arrivalSnapshotTime
+  );
+  const signalToSubmitMs = latencyDelta(orderSubmitTime, signalTimestamp);
+  const signalCloseToSubmitMs = latencyDelta(
+    orderSubmitTime,
+    signalCloseTimestamp
+  );
+  const submitToAckMs = latencyDelta(orderAckTime, orderSubmitTime);
+  const submitToFillMs = latencyDelta(fillTime, orderSubmitTime);
+  const orderAckToFillMs = latencyDelta(fillTime, orderAckTime);
+  const signalToFillMs = latencyDelta(fillTime, signalTimestamp);
+  const observedDelayMs = signalCloseToSubmitMs != null && signalCloseToSubmitMs >= 0 ? signalCloseToSubmitMs : signalToSubmitMs != null && signalToSubmitMs >= 0 ? signalToSubmitMs : null;
+  const candles = getSignalCandles(signal, interval);
+  const currentDelayRiskBps = roundMetric(
+    (0, import_trade.calculateDelayRiskBps)({
+      candles,
+      intervalMs
+    })
+  );
+  const rawConfiguredDelayRiskBps = roundMetric(
+    (0, import_trade.calculateDelayRiskBps)({
+      candles,
+      intervalMs,
+      multiplier: 1,
+      maxBps: Number.POSITIVE_INFINITY
+    })
+  );
+  const rawObservedDelayRiskBps = roundMetric(
+    (0, import_trade.calculateDelayRiskBps)({
+      candles,
+      intervalMs,
+      expectedDelayMs: observedDelayMs,
+      multiplier: 1,
+      maxBps: Number.POSITIVE_INFINITY
+    })
+  );
+  const signalToArrivalAdverseBps = adverseEntryBps({
+    direction,
+    expectedPrice: signalClosePrice,
+    actualPrice: arrivalMid
+  });
+  const arrivalToFillAdverseBps = adverseEntryBps({
+    direction,
+    expectedPrice: arrivalMid,
+    actualPrice: fillAvgPrice
+  });
+  const signalToFillAdverseBps = adverseEntryBps({
+    direction,
+    expectedPrice: signalClosePrice,
+    actualPrice: fillAvgPrice
+  });
+  const currentModelEntrySlippageBps = signalToFillAdverseBps != null ? roundMetric(
+    import_constants.BACKTEST_BASE_SLIPPAGE_BPS + (spreadBps ?? 0) * import_constants.BACKTEST_SPREAD_SLIPPAGE_MULTIPLIER + import_constants.BACKTEST_MARKET_IMPACT_BPS + (currentDelayRiskBps ?? 0)
+  ) : null;
+  const residualVsCurrentModelBps = signalToFillAdverseBps != null && currentModelEntrySlippageBps != null ? roundMetric(signalToFillAdverseBps - currentModelEntrySlippageBps) : null;
+  return {
+    strategy,
+    symbol,
+    interval,
+    direction,
+    orderId,
+    signalId,
+    qty,
+    signalTimestamp,
+    signalCloseTimestamp,
+    signalClosePrice,
+    arrivalSnapshotTime,
+    arrivalSource,
+    arrivalMid,
+    bid,
+    ask,
+    spreadBps,
+    orderSubmitTime,
+    orderAckTime,
+    fillAvgPrice,
+    fillSource,
+    fillTime,
+    telemetryQuality,
+    fee,
+    feeBps: feeBps({ fee, fillAvgPrice, qty }),
+    arrivalSnapshotAgeMs,
+    signalToSubmitMs,
+    signalCloseToSubmitMs,
+    submitToAckMs,
+    submitToFillMs,
+    orderAckToFillMs,
+    signalToFillMs,
+    signalToArrivalAdverseBps,
+    arrivalToFillAdverseBps,
+    signalToFillAdverseBps,
+    currentDelayRiskBps,
+    rawConfiguredDelayRiskBps,
+    rawObservedDelayRiskBps,
+    currentModelEntrySlippageBps,
+    residualVsCurrentModelBps,
+    replayEntryResidualBps: adverseEntryBps({
+      direction: direction ?? match?.direction ?? null,
+      expectedPrice: match?.backtestPrice ?? null,
+      actualPrice: match?.runtimePrice ?? null
+    })
+  };
+};
+var buildReplayOnlySample = (match) => ({
+  strategy: match.strategy,
+  symbol: match.symbol,
+  interval: null,
+  direction: match.direction,
+  orderId: match.orderLinkId ?? match.orderId,
+  signalId: match.signalId,
+  qty: null,
+  signalTimestamp: null,
+  signalCloseTimestamp: null,
+  signalClosePrice: null,
+  arrivalSnapshotTime: null,
+  arrivalSource: null,
+  arrivalMid: null,
+  bid: null,
+  ask: null,
+  spreadBps: null,
+  orderSubmitTime: null,
+  orderAckTime: null,
+  fillAvgPrice: match.runtimePrice,
+  fillSource: "replay_runtime_price",
+  fillTime: null,
+  telemetryQuality: match.runtimePrice != null ? "price_only" : "none",
+  fee: null,
+  feeBps: null,
+  arrivalSnapshotAgeMs: null,
+  signalToSubmitMs: null,
+  signalCloseToSubmitMs: null,
+  submitToAckMs: null,
+  submitToFillMs: null,
+  orderAckToFillMs: null,
+  signalToFillMs: null,
+  signalToArrivalAdverseBps: null,
+  arrivalToFillAdverseBps: null,
+  signalToFillAdverseBps: null,
+  currentDelayRiskBps: null,
+  rawConfiguredDelayRiskBps: null,
+  rawObservedDelayRiskBps: null,
+  currentModelEntrySlippageBps: null,
+  residualVsCurrentModelBps: null,
+  replayEntryResidualBps: adverseEntryBps({
+    direction: match.direction,
+    expectedPrice: match.backtestPrice,
+    actualPrice: match.runtimePrice
+  })
+});
+var hasTelemetry = (sample) => sample.signalClosePrice != null || sample.arrivalMid != null || sample.orderSubmitTime != null || sample.fillAvgPrice != null || sample.fillTime != null || sample.fee != null;
+var hasFullTelemetry = (sample) => sample.signalClosePrice != null && sample.arrivalMid != null && sample.orderSubmitTime != null && sample.orderAckTime != null && sample.fillAvgPrice != null && sample.fillTime != null;
+var buildGroupSummary = (samples) => ({
+  trades: samples.length,
+  fullTelemetryTrades: samples.filter(hasFullTelemetry).length,
+  replayMatchedTrades: metricValues(samples, "replayEntryResidualBps").length,
+  telemetryQuality: countBy(samples, (sample) => sample.telemetryQuality),
+  fillSource: countBy(samples, (sample) => sample.fillSource),
+  arrivalSource: countBy(samples, (sample) => sample.arrivalSource),
+  signalToArrivalAdverseBps: summarizeNumbers(
+    metricValues(samples, "signalToArrivalAdverseBps")
+  ),
+  arrivalToFillAdverseBps: summarizeNumbers(
+    metricValues(samples, "arrivalToFillAdverseBps")
+  ),
+  signalToFillAdverseBps: summarizeNumbers(
+    metricValues(samples, "signalToFillAdverseBps")
+  ),
+  residualVsCurrentModelBps: summarizeNumbers(
+    metricValues(samples, "residualVsCurrentModelBps")
+  ),
+  replayEntryResidualBps: summarizeNumbers(
+    metricValues(samples, "replayEntryResidualBps")
+  ),
+  spreadBps: summarizeNumbers(metricValues(samples, "spreadBps")),
+  feeBps: summarizeNumbers(metricValues(samples, "feeBps")),
+  arrivalSnapshotAgeMs: summarizeNumbers(
+    metricValues(samples, "arrivalSnapshotAgeMs")
+  ),
+  signalToSubmitMs: summarizeNumbers(metricValues(samples, "signalToSubmitMs")),
+  signalCloseToSubmitMs: summarizeNumbers(
+    metricValues(samples, "signalCloseToSubmitMs")
+  ),
+  submitToAckMs: summarizeNumbers(metricValues(samples, "submitToAckMs")),
+  submitToFillMs: summarizeNumbers(metricValues(samples, "submitToFillMs")),
+  orderAckToFillMs: summarizeNumbers(metricValues(samples, "orderAckToFillMs")),
+  currentDelayRiskBps: summarizeNumbers(
+    metricValues(samples, "currentDelayRiskBps")
+  ),
+  rawConfiguredDelayRiskBps: summarizeNumbers(
+    metricValues(samples, "rawConfiguredDelayRiskBps")
+  ),
+  rawObservedDelayRiskBps: summarizeNumbers(
+    metricValues(samples, "rawObservedDelayRiskBps")
+  )
+});
+var groupSamples = (samples, keyGetter) => {
+  const groups = /* @__PURE__ */ new Map();
+  for (const sample of samples) {
+    const key = keyGetter(sample);
+    if (!key) {
+      continue;
+    }
+    groups.set(key, [...groups.get(key) ?? [], sample]);
+  }
+  return Object.fromEntries(
+    [...groups.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([key, group]) => [key, buildGroupSummary(group)])
+  );
+};
+var positiveMetricValues = (samples, key) => metricValues(samples, key).filter((value) => value > 0);
+var buildRecommendation = (samples) => {
+  const fullTelemetrySamples = samples.filter(hasFullTelemetry);
+  const notes = [];
+  if (!fullTelemetrySamples.length) {
+    return {
+      confidence: "none",
+      baseSlippageBps: null,
+      spreadMultiplier: null,
+      delayRiskMultiplier: null,
+      delayRiskMaxBps: null,
+      expectedDelayMs: null,
+      notes: [
+        "No full live execution telemetry was found. Use a newer runtime debug artifact collected after telemetry persistence was enabled.",
+        "Replay residuals can still diagnose model drift, but they are not enough to calibrate signal-to-arrival and arrival-to-fill components separately."
+      ]
+    };
+  }
+  if (fullTelemetrySamples.length < 20) {
+    notes.push(
+      "Sample is small; treat recommendations as diagnostic until at least 20-50 live fills are available."
+    );
+  }
+  const spreadRatios = fullTelemetrySamples.map((sample) => {
+    if (sample.arrivalToFillAdverseBps == null || sample.spreadBps == null || sample.spreadBps <= 0) {
+      return null;
+    }
+    return Math.max(0, sample.arrivalToFillAdverseBps) / sample.spreadBps;
+  }).filter(
+    (value) => value != null && Number.isFinite(value)
+  );
+  const spreadMultiplier = roundMetric(quantile(spreadRatios, 0.75), 4);
+  const baseResiduals = fullTelemetrySamples.map((sample) => {
+    if (sample.arrivalToFillAdverseBps == null) {
+      return null;
+    }
+    return Math.max(
+      0,
+      sample.arrivalToFillAdverseBps - (sample.spreadBps ?? 0) * (spreadMultiplier ?? import_constants.BACKTEST_SPREAD_SLIPPAGE_MULTIPLIER)
+    );
+  }).filter(
+    (value) => value != null && Number.isFinite(value)
+  );
+  const closeDelayMs = positiveMetricValues(
+    fullTelemetrySamples,
+    "signalCloseToSubmitMs"
+  );
+  const fallbackDelayMs = positiveMetricValues(
+    fullTelemetrySamples,
+    "signalToSubmitMs"
+  );
+  if (!spreadRatios.length) {
+    notes.push(
+      "Spread multiplier could not be calibrated because spreadBps or arrival-to-fill telemetry is missing."
+    );
+  }
+  notes.push(
+    "Delay risk bps is disabled; signal-to-arrival latency is modeled by delayed lower-timeframe backtest fills."
+  );
+  return {
+    confidence: fullTelemetrySamples.length >= 50 ? "high" : fullTelemetrySamples.length >= 20 ? "medium" : "low",
+    baseSlippageBps: roundMetric(quantile(baseResiduals, 0.75), 2),
+    spreadMultiplier,
+    delayRiskMultiplier: null,
+    delayRiskMaxBps: null,
+    expectedDelayMs: roundMetric(
+      quantile(closeDelayMs.length ? closeDelayMs : fallbackDelayMs, 0.5),
+      0
+    ),
+    notes
+  };
+};
+var buildExecutionCalibrationReport = ({
+  runtimeArtifact,
+  replayEvidenceArtifact,
+  sourcePaths = {},
+  nowMs = Date.now()
+}) => {
+  const runtimePayload = getRuntimePayload({
+    runtimeArtifact,
+    replayEvidenceArtifact
+  });
+  const runtimeRows = extractRuntimeTradeRows(runtimePayload);
+  const replayMatches = extractReplayMatches(replayEvidenceArtifact);
+  const replayMaps = buildReplayMatchMaps(replayMatches);
+  const usedReplayMatches = /* @__PURE__ */ new Set();
+  const samples = runtimeRows.map((row) => {
+    const orderId = finiteString(row.trade.orderId);
+    const signalId = finiteString(row.trade.signalId);
+    const match = (orderId ? replayMaps.byOrderId.get(orderId) ?? null : null) ?? (signalId ? replayMaps.bySignalId.get(signalId) ?? null : null);
+    if (match) {
+      usedReplayMatches.add(match);
+    }
+    return buildSample({ row, match });
+  });
+  const replayOnlySamples = replayMatches.filter((match) => !usedReplayMatches.has(match)).map(buildReplayOnlySample);
+  return {
+    reportType: "execution-calibration",
+    generatedAt: nowMs,
+    sources: sourcePaths,
+    currentModel: {
+      baseSlippageBps: import_constants.BACKTEST_BASE_SLIPPAGE_BPS,
+      spreadMultiplier: import_constants.BACKTEST_SPREAD_SLIPPAGE_MULTIPLIER,
+      marketImpactBps: import_constants.BACKTEST_MARKET_IMPACT_BPS
+    },
+    counts: {
+      runtimeTrades: runtimeRows.length,
+      telemetryTrades: samples.filter(hasTelemetry).length,
+      fullTelemetryTrades: samples.filter(hasFullTelemetry).length,
+      replayMatched: replayMatches.length,
+      replayMatchedRuntimeTrades: usedReplayMatches.size,
+      replayOnlyMatches: replayOnlySamples.length
+    },
+    summary: {
+      all: buildGroupSummary([...samples, ...replayOnlySamples]),
+      byStrategy: groupSamples(
+        [...samples, ...replayOnlySamples],
+        (sample) => sample.strategy
+      ),
+      bySymbol: groupSamples(samples, (sample) => sample.symbol),
+      byInterval: groupSamples(samples, (sample) => sample.interval),
+      byTelemetryQuality: groupSamples(
+        [...samples, ...replayOnlySamples],
+        (sample) => sample.telemetryQuality
+      ),
+      byFillSource: groupSamples(
+        [...samples, ...replayOnlySamples],
+        (sample) => sample.fillSource
+      ),
+      byLatencyBucket: groupSamples(samples, toLatencyBucket),
+      bySpreadBucket: groupSamples(samples, toSpreadBucket)
+    },
+    recommendation: buildRecommendation(samples),
+    samples,
+    replayOnlySamples
+  };
+};
+
+// src/scripts/executionCalibration.ts
+import_args.default.option(
+  "runtimeEvidence",
+  "Runtime debug JSON collected on the runtime server"
+);
+import_args.default.option(
+  "replayEvidence",
+  "Replay runtime evidence JSON produced by replay-runtime-evidence"
+);
+import_args.default.option(
+  ["o", "out"],
+  "Output JSON path",
+  "output/execution-calibration.json"
+);
+var flags = import_args.default.parse(process.argv);
+var projectRoot = String(process.env.PROJECT_CWD || process.cwd()).trim() || process.cwd();
+var readJsonFile = async (filePath) => JSON.parse(await import_promises.default.readFile(filePath, "utf8"));
+var resolveInputPath = (value) => {
+  const raw = String(value ?? "").trim();
+  return raw ? import_node_path.default.resolve(projectRoot, raw) : null;
+};
+var executionCalibration = async () => {
+  const runtimeEvidencePath = resolveInputPath(flags.runtimeEvidence);
+  const replayEvidencePath = resolveInputPath(flags.replayEvidence);
+  if (!runtimeEvidencePath && !replayEvidencePath) {
+    throw new Error(
+      "Provide --runtimeEvidence, --replayEvidence, or both for execution calibration."
+    );
+  }
+  const [runtimeArtifact, replayEvidenceArtifact] = await Promise.all([
+    runtimeEvidencePath ? readJsonFile(runtimeEvidencePath) : Promise.resolve(void 0),
+    replayEvidencePath ? readJsonFile(replayEvidencePath) : Promise.resolve(void 0)
+  ]);
+  const report = buildExecutionCalibrationReport({
+    runtimeArtifact,
+    replayEvidenceArtifact,
+    sourcePaths: {
+      runtimeEvidence: runtimeEvidencePath,
+      replayEvidence: replayEvidencePath
+    }
+  });
+  const outPath = import_node_path.default.resolve(projectRoot, String(flags.out));
+  await import_promises.default.mkdir(import_node_path.default.dirname(outPath), { recursive: true });
+  await import_promises.default.writeFile(outPath, `${JSON.stringify(report, null, 2)}
+`, "utf8");
+  console.log(import_chalk.default.green(`Wrote ${outPath}`));
+  console.log(
+    JSON.stringify(
+      {
+        counts: report.counts,
+        currentModel: report.currentModel,
+        recommendation: report.recommendation,
+        summary: {
+          signalToArrivalAdverseBps: report.summary.all.signalToArrivalAdverseBps,
+          arrivalToFillAdverseBps: report.summary.all.arrivalToFillAdverseBps,
+          signalToFillAdverseBps: report.summary.all.signalToFillAdverseBps,
+          residualVsCurrentModelBps: report.summary.all.residualVsCurrentModelBps,
+          replayEntryResidualBps: report.summary.all.replayEntryResidualBps,
+          telemetryQuality: report.summary.all.telemetryQuality,
+          fillSource: report.summary.all.fillSource
+        }
+      },
+      null,
+      2
+    )
+  );
+};
+var main = executionCalibration;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  executionCalibration,
+  main
+});