src/store-guards.ts

Functions

Imports

It imports src/auth.ts. Imported by src/access-sync.ts, src/admin-client-audit.ts, src/agents-admin.ts, src/agents-archive.ts, src/bench.ts, src/canon.ts, src/controls-perform.ts, src/doc-statements.ts, src/job-breaker.ts, src/jobs-holder.ts, src/jobs-mirror.ts, src/jobs-transition.ts, src/maintenance-branches.ts, src/maintenance-releases.ts, src/merge-safety.ts, src/merge-units.ts, src/namespace-delete.ts, src/ops-feed.ts, src/ops-packages.ts, src/ops-sites.ts, src/outcome-prs.ts, src/overnight.ts, src/policy-sign.ts, src/pr-approvals.ts, src/push.ts, src/routine-fire.ts, src/shadow.ts, src/site-key.ts, src/site-repair.ts, src/supersede.ts, src/tools/docs-lifecycle.ts, src/tools/docs-write.ts, src/tools/lint.ts, src/tools/namespaces.ts, src/tools/repo-guards.ts.

Source

1import { sha256Hex } from "./auth";
2
3// INSERT that violates NOT NULL, guarded by NOT EXISTS, so a missing row aborts
4// the batch. A pre-read is a different transaction. meta.changes is inflated by
5// FTS5 triggers and cannot count what a batch did.
6const GUARD_VIOLATION = "document_versions.document_id";
7export function requireExists(db: D1Database, namespace: string, path: string): D1PreparedStatement {
8  return db
9    .prepare(
10      `INSERT INTO document_versions (document_id, namespace, path)
11       SELECT NULL, ?1, ?2
12       WHERE NOT EXISTS (SELECT 1 FROM documents WHERE namespace = ?1 AND path = ?2)`
13    )
14    .bind(namespace, path);
15}
16
17// The same abort for a job transition, as the first statement of the batch that
18// carries the UPDATE and every record of it. It fires unless the row is still in the
19// status and holder the caller read, at the updated_at the caller read, so the
20// mirror, audit and outcome rows built from that read commit only with the UPDATE
21// they describe. updated_at moves on every job UPDATE, so any change in between aborts.
22export function requireJobUnchanged(
23  db: D1Database,
24  id: string,
25  status: string,
26  claimedBy: string | null,
27  updatedAt: string
28): D1PreparedStatement {
29  return db
30    .prepare(
31      `INSERT INTO document_versions (document_id, namespace, path)
32       SELECT NULL, 'jobs', ?1
33       WHERE NOT EXISTS (SELECT 1 FROM jobs WHERE id = ?1 AND status = ?2 AND claimed_by IS ?3 AND updated_at = ?4)`
34    )
35    .bind(id, status, claimedBy, updatedAt);
36}
37
38// The same abort for a bench run (src/bench.ts finishRun): fires unless the run is still
39// running, so a run's close and its job's close commit together or not at all.
40export function requireBenchRunRunning(db: D1Database, runId: string): D1PreparedStatement {
41  return db
42    .prepare(
43      `INSERT INTO document_versions (document_id, namespace, path)
44       SELECT NULL, 'bench', ?1
45       WHERE NOT EXISTS (SELECT 1 FROM bench_runs WHERE id = ?1 AND status = 'running')`
46    )
47    .bind(runId);
48}
49
50export function isMissingRowAbort(err: unknown): boolean {
51  return (err instanceof Error ? err.message : String(err)).includes(GUARD_VIOLATION);
52}
53
54// Body equality rather than a stored sha column. `IS` rather than `=` because a
55// NULL body is legitimate and `body = NULL` is never true.
56export function requireBodyUnchanged(
57  db: D1Database,
58  namespace: string,
59  path: string,
60  expectedBody: string | null
61): D1PreparedStatement {
62  return db
63    .prepare(
64      `INSERT INTO document_versions (document_id, namespace, path)
65       SELECT NULL, ?1, ?2
66       WHERE NOT EXISTS (SELECT 1 FROM documents WHERE namespace = ?1 AND path = ?2 AND body IS ?3)`
67    )
68    .bind(namespace, path, expectedBody);
69}
70
71export function requireMissing(db: D1Database, namespace: string, path: string): D1PreparedStatement {
72  return db
73    .prepare(
74      `INSERT INTO document_versions (document_id, namespace, path)
75       SELECT NULL, ?1, ?2
76       WHERE EXISTS (SELECT 1 FROM documents WHERE namespace = ?1 AND path = ?2)`
77    )
78    .bind(namespace, path);
79}
80
81// The snapshot of the live row, one spelling. It selects the row the table holds when
82// the batch runs, not a body read earlier, so a write landing in between is
83// snapshotted rather than lost. It inserts nothing when no row exists.
84export function snapshotLive(db: D1Database, namespace: string, path: string): D1PreparedStatement {
85  return db
86    .prepare(
87      `INSERT INTO document_versions (document_id, namespace, path, title, body)
88       SELECT id, namespace, path, title, body FROM documents WHERE namespace = ?1 AND path = ?2
89       RETURNING id`
90    )
91    .bind(namespace, path);
92}
93
94// Whether a snapshotLive statement inserted a row, from its batch result. Read from
95// RETURNING rather than meta.changes, which the FTS5 triggers inflate.
96export function snapshotTaken(result: D1Result | undefined): boolean {
97  return (result?.results?.length ?? 0) > 0;
98}
99
100type WriteGuard = "none" | "body" | "missing";
101
102type CommitRefusals = {
103  ifMatchOnMissing: string;
104  ifMatchMismatch: (currentSha: string, passed: string) => string;
105  createCollision: string;
106  deletedInFlight: string;
107  bodyChanged: (currentSha: string, elicited: boolean) => string;
108  batchFailed: (reason: string) => string;
109};
110
111export function guardedCommit(opts: {
112  db: D1Database;
113  namespace: string;
114  path: string;
115  prior: { body: string | null } | null;
116  if_match: string | undefined;
117  refusals: CommitRefusals;
118}) {
119  const { db, namespace, path, prior, if_match, refusals } = opts;
120  return {
121    async precheckIfMatch(): Promise<string | null> {
122      if (if_match === undefined) return null;
123      if (!prior) return refusals.ifMatchOnMissing;
124      const currentSha = await sha256Hex(prior.body ?? "");
125      const passed = if_match.trim().toLowerCase();
126      return currentSha === passed ? null : refusals.ifMatchMismatch(currentSha, passed);
127    },
128    // Either the refusal, or the batch results of the caller's own statements in the
129    // order given (the armed guard's result is dropped), so a caller can report what a
130    // statement with RETURNING did.
131    async run(
132      elicited: boolean,
133      statements: D1PreparedStatement[]
134    ): Promise<{ refusal: string } | { results: D1Result[] }> {
135      let guard: WriteGuard = "none";
136      const armed: D1PreparedStatement[] = [];
137      if (!prior) {
138        guard = "missing";
139        armed.push(requireMissing(db, namespace, path));
140      } else if (if_match !== undefined || elicited) {
141        guard = "body";
142        armed.push(requireBodyUnchanged(db, namespace, path, prior.body));
143      }
144      try {
145        const results = await db.batch([...armed, ...statements]);
146        return { results: results.slice(armed.length) };
147      } catch (err) {
148        if (!isMissingRowAbort(err)) {
149          return { refusal: refusals.batchFailed(err instanceof Error ? err.message : String(err)) };
150        }
151        if (guard === "missing") return { refusal: refusals.createCollision };
152        const current = await db
153          .prepare("SELECT body FROM documents WHERE namespace = ?1 AND path = ?2")
154          .bind(namespace, path)
155          .first<{ body: string | null }>();
156        if (!current) return { refusal: refusals.deletedInFlight };
157        return { refusal: refusals.bodyChanged(await sha256Hex(current.body ?? ""), elicited) };
158      }
159    },
160  };
161}
162
163// The document upsert, one spelling, shared by `capsid_write_doc` and `capsid_lint_namespace` mode `report`.
164// COALESCE on every optional column, so an omitted argument leaves the stored value
165// alone. docStatements (src/doc-statements.ts) sets every column and is not folded in.
166//
167// test/mutation-guard-coverage.test.ts and test/tool-annotations.test.ts both match
168// this call as a mutation marker, the same way they match pathMutation().
169export function documentUpsert(
170  db: D1Database,
171  namespace: string,
172  path: string,
173  title: string | null,
174  body: string,
175  type: string | null,
176  tags: string | null,
177  status: string | null
178): D1PreparedStatement {
179  return db
180    .prepare(
181      `INSERT INTO documents (namespace, path, title, body, type, tags, status)
182       VALUES (?1, ?2, ?3, ?4, COALESCE(?5, 'note'), ?6, COALESCE(?7, 'published'))
183       ON CONFLICT(namespace, path) DO UPDATE SET
184         title = COALESCE(?3, documents.title),
185         body = excluded.body,
186         type = COALESCE(?5, documents.type),
187         tags = COALESCE(?6, documents.tags),
188         status = COALESCE(?7, documents.status),
189         updated_at = datetime('now')`
190    )
191    .bind(namespace, path, title, body, type, tags, status);
192}
193
194// The audit row, spelled once. Every write path appends one
195// (snapshot invariant, test/write-invariants.test.ts). params is stored as JSON. An audit row whose params come from inside the batch (delete's
196// edges, a skill transition guarded by its new status) is an INSERT ... SELECT and
197// keeps its own statement.
198export function auditStatement(
199  db: D1Database,
200  actor: string,
201  action: string,
202  namespace: string | null,
203  path: string | null,
204  params: unknown
205): D1PreparedStatement {
206  return db
207    .prepare("INSERT INTO audit_log (actor, action, namespace, path, params) VALUES (?1, ?2, ?3, ?4, ?5)")
208    .bind(actor, action, namespace, path, JSON.stringify(params));
209}