toolroll 0.9.34 → 0.9.37

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/review-findings.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The automatic build review's findings (build-review.ts): one schema for the reply a reviewer gives, the `findings`
+ * a Claude reviewer's `--json-schema` describes (provider.ts, inside the review channel it shares with evidence
+ * reviews), and what `build_review.findings_json` keeps. `parseBuildFindings` (reviewer.ts) reads a reply through it;
+ * a saved row is the same payload, written by `settle` after that read.
+ *
+ * As before, controls and runs of whitespace collapse to one space before text limits are checked. Unknown keys
+ * are ignored in both the review envelope and each finding.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+export declare const FINDING_SEVERITIES: readonly ["HIGH", "MEDIUM", "LOW"];
+export type FindingSeverity = (typeof FINDING_SEVERITIES)[number];
+/** How many findings one review may raise. */
+export declare const FINDINGS_MAX = 40;
+/** One finding: how bad, where (a path and the closest line), and how it fails, in one sentence. */
+export declare const buildFindingSchema: z.ZodObject<{
+    severity: z.ZodEnum<{
+        HIGH: "HIGH";
+        LOW: "LOW";
+        MEDIUM: "MEDIUM";
+    }>;
+    file: z.ZodString;
+    line: z.ZodNumber;
+    scenario: z.ZodString;
+}, z.core.$strip>;
+export type BuildFinding = z.infer<typeof buildFindingSchema>;
+export declare const FINDINGS_VERSION = 1;
+export declare const buildFindingsSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    findings: z.ZodArray<z.ZodObject<{
+        severity: z.ZodEnum<{
+            HIGH: "HIGH";
+            LOW: "LOW";
+            MEDIUM: "MEDIUM";
+        }>;
+        file: z.ZodString;
+        line: z.ZodNumber;
+        scenario: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BuildFindings = z.infer<typeof buildFindingsSchema>;
+/** The `findings` a reviewer's structured reply may carry (provider.ts's review channel), from the same schema. */
+export declare const FINDINGS_MODEL_SCHEMA: Readonly<Record<string, unknown>>;
+/** Read a findings payload: version 1 as itself, a newer one refused plainly, anything else by path. */
+export declare function readBuildFindings(input: unknown): ContractResult<BuildFindings>;

package/dist/contracts/review-findings.js

@@ -0,0 +1,48 @@
+/**
+ * The automatic build review's findings (build-review.ts): one schema for the reply a reviewer gives, the `findings`
+ * a Claude reviewer's `--json-schema` describes (provider.ts, inside the review channel it shares with evidence
+ * reviews), and what `build_review.findings_json` keeps. `parseBuildFindings` (reviewer.ts) reads a reply through it;
+ * a saved row is the same payload, written by `settle` after that read.
+ *
+ * As before, controls and runs of whitespace collapse to one space before text limits are checked. Unknown keys
+ * are ignored in both the review envelope and each finding.
+ */
+import { z } from "zod";
+import { TEXT_LIMITS } from "../text-limits.js";
+import { limited, readVersioned, toModelSchema, versioned } from "./contract.js";
+export const FINDING_SEVERITIES = ["HIGH", "MEDIUM", "LOW"];
+/** How many findings one review may raise. */
+export const FINDINGS_MAX = 40;
+/** One finding: how bad, where (a path and the closest line), and how it fails, in one sentence. */
+export const buildFindingSchema = z.object({
+    severity: z.enum(FINDING_SEVERITIES),
+    file: limited("file", "reviewPath").min(1).describe(`file: at most ${TEXT_LIMITS.reviewPath} characters, on one line.`),
+    line: z.number().min(1).multipleOf(1),
+    scenario: limited("scenario", "reviewNote").min(1).describe(`scenario: at most ${TEXT_LIMITS.reviewNote} characters, on one line.`),
+});
+export const FINDINGS_VERSION = 1;
+export const buildFindingsSchema = versioned(FINDINGS_VERSION, {
+    findings: z.array(buildFindingSchema).max(FINDINGS_MAX),
+}).strip();
+/** The `findings` a reviewer's structured reply may carry (provider.ts's review channel), from the same schema. */
+export const FINDINGS_MODEL_SCHEMA = toModelSchema(buildFindingsSchema.shape.findings);
+/** Read a findings payload: version 1 as itself, a newer one refused plainly, anything else by path. */
+export function readBuildFindings(input) {
+    if (typeof input === "object" && input !== null && !Array.isArray(input)) {
+        const body = input;
+        if (Array.isArray(body["findings"])) {
+            input = { ...body, findings: body["findings"].map(entry => {
+                    if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+                        return entry;
+                    const finding = { ...entry };
+                    for (const key of ["file", "scenario"]) {
+                        const text = finding[key];
+                        if (typeof text === "string")
+                            finding[key] = text.replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]+/g, " ").replace(/\s+/g, " ").trim();
+                    }
+                    return finding;
+                }) };
+        }
+    }
+    return readVersioned(buildFindingsSchema, input);
+}

