toolroll 0.9.33 → 0.9.36

package/dist/contracts/plan.js

@@ -0,0 +1,67 @@
+/**
+ * The planner's handoff: one schema for the file a planner writes, the JSON Schema it is given (`--json-schema`) and
+ * the parser that reads it back (`parsePlan` in plan.ts). The rules JSON Schema cannot state — the plan document's
+ * sections, UTF-8 byte limits, control characters, duplicate criterion ids, the Proof naming every criterion and the
+ * silent-amendment contract check — run in plain code after parsing, each with a named error.
+ */
+import { z } from "zod";
+import { ACCEPTANCE_LIMITS, EVIDENCE_KINDS } from "../scope.js";
+import { limited, readVersioned, toModelSchema, versioned } from "./contract.js";
+/** How many paths a plan may say it touches. */
+export const PLAN_TOUCHES = 32;
+/** One acceptance criterion: the scope's own shape (scope.ts `AcceptanceCriterion`), `how` advisory and unsigned. */
+export const acceptanceCriterionSchema = z.strictObject({
+    id: limited("acceptance id", "acceptanceIdBytes").min(1),
+    statement: limited("acceptance statement", "acceptanceStatementBytes").min(1),
+    how: limited("acceptance how", "acceptanceHowBytes").nullable().optional(),
+    evidence: z.array(z.enum(EVIDENCE_KINDS)).min(1).max(EVIDENCE_KINDS.length),
+});
+export const PLAN_VERSION = 1;
+export const planSchema = versioned(PLAN_VERSION, {
+    goal: limited("goal", "goal").min(1),
+    outOfScope: limited("outOfScope", "goal").nullable().optional(),
+    touches: z.array(limited("touch", "planTouch").min(1)).max(PLAN_TOUCHES).optional(),
+    acceptance: z.array(acceptanceCriterionSchema).min(1).max(ACCEPTANCE_LIMITS.criteria),
+    plan: limited("plan", "planDocumentBytes").min(1),
+    amendment: limited("amendment", "planAmendment").nullable().optional(),
+});
+/** What the planner's `--json-schema` is: the plan schema, exactly. */
+export const PLAN_MODEL_SCHEMA = toModelSchema(planSchema);
+const PLAN_FIELDS = ["goal", "outOfScope", "touches", "acceptance", "plan", "amendment"];
+const CRITERION_FIELDS = ["id", "statement", "how", "evidence"];
+function pick(body, fields) {
+    const out = {};
+    for (const field of fields) {
+        if (Object.prototype.hasOwnProperty.call(body, field) && body[field] !== undefined)
+            out[field] = body[field];
+    }
+    return out;
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * A plan written before plans carried `version` (every plan through 0.9.33), as version 1. The old parser read only
+ * the fields it knew and ignored any others, read a null goal, plan or acceptance as missing and null touches as
+ * none; this keeps exactly that, so every plan that parsed then parses now. Values themselves are never rewritten.
+ */
+export function upgradeUnversionedPlan(body) {
+    const out = { version: PLAN_VERSION, ...pick(body, PLAN_FIELDS) };
+    for (const field of ["goal", "plan", "touches", "acceptance"]) {
+        if (out[field] === null)
+            delete out[field];
+    }
+    if (Array.isArray(out["acceptance"])) {
+        out["acceptance"] = out["acceptance"].map(criterion => (isRecord(criterion) ? pick(criterion, CRITERION_FIELDS) : criterion));
+    }
+    return out;
+}
+export const PLAN_UPGRADES = { 0: upgradeUnversionedPlan };
+/** The payload as version 1, upgraded when it was saved unversioned; null for anything that is not an object. */
+export function planPayloadBody(input) {
+    if (!isRecord(input))
+        return null;
+    return Object.prototype.hasOwnProperty.call(input, "version") ? input : upgradeUnversionedPlan(input);
+}
+/** Read a plan payload: version 1 as itself, an unversioned one upgraded, a newer one refused plainly. */
+export function readPlanPayload(input) {
+    return readVersioned(planSchema, input, PLAN_UPGRADES);
+}

package/dist/contracts/proof.d.ts

@@ -0,0 +1,136 @@
+/**
+ * The builder's proof: one schema for the file a builder writes (the proof manifest), the `proof.json` the machine
+ * stores, and the reader that reads both back (`parseProof` in proof.ts). The rules JSON Schema cannot state — UTF-8
+ * byte limits, blank text, control characters, relative screenshot paths and duplicate ids or paths — run in plain
+ * code after parsing, each with a path-named error.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** How many entries each proof list may hold. Text limits live in TEXT_LIMITS. */
+export declare const PROOF_COUNTS: {
+    readonly criteria: 12;
+    readonly evidencePerCriterion: 4;
+    readonly checks: 12;
+    readonly changed: 64;
+    readonly caveats: 8;
+    readonly screenshots: 8;
+};
+/** Every proof limit by its long-standing name: the counts above and the byte limits from TEXT_LIMITS. */
+export declare const PROOF_LIMITS: {
+    readonly criteria: 12;
+    readonly evidencePerCriterion: 4;
+    readonly checks: 12;
+    readonly changed: 64;
+    readonly caveats: 8;
+    readonly screenshots: 8;
+    readonly payload: number;
+    readonly criterionId: 40;
+    readonly criterionStatement: 300;
+    readonly criterionHow: 500;
+    readonly evidenceRef: 300;
+    readonly checkCommand: 300;
+    readonly checkSummary: 300;
+    readonly changedPath: 300;
+    readonly caveat: 300;
+    readonly screenshotPath: 300;
+    readonly screenshotCaption: 300;
+};
+export declare const CRITERION_VERDICTS: readonly ["met", "not-met", "not-checked", "pending-verification"];
+/** One typed reference a criterion cites: an existing check's command, screenshot's path, a path in `changed`, or
+ * (kind `manual-review`) free text pointing at nothing machine-checkable. */
+export declare const criterionEvidenceSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        "changed-path": "changed-path";
+        check: "check";
+        "manual-review": "manual-review";
+        screenshot: "screenshot";
+    }>;
+    ref: z.ZodString;
+}, z.core.$strict>;
+/** One criterion the proof answers. `pending-verification` asserts all agent-owned work is met and only the
+ * machine-owned final check remains. */
+export declare const proofCriterionSchema: z.ZodObject<{
+    id: z.ZodString;
+    statement: z.ZodString;
+    how: z.ZodString;
+    verdict: z.ZodEnum<{
+        met: "met";
+        "not-checked": "not-checked";
+        "not-met": "not-met";
+        "pending-verification": "pending-verification";
+    }>;
+    evidence: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            "changed-path": "changed-path";
+            check: "check";
+            "manual-review": "manual-review";
+            screenshot: "screenshot";
+        }>;
+        ref: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const proofCheckSchema: z.ZodObject<{
+    command: z.ZodString;
+    summary: z.ZodString;
+    exitCode: z.ZodInt;
+}, z.core.$strict>;
+/** A screenshot the proof claims; its path is where the file lived in the worktree, its bytes are checked by the
+ * caller. */
+export declare const proofScreenshotSchema: z.ZodObject<{
+    path: z.ZodString;
+    caption: z.ZodString;
+}, z.core.$strict>;
+export declare const PROOF_VERSION = 2;
+/** The proof as stored and as every reader returns it: every list present, nothing unknown. */
+export declare const proofSchema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    criteria: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        statement: z.ZodString;
+        how: z.ZodString;
+        verdict: z.ZodEnum<{
+            met: "met";
+            "not-checked": "not-checked";
+            "not-met": "not-met";
+            "pending-verification": "pending-verification";
+        }>;
+        evidence: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                "changed-path": "changed-path";
+                check: "check";
+                "manual-review": "manual-review";
+                screenshot: "screenshot";
+            }>;
+            ref: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    checks: z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        summary: z.ZodString;
+        exitCode: z.ZodInt;
+    }, z.core.$strict>>;
+    changed: z.ZodArray<z.ZodString>;
+    caveats: z.ZodArray<z.ZodString>;
+    screenshots: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        caption: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ParsedProof = z.infer<typeof proofSchema>;
+export type ParsedCriterion = z.infer<typeof proofCriterionSchema>;
+export type CriterionEvidenceRef = z.infer<typeof criterionEvidenceSchema>;
+export type ParsedCheck = z.infer<typeof proofCheckSchema>;
+export type ParsedScreenshot = z.infer<typeof proofScreenshotSchema>;
+/**
+ * A version 1 proof — what a builder writes (`{ "version": 1, "screenshots": [...] }`) and every proof stored through
+ * 0.9.34 — as version 2. Version 1 read only the fields it knew and ignored any others, and read a missing or null
+ * list (a criterion's `evidence` too) as empty; this keeps exactly that. Values themselves are never rewritten.
+ */
+export declare function upgradeProofV1(body: Record<string, unknown>): Record<string, unknown>;
+export declare const PROOF_UPGRADES: {
+    readonly 1: typeof upgradeProofV1;
+};
+/** The payload as version 2 (upgraded from version 1 when needed), for the plain-code rules; null for a non-object. */
+export declare function proofPayloadBody(input: unknown): Record<string, unknown> | null;
+/** Read a proof payload: version 2 as itself, version 1 upgraded, a newer one refused plainly. */
+export declare function readProofPayload(input: unknown): ContractResult<ParsedProof>;

