toolroll 0.9.71 → 0.9.73

package/dist/contracts/release-check.d.ts

@@ -0,0 +1,335 @@
+/**
+ * The release check's structured results (docs/plans/release-once.md, parts 2 and 3): what the orchestrator
+ * (`scripts/release-check.mjs`) reports on its last stdout line, what the plane seals before and after a check runs
+ * (the inventory, the execution context, a targeted plan and its obligation snapshot), and the identities every one of
+ * them names. Only the plane writes the sealed payloads, from typed values; the report comes from the check itself and
+ * is read strictly — anything that doesn't match is no report.
+ *
+ * Coverage trusts test code (Alex, 2026-10-25): a test runs as the same user as the harness, so these results guard
+ * against accidental damage — stray processes, leftover files, output that looks like a report — not a hostile test.
+ * Authority decisions never read them.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** The parts a release check is made of. */
+export declare const CHECK_PARTS: readonly ["typecheck", "build", "unit", "flows", "app", "flows-real", "app-real", "upgrade"];
+export type CheckPart = typeof CHECK_PARTS[number];
+export declare const JOURNEY_SCRIPTS: readonly ["app", "flows"];
+export type JourneyScript = typeof JOURNEY_SCRIPTS[number];
+/** What the orchestrator reports, as the last line of its output: `TOOLROLL_CHECK_REPORT <json>`, at most 256 KiB. */
+export declare const CHECK_REPORT_PREFIX = "TOOLROLL_CHECK_REPORT ";
+export declare const CHECK_REPORT_MAX_BYTES: number;
+export declare const checkReportSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    nonce: z.ZodString;
+    mode: z.ZodEnum<{
+        full: "full";
+        targeted: "targeted";
+    }>;
+    planDigest: z.ZodNullable<z.ZodString>;
+    exitCode: z.ZodInt;
+    parts: z.ZodArray<z.ZodObject<{
+        part: z.ZodEnum<{
+            app: "app";
+            "app-real": "app-real";
+            build: "build";
+            flows: "flows";
+            "flows-real": "flows-real";
+            typecheck: "typecheck";
+            unit: "unit";
+            upgrade: "upgrade";
+        }>;
+        selected: z.ZodBoolean;
+        ran: z.ZodBoolean;
+        code: z.ZodNullable<z.ZodInt>;
+        timedOut: z.ZodBoolean;
+    }, z.core.$strict>>;
+    units: z.ZodNullable<z.ZodObject<{
+        reusedFromCI: z.ZodBoolean;
+        finished: z.ZodBoolean;
+        runErrors: z.ZodInt;
+        files: z.ZodArray<z.ZodObject<{
+            file: z.ZodString;
+            state: z.ZodEnum<{
+                failed: "failed";
+                passed: "passed";
+                skipped: "skipped";
+            }>;
+            passed: z.ZodInt;
+            failed: z.ZodInt;
+            skipped: z.ZodInt;
+            flaky: z.ZodBoolean;
+        }, z.core.$strict>>;
+        identities: z.ZodArray<z.ZodObject<{
+            file: z.ZodString;
+            name: z.ZodString;
+            state: z.ZodEnum<{
+                failed: "failed";
+                passed: "passed";
+                skipped: "skipped";
+            }>;
+            flaky: z.ZodBoolean;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    journeys: z.ZodArray<z.ZodObject<{
+        script: z.ZodEnum<{
+            app: "app";
+            flows: "flows";
+        }>;
+        kind: z.ZodEnum<{
+            real: "real";
+            scripted: "scripted";
+        }>;
+        finished: z.ZodBoolean;
+        groups: z.ZodArray<z.ZodObject<{
+            group: z.ZodString;
+            state: z.ZodEnum<{
+                failed: "failed";
+                "not-run": "not-run";
+                passed: "passed";
+            }>;
+            retried: z.ZodBoolean;
+            unattributed: z.ZodBoolean;
+            journeys: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                state: z.ZodEnum<{
+                    failed: "failed";
+                    passed: "passed";
+                    skipped: "skipped";
+                }>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    upgrades: z.ZodNullable<z.ZodObject<{
+        finished: z.ZodBoolean;
+        versions: z.ZodArray<z.ZodObject<{
+            version: z.ZodString;
+            state: z.ZodEnum<{
+                failed: "failed";
+                "not-run": "not-run";
+                passed: "passed";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CheckReport = z.infer<typeof checkReportSchema>;
+export declare function readCheckReport(input: unknown): ContractResult<CheckReport>;
+/** What a check must account for, sealed before it runs: the unit files (from the verified tree and Vitest's include
+ * globs) and the parts selected. The journey groups and upgrade versions come from the check's own report and are
+ * sealed beside these after it ran. */
+export declare const checkInventorySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    units: z.ZodArray<z.ZodString>;
+    parts: z.ZodArray<z.ZodEnum<{
+        app: "app";
+        "app-real": "app-real";
+        build: "build";
+        flows: "flows";
+        "flows-real": "flows-real";
+        typecheck: "typecheck";
+        unit: "unit";
+        upgrade: "upgrade";
+    }>>;
+}, z.core.$strict>;
+export type CheckInventory = z.infer<typeof checkInventorySchema>;
+/** The sealed inventory artifact: what was sealed before the run, and what the run declared. */
+export declare const sealedInventorySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    sealed: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        units: z.ZodArray<z.ZodString>;
+        parts: z.ZodArray<z.ZodEnum<{
+            app: "app";
+            "app-real": "app-real";
+            build: "build";
+            flows: "flows";
+            "flows-real": "flows-real";
+            typecheck: "typecheck";
+            unit: "unit";
+            upgrade: "upgrade";
+        }>>;
+    }, z.core.$strict>;
+    declared: z.ZodObject<{
+        groups: z.ZodArray<z.ZodObject<{
+            script: z.ZodEnum<{
+                app: "app";
+                flows: "flows";
+            }>;
+            kind: z.ZodEnum<{
+                real: "real";
+                scripted: "scripted";
+            }>;
+            groups: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+        versions: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type SealedInventory = z.infer<typeof sealedInventorySchema>;
+/** Where a check ran: what has to match for an earlier result to stand beside a later one. */
+export declare const checkContextSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    node: z.ZodString;
+    platform: z.ZodString;
+    arch: z.ZodString;
+    lockfile: z.ZodNullable<z.ZodString>;
+    harness: z.ZodString;
+    grant: z.ZodObject<{
+        id: z.ZodInt;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    access: z.ZodString;
+}, z.core.$strict>;
+export type CheckContext = z.infer<typeof checkContextSchema>;
+/** A targeted check's plan: exactly what it runs, sealed before it runs. */
+export declare const targetedPlanSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    base: z.ZodInt;
+    units: z.ZodArray<z.ZodString>;
+    sanity: z.ZodArray<z.ZodString>;
+    groups: z.ZodArray<z.ZodObject<{
+        script: z.ZodEnum<{
+            app: "app";
+            flows: "flows";
+        }>;
+        kind: z.ZodEnum<{
+            real: "real";
+            scripted: "scripted";
+        }>;
+        groups: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    versions: z.ZodArray<z.ZodString>;
+    parts: z.ZodArray<z.ZodEnum<{
+        app: "app";
+        "app-real": "app-real";
+        build: "build";
+        flows: "flows";
+        "flows-real": "flows-real";
+        typecheck: "typecheck";
+        unit: "unit";
+        upgrade: "upgrade";
+    }>>;
+    required: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type TargetedPlan = z.infer<typeof targetedPlanSchema>;
+/** The earlier targeted runs of this generation a targeted attempt took into account, sealed with it. */
+export declare const obligationSnapshotSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    authority: z.ZodInt;
+    base: z.ZodInt;
+    earlier: z.ZodArray<z.ZodObject<{
+        run: z.ZodInt;
+        reportDigest: z.ZodNullable<z.ZodString>;
+        failed: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ObligationSnapshot = z.infer<typeof obligationSnapshotSchema>;
+/** What the plane writes on the check's stdin before closing it. */
+export type CheckHandshake = {
+    nonce: string;
+    mode: "full" | "targeted";
+    plan: TargetedPlan | null;
+    watch: string[];
+};
+/** A unit test: its file and full name. */
+export declare const unitIdentity: (file: string, testName: string) => string;
+/** A unit file. */
+export declare const fileIdentity: (file: string) => string;
+/** A journey group of a script and kind. */
+export declare const groupIdentity: (script: string, kind: string, group: string) => string;
+/** One journey in its group. */
+export declare const journeyIdentity: (script: string, kind: string, group: string, journey: string) => string;
+/** An upgrade version. */
+export declare const versionIdentity: (version: string) => string;
+/** A whole part. */
+export declare const partIdentity: (part: string) => string;
+/** One fd-3 result line a harness process writes (test/release-reporter.ts, scripts/check-results.mjs). The
+ * orchestrator reads only these shapes; anything else on the pipe is passed over. */
+export declare const checkResultLineSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"unit-case">;
+    file: z.ZodString;
+    name: z.ZodString;
+    state: z.ZodEnum<{
+        failed: "failed";
+        passed: "passed";
+        skipped: "skipped";
+    }>;
+    flaky: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"unit-file">;
+    file: z.ZodString;
+    state: z.ZodEnum<{
+        failed: "failed";
+        passed: "passed";
+        skipped: "skipped";
+    }>;
+    passed: z.ZodInt;
+    failed: z.ZodInt;
+    skipped: z.ZodInt;
+    flaky: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"unit-end">;
+    reason: z.ZodString;
+    errors: z.ZodInt;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"journey-inventory">;
+    script: z.ZodEnum<{
+        app: "app";
+        flows: "flows";
+    }>;
+    journeys: z.ZodString;
+    groups: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"journey">;
+    name: z.ZodString;
+    state: z.ZodEnum<{
+        failed: "failed";
+        passed: "passed";
+        skipped: "skipped";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"journey-end">;
+    script: z.ZodOptional<z.ZodEnum<{
+        app: "app";
+        flows: "flows";
+    }>>;
+    journeys: z.ZodOptional<z.ZodString>;
+    browserCheck: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    unstopped: z.ZodOptional<z.ZodBoolean>;
+    catalogue: z.ZodOptional<z.ZodInt>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"journey-group">;
+    script: z.ZodEnum<{
+        app: "app";
+        flows: "flows";
+    }>;
+    journeys: z.ZodString;
+    group: z.ZodString;
+    state: z.ZodEnum<{
+        failed: "failed";
+        "not-run": "not-run";
+        passed: "passed";
+    }>;
+    retried: z.ZodBoolean;
+    unattributed: z.ZodBoolean;
+    results: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        state: z.ZodEnum<{
+            failed: "failed";
+            passed: "passed";
+            skipped: "skipped";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"upgrade-inventory">;
+    versions: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"upgrade-version">;
+    version: z.ZodString;
+    state: z.ZodEnum<{
+        failed: "failed";
+        "not-run": "not-run";
+        passed: "passed";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"upgrade-end">;
+}, z.core.$strict>], "kind">;

package/dist/contracts/release-check.js

@@ -0,0 +1,159 @@
+/**
+ * The release check's structured results (docs/plans/release-once.md, parts 2 and 3): what the orchestrator
+ * (`scripts/release-check.mjs`) reports on its last stdout line, what the plane seals before and after a check runs
+ * (the inventory, the execution context, a targeted plan and its obligation snapshot), and the identities every one of
+ * them names. Only the plane writes the sealed payloads, from typed values; the report comes from the check itself and
+ * is read strictly — anything that doesn't match is no report.
+ *
+ * Coverage trusts test code (Alex, 2026-10-25): a test runs as the same user as the harness, so these results guard
+ * against accidental damage — stray processes, leftover files, output that looks like a report — not a hostile test.
+ * Authority decisions never read them.
+ */
+import { z } from "zod";
+import { readVersioned, versioned } from "./contract.js";
+/** The parts a release check is made of. */
+export const CHECK_PARTS = ["typecheck", "build", "unit", "flows", "app", "flows-real", "app-real", "upgrade"];
+export const JOURNEY_SCRIPTS = ["app", "flows"];
+const hex64 = z.string().regex(/^[0-9a-f]{64}$/);
+/** A repository path as a tree names it: relative, normalized, no control characters. */
+const repoPath = z.string().min(1).max(512).regex(/^(?!\/)(?!.*(?:^|\/)\.\.?(?:\/|$))[^\u0000-\u001f\\]+$/);
+const name = z.string().min(1).max(2000);
+const groupName = z.string().min(1).max(200).regex(/^[A-Za-z0-9._/-]+$/);
+const versionName = z.string().regex(/^\d+\.\d+\.\d+$/);
+const count = z.int().min(0).max(1_000_000);
+/** What the orchestrator reports, as the last line of its output: `TOOLROLL_CHECK_REPORT <json>`, at most 256 KiB. */
+export const CHECK_REPORT_PREFIX = "TOOLROLL_CHECK_REPORT ";
+export const CHECK_REPORT_MAX_BYTES = 256 * 1024;
+export const checkReportSchema = versioned(1, {
+    /** The nonce the plane wrote on the check's stdin: the report is this run's. */
+    nonce: hex64,
+    mode: z.enum(["full", "targeted"]),
+    /** The digest of the targeted plan the orchestrator ran, as it received it; null for a full check. */
+    planDigest: hex64.nullable(),
+    /** The orchestrator's own exit code. */
+    exitCode: z.int().min(0).max(255),
+    parts: z.array(z.strictObject({
+        part: z.enum(CHECK_PARTS),
+        selected: z.boolean(),
+        ran: z.boolean(),
+        code: z.int().min(0).max(255).nullable(),
+        timedOut: z.boolean(),
+    })).max(CHECK_PARTS.length),
+    /** The unit suite, from the Vitest main process's fd-3 lines: every file's outcome, and the identities that failed,
+     * were skipped, passed on a retry or were asked about. Null when the unit part didn't run. */
+    units: z.strictObject({
+        reusedFromCI: z.boolean(),
+        /** Vitest reached the end of its run and said so. */
+        finished: z.boolean(),
+        /** Errors no test owned (an unhandled rejection, a worker crash). */
+        runErrors: count,
+        files: z.array(z.strictObject({
+            file: repoPath,
+            state: z.enum(["passed", "failed", "skipped"]),
+            passed: count, failed: count, skipped: count,
+            flaky: z.boolean(),
+        })).max(5000),
+        identities: z.array(z.strictObject({
+            file: repoPath,
+            name,
+            state: z.enum(["passed", "failed", "skipped"]),
+            flaky: z.boolean(),
+        })).max(5000),
+    }).nullable(),
+    /** Each journey script's run: the groups it ran and every journey's outcome in each. */
+    journeys: z.array(z.strictObject({
+        script: z.enum(JOURNEY_SCRIPTS),
+        kind: z.enum(["scripted", "real"]),
+        finished: z.boolean(),
+        groups: z.array(z.strictObject({
+            group: groupName,
+            state: z.enum(["passed", "failed", "not-run"]),
+            /** Passed only on the runner's retry. */
+            retried: z.boolean(),
+            /** It ended with no result line to read, or only the browser-error check failed. */
+            unattributed: z.boolean(),
+            journeys: z.array(z.strictObject({ name, state: z.enum(["passed", "failed", "skipped"]) })).max(500),
+        })).max(200),
+    })).max(4),
+    upgrades: z.strictObject({
+        finished: z.boolean(),
+        versions: z.array(z.strictObject({ version: versionName, state: z.enum(["passed", "failed", "not-run"]) })).max(500),
+    }).nullable(),
+});
+export function readCheckReport(input) {
+    return readVersioned(checkReportSchema, input);
+}
+/** What a check must account for, sealed before it runs: the unit files (from the verified tree and Vitest's include
+ * globs) and the parts selected. The journey groups and upgrade versions come from the check's own report and are
+ * sealed beside these after it ran. */
+export const checkInventorySchema = versioned(1, {
+    units: z.array(repoPath).max(20_000),
+    parts: z.array(z.enum(CHECK_PARTS)).max(CHECK_PARTS.length),
+});
+/** The sealed inventory artifact: what was sealed before the run, and what the run declared. */
+export const sealedInventorySchema = versioned(1, {
+    sealed: checkInventorySchema,
+    declared: z.strictObject({
+        groups: z.array(z.strictObject({ script: z.enum(JOURNEY_SCRIPTS), kind: z.enum(["scripted", "real"]), groups: z.array(groupName).max(200) })).max(4),
+        versions: z.array(versionName).max(500),
+    }),
+});
+/** Where a check ran: what has to match for an earlier result to stand beside a later one. */
+export const checkContextSchema = versioned(1, {
+    node: z.string().max(40),
+    platform: z.string().max(40),
+    arch: z.string().max(40),
+    /** The verified blob id of package-lock.json, or null when the tree has none. */
+    lockfile: z.string().max(64).nullable(),
+    /** One digest over every harness file's verified blob id. */
+    harness: hex64,
+    grant: z.strictObject({ id: z.int(), digest: z.string().max(128) }),
+    access: z.string().max(40),
+});
+/** A targeted check's plan: exactly what it runs, sealed before it runs. */
+export const targetedPlanSchema = versioned(1, {
+    /** The full check A whose sealed evidence every obligation comes from. */
+    base: z.int().min(1),
+    units: z.array(repoPath).max(5000),
+    sanity: z.array(repoPath).max(200),
+    groups: z.array(z.strictObject({ script: z.enum(JOURNEY_SCRIPTS), kind: z.enum(["scripted", "real"]), groups: z.array(groupName).max(200) })).max(4),
+    versions: z.array(versionName).max(500),
+    /** Whole parts to run again (a part-level outcome at A). */
+    parts: z.array(z.enum(CHECK_PARTS)).max(CHECK_PARTS.length),
+    /** The required identities: each must be reported, and pass. */
+    required: z.array(z.string().min(1).max(2600)).max(5000),
+});
+/** The earlier targeted runs of this generation a targeted attempt took into account, sealed with it. */
+export const obligationSnapshotSchema = versioned(1, {
+    authority: z.int().min(1),
+    base: z.int().min(1),
+    earlier: z.array(z.strictObject({ run: z.int().min(1), reportDigest: z.string().max(64).nullable(), failed: z.array(z.string().min(1).max(2600)).max(5000) })).max(200),
+});
+// ------------------------------------------------------------------ identities
+/** A unit test: its file and full name. */
+export const unitIdentity = (file, testName) => `unit:${file}::${testName}`;
+/** A unit file. */
+export const fileIdentity = (file) => `file:${file}`;
+/** A journey group of a script and kind. */
+export const groupIdentity = (script, kind, group) => `group:${script}:${kind}:${group}`;
+/** One journey in its group. */
+export const journeyIdentity = (script, kind, group, journey) => `journey:${script}:${kind}:${group}::${journey}`;
+/** An upgrade version. */
+export const versionIdentity = (version) => `upgrade:${version}`;
+/** A whole part. */
+export const partIdentity = (part) => `part:${part}`;
+/** One fd-3 result line a harness process writes (test/release-reporter.ts, scripts/check-results.mjs). The
+ * orchestrator reads only these shapes; anything else on the pipe is passed over. */
+export const checkResultLineSchema = z.discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("unit-case"), file: repoPath, name, state: z.enum(["passed", "failed", "skipped"]), flaky: z.boolean() }),
+    z.strictObject({ kind: z.literal("unit-file"), file: repoPath, state: z.enum(["passed", "failed", "skipped"]), passed: count, failed: count, skipped: count, flaky: z.boolean() }),
+    z.strictObject({ kind: z.literal("unit-end"), reason: z.string().max(40), errors: count }),
+    z.strictObject({ kind: z.literal("journey-inventory"), script: z.enum(JOURNEY_SCRIPTS), journeys: z.string().max(20), groups: z.array(groupName).max(200) }),
+    z.strictObject({ kind: z.literal("journey"), name, state: z.enum(["passed", "failed", "skipped"]) }),
+    z.strictObject({ kind: z.literal("journey-end"), script: z.enum(JOURNEY_SCRIPTS).optional(), journeys: z.string().max(20).optional(), browserCheck: z.string().nullable().optional(), unstopped: z.boolean().optional(), catalogue: count.optional() }),
+    z.strictObject({ kind: z.literal("journey-group"), script: z.enum(JOURNEY_SCRIPTS), journeys: z.string().max(20), group: groupName, state: z.enum(["passed", "failed", "not-run"]), retried: z.boolean(), unattributed: z.boolean(),
+        results: z.array(z.strictObject({ name, state: z.enum(["passed", "failed", "skipped"]) })).max(500) }),
+    z.strictObject({ kind: z.literal("upgrade-inventory"), versions: z.array(versionName).max(500) }),
+    z.strictObject({ kind: z.literal("upgrade-version"), version: versionName, state: z.enum(["passed", "failed", "not-run"]) }),
+    z.strictObject({ kind: z.literal("upgrade-end") }),
+]);

package/dist/contracts/release-terms.d.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** The carry rules this runtime knows (release-carry.ts CARRY_RULES). A sealed policy naming any other refuses. */
+export declare const CARRY_RULES_VERSION = 1;
+export declare const releasePolicySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    rules: z.ZodLiteral<1>;
+    carry: z.ZodBoolean;
+    protectProject: z.ZodBoolean;
+    protectedPaths: z.ZodArray<z.ZodString>;
+    limits: z.ZodObject<{
+        lines: z.ZodInt;
+        files: z.ZodInt;
+        churn: z.ZodInt;
+    }, z.core.$strict>;
+    unsandboxedCarry: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type ReleasePolicy = z.infer<typeof releasePolicySchema>;
+export declare const releaseTermsSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    repo: z.ZodString;
+    packageVersion: z.ZodString;
+    branch: z.ZodString;
+    pr: z.ZodInt;
+    base: z.ZodLiteral<"main">;
+    approvedSha: z.ZodString;
+    approvedTree: z.ZodString;
+    policy: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        rules: z.ZodLiteral<1>;
+        carry: z.ZodBoolean;
+        protectProject: z.ZodBoolean;
+        protectedPaths: z.ZodArray<z.ZodString>;
+        limits: z.ZodObject<{
+            lines: z.ZodInt;
+            files: z.ZodInt;
+            churn: z.ZodInt;
+        }, z.core.$strict>;
+        unsandboxedCarry: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
+    grant: z.ZodObject<{
+        id: z.ZodInt;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    access: z.ZodEnum<{
+        sandboxed: "sandboxed";
+        "sign-ins": "sign-ins";
+        unsandboxed: "unsandboxed";
+    }>;
+    expiresAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type ReleaseTerms = z.infer<typeof releaseTermsSchema>;
+export declare function readReleaseTerms(input: unknown): ContractResult<ReleaseTerms>;
+export declare function readReleasePolicy(input: unknown): ContractResult<ReleasePolicy>;
+/** The digest a scope binds for its release terms, domain-separated from every other digest input. */
+export declare function releaseTermsDigest(terms: ReleaseTerms): string;
+/** The digest of an effective policy, as release_authority.policy_digest holds it. */
+export declare function releasePolicyDigest(policy: ReleasePolicy): string;
+/** Strict stored terms: null column → null; anything that isn't exactly terms → a problem. */
+export declare function storedReleaseTerms(raw: unknown): {
+    ok: true;
+    terms: ReleaseTerms | null;
+} | {
+    ok: false;
+    problem: string;
+};

package/dist/contracts/release-terms.js

@@ -0,0 +1,74 @@
+/**
+ * A release scope's terms (docs/plans/release-once.md, part 1): what a person agrees to when they approve a release —
+ * the repository (from Toolroll's records), version, head branch, pull request and base, the approved commit and its
+ * tree, the effective carry policy, the release check grant, the sealed check access (fenced) and the expiry. Part of
+ * the scope digest when present; read strictly, so a row that doesn't match is a stated problem, never authority.
+ */
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { readVersioned, versioned } from "./contract.js";
+/** The carry rules this runtime knows (release-carry.ts CARRY_RULES). A sealed policy naming any other refuses. */
+export const CARRY_RULES_VERSION = 1;
+export const releasePolicySchema = versioned(1, {
+    rules: z.literal(CARRY_RULES_VERSION),
+    /** False: every later commit asks again ("Ask for every release commit", or `toolroll release --no-carry`). */
+    carry: z.boolean(),
+    /** The project's own protection: everything (protectProject) or these paths, which never carry. */
+    protectProject: z.boolean(),
+    protectedPaths: z.array(z.string().min(1).max(400)).max(200),
+    limits: z.strictObject({ lines: z.int().min(0).max(1_000_000), files: z.int().min(0).max(100_000), churn: z.int().min(0).max(1_000_000) }),
+    /** "Carry release approvals when checks aren't sandboxed" (a person's project setting, off by default). Absent (a
+     * policy sealed before it existed): off. */
+    unsandboxedCarry: z.boolean().optional(),
+});
+const sha = z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/);
+export const releaseTermsSchema = versioned(1, {
+    repo: z.string().min(1).max(4096),
+    packageVersion: z.string().regex(/^\d+\.\d+\.\d+$/),
+    branch: z.string().min(1).max(255).regex(/^[A-Za-z0-9._/-]+$/),
+    pr: z.int().min(1),
+    base: z.literal("main"),
+    approvedSha: sha,
+    approvedTree: sha,
+    policy: releasePolicySchema,
+    grant: z.strictObject({ id: z.int(), digest: z.string().min(1).max(128) }),
+    /** The check access the release check runs with at approval: the fence, or (only with unsandboxedCarry sealed in the
+     * policy) a wider one. Never wider later: a check that reaches further than this stops the release. */
+    access: z.enum(["sandboxed", "sign-ins", "unsandboxed"]),
+    expiresAt: z.iso.datetime(),
+});
+export function readReleaseTerms(input) {
+    return readVersioned(releaseTermsSchema, input);
+}
+export function readReleasePolicy(input) {
+    return readVersioned(releasePolicySchema, input);
+}
+/** The digest a scope binds for its release terms, domain-separated from every other digest input. */
+export function releaseTermsDigest(terms) {
+    return createHash("sha256").update(`release-terms:${JSON.stringify(terms)}`).digest("hex");
+}
+/** The digest of an effective policy, as release_authority.policy_digest holds it. */
+export function releasePolicyDigest(policy) {
+    return createHash("sha256").update(`release-policy:${JSON.stringify(policy)}`).digest("hex");
+}
+/** Strict stored terms: null column → null; anything that isn't exactly terms → a problem. */
+export function storedReleaseTerms(raw) {
+    if (raw === null || raw === undefined)
+        return { ok: true, terms: null };
+    if (typeof raw !== "string")
+        return { ok: false, problem: "the release terms are not stored as text" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, problem: "the release terms can't be read" };
+    }
+    const read = readReleaseTerms(parsed);
+    if (!read.ok)
+        return { ok: false, problem: `the release terms don't match their contract (${read.issues[0]?.line ?? "invalid"})` };
+    // Bytes exactly as this code writes them (store.ts serializeReleaseTerms): a reordered or padded row is not what was signed.
+    if (JSON.stringify(read.value) !== raw)
+        return { ok: false, problem: "the release terms are not stored exactly as written" };
+    return { ok: true, terms: read.value };
+}