@coinrithm/mcp-trading 0.7.15 → 0.7.17

package/dist/agent/bench/bench.d.ts

@@ -0,0 +1,59 @@
+import { type ObserveOptions } from "../observe.js";
+import { Provider } from "../providers.js";
+import { AgentSpec, ProposedAction } from "../types.js";
+import { Cassette } from "./cassette.js";
+import type { BenchmarkStrategy } from "../mechanical.js";
+import { LabelFile } from "./labels.js";
+import { BenchReport, CycleRow } from "./report.js";
+export declare const BASELINE_SKIP = "baseline:skip";
+export declare const BASELINE_MARKET = "baseline:market";
+export declare const BASELINE_BASE_RATE = "baseline:base-rate";
+export declare const BASELINE_RANDOM = "baseline:random";
+/**
+ * Mechanical PM baselines, one deterministic run per cassette each: the
+ * market's own probability, an uninformative 50, and a seeded random
+ * forecast (mechanical.ts). They need the recorded PM observation, so a
+ * futures/spot-only corpus has only baseline:skip.
+ */
+export declare const MECHANICAL_BASELINES: ReadonlyArray<readonly [name: string, strategy: BenchmarkStrategy]>;
+export declare const DEFAULT_REPEATS = 3;
+export declare const MAX_REPEATS = 50;
+export declare const DEFAULT_SEED = 20261007;
+export declare const DEFAULT_BOOTSTRAP_RESAMPLES = 2000;
+export interface BenchVariant {
+    name: string;
+    spec: AgentSpec;
+    mergedProse: string;
+    provider: Provider;
+}
+export interface RunBenchOptions {
+    cassettes: Cassette[];
+    variants: BenchVariant[];
+    repeats?: number;
+    labels?: Record<string, LabelFile>;
+    seed?: number;
+    bootstrapResamples?: number;
+    /** Include the skip and market-implied baselines (default true). */
+    baselines?: boolean;
+    log?: (line: string) => void;
+}
+/**
+ * Run `fn` with Date.now() reading `clockMs` plus the real time elapsed since
+ * the call. Restored afterwards even when `fn` throws. `new Date()` with no
+ * argument is NOT shifted (it does not call Date.now); in the runner it only
+ * stamps the whale-context fetchedAt and fallback asOf values.
+ */
+export declare function withReplayClock<T>(clockMs: number, fn: () => Promise<T>): Promise<T>;
+/**
+ * The identity of a move WITHOUT its size, for action-set overlap and repeat
+ * consistency: did the variant do the same thing, not the same amount.
+ */
+export declare function actionKey(action: ProposedAction): string;
+/** Replay one cassette for one variant once, through the real runCycle. */
+export declare function replayCycle(cassette: Cassette, variant: string, repeat: number, spec: AgentSpec, mergedProse: string, provider: Provider, labels?: LabelFile, observeOptions?: ObserveOptions): Promise<CycleRow>;
+/**
+ * Every modelling assumption behind the numbers, written into each report so
+ * a reader never has to guess what a "stop" or a "cost" means here.
+ */
+export declare function benchAssumptions(): Record<string, unknown>;
+export declare function runBench(opts: RunBenchOptions): Promise<BenchReport>;

package/dist/agent/bench/bench.js

