src/doc-statements.ts

Functions

Imports

It imports src/auth.ts, src/normalize.ts, src/store-guards.ts. Imported by src/approval-executor.ts, src/auto-merge-tick.ts, src/jobs-mirror.ts, src/operator-key.ts.

Source

1import { sha256Hex } from "./auth";
2import { normalizeDashes } from "./normalize";
3import { auditStatement, snapshotLive } from "./store-guards";
4
5// The audit actor of the Worker's own unattended actions (the auto-merge tick, an
6// approved merge executed). The string is the improve loop's, which wrote these rows
7// first; it is kept so audit_log reads as one series and src/job-touches.ts still
8// recognises it.
9const SYSTEM_ACTOR = "improve-loop";
10
11// A system document write (a job's mirror document) under the same two invariants as
12// every other write path (snapshot invariant, test/write-invariants.test.ts): the prior row is snapshotted into
13// document_versions and audit_log gets a row, in the same batch as the write, so all
14// three land or none do. Returns statements so a caller can batch them with the row
15// update they belong to.
16export async function docStatements(
17  db: D1Database,
18  doc: {
19    namespace: string;
20    path: string;
21    title: string;
22    body: string;
23    type: string;
24    status?: string;
25    tags: string;
26    prior: { id: number; title: string | null; body: string | null } | null;
27    action: string;
28    // Who the audit row names: the job's actor, because audit_log is the one place that
29    // answers who did it.
30    actor: string;
31  }
32): Promise<D1PreparedStatement[]> {
33  // Server-side dash normalization, as capsid_write_doc applies.
34  const body = normalizeDashes(doc.body, "prose");
35  const title = normalizeDashes(doc.title, "title");
36
37  // The snapshot selects the live row inside the batch rather than binding doc.prior,
38  // read earlier: a write landing in between (the job claim path waits on GitHub
39  // there) is still snapshotted. With no row it inserts nothing.
40  const statements: D1PreparedStatement[] = [snapshotLive(db, doc.namespace, doc.path)];
41  statements.push(
42    db
43      .prepare(
44        `INSERT INTO documents (namespace, path, title, body, type, tags, status)
45         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)
46         ON CONFLICT(namespace, path) DO UPDATE SET
47           title = ?3, body = excluded.body, type = ?5, tags = ?6, status = ?7,
48           updated_at = datetime('now')`
49      )
50      .bind(doc.namespace, doc.path, title, body, doc.type, doc.tags, doc.status ?? "published")
51  );
52  statements.push(
53    auditStatement(db, doc.actor, doc.action, doc.namespace, doc.path, {
54      bytes: body.length,
55      sha256: await sha256Hex(body),
56      updated: Boolean(doc.prior),
57    })
58  );
59  return statements;
60}
61
62export async function priorDoc(
63  db: D1Database,
64  namespace: string,
65  path: string
66): Promise<{ id: number; title: string | null; body: string | null } | null> {
67  return db
68    .prepare("SELECT id, title, body FROM documents WHERE namespace = ?1 AND path = ?2")
69    .bind(namespace, path)
70    .first<{ id: number; title: string | null; body: string | null }>();
71}
72
73// An audit row for a system action that is not a document write (an auto-merge, a
74// decline, an approval executed), under SYSTEM_ACTOR, so one query answers what the
75// Worker did on its own. An action a person made names that person: `actor` is the
76// caller (controls design, finding 5).
77export function systemAudit(
78  db: D1Database,
79  action: string,
80  namespace: string | null,
81  params: unknown,
82  actor: string = SYSTEM_ACTOR
83): D1PreparedStatement {
84  return auditStatement(db, actor, action, namespace, null, params);
85}