package/dist/contracts/proof.js

@@ -0,0 +1,110 @@
+/**
+ * The builder's proof: one schema for the file a builder writes (the proof manifest), the `proof.json` the machine
+ * stores, and the reader that reads both back (`parseProof` in proof.ts). The rules JSON Schema cannot state — UTF-8
+ * byte limits, blank text, control characters, relative screenshot paths and duplicate ids or paths — run in plain
+ * code after parsing, each with a path-named error.
+ */
+import { z } from "zod";
+import { TEXT_LIMITS } from "../text-limits.js";
+import { EVIDENCE_KINDS } from "../scope.js";
+import { limited, readVersioned, versioned } from "./contract.js";
+/** How many entries each proof list may hold. Text limits live in TEXT_LIMITS. */
+export const PROOF_COUNTS = { criteria: 12, evidencePerCriterion: 4, checks: 12, changed: 64, caveats: 8, screenshots: 8 };
+/** Every proof limit by its long-standing name: the counts above and the byte limits from TEXT_LIMITS. */
+export const PROOF_LIMITS = {
+    payload: TEXT_LIMITS.proofPayloadBytes,
+    ...PROOF_COUNTS,
+    criterionId: TEXT_LIMITS.proofCriterionIdBytes,
+    criterionStatement: TEXT_LIMITS.proofLineBytes,
+    criterionHow: TEXT_LIMITS.proofHowBytes,
+    evidenceRef: TEXT_LIMITS.proofLineBytes,
+    checkCommand: TEXT_LIMITS.proofLineBytes,
+    checkSummary: TEXT_LIMITS.proofLineBytes,
+    changedPath: TEXT_LIMITS.proofLineBytes,
+    caveat: TEXT_LIMITS.proofLineBytes,
+    screenshotPath: TEXT_LIMITS.proofLineBytes,
+    screenshotCaption: TEXT_LIMITS.proofLineBytes,
+};
+export const CRITERION_VERDICTS = ["met", "not-met", "not-checked", "pending-verification"];
+const line = (field) => limited(field, "proofLineBytes").min(1);
+/** One typed reference a criterion cites: an existing check's command, screenshot's path, a path in `changed`, or
+ * (kind `manual-review`) free text pointing at nothing machine-checkable. */
+export const criterionEvidenceSchema = z.strictObject({
+    kind: z.enum(EVIDENCE_KINDS),
+    ref: line("evidence ref"),
+});
+/** One criterion the proof answers. `pending-verification` asserts all agent-owned work is met and only the
+ * machine-owned final check remains. */
+export const proofCriterionSchema = z.strictObject({
+    id: limited("criterion id", "proofCriterionIdBytes").min(1),
+    statement: line("criterion statement"),
+    how: limited("criterion how", "proofHowBytes").min(1),
+    verdict: z.enum(CRITERION_VERDICTS),
+    evidence: z.array(criterionEvidenceSchema).max(PROOF_COUNTS.evidencePerCriterion),
+});
+export const proofCheckSchema = z.strictObject({
+    command: line("check command"),
+    summary: line("check summary"),
+    exitCode: z.int().min(0).max(255),
+});
+/** A screenshot the proof claims; its path is where the file lived in the worktree, its bytes are checked by the
+ * caller. */
+export const proofScreenshotSchema = z.strictObject({
+    path: line("screenshot path"),
+    caption: line("screenshot caption"),
+});
+export const PROOF_VERSION = 2;
+/** The proof as stored and as every reader returns it: every list present, nothing unknown. */
+export const proofSchema = versioned(PROOF_VERSION, {
+    criteria: z.array(proofCriterionSchema).max(PROOF_COUNTS.criteria),
+    checks: z.array(proofCheckSchema).max(PROOF_COUNTS.checks),
+    changed: z.array(line("changed path")).max(PROOF_COUNTS.changed),
+    caveats: z.array(line("caveat")).max(PROOF_COUNTS.caveats),
+    screenshots: z.array(proofScreenshotSchema).max(PROOF_COUNTS.screenshots),
+});
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The listed fields of `body`, a null or missing one left out (the old parser read null text as missing). */
+function pick(body, fields) {
+    const out = {};
+    for (const field of fields) {
+        if (body[field] !== undefined && body[field] !== null)
+            out[field] = body[field];
+    }
+    return out;
+}
+const each = (value, fields) => (Array.isArray(value) ? value.map(one => (isRecord(one) ? pick(one, fields) : one)) : value);
+/**
+ * A version 1 proof — what a builder writes (`{ "version": 1, "screenshots": [...] }`) and every proof stored through
+ * 0.9.34 — as version 2. Version 1 read only the fields it knew and ignored any others, and read a missing or null
+ * list (a criterion's `evidence` too) as empty; this keeps exactly that. Values themselves are never rewritten.
+ */
+export function upgradeProofV1(body) {
+    const list = (field) => (body[field] === undefined || body[field] === null ? [] : body[field]);
+    const criteria = list("criteria");
+    return {
+        version: PROOF_VERSION,
+        criteria: Array.isArray(criteria)
+            ? criteria.map(one => {
+                if (!isRecord(one))
+                    return one;
+                const evidence = one["evidence"] === undefined || one["evidence"] === null ? [] : one["evidence"];
+                return { ...pick(one, ["id", "statement", "how", "verdict"]), evidence: each(evidence, ["kind", "ref"]) };
+            })
+            : criteria,
+        checks: each(list("checks"), ["command", "summary", "exitCode"]),
+        changed: list("changed"),
+        caveats: list("caveats"),
+        screenshots: each(list("screenshots"), ["path", "caption"]),
+    };
+}
+export const PROOF_UPGRADES = { 1: upgradeProofV1 };
+/** The payload as version 2 (upgraded from version 1 when needed), for the plain-code rules; null for a non-object. */
+export function proofPayloadBody(input) {
+    if (!isRecord(input))
+        return null;
+    return input["version"] === 1 ? upgradeProofV1(input) : input;
+}
+/** Read a proof payload: version 2 as itself, version 1 upgraded, a newer one refused plainly. */
+export function readProofPayload(input) {
+    return readVersioned(proofSchema, input, PROOF_UPGRADES);
+}

