toolroll 0.9.34 → 0.9.37

package/dist/memory-pass.js

@@ -19,10 +19,17 @@ import { changeKnowledge, knowledgeView } from './project-knowledge.js';
 import { listDecisions, recordDecision } from './project-memory.js';
 import { composeMateRequest, performMateRequest, isDirectChatProvider, CHAT_KEY_ENV } from './converse.js';
 import { performSubscriptionMateRequest } from './subscription-chat.js';
-export const MEMORY_TRACE_BYTES = 40_000;
+import { TEXT_LIMITS } from './text-limits.js';
+import { contractError, parseContract } from './contracts/contract.js';
+import { MEMORY_VERDICT_MODEL_SCHEMA, MEMORY_VERDICT_VERSION, memoryEvidenceSchema, memoryProposalSchema, memoryVerdictReadSchema, readSavedVerdict, savedVerdictSchema } from './contracts/memory-pass.js';
+/** One session's trace, in characters (TEXT_LIMITS.memoryTrace). */
+export const MEMORY_TRACE_BYTES = TEXT_LIMITS.memoryTrace;
 export const MEMORY_MIN_SESSIONS = 2;
 export const MEMORY_MAX_PROPOSALS = 6;
-export const INSTRUCTION_BUDGET_BYTES = 4000;
+/** The project instructions' budget: the same limit knowledge holds them to. */
+export const INSTRUCTION_BUDGET_BYTES = TEXT_LIMITS.knowledgeInstructionsBytes;
+/** How many claims of each kind one verdict keeps. */
+const VERDICT_ITEMS = 20;
 export const MEMORY_GAP_MAX_AGE_MS = 90 * 24 * 3_600_000;
 const sha = (text) => createHash('sha256').update(text).digest('hex');
 /** The Claude Code project directory for a checkout: the path with every slash turned into a dash. */
@@ -174,7 +181,7 @@ export function analysisPrompt(surface, openGaps) {
         'INSTRUCTIONS (refer to them ONLY by id):', ...surface.instructions.map(i => `[${i.id}] ${i.text}`),
         'DECISIONS on record (refer by id):', ...surface.decisions.map(d => `[${d.id}] ${d.claim}`),
         'GAPS ALREADY ON THE BOOKS (cite the key in matchesGap when the same underlying gap):', ...openGaps.map(g => `[${g.key}] ${g.mistake}`),
-        'Return ONE JSON object and nothing else: {"positive":[{"instruction":"IN-001","effect":"...","quote":"verbatim"}],"negative":[{"instruction":"IN-001","effect":"...","class":"harm|non-compliance|irrelevant","quote":"verbatim"}],"gaps":[{"mistake":"...","proposedInstruction":"one imperative sentence","domain":"project|orchestration","quote":"verbatim","matchesGap":"key when known"}]}',
+        `Return ONE JSON object and nothing else, matching this JSON Schema: ${JSON.stringify(MEMORY_VERDICT_MODEL_SCHEMA)}`,
         'Rules: every item needs a verbatim quote copied from the trace or it is discarded; negative evidence outranks positive; class harm means following the instruction caused damage, non-compliance means it was ignored; a mistake caused by the harness or task framing is domain orchestration; report nothing rather than something weak; an empty array is a good answer.',
     ].join('\n');
 }
@@ -204,31 +211,43 @@ export function defaultAnalyzer(store, options) {
             const answer = await performMateRequest(request, config.provider, AbortSignal.timeout(options.timeoutMs ?? 120_000), options.fetcher);
             return answer.ok ? { ok: true, text: answer.answer.text } : { ok: false, problem: answer.problem };
         }
-        const answer = await performSubscriptionMateRequest({ provider: config.provider, model: config.model, system, dataDocument, history, tools: [], timeoutMs: options.timeoutMs ?? 180_000 }, options.runner);
+        // The verdict's own schema is the harness's structured output, so the answer is the verdict itself.
+        const answer = await performSubscriptionMateRequest({ provider: config.provider, model: config.model, system, dataDocument, history, tools: [], outputSchema: MEMORY_VERDICT_MODEL_SCHEMA, timeoutMs: options.timeoutMs ?? 180_000 }, options.runner);
         return answer.ok ? { ok: true, text: answer.answer.text } : { ok: false, problem: answer.problem };
     };
 }