package/dist/contracts/route.d.ts

@@ -0,0 +1,484 @@
+/**
+ * A sealed route (phase-routing.ts): which exact agent plans, builds, repairs and reviews a task, as a scope's
+ * `proposed_route_json` / `approved_route_json` and a standing order's route keep it. One schema covering both versions
+ * a route has been saved in — version 1 (sealed before sizing: no `size`, routine and strong tiers) and version 2 —
+ * plus the override list and the task size it carries. The rules JSON Schema cannot state run in plain code after
+ * parsing, each with a path-named error: the legs run plan, build, repair, review in that order; the posture is what
+ * the legs actually run; one override per phase.
+ *
+ * Reading never rewrites: a version 1 route stays version 1 (its digest domain and bytes are its own), and reads with
+ * no size. phase-routing.ts `canonicalRouteJson` / `routeDigestOf` encode the parsed value, so a sealed route's digest
+ * is what it always was.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** The phases a route has a leg for, in the order its legs run. */
+export declare const ROUTE_PHASES: readonly ["plan", "build", "repair", "review"];
+/** provider.ts's provider ids, restated (provider.ts sits above phase-routing.ts in the module graph) and pinned to
+ * them by the test suite. */
+export declare const ROUTE_PROVIDERS: readonly ["claude", "codex", "openrouter", "gemini"];
+/** provider.ts's MODEL_ID, restated for the same reason: an exact model id is argv-safe — no leading dash, no
+ * whitespace or control bytes. */
+export declare const MODEL_ID_SHAPE: RegExp;
+export declare const RISKS: readonly ["routine", "elevated", "high"];
+export declare const TASK_SIZE_WORDS: readonly ["small", "medium", "large"];
+/** The route version this code seals; version 1 (before sizing) still reads. */
+export declare const ROUTE_VERSION = 2;
+/** How big a change the task is, as it was sized (by the classifier, the description, or a person). */
+export declare const taskSizingSchema: z.ZodObject<{
+    size: z.ZodEnum<{
+        large: "large";
+        medium: "medium";
+        small: "small";
+    }>;
+    risky: z.ZodBoolean;
+    source: z.ZodEnum<{
+        classifier: "classifier";
+        heuristic: "heuristic";
+        person: "person";
+    }>;
+    reason: z.ZodString;
+}, z.core.$strict>;
+/** An approver's explicit per-phase choice, recorded with attribution. */
+export declare const routeOverrideSchema: z.ZodObject<{
+    phase: z.ZodEnum<{
+        build: "build";
+        plan: "plan";
+        repair: "repair";
+        review: "review";
+    }>;
+    provider: z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        gemini: "gemini";
+        openrouter: "openrouter";
+    }>;
+    model: z.ZodString;
+    by: z.ZodString;
+    at: z.ZodString;
+}, z.core.$strict>;
+/** One leg of a version 2 route: the light tier exists. */
+export declare const routeLegSchema: z.ZodObject<{
+    phase: z.ZodEnum<{
+        build: "build";
+        plan: "plan";
+        repair: "repair";
+        review: "review";
+    }>;
+    provider: z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        gemini: "gemini";
+        openrouter: "openrouter";
+    }>;
+    model: z.ZodString;
+    tier: z.ZodEnum<{
+        light: "light";
+        routine: "routine";
+        strong: "strong";
+    }>;
+    chosen: z.ZodEnum<{
+        override: "override";
+        pinned: "pinned";
+        recommended: "recommended";
+    }>;
+    recommended: z.ZodObject<{
+        provider: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            gemini: "gemini";
+            openrouter: "openrouter";
+        }>;
+        model: z.ZodString;
+        tier: z.ZodEnum<{
+            light: "light";
+            routine: "routine";
+            strong: "strong";
+        }>;
+    }, z.core.$strict>;
+    reasons: z.ZodArray<z.ZodString>;
+    problem: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const sealedRouteV1Schema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    risk: z.ZodEnum<{
+        elevated: "elevated";
+        high: "high";
+        routine: "routine";
+    }>;
+    qualityMode: z.ZodEnum<{
+        default: "default";
+        strict: "strict";
+    }>;
+    publication: z.ZodEnum<{
+        automerge: "automerge";
+        none: "none";
+        notify: "notify";
+    }>;
+    evidence: z.ZodArray<z.ZodEnum<{
+        "changed-path": "changed-path";
+        check: "check";
+        "manual-review": "manual-review";
+        screenshot: "screenshot";
+    }>>;
+    posture: z.ZodEnum<{
+        economy: "economy";
+        strong: "strong";
+    }>;
+    demands: z.ZodArray<z.ZodString>;
+    legs: z.ZodArray<z.ZodObject<{
+        phase: z.ZodEnum<{
+            build: "build";
+            plan: "plan";
+            repair: "repair";
+            review: "review";
+        }>;
+        provider: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            gemini: "gemini";
+            openrouter: "openrouter";
+        }>;
+        model: z.ZodString;
+        tier: z.ZodEnum<{
+            routine: "routine";
+            strong: "strong";
+        }>;
+        chosen: z.ZodEnum<{
+            override: "override";
+            pinned: "pinned";
+            recommended: "recommended";
+        }>;
+        recommended: z.ZodObject<{
+            provider: z.ZodEnum<{
+                claude: "claude";
+                codex: "codex";
+                gemini: "gemini";
+                openrouter: "openrouter";
+            }>;
+            model: z.ZodString;
+            tier: z.ZodEnum<{
+                routine: "routine";
+                strong: "strong";
+            }>;
+        }, z.core.$strict>;
+        reasons: z.ZodArray<z.ZodString>;
+        problem: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    overrides: z.ZodArray<z.ZodObject<{
+        phase: z.ZodEnum<{
+            build: "build";
+            plan: "plan";
+            repair: "repair";
+            review: "review";
+        }>;
+        provider: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            gemini: "gemini";
+            openrouter: "openrouter";
+        }>;
+        model: z.ZodString;
+        by: z.ZodString;
+        at: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const sealedRouteV2Schema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    risk: z.ZodEnum<{
+        elevated: "elevated";
+        high: "high";
+        routine: "routine";
+    }>;
+    qualityMode: z.ZodEnum<{
+        default: "default";
+        strict: "strict";
+    }>;
+    publication: z.ZodEnum<{
+        automerge: "automerge";
+        none: "none";
+        notify: "notify";
+    }>;
+    evidence: z.ZodArray<z.ZodEnum<{
+        "changed-path": "changed-path";
+        check: "check";
+        "manual-review": "manual-review";
+        screenshot: "screenshot";
+    }>>;
+    posture: z.ZodEnum<{
+        economy: "economy";
+        strong: "strong";
+    }>;
+    demands: z.ZodArray<z.ZodString>;
+    legs: z.ZodArray<z.ZodObject<{
+        phase: z.ZodEnum<{
+            build: "build";
+            plan: "plan";
+            repair: "repair";
+            review: "review";
+        }>;
+        provider: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            gemini: "gemini";
+            openrouter: "openrouter";
+        }>;
+        model: z.ZodString;
+        tier: z.ZodEnum<{
+            light: "light";
+            routine: "routine";
+            strong: "strong";
+        }>;
+        chosen: z.ZodEnum<{
+            override: "override";
+            pinned: "pinned";
+            recommended: "recommended";
+        }>;
+        recommended: z.ZodObject<{
+            provider: z.ZodEnum<{
+                claude: "claude";
+                codex: "codex";
+                gemini: "gemini";
+                openrouter: "openrouter";
+            }>;
+            model: z.ZodString;
+            tier: z.ZodEnum<{
+                light: "light";
+                routine: "routine";
+                strong: "strong";
+            }>;
+        }, z.core.$strict>;
+        reasons: z.ZodArray<z.ZodString>;
+        problem: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    overrides: z.ZodArray<z.ZodObject<{
+        phase: z.ZodEnum<{
+            build: "build";
+            plan: "plan";
+            repair: "repair";
+            review: "review";
+        }>;
+        provider: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            gemini: "gemini";
+            openrouter: "openrouter";
+        }>;
+        model: z.ZodString;
+        by: z.ZodString;
+        at: z.ZodString;
+    }, z.core.$strict>>;
+    size: z.ZodNullable<z.ZodObject<{
+        size: z.ZodEnum<{
+            large: "large";
+            medium: "medium";
+            small: "small";
+        }>;
+        risky: z.ZodBoolean;
+        source: z.ZodEnum<{
+            classifier: "classifier";
+            heuristic: "heuristic";
+            person: "person";
+        }>;
+        reason: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** A sealed route as saved, in either version. */
+export declare const sealedRouteSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    risk: z.ZodEnum<{
+        elevated: "elevated";
+        high: "high";
+        routine: "routine";
+    }>;
+    qualityMode: z.ZodEnum<{
+        default: "default";
+        strict: "strict";
+    }>;
+    publication: z.ZodEnum<{
+        automerge: "automerge";
+        none: "none";
+        notify: "notify";
+    }>;
+    evidence: z.ZodArray<z.ZodEnum<{
+        "changed-path": "changed-path";
+        check: "check";
+        "manual-review": "manual-review";
+        screenshot: "screenshot";
+    }>>;
+    posture: z.ZodEnum<{
+        economy: "economy";
+        strong: "strong";
+    }>;
+    demands: z.ZodArray<z.ZodString>;
+    legs: z.ZodArray<z.ZodObject<{
+        phase: z.ZodEnum<{
+            build: "build";
+            plan: "plan";
+            repair: "repair";
+            review: "review";
+        }>;
+        provider: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            gemini: "gemini";
+            openrouter: "openrouter";
+        }>;
+        model: z.ZodString;
+        tier: z.ZodEnum<{
+            routine: "routine";
+            strong: "strong";
+        }>;
+        chosen: z.ZodEnum<{
+            override: "override";
+            pinned: "pinned";
+            recommended: "recommended";
+        }>;
+        recommended: z.ZodObject<{
+            provider: z.ZodEnum<{
+                claude: "claude";
+                codex: "codex";
+                gemini: "gemini";
+                openrouter: "openrouter";
+            }>;
+            model: z.ZodString;
+            tier: z.ZodEnum<{
+                routine: "routine";
+                strong: "strong";
+            }>;
+        }, z.core.$strict>;
+        reasons: z.ZodArray<z.ZodString>;
+        problem: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    overrides: z.ZodArray<z.ZodObject<{
+        phase: z.ZodEnum<{
+            build: "build";
+            plan: "plan";
+            repair: "repair";
+            review: "review";
+        }>;
+        provider: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            gemini: "gemini";
+            openrouter: "openrouter";
+        }>;
+        model: z.ZodString;
+        by: z.ZodString;
+        at: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    risk: z.ZodEnum<{
+        elevated: "elevated";
+        high: "high";
+        routine: "routine";
+    }>;
+    qualityMode: z.ZodEnum<{
+        default: "default";
+        strict: "strict";
+    }>;
+    publication: z.ZodEnum<{
+        automerge: "automerge";
+        none: "none";
+        notify: "notify";
+    }>;
+    evidence: z.ZodArray<z.ZodEnum<{
+        "changed-path": "changed-path";
+        check: "check";
+        "manual-review": "manual-review";
+        screenshot: "screenshot";
+    }>>;
+    posture: z.ZodEnum<{
+        economy: "economy";
+        strong: "strong";
+    }>;
+    demands: z.ZodArray<z.ZodString>;
+    legs: z.ZodArray<z.ZodObject<{
+        phase: z.ZodEnum<{
+            build: "build";
+            plan: "plan";
+            repair: "repair";
+            review: "review";
+        }>;
+        provider: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            gemini: "gemini";
+            openrouter: "openrouter";
+        }>;
+        model: z.ZodString;
+        tier: z.ZodEnum<{
+            light: "light";
+            routine: "routine";
+            strong: "strong";
+        }>;
+        chosen: z.ZodEnum<{
+            override: "override";
+            pinned: "pinned";
+            recommended: "recommended";
+        }>;
+        recommended: z.ZodObject<{
+            provider: z.ZodEnum<{
+                claude: "claude";
+                codex: "codex";
+                gemini: "gemini";
+                openrouter: "openrouter";
+            }>;
+            model: z.ZodString;
+            tier: z.ZodEnum<{
+                light: "light";
+                routine: "routine";
+                strong: "strong";
+            }>;
+        }, z.core.$strict>;
+        reasons: z.ZodArray<z.ZodString>;
+        problem: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    overrides: z.ZodArray<z.ZodObject<{
+        phase: z.ZodEnum<{
+            build: "build";
+            plan: "plan";
+            repair: "repair";
+            review: "review";
+        }>;
+        provider: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            gemini: "gemini";
+            openrouter: "openrouter";
+        }>;
+        model: z.ZodString;
+        by: z.ZodString;
+        at: z.ZodString;
+    }, z.core.$strict>>;
+    size: z.ZodNullable<z.ZodObject<{
+        size: z.ZodEnum<{
+            large: "large";
+            medium: "medium";
+            small: "small";
+        }>;
+        risky: z.ZodBoolean;
+        source: z.ZodEnum<{
+            classifier: "classifier";
+            heuristic: "heuristic";
+            person: "person";
+        }>;
+        reason: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "version">;
+export type SealedRoute = z.infer<typeof sealedRouteSchema>;
+export type RouteVersion = SealedRoute["version"];
+export type RouteLeg = z.infer<typeof routeLegSchema>;
+export type RouteOverride = z.infer<typeof routeOverrideSchema>;
+export type TaskSizing = z.infer<typeof taskSizingSchema>;
+/** A route as every reader returns it: a version 1 route reads with no size. */
+export type PhaseRoute = Omit<z.infer<typeof sealedRouteV2Schema>, "version"> & {
+    version: RouteVersion;
+};
+/** The posture legs actually run under: strong only when a leg runs a configured strong agent as recommended. */
+export declare function postureOf(legs: readonly Pick<RouteLeg, "chosen" | "tier">[]): "economy" | "strong";
+/** Read a task's recorded override list (a list on its own, as `route_overrides_json` keeps it). */
+export declare function readRouteOverrides(input: unknown): ContractResult<RouteOverride[]>;
+/** Read a sealed route: either version as itself, every leg, override and the size proved, nothing unknown. */
+export declare function readSealedRoute(input: unknown): ContractResult<PhaseRoute>;