modelrig 0.7.0 → 0.8.1

package/dist/mask/policy.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CS-1 — policy loading & validation (WIRED 2026-08-24, CS-1 Chunk A). Spec §3.
+ *
+ * Runs at ROUTE LOAD (same place `require:` is validated), synchronously — the
+ * route loader is sync (`readFileSync`), so the dictionary read and the hash are
+ * too. An unreadable dictionary or an unknown type is a LOAD error, never a
+ * runtime surprise (spec §3, §9).
+ *
+ * NOTE (P2 — builder flags a scaffold signature change): the architect scaffold
+ * typed `resolveMaskPolicy` as `Promise<ResolvedMaskPolicy>`; it is implemented
+ * SYNC to match the synchronous route loader. Flagged in the PR.
+ */
+import type { MaskDictionaryEntry, MaskPolicy, ResolvedMaskPolicy } from "./types";
+/**
+ * Validate the raw YAML `mask:` block shape before resolution (used by the route
+ * loader and by `modelrig validate`). Returns teaching-style problem strings
+ * (CE-2 fixHint pattern) — EMPTY means the shape is valid. Never throws.
+ */
+export declare function validateMaskPolicyShape(raw: unknown): readonly string[];
+/** Parse a validated raw block into a typed {@link MaskPolicy}. Assumes
+ * {@link validateMaskPolicyShape} already passed (caller checks first). */
+export declare function parseMaskPolicy(raw: Record<string, unknown>): MaskPolicy;
+/** Parse dictionary bytes (YAML or JSON, a `term: type` map) into typed entries.
+ * A term maps to a bare type string, or to `{ type, "case-sensitive"?: bool }`.
+ * Returns [entries, problems]; a malformed dictionary is a load error. */
+export declare function parseDictionary(bytes: string): {
+    entries: MaskDictionaryEntry[];
+    problems: string[];
+};
+/**
+ * Load + validate the `mask:` block and resolve its dictionary. Reads the
+ * dictionary relative to the routes dir, validates entry shapes, and computes
+ * `policyHash` as sha256 over the canonical policy JSON + the RAW dictionary
+ * bytes (never the entries). Throws a load error (teaching message) on an
+ * unreadable dictionary or a malformed entry — validation, not a runtime surprise.
+ */
+export declare function resolveMaskPolicy(policy: MaskPolicy, routesDir: string): ResolvedMaskPolicy;
+//# sourceMappingURL=policy.d.ts.map

package/dist/mask/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/mask/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAUnF;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAiDvE;AAED;2EAC2E;AAC3E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAexE;AAED;;0EAE0E;AAC1E,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CA+BrG;AAgBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,kBAAkB,CAyB3F"}

package/dist/mask/policy.js