@@ -0,0 +1,319 @@
+// The bench: run variants of an agent on the SAME recorded inputs, K times
+// each, next to built-in baselines, and report honest paired statistics.
+//
+// Every replayed cycle goes through the production runCycle in DRY-RUN with a
+// ReplayClient, so prompt building, parsing, ref resolution, capital sizing,
+// validation and every reject code are exactly the shipped code paths. There
+// is no bench-only decision logic to drift from production.
+//
+// Each cycle starts from a fresh run state (the same state recording used),
+// so daily counters, debounce and journal can never leak between cassettes or
+// repeats. The consequence: replay shows how a variant decides on a first
+// look at a recorded market, not how it behaves deep into a running streak.
+//
+// Clock: Date.now() reads the recording's clock plus the real time elapsed in
+// this cycle, so freshness and entry-predicate age checks see the age the data
+// had when recorded (plus the variant's own model latency, as in production).
+import { buildAgentDefinitionSnapshot } from "../definitionSnapshot.js";
+import { clearPmCalibrationCache } from "../observe.js";
+import { runCycle } from "../runner.js";
+import { newState } from "../state.js";
+import { mechanicalBaselineSpec } from "./cassette.js";
+import { FUTURES_SYNTHETIC_FEE_BPS, PM_SYNTHETIC_FEE_RATE_AT_MID, SPOT_SYNTHETIC_FEE_BPS, } from "./costs.js";
+import { scoreAction } from "./labels.js";
+import { BENCH_RUN_ID, SKIP_PROVIDER } from "./recordingClient.js";
+import { ReplayClient } from "./replayClient.js";
+import { buildReport, chronological, } from "./report.js";
+export const BASELINE_SKIP = "baseline:skip";
+export const BASELINE_MARKET = "baseline:market";
+export const BASELINE_BASE_RATE = "baseline:base-rate";
+export const BASELINE_RANDOM = "baseline:random";
+/**
+ * Mechanical PM baselines, one deterministic run per cassette each: the
+ * market's own probability, an uninformative 50, and a seeded random
+ * forecast (mechanical.ts). They need the recorded PM observation, so a
+ * futures/spot-only corpus has only baseline:skip.
+ */
+export const MECHANICAL_BASELINES = [
+    [BASELINE_MARKET, "market-implied"],
+    [BASELINE_BASE_RATE, "base-rate"],
+    [BASELINE_RANDOM, "random"],
+];
+export const DEFAULT_REPEATS = 3;
+export const MAX_REPEATS = 50;
+export const DEFAULT_SEED = 20261007;
+export const DEFAULT_BOOTSTRAP_RESAMPLES = 2000;
+const VARIANT_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,39}$/;
+/**
+ * Run `fn` with Date.now() reading `clockMs` plus the real time elapsed since
+ * the call. Restored afterwards even when `fn` throws. `new Date()` with no
+ * argument is NOT shifted (it does not call Date.now); in the runner it only
+ * stamps the whale-context fetchedAt and fallback asOf values.
+ */
+export async function withReplayClock(clockMs, fn) {
+    const realNow = Date.now;
+    const offset = clockMs - realNow();
+    Date.now = () => realNow() + offset;
+    try {
+        return await fn();
+    }
+    finally {
+        Date.now = realNow;
+    }
+}
+/**
+ * The identity of a move WITHOUT its size, for action-set overlap and repeat
+ * consistency: did the variant do the same thing, not the same amount.
+ */
+export function actionKey(action) {
+    const lower = (s) => (s ?? "").toLowerCase();
+    const upper = (s) => (s ?? "").toUpperCase();
+    switch (action.type) {
+        case "pm_open":
+            return `pm_open:${lower(action.source)}/${lower(action.slug)}/${action.outcomeExternalMarketId ?? action.ref ?? ""}`;
+        case "futures_open":
+            return `futures_open:${upper(action.symbol)}:${action.side}`;
+        case "futures_close":
+            return `futures_close:${action.positionId}`;
+        case "futures_set_sltp":
+            return `futures_set_sltp:${action.positionId}`;
+        case "spot_order":
+            return `spot_order:${upper(action.symbol)}:${action.side}:${action.orderType}`;
+        case "spot_cancel":
+            return `spot_cancel:${action.orderId}`;
+    }
+}
+function sizeOf(action) {
+    if (action.type === "pm_open")
+        return action.stakeMusd;
+    if (action.type === "futures_open")
+        return action.marginMusd;
+    return undefined;
+}
+function toRow(cassette, variant, repeat, result, runtimeError, client, labels) {
+    const actions = (result?.planned ?? []).map((p) => {
+        const forecast = p.action
+            .forecastProbability;
+        return {
+            key: actionKey(p.action),
+            type: p.action.type,
+            accepted: p.accepted,
+            ...(p.accepted ? {} : { code: p.code ?? "unknown" }),
+            ...(p.quote ? { quote: "synthesized" } : {}),
+            ...(typeof forecast === "number"
+                ? { forecastProbability: forecast }
+                : {}),
+            ...(p.quote?.entryProbability !== undefined
+                ? { entryProbability: p.quote.entryProbability }
+                : {}),
+            ...(sizeOf(p.action) !== undefined ? { sizeMusd: sizeOf(p.action) } : {}),
+            ...(p.accepted
+                ? {
+                    score: scoreAction({
+                        action: p.action,
+                        quote: p.quote,
+                        asOf: cassette.asOf,
+                        labels,
+                    }),
+                }
+                : {}),
+        };
+    });
+    const decisionType = runtimeError
+        ? "runtime_error"
+        : (result?.decisionType ?? (result?.decision === "act" ? "act" : "skip"));
+    return {
+        cassetteId: cassette.id,
+        asOf: cassette.asOf,
+        variant,
+        repeat,
+        decision: result?.decision ?? "skip",
+        decisionType,
+        modelFailed: result?.modelFailed === true,
+        llmCallMade: result?.llmCallMade === true,
+        ...(result?.routeAttempts
+            ? {
+                routeAttempts: result.routeAttempts.slice(0, 2).map((attempt) => ({
+                    provider: attempt.provider,
+                    model: attempt.model,
+                    outcome: attempt.outcome,
+                    ...(attempt.failureClass
+                        ? { failureClass: attempt.failureClass }
+                        : {}),
+                    ...(attempt.status !== undefined ? { status: attempt.status } : {}),
+                    ...(attempt.responseSource
+                        ? { responseSource: attempt.responseSource }
+                        : {}),
+                    ...(attempt.actionsStringDiagnostic
+                        ? { actionsStringDiagnostic: attempt.actionsStringDiagnostic }
+                        : {}),
+                    ...(attempt.admissionReasons
+                        ? { admissionReasons: [...attempt.admissionReasons] }
+                        : {}),
+                })),
+                ...(result.routeAttempts.length > 2
+                    ? { routeAttemptsTruncated: true }
+                    : {}),
+            }
+            : {}),
+        ...(result?.triggerCodes ? { triggerCodes: [...result.triggerCodes] } : {}),
+        ...(result?.skipReason
+            ? { skipReason: result.skipReason.slice(0, 200) }
+            : {}),
+        ...(runtimeError ? { runtimeError: runtimeError.slice(0, 200) } : {}),
+        actions,
+        missingInputs: [...new Set(client.stats.missing)].sort(),
+        synthesizedQuotes: client.stats.synthesizedQuotes.length,
+        refusedWrites: [...client.stats.refusedWrites],
+    };
+}
+/** Replay one cassette for one variant once, through the real runCycle. */
+export async function replayCycle(cassette, variant, repeat, spec, mergedProse, provider, labels, observeOptions) {
+    clearPmCalibrationCache();
+    const client = new ReplayClient(cassette);
+    let result;
+    let runtimeError;
+    try {
+        result = await withReplayClock(cassette.clockMs, () => runCycle({
+            client,
+            provider,
+            spec,
+            mergedProse,
+            state: newState(BENCH_RUN_ID),
+            live: false,
+            ...(observeOptions ? { observeOptions } : {}),
+        }));
+    }
+    catch (error) {
+        // A crash is a result for this variant, never a reason to drop the cycle.
+        runtimeError = error instanceof Error ? error.message : String(error);
+    }
+    return toRow(cassette, variant, repeat, result, runtimeError, client, labels);
+}
+/** The always-skip baseline: no reads, no model, no action, by definition. */
+function skipBaselineRow(cassette) {
+    return {
+        cassetteId: cassette.id,
+        asOf: cassette.asOf,
+        variant: BASELINE_SKIP,
+        repeat: 0,
+        decision: "skip",
+        decisionType: "skip",
+        modelFailed: false,
+        llmCallMade: false,
+        skipReason: "baseline: always skip",
+        actions: [],
+        missingInputs: [],
+        synthesizedQuotes: 0,
+        refusedWrites: [],
+    };
+}
+/**
+ * Every modelling assumption behind the numbers, written into each report so
+ * a reader never has to guess what a "stop" or a "cost" means here.
+ */
+export function benchAssumptions() {
+    return {
+        quotes: "every quote is synthesized from recorded evidence (PM: the discover probability of the chosen outcome; futures/spot: the recorded market price); none comes from the paper engine",
+        entry: "entry at the recorded (synthesized) quote with the paper fee model below; entry latency is not modelled",
+        pmFee: {
+            constant: "PM_SYNTHETIC_FEE_RATE_AT_MID",
+            value: PM_SYNTHETIC_FEE_RATE_AT_MID,
+            model: "fee = rate x 4p(1-p) of the price paid (openapi Paper Execution Realism v1 shape: ~1.8% near 50%, ~0 at the extremes); ask spread and size slippage are not modelled, so PM cost is optimistic by an unmeasured amount",
+        },
+        futuresFee: {
+            constant: "FUTURES_SYNTHETIC_FEE_BPS",
+            value: FUTURES_SYNTHETIC_FEE_BPS,
+            model: "flat taker fee on notional at entry and at exit (the runner's conservative pre-quote estimate); spread and slippage not modelled",
+        },
+        spotFee: {
+            constant: "SPOT_SYNTHETIC_FEE_BPS",
+            value: SPOT_SYNTHETIC_FEE_BPS,
+        },
+        pmEntryFloor: "the synthesized quote does not apply the server floor; the runner validator rejects the same action as pm_entry_below_floor (production: quote_ineligible)",
+        pmOutcome: "settled 0/1 from the label file; cost = stake / net shares (fee-inclusive); Brier uses the forecast the agent sent",
+        futuresOutcome: "an OHLC walk MODEL over label bars that open after asOf; it is not exact fill or stop behaviour",
+        sameBarStopAndTarget: "a bar touching both stop and take-profit is resolved as the STOP (conservative) and counted in labelled.futuresSameBarStopFirst",
+        missingBars: "a missing bar before the exit (or before the horizon end) gives outcome unlabelled_gap: counted, never filled",
+        funding: "included only when the label file carries funding events for the symbol (labelled.futuresFundingIncluded); otherwise excluded",
+        liquidation: "approximated at entry x (1 -/+ 1/leverage); forfeits the margin with no extra fill cost",
+        state: "fresh run state per cycle: no journal, theses, debounce or daily counters carried between cassettes or repeats",
+        clock: "Date.now = recording clock + real elapsed time, so data ages as recorded plus model latency",
+        outcomeCutoff: "asOf is the end of all recording reads; it is not the earlier trades sync cursor",
+        pnlComparisons: "zero means a complete no-action cycle; cycles with missing inputs, runtime errors, or any unscored accepted action are excluded from paired PnL, with exclusion counts shown; all repeats of a cassette must qualify",
+        inference: "per-cassette bootstrap assumes independent observations; overlapping market windows can violate that assumption; repeated A/A calibration does not establish independence or future performance",
+    };
+}
+export async function runBench(opts) {
+    const repeats = opts.repeats ?? DEFAULT_REPEATS;
+    if (!Number.isInteger(repeats) || repeats < 1 || repeats > MAX_REPEATS)
+        throw new Error(`repeats must be an integer from 1 to ${MAX_REPEATS}`);
+    if (opts.variants.length === 0)
+        throw new Error("at least one variant is required");
+    const names = new Set();
+    for (const v of opts.variants) {
+        if (!VARIANT_NAME_RE.test(v.name))
+            throw new Error(`variant name "${v.name}" must be 1-40 letters, digits, "_", "." or "-"`);
+        if (names.has(v.name))
+            throw new Error(`duplicate variant "${v.name}"`);
+        names.add(v.name);
+    }
+    if (opts.cassettes.length === 0)
+        throw new Error("the corpus has no cassettes");
+    const seed = (opts.seed ?? DEFAULT_SEED) >>> 0;
+    const resamples = opts.bootstrapResamples ?? DEFAULT_BOOTSTRAP_RESAMPLES;
+    const baselines = opts.baselines !== false;
+    const log = opts.log ?? (() => { });
+    const cassettes = chronological(opts.cassettes);
+    const rows = [];
+    for (const cassette of cassettes) {
+        const labels = opts.labels?.[cassette.id];
+        for (const v of opts.variants) {
+            for (let r = 0; r < repeats; r++) {
+                const row = await replayCycle(cassette, v.name, r, v.spec, v.mergedProse, v.provider, labels);
+                rows.push(row);
+                log(`${cassette.id} ${v.name}#${r + 1}: ${row.decisionType}, ${row.actions.filter((a) => a.accepted).length}/${row.actions.length} accepted${row.missingInputs.length ? `, ${row.missingInputs.length} missing input(s)` : ""}`);
+            }
+        }
+        if (baselines) {
+            rows.push(skipBaselineRow(cassette));
+            // Deterministic, so one run per cassette each. Use the recorded agent's
+            // board policy, not the replacement mechanical provider's policy.
+            // Originally mechanical recordings keep their uncurated board.
+            if (cassette.marketBaselineRecorded)
+                for (const [name, strategy] of MECHANICAL_BASELINES)
+                    rows.push(await replayCycle(cassette, name, 0, mechanicalBaselineSpec(cassette.spec, strategy), "", SKIP_PROVIDER, labels, {
+                        curatedPmBoard: cassette.spec.model?.provider !== "mechanical",
+                    }));
+        }
+    }
+    const variants = opts.variants.map((v) => ({
+        name: v.name,
+        kind: "variant",
+        definitionHash: buildAgentDefinitionSnapshot(v.spec, v.mergedProse)
+            .definitionHash,
+    }));
+    if (baselines) {
+        variants.push({ name: BASELINE_SKIP, kind: "baseline" });
+        if (cassettes.some((c) => c.marketBaselineRecorded))
+            for (const [name] of MECHANICAL_BASELINES)
+                variants.push({ name, kind: "baseline" });
+    }
+    const specHashes = [...new Set(cassettes.map((c) => c.agentSpecHash))].sort();
+    return buildReport({
+        cassettes,
+        rows,
+        variants,
+        repeats,
+        seed,
+        bootstrapResamples: resamples,
+        assumptions: benchAssumptions(),
+        fidelity: {
+            recordedAgentDefinitions: specHashes,
+            synthesizedQuotes: rows.reduce((s, r) => s + r.synthesizedQuotes, 0),
+            cyclesWithMissingInputs: rows.filter((r) => r.missingInputs.length > 0)
+                .length,
+            refusedWrites: rows.reduce((s, r) => s + r.refusedWrites.length, 0),
+        },
+    });
+}

