src/canon.ts

Functions

Imports

It imports src/agents.ts, src/auth.ts, src/jobs-transition.ts, src/scope.ts, src/store-guards.ts. Imported by src/controls-base.ts, src/controls-perform.ts, src/controls-plan.ts, src/ops-feed.ts, src/stale-canon.ts, src/status.ts, src/supersede.ts, src/tools/docs-lifecycle.ts, src/tools/docs-write.ts.

Source

1import type { Agent } from "./agents";
2import { sha256Hex } from "./auth";
3import { callerIsSeat } from "./jobs-transition";
4import { TOOL_GRANTS } from "./scope";
5import { auditStatement, documentUpsert, isMissingRowAbort, requireBodyUnchanged, requireMissing, snapshotLive } from "./store-guards";
6
7// CANON WRITE-PROTECTION (OWASP hardening item 2; design:
8// capsid/research/design-owasp-hardening.md, "Item 2").
9//
10// Canon is what every agent is told to trust: the portfolio rules, each namespace's
11// core.md and its decisions log. A driver's `capsid_write_doc` to one is not applied. It becomes a row in
12// canon_proposals (migrations/0034) and the write answers pending_review. The admin
13// approves it, applied as an ordinary write guarded on the body it was written against,
14// or rejects it, through the `canon_approve` and `canon_reject` controls (src/controls.ts,
15// the Portal and capsid_admin_run_controls). restore, delete and move on a canon path are
16// refused for such a caller: a proposal carries a body, and those three do not.
17//
18// The admin's and the seat's own writes are not queued (callerIsSeat: admin or
19// can_merge, the same test every seat-only job transition uses).
20//
21// Lines a proposal adds that read as instructions to agents are flagged for the
22// reviewer, never auto-rejected: the rulings in a decisions log are themselves
23// instructions to agents, and an automatic reject would refuse the seat's own canon.
24
25export interface CanonRule {
26  // "*" is every namespace.
27  namespace: string;
28  pattern: RegExp;
29  label: string;
30}
31
32// test/canon.test.ts pins this list.
33export const CANON_RULES: readonly CanonRule[] = [
34  { namespace: "capsid", pattern: /^conventions(-[a-z0-9]+)*\.md$/, label: "capsid/conventions.md and capsid/conventions-<name>.md" },
35  { namespace: "*", pattern: /^core\.md$/, label: "<namespace>/core.md" },
36  { namespace: "*", pattern: /^(decisions|archive\/decisions(-vol-[1-9][0-9]{0,3})?)\.md$/, label: "<namespace>/decisions.md and its archived volumes" },
37];
38
39/** Whether a document is canon. Exact strings: documents are keyed by the exact path,
40 *  so "Core.md" or "./core.md" is another document, which no reader takes for canon. */
41export function isCanonPath(namespace: string, path: string): boolean {
42  return CANON_RULES.some((r) => (r.namespace === "*" || r.namespace === namespace) && r.pattern.test(path));
43}
44
45/** Whether this caller's change to this document goes to review instead of the store. */
46export function canonGuarded(agent: Agent, namespace: string, path: string): boolean {
47  return !callerIsSeat(agent) && isCanonPath(namespace, path);
48}
49
50/** The list as capsid_run_improve action status serves it, beside protected_paths. */
51export function servedCanonPaths(): Array<{ namespace: string; source: string; label: string }> {
52  return CANON_RULES.map((r) => ({ namespace: r.namespace, source: r.pattern.source, label: r.label }));
53}
54
55/** The refusal restore, delete and move give a guarded caller on a canon path. */
56export function canonRefusal(tool: "restore" | "delete" | "move", namespace: string, path: string): string {
57  return (
58    `${namespace}/${path} is canon (src/canon.ts), and a ${tool} of it by a driver is refused. Nothing changed. ` +
59    `Canon changes by proposal: write the body you want with \`capsid_write_doc\` and it is queued for the seat or Dustin to approve` +
60    (tool === "restore" ? " (read the version with `capsid_read_doc` action `versions` to get its body)." : ".")
61  );
62}
63
64// ---------------------------------------------------------------------------
65// Instruction-shaped lines.
66
67// A line is compared with these after its markdown lead (list marker, quote, heading,
68// bold) is stripped and it is lowercased. Published in docs/schema.md.
69const DIRECTIVE_OPENERS: readonly string[] = [
70  "you must",
71  "you should",
72  "you will",
73  "you are to",
74  "always ",
75  "never ",
76  "ignore ",
77  "disregard ",
78  "forget ",
79  "do not ",
80  "don't ",
81  "from now on",
82  "agents must",
83  "agents should",
84  "the agent must",
85  "drivers must",
86  "a driver must",
87  "every session must",
88  "sessions must",
89];
90// Or an imperative naming a served tool: "call capsid_write_doc ...", "run `capsid_work_jobs` ...".
91const TOOL_IMPERATIVE = /^(call|run|use|invoke)\s+`?([a-z_]+)`?(\s|$)/;
92
93function stripLead(line: string): string {
94  return line
95    .trim()
96    .replace(/^(?:[-*+]\s+|\d+[.)]\s+|>\s*|#{1,6}\s+)+/, "")
97    .replace(/\*\*|__/g, "")
98    .trim()
99    .toLowerCase();
100}
101
102/** Whether one line reads as an instruction addressed to agents. */
103export function isDirectiveLine(line: string): boolean {
104  const text = stripLead(line);
105  if (!text) return false;
106  if (DIRECTIVE_OPENERS.some((opener) => text.startsWith(opener))) return true;
107  const tool = TOOL_IMPERATIVE.exec(text)?.[2];
108  return tool !== undefined && Object.prototype.hasOwnProperty.call(TOOL_GRANTS, tool);
109}
110
111/** The lines `after` adds to `before` and the lines it drops, as multisets: a line
112 *  moved within the document is neither. Order follows the document. */
113export function lineChanges(before: string | null, after: string): { added: string[]; removed: string[] } {
114  const counts = new Map<string, number>();
115  for (const line of (before ?? "").split("\n")) counts.set(line, (counts.get(line) ?? 0) + 1);
116  const added: string[] = [];
117  for (const line of after.split("\n")) {
118    const n = counts.get(line) ?? 0;
119    if (n > 0) counts.set(line, n - 1);
120    else added.push(line);
121  }
122  const removed: string[] = [];
123  for (const line of (before ?? "").split("\n")) {
124    const n = counts.get(line) ?? 0;
125    if (n > 0) {
126      removed.push(line);
127      counts.set(line, n - 1);
128    }
129  }
130  const content = (l: string) => l.trim() !== "";
131  return { added: added.filter(content), removed: removed.filter(content) };
132}
133
134/** The added lines that read as instructions to agents. */
135export function directiveLines(before: string | null, after: string): string[] {
136  return lineChanges(before, after).added.filter(isDirectiveLine);
137}
138
139// ---------------------------------------------------------------------------
140// The queue.
141
142export interface ProposalInput {
143  namespace: string;
144  path: string;
145  title: string | null;
146  body: string;
147  type: string | null;
148  tags: string | null;
149  status: string | null;
150  mode: string;
151  // The body the write read; null when the document did not exist.
152  priorBody: string | null;
153  priorExists: boolean;
154}
155
156export interface Proposed {
157  id: number;
158  base_sha: string | null;
159  directive_lines: string[];
160}
161
162/** Stores a guarded caller's write as a pending proposal, with its audit row, in one
163 *  batch. Nothing in documents changes. */
164export async function proposeCanon(db: D1Database, actor: string, now: Date, input: ProposalInput): Promise<Proposed> {
165  const baseSha = input.priorExists ? await sha256Hex(input.priorBody ?? "") : null;
166  const flagged = directiveLines(input.priorBody, input.body);
167  const [inserted] = await db.batch([
168    db
169      .prepare(
170        `INSERT INTO canon_proposals (namespace, path, title, body, type, tags, status, mode, base_sha, proposer, created_at, directive_lines)
171         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12)
172         RETURNING id`
173      )
174      .bind(input.namespace, input.path, input.title, input.body, input.type, input.tags, input.status, input.mode, baseSha, actor, now.toISOString(), JSON.stringify(flagged)),
175    auditStatement(db, actor, "canon-proposed", input.namespace, input.path, { mode: input.mode, base_sha: baseSha, directive_lines: flagged.length }),
176  ]);
177  const id = (inserted?.results?.[0] as { id?: number } | undefined)?.id;
178  if (typeof id !== "number") throw new Error(`the proposal for ${input.namespace}/${input.path} was not stored: the insert returned no id`);
179  return { id, base_sha: baseSha, directive_lines: flagged };
180}
181
182interface ProposalRow {
183  id: number;
184  namespace: string;
185  path: string;
186  title: string | null;
187  body: string;
188  type: string | null;
189  tags: string | null;
190  status: string | null;
191  mode: string;
192  base_sha: string | null;
193  proposer: string;
194  created_at: string;
195  directive_lines: string;
196  state: "pending" | "approved" | "rejected";
197  decided_by: string | null;
198  decided_at: string | null;
199  decided_reason: string | null;
200}
201
202async function readProposal(db: D1Database, id: number): Promise<ProposalRow | null> {
203  return db.prepare("SELECT * FROM canon_proposals WHERE id = ?1").bind(id).first<ProposalRow>();
204}
205
206// The pending queue is short by construction (each row waits on one person), so this is
207// a guard, not a page.
208const PENDING_LIMIT = 50;
209
210export interface PendingProposal {
211  id: number;
212  namespace: string;
213  path: string;
214  proposer: string;
215  created_at: string;
216  // Whether the document existed when the proposal was written.
217  creates: boolean;
218  // Whether the stored body is still the one the proposal was written against. A stale
219  // proposal cannot be approved; it is rejected and written again.
220  stale: boolean;
221  added: number;
222  removed: number;
223  directive_lines: string[];
224}
225
226/** The pending proposals, oldest first, each measured against the document as it is
227 *  now. One read whatever the count: the feed's read budget is fixed
228 *  (OPS_FEED_READS in src/ops-feed.ts). */
229export async function pendingProposals(db: D1Database): Promise<PendingProposal[]> {
230  const { results } = await db
231    .prepare(
232      `SELECT p.id, p.namespace, p.path, p.body, p.base_sha, p.proposer, p.created_at, p.directive_lines,
233              d.id AS doc_id, d.body AS current_body
234       FROM canon_proposals p LEFT JOIN documents d ON d.namespace = p.namespace AND d.path = p.path
235       WHERE p.state = 'pending' ORDER BY p.id LIMIT ?1`
236    )
237    .bind(PENDING_LIMIT)
238    .all<Pick<ProposalRow, "id" | "namespace" | "path" | "body" | "base_sha" | "proposer" | "created_at" | "directive_lines"> & { doc_id: number | null; current_body: string | null }>();
239  return Promise.all(
240    (results ?? []).map(async (r) => {
241      const current = r.doc_id === null ? null : (r.current_body ?? "");
242      const sha = current === null ? null : await sha256Hex(current);
243      const change = lineChanges(current, r.body);
244      return {
245        id: r.id,
246        namespace: r.namespace,
247        path: r.path,
248        proposer: r.proposer,
249        created_at: r.created_at,
250        creates: r.base_sha === null,
251        stale: sha !== r.base_sha,
252        added: change.added.length,
253        removed: change.removed.length,
254        directive_lines: parseLines(r.directive_lines),
255      };
256    })
257  );
258}
259
260function parseLines(raw: string): string[] {
261  try {
262    const parsed: unknown = JSON.parse(raw);
263    return Array.isArray(parsed) ? parsed.filter((l): l is string => typeof l === "string") : [];
264  } catch {
265    // Written by proposeCanon from JSON.stringify; unreadable means a hand-edited row,
266    // shown as no flagged lines rather than failing the whole queue read.
267    return [];
268  }
269}
270
271export type ProposalCheck =
272  | { ok: true; row: ProposalRow; current: string | null; directive: string[] }
273  | { ok: false; refusal: string };
274
275/** A pending proposal, and the document as it is now, or why it cannot be decided.
276 *  `forApproval` also refuses a proposal whose base has moved. */
277export async function checkProposal(db: D1Database, id: number, forApproval: boolean): Promise<ProposalCheck> {
278  const row = await readProposal(db, id);
279  if (!row) return { ok: false, refusal: `no canon proposal ${id}.` };
280  if (row.state !== "pending") return { ok: false, refusal: `canon proposal ${id} was already ${row.state}${row.decided_by ? ` by ${row.decided_by}` : ""}${row.decided_at ? ` at ${row.decided_at}` : ""}.` };
281  const doc = await db.prepare("SELECT body FROM documents WHERE namespace = ?1 AND path = ?2").bind(row.namespace, row.path).first<{ body: string | null }>();
282  const current = doc ? (doc.body ?? "") : null;
283  if (forApproval) {
284    const sha = doc ? await sha256Hex(current ?? "") : null;
285    if (sha !== row.base_sha) {
286      return {
287        ok: false,
288        refusal:
289          row.base_sha === null
290            ? `${row.namespace}/${row.path} did not exist when proposal ${id} was written, and it does now. Approving would overwrite a body the proposer never read. Reject it, and the proposer writes it again against the current body.`
291            : `${row.namespace}/${row.path} changed since proposal ${id} was written (written against ${row.base_sha.slice(0, 12)}, now ${sha ? sha.slice(0, 12) : "deleted"}). Approving would overwrite a body the proposer never read. Reject it, and the proposer writes it again against the current body.`,
292      };
293    }
294  }
295  return { ok: true, row, current, directive: parseLines(row.directive_lines) };
296}
297
298export type Decided = { ok: true; row: ProposalRow; sha256: string; snapshotted: boolean } | { ok: false; refusal: string };
299
300// The proposal is still pending, inside the batch: the same NOT NULL abort the store's
301// other guards use (src/store-guards.ts), so a second approve, or an approve racing a
302// reject, changes nothing.
303function requirePending(db: D1Database, id: number): D1PreparedStatement {
304  return db
305    .prepare(
306      `INSERT INTO document_versions (document_id, namespace, path)
307       SELECT NULL, 'canon_proposals', ?1
308       WHERE NOT EXISTS (SELECT 1 FROM canon_proposals WHERE id = ?1 AND state = 'pending')`
309    )
310    .bind(String(id));
311}
312
313/** Approves a proposal: the document is written as the proposal says, as an ordinary
314 *  write (snapshot of the live row, the upsert, an audit row naming the approver and the
315 *  proposal), guarded in the batch on the base body and on the proposal still pending.
316 *  snapshot invariant, test/write-invariants.test.ts. */
317export async function approveProposal(db: D1Database, actor: string, now: Date, id: number): Promise<Decided> {
318  const checked = await checkProposal(db, id, true);
319  if (!checked.ok) return checked;
320  const { row, current } = checked;
321  const exists = row.base_sha !== null;
322  try {
323    const results = await db.batch([
324      requirePending(db, id),
325      exists ? requireBodyUnchanged(db, row.namespace, row.path, current) : requireMissing(db, row.namespace, row.path),
326      ...(exists ? [snapshotLive(db, row.namespace, row.path)] : []),
327      documentUpsert(db, row.namespace, row.path, row.title, row.body, row.type, row.tags, row.status),
328      auditStatement(db, actor, "write", row.namespace, row.path, {
329        title: row.title ?? undefined,
330        type: row.type ?? undefined,
331        tags: row.tags ?? undefined,
332        status: row.status ?? undefined,
333        mode: row.mode,
334        updated: exists,
335        canon_proposal: id,
336        proposer: row.proposer,
337      }),
338      db
339        .prepare("UPDATE canon_proposals SET state = 'approved', decided_by = ?2, decided_at = ?3 WHERE id = ?1 AND state = 'pending'")
340        .bind(id, actor, now.toISOString()),
341    ]);
342    const snapshotted = exists && (results[2]?.results?.length ?? 0) > 0;
343    return { ok: true, row, sha256: await sha256Hex(row.body), snapshotted };
344  } catch (err) {
345    if (!isMissingRowAbort(err)) throw err;
346    return { ok: false, refusal: `canon proposal ${id} was not applied: it was decided, or ${row.namespace}/${row.path} changed, while this approval ran. Nothing changed. Preview it again.` };
347  }
348}
349
350/** Rejects a proposal, with the reason the proposer reads. The document is untouched. */
351export async function rejectProposal(db: D1Database, actor: string, now: Date, id: number, reason: string): Promise<Decided> {
352  const checked = await checkProposal(db, id, false);
353  if (!checked.ok) return checked;
354  const { row } = checked;
355  try {
356    await db.batch([
357      requirePending(db, id),
358      db
359        .prepare("UPDATE canon_proposals SET state = 'rejected', decided_by = ?2, decided_at = ?3, decided_reason = ?4 WHERE id = ?1 AND state = 'pending'")
360        .bind(id, actor, now.toISOString(), reason),
361      auditStatement(db, actor, "canon-rejected", row.namespace, row.path, { canon_proposal: id, proposer: row.proposer, reason }),
362    ]);
363  } catch (err) {
364    if (!isMissingRowAbort(err)) throw err;
365    return { ok: false, refusal: `canon proposal ${id} was decided while this rejection ran. Nothing changed.` };
366  }
367  return { ok: true, row, sha256: await sha256Hex(row.body), snapshotted: false };
368}
369
370// ---------------------------------------------------------------------------
371// Approve all (the canon_approve_all control, src/controls.ts): one decision over the
372// whole pending queue, each proposal still decided by approveProposal or rejectProposal
373// above, so its snapshot, audit row and guards are the single decision's
374// (snapshot invariant, test/write-invariants.test.ts).
375
376type SweepOutcome = "approve" | "superseded" | "outdated";
377
378export interface SweepItem {
379  proposal: PendingProposal;
380  outcome: SweepOutcome;
381  // The reason the proposer reads; null for an approval.
382  reason: string | null;
383}
384
385const docKey = (p: PendingProposal) => JSON.stringify([p.namespace, p.path]);
386
387/** What approve all does to each pending proposal, by id. The newest proposal on a
388 *  document (the highest id) is its candidate; every older one on it is rejected as
389 *  superseded. A stale candidate (its document moved, or now exists when it was a
390 *  create) is rejected as outdated, and every other candidate is approved. Pure. */
391export function planSweep(pending: readonly PendingProposal[]): SweepItem[] {
392  const newest = new Map<string, number>();
393  for (const p of pending) newest.set(docKey(p), Math.max(newest.get(docKey(p)) ?? 0, p.id));
394  return [...pending]
395    .sort((a, b) => a.id - b.id)
396    .map((p): SweepItem => {
397      const top = newest.get(docKey(p)) ?? p.id;
398      if (p.id !== top) return { proposal: p, outcome: "superseded", reason: `superseded by proposal ${top} on the same document` };
399      if (p.stale) {
400        return {
401          proposal: p,
402          outcome: "outdated",
403          reason: `outdated: ${p.namespace}/${p.path} changed after this proposal was written; write it again against the current body`,
404        };
405      }
406      return { proposal: p, outcome: "approve", reason: null };
407    });
408}
409
410/** The plan in one spelling, "<id>:<outcome>" by id, which the confirmation token binds:
411 *  a perform whose plan reads differently now is refused. */
412export function sweepKey(items: readonly SweepItem[]): string {
413  return items.map((i) => `${i.proposal.id}:${i.outcome}`).join(",");
414}
415
416export type Sweep = { ok: true; items: SweepItem[]; key: string } | { ok: false; refusal: string };
417
418/** The plan from the queue as it is now, or why there is none. Reads only. */
419export async function readSweep(db: D1Database): Promise<Sweep> {
420  const pending = await pendingProposals(db);
421  if (!pending.length) return { ok: false, refusal: "no pending canon proposals." };
422  // pendingProposals reads the oldest PENDING_LIMIT. A full read may have left out a newer
423  // proposal on a document it holds, which would change what is newest, so it is refused.
424  if (pending.length >= PENDING_LIMIT) {
425    return {
426      ok: false,
427      refusal: `${PENDING_LIMIT} or more canon proposals are pending, and approve all reads at most ${PENDING_LIMIT}, so it could miss a newer proposal on a document it decides. Decide some one at a time, then preview again.`,
428    };
429  }
430  const items = planSweep(pending);
431  return { ok: true, items, key: sweepKey(items) };
432}