@@ -0,0 +1,187 @@
+"use strict";
+/**
+ * CS-1 — policy loading & validation (WIRED 2026-08-24, CS-1 Chunk A). Spec §3.
+ *
+ * Runs at ROUTE LOAD (same place `require:` is validated), synchronously — the
+ * route loader is sync (`readFileSync`), so the dictionary read and the hash are
+ * too. An unreadable dictionary or an unknown type is a LOAD error, never a
+ * runtime surprise (spec §3, §9).
+ *
+ * NOTE (P2 — builder flags a scaffold signature change): the architect scaffold
+ * typed `resolveMaskPolicy` as `Promise<ResolvedMaskPolicy>`; it is implemented
+ * SYNC to match the synchronous route loader. Flagged in the PR.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateMaskPolicyShape = validateMaskPolicyShape;
+exports.parseMaskPolicy = parseMaskPolicy;
+exports.parseDictionary = parseDictionary;
+exports.resolveMaskPolicy = resolveMaskPolicy;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const yaml_1 = require("yaml");
+const SCRUB_TYPES = new Set(["ssn", "pan", "email", "phone", "mrn"]);
+const MODES = new Set(["off", "detect", "mask", "block"]);
+const STREAM_MODES = new Set(["buffered", "final-only"]);
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Validate the raw YAML `mask:` block shape before resolution (used by the route
+ * loader and by `modelrig validate`). Returns teaching-style problem strings
+ * (CE-2 fixHint pattern) — EMPTY means the shape is valid. Never throws.
+ */
+function validateMaskPolicyShape(raw) {
+    const problems = [];
+    if (!isRecord(raw)) {
+        problems.push('mask must be a block with at least a `mode` (off|detect|mask|block)');
+        return problems;
+    }
+    if (raw.mode !== undefined && (typeof raw.mode !== "string" || !MODES.has(raw.mode))) {
+        problems.push('mask.mode must be one of off | detect | mask | block');
+    }
+    if (raw.types !== undefined) {
+        if (!Array.isArray(raw.types)) {
+            problems.push("mask.types must be a list of deterministic detector types (ssn, pan, email, phone, mrn)");
+        }
+        else {
+            for (const t of raw.types) {
+                if (typeof t !== "string" || !SCRUB_TYPES.has(t)) {
+                    problems.push(`mask.types entry "${String(t)}" is not a known detector — allowed: ssn, pan, email, phone, mrn`);
+                }
+            }
+        }
+    }
+    if (raw.dictionary !== undefined && typeof raw.dictionary !== "string") {
+        problems.push("mask.dictionary must be a local file path (string) relative to the routes dir");
+    }
+    if (raw.fields !== undefined) {
+        if (!Array.isArray(raw.fields)) {
+            problems.push("mask.fields must be a list of { path, type } rules");
+        }
+        else {
+            for (const f of raw.fields) {
+                if (!isRecord(f) || typeof f.path !== "string" || typeof f.type !== "string") {
+                    problems.push('mask.fields entries must be { path: "/json/pointer", type: "person" }');
+                }
+                else if (!f.path.startsWith("/")) {
+                    problems.push(`mask.fields path "${f.path}" must be a JSON pointer starting with "/"`);
+                }
+            }
+        }
+    }
+    if (raw.rehydrate !== undefined && typeof raw.rehydrate !== "boolean") {
+        problems.push("mask.rehydrate must be a boolean (default true when mode=mask)");
+    }
+    if (raw.stream !== undefined && (typeof raw.stream !== "string" || !STREAM_MODES.has(raw.stream))) {
+        problems.push("mask.stream must be buffered | final-only");
+    }
+    if (raw.tolerance !== undefined) {
+        const tol = raw.tolerance;
+        if (!isRecord(tol) || typeof tol.value_accuracy_delta_max !== "number" || typeof tol.conformance_delta_max !== "number") {
+            problems.push("mask.tolerance must be { value_accuracy_delta_max: number, conformance_delta_max: number }");
+        }
+    }
+    return problems;
+}
+/** Parse a validated raw block into a typed {@link MaskPolicy}. Assumes
+ * {@link validateMaskPolicyShape} already passed (caller checks first). */
+function parseMaskPolicy(raw) {
+    const rawFields = Array.isArray(raw.fields) ? raw.fields : [];
+    return {
+        mode: raw.mode ?? "off",
+        types: Array.isArray(raw.types) ? raw.types : [],
+        ...(typeof raw.dictionary === "string" ? { dictionary: raw.dictionary } : {}),
+        ...(rawFields.length > 0
+            ? { fields: rawFields.map((f) => ({ path: f.path, type: f.type })) }
+            : {}),
+        ...(typeof raw.rehydrate === "boolean" ? { rehydrate: raw.rehydrate } : {}),
+        ...(typeof raw.stream === "string" ? { stream: raw.stream } : {}),
+        ...(isRecord(raw.tolerance)
+            ? { tolerance: { value_accuracy_delta_max: raw.tolerance.value_accuracy_delta_max, conformance_delta_max: raw.tolerance.conformance_delta_max } }
+            : {}),
+    };
+}
+/** Parse dictionary bytes (YAML or JSON, a `term: type` map) into typed entries.
+ * A term maps to a bare type string, or to `{ type, "case-sensitive"?: bool }`.
+ * Returns [entries, problems]; a malformed dictionary is a load error. */
+function parseDictionary(bytes) {
+    const problems = [];
+    let doc;
+    try {
+        doc = (0, yaml_1.parse)(bytes); // YAML is a JSON superset — one parser covers both.
+    }
+    catch (err) {
+        return { entries: [], problems: [`dictionary is not valid YAML/JSON: ${err instanceof Error ? err.message : String(err)}`] };
+    }
+    if (!isRecord(doc)) {
+        return { entries: [], problems: ["dictionary must be a map of term → type"] };
+    }
+    const entries = [];
+    for (const [term, spec] of Object.entries(doc)) {
+        if (term === "") {
+            problems.push("dictionary has an empty term");
+            continue;
+        }
+        if (typeof spec === "string") {
+            entries.push({ term, type: spec });
+        }
+        else if (isRecord(spec) && typeof spec.type === "string") {
+            const caseSensitive = spec["case-sensitive"];
+            entries.push({
+                term,
+                type: spec.type,
+                ...(caseSensitive === true ? { caseSensitive: true } : {}),
+            });
+        }
+        else {
+            problems.push(`dictionary term "${term}" must map to a type string or { type, case-sensitive? }`);
+        }
+    }
+    return { entries, problems };
+}
+/** Canonical JSON of a policy for hashing — keys sorted, dictionary PATH excluded
+ * (the dictionary contributes via its bytes, not its location). */
+function canonicalPolicy(policy) {
+    const norm = {
+        mode: policy.mode,
+        types: [...policy.types].sort(),
+        fields: (policy.fields ?? []).map((f) => ({ path: f.path, type: f.type })),
+        rehydrate: policy.rehydrate ?? (policy.mode === "mask"),
+        stream: policy.stream ?? "buffered",
+        tolerance: policy.tolerance ?? null,
+    };
+    return JSON.stringify(norm);
+}
+/**
+ * Load + validate the `mask:` block and resolve its dictionary. Reads the
+ * dictionary relative to the routes dir, validates entry shapes, and computes
+ * `policyHash` as sha256 over the canonical policy JSON + the RAW dictionary
+ * bytes (never the entries). Throws a load error (teaching message) on an
+ * unreadable dictionary or a malformed entry — validation, not a runtime surprise.
+ */
+function resolveMaskPolicy(policy, routesDir) {
+    let entries = [];
+    let dictionaryBytes = "";
+    if (policy.dictionary !== undefined && policy.dictionary !== "") {
+        const path = (0, node_path_1.isAbsolute)(policy.dictionary) ? policy.dictionary : (0, node_path_1.resolve)(routesDir, policy.dictionary);
+        try {
+            dictionaryBytes = (0, node_fs_1.readFileSync)(path, "utf8");
+        }
+        catch (err) {
+            throw new Error(`[modelrig mask] cannot read dictionary "${policy.dictionary}" (resolved: ${path}): ` +
+                `${err instanceof Error ? err.message : String(err)}. The dictionary is a LOCAL file (never uploaded) — check the path is relative to the routes dir.`);
+        }
+        const parsed = parseDictionary(dictionaryBytes);
+        if (parsed.problems.length > 0) {
+            throw new Error(`[modelrig mask] dictionary "${policy.dictionary}" is invalid:\n  - ${parsed.problems.join("\n  - ")}`);
+        }
+        entries = parsed.entries;
+    }
+    const policyHash = (0, node_crypto_1.createHash)("sha256")
+        .update(canonicalPolicy(policy))
+        .update("")
+        .update(dictionaryBytes)
+        .digest("hex");
+    return { policy, entries, policyHash };
+}