package/dist/contracts/verification-receipt.d.ts

@@ -0,0 +1,148 @@
+/**
+ * The machine verification receipt (`verification-receipt.json`): one schema for what `sealVerificationReceipt`
+ * writes and what `verificationEvidence` reads back. Only the machine writes it, from typed values, so every receipt
+ * ever sealed already has exactly this shape; the bindings that need the store — the run, its candidate, the approved
+ * command, the retained log and a reused gate's source — are checked in plain code after parsing.
+ *
+ * Version 1 is a gate executed in its own run. Version 2 added `reusedFrom` and `executedHere: false` for a gate
+ * reused by an unchanged observation follow-up. A direct receipt is still sealed as version 1, so its bytes (and the
+ * digests bound to them) read the same in every Toolroll that reads receipts.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+export declare const VERIFICATION_FAILURES: readonly ["spawn-failed", "timed-out", "dependency-missing", "setup-stale", "setup-failed", "own-install-failed", "tracked-files-changed", "setup-changed-files", "checkout-moved", "cleanliness-unavailable", "dependency-still-missing", "retry-spawn-failed", "retry-timed-out", "custody-lost"];
+/**
+ * What the repository's approved verification command did: not configured; configured but the run could not attempt
+ * it (`attemptFailed`, which downgrades to `short` rather than `refuted`: "we could not check" is not "the claim is
+ * false"); or ran, with its exit code.
+ */
+export declare const verifyCommandFactsSchema: z.ZodUnion<readonly [z.ZodObject<{
+    configured: z.ZodLiteral<false>;
+}, z.core.$strict>, z.ZodObject<{
+    configured: z.ZodLiteral<true>;
+    ran: z.ZodLiteral<false>;
+    attemptFailed: z.ZodLiteral<true>;
+    failure: z.ZodOptional<z.ZodEnum<{
+        "checkout-moved": "checkout-moved";
+        "cleanliness-unavailable": "cleanliness-unavailable";
+        "custody-lost": "custody-lost";
+        "dependency-missing": "dependency-missing";
+        "dependency-still-missing": "dependency-still-missing";
+        "own-install-failed": "own-install-failed";
+        "retry-spawn-failed": "retry-spawn-failed";
+        "retry-timed-out": "retry-timed-out";
+        "setup-changed-files": "setup-changed-files";
+        "setup-failed": "setup-failed";
+        "setup-stale": "setup-stale";
+        "spawn-failed": "spawn-failed";
+        "timed-out": "timed-out";
+        "tracked-files-changed": "tracked-files-changed";
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
+    configured: z.ZodLiteral<true>;
+    ran: z.ZodLiteral<true>;
+    exitCode: z.ZodInt;
+    setupReplayed: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>]>;
+export type VerifyCommandFacts = z.infer<typeof verifyCommandFactsSchema>;
+/** The approved verification grant the gate ran, exactly as the store held it. */
+export declare const receiptCommandSchema: z.ZodObject<{
+    id: z.ZodInt;
+    repo: z.ZodString;
+    command: z.ZodString;
+    timeoutMs: z.ZodInt;
+    digest: z.ZodString;
+    recoverySetupDigest: z.ZodNullable<z.ZodString>;
+    approvedBy: z.ZodString;
+    approvedAt: z.ZodString;
+    revokedAt: z.ZodNullable<z.ZodString>;
+    revokedBy: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+/** The retained check log the receipt binds, by artifact id and content. */
+export declare const receiptLogSchema: z.ZodObject<{
+    artifactId: z.ZodInt;
+    sha256: z.ZodString;
+    bytesStored: z.ZodInt;
+    bytesOriginal: z.ZodInt;
+    truncated: z.ZodBoolean;
+    redacted: z.ZodBoolean;
+    captureStatus: z.ZodNullable<z.ZodEnum<{
+        failed: "failed";
+        ok: "ok";
+    }>>;
+}, z.core.$strict>;
+export declare const RECEIPT_VERSION = 2;
+/** The receipt as read: a reused gate names its source run and digest; a direct one names neither. */
+export declare const verificationReceiptSchema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    run: z.ZodInt;
+    head: z.ZodString;
+    base: z.ZodNullable<z.ZodString>;
+    scopeDigest: z.ZodNullable<z.ZodString>;
+    reusedFrom: z.ZodOptional<z.ZodObject<{
+        run: z.ZodInt;
+        digest: z.ZodString;
+    }, z.core.$strict>>;
+    executedHere: z.ZodOptional<z.ZodLiteral<false>>;
+    command: z.ZodObject<{
+        id: z.ZodInt;
+        repo: z.ZodString;
+        command: z.ZodString;
+        timeoutMs: z.ZodInt;
+        digest: z.ZodString;
+        recoverySetupDigest: z.ZodNullable<z.ZodString>;
+        approvedBy: z.ZodString;
+        approvedAt: z.ZodString;
+        revokedAt: z.ZodNullable<z.ZodString>;
+        revokedBy: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    result: z.ZodUnion<readonly [z.ZodObject<{
+        configured: z.ZodLiteral<false>;
+    }, z.core.$strict>, z.ZodObject<{
+        configured: z.ZodLiteral<true>;
+        ran: z.ZodLiteral<false>;
+        attemptFailed: z.ZodLiteral<true>;
+        failure: z.ZodOptional<z.ZodEnum<{
+            "checkout-moved": "checkout-moved";
+            "cleanliness-unavailable": "cleanliness-unavailable";
+            "custody-lost": "custody-lost";
+            "dependency-missing": "dependency-missing";
+            "dependency-still-missing": "dependency-still-missing";
+            "own-install-failed": "own-install-failed";
+            "retry-spawn-failed": "retry-spawn-failed";
+            "retry-timed-out": "retry-timed-out";
+            "setup-changed-files": "setup-changed-files";
+            "setup-failed": "setup-failed";
+            "setup-stale": "setup-stale";
+            "spawn-failed": "spawn-failed";
+            "timed-out": "timed-out";
+            "tracked-files-changed": "tracked-files-changed";
+        }>>;
+    }, z.core.$strict>, z.ZodObject<{
+        configured: z.ZodLiteral<true>;
+        ran: z.ZodLiteral<true>;
+        exitCode: z.ZodInt;
+        setupReplayed: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strict>]>;
+    log: z.ZodObject<{
+        artifactId: z.ZodInt;
+        sha256: z.ZodString;
+        bytesStored: z.ZodInt;
+        bytesOriginal: z.ZodInt;
+        truncated: z.ZodBoolean;
+        redacted: z.ZodBoolean;
+        captureStatus: z.ZodNullable<z.ZodEnum<{
+            failed: "failed";
+            ok: "ok";
+        }>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type VerificationReceipt = z.infer<typeof verificationReceiptSchema>;
+/** A version 1 receipt read as version 2: the same fields. Reuse is a version 2 field; a version 1 receipt naming it
+ * is refused by its reader, which still knows the version it was sealed as. */
+export declare function upgradeDirectReceipt(body: Record<string, unknown>): Record<string, unknown>;
+export declare const RECEIPT_UPGRADES: {
+    readonly 1: typeof upgradeDirectReceipt;
+};
+/** Read a receipt: version 2 as itself, version 1 as a direct gate, a newer one refused plainly. */
+export declare function readVerificationReceipt(input: unknown): ContractResult<VerificationReceipt>;

package/dist/contracts/verification-receipt.js

@@ -0,0 +1,87 @@
+/**
+ * The machine verification receipt (`verification-receipt.json`): one schema for what `sealVerificationReceipt`
+ * writes and what `verificationEvidence` reads back. Only the machine writes it, from typed values, so every receipt
+ * ever sealed already has exactly this shape; the bindings that need the store — the run, its candidate, the approved
+ * command, the retained log and a reused gate's source — are checked in plain code after parsing.
+ *
+ * Version 1 is a gate executed in its own run. Version 2 added `reusedFrom` and `executedHere: false` for a gate
+ * reused by an unchanged observation follow-up. A direct receipt is still sealed as version 1, so its bytes (and the
+ * digests bound to them) read the same in every Toolroll that reads receipts.
+ */
+import { z } from "zod";
+import { readVersioned, versioned } from "./contract.js";
+export const VERIFICATION_FAILURES = [
+    "spawn-failed",
+    "timed-out",
+    "dependency-missing",
+    "setup-stale",
+    "setup-failed",
+    "own-install-failed",
+    "tracked-files-changed",
+    "setup-changed-files",
+    "checkout-moved",
+    "cleanliness-unavailable",
+    "dependency-still-missing",
+    "retry-spawn-failed",
+    "retry-timed-out",
+    "custody-lost",
+];
+/**
+ * What the repository's approved verification command did: not configured; configured but the run could not attempt
+ * it (`attemptFailed`, which downgrades to `short` rather than `refuted`: "we could not check" is not "the claim is
+ * false"); or ran, with its exit code.
+ */
+export const verifyCommandFactsSchema = z.union([
+    z.strictObject({ configured: z.literal(false) }),
+    z.strictObject({ configured: z.literal(true), ran: z.literal(false), attemptFailed: z.literal(true), failure: z.enum(VERIFICATION_FAILURES).optional() }),
+    z.strictObject({ configured: z.literal(true), ran: z.literal(true), exitCode: z.int().min(0).max(255), setupReplayed: z.literal(true).optional() }),
+]);
+/** The approved verification grant the gate ran, exactly as the store held it. */
+export const receiptCommandSchema = z.strictObject({
+    id: z.int(),
+    repo: z.string(),
+    command: z.string(),
+    timeoutMs: z.int(),
+    digest: z.string(),
+    recoverySetupDigest: z.string().nullable(),
+    approvedBy: z.string(),
+    approvedAt: z.string(),
+    revokedAt: z.string().nullable(),
+    revokedBy: z.string().nullable(),
+});
+/** The retained check log the receipt binds, by artifact id and content. */
+export const receiptLogSchema = z.strictObject({
+    artifactId: z.int(),
+    sha256: z.string(),
+    bytesStored: z.int(),
+    bytesOriginal: z.int(),
+    truncated: z.boolean(),
+    redacted: z.boolean(),
+    captureStatus: z.enum(["ok", "failed"]).nullable(),
+});
+export const RECEIPT_VERSION = 2;
+const receiptFields = {
+    run: z.int(),
+    head: z.string(),
+    base: z.string().nullable(),
+    scopeDigest: z.string().nullable(),
+};
+/** The receipt as read: a reused gate names its source run and digest; a direct one names neither. */
+export const verificationReceiptSchema = versioned(RECEIPT_VERSION, {
+    ...receiptFields,
+    reusedFrom: z.strictObject({ run: z.int(), digest: z.string() }).optional(),
+    executedHere: z.literal(false).optional(),
+    command: receiptCommandSchema,
+    result: verifyCommandFactsSchema,
+    log: receiptLogSchema,
+});
+/** A version 1 receipt read as version 2: the same fields. Reuse is a version 2 field; a version 1 receipt naming it
+ * is refused by its reader, which still knows the version it was sealed as. */
+export function upgradeDirectReceipt(body) {
+    return { ...body, version: RECEIPT_VERSION };
+}
+export const RECEIPT_UPGRADES = { 1: upgradeDirectReceipt };
+/** Read a receipt: version 2 as itself, version 1 as a direct gate, a newer one refused plainly. */
+export function readVerificationReceipt(input) {
+    return readVersioned(verificationReceiptSchema, input, RECEIPT_UPGRADES);
+}

package/dist/demo.js

@@ -38,6 +38,7 @@ import { fileTaskProposal, fileRoutineProposal } from "./proposal.js";
 import { storeEvidence, budgetedStatJson, imageDimensions } from "./evidence.js";
 import { parseProof, adjudicate } from "./proof.js";
 import { sealVerificationReceipt } from "./verification-evidence.js";
+import { HANDOFF_VERSION, readHandoffArtifact } from "./contracts/handoff.js";
 import { parseExecutionPlanDocument, milestonesOf } from "./plan.js";
 import { maybeTriggerRepair } from "./dispose.js";
 import { deflateSync } from "node:zlib";
@@ -84,8 +85,21 @@ index 11aa0b2..c44d1f7 100644
 +    expect(settle(1005, 0.031)).toBe(31.16);
 +  });
 `;
+/** A demo run's handoff artifact: the run's own identity around the story's conclusion and lists, written through
+ * the handoff schema like a real one. */
+function demoHandoffBytes(store, runId, told) {
+    const run = store.getRun(runId);
+    const head = run.headRevision ?? run.baseRevision ?? "0".repeat(40);
+    const read = readHandoffArtifact({
+        version: HANDOFF_VERSION, taskId: store.externalIdFor(run.taskRef) ?? String(run.taskRef), runId, provider: run.provider,
+        sessionId: null, branch: run.branch ?? "", worktree: run.worktree ?? "", base: run.baseRevision ?? head, head, ...told,
+        freshness: { stampedAt: run.startedAt, currentAsOf: head },
+    });
+    if (!read.ok)
+        throw new Error(`demo handoff: ${read.issues.map(issue => issue.line).join("; ")}`);
+    return Buffer.from(JSON.stringify(read.value, null, 2), "utf8");
+}
 const DEMO_HANDOFF = {
-    schema: 1,
     outcome: "built",
     committed: true,
     conclusion: "Fixed the payout rounding drift: settle() now rounds at cent precision instead of accumulating half-cent errors. Added boundary tests against the ledger fixtures. All 214 tests pass.",
@@ -123,7 +137,6 @@ index 2b3c4d5..8e9f0a1 100644
  };
 `;
 const DEMO_FAILED_HANDOFF = {
-    schema: 1,
     outcome: "built",
     committed: true,
     conclusion: "Removed LEGACY_PAYOUT from settlement and config. The admin override still reads it, so one reference remains.",
@@ -193,7 +206,6 @@ index a1b2c3d..d4e5f6a 100644
 +export const EMPTY_STATE_ILLUSTRATION = "quiet-inbox";
 `;
 const DEMO_COPY_HANDOFF = {
-    schema: 1,
     outcome: "built",
     committed: true,
     conclusion: "Rewrote the inbox's empty-state copy so it explains why the list is empty instead of just saying so.",
@@ -605,7 +617,7 @@ export function seedDemo(store, repos, evidenceRoot, now) {
         filesTruncated: false,
     };
     storeEvidence(store, evidenceRoot, doneRun, "diff-stat", "diff-stat.json", budgetedStatJson(stat), "parsed from git diff --numstat -z [demo: synthetic]", hoursAgo(8.5));
-    storeEvidence(store, evidenceRoot, doneRun, "handoff", "handoff.json", Buffer.from(JSON.stringify(DEMO_HANDOFF, null, 2), "utf8"), "composed at completion [demo: synthetic]", hoursAgo(8.4));
+    storeEvidence(store, evidenceRoot, doneRun, "handoff", "handoff.json", demoHandoffBytes(store, doneRun, DEMO_HANDOFF), "composed at completion [demo: synthetic]", hoursAgo(8.4));
     // The evidence bundle (Priority 2): a validated proof, its claimed
     // screenshot stored as immutable image evidence, the plane's own re-run
     // check, and the closed verdict — computed once, exactly as the real
@@ -669,7 +681,7 @@ export function seedDemo(store, repos, evidenceRoot, now) {
         filesTruncated: false,
     };
     storeEvidence(store, evidenceRoot, failedRun, "diff-stat", "diff-stat.json", budgetedStatJson(failedStat), "parsed from git diff --numstat -z [demo: synthetic]", hoursAgo(5.6));
-    storeEvidence(store, evidenceRoot, failedRun, "handoff", "handoff.json", Buffer.from(JSON.stringify(DEMO_FAILED_HANDOFF, null, 2), "utf8"), "composed at completion [demo: synthetic]", hoursAgo(5.6));
+    storeEvidence(store, evidenceRoot, failedRun, "handoff", "handoff.json", demoHandoffBytes(store, failedRun, DEMO_FAILED_HANDOFF), "composed at completion [demo: synthetic]", hoursAgo(5.6));
     storeEvidence(store, evidenceRoot, failedRun, "proof", "proof.json", Buffer.from(JSON.stringify(DEMO_FAILED_PROOF, null, 2), "utf8"), "agent-authored proof (validated, re-serialized) [demo: synthetic]", hoursAgo(5.6));
     const failedAdjudicated = adjudicate({
         proofArtifactPresent: true,
@@ -734,7 +746,7 @@ export function seedDemo(store, repos, evidenceRoot, now) {
         filesTruncated: false,
     };
     storeEvidence(store, evidenceRoot, copyReviewRun, "diff-stat", "diff-stat.json", budgetedStatJson(copyStat), "parsed from git diff --numstat -z [demo: synthetic]", hoursAgo(3.6));
-    storeEvidence(store, evidenceRoot, copyReviewRun, "handoff", "handoff.json", Buffer.from(JSON.stringify(DEMO_COPY_HANDOFF, null, 2), "utf8"), "composed at completion [demo: synthetic]", hoursAgo(3.5));
+    storeEvidence(store, evidenceRoot, copyReviewRun, "handoff", "handoff.json", demoHandoffBytes(store, copyReviewRun, DEMO_COPY_HANDOFF), "composed at completion [demo: synthetic]", hoursAgo(3.5));
     storeEvidence(store, evidenceRoot, copyReviewRun, "proof", "proof.json", Buffer.from(JSON.stringify(DEMO_COPY_PROOF, null, 2), "utf8"), "agent-authored proof (validated, re-serialized) [demo: synthetic]", hoursAgo(3.5));
     const copyReviewProofParse = parseProof(JSON.stringify(DEMO_COPY_PROOF));
     const copyReviewAdjudicated = adjudicate({
@@ -815,10 +827,15 @@ export function seedDemo(store, repos, evidenceRoot, now) {
     };
     storeEvidence(store, evidenceRoot, reviewedRun, "diff-stat", "diff-stat.json", budgetedStatJson(reviewedStat), "parsed from git diff --numstat -z [demo: synthetic]", hoursAgo(4.6));
     const DEMO_REPAIR_HANDOFF = {
-        summary: "Added a TODO comment marking the per-account lock — ran out of turns before wiring the actual guard.",
-        filesTouched: ["src/payout-limiter.ts"],
+        outcome: "built",
+        committed: true,
+        conclusion: "Added a TODO comment marking the per-account lock — ran out of turns before wiring the actual guard.",
+        changes: ["Marked the per-account lock in src/payout-limiter.ts."],
+        verification: [],
+        followUps: [],
+        decisionsIncorporated: [],
     };
-    storeEvidence(store, evidenceRoot, reviewedRun, "handoff", "handoff.json", Buffer.from(JSON.stringify(DEMO_REPAIR_HANDOFF, null, 2), "utf8"), "composed at completion [demo: synthetic]", hoursAgo(4.5));
+    storeEvidence(store, evidenceRoot, reviewedRun, "handoff", "handoff.json", demoHandoffBytes(store, reviewedRun, DEMO_REPAIR_HANDOFF), "composed at completion [demo: synthetic]", hoursAgo(4.5));
     const DEMO_REPAIR_PROOF = {
         version: 1,
         criteria: [
@@ -1389,7 +1406,7 @@ export function createDemoLead(input) {
         };
         const shotPath = `evidence/${plan.kind}.png`;
         const png = demoScreenshot(plan.screenshot.accent);
-        const handoff = { schema: 1, outcome: "built", committed: true, conclusion: plan.conclusion, changes: diffs.map(one => `Changed ${one.path}.`), verification: [plan.checks[0]], followUps: [], decisionsIncorporated: [] };
+        const handoff = { outcome: "built", committed: true, conclusion: plan.conclusion, changes: diffs.map(one => `Changed ${one.path}.`), verification: [plan.checks[0]], followUps: [], decisionsIncorporated: [] };
         const proof = {
             version: 1,
             criteria: [
@@ -1404,7 +1421,7 @@ export function createDemoLead(input) {
         const synthetic = "[demo: scripted]";
         storeEvidence(store, evidenceRoot, run, "terminal-diff", "terminal-diff.patch", Buffer.from(diffs.map(one => one.patch).join(""), "utf8"), `git diff --no-ext-diff --no-textconv --no-color ${base.slice(0, 8)}..HEAD (exit 0) ${synthetic}`, at);
         storeEvidence(store, evidenceRoot, run, "diff-stat", "diff-stat.json", budgetedStatJson(stat), `parsed from git diff --numstat -z ${synthetic}`, at);
-        storeEvidence(store, evidenceRoot, run, "handoff", "handoff.json", Buffer.from(JSON.stringify(handoff, null, 2), "utf8"), `composed at completion ${synthetic}`, at);
+        storeEvidence(store, evidenceRoot, run, "handoff", "handoff.json", demoHandoffBytes(store, run, handoff), `composed at completion ${synthetic}`, at);
         storeEvidence(store, evidenceRoot, run, "proof", "proof.json", Buffer.from(JSON.stringify(proof, null, 2), "utf8"), `agent-authored proof (validated, re-serialized) ${synthetic}`, at);
         storeEvidence(store, evidenceRoot, run, "screenshot", `screenshot-${plan.kind}.png`, png, `agent-claimed screenshot at ${shotPath} (validated png) ${synthetic}`, at);
         const log = `=== Attempt summary ===\n- Project check · attempt 1: (exit 0)\n\n=== Project check · attempt 1 ===\n$ ${DEMO_CHECK_COMMAND}\n(exit 0)\n\n--- stdout ---\n${plan.checkOutput}\n--- stderr ---\n`;