toolroll 0.9.36 → 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/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

package/dist/project-knowledge.d.ts

@@ -1,26 +1,7 @@
-import { type DecisionLine } from './project-memory.js';
-import { type RepositoryContext } from './repository-context.js';
 import type { Store } from './store.js';
+import { type Knowledge, type KnowledgeDraft, type KnowledgeReference, type KnowledgeSelection } from './contracts/project-knowledge.js';
 export declare const KNOWLEDGE_SCHEMA = "\nCREATE TABLE IF NOT EXISTS project_knowledge (\n repo TEXT PRIMARY KEY, identity TEXT NOT NULL, revision INTEGER NOT NULL, payload TEXT NOT NULL, sha TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS knowledge_change (\n id INTEGER PRIMARY KEY, repo TEXT NOT NULL, identity TEXT NOT NULL, revision INTEGER NOT NULL,\n actor TEXT NOT NULL, at TEXT NOT NULL, payload TEXT NOT NULL, sha TEXT NOT NULL,\n UNIQUE(repo,identity,revision)\n);\nCREATE TABLE IF NOT EXISTS knowledge_snapshot (\n run INTEGER PRIMARY KEY REFERENCES run(id), repo TEXT NOT NULL, identity TEXT NOT NULL,\n payload TEXT NOT NULL, sha TEXT NOT NULL\n);\n-- A saved project identity carried forward (a restart renumbered the volume, or an approver applied it).\nCREATE TABLE IF NOT EXISTS project_identity_carry (\n id INTEGER PRIMARY KEY, repo TEXT NOT NULL, from_identity TEXT NOT NULL, to_identity TEXT NOT NULL,\n actor TEXT NOT NULL, at TEXT NOT NULL, how TEXT NOT NULL CHECK(how IN ('automatic','approver')),\n UNIQUE(repo,from_identity,to_identity)\n);\nCREATE TRIGGER IF NOT EXISTS project_identity_carry_no_update BEFORE UPDATE ON project_identity_carry BEGIN SELECT RAISE(ABORT,'Project identity history is immutable'); END;\nCREATE TRIGGER IF NOT EXISTS project_identity_carry_no_delete BEFORE DELETE ON project_identity_carry BEGIN SELECT RAISE(ABORT,'Project identity history is immutable'); END;\nCREATE TRIGGER IF NOT EXISTS knowledge_change_no_update BEFORE UPDATE ON knowledge_change BEGIN SELECT RAISE(ABORT,'Knowledge history is immutable'); END;\nCREATE TRIGGER IF NOT EXISTS knowledge_change_no_delete BEFORE DELETE ON knowledge_change BEGIN SELECT RAISE(ABORT,'Knowledge history is immutable'); END;\nCREATE TRIGGER IF NOT EXISTS knowledge_snapshot_no_update BEFORE UPDATE ON knowledge_snapshot BEGIN SELECT RAISE(ABORT,'Knowledge context is immutable'); END;\nCREATE TRIGGER IF NOT EXISTS knowledge_snapshot_no_delete BEFORE DELETE ON knowledge_snapshot BEGIN SELECT RAISE(ABORT,'Knowledge context is immutable'); END;\n";
-export type KnowledgeReference = {
-    id: string;
-    title: string;
-    content: string;
-    path: string | null;
-    sourceSha: string | null;
-    sourceRevision: string | null;
-};
-export type Knowledge = {
-    instructions: string;
-    references: KnowledgeReference[];
-};
-export type KnowledgeDraft = {
-    instructions?: string;
-    title?: string;
-    content?: string;
-    path?: string;
-    id?: string;
-};
+export type { Knowledge, KnowledgeDraft, KnowledgeReference, KnowledgeSelection };
 export declare const STALE_KNOWLEDGE = "This project's saved knowledge is from before a change; review and apply it";
 export declare function knowledgeView(store: Store, repo: string, actor: string): {
     repo: string;
@@ -53,7 +34,20 @@ export declare function conversationKnowledge(store: Store, repo: string, actor:
     decisions?: never;
 } | {
     stale?: never;
-    decision: import("./project-memory.js").Decision;
+    decision: {
+        repo: string;
+        revision: number;
+        claim: string;
+        why: string;
+        status: "active" | "retired" | "superseded";
+        supersedes: number | null;
+        decidedBy: string;
+        decidedAt: string;
+        sourceKind: "backward-pass" | "conversation" | "manual" | "result" | "task";
+        sourceRef: string | null;
+        recordedBy: string;
+        id: number;
+    };
     notice: string;
     title?: never;
     content?: never;
@@ -110,19 +104,6 @@ export declare function changeKnowledge(store: Store, args: {
  * Returns the new revision, or null when nothing was waiting.
  */
 export declare function applySavedKnowledge(store: Store, repo: string, actor: string, now?: Date): number | null;
-export type KnowledgeSelection = {
-    version: 1;
-    revision: number;
-    instructions: string;
-    references: KnowledgeReference[];
-    omitted: {
-        title: string;
-        reason: string;
-    }[];
-    inheritedFrom: number | null;
-    repository?: RepositoryContext;
-    decisions?: DecisionLine[];
-};
 /** Read the same bounded, source-checked selection without inventing a worker run. */
 export declare function selectProjectKnowledge(store: Store, args: {
     repo: string;