package/dist/mask/proof.d.ts

@@ -0,0 +1,54 @@
+/**
+ * CS-1 — the masked-arm proof (WIRED 2026-08-24, CS-1 Chunk A). Spec §7.
+ *
+ * "The proof is the artifact." For a corpus of route inputs, run the task's
+ * outgoing content through the mask path and then re-run the shared Detector
+ * over the MASKED content: a masked arm that leaks nothing has ZERO detected
+ * spans remaining (the tokens `<TYPE_n>` match no PII pattern and no dictionary
+ * term). The unmasked arm's detections are reported alongside as the Δ the mask
+ * removed — counts by type, never values.
+ *
+ * This lives in `src/mask/**` (CS-1 A's fence) and rides the bake-off matrix
+ * ADDITIVELY: {@link MaskArmProof} is attachable to a bake-off evidence jsonb as
+ * an optional field without restructuring RB-1's engine (see
+ * verification-cs1a.md). The Chunk-B masked-vs-unmasked bake-off arm (Δ
+ * value-accuracy through the RB-1 replay engine) extends this; Chunk A proves the
+ * load-bearing property: no detected span leaves.
+ */
+import type { MaskFinding, ResolvedMaskPolicy } from "./types";
+export interface MaskArmProof {
+    readonly policyHash: string;
+    readonly samples: number;
+    /** Detected spans in the UNMASKED arm, by type (what would have left). */
+    readonly unmaskedDetections: readonly MaskFinding[];
+    /** Detected spans REMAINING in the masked arm, by type. The proof: empty. */
+    readonly maskedLeaks: readonly MaskFinding[];
+    /** True iff the masked arm leaked no detected span across the whole corpus. */
+    readonly proven: boolean;
+    /** Distinct tokens the mask arm introduced across the corpus. */
+    readonly tokensIssued: number;
+}
+/**
+ * Prove that masking the corpus leaves no detected span in the masked arm.
+ * Each sample masks with a FRESH vault (the proof is about leakage, not
+ * cross-sample token stability), then re-detects over the masked text. Pure and
+ * deterministic; NEVER records a matched value.
+ */
+export declare function proveMaskedArm(corpus: readonly string[], resolved: ResolvedMaskPolicy): MaskArmProof;
+/** Collect every string leaf of a JSON value (a capture's replayed input) into
+ * `out` — the corpus the masked-arm proof runs over. Never records structure,
+ * only the leaf strings that would render into an outgoing request. */
+export declare function collectStringLeaves(value: unknown, out?: string[]): string[];
+/**
+ * Prove the masked arm over a bake-off's REPLAY captures (spec §7): extract each
+ * capture's input string leaves and prove masking leaves no detected span. The
+ * result attaches to `BakeoffArtifact.maskArm` (additive; rides the matrix
+ * jsonb). A malformed capture is skipped, never thrown on.
+ */
+export declare function proveMaskArmFromCaptures(captures: readonly {
+    readonly variablesJson: string;
+}[], policy: ResolvedMaskPolicy): MaskArmProof;
+/** Render a masked-arm proof as a Markdown block for the verification doc / a
+ * bake-off PR body. Counts only — the two arms and the leak assertion. */
+export declare function formatMaskArmReport(proof: MaskArmProof): string;
+//# sourceMappingURL=proof.d.ts.map

