modelrig 0.1.0 → 0.3.0

package/dist/verify/diff.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * The diff engine — the honest verdict vocabulary that makes the verifier's
+ * report trustworthy. Pure (no adapters, no run loop): it compares an
+ * original output against a routed one and returns one of three verdicts.
+ *
+ * Design decision (flagged for architect review): the routed output arrives
+ * as PARSED JSON — `run()` only returns after the output validated against the
+ * route schema (or it throws), so a routed sample is guaranteed schema-
+ * conformant and JSON. We therefore compare STRUCTURE, not raw bytes. For JSON,
+ * key order and whitespace are not behavior, so "byte-identical where
+ * deterministic" is operationalized as CANONICAL identity (sorted-key
+ * serialization). Structured-field equality — with declared nondeterministic
+ * fields excluded — is the fallback, exactly as the spec's §6 evaluation
+ * contract prescribes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalJson = canonicalJson;
+exports.firstDivergence = firstDivergence;
+exports.diffOutputs = diffOutputs;
+/** Deterministic JSON serialization: object keys sorted recursively, arrays
+ * left in order (order is semantic). The operative notion of "byte-identical"
+ * for JSON outputs. */
+function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = sortKeys(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/** True when `path` is exactly, or nested under, any declared nondeterministic
+ * path. `/meta` masks `/meta` and `/meta/gen`; it never masks `/metadata`. */
+function isMasked(path, nondeterministicPaths) {
+    return nondeterministicPaths.some((nd) => path === nd || path.startsWith(`${nd}/`));
+}
+/**
+ * First point at which `original` and `routed` structurally differ, in a
+ * stable depth-first order, or null when they are deep-equal after masking the
+ * declared nondeterministic paths. Object keys are visited in sorted order so
+ * the "first" differing field is deterministic across runs.
+ */
+function firstDivergence(original, routed, nondeterministicPaths, path = "") {
+    const here = path === "" ? "" : path;
+    if (isMasked(here || "/", nondeterministicPaths))
+        return null;
+    if (Array.isArray(original) || Array.isArray(routed)) {
+        if (!Array.isArray(original) || !Array.isArray(routed) || original.length !== routed.length) {
+            return { path: here || "/", originalValue: original, routedValue: routed };
+        }
+        for (let i = 0; i < original.length; i += 1) {
+            const d = firstDivergence(original[i], routed[i], nondeterministicPaths, `${here}/${i}`);
+            if (d !== null)
+                return d;
+        }
+        return null;
+    }
+    if (isObject(original) || isObject(routed)) {
+        if (!isObject(original) || !isObject(routed)) {
+            return { path: here || "/", originalValue: original, routedValue: routed };
+        }
+        const keys = [...new Set([...Object.keys(original), ...Object.keys(routed)])].sort();
+        for (const key of keys) {
+            const childPath = `${here}/${escapePointer(key)}`;
+            if (isMasked(childPath, nondeterministicPaths))
+                continue;
+            const inO = Object.prototype.hasOwnProperty.call(original, key);
+            const inR = Object.prototype.hasOwnProperty.call(routed, key);
+            if (!inO || !inR) {
+                return { path: childPath, originalValue: original[key], routedValue: routed[key] };
+            }
+            const d = firstDivergence(original[key], routed[key], nondeterministicPaths, childPath);
+            if (d !== null)
+                return d;
+        }
+        return null;
+    }
+    // Scalars (incl. null): a strict, type-aware compare.
+    if (original !== routed) {
+        return { path: here || "/", originalValue: original, routedValue: routed };
+    }
+    return null;
+}
+function isObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/** RFC-6901 escaping for a path segment (`~`→`~0`, `/`→`~1`). */
+function escapePointer(key) {
+    return key.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function shortValue(v) {
+    const s = typeof v === "string" ? v : JSON.stringify(v);
+    return s !== undefined && s.length > 60 ? `${s.slice(0, 57)}…` : String(s);
+}
+function tryParse(text) {
+    try {
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/**
+ * Diff an original output (raw text) against a routed output (already parsed by
+ * `run()`), returning the verdict. `routedParsed` is guaranteed schema-
+ * conformant JSON by the run loop; `originalText` is whatever the original call
+ * site emitted.
+ *
+ *  - byte / canonical identity ⇒ `equivalent`
+ *  - structurally equal after masking declared nd-paths ⇒
+ *    `equivalent-modulo-nondeterminism`
+ *  - a real structured field differs ⇒ `divergent` (first field named)
+ *  - the original is not JSON ⇒ `divergent` (a free-text call site — this
+ *    isn't route-shaped work; T0/T1 territory, honestly flagged not forced)
+ */
+function diffOutputs(originalText, routedParsed, routedText, nondeterministicPaths) {
+    // True byte-identity first — the strongest, cheapest signal.
+    if (originalText === routedText) {
+        return { verdict: "equivalent", firstDivergentPath: null, detail: "byte-identical output" };
+    }
+    const parsedOriginal = tryParse(originalText);
+    if (!parsedOriginal.ok) {
+        return {
+            verdict: "divergent",
+            firstDivergentPath: null,
+            detail: "original output is not JSON — this is a free-text call site; equivalence is not " +
+                "provable through a task route (T0/T1 territory, not a Tier-2 replacement)",
+        };
+    }
+    // Canonical identity: for JSON, key order and whitespace are not behavior.
+    if (canonicalJson(parsedOriginal.value) === canonicalJson(routedParsed)) {
+        return { verdict: "equivalent", firstDivergentPath: null, detail: "canonically identical JSON" };
+    }
+    const d = firstDivergence(parsedOriginal.value, routedParsed, nondeterministicPaths);
+    if (d === null) {
+        return {
+            verdict: "equivalent-modulo-nondeterminism",
+            firstDivergentPath: null,
+            detail: nondeterministicPaths.length > 0
+                ? `structurally equal after excluding nondeterministic field(s): ${nondeterministicPaths.join(", ")}`
+                : "structurally equal (serialization differs only)",
+        };
+    }
+    return {
+        verdict: "divergent",
+        firstDivergentPath: d.path,
+        detail: `structured field ${d.path} differs: original=${shortValue(d.originalValue)} ` +
+            `routed=${shortValue(d.routedValue)}`,
+    };
+}

package/dist/verify/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shadow-equivalence verifier (Expansion §9, autonomy-ladder Tier 2) — the
+ * public barrel. Proves a same-model call replacement is behavior-preserving
+ * before a human merges the Tier-2 PR: capture (local) → replay through the
+ * routed replacement (reusing the run loop) → diff (honest verdict vocabulary)
+ * → report (machine + human). Refusing an uncapturable call site is a correct
+ * output, never a failure.
+ */
+export { verifySwap } from "./verify";
+export type { VerifySwapRequest } from "./verify";
+export { diffOutputs, firstDivergence, canonicalJson } from "./diff";
+export type { Divergence } from "./diff";
+export { captureOriginal, openShadowCaptureStore, parseFixture, serializeFixture, } from "./capture";
+export type { OriginalCallSite, OriginalCallFn, CaptureOptions, ShadowCaptureStore, ShadowCaptureRecord, } from "./capture";
+export { renderReportMarkdown } from "./report";
+export type { ShadowCapture, ShadowCaptureFixture, CaptureRefusal, SampleVerdict, EquivalenceVerdict, SampleDiff, SampleReport, EquivalenceReport, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/verify/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/verify/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,GACjB,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,iBAAiB,GAClB,MAAM,SAAS,CAAC"}

package/dist/verify/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Shadow-equivalence verifier (Expansion §9, autonomy-ladder Tier 2) — the
+ * public barrel. Proves a same-model call replacement is behavior-preserving
+ * before a human merges the Tier-2 PR: capture (local) → replay through the
+ * routed replacement (reusing the run loop) → diff (honest verdict vocabulary)
+ * → report (machine + human). Refusing an uncapturable call site is a correct
+ * output, never a failure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderReportMarkdown = exports.serializeFixture = exports.parseFixture = exports.openShadowCaptureStore = exports.captureOriginal = exports.canonicalJson = exports.firstDivergence = exports.diffOutputs = exports.verifySwap = void 0;
+var verify_1 = require("./verify");
+Object.defineProperty(exports, "verifySwap", { enumerable: true, get: function () { return verify_1.verifySwap; } });
+var diff_1 = require("./diff");
+Object.defineProperty(exports, "diffOutputs", { enumerable: true, get: function () { return diff_1.diffOutputs; } });
+Object.defineProperty(exports, "firstDivergence", { enumerable: true, get: function () { return diff_1.firstDivergence; } });
+Object.defineProperty(exports, "canonicalJson", { enumerable: true, get: function () { return diff_1.canonicalJson; } });
+var capture_1 = require("./capture");
+Object.defineProperty(exports, "captureOriginal", { enumerable: true, get: function () { return capture_1.captureOriginal; } });
+Object.defineProperty(exports, "openShadowCaptureStore", { enumerable: true, get: function () { return capture_1.openShadowCaptureStore; } });
+Object.defineProperty(exports, "parseFixture", { enumerable: true, get: function () { return capture_1.parseFixture; } });
+Object.defineProperty(exports, "serializeFixture", { enumerable: true, get: function () { return capture_1.serializeFixture; } });
+var report_1 = require("./report");
+Object.defineProperty(exports, "renderReportMarkdown", { enumerable: true, get: function () { return report_1.renderReportMarkdown; } });

package/dist/verify/report.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Report rendering — the shadow-equivalence report the skill's Tier-2 PR
+ * embeds. Two forms, one source: the machine-readable form is the
+ * `EquivalenceReport` object serialized as JSON (stable, `schemaVersion: 1`);
+ * the human-readable form is the Markdown below, written for a PR reviewer who
+ * must decide whether the same-model replacement is safe to merge.
+ *
+ * The rendering never editorializes the verdict — it prints exactly what the
+ * diff decided, always alongside the plumbing-not-model-choice guarantee so a
+ * reader cannot mistake equivalence for a model-quality claim.
+ */
+import type { EquivalenceReport } from "./types";
+export declare function renderReportMarkdown(report: EquivalenceReport): string;
+//# sourceMappingURL=report.d.ts.map

package/dist/verify/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/verify/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAoC,MAAM,SAAS,CAAC;AAwCnF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CA+CtE"}

package/dist/verify/report.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Report rendering — the shadow-equivalence report the skill's Tier-2 PR
+ * embeds. Two forms, one source: the machine-readable form is the
+ * `EquivalenceReport` object serialized as JSON (stable, `schemaVersion: 1`);
+ * the human-readable form is the Markdown below, written for a PR reviewer who
+ * must decide whether the same-model replacement is safe to merge.
+ *
+ * The rendering never editorializes the verdict — it prints exactly what the
+ * diff decided, always alongside the plumbing-not-model-choice guarantee so a
+ * reader cannot mistake equivalence for a model-quality claim.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderReportMarkdown = renderReportMarkdown;
+const VERDICT_LABEL = {
+    equivalent: "EQUIVALENT",
+    "equivalent-modulo-nondeterminism": "EQUIVALENT (modulo nondeterminism)",
+    divergent: "DIVERGENT",
+    refused: "REFUSED",
+};
+/** The one-line headline a reviewer reads first. */
+function headline(report) {
+    const label = VERDICT_LABEL[report.overall];
+    switch (report.overall) {
+        case "equivalent":
+            return `✅ **${label}** — all ${report.n} replayed input(s) reproduced the original output.`;
+        case "equivalent-modulo-nondeterminism":
+            return `🟡 **${label}** — all ${report.n} input(s) matched once declared nondeterministic fields were excluded.`;
+        case "divergent":
+            return `❌ **${label}** — ${report.counts.divergent} of ${report.n} input(s) did not reproduce; do not merge.`;
+        case "refused":
+            return `⛔ **${label}** — not a Tier-2 replacement. ${report.refusalReason ?? ""}`.trim();
+    }
+}
+/** Escape `|` so a field value never breaks the markdown table (the report is
+ * embedded in a PR body — a stray pipe from an odd JSON key must not corrupt it). */
+function cell(text) {
+    return text.replace(/\|/g, "\\|");
+}
+function sampleRow(s) {
+    const detail = s.failureClass !== null
+        ? `replay failed (${s.failureClass})`
+        : s.firstDivergentPath !== null
+            ? `first differs at \`${cell(s.firstDivergentPath)}\``
+            : cell(s.detail);
+    return `| ${s.index} | ${s.verdict} | ${cell(s.servedModel ?? "—")} | $${s.costUsd.toFixed(4)} | ${detail} |`;
+}
+function renderReportMarkdown(report) {
+    const lines = [];
+    lines.push("## Shadow-equivalence verification");
+    lines.push("");
+    lines.push(headline(report));
+    lines.push("");
+    lines.push(`- **Call site:** \`${report.callSiteId}\``);
+    lines.push(`- **Route:** \`${report.route}@${report.routeVersion}\``);
+    lines.push(`- **Pinned model:** \`${report.pinnedModel}\` (original == replacement)`);
+    lines.push(`- **Ran at:** ${report.ranAt}`);
+    lines.push(`- **Tally:** ${report.counts.equivalent} equivalent · ` +
+        `${report.counts.equivalentModulo} modulo-nondeterminism · ${report.counts.divergent} divergent`);
+    lines.push("");
+    lines.push(`> ${report.guarantee}`);
+    lines.push("");
+    if (report.samples.length > 0) {
+        lines.push("| # | verdict | served model | cost | detail |");
+        lines.push("|---|---------|--------------|------|--------|");
+        for (const s of report.samples)
+            lines.push(sampleRow(s));
+        lines.push("");
+    }
+    if (report.refusals.length > 0) {
+        lines.push("### Refusals (honest, not failures)");
+        lines.push("");
+        for (const r of report.refusals)
+            lines.push(`- **${r.reason}** — ${r.detail}`);
+        lines.push("");
+        lines.push("Refused call sites are T0/T1 territory (gateway-pointing or instrumentation), " +
+            "not same-model call replacement — this is a correct outcome, not a gap.");
+        lines.push("");
+    }
+    lines.push(report.overall === "divergent"
+        ? "**Rollback is git-native:** revert this PR to restore the original call byte-for-byte."
+        : report.overall === "refused"
+            ? "No change is proposed for this call site."
+            : "Safe to merge on this evidence: the routed replacement preserves behavior. " +
+                "Rollback stays git-native (revert this PR) — same-model means it is also a route-YAML flip.");
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/verify/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Shadow-equivalence verifier contracts (Expansion §9, autonomy-ladder Tier 2).
+ *
+ * The verifier proves a SAME-MODEL call replacement is behavior-preserving
+ * BEFORE a human merges the Tier-2 PR: capture N invocations of the original
+ * call site's inputs/outputs locally, replay the SAME inputs through the
+ * ModelRig-routed replacement (same provider/model PINNED — this verifies the
+ * PLUMBING, never the model choice), diff the outputs, and emit a report the
+ * skill embeds in the PR.
+ *
+ * Honest refusal is a first-class output: a call site that can't be captured
+ * or replayed (streaming, dynamically-assembled prompts, or a route that does
+ * not pin the original model) is REFUSED, not forced — those sites are T0/T1
+ * territory per the spec's stated limits.
+ */
+import type { CandidateSpec } from "../types/route";
+/** One recorded original invocation: the extracted template variables that
+ * reconstruct the original prompt through the drafted route, and the original
+ * call's raw output text. */
+export interface ShadowCapture {
+    /** The extracted template variables (Tier-2 turns a prompt into
+     * `systemTemplate` + variables); replayed through the route unchanged. */
+    readonly input: Record<string, unknown>;
+    /** The original call site's raw output text, verbatim. */
+    readonly output: string;
+}
+/** A call site (or a single input) that could NOT be captured/replayed.
+ * Refusing IS a correct output — these are T0/T1 territory, never a failure. */
+export interface CaptureRefusal {
+    readonly reason: "streaming" | "dynamic-prompt" | "uncapturable";
+    readonly detail: string;
+}
+/** The portable capture fixture the skill writes and the verifier reads. Stays
+ * local (SQLite/JSON in the SDK process) — nothing here uploads. */
+export interface ShadowCaptureFixture {
+    /** Where the original call lives, e.g. "src/pipeline/summarize.ts:42". */
+    readonly callSiteId: string;
+    /** The provider+model of the ORIGINAL call — the route MUST pin exactly this
+     * (same-model replacement; the verifier refuses otherwise). */
+    readonly original: CandidateSpec;
+    readonly capturedAt: string;
+    readonly samples: readonly ShadowCapture[];
+    /** Inputs/sites the capture step honestly declined (streaming, dynamic). */
+    readonly refusals?: readonly CaptureRefusal[];
+    /** JSON-pointer paths (exact, or subtree prefixes) whose value is allowed to
+     * differ without counting as a divergence — the migration's declared
+     * free-text / nondeterministic fields (e.g. "/summary"). Absent = every
+     * field must match (the conservative default). */
+    readonly nondeterministicPaths?: readonly string[];
+}
+/** Per-sample verdict — the honest three-way vocabulary. */
+export type SampleVerdict = "equivalent" | "equivalent-modulo-nondeterminism" | "divergent";
+/** Whole-run verdict: the per-sample vocabulary plus `refused` (the run never
+ * ran — pin violation, or nothing capturable). */
+export type EquivalenceVerdict = SampleVerdict | "refused";
+/** The result of diffing one original/routed output pair. */
+export interface SampleDiff {
+    readonly verdict: SampleVerdict;
+    /** First differing structured field (JSON-pointer) when divergent on
+     * structured output; null when equivalent, modulo, or divergent for a
+     * non-field reason (bad JSON, plumbing failure, model mismatch). */
+    readonly firstDivergentPath: string | null;
+    readonly detail: string;
+}
+export interface SampleReport extends SampleDiff {
+    readonly index: number;
+    /** "provider/model" that actually served the replay — null when the replay
+     * itself failed before any model served. */
+    readonly servedModel: string | null;
+    readonly costUsd: number;
+    /** Set when the routed replay threw a typed failure (the plumbing could not
+     * produce a conformant output for this input) — itself a divergence. */
+    readonly failureClass: string | null;
+}
+export interface EquivalenceReport {
+    readonly schemaVersion: 1;
+    readonly kind: "shadow-equivalence";
+    readonly callSiteId: string;
+    readonly route: string;
+    readonly routeVersion: number;
+    /** "provider/model" the route pins — equal to the original by construction
+     * (the verifier refuses when it isn't). */
+    readonly pinnedModel: string;
+    readonly ranAt: string;
+    readonly n: number;
+    readonly overall: EquivalenceVerdict;
+    readonly counts: {
+        readonly equivalent: number;
+        readonly equivalentModulo: number;
+        readonly divergent: number;
+    };
+    readonly samples: readonly SampleReport[];
+    /** Capture-time refusals, surfaced verbatim (never a silent subset). */
+    readonly refusals: readonly CaptureRefusal[];
+    /** Set when `overall === "refused"` — why the run never ran. */
+    readonly refusalReason: string | null;
+    /** The plumbing-not-model-choice statement, embedded in the report so a PR
+     * reader cannot mistake equivalence for a model-quality claim. */
+    readonly guarantee: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/verify/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/verify/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;6BAE6B;AAC7B,MAAM,WAAW,aAAa;IAC5B;8EAC0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;gFACgF;AAChF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,gBAAgB,GAAG,cAAc,CAAC;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;oEACoE;AACpE,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;mEAC+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC9C;;;sDAGkD;IAClD,QAAQ,CAAC,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpD;AAED,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GACrB,YAAY,GACZ,kCAAkC,GAClC,WAAW,CAAC;AAEhB;kDACkD;AAClD,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,SAAS,CAAC;AAE3D,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC;;wEAEoE;IACpE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;gDAC4C;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;4EACwE;IACxE,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;+CAC2C;IAC3C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,gEAAgE;IAChE,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC;sEACkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}

package/dist/verify/types.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Shadow-equivalence verifier contracts (Expansion §9, autonomy-ladder Tier 2).
+ *
+ * The verifier proves a SAME-MODEL call replacement is behavior-preserving
+ * BEFORE a human merges the Tier-2 PR: capture N invocations of the original
+ * call site's inputs/outputs locally, replay the SAME inputs through the
+ * ModelRig-routed replacement (same provider/model PINNED — this verifies the
+ * PLUMBING, never the model choice), diff the outputs, and emit a report the
+ * skill embeds in the PR.
+ *
+ * Honest refusal is a first-class output: a call site that can't be captured
+ * or replayed (streaming, dynamically-assembled prompts, or a route that does
+ * not pin the original model) is REFUSED, not forced — those sites are T0/T1
+ * territory per the spec's stated limits.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/verify/verify.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shadow-equivalence orchestrator (Expansion §9, Tier 2) — the replay-and-diff
+ * pass that proves a same-model call replacement is behavior-preserving before
+ * a human merges the Tier-2 PR.
+ *
+ * Reuse, not twin (dev-rule S1): the EXECUTOR is the run loop — the same
+ * verified pipeline `rig.run()` drives — and the replay POSTURE is the
+ * bake-off's (`bakeoff/replay.ts`): captures severed (no capture-of-verify),
+ * one hard envelope across the pass, per-sample cost reconstructed from the
+ * tagged telemetry rows. What differs, and why this is a sibling of
+ * `replayVariant` rather than a call into it: shadow-equivalence pins a
+ * SPECIFIC captured input (not "last N by route"), needs the routed OUTPUT for
+ * a pairwise diff (not an aggregate metric), and asserts the served model
+ * equals the pinned original (a plumbing check variant comparison never makes).
+ */
+import type { RunDeps } from "../run/run";
+import type { EquivalenceReport, ShadowCaptureFixture } from "./types";
+export interface VerifySwapRequest {
+    /** The drafted replacement route (must pin the original model — see below). */
+    readonly route: string;
+    /** The local capture fixture (original inputs/outputs). Never uploaded. */
+    readonly fixture: ShadowCaptureFixture;
+    /** Hard cap for the whole replay pass (default $10). */
+    readonly envelopeUsd?: number;
+    /** Injectable clock for a deterministic `ranAt` (tests). */
+    readonly now?: () => string;
+}
+export declare function verifySwap(deps: RunDeps, req: VerifySwapRequest): Promise<EquivalenceReport>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/verify/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAK1C,OAAO,KAAK,EACV,iBAAiB,EAIjB,oBAAoB,EACrB,MAAM,SAAS,CAAC;AAWjB,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,wDAAwD;IACxD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAiCD,wBAAsB,UAAU,CAC9B,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,iBAAiB,CAAC,CAsH5B"}

package/dist/verify/verify.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * Shadow-equivalence orchestrator (Expansion §9, Tier 2) — the replay-and-diff
+ * pass that proves a same-model call replacement is behavior-preserving before
+ * a human merges the Tier-2 PR.
+ *
+ * Reuse, not twin (dev-rule S1): the EXECUTOR is the run loop — the same
+ * verified pipeline `rig.run()` drives — and the replay POSTURE is the
+ * bake-off's (`bakeoff/replay.ts`): captures severed (no capture-of-verify),
+ * one hard envelope across the pass, per-sample cost reconstructed from the
+ * tagged telemetry rows. What differs, and why this is a sibling of
+ * `replayVariant` rather than a call into it: shadow-equivalence pins a
+ * SPECIFIC captured input (not "last N by route"), needs the routed OUTPUT for
+ * a pairwise diff (not an aggregate metric), and asserts the served model
+ * equals the pinned original (a plumbing check variant comparison never makes).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifySwap = verifySwap;
+const run_1 = require("../run/run");
+const failures_1 = require("../types/failures");
+const diff_1 = require("./diff");
+/** One hard envelope for the whole verification pass when the caller sets none
+ * — replay is real, billed dispatch and must stay bounded (spec §9). */
+const DEFAULT_VERIFY_ENVELOPE_USD = 10;
+const GUARANTEE = "Same provider/model pinned on both sides: this verifies the PLUMBING of the " +
+    "ModelRig-routed replacement, never the model choice. Model optimization is a " +
+    "separate, human-gated bake-off decision.";
+function candidateEquals(a, b) {
+    return a.provider === b.provider && a.model === b.model;
+}
+/** Build a refused report — the run never ran (pin violation, or nothing to
+ * replay). Refusing IS a correct output; it costs nothing. */
+function refused(req, routeVersion, pinnedModel, reason, nowIso) {
+    return {
+        schemaVersion: 1,
+        kind: "shadow-equivalence",
+        callSiteId: req.fixture.callSiteId,
+        route: req.route,
+        routeVersion,
+        pinnedModel,
+        ranAt: nowIso,
+        n: 0,
+        overall: "refused",
+        counts: { equivalent: 0, equivalentModulo: 0, divergent: 0 },
+        samples: [],
+        refusals: req.fixture.refusals ?? [],
+        refusalReason: reason,
+        guarantee: GUARANTEE,
+    };
+}
+async function verifySwap(deps, req) {
+    const nowIso = (req.now ?? (() => new Date().toISOString()))();
+    const bundle = deps.routes.get(req.route);
+    const original = req.fixture.original;
+    const pinnedModel = `${original.provider}/${original.model}`;
+    // Same-model pin (the C2-exit gateway-substitution ruling): the route must
+    // pin EXACTLY the original model and nothing else. A route that offers other
+    // candidates would introduce model choice — which is not what this verifies.
+    const pins = bundle.candidates.length > 0 &&
+        bundle.candidates.every((c) => candidateEquals(c, original));
+    if (!pins) {
+        const declared = bundle.candidates.map((c) => `${c.provider}/${c.model}`).join(", ") || "none";
+        return refused(req, bundle.version, pinnedModel, `route "${req.route}" declares candidates [${declared}]; shadow-equivalence requires it to ` +
+            `pin exactly the original model ${pinnedModel} — this verifies plumbing, not model choice. ` +
+            "A multi-model route is a bake-off, not a Tier-2 replacement.", nowIso);
+    }
+    if (req.fixture.samples.length === 0) {
+        const hadRefusals = (req.fixture.refusals ?? []).length > 0;
+        return refused(req, bundle.version, pinnedModel, hadRefusals
+            ? "no replayable captures — every invocation was honestly refused (streaming / dynamic prompt); " +
+                "this call site is T0/T1 territory, not a Tier-2 replacement"
+            : "no captures to replay — capture N original invocations first", nowIso);
+    }
+    // Replay posture: sever captures (no capture-of-verify) and share one hard
+    // envelope, exactly as bakeoff/replay.ts does.
+    const envelopeUsd = req.envelopeUsd ?? DEFAULT_VERIFY_ENVELOPE_USD;
+    const replayDeps = { ...deps, captures: null, envelopeBudgetUsd: envelopeUsd };
+    const envelopeKey = `verify:${req.route}:${nowIso}`;
+    const nd = req.fixture.nondeterministicPaths ?? [];
+    const samples = [];
+    for (let index = 0; index < req.fixture.samples.length; index += 1) {
+        const capture = req.fixture.samples[index];
+        const sampleTag = `${envelopeKey}#${index}`;
+        let servedModel = null;
+        let failureClass = null;
+        let diff = { verdict: "divergent", firstDivergentPath: null, detail: "" };
+        try {
+            const result = await (0, run_1.run)(replayDeps, req.route, {
+                input: capture.input,
+                tags: { shadow_verify: envelopeKey, shadow_verify_sample: sampleTag },
+                budget: { envelope: envelopeKey, budgetUsd: envelopeUsd },
+            });
+            servedModel = `${result.meta.provider}/${result.meta.model}`;
+            if (servedModel !== pinnedModel) {
+                // A declared candidate served something other than the original — the
+                // plumbing does not preserve the model. Divergent, not equivalent.
+                diff = {
+                    verdict: "divergent",
+                    firstDivergentPath: null,
+                    detail: `routed run served ${servedModel}, not the pinned original ${pinnedModel} — a fallback fired`,
+                };
+            }
+            else {
+                const routedText = JSON.stringify(result.output);
+                diff = (0, diff_1.diffOutputs)(capture.output, result.output, routedText, nd);
+            }
+        }
+        catch (err) {
+            if (!(err instanceof failures_1.RigFailureError))
+                throw err;
+            failureClass = err.failure.class;
+            diff = {
+                verdict: "divergent",
+                firstDivergentPath: null,
+                detail: `routed replacement did not return a conformant output (${err.failure.class}): ` +
+                    `${err.failure.message} — the plumbing regressed for this input`,
+            };
+        }
+        // Per-sample cost from the tagged rows — base + retries + repair, exactly
+        // what telemetry billed (the bake-off's F1-correct accounting).
+        const costUsd = deps.telemetry
+            .queryByTag("shadow_verify_sample", sampleTag)
+            .reduce((a, r) => a + r.costEstimateUsd, 0);
+        samples.push({ index, ...diff, servedModel, costUsd, failureClass });
+    }
+    const counts = {
+        equivalent: samples.filter((s) => s.verdict === "equivalent").length,
+        equivalentModulo: samples.filter((s) => s.verdict === "equivalent-modulo-nondeterminism").length,
+        divergent: samples.filter((s) => s.verdict === "divergent").length,
+    };
+    const overall = counts.divergent > 0 ? "divergent" : counts.equivalentModulo > 0 ? "equivalent-modulo-nondeterminism" : "equivalent";
+    return {
+        schemaVersion: 1,
+        kind: "shadow-equivalence",
+        callSiteId: req.fixture.callSiteId,
+        route: req.route,
+        routeVersion: bundle.version,
+        pinnedModel,
+        ranAt: nowIso,
+        n: samples.length,
+        overall,
+        counts,
+        samples,
+        refusals: req.fixture.refusals ?? [],
+        refusalReason: null,
+        guarantee: GUARANTEE,
+    };
+}