@coinrithm/mcp-trading 0.3.0 → 0.5.0

package/dist/agent/runner.js

@@ -2,11 +2,14 @@
 // spot, futures, and prediction markets. Dry-run never writes. Live uses
 // idempotency keys + agentTrace and exports run evidence. The client + provider
 // are injected so the loop is fully unit-testable with no network/model calls.
-import { spotBuyCost, } from "./types.js";
+import { spotBuyCost, DEFAULT_TRIGGER_POLICY, } from "./types.js";
+import { evaluateGate, noteLlmCall, estimateCostUsd } from "./gate.js";
+import { baseSymbol } from "./setups.js";
 import { observe } from "./observe.js";
 import { buildSystemPrompt, buildUserPrompt } from "./prompt.js";
 import { parseDecision } from "./decision.js";
 import { validateAction } from "./decisionValidator.js";
+import { resolvePmRef } from "./resolvePm.js";
 import { fetchQuote, executeAction } from "./act.js";
 import { makeDecisionId, makeTrace, exportRunEvidence } from "./runEvidence.js";
 import { rollDay, checkKillSwitch, accrueRealized, saveState, } from "./state.js";
@@ -52,6 +55,105 @@ function cashConsumed(action, quote) {
     }
     return 0;
 }
+// Orienting a take-profit relative to side + mark is deterministic arithmetic —
+// the runner should OWN it, not trust a weak model to compute it (the same reason
+// pmN offloads the long-id copy). When a futures_open's takeProfitPrice is missing
+// or on the WRONG side (long TP <= mark / short TP >= mark), the server rejects the
+// WHOLE open (take_profit_not_*_mark) — the position never opens, so the model
+// can't "let winners run". Here we substitute a sensible R:R target off the stop so
+// the open succeeds with a valid TP. Only fires when a usable stop is present (so
+// risk is computable) and the TP is actually missing/wrong-side; a correct TP is
+// left untouched. Systemic fix for the whole free-tier 8B/instruct fleet.
+const DEFAULT_TP_RR = 1.5; // reward:risk of the substituted take-profit
+export function repairFuturesTakeProfit(action, quote) {
+    if (action.type !== "futures_open")
+        return { action, repaired: false };
+    const entry = quote?.entryPrice;
+    const sl = action.stopLossPrice;
+    if (typeof entry !== "number" || !Number.isFinite(entry) || entry <= 0)
+        return { action, repaired: false };
+    if (typeof sl !== "number" || !Number.isFinite(sl) || sl <= 0)
+        return { action, repaired: false };
+    const isLong = action.side === "long";
+    const tp = action.takeProfitPrice;
+    const tpValid = typeof tp === "number" &&
+        Number.isFinite(tp) &&
+        tp > 0 &&
+        (isLong ? tp > entry : tp < entry);
+    if (tpValid)
+        return { action, repaired: false };
+    // Stop must be on the correct side to imply a positive risk distance; if it
+    // isn't, leave the action for the validator to reject (don't fabricate).
+    const risk = isLong ? entry - sl : sl - entry;
+    if (!(risk > 0))
+        return { action, repaired: false };
+    const target = isLong
+        ? entry + DEFAULT_TP_RR * risk
+        : entry - DEFAULT_TP_RR * risk;
+    if (!(target > 0))
+        return { action, repaired: false };
+    return { action: { ...action, takeProfitPrice: target }, repaired: true };
+}
+// One-line, human-readable summary of an executed action for the agent's journal
+// (slice-3 memory). Compact so a few entries cost almost nothing in the prompt.
+function summarizeAction(a) {
+    switch (a.type) {
+        case "futures_open":
+            return `opened ${a.side} ${a.symbol} (x${a.leverage}, ${a.marginMusd}mUSD)`;
+        case "futures_close":
+            return `closed pos#${a.positionId}`;
+        case "futures_set_sltp":
+            return `trailed stop on pos#${a.positionId}`;
+        case "spot_order":
+            return `${a.side} ${a.symbol} (${a.orderType})`;
+        case "spot_cancel":
+            return `cancelled order#${a.orderId}`;
+        case "pm_open":
+            return `bet PM ${a.slug} ${a.stakeMusd}mUSD`;
+    }
+}
+// Tokens that identify the MARKET an action is on, for checking a rationale is
+// actually about it. close/sltp/cancel reference a position/order id (not a market
+// name) so they return none and keep their position-management rationale as-is.
+function actionMarketTokens(a) {
+    switch (a.type) {
+        case "futures_open":
+        case "spot_order":
+            return [a.symbol, baseSymbol(a.symbol)];
+        case "pm_open":
+            return [a.source, ...a.slug.split("-").filter((w) => w.length >= 4)];
+        default:
+            return [];
+    }
+}
+// Does the decision rationale plausibly name this action's market? Lenient: any
+// market token present counts. An empty token set (close/sltp/cancel) returns true.
+function rationaleMatchesAction(rationale, a) {
+    const toks = actionMarketTokens(a).filter((t) => t && t.length >= 2);
+    if (toks.length === 0)
+        return true;
+    const lower = rationale.toLowerCase();
+    return toks.some((t) => lower.includes(t.toLowerCase()));
+}
+// The per-trade "why" shown on the Arena floor, kept HONEST about the market it's
+// on. Prefer the model's per-action summary. Else the decision-level rationale —
+// but a MULTI-action decision commits that rationale to its PRIMARY idea, which can
+// contradict a secondary action's market ("reasoning didn't match the selected
+// market"), so attach it only when it names this action's market; otherwise a
+// faithful one-line summary of the move. A single-action decision's rationale IS
+// about that action, so it is always kept (the common case, unchanged).
+export function rationaleForAction(a, decisionRationale, perActionSummary, totalActions) {
+    const perAction = perActionSummary?.trim();
+    if (perAction)
+        return perAction;
+    if (!decisionRationale)
+        return summarizeAction(a);
+    if (totalActions <= 1)
+        return decisionRationale;
+    return rationaleMatchesAction(decisionRationale, a)
+        ? decisionRationale
+        : summarizeAction(a);
+}
 export async function runCycle(deps) {
     const { client, provider, spec, mergedProse, state, live, stateFile } = deps;
     const log = deps.log ?? (() => { });
@@ -84,9 +186,35 @@ export async function runCycle(deps) {
         state.seen.push(`${asStr(asObj(t).venue) ?? "futures"}:${asNum(asObj(t).id) ?? String(asObj(t).id)}`);
     }
     state.seen = state.seen.slice(-500);
+    // Slice-3 reflection: journal closed-trade OUTCOMES (not just opens) so the agent
+    // remembers how its theses RESOLVED — a stop-out it should not revenge-trade, a
+    // winner its style works on. Defensive field reads (the /trades shape varies);
+    // a partial entry is harmless, a missing one is skipped.
+    for (const t of observation.newClosedTrades.slice(-5)) {
+        const o = asObj(t);
+        const sym = asStr(o.symbol) ?? asStr(o.coinSymbol) ?? asStr(o.coinId);
+        const pnl = asNum(o.realizedPnlMusd) ??
+            asNum(o.pnlMusd) ??
+            asNum(o.realizedPnl) ??
+            asNum(o.pnl);
+        const side = asStr(o.side);
+        if (sym || pnl != null) {
+            const did = `closed ${side ?? ""} ${sym ?? "position"}`.trim() +
+                (pnl != null
+                    ? `: ${pnl >= 0 ? "+" : ""}${Math.round(pnl)}mUSD ${pnl >= 0 ? "WIN" : "LOSS"}`
+                    : "");
+            state.journal = [
+                ...(state.journal ?? []),
+                { at: observation.asOf, did },
+            ].slice(-12);
+        }
+    }
     // Equity-aware drawdown: open mark-to-market losses trip the kill-switch too,
-    // not only realized losses.
-    const unrealized = observation.openPositions.reduce((s, p) => s + (p.unrealizedPnlMusd ?? 0), 0);
+    // not only realized losses. Includes BOTH futures AND prediction-market books —
+    // a PM-only agent (or one with a large PM stake) was previously invisible to the
+    // drawdown stop, so a marking-down PM book could not trip it (P1b).
+    const unrealized = observation.openPositions.reduce((s, p) => s + (p.unrealizedPnlMusd ?? 0), 0) +
+        (observation.pmPositions ?? []).reduce((s, p) => s + (p.unrealizedPnlMusd ?? 0), 0);
     if (spec.killSwitch.maxDrawdownMusd > 0 &&
         state.peakRealizedMusd - (state.realizedPnlMusd + unrealized) >=
             spec.killSwitch.maxDrawdownMusd) {
@@ -108,11 +236,56 @@ export async function runCycle(deps) {
         log(`skip: ${obs.skip}`);
         return { decision: "skip", skipReason: obs.skip, planned: [], live };
     }
+    // GATE (slice 2): only SPEND an LLM call when a deterministic trigger fires — a
+    // flagged entry setup or an open position to manage. No trigger => a cheap
+    // heartbeat (zero tokens). A heartbeat is neither a model reject nor a failure,
+    // so it touches NO kill-switch counter; it just records the cheap cycle.
+    const policy = spec.triggerPolicy ?? DEFAULT_TRIGGER_POLICY;
+    const nowMs = Date.now();
+    const gate = evaluateGate(observation, state, policy, nowMs);
+    const providerName = spec.model?.provider ?? "nvidia";
+    if (!gate.fire) {
+        saveState(stateFile, state);
+        log(`gate: skip (${gate.reason})`);
+        return {
+            decision: "skip",
+            skipReason: gate.reason,
+            planned: [],
+            live,
+            triggerCodes: gate.codes,
+            llmCallMade: false,
+            decisionType: "gate_skip",
+            tokensIn: 0,
+            tokensOut: 0,
+            estimatedCostUsd: 0,
+            writeAttempted: 0,
+            writeAccepted: 0,
+        };
+    }
+    noteLlmCall(state, gate.codes, nowMs);
     // DECIDE
-    const res = await provider.decide({
-        system: buildSystemPrompt(spec, mergedProse),
-        user: buildUserPrompt(observation),
-    });
+    const system = buildSystemPrompt(spec, mergedProse);
+    const user = buildUserPrompt(observation, state.journal);
+    const tokensInEst = Math.round((system.length + user.length) / 4);
+    // Prompt-size + trigger visibility in the live terminal.
+    log(`prompt ~${tokensInEst} tok ` +
+        `(pm ${observation.pmMarkets.length}, trades ${observation.newClosedTrades.length}, watch ${observation.watch.length}, setups ${observation.setups.length}, triggers ${gate.codes.join("|") || "none"})`);
+    const res = await provider.decide({ system, user });
+    // Metering: prefer provider-reported usage; fall back to a chars/4 estimate.
+    const tokensIn = res.ok
+        ? (res.usage?.promptTokens ?? tokensInEst)
+        : tokensInEst;
+    const tokensOut = res.ok
+        ? (res.usage?.completionTokens ?? Math.round(res.text.length / 4))
+        : 0;
+    const estimatedCostUsd = estimateCostUsd(providerName, tokensIn, tokensOut);
+    const meter = {
+        triggerCodes: gate.codes,
+        llmCallMade: true,
+        tokensIn,
+        tokensOut,
+        estimatedCostUsd,
+    };
     if (!res.ok) {
         state.consecutiveModelFailures += 1;
         saveState(stateFile, state);
@@ -123,6 +296,10 @@ export async function runCycle(deps) {
             planned: [],
             modelFailed: true,
             live,
+            ...meter,
+            decisionType: "model_error",
+            writeAttempted: 0,
+            writeAccepted: 0,
         };
     }
     const parsed = parseDecision(res.text);
@@ -133,13 +310,24 @@ export async function runCycle(deps) {
         return {
             decision: "skip",
             skipReason: `model output invalid: ${parsed.error}`,
+            rawModelOutput: res.text.slice(0, 8000),
             planned: [],
             modelFailed: true,
             live,
+            ...meter,
+            decisionType: "model_error",
+            writeAttempted: 0,
+            writeAccepted: 0,
         };
     }
     state.consecutiveModelFailures = 0;
     const decision = parsed.decision;
+    // Reasoning captured for the Arena terminal (keystone transparency): the
+    // model's own analysis this cycle + decision confidence + the full raw text
+    // (capped) for debugging. Shared across the skip + act return paths.
+    const rationale = decision.rationale;
+    const confidence = decision.confidence;
+    const rawModelOutput = res.text.slice(0, 8000);
     if (decision.decision === "skip" || decision.actions.length === 0) {
         state.consecutiveRejectCycles += 1;
         saveState(stateFile, state);
@@ -147,8 +335,15 @@ export async function runCycle(deps) {
         return {
             decision: "skip",
             skipReason: decision.reason ?? "model chose skip",
+            rationale,
+            confidence,
+            rawModelOutput,
             planned: [],
             live,
+            ...meter,
+            decisionType: "skip",
+            writeAttempted: decision.actions.length,
+            writeAccepted: 0,
         };
     }
     // VALIDATE (+ ACT when live). Quote evidence is fetched by the runner.
@@ -166,8 +361,86 @@ export async function runCycle(deps) {
     let anyAccepted = false;
     let anyExecuted = false;
     let anyExecFailed = false;
-    for (const action of decision.actions) {
+    for (let action of decision.actions) {
+        // Resolve a short PM ref (pm1…pmN) to the canonical {source,slug,outcome} BEFORE
+        // any quote/validation. Small models copy a 3-char ref reliably but mis-copy the
+        // long outcomeExternalMarketId; an unknown/missing ref is rejected here with a
+        // clear code instead of crashing the validator on an undefined id.
+        if (action.type === "pm_open") {
+            const resolved = resolvePmRef(action, observation.pmMarkets);
+            if (!resolved.ok) {
+                planned.push({
+                    action,
+                    accepted: false,
+                    code: resolved.code,
+                    reason: resolved.reason,
+                });
+                log(`reject pm_open: ${resolved.code} (${resolved.reason})`);
+                continue;
+            }
+            action = resolved.action;
+            // Anti-churn for PM (the analog of the futures duplicate_intent guard):
+            // block re-betting a market+outcome we ALREADY hold an open position on.
+            // Without this a model re-bets the same mispriced market every cycle (one
+            // agent opened 25 identical bets) — pure churn. The model SEES its holdings
+            // in observation.pmPositions; this enforces it. Bet a DIFFERENT market instead.
+            const pm = resolved.action; // narrowed to pm_open (canonical triple filled)
+            const heldPm = observation.pmPositions.find((p) => (p.source ?? "").toLowerCase() === (pm.source ?? "").toLowerCase() &&
+                (p.slug ?? "").toLowerCase() === (pm.slug ?? "").toLowerCase() &&
+                p.outcomeExternalMarketId === pm.outcomeExternalMarketId);
+            if (heldPm) {
+                planned.push({
+                    action,
+                    accepted: false,
+                    code: "duplicate_intent",
+                    reason: `already hold a PM bet on ${pm.slug} / ${pm.outcomeExternalMarketId} — do not re-bet the same market+outcome (churn); pick a different market or skip`,
+                });
+                log(`reject pm_open: duplicate_intent (hold PM ${pm.slug})`);
+                continue;
+            }
+        }
+        // Anti-churn critic: block re-opening a futures position we ALREADY hold unless
+        // it's a confirmed WINNER with room (a legit scale-in). Stops the re-open-a-
+        // loser / re-open-into-the-cap churn deterministically — before we even spend a
+        // quote — with a clear "duplicate_intent" instead of a cryptic cap reject. The
+        // runner caps remain the backstop; this is the cleaner, earlier stop.
+        if (action.type === "futures_open") {
+            // Bind the narrowed action to a const: `action` is a reassignable loop var
+            // (pm-resolve + the take-profit repair below both write to it), and a later
+            // reassignment would otherwise widen it back to the union inside this
+            // closure's control-flow analysis.
+            const fo = action;
+            const ab = baseSymbol(fo.symbol);
+            const held = observation.openPositions.find((p) => p.venue === "futures" &&
+                p.side === fo.side &&
+                baseSymbol(p.symbol) === ab);
+            if (held) {
+                const winning = (held.unrealizedPnlMusd ?? 0) > 0;
+                const hasRoom = openCount < spec.risk.maxConcurrentPositions &&
+                    openMarginMusd + fo.marginMusd <= spec.limits.maxOpenMarginMusd;
+                if (!(winning && hasRoom)) {
+                    planned.push({
+                        action,
+                        accepted: false,
+                        code: "duplicate_intent",
+                        reason: `already hold ${fo.symbol} ${fo.side}${winning ? " (no margin room to add)" : " — manage it, do not average down or re-open"}`,
+                    });
+                    log(`reject ${action.type}: duplicate_intent (hold ${fo.symbol} ${fo.side})`);
+                    continue;
+                }
+            }
+        }
         const quote = await fetchQuote(client, action, observation, baseTrace);
+        // Auto-clamp a missing/wrong-side futures take-profit to a valid R:R target
+        // off the stop, so the open isn't silently rejected server-side (the runner
+        // owns trigger orientation; weak models routinely mis-sign it).
+        {
+            const fixed = repairFuturesTakeProfit(action, quote);
+            if (fixed.repaired) {
+                action = fixed.action;
+                log(`repaired ${action.type} take-profit -> ${action.takeProfitPrice} (R:R off stop; model TP was missing/wrong-side)`);
+            }
+        }
         const ctx = {
             spec,
             // Inherit the decision-level confidence so the per-action abstention gate
@@ -215,7 +488,13 @@ export async function runCycle(deps) {
         const seq = state.intentSeq[intentKey] ?? 0;
         const idem = `${runId}:${intentKey}:${seq}`;
         const meta = action;
-        const trace = makeTrace(runId, decisionId, spec, meta.confidence ?? decision.confidence, meta.rationaleSummary);
+        const trace = makeTrace(runId, decisionId, spec, meta.confidence ?? decision.confidence, 
+        // The trade's "why" on the Arena live floor. Prefer the model's per-action
+        // summary; else the decision rationale, but kept HONEST about this action's
+        // market (a multi-action decision's rationale can be about a DIFFERENT market
+        // than a secondary trade — see rationaleForAction). Sanitized short reasoning
+        // only — never raw chain-of-thought.
+        rationaleForAction(action, decision.rationale, meta.rationaleSummary, decision.actions.length));
         const r = await executeAction(client, action, observation, trace, idem);
         planned.push({
             action,
@@ -253,10 +532,33 @@ export async function runCycle(deps) {
     state.consecutiveExecFailures =
         anyExecFailed && !anyExecuted ? state.consecutiveExecFailures + 1 : 0;
     state.rateLimitHits = client.rateLimitHits ?? state.rateLimitHits;
+    // Slice-3 memory: journal the accepted move(s) + the thesis behind them so next
+    // cycle has continuity (manage with memory of WHY; don't re-open what we just did).
+    const moves = planned
+        .filter((p) => p.accepted)
+        .map((p) => summarizeAction(p.action));
+    if (moves.length > 0) {
+        const did = `${moves.join("; ")}${rationale ? ` — ${rationale.slice(0, 90)}` : ""}`;
+        state.journal = [
+            ...(state.journal ?? []),
+            { at: observation.asOf, did },
+        ].slice(-10);
+    }
     saveState(stateFile, state);
     if (live && anyExecuted)
         await exportRunEvidence(client, runId);
-    return { decision: "act", planned, live };
+    return {
+        decision: "act",
+        rationale,
+        confidence,
+        rawModelOutput,
+        planned,
+        live,
+        ...meter,
+        decisionType: "act",
+        writeAttempted: decision.actions.length,
+        writeAccepted: planned.filter((p) => p.accepted).length,
+    };
 }
 export async function runLoop(deps, opts = {}) {
     const results = [];

package/dist/agent/scorecard.d.ts

@@ -0,0 +1,24 @@
+export interface ScorecardInput {
+    realizedPnls: number[];
+    cumulative?: number[];
+    returns?: number[];
+    annualizationFactor?: number;
+    trials?: number;
+    predictions?: Array<{
+        p: number;
+        outcome: 0 | 1;
+    }>;
+    gates?: {
+        stopCoverage?: number;
+        evidenceCoverage?: number;
+        leakageClean?: boolean;
+    };
+}
+export interface Scorecard {
+    schema: "coinrithm.agent.scorecard.v1";
+    sampleSize: number;
+    returnsBasis: "returns" | "realized_pnl";
+    metrics: Record<string, number | null>;
+    contentHash: string;
+}
+export declare function computeScorecard(input: ScorecardInput): Scorecard;

package/dist/agent/scorecard.js

@@ -0,0 +1,177 @@
+// Deterministic scorecard engine — pure math over an agent's realized track
+// record. The reproducible-evaluation half of coinrithm.agent.scorecard.v1
+// (see examples/agents/_shared/scorecard.metrics.yaml + DECISIONS D17).
+//
+// DETERMINISM CONTRACT: the same inputs always yield the same metrics AND the
+// same contentHash (sha256 of the canonicalized result), mirroring
+// meta/manifest.lock.json. The engine NEVER calls the network or the model — it
+// reads the run-evidence ledger export + realized equity curve (fetched by the
+// caller) and computes, so tuning-to-the-metric is structurally impossible
+// (leakage separation, arXiv 2512.02227). Every function returns null when there
+// is too little data, so a thin record reports "n/a" rather than a fake number.
+//
+// SCIENTIFIC BASIS: risk-adjusted ratios (Sharpe/Sortino), skill-vs-luck
+// deflation (probabilistic + deflated Sharpe, Bailey & Lopez de Prado), and
+// calibration (Brier/ECE) for probabilistic calls — the reproducible-evaluation
+// layer the field lacks (arXiv 2605.19337).
+import { createHash } from "node:crypto";
+const round = (n, d = 6) => {
+    const f = 10 ** d;
+    return Math.round(n * f) / f;
+};
+const sum = (xs) => xs.reduce((a, b) => a + b, 0);
+const mean = (xs) => (xs.length ? sum(xs) / xs.length : 0);
+// Sample standard deviation (n-1). null for < 2 points (undefined dispersion).
+function sampleStd(xs) {
+    if (xs.length < 2)
+        return null;
+    const m = mean(xs);
+    const v = sum(xs.map((x) => (x - m) ** 2)) / (xs.length - 1);
+    return Math.sqrt(v);
+}
+// Downside deviation about a 0 minimum-acceptable-return (Sortino denominator).
+function downsideDev(xs) {
+    if (xs.length < 2)
+        return null;
+    const sq = xs.map((x) => (x < 0 ? x * x : 0));
+    return Math.sqrt(sum(sq) / xs.length);
+}
+// Population moments used by the (probabilistic) Sharpe formula.
+function moment(xs, k) {
+    const m = mean(xs);
+    return sum(xs.map((x) => (x - m) ** k)) / xs.length;
+}
+// Standard normal CDF via an Abramowitz & Stegun erf approximation (max err ~1e-7).
+function normalCdf(z) {
+    const t = 1 / (1 + 0.2316419 * Math.abs(z));
+    const d = 0.3989422804014327 * Math.exp(-(z * z) / 2);
+    const p = d *
+        t *
+        (0.31938153 +
+            t * (-0.356563782 + t * (1.781477937 + t * (-1.821255978 + t * 1.330274429))));
+    return z >= 0 ? 1 - p : p;
+}
+// Max peak-to-trough drawdown (mUSD, >= 0) on a cumulative series.
+function maxDrawdown(cumulative) {
+    let peak = -Infinity;
+    let maxDd = 0;
+    for (const c of cumulative) {
+        if (!Number.isFinite(c))
+            continue;
+        peak = Math.max(peak, c);
+        maxDd = Math.max(maxDd, peak - c);
+    }
+    return Number.isFinite(maxDd) ? maxDd : 0;
+}
+// Per-observation Sharpe (mean/std), the basis for the probabilistic SR test.
+function rawSharpe(rs) {
+    const sd = sampleStd(rs);
+    if (sd == null || sd === 0)
+        return null;
+    return mean(rs) / sd;
+}
+// Probabilistic / deflated Sharpe (Bailey & Lopez de Prado, approximated).
+// PSR(SR0) = Phi( (SR - SR0) * sqrt(n-1) / sqrt(1 - skew*SR + ((kurt-1)/4)*SR^2) ).
+// Deflation: SR0 = sqrt(2*ln(trials)) / sqrt(n) — the expected max per-obs Sharpe
+// of `trials` random strategies (extreme-value heuristic). trials=1 -> SR0=0, so
+// it reduces to the probabilistic Sharpe (already penalizing short, skewed tracks).
+function deflatedSharpe(rs, trials) {
+    const n = rs.length;
+    if (n < 3)
+        return null;
+    const sr = rawSharpe(rs);
+    if (sr == null)
+        return null;
+    const m2 = moment(rs, 2);
+    if (m2 === 0)
+        return null;
+    const skew = moment(rs, 3) / m2 ** 1.5;
+    const kurt = moment(rs, 4) / m2 ** 2; // 3 for a normal distribution
+    const denom = Math.sqrt(Math.max(1e-9, 1 - skew * sr + ((kurt - 1) / 4) * sr * sr));
+    const sr0 = Math.sqrt(2 * Math.log(Math.max(1, trials))) / Math.sqrt(n);
+    const z = ((sr - sr0) * Math.sqrt(n - 1)) / denom;
+    return normalCdf(z);
+}
+// Brier score: mean((p - outcome)^2). Lower = better-calibrated.
+function brier(preds) {
+    if (preds.length === 0)
+        return null;
+    return mean(preds.map((x) => (x.p - x.outcome) ** 2));
+}
+// Expected calibration error over 10 equal-width probability buckets.
+function ece(preds) {
+    if (preds.length === 0)
+        return null;
+    const buckets = 10;
+    let total = 0;
+    for (let b = 0; b < buckets; b += 1) {
+        const lo = b / buckets;
+        const hi = (b + 1) / buckets;
+        const inB = preds.filter((x) => (b === buckets - 1 ? x.p >= lo && x.p <= hi : x.p >= lo && x.p < hi));
+        if (inB.length === 0)
+            continue;
+        const avgP = mean(inB.map((x) => x.p));
+        const avgO = mean(inB.map((x) => x.outcome));
+        total += (inB.length / preds.length) * Math.abs(avgP - avgO);
+    }
+    return total;
+}
+export function computeScorecard(input) {
+    const pnls = input.realizedPnls.filter(Number.isFinite);
+    const n = pnls.length;
+    const wins = pnls.filter((x) => x > 0);
+    const losses = pnls.filter((x) => x < 0);
+    const decided = wins.length + losses.length;
+    const grossWin = sum(wins);
+    const grossLoss = Math.abs(sum(losses));
+    const avgWin = wins.length ? grossWin / wins.length : 0;
+    const avgLoss = losses.length ? grossLoss / losses.length : 0;
+    const pWin = decided ? wins.length / decided : null;
+    const rs = input.returns && input.returns.length ? input.returns.filter(Number.isFinite) : pnls;
+    const returnsBasis = input.returns && input.returns.length ? "returns" : "realized_pnl";
+    const ann = input.annualizationFactor ?? 1;
+    const cumulative = input.cumulative && input.cumulative.length
+        ? input.cumulative
+        : pnls.reduce((acc, x) => {
+            acc.push((acc.length ? acc[acc.length - 1] : 0) + x);
+            return acc;
+        }, []);
+    const sd = sampleStd(rs);
+    const dd = downsideDev(rs);
+    const sharpe = sd && sd !== 0 ? (mean(rs) / sd) * ann : null;
+    const sortino = dd && dd !== 0 ? (mean(rs) / dd) * ann : null;
+    const metrics = {
+        realized_pnl_musd: round(sum(pnls)),
+        trade_count: n,
+        decided_count: decided,
+        win_rate: pWin == null ? null : round(pWin),
+        expectancy_musd: pWin == null ? null : round(pWin * avgWin - (1 - pWin) * avgLoss),
+        profit_factor: grossLoss > 0 ? round(grossWin / grossLoss) : grossWin > 0 ? null : 0, // null = ∞ (no losses)
+        reward_to_risk: avgLoss > 0 ? round(avgWin / avgLoss) : null,
+        sharpe: sharpe == null ? null : round(sharpe),
+        sortino: sortino == null ? null : round(sortino),
+        deflated_sharpe: round0(deflatedSharpe(rs, input.trials ?? 1)),
+        max_drawdown_musd: round(maxDrawdown(cumulative)),
+        brier_score: round0(brier(input.predictions ?? [])),
+        calibration_error: round0(ece(input.predictions ?? [])),
+        stop_coverage: input.gates?.stopCoverage ?? null,
+        evidence_coverage: input.gates?.evidenceCoverage ?? null,
+        leakage_clean: input.gates?.leakageClean == null ? null : input.gates.leakageClean ? 1 : 0,
+    };
+    // Canonicalize (sorted keys) and hash, so the report card carries a stable,
+    // verifiable fingerprint — a scorecard whose hash does not reproduce is not trusted.
+    const canonical = JSON.stringify(Object.keys(metrics)
+        .sort()
+        .map((k) => [k, metrics[k]]));
+    const contentHash = createHash("sha256").update(canonical).digest("hex");
+    return {
+        schema: "coinrithm.agent.scorecard.v1",
+        sampleSize: n,
+        returnsBasis,
+        metrics,
+        contentHash,
+    };
+}
+function round0(n) {
+    return n == null ? null : round(n);
+}

package/dist/agent/setups.d.ts

@@ -0,0 +1,3 @@
+import { OpenPosition, SetupSignal, WatchEntry } from "./types.js";
+export declare function baseSymbol(s: string | undefined): string;
+export declare function scanSetups(watch: WatchEntry[], openPositions?: OpenPosition[]): SetupSignal[];