package/dist/mask/proof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof.d.ts","sourceRoot":"","sources":["../../src/mask/proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAG/D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,kBAAkB,EAAE,SAAS,WAAW,EAAE,CAAC;IACpD,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,SAAS,WAAW,EAAE,CAAC;IAC7C,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AASD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,kBAAkB,GAAG,YAAY,CA6BpG;AAED;;uEAEuE;AACvE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAKhF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS;IAAE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EAAE,EACvD,MAAM,EAAE,kBAAkB,GACzB,YAAY,CAWd;AAED;0EAC0E;AAC1E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAkB/D"}

package/dist/mask/proof.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * CS-1 — the masked-arm proof (WIRED 2026-08-24, CS-1 Chunk A). Spec §7.
+ *
+ * "The proof is the artifact." For a corpus of route inputs, run the task's
+ * outgoing content through the mask path and then re-run the shared Detector
+ * over the MASKED content: a masked arm that leaks nothing has ZERO detected
+ * spans remaining (the tokens `<TYPE_n>` match no PII pattern and no dictionary
+ * term). The unmasked arm's detections are reported alongside as the Δ the mask
+ * removed — counts by type, never values.
+ *
+ * This lives in `src/mask/**` (CS-1 A's fence) and rides the bake-off matrix
+ * ADDITIVELY: {@link MaskArmProof} is attachable to a bake-off evidence jsonb as
+ * an optional field without restructuring RB-1's engine (see
+ * verification-cs1a.md). The Chunk-B masked-vs-unmasked bake-off arm (Δ
+ * value-accuracy through the RB-1 replay engine) extends this; Chunk A proves the
+ * load-bearing property: no detected span leaves.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.proveMaskedArm = proveMaskedArm;
+exports.collectStringLeaves = collectStringLeaves;
+exports.proveMaskArmFromCaptures = proveMaskArmFromCaptures;
+exports.formatMaskArmReport = formatMaskArmReport;
+const detect_1 = require("./detect");
+const apply_1 = require("./apply");
+const vault_1 = require("./vault");
+function toFindings(counts) {
+    return [...counts.entries()]
+        .filter(([, c]) => c > 0)
+        .map(([type, count]) => ({ type, count }))
+        .sort((a, b) => (a.type < b.type ? -1 : a.type > b.type ? 1 : 0));
+}
+/**
+ * Prove that masking the corpus leaves no detected span in the masked arm.
+ * Each sample masks with a FRESH vault (the proof is about leakage, not
+ * cross-sample token stability), then re-detects over the masked text. Pure and
+ * deterministic; NEVER records a matched value.
+ */
+function proveMaskedArm(corpus, resolved) {
+    const unmasked = new Map();
+    const leaks = new Map();
+    let tokensIssued = 0;
+    for (const text of corpus) {
+        // Unmasked arm: what the Detector finds in the original content.
+        for (const span of (0, detect_1.detectSpans)(text, resolved)) {
+            unmasked.set(span.type, (unmasked.get(span.type) ?? 0) + 1);
+        }
+        // Masked arm: mask, then re-detect. A leak is any span the Detector still
+        // finds in the masked content.
+        const vault = (0, vault_1.createRunVault)();
+        const masked = (0, apply_1.maskText)(text, resolved, vault);
+        tokensIssued += masked.tokensIssued;
+        for (const span of (0, detect_1.detectSpans)(masked.text, resolved)) {
+            leaks.set(span.type, (leaks.get(span.type) ?? 0) + 1);
+        }
+    }
+    const maskedLeaks = toFindings(leaks);
+    return {
+        policyHash: resolved.policyHash,
+        samples: corpus.length,
+        unmaskedDetections: toFindings(unmasked),
+        maskedLeaks,
+        proven: maskedLeaks.length === 0,
+        tokensIssued,
+    };
+}
+/** Collect every string leaf of a JSON value (a capture's replayed input) into
+ * `out` — the corpus the masked-arm proof runs over. Never records structure,
+ * only the leaf strings that would render into an outgoing request. */
+function collectStringLeaves(value, out = []) {
+    if (typeof value === "string")
+        out.push(value);
+    else if (Array.isArray(value))
+        for (const v of value)
+            collectStringLeaves(v, out);
+    else if (value !== null && typeof value === "object")
+        for (const v of Object.values(value))
+            collectStringLeaves(v, out);
+    return out;
+}
+/**
+ * Prove the masked arm over a bake-off's REPLAY captures (spec §7): extract each
+ * capture's input string leaves and prove masking leaves no detected span. The
+ * result attaches to `BakeoffArtifact.maskArm` (additive; rides the matrix
+ * jsonb). A malformed capture is skipped, never thrown on.
+ */
+function proveMaskArmFromCaptures(captures, policy) {
+    const corpus = [];
+    for (const c of captures) {
+        try {
+            collectStringLeaves(JSON.parse(c.variablesJson), corpus);
+        }
+        catch {
+            // A capture that does not parse contributes nothing — the proof still
+            // holds over the rest (counts reflect only well-formed replays).
+        }
+    }
+    return proveMaskedArm(corpus, policy);
+}
+/** Render a masked-arm proof as a Markdown block for the verification doc / a
+ * bake-off PR body. Counts only — the two arms and the leak assertion. */
+function formatMaskArmReport(proof) {
+    const lines = [];
+    lines.push(`### Masked-arm proof — policy \`${proof.policyHash.slice(0, 12)}…\``);
+    lines.push("");
+    lines.push(`- samples: **${proof.samples}**`);
+    lines.push(`- tokens issued (masked arm): **${proof.tokensIssued}**`);
+    lines.push(`- masked-arm leaks: **${proof.maskedLeaks.length === 0 ? "0 (PROVEN)" : "NON-ZERO — FAIL"}**`);
+    lines.push("");
+    lines.push("| type | detected (unmasked) | leaked (masked) |");
+    lines.push("|---|---|---|");
+    const leakByType = new Map(proof.maskedLeaks.map((f) => [f.type, f.count]));
+    if (proof.unmaskedDetections.length === 0) {
+        lines.push("| _(none detected)_ | 0 | 0 |");
+    }
+    for (const f of proof.unmaskedDetections) {
+        lines.push(`| ${f.type} | ${f.count} | ${leakByType.get(f.type) ?? 0} |`);
+    }
+    return lines.join("\n");
+}

