omp-conductor 0.3.24 → 0.4.0

package/src/store.ts

@@ -21,9 +21,22 @@ import type {
   FrictionKind,
   FrictionObservation,
   FrictionSignal,
+  MergeLock,
+  ReportDeliveryState,
+  ReportDraft,
+  ReportEnqueue,
+  ReportKind,
+  ReportRecord,
   RunRecord,
   RunState,
+  SessionRole,
+  SettlementFlag,
   Store,
+  VerbDecision,
+  VerbLedgerDraft,
+  VerbLedgerEntry,
+  VerbName,
+  VerbRefusal,
 } from "./types.ts";
 
 /**
@@ -85,9 +98,13 @@ const UPDATABLE_COLUMNS: Record<string, true> = {
   sessionFile: true,
   prUrl: true,
   headSha: true,
+  salvageSha: true,
+  salvageError: true,
+  salvageAckAt: true,
   startedAt: true,
   endedAt: true,
   lastError: true,
+  settlementFlags: true,
 };
 
 /** Everything SQLite will accept from us. */
@@ -109,9 +126,13 @@ interface RunRow {
   sessionFile: string | null;
   prUrl: string | null;
   headSha: string | null;
+  salvageSha: string | null;
+  salvageError: string | null;
+  salvageAckAt: number | null;
   startedAt: number;
   endedAt: number | null;
   lastError: string | null;
+  settlementFlags: string | null;
 }
 
 interface FrictionRollupRow {
@@ -130,6 +151,49 @@ interface FrictionSurfaceRow {
   at: number;
 }
 
+/** The `reports` table exactly as SQLite hands it back. */
+interface ReportRow {
+  id: string;
+  project: string;
+  kind: string;
+  body: string;
+  state: string;
+  attempts: number;
+  attemptId: string | null;
+  ambiguous: number;
+  dedupeKey: string | null;
+  createdAt: number;
+  updatedAt: number;
+  nextAttemptAt: number;
+  messageId: number | null;
+  deliveredAt: number | null;
+  lastError: string | null;
+}
+
+/** The `verb_ledger` table exactly as SQLite hands it back (#126). */
+interface VerbLedgerRow {
+  id: string;
+  project: string;
+  runId: string | null;
+  issue: number | null;
+  verb: string;
+  role: string;
+  args: string;
+  decision: string;
+  refusal: string | null;
+  detail: string;
+  sha: string | null;
+  at: number;
+}
+
+/** The `merge_locks` table exactly as SQLite hands it back (#126). */
+interface MergeLockRow {
+  project: string;
+  holder: string;
+  prUrl: string;
+  at: number;
+}
+
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS runs (
   id          TEXT    PRIMARY KEY,
@@ -146,9 +210,13 @@ CREATE TABLE IF NOT EXISTS runs (
   sessionFile TEXT,
   prUrl       TEXT,
   headSha     TEXT,
+  salvageSha  TEXT,
+  salvageError TEXT,
+  salvageAckAt INTEGER,
   startedAt   INTEGER NOT NULL,
   endedAt     INTEGER,
-  lastError   TEXT
+  lastError   TEXT,
+  settlementFlags TEXT
 );
 CREATE INDEX IF NOT EXISTS runs_project_issue ON runs (project, issue);
 CREATE INDEX IF NOT EXISTS runs_project_state ON runs (project, state);
@@ -183,6 +251,72 @@ CREATE TABLE IF NOT EXISTS friction_surfaces (
   at      INTEGER NOT NULL,
   PRIMARY KEY (project, kind)
 );
+
+-- The report outbox (#123). Deliberately NOT an extension of notifications:
+-- that table's primary key is its dedupe key, so it cannot hold two attempts of
+-- one report, and widening it would put escalation dedupe and report delivery
+-- on the same row. This one is keyed by report id and carries delivery state,
+-- the attempt in flight, and the message id Telegram actually returned.
+--
+-- The partial unique index is the digest guard: a digest:<day> key can exist at
+-- most once per project, so "has today's digest been handed over?" is a question
+-- the ledger answers rather than the model's memory of the last tick. Material
+-- reports carry no key and are never suppressed.
+CREATE TABLE IF NOT EXISTS reports (
+  id            TEXT    PRIMARY KEY,
+  project       TEXT    NOT NULL,
+  kind          TEXT    NOT NULL,
+  body          TEXT    NOT NULL,
+  state         TEXT    NOT NULL,
+  attempts      INTEGER NOT NULL,
+  attemptId     TEXT,
+  ambiguous     INTEGER NOT NULL,
+  dedupeKey     TEXT,
+  createdAt     INTEGER NOT NULL,
+  updatedAt     INTEGER NOT NULL,
+  nextAttemptAt INTEGER NOT NULL,
+  messageId     INTEGER,
+  deliveredAt   INTEGER,
+  lastError     TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS reports_dedupe
+  ON reports (project, dedupeKey) WHERE dedupeKey IS NOT NULL;
+CREATE INDEX IF NOT EXISTS reports_project_state
+  ON reports (project, state, nextAttemptAt);
+
+-- The action ledger for the conductor-owned mutation verbs (#126). Every
+-- decided call lands here, refusals included: the question an escalation asks
+-- is "what did this run try", and a table that only records what succeeded
+-- cannot answer it. The 'args' column is the payload verbatim, so the row is
+-- evidence rather than a summary of evidence.
+CREATE TABLE IF NOT EXISTS verb_ledger (
+  id       TEXT    PRIMARY KEY,
+  project  TEXT    NOT NULL,
+  runId    TEXT,
+  issue    INTEGER,
+  verb     TEXT    NOT NULL,
+  role     TEXT    NOT NULL,
+  args     TEXT    NOT NULL,
+  decision TEXT    NOT NULL,
+  refusal  TEXT,
+  detail   TEXT    NOT NULL,
+  sha      TEXT,
+  at       INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS verb_ledger_project_at ON verb_ledger (project, at);
+CREATE INDEX IF NOT EXISTS verb_ledger_run ON verb_ledger (runId, at);
+
+-- One merge in flight per project (#126). A table rather than a mutex because
+-- the CLI, the daemon and every session are separate processes: an in-process
+-- lock serialises one process against itself and nothing else, which is the
+-- shape "one merge in flight" had on main -- none at all. The project is the
+-- primary key, so the claim is the row's existence and the race is SQLite's.
+CREATE TABLE IF NOT EXISTS merge_locks (
+  project TEXT    PRIMARY KEY,
+  holder  TEXT    NOT NULL,
+  prUrl   TEXT    NOT NULL,
+  at      INTEGER NOT NULL
+);
 `;
 
 /**
@@ -192,9 +326,41 @@ CREATE TABLE IF NOT EXISTS friction_surfaces (
 function toSql(value: unknown): SqlValue {
   if (value === undefined || value === null) return null;
   if (typeof value === "boolean") return value ? 1 : 0;
+  // `RunRecord.settlementFlags` is the only structured field on a run row, and
+  // it is JSON in one TEXT column rather than a table of its own: the flags are
+  // 1:1 with the run, written once at settlement, and never read except beside
+  // the row they belong to. A join per `status` render would buy a query nobody
+  // makes (#128).
+  if (Array.isArray(value)) return JSON.stringify(value);
   return value as SqlValue;
 }
 
+/**
+ * Settlement flags out of their column, or undefined for anything that is not
+ * an array of flag-shaped objects.
+ *
+ * Same posture as {@link toDispatchSummary}: this is advisory evidence, so a
+ * row hand-edited or written by a future version drops its flags rather than
+ * throwing and taking `status` down with it.
+ */
+function toSettlementFlags(text: string): SettlementFlag[] | undefined {
+  try {
+    const value: unknown = JSON.parse(text);
+    if (!Array.isArray(value) || value.length === 0) return undefined;
+    const flags = value.filter(
+      (flag): flag is SettlementFlag =>
+        typeof flag === "object" &&
+        flag !== null &&
+        typeof (flag as SettlementFlag).kind === "string" &&
+        typeof (flag as SettlementFlag).file === "string" &&
+        typeof (flag as SettlementFlag).detail === "string",
+    );
+    return flags.length === 0 ? undefined : flags;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * A NULL column becomes an absent property rather than an `undefined` one, so
  * a record read back out of the store deep-equals the one that went in.
@@ -217,11 +383,87 @@ function toRecord(row: RunRow): RunRecord {
   if (row.sessionFile !== null) record.sessionFile = row.sessionFile;
   if (row.prUrl !== null) record.prUrl = row.prUrl;
   if (row.headSha !== null) record.headSha = row.headSha;
+  if (row.salvageSha !== null) record.salvageSha = row.salvageSha;
+  if (row.salvageError !== null) record.salvageError = row.salvageError;
+  if (row.salvageAckAt !== null) record.salvageAckAt = row.salvageAckAt;
   if (row.endedAt !== null) record.endedAt = row.endedAt;
   if (row.lastError !== null) record.lastError = row.lastError;
+  if (row.settlementFlags !== null) {
+    const flags = toSettlementFlags(row.settlementFlags);
+    if (flags !== undefined) record.settlementFlags = flags;
+  }
+  return record;
+}
+
+/**
+ * NULL columns become absent properties, matching {@link toRecord}: a report
+ * read back out of the store deep-equals the one that went in.
+ */
+function toReport(row: ReportRow): ReportRecord {
+  const record: ReportRecord = {
+    id: row.id,
+    project: row.project,
+    kind: row.kind as ReportKind,
+    body: row.body,
+    state: row.state as ReportDeliveryState,
+    attempts: row.attempts,
+    ambiguous: row.ambiguous !== 0,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+    nextAttemptAt: row.nextAttemptAt,
+  };
+  if (row.attemptId !== null) record.attemptId = row.attemptId;
+  if (row.dedupeKey !== null) record.dedupeKey = row.dedupeKey;
+  if (row.messageId !== null) record.messageId = row.messageId;
+  if (row.deliveredAt !== null) record.deliveredAt = row.deliveredAt;
+  if (row.lastError !== null) record.lastError = row.lastError;
   return record;
 }
 
+/**
+ * Long enough that a collision is not a thing anyone has to handle, short
+ * enough that an operator can compare it against the id printed in a Telegram
+ * message by eye — which is the only reconciliation this transport allows.
+ */
+function newReportId(): string {
+  return crypto.randomUUID().replaceAll("-", "").slice(0, 12);
+}
+
+/**
+ * A ledger row, with the same NULL-becomes-absent posture as {@link toReport}.
+ *
+ * `args` is stored as JSON and read back defensively: a row whose payload no
+ * longer parses is still a row that says which verb was called and how it was
+ * decided, and losing the whole entry to a malformed blob would erase exactly
+ * the call somebody is trying to audit.
+ */
+function toVerbLedgerEntry(row: VerbLedgerRow): VerbLedgerEntry {
+  let args: Record<string, unknown> = {};
+  try {
+    const parsed: unknown = JSON.parse(row.args);
+    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+      args = parsed as Record<string, unknown>;
+    }
+  } catch {
+    args = { "(unreadable)": row.args };
+  }
+  const entry: VerbLedgerEntry = {
+    id: row.id,
+    project: row.project,
+    verb: row.verb as VerbName,
+    role: row.role as SessionRole,
+    args,
+    decision: row.decision as VerbDecision,
+    detail: row.detail,
+    at: row.at,
+  };
+  if (row.runId !== null) entry.runId = row.runId;
+  if (row.issue !== null) entry.issue = row.issue;
+  if (row.refusal !== null) entry.refusal = row.refusal as VerbRefusal;
+  if (row.sha !== null) entry.sha = row.sha;
+  return entry;
+}
+
 function toDispatchSummary(text: string): DispatchSummary | undefined {
   try {
     const value = JSON.parse(text) as DispatchSummary;
@@ -324,12 +566,34 @@ export function openStore(dbPath: string): Store {
   if (!columns.some((column) => column.name === "headSha")) {
     db.exec("ALTER TABLE runs ADD COLUMN headSha TEXT");
   }
+  // v0.3.22 and earlier removed a blocked run's dirty tree without saving it
+  // (#118), so no row before this release has anywhere to record where the
+  // work went. A NULL `salvageSha` on a historical row therefore means "never
+  // asked", which reads the same as "clean tree" — the honest reading for a
+  // release that never salvaged one.
+  for (const [name, type] of [
+    ["salvageSha", "TEXT"],
+    ["salvageError", "TEXT"],
+    ["salvageAckAt", "INTEGER"],
+  ] as const) {
+    if (!columns.some((column) => column.name === name)) {
+      db.exec(`ALTER TABLE runs ADD COLUMN ${name} ${type}`);
+    }
+  }
+  // Rows written before the settlement audit existed (#128) were never audited,
+  // so a NULL here means "no audit ran" and reads the same as "found nothing".
+  // That conflation is deliberate and harmless: the flags are advisory, and no
+  // decision anywhere is taken on their absence.
+  if (!columns.some((column) => column.name === "settlementFlags")) {
+    db.exec("ALTER TABLE runs ADD COLUMN settlementFlags TEXT");
+  }
 
   const insertRun = db.query<unknown, SqlValue[]>(
     `INSERT INTO runs (
        id, project, issue, repo, branch, worktree, state, attempt, turns,
-       maxTurns, spendUsd, sessionFile, prUrl, headSha, startedAt, endedAt, lastError
-     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+       maxTurns, spendUsd, sessionFile, prUrl, headSha, salvageSha, salvageError,
+       salvageAckAt, startedAt, endedAt, lastError, settlementFlags
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
   );
   const selectRun = db.query<RunRow, [string]>(`SELECT * FROM runs WHERE id = ?`);
   const selectActive = db.query<RunRow, SqlValue[]>(
@@ -370,6 +634,21 @@ export function openStore(dbPath: string): Store {
     `SELECT COUNT(*) AS n FROM runs
       WHERE project = ? AND issue = ? AND state IN ('killed', 'orphaned', 'blocked')`,
   );
+  // Salvage state that still describes an issue's present, so an operator is
+  // shown a preserved WIP tip exactly while it is the thing a re-claim would
+  // build on — and an unsalvaged tree for as long as it is the only copy.
+  // Newest-attempt-only for the same reason the board is: a later attempt has
+  // already consumed or superseded whatever an older one left behind.
+  const selectSalvaged = db.query<RunRow, [string]>(
+    `SELECT * FROM runs
+      WHERE rowid IN (
+        SELECT MAX(rowid) FROM runs
+        WHERE project = ?
+        GROUP BY issue
+      )
+        AND (salvageSha IS NOT NULL OR salvageError IS NOT NULL)
+      ORDER BY issue ASC`,
+  );
   // Newest attempt for one issue. `startedAt` is millisecond-resolution and two
   // attempts could in principle share one, so rowid breaks the tie by insertion
   // order — a `tail` that attached to the older of two same-millisecond attempts
@@ -432,6 +711,106 @@ export function openStore(dbPath: string): Store {
      ON CONFLICT(project, kind) DO UPDATE SET at = excluded.at`,
   );
 
+  // The report outbox (#123). Every terminal transition names the attempt it is
+  // settling, because a request can come back *after* the stale-`sending` sweep
+  // has already reclaimed its row — and a late answer must not overwrite a
+  // newer attempt's outcome. That predicate is also what stops one report being
+  // concurrently in flight twice: only one claim can move a `pending` row.
+  const insertReport = db.query<unknown, SqlValue[]>(
+    `INSERT OR IGNORE INTO reports (
+       id, project, kind, body, state, attempts, attemptId, ambiguous, dedupeKey,
+       createdAt, updatedAt, nextAttemptAt, messageId, deliveredAt, lastError
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  );
+  const selectReport = db.query<ReportRow, [string]>(`SELECT * FROM reports WHERE id = ?`);
+  const selectReportByDedupe = db.query<ReportRow, [string, string]>(
+    `SELECT * FROM reports WHERE project = ? AND dedupeKey = ?`,
+  );
+  const selectDueReports = db.query<ReportRow, [string, number, number]>(
+    `SELECT * FROM reports
+      WHERE project = ? AND state = 'pending' AND nextAttemptAt <= ?
+      ORDER BY createdAt ASC, rowid ASC
+      LIMIT ?`,
+  );
+  const claimReportRow = db.query<unknown, [string, number, string, number]>(
+    `UPDATE reports
+        SET state = 'sending', attemptId = ?, attempts = attempts + 1, updatedAt = ?
+      WHERE id = ? AND state = 'pending' AND nextAttemptAt <= ?`,
+  );
+  const deliverReportRow = db.query<unknown, SqlValue[]>(
+    `UPDATE reports
+        SET state = 'delivered', attemptId = NULL, messageId = ?, deliveredAt = ?,
+            updatedAt = ?, lastError = NULL
+      WHERE id = ? AND state = 'sending' AND attemptId = ?`,
+  );
+  const requeueReportRow = db.query<unknown, [number, string, number, string, string]>(
+    `UPDATE reports
+        SET state = 'pending', attemptId = NULL, nextAttemptAt = ?, lastError = ?, updatedAt = ?
+      WHERE id = ? AND state = 'sending' AND attemptId = ?`,
+  );
+  // Stays `sending` and keeps its attempt id: the request is over but its
+  // outcome is not known, which is precisely what `sending` means. `updatedAt`
+  // is left alone so the stale window keeps running from when the request left.
+  const uncertainReportRow = db.query<unknown, [string, string, string]>(
+    `UPDATE reports
+        SET ambiguous = 1, lastError = ?
+      WHERE id = ? AND state = 'sending' AND attemptId = ?`,
+  );
+  const failReportRow = db.query<unknown, [string, number, string, string]>(
+    `UPDATE reports
+        SET state = 'failed', attemptId = NULL, lastError = ?, updatedAt = ?
+      WHERE id = ? AND state = 'sending' AND attemptId = ?`,
+  );
+  const selectStaleSending = db.query<ReportRow, [string, number]>(
+    `SELECT * FROM reports
+      WHERE project = ? AND state = 'sending' AND updatedAt <= ?
+      ORDER BY createdAt ASC, rowid ASC`,
+  );
+  const recoverSendingRows = db.query<unknown, [number, number, string, number]>(
+    `UPDATE reports
+        SET state = 'pending', attemptId = NULL, ambiguous = 1, nextAttemptAt = ?, updatedAt = ?
+      WHERE project = ? AND state = 'sending' AND updatedAt <= ?`,
+  );
+  const selectOpenReports = db.query<ReportRow, [string]>(
+    `SELECT * FROM reports
+      WHERE project = ? AND state IN ('pending', 'sending', 'failed')
+      ORDER BY createdAt ASC, rowid ASC`,
+  );
+
+  const insertVerbLedger = db.query<unknown, SqlValue[]>(
+    `INSERT INTO verb_ledger
+       (id, project, runId, issue, verb, role, args, decision, refusal, detail, sha, at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  );
+  const selectVerbLedger = db.query<VerbLedgerRow, [string, string, string, number, number, number]>(
+    `SELECT * FROM verb_ledger
+      WHERE project = ?
+        AND (? = '' OR runId = ?)
+        AND (? = 0 OR issue = ?)
+      ORDER BY at DESC, rowid DESC
+      LIMIT ?`,
+  );
+  // Breaking a stale claim and taking it must be one transaction, or two
+  // daemons both see the stale row, both delete it, and both insert.
+  const breakStaleMergeLock = db.query<unknown, [string, number]>(
+    `DELETE FROM merge_locks WHERE project = ? AND at <= ?`,
+  );
+  const claimMergeLock = db.query<unknown, [string, string, string, number]>(
+    `INSERT OR IGNORE INTO merge_locks (project, holder, prUrl, at) VALUES (?, ?, ?, ?)`,
+  );
+  const dropMergeLock = db.query<unknown, [string, string]>(
+    `DELETE FROM merge_locks WHERE project = ? AND holder = ?`,
+  );
+  const selectMergeLock = db.query<MergeLockRow, [string]>(
+    `SELECT * FROM merge_locks WHERE project = ?`,
+  );
+  const takeMergeLock = db.transaction(
+    (project: string, holder: string, prUrl: string, now: number, staleAt: number): boolean => {
+      breakStaleMergeLock.run(project, staleAt);
+      return claimMergeLock.run(project, holder, prUrl, now).changes > 0;
+    },
+  );
+
   const recordFriction = (project: string, observation: FrictionObservation): void => {
     if (
       !Number.isSafeInteger(observation.occurrences) ||
@@ -487,9 +866,13 @@ export function openStore(dbPath: string): Store {
         toSql(record.sessionFile),
         toSql(record.prUrl),
         toSql(record.headSha),
+        toSql(record.salvageSha),
+        toSql(record.salvageError),
+        toSql(record.salvageAckAt),
         record.startedAt,
         toSql(record.endedAt),
         toSql(record.lastError),
+        toSql(record.settlementFlags),
       );
       return record;
     },
@@ -532,6 +915,10 @@ export function openStore(dbPath: string): Store {
       return selectRecentRuns.all(project, mergedSinceEpochMs).map(toRecord);
     },
 
+    salvagedRuns(project: string): RunRecord[] {
+      return selectSalvaged.all(project).map(toRecord);
+    },
+
     attemptsFor(project: string, issue: number): number {
       return countAttempts.get(project, issue)?.n ?? 0;
     },
@@ -653,6 +1040,171 @@ export function openStore(dbPath: string): Store {
       for (const kind of new Set(kinds)) upsertFrictionSurface.run(project, kind, at);
     },
 
+    enqueueReport(draft: ReportDraft): ReportEnqueue {
+      const report: ReportRecord = {
+        id: newReportId(),
+        project: draft.project,
+        kind: draft.kind,
+        body: draft.body,
+        state: "pending",
+        attempts: 0,
+        ambiguous: false,
+        ...(draft.dedupeKey === undefined ? {} : { dedupeKey: draft.dedupeKey }),
+        createdAt: draft.at,
+        updatedAt: draft.at,
+        // Due immediately. A backoff nobody has earned yet would delay the
+        // first attempt at a report an operator is already waiting for.
+        nextAttemptAt: draft.at,
+      };
+      const inserted = insertReport.run(
+        report.id,
+        report.project,
+        report.kind,
+        report.body,
+        report.state,
+        report.attempts,
+        null,
+        0,
+        toSql(draft.dedupeKey),
+        report.createdAt,
+        report.updatedAt,
+        report.nextAttemptAt,
+        null,
+        null,
+        null,
+      );
+      if (inserted.changes > 0) return { report, deduped: false };
+      // `INSERT OR IGNORE` swallowed a conflict, and the only conflict this
+      // table has is the digest guard — a 48-bit id collision is not a thing
+      // anyone needs to handle. Return the row that won rather than the one
+      // that lost, so whoever handed the digest over is told the truth about
+      // which report their operator will actually receive.
+      const existing =
+        draft.dedupeKey === undefined ? null : selectReportByDedupe.get(draft.project, draft.dedupeKey);
+      if (existing === null) {
+        throw new Error(`report ${report.id} could not be enqueued for ${draft.project}`);
+      }
+      return { report: toReport(existing), deduped: true };
+    },
+
+    getReport(id: string): ReportRecord | undefined {
+      const row = selectReport.get(id);
+      return row === null ? undefined : toReport(row);
+    },
+
+    dueReports(project: string, now: number, limit: number): ReportRecord[] {
+      return selectDueReports.all(project, now, limit).map(toReport);
+    },
+
+    claimReport(id: string, attemptId: string, at: number): ReportRecord | undefined {
+      // The row is written `sending` *before* the caller's request leaves, so a
+      // crash in the window leaves an explicitly ambiguous row rather than a
+      // silently lost one. Losing the race is normal, not an error: it means
+      // another pass already owns this attempt.
+      if (claimReportRow.run(attemptId, at, id, at).changes === 0) return undefined;
+      const row = selectReport.get(id);
+      return row === null ? undefined : toReport(row);
+    },
+
+    markReportDelivered(
+      id: string,
+      attemptId: string,
+      messageId: number | undefined,
+      at: number,
+    ): boolean {
+      return (
+        deliverReportRow.run(toSql(messageId), at, at, id, attemptId).changes > 0
+      );
+    },
+
+    markReportUncertain(id: string, attemptId: string, error: string): boolean {
+      return uncertainReportRow.run(error, id, attemptId).changes > 0;
+    },
+
+    markReportPending(
+      id: string,
+      attemptId: string,
+      nextAttemptAt: number,
+      error: string,
+      at: number,
+    ): boolean {
+      return requeueReportRow.run(nextAttemptAt, error, at, id, attemptId).changes > 0;
+    },
+
+    markReportFailed(id: string, attemptId: string, error: string, at: number): boolean {
+      return failReportRow.run(error, at, id, attemptId).changes > 0;
+    },
+
+    recoverSendingReports(project: string, staleAt: number, at: number): ReportRecord[] {
+      const stale = selectStaleSending.all(project, staleAt);
+      if (stale.length === 0) return [];
+      recoverSendingRows.run(at, at, project, staleAt);
+      // Re-read rather than patching the pre-update rows: the caller logs and
+      // renders these, and a row that says `sending` while the ledger says
+      // `pending` is exactly the kind of quiet disagreement #123 is about.
+      return stale
+        .map((row) => selectReport.get(row.id))
+        .filter((row): row is ReportRow => row !== null)
+        .map(toReport);
+    },
+
+    openReports(project: string): ReportRecord[] {
+      return selectOpenReports.all(project).map(toReport);
+    },
+
+    appendVerbLedger(draft: VerbLedgerDraft): VerbLedgerEntry {
+      const entry: VerbLedgerEntry = { ...draft, id: crypto.randomUUID(), at: Date.now() };
+      insertVerbLedger.run(
+        entry.id,
+        entry.project,
+        toSql(entry.runId),
+        toSql(entry.issue),
+        entry.verb,
+        entry.role,
+        JSON.stringify(entry.args),
+        entry.decision,
+        toSql(entry.refusal),
+        entry.detail,
+        toSql(entry.sha),
+        entry.at,
+      );
+      return entry;
+    },
+
+    verbLedger(
+      project: string,
+      opts: { runId?: string; issue?: number; limit?: number } = {},
+    ): VerbLedgerEntry[] {
+      // Sentinels rather than a composed SQL string: the filters are optional,
+      // and building the WHERE clause by concatenation is how a project name
+      // ends up interpolated into a query in a package that otherwise binds
+      // every value (see `UPDATABLE_COLUMNS` for the one place that cannot).
+      const runId = opts.runId ?? "";
+      const issue = opts.issue ?? 0;
+      const limit = opts.limit ?? 50;
+      return selectVerbLedger.all(project, runId, runId, issue, issue, limit).map(toVerbLedgerEntry);
+    },
+
+    acquireMergeLock(
+      project: string,
+      holder: string,
+      prUrl: string,
+      now: number,
+      staleAfterMs: number,
+    ): MergeLock | undefined {
+      if (!takeMergeLock(project, holder, prUrl, now, now - staleAfterMs)) return undefined;
+      return { project, holder, prUrl, at: now };
+    },
+
+    releaseMergeLock(project: string, holder: string): void {
+      dropMergeLock.run(project, holder);
+    },
+
+    mergeLock(project: string): MergeLock | undefined {
+      const row = selectMergeLock.get(project);
+      return row === null ? undefined : { ...row };
+    },
+
     close(): void {
       db.close(false);
     },