-/** Parse strictly and keep only claims whose quote is really in the trace. */
+const UNREADABLE = 'The analysis was not a readable verdict.';
+/**
+ * Read the analyser's answer with the tolerant parse-side schema, then keep only claims whose quote
+ * is really in the trace and, for an instruction's effect, whose id is on the surface audited.
+ */
 export function parseVerdict(text, trace, surface) {
     const start = text.indexOf('{'), end = text.lastIndexOf('}');
     if (start < 0 || end <= start)
-        return null;
+        return { ok: false, problem: UNREADABLE };
     let raw;
     try {
-        raw = obj(JSON.parse(text.slice(start, end + 1)));
+        raw = JSON.parse(text.slice(start, end + 1));
     }
     catch {
-        return null;
+        return { ok: false, problem: UNREADABLE };
     }
+    const read = parseContract(memoryVerdictReadSchema, raw);
+    if (!read.ok)
+        return { ok: false, problem: `${UNREADABLE.slice(0, -1)}: ${read.issues.slice(0, 5).map(issue => issue.line).join('; ')}` };
     const ids = new Set(surface.instructions.map(i => i.id));
-    const quoted = (item) => typeof item['quote'] === 'string' && item['quote'].trim().length >= 12 && trace.includes(item['quote'].trim());
-    const list = (key) => (Array.isArray(raw[key]) ? raw[key].map(obj) : []).filter(quoted).slice(0, 20);
-    return {
-        positive: list('positive').filter(i => ids.has(String(i['instruction']))).map(i => ({ instruction: String(i['instruction']), effect: clip(String(i['effect'] ?? ''), 300), quote: String(i['quote']).trim() })),
-        negative: list('negative').filter(i => ids.has(String(i['instruction'])) && ['harm', 'non-compliance', 'irrelevant'].includes(String(i['class']))).map(i => ({ instruction: String(i['instruction']), effect: clip(String(i['effect'] ?? ''), 300), class: i['class'], quote: String(i['quote']).trim() })),
-        gaps: list('gaps').filter(i => typeof i['mistake'] === 'string' && typeof i['proposedInstruction'] === 'string').map(i => ({ mistake: clip(String(i['mistake']), 300), proposedInstruction: clip(String(i['proposedInstruction']), 240), domain: i['domain'] === 'orchestration' ? 'orchestration' : 'project', quote: String(i['quote']).trim(), ...(typeof i['matchesGap'] === 'string' ? { matchesGap: i['matchesGap'] } : {}) })),
-    };
+    const quoted = (item) => item.quote.trim().length >= 12 && trace.includes(item.quote.trim());
+    const list = (items) => items
+        .filter(item => item !== null && quoted(item)).slice(0, VERDICT_ITEMS)
+        .flatMap(item => item === null || item.claim === null ? [] : [{ ...item.claim, quote: item.quote.trim() }]);
+    return { ok: true, verdict: {
+            positive: list(read.value.positive).filter(i => ids.has(i.instruction)),
+            negative: list(read.value.negative).filter(i => ids.has(i.instruction)),
+            gaps: list(read.value.gaps),
+        } };
 }