package/dist/mask/receipt.d.ts

@@ -0,0 +1,30 @@
+/**
+ * CS-1 — receipt (WIRED 2026-08-24, CS-1 Chunk A). Spec §6.
+ *
+ * The ONLY producer of `MaskReceipt` (same single-producer discipline as
+ * `summarizeScrub` in src/artifacts/scrub.ts) so the counts-not-values invariant
+ * lives in one place. Inputs are already counts; this function never receives a
+ * matched value or a vault — its parameter type makes that structural.
+ */
+import type { MaskFinding, MaskMode, MaskReceipt, MaskStreamMode } from "./types";
+export interface MaskOutcome {
+    readonly policyHash: string;
+    readonly mode: MaskMode;
+    readonly blocked: boolean;
+    readonly findings: ReadonlyMap<string, number>;
+    readonly tokensIssued: number;
+    readonly rehydrated: number;
+    readonly unresolved: number;
+    readonly stream: MaskStreamMode | null;
+    readonly toolCallsUnmasked?: number;
+    readonly error?: boolean;
+}
+/** Build the persisted {@link MaskReceipt} from a completed mask outcome. Sorts
+ * findings by type; omits optional fields when absent so the wire/jsonb payload
+ * is minimal and stable. */
+export declare function summarizeMask(outcome: MaskOutcome): MaskReceipt;
+/** Run rollup (derived, never stored — spec §6): sum findings by type across a
+ * run's step receipts. Sorted by type. The server read route and the console
+ * compute the same rollup from step data; this is the SDK-side reference. */
+export declare function rollupFindings(receipts: readonly MaskReceipt[]): readonly MaskFinding[];
+//# sourceMappingURL=receipt.d.ts.map

