toolroll 0.9.36 → 0.9.37

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 {};

package/dist/project-skills.js

@@ -6,6 +6,10 @@ import { parseDocument } from "yaml";
 import { acceptedIdentities, learningIdentity, learningSha } from "./project-learning.js";
 import { scanForSecrets } from "./evidence.js";
 import { fileTaskProposal } from "./proposal.js";
+import { TEXT_LIMITS } from "./text-limits.js";
+import { contractError } from "./contracts/contract.js";
+import { SKILL_COUNTS, SKILL_LIMITS, readSkillsSnapshotPayload, savedSkillPackageSchema, savedSkillsSnapshotSchema, skillPackageSchema, skillSelectionSchema, } from "./contracts/project-skills.js";
+export { SKILL_LIMITS };
 export const SKILLS_SCHEMA = `
 CREATE TABLE IF NOT EXISTS skill_package (sha TEXT PRIMARY KEY, payload TEXT NOT NULL);
 CREATE TABLE IF NOT EXISTS skill_owner (sha TEXT NOT NULL REFERENCES skill_package(sha), actor TEXT NOT NULL, at TEXT NOT NULL, PRIMARY KEY(sha,actor));
@@ -14,14 +18,6 @@ CREATE TABLE IF NOT EXISTS skill_snapshot (run INTEGER PRIMARY KEY REFERENCES ru
 CREATE TABLE IF NOT EXISTS skill_test (task_ref INTEGER PRIMARY KEY REFERENCES task_ref(id), package TEXT NOT NULL REFERENCES skill_package(sha), actor TEXT NOT NULL, request_sha TEXT NOT NULL, sample TEXT NOT NULL, source_run INTEGER REFERENCES run(id), feedback TEXT, identity TEXT NOT NULL);
 ${["skill_package", "skill_owner", "project_skill_change", "skill_snapshot", "skill_test"].map((t) => `CREATE TRIGGER IF NOT EXISTS ${t}_no_update BEFORE UPDATE ON ${t} BEGIN SELECT RAISE(ABORT,'Skill history is immutable'); END; CREATE TRIGGER IF NOT EXISTS ${t}_no_delete BEFORE DELETE ON ${t} BEGIN SELECT RAISE(ABORT,'Skill history is immutable'); END;`).join("\n")}
 `;
