src/supersede.ts

Functions

Imports

It imports src/canon.ts, src/env.ts, src/store-guards.ts. Imported by src/index.ts.

Source

1import { isCanonPath } from "./canon";
2import type { Env } from "./env";
3import { auditStatement, snapshotLive } from "./store-guards";
4
5// The daily supersede pass (capsid/research/design-hybrid-search.md 3.3). A document
6// that a live document `supersedes` or `replaces` (src/links.ts) is marked superseded,
7// so search hides it by default and the current answer is not shown beside the old
8// one. Each change is an ordinary write: the live row is snapshotted, the status set,
9// and an audit row names the edge (snapshot invariant, test/write-invariants.test.ts). It never deletes and
10// never reverses itself. To un-supersede a document, remove the edge as well as editing
11// the status, or the next pass sets it again.
12//
13// Canon (src/canon.ts) is never marked: a driver may write an edge in its own namespace
14// but may not change that namespace's core.md or decisions.md, so an edge to one must
15// not do it on the driver's behalf (Grok audit 2026-10, M4). The seat changes a canon
16// document's status itself. The write path refuses such an edge, and a cross-namespace
17// one the writer cannot write, before it is stored (src/tools/docs-write.ts).
18
19export const SUPERSEDE_ACTOR = "system:supersede-pass";
20// Documents changed per pass, so a bad edge set changes a bounded number.
21export const SUPERSEDE_MAX = 50;
22// Rows read per pass. Canon targets are read and skipped, and are never marked, so they
23// would hold the window forever if it were only SUPERSEDE_MAX + 1 wide.
24const SUPERSEDE_READ = SUPERSEDE_MAX * 4;
25
26const LIVE_SOURCE = ["draft", "superseded", "closed"];
27
28interface Target {
29  namespace: string;
30  path: string;
31  status: string | null;
32  from_ns: string;
33  from_path: string;
34  type: string;
35}
36
37export interface SupersedeReport {
38  marked: Array<{ document: string; by: string }>;
39  // Canon targets an edge names, left as they are.
40  skipped_canon: string[];
41  more: boolean;
42}
43
44export async function supersedePass(env: Env): Promise<SupersedeReport> {
45  const { results } = await env.DB.prepare(
46    `SELECT d.namespace, d.path, d.status, l.from_ns, l.from_path, l.type
47     FROM document_links l
48     JOIN documents s ON s.namespace = l.from_ns AND s.path = l.from_path
49     JOIN documents d ON d.namespace = l.to_ns AND d.path = l.to_path
50     WHERE l.type IN ('supersedes', 'replaces')
51       AND COALESCE(s.status, 'published') NOT IN (SELECT value FROM json_each(?1))
52       AND COALESCE(d.status, 'published') NOT IN ('superseded', 'closed')
53     ORDER BY d.namespace, d.path
54     LIMIT ?2`
55  )
56    .bind(JSON.stringify(LIVE_SOURCE), SUPERSEDE_READ)
57    .all<Target>();
58  const skipped = new Set<string>();
59  const targets = results.filter((t) => {
60    if (!isCanonPath(t.namespace, t.path)) return true;
61    skipped.add(`${t.namespace}/${t.path}`);
62    return false;
63  });
64  const marked: SupersedeReport["marked"] = [];
65  const seen = new Set<string>();
66  for (const t of targets.slice(0, SUPERSEDE_MAX)) {
67    const document = `${t.namespace}/${t.path}`;
68    if (seen.has(document)) continue;
69    seen.add(document);
70    const by = `${t.from_ns}/${t.from_path}`;
71    await env.DB.batch([
72      snapshotLive(env.DB, t.namespace, t.path),
73      env.DB.prepare(
74        `UPDATE documents SET status = 'superseded', updated_at = datetime('now')
75         WHERE namespace = ?1 AND path = ?2 AND COALESCE(status, 'published') NOT IN ('superseded', 'closed')`
76      ).bind(t.namespace, t.path),
77      auditStatement(env.DB, SUPERSEDE_ACTOR, "write", t.namespace, t.path, { status: "superseded", prior_status: t.status, superseded_by: by, link: t.type }),
78    ]);
79    marked.push({ document, by });
80  }
81  return { marked, skipped_canon: [...skipped], more: targets.length > SUPERSEDE_MAX || results.length === SUPERSEDE_READ };
82}