package/dist/mask/receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.d.ts","sourceRoot":"","sources":["../../src/mask/receipt.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAElF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAUD;;4BAE4B;AAC5B,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,CAe/D;AAED;;6EAE6E;AAC7E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,GAAG,SAAS,WAAW,EAAE,CAMvF"}

package/dist/mask/receipt.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * CS-1 — receipt (WIRED 2026-08-24, CS-1 Chunk A). Spec §6.
+ *
+ * The ONLY producer of `MaskReceipt` (same single-producer discipline as
+ * `summarizeScrub` in src/artifacts/scrub.ts) so the counts-not-values invariant
+ * lives in one place. Inputs are already counts; this function never receives a
+ * matched value or a vault — its parameter type makes that structural.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarizeMask = summarizeMask;
+exports.rollupFindings = rollupFindings;
+/** Sort findings by type into the stable, counts-only array the receipt carries. */
+function sortedFindings(findings) {
+    return [...findings.entries()]
+        .filter(([, count]) => count > 0)
+        .map(([type, count]) => ({ type, count }))
+        .sort((a, b) => (a.type < b.type ? -1 : a.type > b.type ? 1 : 0));
+}
+/** Build the persisted {@link MaskReceipt} from a completed mask outcome. Sorts
+ * findings by type; omits optional fields when absent so the wire/jsonb payload
+ * is minimal and stable. */
+function summarizeMask(outcome) {
+    return {
+        policy_hash: outcome.policyHash,
+        mode: outcome.mode,
+        blocked: outcome.blocked,
+        findings: sortedFindings(outcome.findings),
+        tokens_issued: outcome.tokensIssued,
+        rehydrated: outcome.rehydrated,
+        unresolved: outcome.unresolved,
+        stream: outcome.stream,
+        ...(outcome.toolCallsUnmasked !== undefined && outcome.toolCallsUnmasked > 0
+            ? { tool_calls_unmasked: outcome.toolCallsUnmasked }
+            : {}),
+        ...(outcome.error === true ? { error: true } : {}),
+    };
+}
+/** Run rollup (derived, never stored — spec §6): sum findings by type across a
+ * run's step receipts. Sorted by type. The server read route and the console
+ * compute the same rollup from step data; this is the SDK-side reference. */
+function rollupFindings(receipts) {
+    const totals = new Map();
+    for (const r of receipts) {
+        for (const f of r.findings)
+            totals.set(f.type, (totals.get(f.type) ?? 0) + f.count);
+    }
+    return sortedFindings(totals);
+}

