toolroll 0.9.34 → 0.9.37

package/dist/plan.d.ts

@@ -6,7 +6,7 @@
  * the scope proposal is authority-bearing, so it gets the park discipline).
  */
 import { type AcceptanceCriterion } from "./scope.js";
-import type { ContractIssue } from "./contracts/contract.js";
+import { type ContractIssue } from "./contracts/contract.js";
 export type PlanProblem = {
     reason: string;
     message: string;
@@ -71,11 +71,11 @@ export type PlanParseResult = {
     problems: PlanProblem[];
 };
 /**
- * A contract issue as a plan problem: the path-named line is the message, and the reason keeps the codes the rest of
- * the code relies on — `missing-goal`, `bad-touches`, `plan-too-long`, `amendment-too-long`, `acceptance-too-many` —
- * so repair eligibility (document-only problems) and durable outcomes read the same as before the contract.
+ * A contract issue as a plan problem (`contractProblemOf`): the reason keeps the codes the rest of the code relies on
+ * — `missing-goal`, `bad-touches`, `plan-too-long`, `amendment-too-long`, `acceptance-too-many` — so repair eligibility
+ * (document-only problems) and durable outcomes read the same as before the contract.
  */
-export declare function planProblemOf(issue: ContractIssue): PlanProblem;
+export declare const planProblemOf: (issue: ContractIssue) => PlanProblem;
 /**
  * The planner's handoff, read against the plan contract (src/contracts/plan.ts): fail closed, every problem at once,
  * each one naming its path (`acceptance[0].evidence[0]: must be one of ...`). A plan saved before plans carried

package/dist/plan.js

@@ -9,6 +9,7 @@ import { createHash } from "node:crypto";
 import { hasForbiddenControls } from "./decision.js";
 import { parseAcceptanceCriteria } from "./scope.js";
 import { TEXT_LIMITS } from "./text-limits.js";
+import { contractProblemOf } from "./contracts/contract.js";
 import { planPayloadBody, readPlanPayload } from "./contracts/plan.js";
 const EXECUTION_PLAN_SECTIONS = ["approach", "milestones", "dependencies", "risks", "proof"];
 const EXECUTION_PLAN_LIST_CAP = 12;
@@ -163,32 +164,11 @@ function prose(value, field, cap, required, problems) {
     return value;
 }
 /**
- * A contract issue as a plan problem: the path-named line is the message, and the reason keeps the codes the rest of
- * the code relies on — `missing-goal`, `bad-touches`, `plan-too-long`, `amendment-too-long`, `acceptance-too-many` —
- * so repair eligibility (document-only problems) and durable outcomes read the same as before the contract.
+ * A contract issue as a plan problem (`contractProblemOf`): the reason keeps the codes the rest of the code relies on
+ * — `missing-goal`, `bad-touches`, `plan-too-long`, `amendment-too-long`, `acceptance-too-many` — so repair eligibility
+ * (document-only problems) and durable outcomes read the same as before the contract.
  */
-export function planProblemOf(issue) {
-    const at = issue.path;
-    const reason = (() => {
-        switch (issue.kind) {
-            case "required":
-            case "empty":
-            case "too-few":
-                return `missing-${at}`;
-            case "too-long":
-                return `${at}-too-long`;
-            case "too-many":
-                return `${at}-too-many`;
-            case "unknown-key":
-                return `${at}-unknown-key`;
-            case "newer-version":
-                return "newer-version";
-            default:
-                return `bad-${at}`;
-        }
-    })();
-    return { reason, message: issue.line };
-}
+export const planProblemOf = contractProblemOf;
 /** scope.ts's rubric problem as a path-named line: `acceptance[0].id: is over 40 bytes`. */
 function acceptanceLine(problem) {
     const named = /^(acceptance(?:\[\d+\])?(?:\.[A-Za-z]+)?) (.*)$/.exec(problem.message);

package/dist/process-recovery-eligibility.d.ts

@@ -37,7 +37,7 @@ export declare function preparedCandidateObserverGapEligibility(store: Store, in
             leaseId: string;
             role: "builder";
             outcome: "built" | "no-change";
-            committed: boolean | null;
+            committed: boolean;
             startedAt: string;
             finishedAt: string;
             branch: string;
@@ -81,7 +81,7 @@ export declare function preparedCandidateObserverGapEligibility(store: Store, in
                 readonly state: import("./proof.js").CriterionMatrixState;
                 readonly detail: readonly string[];
                 readonly answered: readonly {
-                    readonly kind: import("./scope.js").EvidenceKind;
+                    readonly kind: "changed-path" | "check" | "manual-review" | "screenshot";
                     readonly ref: string;
                 }[];
                 readonly review: {

package/dist/process-recovery-eligibility.js

@@ -8,6 +8,8 @@
 import { createHash } from "node:crypto";
 import { normalizeBootId } from "./boot-identity.js";
 import { scopeApprovedForDispatch } from "./dispatch.js";
+import { parseHandoffArtifact } from "./contracts/handoff.js";
+import { readVerificationReceipt } from "./contracts/verification-receipt.js";
 import { readVerifiedArtifact } from "./evidence.js";
 import { ownedProcessCount, runOwnerTag } from "./exec.js";
 import { scopeAuthorityOf } from "./scope.js";
@@ -97,11 +99,11 @@ export function preparedCandidateObserverGapEligibility(store, input) {
             const gate = verificationEvidence(store, evidenceRoot, runId);
             if (!gate.ok || gate.bytes === null)
                 return refuse("verification-evidence-unavailable");
-            const receipt = JSON.parse(gate.bytes);
-            if (receipt.version !== 1 || receipt.source !== undefined || receipt.reusedFrom !== undefined || receipt.executedHere !== undefined ||
-                receipt.result?.configured !== true || receipt.result.ran !== true || receipt.result.exitCode !== 0 ||
-                Object.keys(receipt.result).some(key => !["configured", "ran", "exitCode", "setupReplayed"].includes(key)) ||
-                (receipt.result.setupReplayed !== undefined && receipt.result.setupReplayed !== true) ||
+            // A legacy log-header view is not a sealed receipt: the strict schema refuses its extra keys.
+            const view = JSON.parse(gate.bytes);
+            const receipt = readVerificationReceipt(view);
+            if (!receipt.ok || view.version !== 1 || receipt.value.reusedFrom !== undefined || receipt.value.executedHere !== undefined ||
+                receipt.value.result.configured !== true || receipt.value.result.ran !== true || receipt.value.result.exitCode !== 0 ||
                 !instant(gateArtifact.createdAt) || Date.parse(gateArtifact.createdAt) < Date.parse(run.startedAt) ||
                 Date.parse(gateArtifact.createdAt) > Date.parse(machine.decidedAt) ||
                 Date.parse(gateArtifact.createdAt) > Date.parse(run.finishedAt))
@@ -115,12 +117,15 @@ export function preparedCandidateObserverGapEligibility(store, input) {
             const saved = readVerifiedArtifact(evidenceRoot, artifact);
             if (!saved.ok)
                 return refuse("machine-prepared-handoff-unavailable");
-            const handoff = JSON.parse(saved.content.toString("utf8"));
+            const read = parseHandoffArtifact(saved.content.toString("utf8"));
+            if (!read.ok)
+                return refuse("machine-prepared-handoff-mismatch");
+            const handoff = read.value;
             const conclusion = `Prepared candidate ${scope.candidate} was checked out by the machine; no agent ran. ${run.outcome === "no-change" ? "The branch already matched it." : "The sealed diff spans this task's base to that candidate."}`;
-            if (handoff.schema !== 1 || handoff.runId !== runId || handoff.taskId !== ref.externalId || handoff.sessionId !== null ||
+            if (handoff.runId !== runId || handoff.taskId !== ref.externalId || handoff.sessionId !== null ||
                 handoff.provider !== run.provider || handoff.branch !== run.branch || handoff.worktree !== run.worktree ||
                 handoff.base !== run.baseRevision || handoff.head !== run.headRevision || handoff.outcome !== run.outcome ||
-                handoff.committed !== run.committed || handoff.freshness?.currentAsOf !== run.headRevision ||
+                handoff.committed !== run.committed || handoff.freshness.currentAsOf !== run.headRevision ||
                 handoff.conclusion !== conclusion || run.handoff !== conclusion ||
                 !instant(artifact.createdAt) || Date.parse(artifact.createdAt) < Date.parse(run.startedAt) ||
                 Date.parse(artifact.createdAt) > Date.parse(gateArtifact.createdAt))

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;

package/dist/project-knowledge.js

@@ -5,6 +5,9 @@ import { currentActor } from './actor.js';
 import { decisionLines, getDecision, listDecisions } from './project-memory.js';
 import { scanForSecrets } from './evidence.js';
 import { repositoryContextRead } from './repository-context.js';
+import { TEXT_LIMITS } from './text-limits.js';
+import { contractError } from './contracts/contract.js';
+import { KNOWLEDGE_COUNTS, KNOWLEDGE_SELECTION_VERSION, KNOWLEDGE_VERSION, knowledgeSchema, knowledgeSelectionSchema, readKnowledge, readKnowledgeSelection } from './contracts/project-knowledge.js';
 export const KNOWLEDGE_SCHEMA = `
 CREATE TABLE IF NOT EXISTS project_knowledge (
  repo TEXT PRIMARY KEY, identity TEXT NOT NULL, revision INTEGER NOT NULL, payload TEXT NOT NULL, sha TEXT NOT NULL
@@ -49,10 +52,21 @@ export const STALE_KNOWLEDGE = "This project's saved knowledge is from before a
 const STALE_OMITTED = { title: 'Saved project knowledge', reason: 'Saved knowledge is from before a change; it was not applied' };
 /** Revisions under any identity this project accepts, as a bound JSON list. */
 const IN_ACCEPTED = 'identity IN (SELECT value FROM json_each(?))';
+/** The stored bytes are checked against their digest first; only then are they parsed, and upgraded in memory. */
 function decode(payload, sha) {
     if (learningSha(payload) !== sha)
         throw Error('Project knowledge could not be verified.');
-    return JSON.parse(payload);
+    const read = readKnowledge(JSON.parse(payload));
+    if (!read.ok)
+        throw Error('Project knowledge could not be verified.');
+    return read.value;
+}
+/** Knowledge (or a selection) as it is written: through its schema, so a refusal names the field. */
+function encode(schema, value, what) {
+    const read = schema.safeParse(value, { reportInput: true });
+    if (!read.success)
+        throw Error(`${what} could not be saved: ${contractError(read.error).join('; ')}`);
+    return JSON.stringify(read.data);
 }
 /** Saved knowledge under another identity is stale: it is returned for review, never applied. */
 function current(store, repo, accepted) {
@@ -73,9 +87,9 @@ function document(repo, revision, path) {
     if (!match)
         throw Error('This reference must be a committed text file, not a folder or link.');
     const sha = match[1];
-    if (Number(git(repo, ['cat-file', '-s', sha])) > 12000)
+    if (Number(git(repo, ['cat-file', '-s', sha])) > TEXT_LIMITS.knowledgeReferenceBytes)
         throw Error('Choose a shorter reference (up to 12 KB).');
-    return { content: clean(git(repo, ['cat-file', 'blob', sha]), 12000), sha };
+    return { content: clean(git(repo, ['cat-file', 'blob', sha]), TEXT_LIMITS.knowledgeReferenceBytes), sha };
 }
 export function knowledgeView(store, repo, actor) {
     const { identity, accepted } = admission(store, repo, actor), { stale, ...value } = current(store, repo, accepted);
@@ -128,7 +142,7 @@ export function changeKnowledge(store, args, now = new Date()) {
             throw Error('Knowledge changed in another window. Review your draft below before saving again.');
         let knowledge = existing.knowledge;
         if (args.action === 'instructions')
-            knowledge.instructions = clean(args.draft.instructions ?? '', 4000);
+            knowledge.instructions = clean(args.draft.instructions ?? '', TEXT_LIMITS.knowledgeInstructionsBytes);
         else if (args.action === 'restore') {
             const row = store.handle.prepare(`SELECT payload,sha FROM knowledge_change WHERE repo=? AND ${IN_ACCEPTED} AND revision=?`).get(args.repo, JSON.stringify([...accepted]), args.restore ?? -1);
             if (!row)
@@ -141,26 +155,26 @@ export function changeKnowledge(store, args, now = new Date()) {
             knowledge.references = knowledge.references.filter(r => r.id !== args.draft.id);
         }
         else if (args.action === 'save') {
-            const title = clean(args.draft.title ?? '', 120);
+            const title = clean(args.draft.title ?? '', TEXT_LIMITS.knowledgeTitleBytes);
             if (!title)
                 throw Error('Give this reference a short name.');
             const id = args.draft.id || learningSha(`${identity}:${existing.revision + 1}:${title}`).slice(0, 20);
             if (args.draft.id && !knowledge.references.some(r => r.id === id))
                 throw Error('That reference is no longer available.');
-            const path = clean(args.draft.path ?? '', 300) || null;
+            const path = clean(args.draft.path ?? '', TEXT_LIMITS.knowledgePathBytes) || null;
             const sourceRevision = path ? git(args.repo, ['rev-parse', 'HEAD']) : null;
             const source = path ? document(args.repo, sourceRevision, path) : null;
-            const content = source?.content ?? clean(args.draft.content ?? '', 12000);
+            const content = source?.content ?? clean(args.draft.content ?? '', TEXT_LIMITS.knowledgeReferenceBytes);
             if (!content)
                 throw Error('Add reference text or select a committed project document.');
             const ref = { id, title, content, path, sourceSha: source?.sha ?? null, sourceRevision };
             knowledge.references = [...knowledge.references.filter(r => r.id !== id), ref];
-            if (knowledge.references.length > 12)
+            if (knowledge.references.length > KNOWLEDGE_COUNTS.references)
                 throw Error('Keep up to 12 focused references. Remove one before adding another.');
         }
         else
             throw Error('Choose a supported knowledge action.');
-        const payload = JSON.stringify(knowledge), sha = learningSha(payload), revision = existing.revision + 1;
+        const payload = encode(knowledgeSchema, { version: KNOWLEDGE_VERSION, ...knowledge }, 'Project knowledge'), sha = learningSha(payload), revision = existing.revision + 1;
         store.handle.prepare('INSERT INTO knowledge_change(repo,identity,revision,actor,at,payload,sha) VALUES (?,?,?,?,?,?,?)').run(args.repo, identity, revision, args.actor, now.toISOString(), payload, sha);
         store.handle.prepare('INSERT INTO project_knowledge VALUES (?,?,?,?,?) ON CONFLICT(repo) DO UPDATE SET identity=excluded.identity,revision=excluded.revision,payload=excluded.payload,sha=excluded.sha').run(args.repo, identity, revision, payload, sha);
     });
@@ -191,7 +205,7 @@ function select(store, repo, accepted, query, head) {
     const ranked = knowledge.references.map(ref => ({ ref, score: [...tokens(`${ref.title} ${ref.path ?? ''}`)].reduce((n, t) => n + (q.has(t) ? 3 : 0), 0) + [...tokens(ref.content)].reduce((n, t) => n + (q.has(t) ? 1 : 0), 0) })).sort((a, b) => b.score - a.score || a.ref.id.localeCompare(b.ref.id));
     const references = [];
     for (const { ref, score } of ranked) {
-        let reason = score === 0 ? 'Not relevant to this task' : references.length >= 3 ? 'More relevant references selected' : '';
+        let reason = score === 0 ? 'Not relevant to this task' : references.length >= KNOWLEDGE_COUNTS.selected ? 'More relevant references selected' : '';
         if (ref.path) {
             try {
                 if (document(repo, head, ref.path).sha !== ref.sourceSha)
@@ -201,7 +215,7 @@ function select(store, repo, accepted, query, head) {
                 reason = 'Source unavailable; refresh this reference';
             }
         }
-        if (!reason && Buffer.byteLength(JSON.stringify({ instructions: knowledge.instructions, references: [...references, ref] })) > 24000)
+        if (!reason && Buffer.byteLength(JSON.stringify({ instructions: knowledge.instructions, references: [...references, ref] })) > TEXT_LIMITS.knowledgeContextBytes)
             reason = 'Context size limit';
         if (reason)
             omitted.push({ title: ref.title, reason });
@@ -210,8 +224,8 @@ function select(store, repo, accepted, query, head) {
     }
     // Settled decisions ride the same frozen record, one line each; the why
     // loads on demand by id, so nothing is repeated between brief and store.
-    const decisions = decisionLines(store, repo, query, { limit: 8, bytes: Math.max(0, Math.min(1500, 24000 - Buffer.byteLength(JSON.stringify({ instructions: knowledge.instructions, references })) - 200)) });
-    return { version: 1, revision, instructions: knowledge.instructions, references, omitted, inheritedFrom: null, ...(decisions.length ? { decisions } : {}) };
+    const decisions = decisionLines(store, repo, query, { limit: KNOWLEDGE_COUNTS.decisions, bytes: Math.max(0, Math.min(TEXT_LIMITS.knowledgeDecisionsBytes, TEXT_LIMITS.knowledgeContextBytes - Buffer.byteLength(JSON.stringify({ instructions: knowledge.instructions, references })) - 200)) });
+    return { version: KNOWLEDGE_SELECTION_VERSION, revision, instructions: knowledge.instructions, references, omitted, inheritedFrom: null, ...(decisions.length ? { decisions } : {}) };
 }
 /** Read the same bounded, source-checked selection without inventing a worker run. */
 export function selectProjectKnowledge(store, args) {
@@ -227,10 +241,17 @@ export function readKnowledgeSnapshot(store, runId) {
     if (!row)
         return null;
     const run = store.getRun(runId), repo = run && store.refForId(run.taskRef)?.repo;
-    const selection = JSON.parse(String(row['payload']));
+    const unverified = () => Error('The context saved for this run could not be verified.');
+    // The stored bytes are checked against their digest before they are parsed.
+    if (!repo || row['repo'] !== repo || learningSha(String(row['payload'])) !== row['sha'])
+        throw unverified();
+    const read = readKnowledgeSelection(JSON.parse(String(row['payload'])));
+    if (!read.ok)
+        throw unverified();
+    const selection = read.value;
     const empty = row['identity'] === 'unconfigured' && unconfigured(selection);
-    if (!repo || row['repo'] !== repo || (!empty && !acceptedIdentities(store, repo).has(String(row['identity']))) || learningSha(String(row['payload'])) !== row['sha'])
-        throw Error('The context saved for this run could not be verified.');
+    if (!empty && !acceptedIdentities(store, repo).has(String(row['identity'])))
+        throw unverified();
     return selection;
 }
 /** Freeze at provider admission. Reviewers see the builder's exact project context. */
@@ -259,18 +280,18 @@ export function knowledgeContext(store, runId, cacheRoot, validatedBuilderBase)
             const configured = !!store.handle.prepare('SELECT 1 FROM project_knowledge WHERE repo=?').get(repo);
             // A legacy source without a snapshot did not receive this feature's
             // context. Never give its reviewer newly configured project guidance.
-            selection = inherited ? { ...inherited, inheritedFrom: parent.id } : !configured || parent ? { version: 1, revision: 0, instructions: '', references: [], omitted: [], inheritedFrom: parent?.id ?? null } : select(store, repo, acceptedIdentities(store, repo), `${store.getTask(ref.externalId)?.title ?? ''} ${scope?.goal ?? ''} ${(scope?.touches ?? []).join(' ')}`, contextBase || git(repo, ['rev-parse', 'HEAD']));
+            selection = inherited ? { ...inherited, inheritedFrom: parent.id } : !configured || parent ? { version: KNOWLEDGE_SELECTION_VERSION, revision: 0, instructions: '', references: [], omitted: [], inheritedFrom: parent?.id ?? null } : select(store, repo, acceptedIdentities(store, repo), `${store.getTask(ref.externalId)?.title ?? ''} ${scope?.goal ?? ''} ${(scope?.touches ?? []).join(' ')}`, contextBase || git(repo, ['rev-parse', 'HEAD']));
             // Optional source selection is captured once from this crew's actual
             // checkout. It is reused with the immutable run snapshot on resume.
             // Index/source failure stays context metadata, never an admission gate.
             if (!parent && run.worktree && contextBase) {
-                const available = 24000 - Buffer.byteLength(JSON.stringify(selection)) - 30;
-                if (available >= 3000)
-                    selection.repository = repositoryContextRead({ repo: run.worktree, project: repo, baseRevision: contextBase, audience: 'crew', maxBytes: Math.min(6000, available), ...(cacheRoot === undefined ? {} : { cacheRoot }), query: `${store.getTask(ref.externalId)?.title ?? ''} ${scope?.goal ?? ''} ${(scope?.touches ?? []).join(' ')}` });
+                const available = TEXT_LIMITS.knowledgeContextBytes - Buffer.byteLength(JSON.stringify(selection)) - 30;
+                if (available >= TEXT_LIMITS.knowledgeRepositoryMinBytes)
+                    selection.repository = repositoryContextRead({ repo: run.worktree, project: repo, baseRevision: contextBase, audience: 'crew', maxBytes: Math.min(TEXT_LIMITS.knowledgeRepositoryBytes, available), ...(cacheRoot === undefined ? {} : { cacheRoot }), query: `${store.getTask(ref.externalId)?.title ?? ''} ${scope?.goal ?? ''} ${(scope?.touches ?? []).join(' ')}` });
                 else
                     selection.omitted.push({ title: 'Repository context', reason: 'Context size limit' });
             }
-            const payload = JSON.stringify(selection);
+            const payload = encode(knowledgeSelectionSchema, selection, 'Project context');
             store.handle.prepare('INSERT INTO knowledge_snapshot VALUES (?,?,?,?,?)').run(runId, repo, unconfigured(selection) ? 'unconfigured' : learningIdentity(repo), payload, learningSha(payload));
         }
         // JSON escapes ordinary newlines, but not Unicode line separators. Keep

package/dist/project-memory.d.ts

@@ -1,28 +1,7 @@
 import type { Store } from './store.js';
+import { type Decision, type DecisionDraft, type DecisionLine } from './contracts/project-memory.js';
+export type { Decision, DecisionDraft, DecisionLine };
 export declare const MEMORY_SCHEMA = "\nCREATE TABLE IF NOT EXISTS project_decision (\n id INTEGER PRIMARY KEY, repo TEXT NOT NULL, identity TEXT NOT NULL, revision INTEGER NOT NULL DEFAULT 1,\n claim TEXT NOT NULL, why TEXT NOT NULL,\n status TEXT NOT NULL CHECK(status IN ('active','superseded','retired')),\n supersedes INTEGER REFERENCES project_decision(id),\n decided_by TEXT NOT NULL, decided_at TEXT NOT NULL,\n source_kind TEXT NOT NULL CHECK(source_kind IN ('conversation','task','result','manual','backward-pass')),\n source_ref TEXT, recorded_by TEXT NOT NULL, sha TEXT NOT NULL\n);\nCREATE INDEX IF NOT EXISTS project_decision_repo ON project_decision(repo, status, id);\nCREATE TABLE IF NOT EXISTS decision_change (\n id INTEGER PRIMARY KEY, decision INTEGER NOT NULL REFERENCES project_decision(id), revision INTEGER NOT NULL,\n actor TEXT NOT NULL, at TEXT NOT NULL, action TEXT NOT NULL, payload TEXT NOT NULL, sha TEXT NOT NULL,\n UNIQUE(decision, revision)\n);\nCREATE TRIGGER IF NOT EXISTS decision_change_no_update BEFORE UPDATE ON decision_change BEGIN SELECT RAISE(ABORT,'Decision history is immutable'); END;\nCREATE TRIGGER IF NOT EXISTS decision_change_no_delete BEFORE DELETE ON decision_change BEGIN SELECT RAISE(ABORT,'Decision history is immutable'); END;\nCREATE TRIGGER IF NOT EXISTS project_decision_no_delete BEFORE DELETE ON project_decision BEGIN SELECT RAISE(ABORT,'Decisions are retired, never deleted'); END;\nCREATE VIRTUAL TABLE IF NOT EXISTS memory_search USING fts5(kind UNINDEXED, ref UNINDEXED, repo UNINDEXED, scope UNINDEXED, title, body, tokenize='unicode61');\n-- The backward pass (memory-pass.ts): sessions analysed once per surface\n-- version, gaps that accumulate corroboration across runs, and the\n-- proposals a person accepts or rejects. Rejections are remembered.\nCREATE TABLE IF NOT EXISTS memory_session (\n id TEXT PRIMARY KEY, repo TEXT NOT NULL, kind TEXT NOT NULL CHECK(kind IN ('claude','codex','lead','crew')),\n source TEXT NOT NULL, seen_at TEXT NOT NULL, surface TEXT NOT NULL, trace_sha TEXT NOT NULL,\n analyzed_at TEXT, verdict TEXT, problem TEXT\n);\nCREATE INDEX IF NOT EXISTS memory_session_repo ON memory_session(repo, seen_at);\nCREATE TABLE IF NOT EXISTS memory_gap (\n id INTEGER PRIMARY KEY, repo TEXT NOT NULL, key TEXT NOT NULL, mistake TEXT NOT NULL, proposed TEXT NOT NULL,\n domain TEXT NOT NULL CHECK(domain IN ('project','orchestration')), first_seen TEXT NOT NULL, last_seen TEXT NOT NULL,\n retired_at TEXT, retired_reason TEXT, UNIQUE(repo, key)\n);\nCREATE TABLE IF NOT EXISTS memory_sighting (\n gap INTEGER NOT NULL REFERENCES memory_gap(id), session TEXT NOT NULL REFERENCES memory_session(id),\n at TEXT NOT NULL, quote TEXT NOT NULL, PRIMARY KEY(gap, session)\n);\nCREATE TABLE IF NOT EXISTS memory_proposal (\n id INTEGER PRIMARY KEY, repo TEXT NOT NULL, kind TEXT NOT NULL CHECK(kind IN ('instruction-add','instruction-remove','decision-add')),\n fingerprint TEXT NOT NULL, title TEXT NOT NULL, rationale TEXT NOT NULL, before_text TEXT, after_text TEXT NOT NULL,\n evidence TEXT NOT NULL, sessions INTEGER NOT NULL, status TEXT NOT NULL CHECK(status IN ('pending','accepted','rejected','stale')),\n created_at TEXT NOT NULL, decided_by TEXT, decided_at TEXT, surface TEXT NOT NULL\n);\nCREATE INDEX IF NOT EXISTS memory_proposal_pending ON memory_proposal(repo, status, fingerprint);\nCREATE TABLE IF NOT EXISTS memory_rejection (\n repo TEXT NOT NULL, fingerprint TEXT NOT NULL, rejected_at TEXT NOT NULL, rejected_by TEXT NOT NULL, sessions INTEGER NOT NULL, PRIMARY KEY(repo, fingerprint)\n);\n";
-export type Decision = {
-    id: number;
-    repo: string;
-    revision: number;
-    claim: string;
-    why: string;
-    status: 'active' | 'superseded' | 'retired';
-    supersedes: number | null;
-    decidedBy: string;
-    decidedAt: string;
-    sourceKind: 'conversation' | 'task' | 'result' | 'manual' | 'backward-pass';
-    sourceRef: string | null;
-    recordedBy: string;
-};
-export type DecisionDraft = {
-    claim: string;
-    why: string;
-    decidedBy?: string;
-    decidedAt?: string;
-    sourceKind?: Decision['sourceKind'];
-    sourceRef?: string | null;
-    supersedes?: number | null;
-};
 export declare function listDecisions(store: Store, repo: string, actor: string, options?: {
     status?: Decision['status'] | 'all';
     limit?: number;
@@ -47,11 +26,6 @@ export declare function decisionHistory(store: Store, repo: string, actor: strin
     at: string;
     action: string;
 }[];
-export type DecisionLine = {
-    id: number;
-    claim: string;
-    decidedAt: string;
-};
 /**
  * The decisions worth one line each in a brief: relevant to the query first,
  * then newest, within a byte budget. Bodies (the why) load on demand by id,

package/dist/project-memory.js

@@ -10,6 +10,9 @@
 import { createHash } from 'node:crypto';
 import { scanForSecrets } from './evidence.js';
 import { learningIdentity } from './project-learning.js';
+import { TEXT_LIMITS } from './text-limits.js';
+import { contractError } from './contracts/contract.js';
+import { DECISION_CHANGE_VERSION, decisionChangeSchema, decisionRecordSchema, decisionSchema } from './contracts/project-memory.js';
 export const MEMORY_SCHEMA = `
 CREATE TABLE IF NOT EXISTS project_decision (
  id INTEGER PRIMARY KEY, repo TEXT NOT NULL, identity TEXT NOT NULL, revision INTEGER NOT NULL DEFAULT 1,
@@ -75,18 +78,29 @@ function admission(store, repo, actor, write = false) {
         throw Error('Project memory is outside your access.');
     return learningIdentity(repo);
 }
+/** A decision row through its schema; null when the row does not read as one (it is then unverifiable). */
 function decisionOf(row) {
-    return { id: Number(row['id']), repo: String(row['repo']), revision: Number(row['revision']), claim: String(row['claim']), why: String(row['why']),
+    const read = decisionSchema.safeParse({ id: Number(row['id']), repo: String(row['repo']), revision: Number(row['revision']), claim: String(row['claim']), why: String(row['why']),
         status: row['status'], supersedes: row['supersedes'] === null ? null : Number(row['supersedes']),
         decidedBy: String(row['decided_by']), decidedAt: String(row['decided_at']), sourceKind: row['source_kind'],
-        sourceRef: row['source_ref'] === null ? null : String(row['source_ref']), recordedBy: String(row['recorded_by']) };
+        sourceRef: row['source_ref'] === null ? null : String(row['source_ref']), recordedBy: String(row['recorded_by']) });
+    return read.success ? read.data : null;
 }
 const digestOf = (d) => sha(JSON.stringify([d.repo, d.revision, d.claim, d.why, d.status, d.supersedes, d.decidedBy, d.decidedAt, d.sourceKind, d.sourceRef, d.recordedBy]));
+/** A record or history entry through its schema before it is written; a refusal names the field. */
+function checked(schema, value) {
+    const read = schema.safeParse(value);
+    if (!read.success)
+        throw Error(`This decision could not be saved: ${contractError(read.error).join('; ')}`);
+    return read.data;
+}
+const history = (payload) => JSON.stringify(checked(decisionChangeSchema, { version: DECISION_CHANGE_VERSION, ...payload }));
 export function listDecisions(store, repo, actor, options = {}) {
     admission(store, repo, actor);
     const status = options.status ?? 'active', limit = Math.min(200, Math.max(1, options.limit ?? 50));
     return store.handle.prepare(`SELECT * FROM project_decision WHERE repo=? AND (?='all' OR status=?) ORDER BY id DESC LIMIT ?`).all(repo, status, status, limit)
-        .map(row => decisionOf(row)).filter(d => digestOf(d) === String(store.handle.prepare('SELECT sha FROM project_decision WHERE id=?').get(d.id)['sha']));
+        .flatMap(row => { const d = decisionOf(row); return d === null ? [] : [d]; })
+        .filter(d => digestOf(d) === String(store.handle.prepare('SELECT sha FROM project_decision WHERE id=?').get(d.id)['sha']));
 }
 export function getDecision(store, repo, actor, id) {
     admission(store, repo, actor);
@@ -94,20 +108,20 @@ export function getDecision(store, repo, actor, id) {
     if (!row)
         return null;
     const d = decisionOf(row);
-    if (digestOf(d) !== String(row['sha']))
+    if (d === null || digestOf(d) !== String(row['sha']))
         throw Error('This decision could not be verified.');
     return d;
 }
 /** Record one settled choice. A superseding decision retires the older one in the same transaction. */
 export function recordDecision(store, args, now = new Date()) {
     const identity = admission(store, args.repo, args.actor, true);
-    const claim = clean(args.draft.claim, 240, 'The decision'), why = clean(args.draft.why, 2000, 'The reason');
-    const decidedBy = args.draft.decidedBy === undefined ? args.actor : clean(args.draft.decidedBy, 80, 'Who decided');
+    const claim = clean(args.draft.claim, TEXT_LIMITS.decisionClaimBytes, 'The decision'), why = clean(args.draft.why, TEXT_LIMITS.decisionWhyBytes, 'The reason');
+    const decidedBy = args.draft.decidedBy === undefined ? args.actor : clean(args.draft.decidedBy, TEXT_LIMITS.decisionByBytes, 'Who decided');
     const decidedAt = args.draft.decidedAt ?? now.toISOString();
     if (!/^\d{4}-\d{2}-\d{2}T/.test(decidedAt))
         throw Error('When it was decided must be an ISO timestamp.');
     const sourceKind = args.draft.sourceKind ?? 'manual';
-    const sourceRef = args.draft.sourceRef === undefined || args.draft.sourceRef === null ? null : clean(String(args.draft.sourceRef), 200, 'The source');
+    const sourceRef = args.draft.sourceRef === undefined || args.draft.sourceRef === null ? null : clean(String(args.draft.sourceRef), TEXT_LIMITS.decisionSourceBytes, 'The source');
     return store.transact(() => {
         let supersedes = null;
         if (args.draft.supersedes !== undefined && args.draft.supersedes !== null) {
@@ -116,11 +130,11 @@ export function recordDecision(store, args, now = new Date()) {
                 throw Error('The decision being replaced is not active.');
             supersedes = older.id;
         }
-        const record = { repo: args.repo, revision: 1, claim, why, status: 'active', supersedes, decidedBy, decidedAt, sourceKind, sourceRef, recordedBy: args.actor };
+        const record = checked(decisionRecordSchema, { repo: args.repo, revision: 1, claim, why, status: 'active', supersedes, decidedBy, decidedAt, sourceKind, sourceRef, recordedBy: args.actor });
         const inserted = store.handle.prepare(`INSERT INTO project_decision(repo,identity,revision,claim,why,status,supersedes,decided_by,decided_at,source_kind,source_ref,recorded_by,sha)
       VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)`).run(args.repo, identity, 1, claim, why, 'active', supersedes, decidedBy, decidedAt, sourceKind, sourceRef, args.actor, digestOf(record));
         const id = Number(inserted.lastInsertRowid);
-        store.handle.prepare('INSERT INTO decision_change(decision,revision,actor,at,action,payload,sha) VALUES (?,?,?,?,?,?,?)').run(id, 1, args.actor, now.toISOString(), 'record', JSON.stringify(record), digestOf(record));
+        store.handle.prepare('INSERT INTO decision_change(decision,revision,actor,at,action,payload,sha) VALUES (?,?,?,?,?,?,?)').run(id, 1, args.actor, now.toISOString(), 'record', history(record), digestOf(record));
         if (supersedes !== null)
             changeStatus(store, args.repo, args.actor, supersedes, 'superseded', `Replaced by decision ${id}.`, now);
         reindexProjectMemory(store, args.repo);
@@ -133,15 +147,16 @@ function changeStatus(store, repo, actor, id, status, reason, now) {
         throw Error('That decision is unavailable.');
     if (existing.status !== 'active')
         throw Error('That decision is no longer active.');
-    const next = { ...existing, revision: existing.revision + 1, status };
+    const { id: _id, ...was } = existing;
+    const next = { ...was, revision: existing.revision + 1, status };
     store.handle.prepare('UPDATE project_decision SET revision=?,status=?,sha=? WHERE id=?').run(next.revision, status, digestOf(next), id);
-    store.handle.prepare('INSERT INTO decision_change(decision,revision,actor,at,action,payload,sha) VALUES (?,?,?,?,?,?,?)').run(id, next.revision, actor, now.toISOString(), status, JSON.stringify({ reason }), digestOf(next));
+    store.handle.prepare('INSERT INTO decision_change(decision,revision,actor,at,action,payload,sha) VALUES (?,?,?,?,?,?,?)').run(id, next.revision, actor, now.toISOString(), status, history({ reason }), digestOf(next));
     return { id, ...next };
 }
 /** Retire a decision that no longer holds; history keeps it. */
 export function retireDecision(store, args, now = new Date()) {
     admission(store, args.repo, args.actor, true);
-    const reason = clean(args.reason, 500, 'The reason');
+    const reason = clean(args.reason, TEXT_LIMITS.decisionRetireBytes, 'The reason');
     return store.transact(() => { const d = changeStatus(store, args.repo, args.actor, args.id, 'retired', reason, now); reindexProjectMemory(store, args.repo); return d; });
 }
 export function decisionHistory(store, repo, actor, id) {
@@ -166,7 +181,7 @@ export function decisionLines(store, repo, query, options = {}) {
         return { line: { id: Number(row['id']), claim, decidedAt: String(row['decided_at']) }, score };
     })
         .sort((a, b) => b.score - a.score || b.line.id - a.line.id);
-    const limit = options.limit ?? 8, bytes = options.bytes ?? 1500, out = [];
+    const limit = options.limit ?? 8, bytes = options.bytes ?? TEXT_LIMITS.knowledgeDecisionsBytes, out = [];
     for (const { line } of ranked) {
         if (out.length >= limit)
             break;

package/dist/project-skills.d.ts

@@ -1,48 +1,27 @@
 import type { Store } from "./store.js";
+import { SKILL_LIMITS, type SavedSkill, type SkillFile, type SkillPackage, type SkillSelection, type SkillsSnapshot } from "./contracts/project-skills.js";
+export { SKILL_LIMITS };
+export type { SavedSkill, SkillFile, SkillPackage, SkillsSnapshot };
 export declare const SKILLS_SCHEMA: string;
-export type SkillFile = {
-    path: string;
-    base64: string;
-};
-export type SkillPackage = {
-    name: string;
-    description: string;
-    source: string;
-    requirements: string;
-    warnings: string[];
-    files: SkillFile[];
-};
-export type SavedSkill = SkillPackage & {
-    sha: string;
-};
-type Choice = {
-    sha: string;
-    enabled: boolean;
-};
-type Selection = Record<string, Choice>;
-export type SkillsSnapshot = {
-    version: 1;
-    revision: number;
-    identity: string;
-    inheritedFrom: number | null;
-    test: boolean;
-    packages: SavedSkill[];
-};
-export declare const SKILL_LIMITS: {
-    files: number;
-    packageBytes: number;
-    fileBytes: number;
-    bodyBytes: number;
-    enabled: number;
-    selectionBytes: number;
-};
+type Selection = SkillSelection;
 export declare function validateSkill(files: SkillFile[], source: string): SkillPackage;
 export declare function skillsView(store: Store, repo: string, actor: string): {
     revision: number;
     selection: Selection;
     repo: string;
     identity: string;
-    library: SavedSkill[];
+    library: {
+        name: string;
+        description: string;
+        source: string;
+        requirements: string;
+        warnings: string[];
+        files: {
+            path: string;
+            base64: string;
+        }[];
+        sha: string;
+    }[];
     history: {
         revision: number;
         actor: string;
@@ -159,4 +138,3 @@ export declare function githubSkill(url: string, fetcher?: typeof fetch): Promis
     files: SkillFile[];
     source: string;
 }>;
-export {};