+/** A verdict as a session keeps it: through its schema, with its version. */
+const keptVerdict = (verdict) => JSON.stringify(savedVerdictSchema.parse({ version: MEMORY_VERDICT_VERSION, ...verdict }));
 const gapKey = (mistake) => sha(mistake.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim()).slice(0, 16);
 /**
  * Collect, distil, analyse and aggregate for one project. Never writes memory:
@@ -263,20 +282,21 @@ export async function runMemoryPass(store, args, now = new Date()) {
       ON CONFLICT(id) DO UPDATE SET surface=excluded.surface, trace_sha=excluded.trace_sha, analyzed_at=NULL, verdict=NULL, problem=NULL`).run(session.id, args.repo, session.kind, session.source, session.at || now.toISOString(), surface.version, sha(trace));
         const gaps = openGaps();
         const answer = await args.analyzer({ trace, surface, openGaps: gaps, kind: session.kind });
-        const verdict = answer.ok ? parseVerdict(answer.text, trace, surface) : null;
-        if (verdict === null) {
+        const parsed = answer.ok ? parseVerdict(answer.text, trace, surface) : null;
+        if (parsed === null || !parsed.ok) {
             report.failed++;
-            const problem = answer.ok ? 'The analysis was not a readable verdict.' : answer.problem;
+            const problem = parsed === null ? (answer.ok ? UNREADABLE : answer.problem) : parsed.problem;
             report.problems.push(`${session.id}: ${problem}`);
             store.handle.prepare('UPDATE memory_session SET problem=? WHERE id=?').run(problem, session.id);
             continue;
         }
+        const verdict = parsed.verdict;
         store.transact(() => {
-            store.handle.prepare('UPDATE memory_session SET analyzed_at=?, verdict=?, problem=NULL WHERE id=?').run(now.toISOString(), JSON.stringify(verdict), session.id);
+            store.handle.prepare('UPDATE memory_session SET analyzed_at=?, verdict=?, problem=NULL WHERE id=?').run(now.toISOString(), keptVerdict(verdict), session.id);
             for (const gap of verdict.gaps) {
                 if (gap.domain === 'orchestration')
                     continue;
-                const key = gap.matchesGap !== undefined && gaps.some(g => g.key === gap.matchesGap) ? gap.matchesGap : gapKey(gap.mistake);
+                const key = gap.matchesGap !== null && gaps.some(g => g.key === gap.matchesGap) ? gap.matchesGap : gapKey(gap.mistake);
                 store.handle.prepare(`INSERT INTO memory_gap(repo,key,mistake,proposed,domain,first_seen,last_seen) VALUES (?,?,?,?,?,?,?)
           ON CONFLICT(repo,key) DO UPDATE SET last_seen=excluded.last_seen, retired_at=NULL, retired_reason=NULL`).run(args.repo, key, gap.mistake, gap.proposedInstruction, gap.domain, now.toISOString(), now.toISOString());
                 const id = Number(store.handle.prepare('SELECT id FROM memory_gap WHERE repo=? AND key=?').get(args.repo, key)['id']);
@@ -289,10 +309,15 @@ export async function runMemoryPass(store, args, now = new Date()) {
     report.proposals = synthesizeProposals(store, args.repo, args.actor, surface, now);
     return report;
 }
+// ---- 4. propose --------------------------------------------------------------------
+/** A proposal row through its schema; one that does not read as a proposal names the field. */
 function proposalOf(row) {
-    return { id: Number(row['id']), repo: String(row['repo']), kind: row['kind'], fingerprint: String(row['fingerprint']), title: String(row['title']), rationale: String(row['rationale']),
+    const read = memoryProposalSchema.safeParse({ id: Number(row['id']), repo: String(row['repo']), kind: row['kind'], fingerprint: String(row['fingerprint']), title: String(row['title']), rationale: String(row['rationale']),
         beforeText: row['before_text'] === null ? null : String(row['before_text']), afterText: String(row['after_text']), evidence: JSON.parse(String(row['evidence'])),
-        sessions: Number(row['sessions']), status: String(row['status']), createdAt: String(row['created_at']), surface: String(row['surface']) };
+        sessions: Number(row['sessions']), status: String(row['status']), createdAt: String(row['created_at']), surface: String(row['surface']) }, { reportInput: true });
+    if (!read.success)
+        throw Error(`Memory proposal ${String(row['id'])} could not be read: ${contractError(read.error).join('; ')}`);
+    return read.data;
 }
 /**
  * Turn corroborated gaps and harm into a few proposals: an addition needs
@@ -317,7 +342,7 @@ export function synthesizeProposals(store, repo, actor, surface, now = new Date(
             if (sessions < MEMORY_MIN_SESSIONS || (rejected.get(fingerprint) ?? -1) >= sessions)
                 return;
             store.handle.prepare('INSERT INTO memory_proposal(repo,kind,fingerprint,title,rationale,before_text,after_text,evidence,sessions,status,created_at,surface) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)')
-                .run(repo, kind, fingerprint, title, rationale, beforeText, afterText, JSON.stringify(evidence.slice(0, 6)), sessions, 'pending', now.toISOString(), surface.version);
+                .run(repo, kind, fingerprint, title, rationale, beforeText, afterText, JSON.stringify(memoryEvidenceSchema.parse(evidence.slice(0, 6))), sessions, 'pending', now.toISOString(), surface.version);
             pendingFingerprints.add(fingerprint);
             made++;
         };
@@ -342,14 +367,17 @@ export function synthesizeProposals(store, repo, actor, surface, now = new Date(
         // Removals from harm.
         const harm = new Map();
         for (const row of store.handle.prepare("SELECT id, verdict FROM memory_session WHERE repo=? AND surface=? AND verdict IS NOT NULL").all(repo, surface.version)) {
-            let verdict;
+            let kept;
             try {
-                verdict = JSON.parse(String(row['verdict']));
+                kept = JSON.parse(String(row['verdict']));
             }
             catch {
                 continue;
             }
-            for (const item of verdict.negative)
+            const verdict = readSavedVerdict(kept);
+            if (!verdict.ok)
+                continue;
+            for (const item of verdict.value.negative)
                 if (item.class === 'harm')
                     harm.set(item.instruction, [...(harm.get(item.instruction) ?? []), { session: String(row['id']), quote: item.quote }]);
         }

package/dist/operate.js

@@ -53,6 +53,7 @@ import { FLOWS_VALUE_FLAGS, runFlowsCommand } from "./flows-cli.js";
 import { runAssignmentCommand } from "./assignment-adapters.js";
 import { applyProjectProfile, runProjectCommand } from "./project-cli.js";
 import { pullRequestLines, runTaskMergeCommand, runTaskOutcomeCommand } from "./task-outcome-cli.js";
+import { taskReviewBrief, renderReviewBrief } from "./task-review-brief.js";
 /**
  * The commands that actually move work: authoring tasks, and the claim loop.
  *
@@ -261,6 +262,7 @@ export const OPERATE_HELP = `toolroll — operating the queue
   toolroll backup now|list          back the database up now; list backups and how the last ones went
   toolroll restore <file> [--dry-run]  put a backup back (Toolroll stopped; the current database is kept)
   toolroll review show|on|off --repo <path>  one automatic review of each finished build; only HIGH findings send it back
+  toolroll task review <id> --brief   compact saved result, checks and findings; --run <id>, --all, --json
   toolroll policy show|set          the organisation policy; an instance operator sets it with --providers claude,codex|any,
                                         --models <m,…>|any, --tools <t,…>|any, --ceiling safe|standard|escalated
   toolroll ledger verify             check the action ledger's hash chain (--checkpoint <n:hash> to compare a copied head)
@@ -665,7 +667,7 @@ export const OPERATE_VALUE_FLAGS = new Set([
     "task",
 ]);
 export const OPERATE_BOOLEAN_FLAGS = new Set([
-    "json", "yes", "all", "local", "history", "latest-watch", "dry-run", "file", "allow-paid-fallback",
+    "json", "yes", "all", "brief", "local", "history", "latest-watch", "dry-run", "file", "allow-paid-fallback",
     "clear", "follow", "ready", "all-tasks", "inbound-only", "help", "undo", "anyone", "allow-dispatch", "allow-merge", "merge-delete-branch",
     "no-open", "remove", "no-verify", "no-follow", "end", "report", "off", "tmux",
     "self-heal", "plan-auto", "chat-approve", "repair-auto", "review-retry-auto", "no-local",
@@ -5171,9 +5173,36 @@ async function planTaskCommand(positional, flags, context) {
         autoPlan ? "An unchanged, verified plan can auto-approve under your signed mode. Amendments and questions still wait for you." : "Its questions reach you like any decision; its plan lands as a scope for you to edit and approve.",
     ]);
 }
-/** The retired command is a typed refusal, never a new provider request. */
+/** Read saved work; neither form requests a new provider review. */
 async function reviewTaskCommand(positional, flags, context) {
     const { store, write, json } = context;
+    if (flags.has("brief")) {
+        const allowed = new Set(["brief", "all", "run", "json", "db", "as", "token"]);
+        for (const name of flags.keys())
+            if (!allowed.has(name))
+                return fail(write, json, "task review", "usage", `--${name} is not a task review --brief option.`, EXIT.usage);
+        const task = positional[0], selected = flags.get("run");
+        if (positional.length !== 1 || !task || task.length > 64 || /[\x00-\x1f\x7f]/.test(task) ||
+            selected !== undefined && (typeof selected !== "string" || !/^[1-9]\d*$/.test(selected) || !Number.isSafeInteger(Number(selected)))) {
+            return fail(write, json, "task review", "usage", "Use toolroll task review <task> --brief [--run <id>] [--all] [--json].", EXIT.usage);
+        }
+        // The normal CLI entry has already authenticated lead tokens. Local reads
+        // stay available; a signed-in lead sees only its owner's admitted projects.
+        let viewer = currentActor()?.account ?? null;
+        if (viewer === null && (flags.has("as") || flags.has("token"))) {
+            const acting = await askCredentials(flags, context);
+            if (acting === null || !authenticateApprover(store, acting.name, acting.token).ok)
+                return fail(write, json, "task review", "unauthenticated", "That sign-in is not valid.", EXIT.refused);
+            viewer = acting.name;
+        }
+        const repos = viewer === null ? null : store.knownRepos().filter(repo => store.accountCanAccess(viewer, repo));
+        const result = taskReviewBrief(store, task, context.evidenceRoot, context.now, { principal: "operator", repos, includeUnplaced: viewer === null }, { ...(selected === undefined ? {} : { run: Number(selected) }), all: flags.has("all"), secrets: [context.leadToken ?? "", text(flags, "token") ?? ""] });
+        if (!result.ok)
+            return fail(write, json, "task review", result.reason, result.message, EXIT.refused);
+        return succeed(write, json, "task review", { brief: result.brief }, () => renderReviewBrief(result.brief));
+    }
+    if (flags.has("run") || flags.has("all"))
+        return fail(write, json, "task review", "usage", "--run and --all require --brief.", EXIT.usage);
     const [runText] = positional;
     const runId = Number(runText ?? "");
     if (runText === undefined || !Number.isInteger(runId) || runId < 1) {

package/dist/phase-routing.d.ts

@@ -45,22 +45,21 @@
  * sealed route. Only a row proven to predate v47 (no route era) reads as
  * a legacy approval governed by its sealed profile alone.
  */
+import type { EvidenceKind } from "./contracts/acceptance-terms.js";
+import { MODEL_ID_SHAPE, RISKS, ROUTE_VERSION, type PhaseRoute, type RouteLeg, type RouteOverride, type RouteVersion, type TaskSizing } from "./contracts/route.js";
 import type { Phase, ProviderId } from "./provider.js";
 import type { QualityMode } from "./quality.js";
+/** The sealed route's shape is its contract (contracts/route.ts); these are its types. */
+export type { PhaseRoute, RouteLeg, RouteOverride, RouteVersion, TaskSizing };
+export { MODEL_ID_SHAPE };
 export declare const PROVIDER_ID_LIST: readonly ProviderId[];
-/** provider.ts's MODEL_ID, restated for the same reason and pinned by the
- * same test: an exact model id is argv-safe — no leading dash, no
- * whitespace or control bytes — or it is not a model id this policy can
- * seal, stamp, or rehydrate. */
-export declare const MODEL_ID_SHAPE: RegExp;
 /** The same exactness for callers outside this policy (the profile
  * rehydrator): one shape, one definition. */
 export declare function exactModelId(v: unknown): v is string;
 /** v2 adds the task's size (small / medium / large, risky or not), the
  * light tier, and plan headroom. A v1 route — sealed before sizing — still
  * reads back exactly and keeps its own digest domain. */
-export declare const ROUTE_VERSION = 2;
-export type RouteVersion = 1 | 2;
+export { ROUTE_VERSION };
 /** The durable route ERA a scope row carries once it was filed under this
  * policy: NULL on a row proven to predate v47 (legacy — the sealed profile
  * alone governs), this value on every row filed since. A row with an era
@@ -70,27 +69,21 @@ export declare const ROUTE_ERA = 1;
 export declare const PHASES: readonly Phase[];
 /** The review leg remains readable in signed history but is no longer scheduled. */
 export declare const ACTIVE_PHASES: readonly Phase[];
-export type RiskLevel = "routine" | "elevated" | "high";
+export type RiskLevel = (typeof RISKS)[number];
 export declare const RISK_LEVELS: readonly RiskLevel[];
 export declare function isRiskLevel(value: unknown): value is RiskLevel;
 /** How big a change the task is, sized once at filing (by the classifier,
  * by the description when it cannot answer, or by a person). */
-export type TaskSize = "small" | "medium" | "large";
+export type TaskSize = TaskSizing["size"];
 export declare const TASK_SIZES: readonly TaskSize[];
-export type SizeSource = "classifier" | "heuristic" | "person";
-export type TaskSizing = {
-    size: TaskSize;
-    risky: boolean;
-    source: SizeSource;
-    reason: string;
-};
+export type SizeSource = TaskSizing["source"];
 export declare function isTaskSize(value: unknown): value is TaskSize;
 /** Whether a task makes no plan: a small change that is not risky, at
  * routine risk. Elevated or high risk always plans, whatever the size. */
 export declare function makesNoPlan(size: TaskSizing | null | undefined, risk: RiskLevel): boolean;
 /** Where a size came from, in words. */
 export declare function sizeSourceWords(source: SizeSource): string;
-/** Strict read of a stored sizing: exact keys, known words, bounded reason. */
+/** Strict read of a stored sizing (the route contract's): exact keys, known words, bounded reason. */
 export declare function parseSizing(raw: unknown): TaskSizing | null;
 export declare function riskTitle(risk: RiskLevel): string;
 /**
@@ -159,16 +152,9 @@ export type RouteCandidates = {
     repair: RepairCandidates;
     review: PhaseCandidates;
 };
-/** An approver's explicit per-phase choice, recorded with attribution.
- * Always an exact pair. */
-export type RouteOverride = ExactSpec & {
-    phase: Phase;
-    by: string;
-    at: string;
-};
 /** The evidence kinds an acceptance rubric demands — `scope.ts` owns the
  * full type; the policy only needs the names. */
-export type RouteEvidenceKind = "check" | "screenshot" | "changed-path" | "manual-review";
+export type RouteEvidenceKind = EvidenceKind;
 /** How far the plane may carry a result without a person: no publication
  * grant at all, a grant whose merges wait for a human (notify), or a live
  * mode that merges by itself (automerge). */
@@ -220,48 +206,6 @@ export type RouteInput = {
      * provider past its limits gives way even to a stronger tier. */
     headroom?: readonly ProviderRoom[];
 };
-export type RouteLeg = {
-    phase: Phase;
-    provider: ProviderId;
-    /** The exact model id this leg runs — never null on a frozen route. */
-    model: string;
-    /** The tier the recommendation drew from; an override or pin still
-     * records what tier the policy would have used. */
-    tier: CandidateTier;
-    chosen: "recommended" | "override" | "pinned";
-    /** What the policy recommended before any override or pin — shown so an
-     * overridden leg can say what it replaced. */
-    recommended: {
-        provider: ProviderId;
-        model: string;
-        tier: CandidateTier;
-    };
-    /** Plain-English, ordered, deterministic. */
-    reasons: string[];
-    /** A configuration that cannot run this leg at all (gemini on review,
-     * cross-provider repair) — stated, never repaired by substitution; a
-     * route with any problem files its scope unresolved. */
-    problem: string | null;
-};
-export type PhaseRoute = {
-    version: RouteVersion;
-    risk: RiskLevel;
-    qualityMode: QualityMode;
-    publication: PublicationAuthority;
-    evidence: RouteEvidenceKind[];
-    /** The posture the route ACTUALLY runs under: "strong" only when at
-     * least one leg draws from a configured strong agent; "economy" when
-     * every selected agent is the routine one — however demanding the task,
-     * a route that keeps every default never claims stronger agents. */
-    posture: "economy" | "strong";
-    /** Why a stronger tier was wanted, in order (empty for a routine task). */
-    demands: string[];
-    legs: RouteLeg[];
-    overrides: RouteOverride[];
-    /** The task's size as it was routed (v2); null on a v1 route or an
-     * unsized task. */
-    size: TaskSizing | null;
-};
 export declare function specWords(spec: {
     provider: string;
     model: string;
@@ -291,12 +235,15 @@ export declare function canonicalRouteJson(route: PhaseRoute): string;
  * same 128 bits every other safety digest here uses. Its own domain, so a
  * route digest can never collide with a profile or chain digest. */
 export declare function routeDigestOf(route: PhaseRoute): string;
-/** Strict rehydration of a stored route — every field type-proved, every
- * model an exact non-empty string; anything unexpected is null, never a
- * guess. A null from a row that carries a route era is a corrupt seal. */
+/** Strict rehydration of a stored route through the route contract — every
+ * field type-proved, every model an exact non-empty string, nothing unknown;
+ * anything unexpected is null, never a guess. A null from a row that carries
+ * a route era is a corrupt seal. */
 export declare function routeFromJson(json: string | null): PhaseRoute | null;
-/** Strict parse of an override list: one per phase, every field proved,
- * every model exact. */
+/** Why a stored route does not read, as path-named lines (`legs[1].model: …`); null when it reads. */
+export declare function routeJsonProblem(json: string): string | null;
+/** Strict parse of an override list (the route contract's): one per phase,
+ * every field proved, every model exact, in phase order. */
 export declare function parseOverrides(raw: unknown): RouteOverride[] | null;
 /** The stored override list (a task-level column). Malformed reads as
  * null — the caller files the scope unresolved rather than routing as if

package/dist/phase-routing.js

@@ -46,19 +46,16 @@
  * a legacy approval governed by its sealed profile alone.
  */
 import { createHash } from "node:crypto";
-// Type-only imports above: provider.ts sits under evidence.ts and scope.ts
+import { MODEL_ID_SHAPE, postureOf, readRouteOverrides, readSealedRoute, RISKS, ROUTE_PHASES, ROUTE_PROVIDERS, ROUTE_VERSION, TASK_SIZE_WORDS, taskSizingSchema, } from "./contracts/route.js";
+export { MODEL_ID_SHAPE };
+// Type-only imports from provider.ts: it sits under evidence.ts and scope.ts
 // in the module graph, and this policy is imported by scope.ts — a value
-// import would be a cycle at load time. The id list is restated here and
-// pinned to provider.ts's by the test suite.
-export const PROVIDER_ID_LIST = ["claude", "codex", "openrouter", "gemini"];
+// import would be a cycle at load time. The route contract restates the id
+// list, pinned to provider.ts's by the test suite.
+export const PROVIDER_ID_LIST = ROUTE_PROVIDERS;
 function isProviderId(value) {
     return PROVIDER_ID_LIST.includes(value);
 }
-/** provider.ts's MODEL_ID, restated for the same reason and pinned by the
- * same test: an exact model id is argv-safe — no leading dash, no
- * whitespace or control bytes — or it is not a model id this policy can
- * seal, stamp, or rehydrate. */
-export const MODEL_ID_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/;
 function exactModel(v) {
     return typeof v === "string" && MODEL_ID_SHAPE.test(v);
 }
@@ -70,21 +67,21 @@ export function exactModelId(v) {
 /** v2 adds the task's size (small / medium / large, risky or not), the
  * light tier, and plan headroom. A v1 route — sealed before sizing — still
  * reads back exactly and keeps its own digest domain. */
-export const ROUTE_VERSION = 2;
+export { ROUTE_VERSION };
 /** The durable route ERA a scope row carries once it was filed under this
  * policy: NULL on a row proven to predate v47 (legacy — the sealed profile
  * alone governs), this value on every row filed since. A row with an era
  * and no readable route is corrupt and fails closed. The era marks a ROUTED
  * row; which route version it holds rides in the snapshot itself. */
 export const ROUTE_ERA = 1;
-export const PHASES = ["plan", "build", "repair", "review"];
+export const PHASES = ROUTE_PHASES;
 /** The review leg remains readable in signed history but is no longer scheduled. */
 export const ACTIVE_PHASES = ["plan", "build", "repair"];
-export const RISK_LEVELS = ["routine", "elevated", "high"];
+export const RISK_LEVELS = RISKS;
 export function isRiskLevel(value) {
     return value === "routine" || value === "elevated" || value === "high";
 }
-export const TASK_SIZES = ["small", "medium", "large"];
+export const TASK_SIZES = TASK_SIZE_WORDS;
 export function isTaskSize(value) {
     return value === "small" || value === "medium" || value === "large";
 }
@@ -97,20 +94,10 @@ export function makesNoPlan(size, risk) {
 export function sizeSourceWords(source) {
     return source === "classifier" ? "sized automatically" : source === "person" ? "set by a person" : "sized from the description";
 }
-/** Strict read of a stored sizing: exact keys, known words, bounded reason. */
+/** Strict read of a stored sizing (the route contract's): exact keys, known words, bounded reason. */
 export function parseSizing(raw) {
-    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
-        return null;
-    const v = raw;
-    if (!exactKeysOf(v, ["size", "risky", "source", "reason"]))
-        return null;
-    if (!isTaskSize(v["size"]) || typeof v["risky"] !== "boolean")
-        return null;
-    if (v["source"] !== "classifier" && v["source"] !== "heuristic" && v["source"] !== "person")
-        return null;
-    if (typeof v["reason"] !== "string" || v["reason"].length > 300)
-        return null;
-    return { size: v["size"], risky: v["risky"], source: v["source"], reason: v["reason"] };
+    const parsed = taskSizingSchema.safeParse(raw);
+    return parsed.success ? parsed.data : null;
 }
 export function riskTitle(risk) {
     return risk === "high" ? "High risk" : risk === "elevated" ? "Elevated risk" : "Routine";
@@ -491,7 +478,7 @@ function withHeadroom(input, phase, chosen) {
 }
 /** Whether any leg actually runs a configured strong agent. */
 function drawsStrong(legs) {
-    return legs.some(leg => leg.chosen === "recommended" && leg.tier === "strong");
+    return postureOf(legs) === "strong";
 }
 export function legOf(route, phase) {
     const leg = route.legs.find(one => one.phase === phase);
@@ -559,156 +546,39 @@ export function routeDigestOf(route) {
 function str(v) {
     return typeof v === "string" && v !== "";
 }
-/** Exactly these keys, every one present, nothing unknown. */
-function exactKeysOf(value, keys) {
-    const own = Object.keys(value);
-    return own.length === keys.length && keys.every(key => own.includes(key));
-}
-function strOrNull(v) {
-    return v === null || str(v);
-}
-function stringList(v) {
-    return Array.isArray(v) && v.every(one => typeof one === "string");
-}
-/** Strict rehydration of a stored route — every field type-proved, every
- * model an exact non-empty string; anything unexpected is null, never a
- * guess. A null from a row that carries a route era is a corrupt seal. */
+/** Strict rehydration of a stored route through the route contract — every
+ * field type-proved, every model an exact non-empty string, nothing unknown;
+ * anything unexpected is null, never a guess. A null from a row that carries
+ * a route era is a corrupt seal. */
 // Recovery and normal admission share this strict decoder; neither may replace
 // unreadable signed routing with a convenient current default.
 export function routeFromJson(json) {
     if (json === null)
         return null;
+    const read = readRouteJson(json);
+    return read.ok ? read.route : null;
+}
+/** Why a stored route does not read, as path-named lines (`legs[1].model: …`); null when it reads. */
+export function routeJsonProblem(json) {
+    const read = readRouteJson(json);
+    return read.ok ? null : read.lines.join("; ");
+}
+function readRouteJson(json) {
     let parsed;
     try {
         parsed = JSON.parse(json);
     }
     catch {
-        return null;
+        return { ok: false, lines: ["payload: not valid JSON"] };
     }
-    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
-        return null;
-    const r = parsed;
-    // Exact keys (v48 integrity): the snapshot carries what canonicalRouteJson
-    // writes and nothing else — on the route, on every leg, on every leg's
-    // recommendation, and on every override.
-    // A v1 route (sealed before sizing) reads back exactly as it was written:
-    // no size, routine and strong tiers only.
-    const version = r["version"];
-    if (version !== 1 && version !== 2)
-        return null;
-    const v1Keys = ["version", "risk", "qualityMode", "publication", "evidence", "posture", "demands", "legs", "overrides"];
-    if (!exactKeysOf(r, version === 1 ? v1Keys : [...v1Keys, "size"]))
-        return null;
-    const tierOk = (tier) => tier === "routine" || tier === "strong" || (version === 2 && tier === "light");
-    const size = version === 1 || r["size"] === null ? null : parseSizing(r["size"]);
-    if (version === 2 && r["size"] !== null && size === null)
-        return null;
-    if (!isRiskLevel(r["risk"]))
-        return null;
-    if (r["qualityMode"] !== "default" && r["qualityMode"] !== "strict")
-        return null;
-    if (r["publication"] !== "none" && r["publication"] !== "notify" && r["publication"] !== "automerge")
-        return null;
-    if (r["posture"] !== "economy" && r["posture"] !== "strong")
-        return null;
-    if (!stringList(r["demands"]))
-        return null;
-    const evidence = r["evidence"];
-    if (!Array.isArray(evidence) || !evidence.every(one => one === "check" || one === "screenshot" || one === "changed-path" || one === "manual-review"))
-        return null;
-    if (!Array.isArray(r["legs"]) || r["legs"].length !== PHASES.length)
-        return null;
-    const legs = [];
-    for (const [index, raw] of r["legs"].entries()) {
-        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
-            return null;
-        const leg = raw;
-        if (!exactKeysOf(leg, ["phase", "provider", "model", "tier", "chosen", "recommended", "reasons", "problem"]))
-            return null;
-        if (leg["phase"] !== PHASES[index])
-            return null;
-        if (!str(leg["provider"]) || !isProviderId(leg["provider"]))
-            return null;
-        if (!exactModel(leg["model"]))
-            return null;
-        if (!tierOk(leg["tier"]))
-            return null;
-        if (leg["chosen"] !== "recommended" && leg["chosen"] !== "override" && leg["chosen"] !== "pinned")
-            return null;
-        const rec = leg["recommended"];
-        if (rec === null || typeof rec !== "object" || Array.isArray(rec))
-            return null;
-        const recommended = rec;
-        if (!exactKeysOf(recommended, ["provider", "model", "tier"]))
-            return null;
-        if (!str(recommended["provider"]) || !isProviderId(recommended["provider"]))
-            return null;
-        if (!exactModel(recommended["model"]))
-            return null;
-        if (!tierOk(recommended["tier"]))
-            return null;
-        if (!stringList(leg["reasons"]))
-            return null;
-        if (!strOrNull(leg["problem"]))
-            return null;
-        legs.push({
-            phase: PHASES[index],
-            provider: leg["provider"],
-            model: leg["model"],
-            tier: leg["tier"],
-            chosen: leg["chosen"],
-            recommended: { provider: recommended["provider"], model: recommended["model"], tier: recommended["tier"] },
-            reasons: [...leg["reasons"]],
-            problem: leg["problem"],
-        });
-    }
-    // The posture must be what the legs say — a snapshot claiming a strong
-    // posture over routine legs (or the reverse) is not one this policy wrote.
-    if ((drawsStrong(legs) ? "strong" : "economy") !== r["posture"])
-        return null;
-    const overrides = parseOverrides(r["overrides"]);
-    if (overrides === null)
-        return null;
-    return {
-        version,
-        risk: r["risk"],
-        qualityMode: r["qualityMode"],
-        publication: r["publication"],
-        evidence: [...evidence].sort(),
-        posture: r["posture"],
-        demands: [...r["demands"]],
-        legs,
-        overrides,
-        size,
-    };
+    const read = readSealedRoute(parsed);
+    return read.ok ? { ok: true, route: read.value } : { ok: false, lines: read.issues.map(one => one.line) };
 }
-/** Strict parse of an override list: one per phase, every field proved,
- * every model exact. */
+/** Strict parse of an override list (the route contract's): one per phase,
+ * every field proved, every model exact, in phase order. */
 export function parseOverrides(raw) {
-    if (!Array.isArray(raw))
-        return null;
-    const overrides = [];
-    const seen = new Set();
-    for (const entry of raw) {
-        if (entry === null || typeof entry !== "object" || Array.isArray(entry))
-            return null;
-        const o = entry;
-        if (!exactKeysOf(o, ["phase", "provider", "model", "by", "at"]))
-            return null;
-        if (!str(o["phase"]) || !PHASES.includes(o["phase"]))
-            return null;
-        if (seen.has(o["phase"]))
-            return null;
-        seen.add(o["phase"]);
-        if (!str(o["provider"]) || !isProviderId(o["provider"]))
-            return null;
-        if (!exactModel(o["model"]))
-            return null;
-        if (!str(o["by"]) || !str(o["at"]))
-            return null;
-        overrides.push({ phase: o["phase"], provider: o["provider"], model: o["model"], by: o["by"], at: o["at"] });
-    }
-    return overrides.sort((a, b) => PHASES.indexOf(a.phase) - PHASES.indexOf(b.phase));
+    const read = readRouteOverrides(raw);
+    return read.ok ? read.value : null;
 }
 /** The stored override list (a task-level column). Malformed reads as
  * null — the caller files the scope unresolved rather than routing as if