package/dist/mask/seam.d.ts

@@ -0,0 +1,53 @@
+/**
+ * CS-1 — the dispatch seam (WIRED 2026-08-24, CS-1 Chunk A). Spec §1.2, §9.
+ *
+ * "A per-route mask policy rewrites the `AdapterRequest` before dispatch and
+ * rehydrates the `AdapterResult` after, inside the customer's process. Adapters
+ * are untouched." (spec §1.2). This module IS that seam: {@link createMaskSeam}
+ * returns a small stateful object the run loop drives —
+ *   1. `maskRequest(req)` masks the outgoing USER slot (trusted system slot is
+ *      never touched — B3 keeps untrusted content in the user path) and returns
+ *      a discriminated outcome so the loop can FAIL CLOSED pre-dispatch;
+ *   2. `rehydrateText` / `rehydrateOutput` restore tokens in the response;
+ *   3. `receipt()` produces the counts-only {@link MaskReceipt} via the single
+ *      producer.
+ *
+ * Fail-closed matrix (spec §9): in `mask`/`block`, a detector throw ⇒ `error`
+ * outcome (loop refuses pre-dispatch, no request sent); `block` with any finding
+ * ⇒ `blocked` outcome (refuse, receipt `blocked:true`). In `detect`, a throw
+ * warns once and sends verbatim with `error:true`. `off` ⇒ the seam is inert and
+ * the run loop never builds one (byte-identical).
+ */
+import type { AdapterRequest } from "../types/provider";
+import type { MaskReceipt, ResolvedMaskPolicy } from "./types";
+import type { RunVault } from "./vault";
+export type MaskRequestOutcome = {
+    readonly kind: "ok";
+    readonly request: AdapterRequest;
+}
+/** `block` mode found a match — refuse pre-dispatch (no request sent). */
+ | {
+    readonly kind: "blocked";
+}
+/** Detector threw in `mask`/`block` — refuse pre-dispatch, fail closed. */
+ | {
+    readonly kind: "error";
+    readonly message: string;
+};
+export interface MaskSeam {
+    /** Mask the outgoing request's USER slot per the policy mode. */
+    maskRequest(req: AdapterRequest): MaskRequestOutcome;
+    /** Rehydrate a plain-text result (non-structured route). */
+    rehydrateText(text: string): string;
+    /** Rehydrate a validated structured output (post-validate, spec §5). */
+    rehydrateOutput<T>(value: T): T;
+    /** Build the counts-only receipt from accumulated state. */
+    receipt(): MaskReceipt;
+}
+/** Create the per-run dispatch seam for an ACTIVE policy (mode !== "off"). The
+ * vault is shared across every attempt/candidate of one `rig.run()` so a value
+ * keeps one token for the whole run. */
+export declare function createMaskSeam(resolved: ResolvedMaskPolicy, vault: RunVault): MaskSeam;
+/** Test-only: reset the once-per-process detect-error warning latch. */
+export declare function resetMaskWarningsForTest(): void;
+//# sourceMappingURL=seam.d.ts.map

package/dist/mask/seam.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seam.d.ts","sourceRoot":"","sources":["../../src/mask/seam.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD,OAAO,KAAK,EAAE,WAAW,EAAkB,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAC/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;CAAE;AAC3D,0EAA0E;GACxE;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE;AAC9B,2EAA2E;GACzE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,WAAW,QAAQ;IACvB,iEAAiE;IACjE,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,kBAAkB,CAAC;IACrD,4DAA4D;IAC5D,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACpC,wEAAwE;IACxE,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;IAChC,4DAA4D;IAC5D,OAAO,IAAI,WAAW,CAAC;CACxB;AAID;;wCAEwC;AACxC,wBAAgB,cAAc,CAAC,QAAQ,EAAE,kBAAkB,EAAE,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAuFtF;AAED,wEAAwE;AACxE,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}