package/dist/agent/bench/cassette.d.ts

@@ -0,0 +1,97 @@
+import { AgentSpec } from "../types.js";
+import type { BenchmarkStrategy } from "../mechanical.js";
+import { LabelFile } from "./labels.js";
+export declare const CASSETTE_SCHEMA = "coinrithm.bench.cassette.v1";
+export interface RecordedResponse {
+    /** Canonical request key: METHOD + path + sorted query. */
+    key: string;
+    method: string;
+    path: string;
+    query: Record<string, string>;
+    status: number;
+    ok: boolean;
+    /** The body as the client parses it: JSON when it parses, else the text. */
+    data: unknown;
+    /** The recorded request failed in transport (no HTTP response at all). */
+    transportError?: boolean;
+}
+export interface Cassette {
+    schema: typeof CASSETTE_SCHEMA;
+    id: string;
+    recordedAt: string;
+    /** Epoch ms the replay clock starts from (Date.now during replay). */
+    clockMs: number;
+    /** Cutoff after ALL recording reads, including baseline-only inputs. */
+    asOf: string;
+    /** definitionHash of the recorded spec + prose (see definitionSnapshot). */
+    agentSpecHash: string;
+    spec: AgentSpec;
+    /** PM observation available for baselines. Legacy recordings used this
+     *  only to mark an attempted extra mechanical pass; replay still reports
+     *  missing inputs instead of treating the marker as a coverage guarantee. */
+    marketBaselineRecorded: boolean;
+    recordCycle: {
+        decision: string;
+        decisionType?: string;
+        skipReason?: string;
+    };
+    /** Non-GET requests the recorder refused to forward (never sent). */
+    refusedRequests: string[];
+    responses: RecordedResponse[];
+}
+export interface CanonicalRequest {
+    key: string;
+    method: string;
+    path: string;
+    query: Record<string, string>;
+}
+/**
+ * Canonical request identity used for both recording and replay: upper-cased
+ * method, the path relative to the API base path, and the query parameters
+ * sorted by name. The host is deliberately not part of the key, so a cassette
+ * recorded against one base URL replays against the bench's fake one.
+ */
+export declare function canonicalRequest(method: string, url: string, basePath?: string): CanonicalRequest;
+/** The path prefix of an API base URL ("" for a host-root base). */
+export declare function basePathOf(baseUrl: string): string;
+export declare function sha256Hex(text: string): string;
+/** Sorted-key JSON, the same canonicalization the scorecard hash relies on. */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * The spec a recording pass runs with: the agent's own spec with its gate
+ * forced to fire, so the post-gate reads (whale context) are always recorded
+ * and a variant whose gate fires on replay finds them in the cassette.
+ */
+export declare function recordingSpec(spec: AgentSpec): AgentSpec;
+/**
+ * The market-implied baseline: the recorded agent's spec and caps with the
+ * deterministic mechanical "market-implied" strategy as its brain (mechanical
+ * .ts). runBench separately preserves the recorded agent's observation
+ * policy, so replacing the provider never changes the PM opportunity set.
+ */
+export declare function marketBaselineSpec(spec: AgentSpec): AgentSpec;
+/**
+ * The same recorded spec with one of the mechanical benchmark strategies as
+ * its brain. base-rate and random pick the SAME market from the SAME
+ * observation as market-implied (mechanical.ts); all use the original
+ * recording's PM board and never fetch a separate baseline universe.
+ */
+export declare function mechanicalBaselineSpec(spec: AgentSpec, strategy: BenchmarkStrategy): AgentSpec;
+/** Filesystem-safe, content-addressed cassette id: asOf stamp + body hash. */
+export declare function cassetteId(asOf: string, contentHash: string): string;
+export declare function writeCassette(dir: string, cassette: Cassette): string;
+/** Validate a parsed cassette. Throws on a malformed one (fail closed). */
+export declare function parseCassette(value: unknown, source: string): Cassette;
+export interface Corpus {
+    cassettes: Cassette[];
+    labels: Record<string, LabelFile>;
+    /** Top-level .json files that are not cassettes (e.g. a saved report). */
+    ignored: string[];
+}
+/**
+ * Read every cassette at the top level of `dir` plus the optional
+ * `labels/<cassetteId>.json` files. A JSON file with the cassette schema that
+ * fails validation, or a malformed label file, stops the bench: a silently
+ * skipped input would bias the comparison.
+ */
+export declare function readCorpus(dir: string): Corpus;