-export const SKILL_LIMITS = {
-    files: 64,
-    packageBytes: 1024 * 1024,
-    fileBytes: 256 * 1024,
-    bodyBytes: 24 * 1024,
-    enabled: 8,
-    selectionBytes: 2 * 1024 * 1024,
-};
 const controls = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufffd]/u;
 const text = (value, max, label) => {
     if (typeof value !== "string" ||
@@ -44,7 +40,7 @@ export function validateSkill(files, source) {
         .map((file) => {
         if (!file ||
             typeof file.path !== "string" ||
-            file.path.length > 240 ||
+            file.path.length > TEXT_LIMITS.skillPath ||
             !/^[a-zA-Z0-9_. -]+(?:\/[a-zA-Z0-9_. -]+)*$/.test(file.path) ||
             file.path
                 .split("/")
@@ -91,13 +87,13 @@ export function validateSkill(files, source) {
     }
     if (!front || typeof front !== "object" || Array.isArray(front))
         throw Error("Skill metadata must contain a name and description.");
-    const name = text(front["name"], 64, "Skill name");
+    const name = text(front["name"], TEXT_LIMITS.skillNameBytes, "Skill name");
     if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name))
         throw Error("Use a lowercase skill name with hyphens between words.");
-    const description = text(front["description"], 1024, "Description");
+    const description = text(front["description"], TEXT_LIMITS.skillDescriptionBytes, "Description");
     const requirements = front["compatibility"] === undefined
         ? ""
-        : text(front["compatibility"], 500, "Requirements");
+        : text(front["compatibility"], TEXT_LIMITS.skillRequirementsBytes, "Requirements");
     const extensions = Object.keys(front).filter((k) => !["name", "description", "license", "compatibility", "metadata"].includes(k));
     const warnings = [];
     if (extensions.length || safe.some((f) => f.path === "agents/openai.yaml"))
@@ -106,14 +102,21 @@ export function validateSkill(files, source) {
         warnings.push("Dynamic shell substitutions are not evaluated by the skill manager.");
     if (safe.some((f) => f.path.startsWith("scripts/")))
         warnings.push("Includes scripts. Agents may run them only within their task permissions.");
-    return {
+    return written(skillPackageSchema, {
         name,
         description,
-        source: text(source, 500, "Source"),
+        source: text(source, TEXT_LIMITS.skillSourceBytes, "Source"),
         requirements,
         warnings,
         files: safe,
-    };
+    });
+}
+/** A payload through its schema before it is written; a refusal names the field. */
+function written(schema, value) {
+    const read = schema.safeParse(value, { reportInput: true });
+    if (!read.success)
+        throw Error(`This skill could not be saved: ${contractError(read.error).join("; ")}`);
+    return read.data;
 }
 function admit(store, repo, actor, write = false) {
     if (!store.schemaCurrent() ||
@@ -125,18 +128,24 @@ function admit(store, repo, actor, write = false) {
 /** Revisions under any identity this project accepts, as a bound JSON list. */
 const IN_ACCEPTED = "identity IN (SELECT value FROM json_each(?))";
 const listOf = (accepted) => JSON.stringify([...accepted]);
-function unpack(payload, sha) {
+/** Saved bytes are checked against their digest first; only then are they parsed through their schema. */
+function unpack(payload, sha, read) {
     if (typeof payload !== "string" || learningSha(payload) !== sha)
         throw Error("Saved skills could not be verified.");
-    return JSON.parse(payload);
+    const value = read(JSON.parse(payload));
+    if (value === null)
+        throw Error("Saved skills could not be verified.");
+    return value;
 }
+const through = (schema) => (input) => { const read = schema.safeParse(input); return read.success ? read.data : null; };
+const unpackSelection = (payload, sha) => unpack(payload, sha, through(skillSelectionSchema));
 function packageOf(store, sha) {
     const row = store.handle
         .prepare("SELECT payload FROM skill_package WHERE sha=?")
         .get(sha);
     if (!row)
         throw Error("That skill version is unavailable.");
-    return { ...unpack(row["payload"], sha), sha };
+    return { ...unpack(row["payload"], sha, through(savedSkillPackageSchema)), sha };
 }
 function current(store, repo, accepted) {
     const row = store.handle
@@ -148,7 +157,7 @@ function current(store, repo, accepted) {
         throw Error("The project changed. Its previous skills have not been applied.");
     return {
         revision: Number(row["revision"]),
-        selection: unpack(row["payload"], row["sha"]),
+        selection: unpackSelection(row["payload"], row["sha"]),
     };
 }
 export function skillsView(store, repo, actor) {
@@ -173,7 +182,7 @@ export function skillsView(store, repo, actor) {
             }
         }
         if (row)
-            for (const c of Object.values(unpack(row["payload"], row["sha"])))
+            for (const c of Object.values(unpackSelection(row["payload"], row["sha"])))
                 visible.add(c.sha);
     }
     for (const c of Object.values(value.selection))
@@ -192,7 +201,7 @@ export function skillsView(store, repo, actor) {
         revision: Number(r["revision"]),
         actor: String(r["actor"]),
         at: String(r["at"]),
-        enabled: Object.entries(unpack(r["payload"], r["sha"]))
+        enabled: Object.entries(unpackSelection(r["payload"], r["sha"]))
             .filter(([, c]) => c.enabled)
             .map(([name, c]) => ({ name, version: c.sha.slice(0, 10) })),
     }));
@@ -215,7 +224,7 @@ export function skillsVersion(store, repo, actor, revision) {
     const row = store.handle.prepare(`SELECT payload,sha FROM project_skill_change WHERE repo=? AND ${IN_ACCEPTED} AND revision=?`).get(repo, listOf(accepted), revision);
     if (!row)
         throw Error("That skills version is unavailable.");
-    const selection = unpack(row["payload"], row["sha"]);
+    const selection = unpackSelection(row["payload"], row["sha"]);
     for (const choice of Object.values(selection))
         packageOf(store, choice.sha);
     return selection;
@@ -229,7 +238,7 @@ export function importSkill(store, repo, actor, files, source, now = new Date())
             .get(sha, actor) &&
             Number(store.handle
                 .prepare("SELECT COUNT(*) AS n FROM skill_owner WHERE actor=?")
-                .get(actor)?.["n"]) >= 100)
+                .get(actor)?.["n"]) >= SKILL_COUNTS.library)
             throw Error("Your library has 100 saved versions. Reuse an existing version.");
         store.handle
             .prepare("INSERT OR IGNORE INTO skill_package VALUES (?,?)")
@@ -255,7 +264,7 @@ export function changeSkills(store, args, now = new Date()) {
                 .get(args.repo, listOf(accepted), args.restore ?? -1);
             if (!row)
                 throw Error("That version is unavailable.");
-            selection = unpack(row["payload"], row["sha"]);
+            selection = unpackSelection(row["payload"], row["sha"]);
         }
         else {
             const skill = view.library.find((p) => p.sha === args.sha);
@@ -274,7 +283,7 @@ export function changeSkills(store, args, now = new Date()) {
         if (enabled.length > SKILL_LIMITS.enabled ||
             Buffer.byteLength(JSON.stringify(enabled)) > SKILL_LIMITS.selectionBytes)
             throw Error("Enable up to 8 skills, totaling at most 2 MB.");
-        const payload = JSON.stringify(selection);
+        const payload = JSON.stringify(written(skillSelectionSchema, selection));
         store.handle
             .prepare("INSERT INTO project_skill_change VALUES (?,?,?,?,?,?,?)")
             .run(args.repo, identity, view.revision + 1, args.actor, now.toISOString(), payload, learningSha(payload));
@@ -316,7 +325,7 @@ export function readSkillsSnapshot(store, runId) {
     const run = store.getRun(runId);
     if (!run || store.refForId(run.taskRef)?.repo !== row["repo"])
         throw Error("Saved skills belong to another project.");
-    const saved = unpack(row["payload"], row["sha"]);
+    const saved = unpack(row["payload"], row["sha"], (input) => { const read = readSkillsSnapshotPayload(input); return read.ok ? read.value : null; });
     const { packageShas, ...facts } = saved;
     if (packageShas.length &&
         !acceptedIdentities(store, String(row["repo"])).has(facts.identity))
@@ -401,10 +410,10 @@ export function freezeSkills(store, runId) {
             }
         }
         const { packages, ...facts } = snapshot;
-        const payload = JSON.stringify({
+        const payload = JSON.stringify(written(savedSkillsSnapshotSchema, {
             ...facts,
             packageShas: packages.map((p) => p.sha),
-        });
+        }));
         store.handle
             .prepare("INSERT INTO skill_snapshot VALUES (?,?,?,?)")
             .run(runId, ref.repo, payload, learningSha(payload));
@@ -474,11 +483,11 @@ export function testSkill(store, args, now = new Date()) {
     const skill = view.library.find((p) => p.sha === args.sha);
     if (!skill)
         throw Error("Choose an available skill.");
-    const sample = text(args.sample, 4000, "Sample request");
-    if (sample.length > 800)
+    const sample = text(args.sample, TEXT_LIMITS.skillSampleBytes, "Sample request");
+    if (sample.length > TEXT_LIMITS.skillSample)
         throw Error("Keep the sample request to 800 characters.");
-    const feedback = args.feedback === undefined ? null : text(args.feedback, 2000, "Feedback");
-    if (feedback && feedback.length > 500)
+    const feedback = args.feedback === undefined ? null : text(args.feedback, TEXT_LIMITS.skillFeedbackBytes, "Feedback");
+    if (feedback && feedback.length > TEXT_LIMITS.skillFeedback)
         throw Error("Keep feedback to 500 characters.");
     if (args.sourceRun !== undefined) {
         const source = skillTestResult(store, args.sourceRun, args.actor);

package/dist/project-tools.d.ts

@@ -201,6 +201,7 @@ export declare function prepareRunTools(store: Pick<Store, "projectTools" | "get
     now: Date;
     includeModel: boolean;
     readOnly?: Readonly<Record<string, readonly string[]>>;
+    withheld?: Readonly<Record<string, string>>;
 }): ToolLaunchArgs;
 /** When a launch's tools cannot be prepared, it still gets none of anything else's: the same isolation with an empty list. */
 export declare function noToolsArgs(provider: "claude" | "codex" | "openrouter" | "gemini", includeModel: boolean): ToolLaunchArgs;

package/dist/project-tools.js

@@ -694,7 +694,7 @@ export function toolLaunchFor(store, runId, home = homedir()) {
  * with `argv`/`env` and calls `cleanup` when the process is done.
  */
 export function prepareRunTools(store, runId, provider, options) {
-    const launch = limitedTo(toolLaunchFor(store, runId, options.home), options.readOnly);
+    const launch = limitedTo(toolLaunchFor(store, runId, options.home), options.readOnly, options.withheld);
     const enabledTools = options.readOnly === undefined ? {} : { enabledTools: options.readOnly };
     const prepared = provider === "claude" ? claudeToolArgs(launch)
         : provider === "codex" ? codexToolArgs(launch, { includeModel: options.includeModel, ...enabledTools })
@@ -710,14 +710,14 @@ export function prepareRunTools(store, runId, provider, options) {
     }), options.now);
     return prepared;
 }
-/** A research step's launch: only the servers it may read, each limited to its read-only actions; the rest left out, saying why. */
-function limitedTo(launch, readOnly) {
+/** A research step's launch: only the servers it may read, each limited to its read-only actions; the rest left out, saying why (`withheld`, when a service has its own reason). */
+function limitedTo(launch, readOnly, withheld = {}) {
     if (readOnly === undefined)
         return launch;
     const readable = (name) => (readOnly[name] ?? []).length > 0;
     return {
         tools: launch.tools.filter(one => readable(one.spec.name)),
-        skipped: [...launch.skipped, ...launch.tools.filter(one => !readable(one.spec.name)).map(one => ({ name: one.spec.name, reason: "research reads only connected services' read-only actions" }))],
+        skipped: [...launch.skipped, ...launch.tools.filter(one => !readable(one.spec.name)).map(one => ({ name: one.spec.name, reason: withheld[one.spec.name] ?? "research reads only connected services' read-only actions" }))],
     };
 }
 /** When a launch's tools cannot be prepared, it still gets none of anything else's: the same isolation with an empty list. */