package/dist/agent/bench/cassette.js

@@ -0,0 +1,181 @@
+// Bench cassettes: the recorded READ inputs of one agent cycle.
+//
+// A cassette is the source of truth the bench replays. It holds every read
+// response the real production runner made in one dry-run cycle (status, body,
+// keyed by a canonical request key), the clock it was recorded at, and the
+// recorded agent's spec (needed to replay the built-in baselines on the same
+// inputs). It never holds request headers, so no API key reaches a cassette.
+// It DOES hold the recording account's paper reads (wallet, positions), so
+// keep a corpus as private as the account it was recorded from.
+//
+// Why not replay the stored `decision_input_record`: that record declares
+// itself partial (prompts, news and journal excluded, byte budget) and carries
+// no replay guarantee. Inputs are therefore recorded going forward, in full.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_TRIGGER_POLICY } from "../types.js";
+import { sortDeep } from "../util.js";
+import { parseLabelFile } from "./labels.js";
+export const CASSETTE_SCHEMA = "coinrithm.bench.cassette.v1";
+/**
+ * Canonical request identity used for both recording and replay: upper-cased
+ * method, the path relative to the API base path, and the query parameters
+ * sorted by name. The host is deliberately not part of the key, so a cassette
+ * recorded against one base URL replays against the bench's fake one.
+ */
+export function canonicalRequest(method, url, basePath = "") {
+    const u = new URL(url);
+    const base = basePath.replace(/\/+$/, "");
+    let path = u.pathname;
+    if (base && (path === base || path.startsWith(`${base}/`)))
+        path = path.slice(base.length) || "/";
+    const params = new URLSearchParams(u.search);
+    params.sort();
+    const query = {};
+    params.forEach((value, name) => {
+        query[name] = value;
+    });
+    const qs = params.toString();
+    const m = method.toUpperCase();
+    return { key: `${m} ${path}${qs ? `?${qs}` : ""}`, method: m, path, query };
+}
+/** The path prefix of an API base URL ("" for a host-root base). */
+export function basePathOf(baseUrl) {
+    return new URL(baseUrl).pathname.replace(/\/+$/, "");
+}
+export function sha256Hex(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+/** Sorted-key JSON, the same canonicalization the scorecard hash relies on. */
+export function canonicalJson(value) {
+    return JSON.stringify(sortDeep(value));
+}
+/**
+ * The spec a recording pass runs with: the agent's own spec with its gate
+ * forced to fire, so the post-gate reads (whale context) are always recorded
+ * and a variant whose gate fires on replay finds them in the cassette.
+ */
+export function recordingSpec(spec) {
+    return {
+        ...spec,
+        triggerPolicy: {
+            ...(spec.triggerPolicy ?? DEFAULT_TRIGGER_POLICY),
+            mode: "always",
+        },
+    };
+}
+/**
+ * The market-implied baseline: the recorded agent's spec and caps with the
+ * deterministic mechanical "market-implied" strategy as its brain (mechanical
+ * .ts). runBench separately preserves the recorded agent's observation
+ * policy, so replacing the provider never changes the PM opportunity set.
+ */
+export function marketBaselineSpec(spec) {
+    return mechanicalBaselineSpec(spec, "market-implied");
+}
+/**
+ * The same recorded spec with one of the mechanical benchmark strategies as
+ * its brain. base-rate and random pick the SAME market from the SAME
+ * observation as market-implied (mechanical.ts); all use the original
+ * recording's PM board and never fetch a separate baseline universe.
+ */
+export function mechanicalBaselineSpec(spec, strategy) {
+    return {
+        ...recordingSpec(spec),
+        model: { provider: "mechanical", name: strategy },
+    };
+}
+function stampOf(asOf) {
+    const stamp = asOf
+        .replace(/[^0-9A-Za-z]+/g, "-")
+        .slice(0, 40)
+        .replace(/^-+|-+$/g, "");
+    return stamp || "cassette";
+}
+/** Filesystem-safe, content-addressed cassette id: asOf stamp + body hash. */
+export function cassetteId(asOf, contentHash) {
+    return `${stampOf(asOf)}-${contentHash.slice(0, 12)}`;
+}
+export function writeCassette(dir, cassette) {
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `${cassette.id}.json`);
+    writeFileSync(file, `${JSON.stringify(cassette, null, 2)}\n`, "utf8");
+    return file;
+}
+/** Validate a parsed cassette. Throws on a malformed one (fail closed). */
+export function parseCassette(value, source) {
+    const c = (value ?? {});
+    const problems = [];
+    if (c.schema !== CASSETTE_SCHEMA)
+        problems.push("schema");
+    if (typeof c.id !== "string" || !/^[0-9A-Za-z-]{1,80}$/.test(c.id))
+        problems.push("id");
+    if (typeof c.asOf !== "string" || !Number.isFinite(Date.parse(c.asOf)))
+        problems.push("asOf");
+    if (typeof c.clockMs !== "number" || !Number.isFinite(c.clockMs))
+        problems.push("clockMs");
+    if (!c.spec || typeof c.spec !== "object" || !Array.isArray(c.spec.venues))
+        problems.push("spec");
+    if (!Array.isArray(c.responses) ||
+        c.responses.some((r) => !r ||
+            typeof r.key !== "string" ||
+            typeof r.path !== "string" ||
+            typeof r.status !== "number"))
+        problems.push("responses");
+    if (problems.length > 0)
+        throw new Error(`cassette ${source} is invalid (${problems.join(", ")}); re-record it`);
+    return {
+        ...c,
+        marketBaselineRecorded: c.marketBaselineRecorded === true,
+        refusedRequests: Array.isArray(c.refusedRequests) ? c.refusedRequests : [],
+    };
+}
+/**
+ * Read every cassette at the top level of `dir` plus the optional
+ * `labels/<cassetteId>.json` files. A JSON file with the cassette schema that
+ * fails validation, or a malformed label file, stops the bench: a silently
+ * skipped input would bias the comparison.
+ */
+export function readCorpus(dir) {
+    const cassettes = [];
+    const ignored = [];
+    for (const name of readdirSync(dir).sort()) {
+        if (!name.endsWith(".json"))
+            continue;
+        const file = join(dir, name);
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            throw new Error(`corpus file ${name} is not valid JSON; repair or explicitly remove it before comparing variants`);
+        }
+        if (parsed?.schema !== CASSETTE_SCHEMA) {
+            ignored.push(name);
+            continue;
+        }
+        cassettes.push(parseCassette(parsed, name));
+    }
+    const ids = new Set();
+    for (const c of cassettes) {
+        if (ids.has(c.id))
+            throw new Error(`duplicate cassette id ${c.id}`);
+        ids.add(c.id);
+    }
+    const labels = {};
+    for (const c of cassettes) {
+        const file = join(dir, "labels", `${c.id}.json`);
+        if (!existsSync(file))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch (e) {
+            throw new Error(`label file labels/${c.id}.json is not valid JSON: ${e.message}`);
+        }
+        labels[c.id] = parseLabelFile(parsed, `labels/${c.id}.json`);
+    }
+    return { cassettes, labels, ignored };
+}