@henols/vice-mcp 0.2.1 → 0.2.2

package/anno-store.ts

@@ -0,0 +1,3486 @@
+#!/usr/bin/env node
+// anno-store.ts
+//
+// The ONE module in this repo that names `node:sqlite`. Nothing else may open,
+// query or write an annotation store file; every other module reaches the
+// store through the functions below (STORE-07).
+//
+// ---------------------------------------------------------------------------
+// WHY THIS FILE EXISTS
+// ---------------------------------------------------------------------------
+// `node:sqlite` is still marked *active development* on the Node 22 line: its
+// surface can change under a patch release, and it emits an
+// `ExperimentalWarning` on first load. A dependency with that profile earns a
+// blast radius of exactly one file -- and, more to the point, a CONFINEMENT
+// THAT IS ASSERTED rather than promised. `anno-seam.test.ts` scans the shipped
+// module set and fails if any second module names the specifier, through any of
+// its four working access routes.
+//
+// Three measured facts shaped the code below, and each one is here because the
+// obvious reading of SQLite's behaviour is wrong:
+//
+//   * A ZERO-LENGTH FILE OPENS. Measured on this host: `new DatabaseSync()`
+//     over an empty file succeeds, `pragma integrity_check` reports `ok`,
+//     `sqlite_master` comes back empty and `user_version` reads 0. So SQLite
+//     cannot tell "your annotations are gone" from "there are no annotations"
+//     -- and the difference is the difference between a bug report and a
+//     shrug. The refusal is therefore the store's OWN job: the `anno_meta`
+//     row, the `schema_version` match, and `pragma integrity_check`
+//     (0.73 ms measured on a 100 KB / 5,000-row store). Stated residual, not
+//     a closed claim: a truncation small enough to leave the last page
+//     internally consistent would still open.
+//
+//   * THE DEFAULT `delete` JOURNAL MODE IS THE RIGHT ONE, and it is not set
+//     here. Measured: `delete` and `wal` survive `SIGKILL` identically.
+//     `delete` is single-file at rest and leaves only a transient
+//     `<db>-journal` after an unclean kill, which the next open rolls back and
+//     removes; `wal` is the only mode with PERSISTENT `-wal`/`-shm` sidecars.
+//     And `journal_mode` is a PERSISTENT DATABASE PROPERTY -- `pragma`
+//     statements are not transactional -- so one stray `pragma journal_mode`
+//     anywhere would be inherited by every later connection to that file, by
+//     any process. Setting nothing is the decision; a test pins the mode so
+//     the decision cannot be undone silently.
+//
+//   * `node:sqlite` DOES expose a session surface. `DatabaseSync.prototype`
+//     carries `createSession` and `applyChangeset`, `ENABLE_SESSION` is
+//     compiled in, and a changeset was replayed between two databases during
+//     research. Only the changeset INVERSION primitive is missing -- which is
+//     why revert is a whole-store snapshot restore rather than an inverted
+//     changeset. No comment in this repo may claim the session surface is
+//     absent, because that is false.
+//
+// THIS MODULE MUST BE LISTED IN `package.json`'s `files[]`, and the reason is
+// NOT the reachability reason `prg-image.ts:30-36` gives for itself. This
+// module is not yet reachable from the published entry point's import closure,
+// and `scripts/check-npm-packages.mjs` asserts only one direction -- every
+// REACHABLE module must be listed -- never the converse. The real reason to
+// list it: `STORE-07`'s assertion scans `shippedTsModules()`, which is derived
+// from `files[]`, so an unlisted module makes that assertion VACUOUS. It would
+// pass by scanning a set this file is not in. Copying the reachability sentence
+// here would plant a false claim in a brand-new seam header, which is the
+// defect `block-class.ts`'s own stale rationale demonstrates.
+//
+// ---------------------------------------------------------------------------
+// WHAT NOT TO DO -- each entry names a specific, named trap
+// ---------------------------------------------------------------------------
+//   1. NEVER load a SQLite extension: not through the two extension-loading
+//      methods on `DatabaseSync.prototype`, and not through the constructor
+//      option that permits them. Both exist, and either one turns this
+//      module's caller-supplied FILE ARGUMENT into arbitrary code loading.
+//      `anno-seam.test.ts` asserts all three names are absent from this
+//      module's code.
+//   2. NEVER write a double-quoted SQL string literal. `node:sqlite` disables
+//      the double-quoted-string misfeature by default, so
+//      `insert into t values ("a")` throws `no such column: "a"` rather than
+//      inserting the letter a. Single quotes for literals, or bound parameters.
+//   3. NEVER interpolate a value into `exec()`. `exec()` takes NO parameters,
+//      which is exactly why everything else goes through `prepare().run()`.
+//      There is one unavoidable exception -- `vacuum into '<path>'` cannot be
+//      parameterised -- and that path is validated before it arrives and
+//      single-quote-escaped by doubling at the one site that builds it.
+//   4. NEVER set `journal_mode`, and never set `synchronous`. See the second
+//      measured fact above: the mode is persistent in the FILE, so this is not
+//      a per-connection preference that a later caller could override.
+//   5. NEVER create an FTS5 virtual table. Measured: an indexed
+//      `LIKE 'prefix%'` is 2.02 ms against FTS5 `MATCH`'s 2.99 ms, with a
+//      121.8 ms index rebuild, over 20,000 rows. Adding FTS5 later is
+//      ADDITIVE; removing it is a schema migration. The search surface belongs
+//      to `STORE-06` and this module must simply not foreclose it.
+//   6. NEVER add an explicit save or flush verb. Durability is this module's
+//      responsibility, not the caller's: every accepted write commits before it
+//      returns. A save verb is a way for a caller to lose data by forgetting.
+//   7. NEVER import either host/container path-translation seam. The store file
+//      is container-side; a host-translated path would let a store write land
+//      on the HOST filesystem, silently, outside the workspace. That is
+//      precisely the failure the closed consumer set in
+//      `hostpath-consumers.test.ts` exists to prevent, and this module's
+//      absence from it is asserted there rather than merely stated here.
+//   8. NEVER cache a derived index, census or xref on disk. A cached
+//      derivation is a second truth that can disagree with the rows; see
+//      `anno-index.ts`'s trap 2.
+//   9. NEVER turn the contradicted-comment report into an error or a refusal,
+//      and never widen the rule to "any comment at the address". Both changes
+//      look like tightening and are the opposite. A REFUSAL would push a caller
+//      toward deleting the comment to get the retype through, converting a
+//      reported loss into a silent one -- the exact outcome the report exists to
+//      prevent (`STORE-03`). A WIDENED rule would fire on every retype of a
+//      commented range, and a report that fires every time is a report nobody
+//      reads, so the one case that matters stops being noticed (`STORE-01`).
+//  10. NEVER prune the snapshot ring INSIDE the write transaction, and never
+//      let a revert fall back to the nearest retained revision. A filesystem
+//      unlink is not part of the transaction, so pruning inside it means a
+//      rollback leaves a POINTER ROW AIMED AT A FILE THAT IS ALREADY GONE --
+//      the one failure direction the revert path cannot survive. Pruning after
+//      the commit inverts that failure deliberately: a kill in the window
+//      between the commit and the prune leaves EXTRA files, which are harmless
+//      and reconcilable by revision number. INSIDE the prune loop the SAME
+//      premise decides the SAME way: the POINTER ROW is deleted first and the
+//      file second, because a kill landing between those two adjacent
+//      statements is what chooses between the two half-states, and
+//      row-then-file is the arrangement that produces the harmless one.
+//      RECORDED RATHER THAN QUIETLY DELETED, because a rationale that became
+//      false is evidence: this paragraph previously concluded the reverse --
+//      that the file is deleted before its pointer row -- which contradicted
+//      its own premise, and the loop was written to match the inverted
+//      conclusion. And a revert that SUBSTITUTES the nearest
+//      retained revision for the one asked for changes the caller's intent with
+//      nothing recording that it happened, so a revert past the bound is
+//      refused BY NAME instead (`STORE-04`).
+import { randomUUID } from "node:crypto";
+import { closeSync, copyFileSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+
+import { buildPaintIndex, type PaintIndex } from "./anno-index.ts";
+import {
+  assertAccessKind,
+  assertCommentText,
+  assertCommentType,
+  assertDataType,
+  assertEnumName,
+  assertLabelKind,
+  assertLegalLabel,
+  assertRangeShape,
+  isSplitDataType,
+  splitEntryAddressPairs,
+  AnnoCommentGradeError,
+  AnnoLabelError,
+  AnnoRangeShapeError,
+  AnnoRevisionArgumentError,
+  AnnoSplitRemainderError,
+  AnnoStoreCorruptError,
+  AnnoStoreError,
+  AnnoStorePathError,
+  AnnoStoreStaleRevisionError,
+  AnnoTypeError,
+  MAX_SNAPSHOT_REVISIONS,
+  parseStoreAddress,
+  parseVariantKey,
+  storePathWithinWorkspace,
+  SCHEMA_VERSION,
+  type CommentRow,
+  type CommentType,
+  type ContradictedComment,
+  type DataType,
+  type LabelKind,
+  type LabelRow,
+  type EnumUsageRow,
+  type ProjectEnumRow,
+  type RangeRow,
+  type ScopeRow,
+  type SplitDataType,
+  type SplitTableReinterpretation,
+  type SplitTableSurvivor,
+  type XrefAccessKind,
+  type XrefRow,
+} from "./anno-types.ts";
+import { CONFIDENCE_GRADES, parseConfidencePrefix, AnnoConfidenceGradeError } from "./anno-confidence.ts";
+// Imported for ONE purpose: the family predicate the guarded regions below use to
+// decide "rethrow unchanged" versus "wrap". Every `Anno*Error` in `anno-types.ts`
+// already extends it, so nothing new enters the module graph -- `anno-types.ts`
+// imports the same class from the same file.
+import { ViceError } from "./vice.ts";
+
+/**
+ * What every write entry point in this module returns.
+ *
+ * `changed` is the ONLY signal that distinguishes a no-op from a real edit. The
+ * revision is NOT that signal: every accepted write advances it by exactly one,
+ * including a write that turned out to be identical to what was already stored.
+ * That is deliberate -- a repeated identical write is accepted rather than
+ * refused (an agent re-running an annotation pass must not have to diff first),
+ * and the revision has to advance for the snapshot ring to stay meaningful.
+ */
+export interface AnnoWriteResult {
+  revision: number;
+  changed: boolean;
+}
+
+/**
+ * The complete on-disk schema, created in full at first open.
+ *
+ * THE REVERSAL THIS RECORDS, kept rather than deleted because a rationale that
+ * became false is evidence. This paragraph used to read "created in full at
+ * first open so `SCHEMA_VERSION` stays 1 and no later work alters an on-disk
+ * shape". The FIRST half is still true and is why every table below exists from
+ * the very first write. The SECOND half became false: `anno_snapshot` carried a
+ * `path text not null` column holding the snapshot's ABSOLUTE location, and two
+ * destructive consequences were reproduced against committed code -- two stores
+ * in one directory sharing one ring (CR-01) and a directory rename plus one
+ * write destroying the whole revert history (CR-03). The column is DROPPED at
+ * `SCHEMA_VERSION` 2 and the location is computed from the handle by
+ * `snapshotDirFor()` at every read and every delete, so there is no persisted
+ * absolute string left for a second namespace -- a bind mount seen from the
+ * host and from a container is this repo's own everyday case -- to disagree
+ * with. `anno-types.ts`'s `SCHEMA_VERSION` doc comment carries the whole
+ * argument and the reason a version-1 store is refused rather than migrated.
+ *
+ * THE VERSION 2 DDL CHANGE TOUCHED ONLY `anno_snapshot`. Every other table's
+ * column list below, including the reserved and uninterpreted `bank` columns,
+ * was byte-identical to version 1's.
+ *
+ * THAT SENTENCE IS KEPT AND SCOPED RATHER THAN DELETED, because at
+ * `SCHEMA_VERSION` 3 it stopped being the whole truth: D-15 (2026-08-29) ADDS
+ * one table, `anno_enum_usage`, and its index. It changes no existing table's
+ * column list, so the scoped claim above still holds of every table version 2
+ * had. The version 3 table associates ONE address with ONE `anno_enum` row by
+ * enum **id** -- see `anno-types.ts`'s `SCHEMA_VERSION` doc comment for what
+ * the bump buys, why no migration arm was written, and the basis measured on
+ * the day that cost was accepted.
+ *
+ * `anno_xref` and its `access_kind` column exist from the very first write.
+ * Two requirement texts look like they conflict here and do not: `STORE-05`
+ * requires the column, while the cross-reference criterion forbids CACHING a
+ * DERIVED cross-reference on disk. Both hold at once -- the table exists, and
+ * only non-derivable references (hand-asserted, or resolved from something
+ * outside the bytes) are ever stored in it. Derivation stays on the query
+ * side. This paragraph exists so a later reader does not have to rediscover
+ * that the two criteria appeared to disagree.
+ *
+ * Every range, label, comment and xref row carries a nullable `bank` column
+ * that NOTHING in this module interprets and no code path reads except the row
+ * mapper in `listRanges()`. It is reserved, and every row written today has it
+ * null.
+ */
+export const DDL = `
+create table anno_meta (
+  id integer primary key check(id = 1),
+  schema_version integer not null,
+  revision integer not null
+);
+
+create table anno_range (
+  id integer primary key autoincrement,
+  start integer not null,
+  end_inclusive integer not null,
+  data_type text not null,
+  bank integer
+);
+
+create table anno_label (
+  id integer primary key autoincrement,
+  address integer not null,
+  name text not null unique,
+  kind text not null,
+  bank integer
+);
+
+create table anno_comment (
+  id integer primary key autoincrement,
+  address integer not null,
+  comment_type text not null,
+  text text not null,
+  bank integer,
+  unique(address, comment_type)
+);
+
+create table anno_scope (
+  id integer primary key autoincrement,
+  start integer not null,
+  end_inclusive integer not null
+);
+
+create table anno_enum (
+  id integer primary key autoincrement,
+  name text not null unique,
+  variants text not null,
+  description text
+);
+
+create table anno_enum_usage (
+  id integer primary key autoincrement,
+  address integer not null,
+  enum_id integer not null references anno_enum(id),
+  bank integer,
+  unique(address, bank)
+);
+
+create table anno_xref (
+  id integer primary key autoincrement,
+  from_address integer not null,
+  to_address integer not null,
+  access_kind text not null,
+  bank integer
+);
+
+create table anno_snapshot (
+  revision integer primary key
+);
+
+create index anno_range_end_start on anno_range(end_inclusive, start);
+create index anno_label_address on anno_label(address);
+create index anno_comment_address on anno_comment(address);
+create index anno_enum_usage_address on anno_enum_usage(address);
+create index anno_xref_to on anno_xref(to_address);
+`;
+
+/** An open store: the connection, the resolved store path, and the directory
+ * the snapshots sibling lives in. The handle is owned by its CALLER -- this
+ * module holds no connection of its own, so two concurrent callers cannot
+ * observe each other's connection state. */
+export interface AnnoStoreHandle {
+  db: DatabaseSync;
+  path: string;
+  dir: string;
+  /**
+   * THIS CONNECTION'S TRANSACTION STATE IS UNKNOWN: a housekeeping sweep run on
+   * it reported that its own `rollback` threw, so it may still hold an open
+   * transaction and the store's write lock (WR-18).
+   *
+   * THE REMEDY IS THE ONE THE COMMIT HANDLER ALREADY PRINTS, in the same words:
+   * CLOSE IT AND REOPEN rather than reusing it. Node 22's `DatabaseSync` exposes
+   * no transaction-state accessor -- the surface is `open, close, prepare, exec,
+   * function, location, aggregate, createSession, applyChangeset,
+   * enableLoadExtension, loadExtension`, measured on this host -- so this field
+   * is the only thing that can carry the fact from the call that produced it to
+   * the call that must act on it.
+   *
+   * WHY THE FACT LIVES ON THE HANDLE AND NOT ON THE WRITE'S RESULT. The write
+   * that produced it COMMITTED; reporting it as that write's failure is exactly
+   * what prohibition 28-11 P5 forbids, and would send a caller to retry an
+   * additive verb. So the accepted write returns its revision unchanged and it
+   * is the NEXT call on this connection that refuses BY NAME -- which is what
+   * turns CR-07's bare `cannot start a transaction within a transaction` into a
+   * diagnosis.
+   *
+   * `false` on every freshly opened handle, set in `openStore` at the one place
+   * the handle object is built.
+   */
+  transactionStateUnknown: boolean;
+}
+
+/** The ONE `commit` statement in this module. Both the first-open schema
+ * creation and the write sequence route through here, so the single site a
+ * durability proof plants its violation against is unique and unambiguous. */
+function commitTransaction(db: DatabaseSync): void {
+  db.exec("commit");
+}
+
+/** The one place a filesystem path is spliced into SQL text, because
+ * `vacuum into` cannot be parameterised and `exec()` takes no parameters
+ * (trap 3). Refuses a path carrying a NUL or a newline outright rather than
+ * escaping it, then doubles single quotes. */
+function sqlQuotedPath(path: string): string {
+  if (/[\0\n\r]/.test(path)) {
+    throw new AnnoStorePathError(`store path ${JSON.stringify(path)} contains a control character -- refusing to splice it into SQL text`, {
+      path,
+    });
+  }
+  return `'${path.replace(/'/g, "''")}'`;
+}
+
+/** `fsync` a file or a directory by path. Directory fsync is what makes a
+ * `rename` durable, not just visible. */
+function fsyncPath(path: string): void {
+  const fd = openSync(path, "r");
+  try {
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Opens the store at `path`, creating and initialising it when it does not
+ * exist yet, and REFUSING it when it exists but is not a store this build can
+ * speak to.
+ *
+ * A `workspaceRoot` IS REQUIRED unless the caller explicitly asks for the
+ * unconfined path with `unconfinedModuleDerivedPath: true`, and the inversion is
+ * deliberate (WR-25). Confinement used to be opt-IN, which made the mitigation
+ * for the one unvalidated input this module's own header calls out the one a
+ * caller could forget -- and two of this store's recorded blockers were confinement
+ * escapes. The escape exists for exactly one shape: a path THIS MODULE derived
+ * itself (a snapshot image path, a staging path, or the live store path
+ * `revertTo` already resolved), where there is no caller argument left to
+ * confine. Every such site below carries a one-line comment naming the
+ * module-derived value that produced its path, and `anno-seam.test.ts` pins
+ * that no other shipped module names the option at all.
+ *
+ * When `workspaceRoot` is supplied the path is confined to it first. The
+ * fresh-versus-existing decision is made with `existsSync` BEFORE the
+ * connection is constructed, because constructing `DatabaseSync` creates the
+ * file -- after that point there is no way left to ask the question.
+ *
+ * `timeout` is set so a genuinely concurrent writer WAITS for the lock rather
+ * than failing `SQLITE_BUSY` on contact. No other connection option is passed:
+ * see traps 1 and 4.
+ *
+ * `mustExist` EXISTS FOR EXACTLY ONE PURPOSE: JUDGING A FILE THE CALLER IS
+ * ABOUT TO INSTALL, and its two halves are inseparable. This function's default
+ * behaviour is to CREATE and initialise an absent store -- which is the right
+ * default for opening a project's store and precisely the wrong one for asking
+ * "is this snapshot image a store I can speak to", because a judge that can
+ * create or modify the thing it judges is not a judge: it would manufacture the
+ * very empty store it was asked to detect and then report it healthy. So with
+ * `mustExist` set, an absent path is REFUSED BY NAME before `new DatabaseSync`
+ * is constructed, which makes the create-and-initialise branch below
+ * unreachable, and the connection is opened `readOnly`.
+ *
+ * READ-ONLY IS NOT BELT-AND-BRACES ON THE EXISTENCE TEST -- it closes the
+ * residual window the existence test leaves. Between the `existsSync` above and
+ * the constructor below the file can be unlinked; a writable open would then
+ * create it, and the judgement would be about a file this call had just made
+ * up. Measured on this host at plan time: a `readOnly` open of an absent path
+ * REFUSES with `unable to open database file` rather than creating it. Nothing
+ * downstream is duplicated for this option -- the `anno_meta` read, the
+ * `schema_version` comparison and `pragma integrity_check` are REUSED
+ * UNCHANGED, because those four checks together ARE the definition of "an
+ * annotation store this build can speak to" and a second list of them would be
+ * a second answer to the one question this option exists to answer once.
+ */
+export function openStore(
+  path: string,
+  opts: { workspaceRoot?: string; mustExist?: boolean; unconfinedModuleDerivedPath?: boolean } = {},
+): AnnoStoreHandle {
+  // CONFINEMENT IS THE DEFAULT, AND THE ESCAPE IS A WORD A GREP CAN FIND
+  // (WR-25). `anno-types.ts`'s header names the three things nothing upstream
+  // validates -- "an address of 65536, a misspelled data type, and a store path
+  // pointing outside the workspace all look identical to the transport" -- and
+  // this was the only one of the three whose mitigation a caller could simply
+  // forget. Two of this phase's blockers (CR-03, CR-04) were confinement
+  // escapes.
+  //
+  // REFUSED BEFORE THE PATH IS RESOLVED AND LONG BEFORE `new DatabaseSync`, for
+  // the same reason `mustExist` is refused where it is and recorded in its own
+  // comment: this function's default behaviour is to CREATE the file, so after
+  // the constructor there is no longer a question to ask -- the store would
+  // already exist wherever the argument pointed.
+  if (opts.workspaceRoot === undefined && opts.unconfinedModuleDerivedPath !== true) {
+    throw new AnnoStorePathError(
+      `${path}: refusing to open an annotation store without a workspace root. The MCP transport validates NOTHING -- ` +
+        `\`vice-proxy.ts\`'s raw-schema validator is \`validate: (value) => ({ value })\` -- so an unconfined store path is a store file ` +
+        `created wherever the caller's argument pointed. Pass { workspaceRoot } to confine the path, or ` +
+        `{ unconfinedModuleDerivedPath: true } if and only if THIS MODULE derived the path itself.`,
+      { path },
+    );
+  }
+
+  const resolved = opts.workspaceRoot === undefined ? resolve(path) : storePathWithinWorkspace(path, opts.workspaceRoot);
+  const fresh = !existsSync(resolved);
+
+  // REFUSED BEFORE THE CONNECTION IS CONSTRUCTED, and the position is the whole
+  // point: `new DatabaseSync` on an absent path CREATES the file, so after that
+  // line there is no way left to ask the question -- and the answer would be
+  // "yes, a healthy empty store", about a file this call invented.
+  if (opts.mustExist === true && fresh) {
+    throw new AnnoStoreError(
+      `${resolved}: cannot open an annotation store here -- the file does not exist, and this open was asked to JUDGE an existing image ` +
+        `rather than create one. An absent image is refused rather than initialised, because a judge that creates the thing it judges ` +
+        `would report the empty store it just made as healthy.`,
+      { data: { path: resolved } },
+    );
+  }
+
+  // WRAPPED, AND THE CLASS IS DELIBERATE. Two reproduced inputs -- a path that
+  // IS a directory, and a path whose parent directory does not exist -- both
+  // throw a bare `unable to open database file` here, with no path in the
+  // message and outside the `ViceError` family that every other refusal in this
+  // module belongs to. `AnnoStorePathError` rather than a new class, because
+  // both cases say the same thing `storePathWithinWorkspace` already says:
+  // this is not a place a store can live.
+  let db: DatabaseSync;
+  try {
+    db = opts.mustExist === true ? new DatabaseSync(resolved, { readOnly: true, timeout: 5_000 }) : new DatabaseSync(resolved, { timeout: 5_000 });
+  } catch (e) {
+    throw new AnnoStorePathError(`${resolved}: cannot open an annotation store here (${(e as Error).message})`, { path: resolved });
+  }
+  const handle: AnnoStoreHandle = { db, path: resolved, dir: dirname(resolved), transactionStateUnknown: false };
+
+  if (fresh) {
+    // WRAPPED FOR THE CONNECTION, NOT ONLY FOR THE MESSAGE. The most plausible
+    // failure in this block is a SECOND process that also saw
+    // the file absent, giving `table anno_meta already exists` -- and
+    // unwrapped that left BOTH the connection and the transaction open, so the
+    // caller lost the file handle and the lock with no way to reach either.
+    // The rollback is attempted inside its own swallowing `try` for the same
+    // reason the write sequence does it: there is nothing useful to do with a
+    // second error, and reporting it would replace the real one.
+    try {
+      db.exec("begin immediate");
+      db.exec(DDL);
+      db.prepare("insert into anno_meta(id, schema_version, revision) values (1, ?, 0)").run(SCHEMA_VERSION);
+      commitTransaction(db);
+    } catch (e) {
+      try {
+        db.exec("rollback");
+      } catch {
+        // deliberately ignored -- see above
+      }
+      db.close();
+      throw new AnnoStoreError(`${resolved}: failed to initialise a fresh annotation store (${(e as Error).message})`);
+    }
+    return handle;
+  }
+
+  let meta: { schema_version: number; revision: number } | undefined;
+  try {
+    meta = db.prepare("select schema_version, revision from anno_meta where id = 1").get() as
+      | { schema_version: number; revision: number }
+      | undefined;
+  } catch (e) {
+    db.close();
+    throw new AnnoStoreCorruptError(
+      `${resolved}: not an annotation store (${(e as Error).message}) -- refusing to treat a truncated, empty or foreign file as an empty store, ` +
+        `because "the annotations are gone" and "there are no annotations" must not read the same. This is the branch a ZERO-LENGTH file takes: ` +
+        `SQLite opens it, reports integrity_check ok and returns an empty sqlite_master, so the refusal has to be the store's own.`,
+      { path: resolved },
+    );
+  }
+
+  if (!meta) {
+    db.close();
+    throw new AnnoStoreCorruptError(
+      `${resolved}: annotation store has no meta row -- refusing to treat a truncated, empty or foreign file as an empty store, ` +
+        `because "the annotations are gone" and "there are no annotations" must not read the same`,
+      { path: resolved },
+    );
+  }
+
+  if (meta.schema_version !== SCHEMA_VERSION) {
+    db.close();
+    throw new AnnoStoreCorruptError(`${resolved}: schema_version ${meta.schema_version}, expected ${SCHEMA_VERSION}`, { path: resolved });
+  }
+
+  // WR-04, THE LAST KNOWN FAMILY ESCAPE IN THIS FUNCTION. The two blocks either
+  // side of this one are already wrapped, and for the same two reasons: an
+  // unwrapped failure here leaks the CONNECTION as well as escaping the
+  // `ViceError` family, so the caller loses the file handle with no way to
+  // reach it. The shape deliberately matches those two -- close, then refuse
+  // with `AnnoStoreCorruptError` naming the path -- because a store whose
+  // integrity check cannot even RUN is not a store this build can speak to,
+  // which is the same fact the non-`ok` branch below reports.
+  let check: { integrity_check: string }[];
+  try {
+    check = db.prepare("pragma integrity_check").all() as { integrity_check: string }[];
+  } catch (e) {
+    db.close();
+    throw new AnnoStoreCorruptError(`${resolved}: integrity_check could not be run at all (${(e as Error).message})`, { path: resolved });
+  }
+  if (check.length !== 1 || check[0].integrity_check !== "ok") {
+    db.close();
+    throw new AnnoStoreCorruptError(`${resolved}: integrity_check reported ${JSON.stringify(check)}`, { path: resolved });
+  }
+
+  return handle;
+}
+
+/** Closes the connection. Safe to call once per handle. */
+export function closeStore(handle: AnnoStoreHandle): void {
+  handle.db.close();
+}
+
+/** The store's current revision, read from `anno_meta`. */
+export function currentRevision(handle: AnnoStoreHandle): number {
+  const row = handle.db.prepare("select revision from anno_meta where id = 1").get() as { revision: number } | undefined;
+  if (!row) {
+    throw new AnnoStoreCorruptError(`${handle.path}: annotation store has no meta row`, { path: handle.path });
+  }
+  return row.revision;
+}
+
+/**
+ * The suffix appended to the store FILENAME to name its snapshot ring
+ * directory. Appended to the FILENAME rather than being a fixed directory name
+ * (`<dir>/snapshots`, which is what this was), and the distinction is the whole
+ * of CR-01's fix: two distinct store files in one directory have distinct
+ * basenames by definition of a filesystem, so distinct basenames give distinct
+ * rings BY CONSTRUCTION rather than by an ownership predicate layered over a
+ * shared location.
+ *
+ * THE PREDICATE ROUTE WAS ALREADY TRIED AND COULD NOT SEE THE DEFECT. Plan
+ * 28-07 added a per-revision ownership check over the shared `<dir>/snapshots`
+ * ring; it was structurally blind to CR-01 because revision numbers are not
+ * unique ACROSS stores -- two stores in one directory both write `r1.db`, and
+ * every per-revision predicate says "yes, revision 1 is mine" to both of them.
+ * A location that cannot collide has no such blind spot to test for.
+ */
+const SNAPSHOT_DIR_SUFFIX = ".snapshots";
+
+/**
+ * THE one authority on where a store's snapshot ring lives: a sibling
+ * directory of the store file, named after the store FILE plus
+ * `SNAPSHOT_DIR_SUFFIX`. For a store at `<dir>/proj.annostore` that is
+ * `<dir>/proj.annostore.snapshots`.
+ *
+ * THE RESIDUAL, STATED RATHER THAN CLAIMED CLOSED -- AND RESTATED AFTER THIS
+ * PARAGRAPH'S EARLIER VERSION WAS FALSIFIED BY DRIVING THE CODE (CR-05). What
+ * it got RIGHT and keeps: the location is a pure function of the handle, the
+ * sweep only ever reads `snapshotDirFor(handle)` so it cannot see a ring it
+ * does not name, and renaming the containing DIRECTORY is not a residual at all
+ * -- the ring moves with the directory, so nothing is lost (pinned by the CR-03
+ * rename test). What became FALSE: it claimed the old ring was never deleted at
+ * all and that `retainedRevisions()` reporting an empty list was therefore a
+ * truthful under-claim. That was true of the FILES and false of the ROWS -- so
+ * the claim is not repeated here even to disown it, because the next reader
+ * greps this file for the guarantee, not for its refutation. The verifier drove
+ * it in round 3: the next
+ * write's sweep classified every pointer row as an orphan and deleted them
+ * irreversibly, and restoring the original name recovered nothing.
+ *
+ * WHAT THE CODE ACTUALLY DOES NOW. A second spelling of the same store file --
+ * a SYMLINK ALIAS, or a store-file rename (`mv proj.annostore
+ * other.annostore`) -- names a DIFFERENT ring, so a handle opened under it
+ * publishes into a SECOND ring. The first ring's files are never deleted, and
+ * since CR-05 its pointer rows are never deleted BY THE SWEEP -- but
+ * `pruneSnapshots`' doomed loop still deletes every row below
+ * `currentRevision() - MAX_SNAPSHOT_REVISIONS`, so restoring the original name
+ * restores the floor ONLY while the wrong-spelling handle has not advanced past
+ * `MAX_SNAPSHOT_REVISIONS` further revisions. The bound is stated in the same
+ * sentence as the claim on purpose: an unqualified "the rows survive, so
+ * renaming back recovers the floor" with the qualifier in a later sentence is a
+ * paragraph a reader takes the unqualified half of, which is the 28-07 P3
+ * failure this correction exists to remove, reproduced by the correction.
+ *
+ * TWO RESIDUALS SURVIVE, BOTH ACCEPTED ON THE RECORD.
+ *   * Each spelling accretes its OWN ring, so `MAX_SNAPSHOT_REVISIONS` bounds
+ *     each ring but not the on-disk footprint across spellings.
+ *   * Prohibition 28-07 P2 remains VIOLATED in the UNDER-CLAIM direction under
+ *     a second spelling: opened that way the store reports
+ *     `retainedRevisions() == []` and `oldestRetainedRevision() ==
+ *     NO_RETAINED_REVISION` while the first ring's files sit on disk. Abandoning
+ *     the row sweep removed the DESTRUCTION that under-claim used to drive; it
+ *     did not remove the under-claim. Closing it would mean teaching
+ *     `retainedRevisions` to read a ring whose ownership this handle cannot
+ *     establish, which is prohibition 28-10 P3 / 28-11 P4 -- the guess the whole
+ *     decision exists to refuse.
+ */
+export function snapshotDirFor(handle: AnnoStoreHandle): string {
+  return join(handle.dir, basename(handle.path) + SNAPSHOT_DIR_SUFFIX);
+}
+
+/** Where the pre-mutation snapshot of `revision` lives: inside the ring
+ * `snapshotDirFor()` names -- a sibling directory named after the store FILE --
+ * holding one file per revision. The extension and the layout are decided here
+ * on purpose -- changing either later is a user-visible file rename. */
+export function snapshotPathFor(handle: AnnoStoreHandle, revision: number): string {
+  return join(snapshotDirFor(handle), `r${revision}.db`);
+}
+
+/** What `oldestRetainedRevision()` reports when the ring holds NO snapshot at
+ * all -- a freshly created store, or one restored from its very first
+ * snapshot. Named rather than left as a bare `-1` for the same reason
+ * `anno-index.ts`'s `NO_ROW` is named: a sentinel a caller has to recognise
+ * from its VALUE is a sentinel a caller gets wrong. Reporting
+ * `currentRevision()` in that state instead would be a LIE -- `revertTo`
+ * refuses the current revision too, because no snapshot records it. */
+export const NO_RETAINED_REVISION = -1;
+
+/**
+ * The anchored filename of one snapshot inside the ring directory
+ * `snapshotDirFor()` names, and the source of the revision number the
+ * reconciliation below derives from a filename alone.
+ *
+ * ANCHORED ON PURPOSE, and the anchoring is load-bearing rather than tidy:
+ * plan 28-08 introduces per-attempt STAGING files in this same directory under
+ * a different suffix, and a sweep that matched them would delete another
+ * writer's in-flight snapshot -- the exact loss this reconciliation exists to
+ * prevent, committed by the repair itself.
+ *
+ * A frozen `RegExp` literal is NOT module-level mutable state: the scan in
+ * `anno-seam.test.ts` matches `new Map|Set|WeakMap|WeakSet` and array/object
+ * initialisers, so this constant sits outside it by construction rather than
+ * by exemption.
+ */
+const SNAPSHOT_FILE_PATTERN = /^r(\d+)\.db$/;
+
+/**
+ * THE file-half witness, and the ONLY answer in this module to "can revision
+ * `r`'s snapshot image be opened as an annotation store this build can speak
+ * to". Returns `null` when it can, and the underlying refusal's MESSAGE when it
+ * cannot.
+ *
+ * IT REPLACED A PRESENCE TEST AT BOTH OF THE TWO SITES THAT CARRIED ONE -- the
+ * filter inside `retainedRevisions` and `revertTo`'s step-2 gate -- and the
+ * promotion is the whole of CR-08's supporting half. Presence was never a
+ * witness that a file is a store: this module's FIRST MEASURED FACT (header,
+ * `:22-31`) is that a ZERO-LENGTH FILE OPENS as a SQLite database and reports
+ * `integrity_check ok`. So the store advertised a revision whose image was not a
+ * database, and a caller following that published floor destroyed the live store
+ * irrecoverably. After this function there is no presence test on a snapshot
+ * path left anywhere in the module, and a test asserts that as an absence.
+ *
+ * IT RETURNS THE REASON RATHER THAN A BOOLEAN because two callers need two
+ * different things from one question: the filter needs only "did it open", and
+ * `revertTo`'s refusal QUOTES the reason so the caller can tell an absent image
+ * from a corrupt one without a second predicate to disagree with the first.
+ *
+ * `mustExist` IS WHAT MAKES THIS A JUDGEMENT RATHER THAN A CREATION.
+ * `openStore`'s default is to create and initialise an absent store, so a
+ * witness built without that option would manufacture the very empty store it
+ * was asked to detect, in the ring, and then report it healthy. See
+ * `openStore`'s doc comment for why the read-only half is inseparable from it.
+ */
+function snapshotOpenFailure(handle: AnnoStoreHandle, revision: number): string | null {
+  try {
+    // MODULE-DERIVED PATH: `snapshotPathFor(handle, revision)` -- built from the
+    // handle's own already-confined store path, so there is no caller argument
+    // left to confine. `mustExist` is unchanged: this open JUDGES, never creates.
+    closeStore(openStore(snapshotPathFor(handle, revision), { mustExist: true, unconfinedModuleDerivedPath: true }));
+    return null;
+  } catch (e) {
+    return (e as Error).message;
+  }
+}
+
+/**
+ * The pointer-ROW question, and NOT a second answer to "what is retained":
+ * which revisions does `anno_snapshot` CLAIM, in ascending order, regardless of
+ * whether their images can be opened.
+ *
+ * NAMED DIFFERENTLY BECAUSE IT IS A DIFFERENT QUESTION, and the naming is the
+ * guard against it being mistaken for a fourth independent decision about
+ * "retained". Its one consumer is `reconcileSnapshotRing`'s keep-set: a sweep
+ * over FILES asks "is this file claimed by a row", which is not the same
+ * question as "can a caller revert to this revision". The two answers were
+ * identical for every input reachable before the promotion above -- the presence
+ * half of the old definition is trivially true of a file `readdirSync` just
+ * returned -- and they begin to diverge only now, in the safe direction: an
+ * image that fails to open but that a row still claims stays on disk as
+ * EVIDENCE instead of being unlinked by a sweep that would otherwise perform a
+ * second destruction while calling itself a repair.
+ */
+function claimedRevisions(handle: AnnoStoreHandle): number[] {
+  const rows = handle.db.prepare("select revision from anno_snapshot order by revision").all() as { revision: number }[];
+  return rows.map((row) => row.revision);
+}
+
+/**
+ * THE definition of "revision `r` is retained", and the only one. Returns the
+ * retained revisions in ascending order.
+ *
+ * A revision is retained when its pointer row in `anno_snapshot` exists AND its
+ * image in the ring `snapshotDirFor()` names OPENS as an annotation store this
+ * build can speak to. The pointer row is the INDEX -- it is what a revision
+ * number is looked up in -- and the image is proved by `snapshotOpenFailure`,
+ * which opens it.
+ *
+ * THE FILE HALF WAS PROMOTED FROM PRESENCE TO OPENABILITY, and the reversal is
+ * recorded here because a rationale that became false is evidence. The
+ * previous witness was `existsSync` alone. It advertised a revision whose image
+ * was NOT a database -- a snapshot truncated to zero bytes by a crash between
+ * `vacuum into` and its fsync, a partial copy, bit rot, a file another tool
+ * wrote -- and `revertTo` gated on the same presence test, so following the
+ * store's OWN published floor took a 69,632-byte live store to 0 bytes with no
+ * handle returned and every later `openStore` refusing. The bytes destroyed
+ * were the only copy: the CURRENT revision has no snapshot, by design. Presence
+ * could never have been the witness, and the module knew why before it was
+ * written -- a ZERO-LENGTH FILE OPENS and reports `integrity_check ok`, so
+ * "the annotations are gone" and "there are no annotations" read the same and
+ * the refusal has to be the store's own. That reasoning was applied to
+ * `openStore` and not to the image `revertTo` installs.
+ *
+ * THE COST, IN THE SAME PARAGRAPH AS THE CLAIM. This function now OPENS up to
+ * `MAX_SNAPSHOT_REVISIONS` (32) SQLite databases per call, each running an
+ * `anno_meta` read, a `schema_version` comparison and `pragma integrity_check`
+ * (0.73 ms measured on a 100 KB store). That is affordable because every one of
+ * its call sites is QUERY-TIME, and it is affordable only because of that:
+ * `oldestRetainedRevision()` (which has no shipped caller at all today) and
+ * `revertTo()`'s step-2 gate and refusal list. NOTHING ON THE WRITE PATH READS
+ * IT -- `reconcileSnapshotRing`'s keep-set moved to `claimedRevisions` in the
+ * same change, which is what keeps the 32 opens out of every accepted write and
+ * out of the sweep's own write lock. If a caller ever needs "retained" on a
+ * per-write hot path, the answer has to be cached or narrowed and THAT becomes
+ * the single decision -- not a fourth one alongside this.
+ *
+ * THE WITNESS IS COMPUTED FROM THE HANDLE, not read from the row. Version 1
+ * persisted the snapshot's absolute path in `anno_snapshot.path` and tested THAT
+ * for existence, which is a SECOND TRUTH about one file -- and two truths about
+ * one file are two things that can disagree. They did, twice, both reproduced:
+ * a directory rename invalidated every persisted path at once, after which this
+ * function reported NO retained revisions while the files sat there on disk, and
+ * the next write's prune destroyed them (CR-03). The same shape covers every
+ * adjacent case rather than just that one repro -- a bind mount seen from two
+ * namespaces (this repo's entire architecture is built around that boundary), a
+ * symlinked ancestor, a container/host path pair, a case-insensitive filesystem,
+ * a `realpath` that changes between two opens. Dropping the column removes the
+ * PRIMITIVE: there is no persisted absolute string left, so there is nothing for
+ * a second namespace to disagree with.
+ *
+ * Neither half is sufficient on its own, and the reason is
+ * measured rather than theoretical: the snapshot image is a `vacuum into` of
+ * the WHOLE store, so it carries the `anno_snapshot` table with it, and
+ * restoring it reinstates pointer rows for revisions whose FILES an earlier
+ * prune already deleted. A row without a usable image is not a revision anyone
+ * can revert to, and reporting it as one steers the caller straight into a raw
+ * `ENOENT` out of `copyFileSync` -- or, once the image is present but not a
+ * database, into the destruction of the live store.
+ *
+ * ITS CONSUMERS ARE NAMED HERE so a reader can see the set is closed, and the
+ * set is SMALLER than it was: `oldestRetainedRevision()` (the published floor)
+ * and `revertTo()` (the step-2 gate, and the "available revisions" list inside
+ * its refusal). `reconcileSnapshotRing` IS NO LONGER ONE OF THEM -- it reads
+ * `claimedRevisions` instead, because a sweep over FILES asks a different
+ * question, and because reading this function from inside that sweep's own
+ * `begin immediate` would have opened up to 32 databases with the store's write
+ * lock held. Every remaining consumer reads this function rather than deciding
+ * for itself what "retained" means: three independent decisions is precisely how
+ * the three answers came to disagree, CR-08 was the gap between two of them, and
+ * a fourth would also hide the row-only regression from the proofs that exist to
+ * catch it.
+ */
+export function retainedRevisions(handle: AnnoStoreHandle): number[] {
+  return claimedRevisions(handle).filter((revision) => snapshotOpenFailure(handle, revision) === null);
+}
+
+/**
+ * The smallest revision the snapshot ring still holds, or
+ * `NO_RETAINED_REVISION` when it holds none. This is the FLOOR of what
+ * `revertTo` can still honour.
+ *
+ * Read from the pointer ROWS rather than computed as
+ * `currentRevision() - MAX_SNAPSHOT_REVISIONS`. The two agree on a store that
+ * has only ever been written forward, and they DISAGREE after a revert -- the
+ * arithmetic would then name a revision no row records, and a floor naming an
+ * unrevertable revision is worse than no floor at all.
+ *
+ * AND THE ROW-ONLY READING PRODUCED EXACTLY THE FAILURE THAT PARAGRAPH WAS
+ * WRITTEN TO AVOID. Reading `min(revision)` off the pointer rows alone
+ * published `0` on a store whose `r0.db` the prune had already removed, and
+ * following that floor threw a bare `ENOENT` -- the argument above was right
+ * and its implementation was one existence check short. So the floor is now
+ * the first element of `retainedRevisions()` -- and that reading was then one
+ * step short a SECOND time, in the same direction: an existence check published
+ * `0` on a store whose `r0.db` was present but was not a database, and
+ * following THAT floor destroyed the live store (CR-08). The floor now requires
+ * the image to OPEN, not merely to exist, so the store still cannot publish a
+ * number it will then refuse -- in either direction.
+ */
+export function oldestRetainedRevision(handle: AnnoStoreHandle): number {
+  const retained = retainedRevisions(handle);
+  return retained.length === 0 ? NO_RETAINED_REVISION : retained[0];
+}
+
+/**
+ * THE resolver for a snapshot-ring half-state, and the only one. Returns what
+ * it actually did, so a caller -- and a test -- can ASSERT the resolution
+ * rather than infer it from a later symptom.
+ *
+ * The ring has two truths that can disagree, and therefore two half-states:
+ *
+ *   * AN ORPHAN ROW (a pointer row whose file is gone) IS NO LONGER SWEPT AT
+ *     ALL, and the reversal is recorded here rather than left to be inferred
+ *     from an absence. This function used to delete every such row. CR-05
+ *     reproduced, twice, what that costs: the ring is named from
+ *     `basename(handle.path)` -- a PATH SPELLING -- so a SYMLINK ALIAS of the
+ *     store file, or a store-file rename (`mv proj.annostore
+ *     other.annostore`), makes `retainedRevisions()` report every EXISTING
+ *     pointer row as unretained, after which this sweep classified them as
+ *     orphan rows and deleted them under its own committed transaction. A
+ *     reachable revert history was destroyed irreversibly, and restoring the
+ *     original name recovered nothing.
+ *
+ *     THE ROW DIRECTION IS ABANDONED RATHER THAN GUARDED because this sweep
+ *     cannot establish ownership of it in ANY spelling, and a repair that
+ *     judges a state it cannot have produced is the guess prohibitions 28-10 P3
+ *     / 28-11 P4 forbid. Trap 10 calls the orphan-ROW direction "the one the
+ *     revert path cannot survive" and that was true when it was written; it is
+ *     not true of this code. `retainedRevisions()` requires the image to OPEN
+ *     as an annotation store, `oldestRetainedRevision()` routes through it, and
+ *     `revertTo` step 2 refuses on the SAME witness -- `snapshotOpenFailure` --
+ *     BEFORE anything is destroyed, in three arms rather than one: no pointer
+ *     row, an image that will not open, and (step 3b) a staged copy that will
+ *     not open. So the store never advertises an unusable revision and never
+ *     follows one.
+ *
+ *     AND THE BASIS OF "INERT" HAS CHANGED, so it is restated rather than left
+ *     to be re-derived. The old basis was that every consumer of "retained"
+ *     required the FILE, so a row nothing looked at was invisible to the whole
+ *     ring. That is no longer true: the keep-set below reads
+ *     `claimedRevisions`, so this sweep now looks at rows the advertisement
+ *     ignores. THE NEW BASIS IS BETTER RATHER THAN WEAKER, and it is the
+ *     conclusion CR-08 forced: a row the sweep KEEPS is precisely what makes a
+ *     corrupt image survive on disk as EVIDENCE instead of being unlinked. A
+ *     sweep that deleted the image of a failure would be destroying the only
+ *     record of the failure that has to be diagnosed -- a second destruction
+ *     dressed as a repair. The CR-05 conclusion is unchanged: the row direction
+ *     stays abandoned, for the ownership reason above.
+ *
+ *     THE KEEP-SET QUERY RUNS ON THE CONNECTION ALREADY IN HAND, and that is
+ *     the second, independent reason it reads `claimedRevisions` rather than
+ *     `retainedRevisions`. This function computes its keep-set INSIDE its own
+ *     `begin immediate`, with the store's WRITE LOCK held. Under the promoted
+ *     meaning of "retained", reading that function here would have opened up to
+ *     `MAX_SNAPSHOT_REVISIONS` (32) SQLite databases while holding that lock, on
+ *     every accepted write. `claimedRevisions` is one `select` on the connection
+ *     this function already has, so the promoted witness is NEVER invoked while
+ *     this sweep holds the store's write lock, and the 32-image cost stays
+ *     confined to query time.
+ *
+ *     Deleting an orphan row was hygiene, and hygiene that destroyed a
+ *     reachable revert history is a worse failure than the state it tidied.
+ *
+ *     ROWS STAY BOUNDED WITHOUT THIS SWEEP. `pruneSnapshots`' doomed loop
+ *     deletes every row below `currentRevision() - MAX_SNAPSHOT_REVISIONS`, so
+ *     an orphan row is reaped on the ordinary path once it ages out -- and
+ *     under a wrong spelling that reaping is exactly what the correct spelling
+ *     would also have done at the same revision, so the behaviour converges to
+ *     correct instead of diverging into loss. The residual is extra ROWS, which
+ *     is the direction this module's own trap-10 premise calls harmless.
+ *   * AN ORPHAN FILE (a snapshot file no surviving pointer row claims) is the
+ *     harmless direction, and it is harmless only until it is FORGOTTEN: the
+ *     bound is computed over rows, so an unclaimed file is invisible to it
+ *     forever. A single revert orphans up to `MAX_SNAPSHOT_REVISIONS` of them
+ *     at once, which is how the directory bound stopped holding after a
+ *     revert. Every such file is unlinked and its path reported in
+ *     `droppedFiles`.
+ *
+ * Each unlink is `force: true` inside a SWALLOWING `try`, and only a unlink
+ * that actually happened is reported: an undeletable file must not make the
+ * store unwritable, and leaving it unreported means the NEXT reconciliation
+ * sees it again rather than the store believing it is gone.
+ *
+ * ITS CALL SITES ARE EXACTLY TWO, AND `openStore` IS DELIBERATELY NOT ONE OF
+ * THEM. It runs at the end of `revertTo` on the NEW handle before that handle
+ * is returned (a restore is the one operation that manufactures orphan rows),
+ * and as the FIRST statement of `pruneSnapshots` (so the bound is computed
+ * over a ring with no half-states). It must NOT run from `openStore`:
+ * `anno-durability.test.ts:291-347` asserts that an orphan snapshot file left
+ * in the kill window SURVIVES a reopen and is identified by its revision, and
+ * that is a verified truth of plan 28-06 -- merely LOOKING at a store must not
+ * change it, and the orphan a kill window leaves is deliberately the harmless
+ * direction. Reconciling on open would redden that test, and rightly. BOTH
+ * SITES ARE OUTSIDE ANY OPEN TRANSACTION, which is now a REQUIREMENT rather
+ * than an incidental fact: this function opens and closes a transaction of its
+ * own, so calling it from inside one is not supported.
+ *
+ * IT NOW TAKES THE STORE'S WRITE LOCK BEFORE IT DECIDES ANYTHING, and the
+ * reason is a reproduced defect (CR-02) rather than caution. A snapshot becomes
+ * a FILESYSTEM fact (the `renameSync` inside `publishSnapshot`) before it
+ * becomes a TRANSACTIONAL one (the pointer-row insert), so a sweep reading only
+ * its own committed view sees a live writer's published file as unowned and
+ * unlinks it -- after which the winning writer's own pointer row advertises a
+ * revision whose file is gone. That is the orphan-ROW state trap 10 calls
+ * unsurvivable, manufactured by the reconciliation written to prevent it, and
+ * the destroyed revision is permanently unrevertible.
+ *
+ * THE LOCK IS THE EXACT INSTRUMENT, NOT A TIMING HEURISTIC, and the exactness
+ * is derived rather than measured: publication is reachable only from behind a
+ * WON compare-and-swap, and the compare-and-swap runs inside `begin immediate`,
+ * so a writer that is published-but-uncommitted HOLDS this same write lock. The
+ * publish-to-commit window and the write-lock hold are the same interval. A
+ * grace bound over file mtimes was the offered alternative and is refused on the
+ * record: it is a guess about how long a writer may sit between its rename and
+ * its transaction's end, it is wrong for a writer that is paged out or stopped
+ * at a debugger, and the next reproduction of this defect would arrive as a
+ * request to raise the constant.
+ *
+ * `deferred` IS WHAT DECLINING LOOKS LIKE, AND DECLINING IS CORRECT RATHER THAN
+ * BEST-EFFORT. When the lock cannot be taken within the connection's five-second
+ * `busy_timeout`, this function changes NOTHING and returns
+ * `{ droppedFiles: [], deferred: true, rollbackFailed: false }`. A sweep that pressed
+ * on would be judging a state it cannot establish -- exactly the guess the lock
+ * exists to remove -- so it abstains and REPORTS the abstention, which is what
+ * lets a caller and a test assert it rather than infer it from an absence. The
+ * cost is that the ring may temporarily exceed `MAX_SNAPSHOT_REVISIONS` files
+ * until the next accepted write sweeps successfully: extra FILES, the direction
+ * trap 10's own premise calls harmless and reconcilable by revision number.
+ *
+ * `deferred` IS NOW WIDENED, AND THE WIDENING IS STATED RATHER THAN LEFT TO BE
+ * INFERRED FROM THE ONE NEW RETURN SITE. It reports "THIS SWEEP CHANGED
+ * NOTHING -- which holds as stated while `rollbackFailed` is `false`, and which
+ * becomes 'this sweep INTENDED to change nothing but cannot establish that its
+ * own transaction closed' when `rollbackFailed` is `true`", and it covers two
+ * causes: another writer holds the write lock (step
+ * 1 above), and this sweep failed part-way and rolled back (the structural
+ * handler around steps 2-4). The qualifier is in the SAME sentence as the claim
+ * on purpose: an unqualified guarantee with its qualifier further down is the
+ * 28-07 P3 shape this module has already had to correct once, and a reader who
+ * stops at the first sentence must not stop at a claim that is sometimes false.
+ *
+ * `rollbackFailed` IS ALWAYS PRESENT AND IS NEVER OPTIONAL, for the reason the
+ * neighbouring `droppedRows` assertion in `anno-store.test.ts` already records:
+ * a field that can only ever answer one value is a claim the next reader has to
+ * falsify by experiment. It is `false` at every ordinary return site including
+ * the lock-contention deferral, and `true` only where this function's own
+ * `rollback` threw -- which is the one state in which the sentence above cannot
+ * be honoured, and the one this function has no other way to report, because
+ * rethrowing is forbidden here (28-11 P5).
+ *
+ * NO SECOND DISCRIMINATOR WAS ADDED FOR `deferred`'s TWO CAUSES, and the reason
+ * is not economy. Its only consumer, `pruneSnapshots`, returns early
+ * identically in both cases, so a discriminator would have no reader -- and
+ * CR-07's actual complaint, that a LEAKED transaction makes every later sweep
+ * report `deferred` indistinguishably from contention, is removed AT ITS SOURCE
+ * by the handler rather than papered over with a label. A field describing a
+ * state this code can no longer reach would be exactly the kind of comment
+ * prohibition 28-07 P3 forbids, in the shape of an enum.
+ *
+ * THE NEW CALLER-VISIBLE LATENCY, STATED HERE BECAUSE A READER OF THE OLD
+ * COMMENT WOULD NOT EXPECT IT. Before this change the sweep took no write lock
+ * and could not block at all. After it, under contention, a caller blocks HERE
+ * for up to the connection's five-second `busy_timeout` before it proceeds --
+ * at BOTH of the two call sites: every accepted write (through `pruneSnapshots`
+ * at `runWriteSequence` step 9) and every `revertTo` (through its own step-6
+ * sweep on the restored handle). Phase 29 puts both on an MCP tool path. Each is
+ * bounded at ONE timeout and not two, because `pruneSnapshots` returns early
+ * when this function reports `deferred` rather than running its own autocommit
+ * deletes into the same contention. An honest cost stated at the seam is worth
+ * more than a fast comment.
+ *
+ * AND THE TRANSACTION IS STILL CLOSED BEFORE ANY UNLINK, for exactly the reason
+ * `pruneSnapshots`' own loop deletes the row first. This used to be stated as
+ * "the row deletes are committed before any unlink"; there are no row deletes
+ * left (see the ORPHAN ROW bullet above), so what the ordering now guarantees is
+ * narrower and is stated narrowly: an interruption between the commit and the
+ * unlinks leaves extra FILES, never a pointer row aimed at a deleted file.
+ * Pinned by a source-order control in `anno-store.test.ts`, which since CR-05
+ * asserts the ABSENCE of any pointer-row delete in this body as well as the
+ * surviving commit-before-unlink order -- a presence assertion cannot see
+ * either.
+ */
+export function reconcileSnapshotRing(handle: AnnoStoreHandle): { droppedFiles: string[]; deferred: boolean; rollbackFailed: boolean } {
+  const droppedFiles: string[] = [];
+
+  // STEP 1. Take the store's write lock BEFORE reading anything, so no writer
+  // can be mid-publication while this function decides. Every failure is
+  // treated the same way and none is rethrown: the expected one is
+  // `SQLITE_BUSY` after the connection's five-second `busy_timeout` (another
+  // writer holds the lock), and any other failure equally means this function
+  // cannot establish the moment it is required to judge from. Declining is the
+  // whole contract -- a partial sweep is precisely what must not happen.
+  try {
+    handle.db.exec("begin immediate");
+  } catch {
+    // `rollbackFailed: false` and not omitted: nothing was begun, so there was
+    // no transaction to close and the reported abstention is exact.
+    return { droppedFiles, deferred: true, rollbackFailed: false };
+  }
+
+  // DECLARED OUTSIDE THE HANDLER BELOW so step 5 can still read it after the
+  // handler closes. The transaction's lifetime is structural; the drop set's
+  // scope is not, and conflating the two would put the unlink loop inside the
+  // transaction, which is exactly what trap 10 forbids.
+  const orphanFiles: string[] = [];
+
+  // EVERYTHING FROM HERE TO THE COMMIT IS BRACKETED, AND THE BRACKET IS THE
+  // FIX (CR-07). `begin immediate` above has already opened a transaction on
+  // the CALLER's connection. Before this handler existed, any throw between
+  // that statement and the commit -- `readdirSync` on a ring directory that
+  // became unreadable, a failure of the keep-set `select`, anything --
+  // propagated out with the transaction still
+  // OPEN. Step 9's WR-02 wrap then swallowed it, so an ordinary `setDataType`
+  // reported SUCCESS while leaving the handle permanently inside a transaction:
+  // every later write failed with "cannot start a transaction within a
+  // transaction", and every later sweep reported `deferred` indistinguishably
+  // from ordinary contention. The lifetime is now structural rather than
+  // path-dependent: there is no route out of this block that does not either
+  // commit or roll back.
+  try {
+    // STEP 2. With the lock held, compute the drop set -- which since CR-05 has
+    // exactly ONE direction, the FILE direction -- before changing anything.
+    //
+    // THE KEEP-SET IS THE POINTER-ROW SET, AND THAT IS A DIFFERENT QUESTION
+    // rather than a fourth answer to "what is retained". This resolver still
+    // does NOT re-decide anything with a predicate of its own -- it asks
+    // `claimedRevisions`, the ONE answer to "which revisions does
+    // `anno_snapshot` claim", exactly as it used to ask the ONE answer to "what
+    // is retained".
+    //
+    // WHY THE QUESTION IS GENUINELY DIFFERENT, AND WHY THE ANSWERS ONLY DIVERGE
+    // NOW. A sweep over FILES asks "is this file claimed by a pointer row";
+    // `retainedRevisions` asks "can a caller revert to this revision". Before
+    // CR-08's promotion those two were identical for every reachable input,
+    // because the presence half of the old definition is trivially true of a
+    // file `readdirSync` just returned. The promotion is what separates them,
+    // and the separation runs in the SAFE direction: an image that fails to open
+    // but that a row still claims is kept on disk as EVIDENCE. Leaving this
+    // keep-set on `retainedRevisions` would have made the CR-08 fix its own
+    // second destroyer -- the sweep would unlink exactly the corrupt image whose
+    // refusal has to be diagnosed, one ordinary write after the refusal.
+    //
+    // AND IT IS ONE `select` ON THE CONNECTION ALREADY IN HAND, INSIDE THE WRITE
+    // LOCK. `begin immediate` above is held for the whole of this block, so
+    // reading the promoted `retainedRevisions` here would open up to
+    // `MAX_SNAPSHOT_REVISIONS` (32) SQLite databases with the store's write lock
+    // held, on every accepted write. See the ORPHAN ROW bullet above.
+    const claimed = new Set(claimedRevisions(handle));
+
+    // A store that has never been written has no ring directory at all, and
+    // `readdirSync` throws on an absent one. That is not a half-state -- and the
+    // check lives HERE, inside the drop-set computation, rather than returning
+    // early: an early return from this point would leave the sweep's own
+    // transaction OPEN on the caller's connection. With no directory there are
+    // simply no orphan files, and the function falls through to close its
+    // transaction like any other run.
+    //
+    // NAMED THROUGH `snapshotDirFor` AND ONLY THROUGH IT, which is what confines
+    // this sweep to a ring this store can be the owner of. It cannot see -- and
+    // therefore cannot delete -- a legacy `<dir>/snapshots` ring, or a ring
+    // belonging to a neighbouring store file in the same directory.
+    const snapshotDir = snapshotDirFor(handle);
+    if (existsSync(snapshotDir)) {
+      for (const name of readdirSync(snapshotDir).sort()) {
+        const match = SNAPSHOT_FILE_PATTERN.exec(name);
+        if (!match) continue;
+        if (claimed.has(Number(match[1]))) continue;
+        orphanFiles.push(join(snapshotDir, name));
+      }
+    }
+
+    // STEP 3 IS GONE ON PURPOSE, and its absence is the fix for CR-05. It
+    // deleted every pointer row this handle's spelling of the ring could not
+    // vouch for; under a second spelling of the same store file that was every
+    // row it had. The whole argument is in the ORPHAN ROW bullet above.
+
+    // STEP 4. Close the sweep's own transaction through THE module's single
+    // commit site. It must be `commitTransaction` and never a second
+    // `handle.db.exec` of the bare word: `anno-seam.test.ts` asserts this module
+    // contains exactly ONE such statement, because the durability proof's planted
+    // violation must have a single site -- a second literal would split that
+    // planting and let half of it survive.
+    commitTransaction(handle.db);
+  } catch {
+    // ROLLED BACK INSIDE ITS OWN SWALLOWING `try`: there is nothing useful to
+    // do with a second error here, and reporting it would replace the first.
+    // WHAT IS NEW IS THAT THE OUTCOME IS RECORDED RATHER THAN ASSUMED (WR-16).
+    // Node 22's `DatabaseSync` exposes no transaction-state accessor, so this
+    // boolean is the only thing that can tell a caller which of the two
+    // happened -- and this function cannot tell it by throwing, because
+    // rethrowing here would convert a COMMITTED write into a caller-visible
+    // failure on `revertTo`'s step-6 call site (28-11 P5).
+    let rolledBack = true;
+    try {
+      handle.db.exec("rollback");
+    } catch {
+      // deliberately ignored -- see above; only the FACT is kept.
+      rolledBack = false;
+    }
+    // AND DELIBERATELY NOT RETHROWN. A throw from here is swallowed by step 9's
+    // WR-02 wrap anyway, so rethrowing would buy nothing on the write path --
+    // and on `revertTo`'s own step-6 call site it would convert a COMMITTED
+    // write into a caller-visible failure, which prohibition 28-11 P5 forbids.
+    // The sweep changed nothing, which is precisely what `deferred` reports --
+    // qualified by `rollbackFailed`, which is the one case in which "changed
+    // nothing" is an intention this function cannot establish.
+    return { droppedFiles: [], deferred: true, rollbackFailed: !rolledBack };
+  }
+
+  // STEP 5, AND ITS POSITION IS THE POINT: only now, with the sweep's
+  // transaction durably closed, unlink the orphan files. An interruption
+  // between step 4 and here leaves extra FILES, which trap 10's premise calls
+  // harmless and reconcilable by revision number, and never a pointer row aimed
+  // at a deleted file.
+  //
+  // Each unlink is `force: true` inside a SWALLOWING `try`, and only a unlink
+  // that actually happened is reported: an undeletable file must not make the
+  // store unwritable, and leaving it unreported means the NEXT reconciliation
+  // sees it again rather than the store believing it is gone.
+  for (const orphan of orphanFiles) {
+    try {
+      rmSync(orphan, { force: true });
+      droppedFiles.push(orphan);
+    } catch {
+      // Deliberately ignored, and deliberately NOT reported as dropped: an
+      // undeletable file must not make the store unwritable, and the next
+      // reconciliation has to see it again rather than believe it is gone.
+    }
+  }
+
+  // `rollbackFailed: false` on the ordinary path: control only reaches here
+  // through the commit above, so no rollback was attempted at all.
+  return { droppedFiles, deferred: false, rollbackFailed: false };
+}
+
+/**
+ * Bounds the store's own snapshot ring directory (`snapshotDirFor()`) at
+ * `MAX_SNAPSHOT_REVISIONS` by
+ * deleting every snapshot older than the newest `MAX_SNAPSHOT_REVISIONS`
+ * revisions -- ITS POINTER ROW FIRST, THE FILE SECOND.
+ *
+ * MUST BE CALLED AFTER THE COMMIT AND OUTSIDE THE TRANSACTION. Trap 10 in the
+ * module header carries the whole argument; the short form is that an unlink is
+ * not transactional, so the ordering around the commit CHOOSES which failure a
+ * kill in the window produces -- and the choice made here is "extra files"
+ * over "a pointer row aimed at a deleted file".
+ *
+ * THE SAME CHOICE IS MADE AGAIN INSIDE THE LOOP, between its two statements,
+ * and for the same reason. A kill landing there leaves an orphan FILE -- which
+ * trap 10's premise already calls harmless and reconcilable by revision
+ * number -- and never an orphan ROW. The ordering is pinned by a source-order
+ * control in `anno-store.test.ts`, because both statements are present in
+ * either arrangement and a presence assertion cannot see the difference.
+ *
+ * The bound itself lives in `anno-types.ts` and is imported, never copied: a
+ * second literal would drift the moment the first one is edited, silently, and
+ * a store whose pruning bound disagrees with its declared bound has a revert
+ * history shorter than it says it has.
+ *
+ * ITS FIRST STATEMENT NOW TAKES AND RELEASES A TRANSACTION, so `pruneSnapshots`
+ * itself must not be called from inside one -- and under contention that first
+ * statement can block for the connection's five-second `busy_timeout`. See
+ * `reconcileSnapshotRing` for the whole argument and for the latency this adds
+ * at both of its call sites.
+ */
+export function pruneSnapshots(handle: AnnoStoreHandle): boolean {
+  // FIRST, BEFORE THE BOUND IS COMPUTED: resolve any half-state, so the bound
+  // is computed over a ring whose rows and files agree. This is what makes the
+  // directory bound hold AFTER A REVERT as well as after a forward-only run --
+  // a restore leaves up to `MAX_SNAPSHOT_REVISIONS` files claimed by no row,
+  // and a prune that iterates rows alone can never see them.
+  //
+  // AND ITS REPORT IS CONSUMED RATHER THAN DISCARDED. When the sweep DECLINED
+  // to judge -- it could not take the write lock inside the connection's
+  // five-second `busy_timeout`, so another writer is mid-publication -- this
+  // function returns here, before the doomed-set `select`. Two reasons, and the
+  // second is the load-bearing one:
+  //
+  //   1. It bounds the added latency at ONE `busy_timeout` rather than two. The
+  //      doomed-set deletes below are autocommit WRITES, so under the same
+  //      contention they would block a second five seconds and then fail
+  //      `SQLITE_BUSY` -- which the step-9 call site's wrap swallows, making the
+  //      worst case roughly ten seconds of silent added latency for work that is
+  //      guaranteed to be redone.
+  //   2. The doomed set would be computed over a ring the sweep just declined to
+  //      reconcile. Acting on it is the same guess the sweep abstained from,
+  //      with an extra step: a prune that presses on where its own sweep
+  //      abstained publishes a bound the store cannot support.
+  //
+  // The cost is one more accepted write's worth of un-pruned ring -- extra
+  // FILES, the direction trap 10's premise calls harmless and reconcilable by
+  // revision number, and the same direction a deferred sweep already accepts.
+  //
+  // AND ITS `rollbackFailed` IS CONSUMED FOR THE SAME REASON, RETURNED RATHER
+  // THAN DISCARDED (WR-18). The argument recorded above for consuming
+  // `.deferred` is the argument for consuming this one, so it is extended here
+  // rather than restated: a fact this function throws away is a fact its caller
+  // cannot act on, and `rollbackFailed` reports the ONE state the sweep's own
+  // handler cannot fix -- its `rollback` threw, so the connection may still hold
+  // an open transaction and the store's write lock. Until this return existed
+  // the field had no production reader anywhere, which is what a field whose
+  // only reader is a test asserting it is always `false` amounts to.
+  //
+  // IT IS RETURNED, NOT THROWN, and the distinction is prohibition 28-11 P5:
+  // both call sites reach this function AFTER a write or a revert has already
+  // landed, so a throw here would convert a committed write into a
+  // caller-visible failure.
+  const swept = reconcileSnapshotRing(handle);
+  if (swept.deferred) return swept.rollbackFailed;
+
+  const floor = currentRevision(handle) - MAX_SNAPSHOT_REVISIONS;
+  const doomed = handle.db.prepare("select revision from anno_snapshot where revision < ? order by revision").all(floor) as {
+    revision: number;
+  }[];
+
+  for (const row of doomed) {
+    // THE POINTER ROW GOES FIRST, AND THE ORDER IS THE GUARANTEE. The prune
+    // runs outside any transaction (correctly -- see above), so a kill BETWEEN
+    // these two statements decides which half-state survives. Row-then-file
+    // leaves an orphan FILE, which trap 10's own premise calls harmless and
+    // reconcilable by revision number. File-then-row -- the arrangement this
+    // loop used to be written in -- leaves a POINTER ROW AIMED AT A DELETED
+    // FILE, which is the one failure direction the revert path cannot survive.
+    // Deliberately NOT swallowed: the row delete is the half that must be loud.
+    handle.db.prepare("delete from anno_snapshot where revision = ?").run(row.revision);
+
+    // Swallowed on purpose, and ONLY here: an interrupted earlier prune may
+    // already have removed this file, and a prune that threw on an
+    // already-absent file would make the store unwritable after a single kill
+    // in the window. With the row already gone, a file this fails to unlink is
+    // an orphan FILE -- which the reconciliation at the top of the NEXT prune
+    // can still see and retry. Under the earlier arrangement the row was
+    // deleted unconditionally after a swallowed failure, so the file became
+    // invisible to the bound forever (WR-01's secondary point).
+    try {
+      // THE PATH IS COMPUTED HERE, at the delete, from the handle -- never read
+      // from the row. A persisted absolute path is environment-controlled input
+      // to an `rmSync`; the only path this delete can name is
+      // `join(snapshotDirFor(handle), "r<digits>.db")`.
+      rmSync(snapshotPathFor(handle, row.revision), { force: true });
+    } catch {
+      // deliberately ignored -- see above
+    }
+  }
+
+  // Control only reaches here through a sweep that returned `deferred: false`,
+  // which is only produced after its own commit -- so no rollback was attempted
+  // at all and the answer is exact rather than a default.
+  return false;
+}
+
+/**
+ * Vacuums the store's CURRENT contents into a snapshot file staged under a name
+ * unique to THIS ATTEMPT, and returns that path. It never reads, writes,
+ * removes or renames the published `r<revision>.db` -- publication is
+ * `publishSnapshot`'s job and happens only after the compare-and-swap below has
+ * been won.
+ *
+ * EXPORTED FOR EXACTLY ONE REASON, and no other: the snapshot-ownership proof
+ * has to drive the IDENTICAL staging code the production writer uses. A
+ * hand-copied variant inside a test can drift out of agreement with the real
+ * one, and a proof that agrees with a copy proves nothing about the original.
+ * `anno-seam.test.ts` asserts that no shipped module other than this one so
+ * much as names it -- the same bound `applyWriteWithoutCommit` carries, by the
+ * same mechanism rather than a second one.
+ *
+ * THE STAGING SUFFIX IS DELIBERATELY OUTSIDE `SNAPSHOT_FILE_PATTERN`. That
+ * pattern is anchored on `r<digits>.db`, and `reconcileSnapshotRing`'s
+ * directory sweep matches only what it matches -- so a concurrent writer's
+ * in-flight staging file is invisible to the sweep and can never be deleted out
+ * from under it. That anchoring is the contract between this function and the
+ * reconciliation; neither side may drift from it.
+ *
+ * THE UNIQUENESS IS PER ATTEMPT, NOT PER REVISION, and the distinction is
+ * load-bearing: a revision number can recur after a revert, and two attempts at
+ * the same revision -- in this process or another -- must not share a path,
+ * because `vacuum into` refuses an existing target and because two writers
+ * filling one file is the very collision this staging exists to remove.
+ *
+ * AND THE IMAGE IS FSYNCED BEFORE THIS FUNCTION RETURNS (WR-13). The pointer row
+ * that names this file is inserted inside the write transaction and committed by
+ * SQLite, WHICH DOES FSYNC -- so without the `fsyncPath` below the ROW is
+ * durable and the FILE it names is not. Trap 10's durability premise covers a
+ * `SIGKILL`, where the page cache survives the dead process and the bytes land
+ * anyway; it does NOT cover a host crash, which loses the cache. The consequence
+ * is not an extra file: it is a PRESENT, PARTIAL snapshot that
+ * `retainedRevisions()` would advertise as revertible, which is exactly the input
+ * CR-08 was reproduced with. 28-16's step-2 and step-3b gates make that input a
+ * REFUSAL rather than a destruction; this call removes the input at its source
+ * rather than relying on the refusal, because a refusal on the only route back
+ * is still a lost history.
+ */
+export function stageSnapshot(handle: AnnoStoreHandle, revision: number): string {
+  const snapPath = snapshotPathFor(handle, revision);
+  mkdirSync(dirname(snapPath), { recursive: true });
+  const staging = join(dirname(snapPath), `r${revision}.${process.pid}.${randomUUID()}.tmp`);
+  handle.db.exec(`vacuum into ${sqlQuotedPath(staging)}`);
+  fsyncPath(staging);
+  return staging;
+}
+
+/**
+ * Publishes a staged snapshot onto its revision's user-visible path. One
+ * `renameSync`, called from exactly one place: between the WON compare-and-swap
+ * and the pointer-row insert, so the only writer that can publish is the writer
+ * that will own the row.
+ *
+ * THE REVERSAL THIS RECORDS. The code here used to be an unconditional
+ * `rmSync(snapPath, { force: true })` followed by a `vacuum into` of the
+ * published path, both BEFORE `begin immediate`, justified by a comment reading
+ * "`vacuum into` refuses an existing target, and a revision number can recur
+ * after a revert, so the stale file is removed rather than colliding". THE
+ * PREMISE IS TRUE AND IS KEPT: `vacuum into` does refuse an existing target, and
+ * a revision number does recur after a revert. THE REMEDY WAS WRONG. Removing
+ * the published path is an unowned write, performed by a writer that may be
+ * about to be refused, onto a file a COMMITTED pointer row already claims -- so
+ * a losing writer replaced a winner's bytes and left that winner's row
+ * describing a different revision, which `revertTo` then restored without a
+ * word. The recurrence is handled HERE instead: a rename overwrites without a
+ * prior removal, so the stale file is replaced by the writer that OWNS the new
+ * pointer row and by no one else.
+ *
+ * AND A RENAME HERE CANNOT DESTROY A CLAIMED SNAPSHOT, which is proved rather
+ * than hoped. Pointer rows are inserted for the PRE-mutation revision, and the
+ * vacuum image is taken before that insert -- so every row in any surviving
+ * pointer table names a revision STRICTLY BELOW the revision the store is at.
+ * The only path this rename targets is the CURRENT revision's, which no
+ * surviving row can name. `anno-store.test.ts` asserts that property over a
+ * store that has been reverted and written forward again, rather than leaving
+ * it as an argument.
+ *
+ * AND THE RING DIRECTORY IS FSYNCED AFTER THE RENAME (WR-13). A rename is
+ * VISIBLE immediately and DURABLE only after the directory is fsynced -- the
+ * distinction `fsyncPath`'s own doc sentence records. The pointer row that names
+ * this file is inserted inside the write transaction a few statements below and
+ * committed by SQLite, WHICH DOES FSYNC, so without this call the two halves of
+ * one revision's record have different durability: the ROW survives a host crash
+ * and the DIRECTORY ENTRY naming its image may not. Trap 10's premise -- that a
+ * kill in the window leaves EXTRA files, which are harmless -- is true of a
+ * `SIGKILL` and NOT of a host crash, which loses the page cache; the surviving
+ * half-state there is a durable row naming a file whose bytes never reached
+ * disk, i.e. the PRESENT, PARTIAL snapshot `retainedRevisions()` would advertise
+ * and the exact input CR-08 was reproduced with. 28-16 made that input a refusal
+ * rather than a destruction; this call removes the input at its source instead of
+ * relying on that refusal. The order is the same as `revertTo`'s steps 3 and 5
+ * and uses the same helper, deliberately -- a second durability idiom in one
+ * module is a second thing to keep true.
+ *
+ * AND THE DIRECTORY FSYNC IS BEST EFFORT WHILE THE IMAGE FSYNC IS NOT, which is
+ * a difference in WHICH half-state each one removes and not a difference in
+ * rigour. `stageSnapshot`'s `fsyncPath` is unguarded because it removes the
+ * DESTRUCTIVE outcome: a durable row naming a file whose BYTES never reached
+ * disk, i.e. a present, partial image `retainedRevisions()` advertises. A failure
+ * there refuses before `begin immediate`, so nothing is published and nothing is
+ * committed. THIS call removes only the OTHER outcome -- a crash losing the
+ * directory entry, which leaves an orphan ROW naming a file that is not there,
+ * the direction trap 10's premise already calls harmless, 28-13 made inert and
+ * 28-16 refuses BY NAME. Refusing an ordinary write because that harmless
+ * direction could not be closed would trade a bounded, non-destructive
+ * half-state for a store that cannot be written at all: `openSync(dir, "r")`
+ * needs the ring directory READABLE, so a writable-but-unreadable ring (mode
+ * 0300 -- measured) would make every `setDataType` throw, and that is also the
+ * precondition CR-07's only behavioural control is built from. So the two
+ * reachable outcomes after an interruption stay exactly the two this module
+ * bounds them to -- a missing entry, or an entry whose contents ARE durable --
+ * and the failure of this call moves the outcome from the second to the first
+ * rather than out of the pair.
+ */
+function publishSnapshot(stagingPath: string, snapPath: string): void {
+  renameSync(stagingPath, snapPath);
+  try {
+    fsyncPath(dirname(snapPath));
+  } catch {
+    // deliberately ignored -- see above. Swallowed rather than reported for the
+    // same reason `discardSnapshot` swallows: replacing the caller's ACTUAL
+    // outcome with a second error about a durability step whose failure leaves
+    // an already-bounded half-state is a worse answer than the one it replaces.
+  }
+}
+
+/**
+ * Removes a staged snapshot that will never be published, on every refusal and
+ * every rollback exit of the write sequence. A safe no-op after a successful
+ * publication, because the staged file no longer exists under that name -- which
+ * is why the call sites do not have to know which side of the publication they
+ * are on.
+ *
+ * AND IT IS THE ONE PLACE A STAGING FILE IS REMOVED, which is why `revertTo`'s
+ * three cleanup exits route through it too (WR-24 / WR-11). Those three used to
+ * be bare `rmSync(staging, { force: true })` calls, so the module had two
+ * answers to "where does a staging file get removed" and a later reader looking
+ * for the one place found only half of them. The swallowing semantics below are
+ * what all three of those sites want as well: each is already refusing with a
+ * named error the caller needs to read, and a second error about a temporary
+ * file would replace it.
+ *
+ * Swallowing on purpose. A staging file this fails to remove is an orphan
+ * `.tmp`, and an orphan `.tmp` is harmless: nothing addresses it, no pointer row
+ * can name it and the reconciliation sweep does not match it. Reporting a second
+ * error here would replace the caller's ACTUAL refusal -- the one it needs to
+ * read -- with a confusing one about a temporary file.
+ */
+function discardSnapshot(stagingPath: string): void {
+  try {
+    rmSync(stagingPath, { force: true });
+  } catch {
+    // deliberately ignored -- see above
+  }
+}
+
+/**
+ * The write sequence. THE ORDER BELOW IS LOAD-BEARING and is not a style
+ * choice:
+ *
+ *   1. read the current revision;
+ *   2. refuse immediately if the caller based its edit on a different one;
+ *   3. STAGE the pre-mutation snapshot with `vacuum into`, under a name unique
+ *      to this attempt and outside the published naming;
+ *   4. `begin immediate`;
+ *   5. compare-and-swap the revision, requiring exactly one changed row;
+ *   6. PUBLISH the staged snapshot onto the revision's path by rename, then
+ *      insert the snapshot pointer row for the PRE-mutation revision;
+ *   7. run the caller's mutation;
+ *   8. commit -- once, through the module's one commit site;
+ *   9. prune the snapshot ring -- AFTER the commit and OUTSIDE the
+ *      transaction, because an unlink is not transactional (trap 10).
+ *
+ * WHY THE SNAPSHOT PRECEDES THE MUTATION: reverse the two and a kill inside
+ * the window leaves a DURABLE MUTATION WITH NO SNAPSHOT -- an edit that can
+ * never be undone. In the present order a kill inside the window leaves an
+ * orphan snapshot FILE, which is harmless and reconcilable by revision number.
+ *
+ * WHY THE SNAPSHOT IS STAGED AND ONLY PUBLISHED AFTER THE COMPARE-AND-SWAP IS
+ * WON: a published snapshot must have EXACTLY ONE writer -- the writer that
+ * goes on to commit that revision's pointer row. The earlier arrangement did
+ * the filesystem work before the lock, on the published path, with no check
+ * that a committed pointer row already owned it, so a writer that was about to
+ * be REFUSED could still replace a winner's bytes:
+ *
+ *     B reads rev 5; A reads rev 5, snapshots r5.db, wins the CAS, commits the
+ *     row (5, r5.db); B removes r5.db and re-creates it from the CURRENT
+ *     (revision 6) state; B's CAS then fails and B is refused -- leaving A's
+ *     committed row describing revision 6, and `revertTo(5)` silently restoring
+ *     the wrong state.
+ *
+ * A refusal must be indistinguishable, from every other process's point of
+ * view, from the write never having been attempted -- ON DISK INCLUDED, in
+ * bytes nobody reads until a revert. Staging under a per-attempt name and
+ * publishing by rename only after the CAS is won is what makes that true: a
+ * loser touches nothing but its own staging file, and discards even that.
+ *
+ * WHY THE POINTER ROW IS INSERTED INSIDE THE SAME TRANSACTION AS THE MUTATION:
+ * that is the mechanism that makes the durability claim and the revert claim
+ * fail TOGETHER from one planted violation instead of separately. Removing the
+ * commit at step 8 loses the mutation and the pointer row at once, so a single
+ * combined test reddens in both halves.
+ */
+function runWriteSequence<T>(
+  handle: AnnoStoreHandle,
+  mutate: (db: DatabaseSync) => T,
+  doCommit: boolean,
+  baseRevision?: number,
+): { revision: number; result: T } {
+  // BEFORE `begin immediate`, AND BEFORE ANYTHING IS READ (WR-18). A previous
+  // write's housekeeping sweep ran on THIS connection and reported that its own
+  // `rollback` threw, so the connection may still hold an open transaction and
+  // the store's write lock. Without this refusal the next `begin immediate`
+  // surfaces SQLite's bare `cannot start a transaction within a transaction` --
+  // CR-07's exact reported symptom, outside the `ViceError` family, with nothing
+  // naming the cause or the remedy.
+  //
+  // AN EXISTING IN-FAMILY CLASS, NOT A NEW ONE: this is the same fact the commit
+  // handler and the publish handler already report in prose, so it is reported
+  // in the same words -- CLOSE IT AND REOPEN -- rather than given a second
+  // vocabulary a caller would have to learn.
+  if (handle.transactionStateUnknown) {
+    throw new AnnoStoreError(
+      `${handle.path}: refusing the write -- a previous write's housekeeping sweep on this connection could not roll back its own ` +
+        `transaction, so this connection may still hold an open transaction and the store's write lock. Its transaction state cannot ` +
+        `be established from this process (Node's DatabaseSync exposes no transaction-state accessor), so it is not reused: CLOSE IT ` +
+        `AND REOPEN rather than reusing it. The store on disk is unharmed -- the write that produced this state COMMITTED -- and a ` +
+        `freshly opened handle on the same path writes normally.`,
+      { data: { path: handle.path, step: "refuse a handle whose transaction state is unknown" } },
+    );
+  }
+
+  const rev = currentRevision(handle);
+
+  if (baseRevision !== undefined && baseRevision !== rev) {
+    throw new AnnoStoreStaleRevisionError(
+      `refusing the write: base revision ${baseRevision} is not the current on-disk revision ${rev}`,
+      { baseRevision, currentRevision: rev },
+    );
+  }
+
+  // WR-01, THE PRE-LOCK ARM. `stageSnapshot` runs BEFORE `begin immediate`, so
+  // it gets its own handler rather than sharing the outer one below: there is
+  // no transaction to roll back yet and no staged file to discard, so the two
+  // arms genuinely differ in what they have to undo. The reachable input is a
+  // regular FILE sitting where the ring directory should be, which makes
+  // `mkdirSync` throw `EEXIST` with no privilege and no race involved -- and
+  // unwrapped that escaped as a bare `Error`.
+  let staging: string;
+  try {
+    staging = stageSnapshot(handle, rev);
+  } catch (e) {
+    if (e instanceof ViceError) throw e;
+    throw new AnnoStoreError(
+      `${handle.path}: the write sequence failed while staging the pre-mutation snapshot for revision ${rev} ` +
+        `(${(e as Error).message}). Nothing has been changed -- the transaction was not opened.`,
+      { data: { path: handle.path, revision: rev, step: "stage the pre-mutation snapshot" } },
+    );
+  }
+
+  // WR-01, THE MAIN WINDOW: `begin immediate`, the compare-and-swap, the
+  // publication and the pointer-row insert, wrapped as ONE region. Its catch
+  // undoes both kinds of state this region can leave behind -- an open
+  // transaction with the compare-and-swap applied, and a staged `.tmp` -- and
+  // only then rethrows. A `ViceError` goes through UNCHANGED so no existing
+  // refusal's class or message moves; anything else is wrapped, which is what
+  // keeps the family closed.
+  //
+  // THE INNER ROLLBACK AND DISCARD IN THE CAS-FAILURE BRANCH BELOW ARE NOT
+  // REDUNDANT AND MUST NOT BE "SIMPLIFIED" AWAY. `anno-store.test.ts`'s WR-11
+  // control extracts the slice between `cas.changes` and `publishSnapshot` and
+  // asserts a `rollback` is present inside it, positioned after the
+  // `select revision from anno_meta` read -- that positioning is a VERIFIED
+  // behaviour, because the second number is only visible while that transaction
+  // still sees it. What this handler's own second attempt does on a connection
+  // that branch already rolled back is throw "no transaction is active", which
+  // its own swallowing `try` absorbs; and its second `discardSnapshot` is a
+  // `force: true` no-op.
+  try {
+    handle.db.exec("begin immediate");
+
+    const cas = handle.db.prepare("update anno_meta set revision = revision + 1 where id = 1 and revision = ?").run(rev);
+    if (Number(cas.changes) !== 1) {
+      // THE SECOND NUMBER IS READ BEFORE THE ROLLBACK, and the order is the
+      // point: this is the one refusal path on which a CONCURRENT writer moved
+      // the revision, so it is the path on which the second number is most
+      // informative -- and it is only visible while this transaction still sees
+      // it. Reporting "the revision moved" with one number is the word
+      // "conflict" with extra steps: the caller cannot tell a lost race from a
+      // mistyped base, and cannot say which two values disagreed.
+      const moved = handle.db.prepare("select revision from anno_meta where id = 1").get() as { revision: number } | undefined;
+      handle.db.exec("rollback");
+      discardSnapshot(staging);
+      throw new AnnoStoreStaleRevisionError(
+        `refusing the write: the revision moved under us (expected ${rev}, found ${moved === undefined ? "no meta row" : moved.revision})`,
+        { baseRevision: rev, currentRevision: moved?.revision },
+      );
+    }
+
+    // ONLY THE WINNER REACHES HERE, which is the whole ownership discipline: the
+    // publication sits between the won compare-and-swap and the pointer-row
+    // insert, so the writer that puts the bytes at the revision's path is
+    // exactly the writer whose row will claim them. A loser never names this
+    // path at all.
+    const snapPath = snapshotPathFor(handle, rev);
+    publishSnapshot(staging, snapPath);
+
+    // THE ROW CARRIES A REVISION NUMBER AND NOTHING ELSE. Its location is not
+    // persisted: `snapshotPathFor(handle, revision)` recomputes it at every read
+    // and every delete, so the row cannot come to disagree with the file it
+    // claims (see `retainedRevisions`).
+    handle.db.prepare("insert into anno_snapshot(revision) values (?)").run(rev);
+  } catch (e) {
+    // THE ROLLBACK'S OUTCOME IS RECORDED, NOT ASSUMED (WR-16). The message below
+    // used to state the rollback as a fact after this `catch` had swallowed that
+    // rollback's own failure, so the one case in which the claim is false is
+    // exactly the case in which it was printed. Node 22's `DatabaseSync` exposes
+    // no transaction-state accessor -- the surface is `open, close, prepare,
+    // exec, function, location, aggregate, createSession, applyChangeset,
+    // enableLoadExtension, loadExtension`, measured on this host -- so this local
+    // is the only thing that can keep the message honest.
+    let rolledBack = true;
+    try {
+      handle.db.exec("rollback");
+    } catch {
+      // Deliberately ignored. On the CAS-failure path this connection has
+      // already been rolled back, so this second attempt reports "no
+      // transaction is active" -- and there is nothing useful to do with a
+      // second error anyway: reporting it would replace the caller's actual
+      // refusal. Only the FACT is kept.
+      rolledBack = false;
+    }
+    // Unconditional and safe unconditionally: `force: true` on a name the
+    // publication may already have renamed away is a no-op, so this call site
+    // does not have to know which side of the publication the failure landed on.
+    // What it removes is the case that matters -- a failure BEFORE the rename,
+    // which would otherwise leave a `.tmp` nothing addresses and that the
+    // reconciliation sweep is deliberately anchored NOT to match, so nothing
+    // would ever clean it up.
+    discardSnapshot(staging);
+    if (e instanceof ViceError) throw e;
+    throw new AnnoStoreError(
+      `${handle.path}: the write sequence failed between the staged snapshot and the pointer-row insert for revision ${rev} ` +
+        `(${(e as Error).message}). ` +
+        (rolledBack
+          ? `The transaction has been rolled back and the staged snapshot discarded, so the revision is unchanged.`
+          : `The staged snapshot has been discarded, but the rollback ALSO failed: this connection may still hold an open transaction ` +
+            `and the store's write lock, so CLOSE IT AND REOPEN rather than reusing it. Nothing was written -- the store on disk is ` +
+            `still at revision ${rev} -- but this connection's own view of the revision cannot be trusted until it is reopened.`),
+      { data: { path: handle.path, revision: rev, rolledBack, step: "publish the snapshot and insert its pointer row" } },
+    );
+  }
+
+  // A REFUSAL RAISED INSIDE THE MUTATION MUST ROLL THE WHOLE SEQUENCE BACK.
+  // Several entry points below refuse from inside their mutation on purpose,
+  // because the refusal needs to read rows -- a label name already bound to a
+  // different address is the load-bearing case, and reading it outside the
+  // transaction would open a window in which a concurrent writer binds the
+  // name between the read and the insert. Without this rollback the thrown
+  // refusal would leave the transaction OPEN with the revision compare-and-swap
+  // already applied, so `currentRevision()` on this same connection would report
+  // an advanced revision for a write that was refused, and every later statement
+  // would run inside a transaction nobody meant to start.
+  //
+  // The inner catch is deliberately silent: if the rollback itself fails there
+  // is nothing useful to do with that second error, and reporting it would
+  // replace the caller's actual refusal with a confusing one.
+  let result: T;
+  try {
+    result = mutate(handle.db);
+  } catch (mutationError) {
+    try {
+      handle.db.exec("rollback");
+    } catch {
+      // deliberately ignored -- see above
+    }
+    // Unconditional, and safe unconditionally: by this point the staged file has
+    // already been renamed onto the revision's path, so this is a no-op -- the
+    // call site does not have to know which side of the publication it is on.
+    // What the rollback DOES leave behind is a published FILE no pointer row
+    // claims, which is the harmless direction: `reconcileSnapshotRing` sweeps
+    // exactly that.
+    discardSnapshot(staging);
+    throw mutationError;
+  }
+
+  if (doCommit) {
+    // CR-06, THE COMMIT ARM. This is the ONE statement in the sequence whose
+    // failure leaves the transaction OPEN with everything already applied -- the
+    // compare-and-swap, the caller's mutation and the pointer-row insert -- and
+    // it was outside every handler until this arm was added. A concurrent READER
+    // is enough to trigger it: `COMMIT` of a write transaction needs SQLite's
+    // EXCLUSIVE lock, and step 4's `begin immediate` never excluded readers. It
+    // was reproduced with a genuinely separate OS process holding a read
+    // transaction: a bare `Error: database is locked` after the connection's
+    // 5000 ms `busy_timeout`, outside the `ViceError` family, with the write
+    // lock still held and `currentRevision()` on this connection reporting the
+    // ADVANCED revision for a write that never landed. On the Phase 29 tool
+    // path a handle lives as long as the session, so the leaked write lock
+    // locks every other connection out for that long.
+    //
+    // THE ROLLBACK IS THE REPAIR, not the refusal: it releases the store's write
+    // lock and undoes the compare-and-swap, the caller's mutation and the
+    // pointer-row insert TOGETHER, so `currentRevision()` on this connection
+    // goes back to `rev` and the handle is immediately usable again. Its inner
+    // `catch` swallows for the same stated reason as the two handlers above --
+    // there is nothing useful to do with a second error and reporting it would
+    // replace the caller's actual refusal.
+    //
+    // `discardSnapshot(staging)` is a NO-OP by the time control reaches here:
+    // `publishSnapshot` has already renamed the staged file onto the revision's
+    // published path, so nothing exists under the staging name and `force: true`
+    // returns quietly. It is called anyway so this arm matches the other two and
+    // no future reader has to prove which side of the publication it is on. The
+    // PUBLISHED file is deliberately left behind: with the pointer row rolled
+    // back it is an orphan FILE -- the harmless direction, which the next
+    // accepted write's sweep reclaims.
+    //
+    // The refusal carries `code` from the underlying error when it has one
+    // (IN-05's cheap half, on this wrap only), so a caller can ask whether the
+    // failure was lock contention without substring-matching the message.
+    // `cause` is deliberately NOT added: that needs a new field on
+    // `ViceErrorOptions` in `vice.ts`, a shared module outside this phase.
+    try {
+      commitTransaction(handle.db);
+    } catch (e) {
+      // RECORDED, NOT ASSERTED (WR-16). "the transaction has been rolled back"
+      // was stated as a fact directly under a `catch` that swallowed the
+      // rollback's own failure -- so on the one path where the claim is false it
+      // was still printed, and a refusal that reports the CR-06 state as its own
+      // repair sends the caller straight back into reusing a connection that may
+      // still hold the store's write lock. There is no cheap check available:
+      // Node 22's `DatabaseSync` exposes no transaction-state accessor (surface
+      // measured on this host: `open, close, prepare, exec, function, location,
+      // aggregate, createSession, applyChangeset, enableLoadExtension,
+      // loadExtension`), which is a reason not to ASSERT the outcome, and this
+      // local is what replaces the assertion.
+      let rolledBack = true;
+      try {
+        handle.db.exec("rollback");
+      } catch {
+        // deliberately ignored -- see above; only the FACT is kept.
+        rolledBack = false;
+      }
+      discardSnapshot(staging);
+      if (e instanceof ViceError) throw e;
+      throw new AnnoStoreError(
+        `${handle.path}: the write for revision ${rev + 1} could not be committed (${(e as Error).message}). ` +
+          (rolledBack
+            ? `Nothing was written and the transaction has been rolled back, so the store is still at revision ${rev}.`
+            : `Nothing was written, but the rollback ALSO failed: this connection may still hold an open transaction and the store's ` +
+              `write lock, so CLOSE IT AND REOPEN rather than reusing it. The store on disk is still at revision ${rev}, while this ` +
+              `connection may report ${rev + 1} for a write that never landed.`),
+        {
+          code: (e as { code?: number | string }).code,
+          // `rolledBack` is carried in `data` as well as in the prose so a caller
+          // can branch on the fact instead of substring-matching a message.
+          // The wording here is FREE. It used to be constrained: the
+          // single-commit-site control in `anno-seam.test.ts` counted the WORD
+          // `commit` over this module's stripped source, so a `step` value
+          // reading "commit ..." reddened a control in a different file. WR-15
+          // replaced that count with a match on `exec()` calls carrying a bare
+          // statement literal, which no error message can satisfy, and the
+          // constraint went with it -- this value is unchanged only because
+          // changing it would be a gratuitous behaviour change.
+          data: { path: handle.path, revision: rev, rolledBack, step: "committing the write transaction" },
+        },
+      );
+    }
+    // STEP 9, AND ITS POSITION IS THE POINT: the prune runs AFTER the commit
+    // and OUTSIDE the transaction (trap 10). It sits inside the `doCommit`
+    // branch because a sequence that never commits has no accepted write to
+    // bound.
+    //
+    // WR-02: WRAPPED, AND DELIBERATELY NOT RETHROWN. By this line the
+    // transaction has already returned, so THE WRITE HAPPENED -- the mutation
+    // and the pointer row are durable. A housekeeping failure that threw from
+    // here would report a write that succeeded as a failure, and the caller
+    // would retry an ADDITIVE verb and produce a second row. That is WR-02's
+    // exact complaint, and it became more likely rather than less once the
+    // sweep started taking the write lock.
+    //
+    // The consequence of swallowing is an UN-PRUNED RING -- extra files, the
+    // direction trap 10's own premise calls harmless and reconcilable by
+    // revision number -- and the next accepted write's sweep resolves it. There
+    // is deliberately NO logging channel: this module has none, and introducing
+    // one here would be new surface with its own stdio hazards on an MCP
+    // transport.
+    //
+    // AND ITS REPORT IS CONSUMED (WR-18). `pruneSnapshots` returns the sweep's
+    // `rollbackFailed` -- the one state the sweep's own handler cannot fix --
+    // and it is RECORDED ON THE HANDLE rather than thrown or logged. Not thrown,
+    // because by this line the write is committed and 28-11 P5 forbids reporting
+    // a committed write as a failure; not logged, because this module has no
+    // logging channel and introducing one here would be new surface with stdio
+    // hazards on an MCP transport (see the paragraph above).
+    //
+    // THE WRITE'S OWN RESULT IS STILL A SUCCESS WITH ITS REVISION. The fact is
+    // carried on the HANDLE precisely so the write that succeeded is not the
+    // call that reports it: the NEXT call on this connection refuses by name at
+    // the head of this function, with the close-and-reopen remedy.
+    try {
+      if (pruneSnapshots(handle)) handle.transactionStateUnknown = true;
+    } catch {
+      // deliberately ignored -- see above
+    }
+  }
+
+  return { revision: rev + 1, result };
+}
+
+/** Runs `mutate` as one durable, revision-advancing write. */
+export function applyWrite<T>(
+  handle: AnnoStoreHandle,
+  mutate: (db: DatabaseSync) => T,
+  opts: { baseRevision?: number } = {},
+): { revision: number; result: T } {
+  return runWriteSequence(handle, mutate, true, opts.baseRevision);
+}
+
+/**
+ * The same sequence WITHOUT the commit. This exists for exactly one reason and
+ * no other: the durability-and-revert proof's planted violation is "remove the
+ * commit", and a planting that drives the IDENTICAL code path is stronger
+ * evidence than a hand-copied variant that can drift out of agreement with the
+ * real one.
+ *
+ * Its only caller is a spawned, test-only helper that is deliberately absent
+ * from `package.json`'s `files[]`, and `anno-seam.test.ts` asserts that no
+ * shipped module other than this one so much as names it.
+ */
+export function applyWriteWithoutCommit<T>(
+  handle: AnnoStoreHandle,
+  mutate: (db: DatabaseSync) => T,
+  opts: { baseRevision?: number } = {},
+): { revision: number; result: T } {
+  return runWriteSequence(handle, mutate, false, opts.baseRevision);
+}
+
+/**
+ * The module's ONE range insert. `bank` is a parameter rather than a hardcoded
+ * `null` (IN-06): a remainder re-inserted by split-and-preserve carries the
+ * overlapped row's own `bank` forward, and a newly typed range carries `null`.
+ * `bank` is reserved and interpreted by nothing today, which is exactly why a
+ * write path that silently dropped it would be an unobservable loss a future
+ * banked-memory model inherits.
+ */
+function insertRange(db: DatabaseSync, start: number, endInclusive: number, dataType: string, bank: number | null): void {
+  db.prepare("insert into anno_range(start, end_inclusive, data_type, bank) values (?, ?, ?, ?)").run(start, endInclusive, dataType, bank);
+}
+
+/** One overlapped row as `retype()` reads it. `bank` is selected because the
+ * remainders re-inserted from this row must carry it forward. */
+interface OverlappedRangeRow {
+  id: number;
+  start: number;
+  end_inclusive: number;
+  data_type: string;
+  bank: number | null;
+}
+
+/**
+ * Would preserving `remainderStart..remainderEndInclusive` as `row`'s own type
+ * write a row the store would REFUSE at its own entry point? Returns the
+ * refusal to throw, or `null` when the remainder is legal.
+ *
+ * THE QUESTION IS ASKED THROUGH `assertRangeShape` ITSELF, never through a
+ * re-implemented even-count test. That is the whole point: there is then exactly
+ * ONE definition of a legal range shape in the repo, and a rule added to it
+ * later applies to the store's own writer for free. A second copy of the rule
+ * here would drift the moment the first one is edited, and the drift is silent.
+ *
+ * It is a separate named function rather than inline code so the round-trip
+ * invariant in `anno-overlap.test.ts` has a named thing to point at.
+ */
+function remainderRefusal(
+  row: OverlappedRangeRow,
+  remainderStart: number,
+  remainderEndInclusive: number,
+  side: "head" | "tail",
+  callerStart: number,
+  callerEndInclusive: number,
+): AnnoSplitRemainderError | null {
+  try {
+    assertRangeShape(remainderStart, remainderEndInclusive, row.data_type as DataType);
+    return null;
+  } catch (e) {
+    if (!(e instanceof AnnoRangeShapeError)) throw e;
+    // The caller's own boundary on the OFFENDING side. Moving it by one flips
+    // the remainder's parity, so the two nearest legal values are one either
+    // way -- reported as numbers so the caller does not have to work out which
+    // end to move or by how much.
+    const boundaryName = side === "head" ? "start" : "endInclusive";
+    const boundary = side === "head" ? callerStart : callerEndInclusive;
+    const span = remainderEndInclusive - remainderStart + 1;
+    const message =
+      `typing ${callerStart}..${callerEndInclusive} (${hexRange(callerStart, callerEndInclusive)}) would split range id ${row.id} ` +
+      `(${row.start}..${row.end_inclusive}, ${hexRange(row.start, row.end_inclusive)}, ${row.data_type}) and leave a ${side} remainder ` +
+      `${remainderStart}..${remainderEndInclusive} (${hexRange(remainderStart, remainderEndInclusive)}) of ${span} byte(s), which is not a ` +
+      `shape this store accepts: ${e.message}. The whole retype is refused, so nothing was written. The nearest ${boundaryName} values ` +
+      `that would leave an even ${side} are ${boundary - 1} and ${boundary + 1}; alternatively extend the retype to one of the table's ` +
+      `own entry boundaries, or retype the whole table to the type you want first.`;
+    return new AnnoSplitRemainderError(message, {
+      start: remainderStart,
+      endInclusive: remainderEndInclusive,
+      rowId: row.id,
+      rowStart: row.start,
+      rowEndInclusive: row.end_inclusive,
+      dataType: row.data_type as DataType,
+      remainderStart,
+      remainderEndInclusive,
+      side,
+    });
+  }
+}
+
+/** `$xxxx-$xxxx`, the spelling the rest of this module's messages use. */
+function hexRange(start: number, endInclusive: number): string {
+  return `$${start.toString(16).padStart(4, "0")}-$${endInclusive.toString(16).padStart(4, "0")}`;
+}
+
+/** A canonical key for one entry-address couple, so the intersection below is
+ * exact set arithmetic rather than an `includes()` over arrays that compares
+ * tuple IDENTITY and would report every pair lost. */
+function entryPairKey(pair: readonly [number, number]): string {
+  return `${pair[0]}:${pair[1]}`;
+}
+
+/**
+ * What fragmenting `row` at the caller's range COSTS, or `null` when it costs
+ * nothing this record could describe (CR-10).
+ *
+ * `null` in exactly two cases, both of them honest:
+ *   * the row is not a split-table layout -- asked through `isSplitDataType`,
+ *     never through a hand-written list of the four names (`anno-types.ts` trap
+ *     2). A non-split row's meaning does not depend on its extent, so there is
+ *     nothing to disclose;
+ *   * the caller's range leaves NO remainder of this row. Nothing survives, so
+ *     no preservation is claimed and none is owed. A full cover is a deletion,
+ *     and a deletion is already visible in the row set.
+ *
+ * Otherwise it consults the SPLIT LAYOUT'S OWN PAIRING RULE through
+ * `splitEntryAddressPairs()` -- the same single definition `resolveSplitTargets()`
+ * consumes -- once over the ROW's span and once over each remainder's, and
+ * reports both sets plus their intersection.
+ *
+ * IT MUST RUN AFTER `remainderRefusal()` FOR THE SAME ROW AND BEFORE THE FIRST
+ * `delete`. After, because a remainder that fails the parity gate is not a
+ * remainder this store will ever write and `splitEntryAddressPairs()` would
+ * refuse it; before, because a refusal must still cost nothing and an acceptance
+ * must never be half-applied.
+ *
+ * PURE: no I/O, no SQL, no state. It reads the row shape it is handed.
+ */
+function splitReinterpretation(
+  row: OverlappedRangeRow,
+  callerStart: number,
+  callerEndInclusive: number,
+): SplitTableReinterpretation | null {
+  const dataType = row.data_type as DataType;
+  if (!isSplitDataType(dataType)) return null;
+
+  const hasHead = row.start < callerStart;
+  const hasTail = row.end_inclusive > callerEndInclusive;
+  if (!hasHead && !hasTail) return null;
+
+  const layout = dataType as SplitDataType;
+  const before = splitEntryAddressPairs(row.start, row.end_inclusive, layout);
+
+  // HEAD THEN TAIL, and the order is part of the contract: within one record the
+  // survivors read in ascending address order, which is the order the mutation
+  // loop below re-inserts them in.
+  const survivors: SplitTableSurvivor[] = [];
+  const addSurvivor = (start: number, endInclusive: number): void => {
+    const pairs = splitEntryAddressPairs(start, endInclusive, layout);
+    survivors.push({ start, endInclusive, entryCount: pairs.entryCount, entryPairs: pairs.pairs });
+  };
+  if (hasHead) addSurvivor(row.start, callerStart - 1);
+  if (hasTail) addSurvivor(callerEndInclusive + 1, row.end_inclusive);
+
+  // THE INTERSECTION IS COMPUTED, NOT ASSUMED. It is empty today for every
+  // proper fragment -- that is the arithmetic in `retype()`'s DECISION 1 -- but
+  // hardcoding the emptiness would make this field a restatement of the layout
+  // rather than a measurement of it, and it would stop being true the moment a
+  // layout with a different pairing is added.
+  const survivingKeys = new Set(survivors.flatMap((s) => s.entryPairs.map(entryPairKey)));
+  const preservedEntryPairs = before.pairs.filter((pair) => survivingKeys.has(entryPairKey(pair)));
+
+  const survivorText = survivors
+    .map((s) => `${s.start}..${s.endInclusive} (${hexRange(s.start, s.endInclusive)}, ${s.entryCount} entries)`)
+    .join(" and ");
+  const summary =
+    `typing ${callerStart}..${callerEndInclusive} (${hexRange(callerStart, callerEndInclusive)}) fragments range id ${row.id} ` +
+    `(${row.start}..${row.end_inclusive}, ${hexRange(row.start, row.end_inclusive)}, ${dataType}, ${before.entryCount} entries), ` +
+    `leaving ${survivorText}. A split table pairs byte i with byte n + i, so changing either end re-pairs every entry: ` +
+    `${preservedEntryPairs.length} of ${before.entryCount} entry-address pairs are preserved. The surviving row(s) are still legal ` +
+    `and still decode -- they decode to DIFFERENT 16-bit values than the ones recorded here.`;
+
+  return {
+    rowId: row.id,
+    rowStart: row.start,
+    rowEndInclusive: row.end_inclusive,
+    dataType: layout,
+    entryCountBefore: before.entryCount,
+    entryPairsBefore: before.pairs,
+    survivors,
+    preservedEntryPairs,
+    summary,
+  };
+}
+
+/**
+ * SPLIT-AND-PRESERVE. Every row overlapping the new range is deleted, and the
+ * parts of it that fall OUTSIDE the new range are re-inserted with their
+ * original type -- the head when the old row started earlier, the tail when it
+ * ended later.
+ *
+ * Why not the obvious `filter()`-and-insert (delete every overlapping row,
+ * insert the new one): it is accidentally RIGHT on the total-typed-bytes
+ * metric for four of the five overlap cases, and it LOSES BYTES in the
+ * fully-contained case -- an old row strictly wider than the new one on both
+ * sides has both its head and its tail discarded. That case is therefore the
+ * detector, and a proof that exercises only the other four proves nothing.
+ *
+ * Returns whether the mutation CHANGED anything. Typing a range that is already
+ * exactly that range with exactly that type is a no-op: it leaves the single
+ * existing row alone and reports `false`. The revision still advances, because
+ * every accepted write advances it by exactly one -- so `changed` is the ONLY
+ * signal that distinguishes a no-op, and the revision is never that signal.
+ *
+ * ---------------------------------------------------------------------------
+ * DECISION 1: THE SPLIT-ROW REMAINDER RULE -- TWO OUTCOMES, NEITHER SILENT
+ * (CR-09 and CR-10).
+ * ---------------------------------------------------------------------------
+ * A split-table row has TWO things that can go wrong when a caller's range
+ * fragments it, and this function answers them differently on purpose. The
+ * comment and the code below state ONE rule, and both halves of it are here.
+ *
+ * (1) THE ODD REMAINDER IS REFUSED, and the whole retype is refused with it
+ * (CR-09). A remainder that is not a legal shape for its OWN type -- the
+ * odd-byte-count tail of a fragmented split table is the reachable case -- is a
+ * row `setDataType` would decline to create and `resolveSplitTargets()` cannot
+ * decode. The store never persists a range row it would refuse at its own entry
+ * point, by any writer. DEMOTING the illegal remainder to the vocabulary's
+ * `undefined` member was considered and REJECTED, because it destroys the
+ * recorded split ORIENTATION, which this module's own header calls the one
+ * irreversible decision in this area with no field to migrate -- a one-way data
+ * decision taken silently on the caller's behalf. Rounding the caller's range
+ * outward to an entry boundary is forbidden outright by `anno-types.ts` trap 7.
+ *
+ * (2) THE EVEN REMAINDER IS ACCEPTED **WITH A REPORT** -- never accepted
+ * silently (CR-10). Parity is not the only thing a fragment can break. A split
+ * table pairs byte `i` with byte `n + i`, so an entry's partner is a function of
+ * the row's START and its LENGTH, and changing either end re-pairs EVERY entry.
+ *
+ * THE ARITHMETIC, because it settles the design rather than merely describing
+ * it: a surviving fragment of `m` entries pairs its own byte `j` with its own
+ * byte `m + j`, which matches an original pair only when `m == n` -- only when
+ * the fragment IS the whole row. **No proper fragment preserves a single entry
+ * pair, at any boundary, THE MIDPOINT INCLUDED.** So preservation is not
+ * something a cleverer boundary rule can recover, and the surviving rows are the
+ * dangerous kind of wrong: legal, re-acceptable, decodable, and decoding to
+ * different 16-bit values than the ones a human recorded.
+ *
+ * ANSWER (a) -- REFUSE ANY PARTIAL OVERLAP OF A SPLIT ROW -- WAS WEIGHED AND NOT
+ * TAKEN. It is defensible and it is implementable, but it makes split tables
+ * editable only WHOLESALE, and the inputs it would refuse are ordinary
+ * annotation work: correcting a few bytes inside a table, or trimming a table
+ * typed one entry too wide. Split-and-preserve exists for exactly that.
+ *
+ * WHAT IS TAKEN is answer (b): `splitReinterpretation()` builds one record per
+ * fragmented split row, carrying the pairs the row read BEFORE and the pairs
+ * each survivor reads AFTER, and `setDataType()` returns it as DATA on a
+ * SUCCESSFUL result beside `contradictedComments`. The failing clause was never
+ * "a partial overwrite must preserve"; it was "silently un-documenting a
+ * previously annotated region is the exact failure the store exists to prevent".
+ * Disclosure removes the silence, which is the clause that was actually false.
+ *
+ * RECORDING THE TABLE'S ORIGINAL EXTENT ON DISK -- so the pairing could be
+ * reconstructed later -- WAS REJECTED. It is a new column, therefore a
+ * `SCHEMA_VERSION` bump, therefore a one-way decision requiring the older
+ * on-disk shape to refuse by name (28-10 P4); and this milestone's one
+ * irreversible decision is already spent on the twelve-member vocabulary. The
+ * return channel gives the caller the same fact at the only moment it can still
+ * act on it, and costs nothing that cannot be reverted.
+ *
+ * BOTH CHECKS RUN OVER EVERY REMAINDER OF EVERY OVERLAPPING ROW BEFORE THE FIRST
+ * `delete`, and the ordering is the guarantee, not a tidiness preference: a
+ * refusal must cost nothing observable, and leaning on the transaction's
+ * rollback to undo a half-applied mutation would make that depend on a rollback
+ * that the CR-06 arm's own `rollbackFailed` handling shows can itself fail.
+ * Compute, refuse, then mutate. The parity check runs FIRST and is untouched by
+ * the disclosure: a refusing retype returns no report because it returns nothing
+ * at all.
+ *
+ * ---------------------------------------------------------------------------
+ * DECISION 2: THE UNION COLLAPSE IS INTENDED (STORE-02, round-3 WR-08).
+ * ---------------------------------------------------------------------------
+ * A caller range that SPANS several existing rows deletes all of them and
+ * inserts one row. That is intended, and it does not contradict STORE-02:
+ * STORE-02 forbids the store joining adjacent ranges OF ITS OWN ACCORD, and
+ * here the caller asked for exactly one range and got exactly one range. The
+ * store still never joins two rows nobody asked about -- see the behavioural
+ * and structural adjacency controls.
+ *
+ * `changed: true` is CORRECT for that call even when every address resolves to
+ * the same type afterwards, because `changed` reports the ROW SET and the row
+ * identities really did change: both original ids are gone and a new one exists.
+ * Both shapes -- the union retype and the same-type subrange, which fragments
+ * one row into three with every id churned -- are pinned BY VALUE in
+ * `anno-overlap.test.ts`, so "does not join" can be told apart from "was never
+ * asked to".
+ */
+function retype(
+  db: DatabaseSync,
+  start: number,
+  endInclusive: number,
+  dataType: DataType,
+): { changed: boolean; reinterpretedSplitTables: readonly SplitTableReinterpretation[] } {
+  const overlapping = db
+    .prepare("select id, start, end_inclusive, data_type, bank from anno_range where end_inclusive >= ? and start <= ? order by id")
+    // The cast names the shape INLINE rather than through `OverlappedRangeRow`
+    // for one mechanical reason: `node:sqlite` types `all()` as
+    // `Record<string, SQLOutputValue>[]`, and TypeScript refuses a direct
+    // assertion to a named interface as insufficiently overlapping while
+    // accepting the identical anonymous shape. The result is structurally the
+    // interface, which is what the helper below takes.
+    .all(start, endInclusive) as { id: number; start: number; end_inclusive: number; data_type: string; bank: number | null }[];
+
+  if (
+    overlapping.length === 1 &&
+    overlapping[0].start === start &&
+    overlapping[0].end_inclusive === endInclusive &&
+    overlapping[0].data_type === dataType
+  ) {
+    // AN IDENTICAL REPEAT REPORTS NOTHING. Nothing is fragmented, so a second
+    // disclosure of a fragmentation that already happened would be a false
+    // report -- and the field is empty rather than absent, so the caller still
+    // reads it unconditionally.
+    return { changed: false, reinterpretedSplitTables: [] };
+  }
+
+  // THE GATE. Every remainder the loop below would write, asked the entry
+  // point's own shape question, BEFORE anything is deleted or inserted -- and,
+  // for a split row that survives that question, what the fragmentation COSTS.
+  //
+  // WHAT THIS GATE DOES NOT ASK, said here because "THE GATE" reads absolute
+  // and a reader will otherwise take it for one (WR-31, 28-21 P1 / 28-07 P3):
+  // the shape question is asked of REMAINDERS, never of the overlapped row
+  // itself. A row the caller's range covers in full has no head and no tail,
+  // so neither branch below runs and its shape is never examined -- correctly,
+  // because the second loop DELETES it outright and a deletion owes no shape.
+  // The consequence to hold on to: a malformed legacy row (one an already-
+  // superseded build wrote) is refused only when something of it SURVIVES.
+  // Do not read this gate as a validity check over `overlapping`; it is a
+  // validity check over what `retype()` is about to write back.
+  //
+  // ORDER WITHIN THE LOOP IS LOAD-BEARING TWICE OVER: the two refusal checks run
+  // before the reinterpretation for the SAME row, so a row whose remainder fails
+  // parity never reaches a computation that would refuse it a second time with a
+  // worse message; and the whole loop runs before the first `delete`, so a
+  // refusal still costs nothing and an acceptance is never half-applied.
+  //
+  // The records are collected in the query's own `order by id` order, which is
+  // what makes the report's array order ASCENDING OVERLAPPED-ROW ID rather than
+  // an accident of iteration.
+  const reinterpretedSplitTables: SplitTableReinterpretation[] = [];
+  for (const row of overlapping) {
+    if (row.start < start) {
+      const refusal = remainderRefusal(row, row.start, start - 1, "head", start, endInclusive);
+      if (refusal) throw refusal;
+    }
+    if (row.end_inclusive > endInclusive) {
+      const refusal = remainderRefusal(row, endInclusive + 1, row.end_inclusive, "tail", start, endInclusive);
+      if (refusal) throw refusal;
+    }
+    const reinterpretation = splitReinterpretation(row, start, endInclusive);
+    if (reinterpretation !== null) reinterpretedSplitTables.push(reinterpretation);
+  }
+
+  for (const row of overlapping) {
+    db.prepare("delete from anno_range where id = ?").run(row.id);
+    if (row.start < start) {
+      insertRange(db, row.start, start - 1, row.data_type, row.bank);
+    }
+    if (row.end_inclusive > endInclusive) {
+      insertRange(db, endInclusive + 1, row.end_inclusive, row.data_type, row.bank);
+    }
+  }
+
+  insertRange(db, start, endInclusive, dataType, null);
+  return { changed: true, reinterpretedSplitTables };
+}
+
+/** The two grade brackets that assert the addresses are CODE, and the two that
+ * assert they are DATA -- derived from the five-grade vocabulary by their
+ * token's suffix rather than restated here. The vocabulary has exactly one home
+ * and this module is not it: a second copy of the four bracket strings would
+ * drift the moment the first one is edited, and the drift is silent. */
+const CODE_GRADE_BRACKETS: readonly string[] = CONFIDENCE_GRADES.filter((grade) => grade.token.endsWith("-code")).map((grade) => grade.bracket);
+const DATA_GRADE_BRACKETS: readonly string[] = CONFIDENCE_GRADES.filter((grade) => grade.token.endsWith("-data")).map((grade) => grade.bracket);
+
+/**
+ * Does retyping a region to `dataType` make a comment graded `gradeBracket`
+ * FALSE? The ONE definition of "contradicted" in this repo; the query path below
+ * calls it, and so does its test, so the rule and its proof cannot drift.
+ *
+ * The rule:
+ *   * a code-asserting grade is contradicted by any data type other than
+ *     `code` -- the comment says the bytes execute and the retype says they do
+ *     not;
+ *   * a data-asserting grade is contradicted by `code`, and by nothing else --
+ *     every other member of the vocabulary is another way of saying data, so a
+ *     `byte` region retyped to `word` leaves such a comment true;
+ *   * the no-reliable-interpretation grade, and an ungraded comment
+ *     (`gradeBracket` null), are NEVER contradicted. Neither one asserted
+ *     anything a retype could falsify.
+ *
+ * THE DECISION, WITH THE ALTERNATIVE NOT TAKEN. "Contradicts" means the retype
+ * makes the comment FALSE -- not merely that a comment happens to sit at a
+ * retyped address. The broad reading -- any comment at all at a retyped address
+ * is contradicted -- was considered and REJECTED, because it would make every
+ * retype of a commented range report, and a report that fires every time is a
+ * report nobody reads. The report exists so a human notices the one case that
+ * matters. A later reader must NOT "simplify" this predicate back into the broad
+ * form; that is a regression wearing the clothes of a cleanup.
+ */
+export function contradictedCommentsFor(gradeBracket: string | null, dataType: DataType): boolean {
+  if (gradeBracket === null) return false;
+  if (CODE_GRADE_BRACKETS.includes(gradeBracket)) return dataType !== "code";
+  if (DATA_GRADE_BRACKETS.includes(gradeBracket)) return dataType === "code";
+  return false;
+}
+
+/**
+ * Every stored comment inside `start..endInclusive` that retyping to `dataType`
+ * makes false, in ascending address order.
+ *
+ * MUST RUN INSIDE THE RETYPE'S OWN TRANSACTION. Run outside it, a comment
+ * written by another connection between the query and the retype would be
+ * missed, and the report would be silently short by one -- which is the failure
+ * mode a report is supposed to close, not open. `begin immediate` serialises the
+ * pair.
+ *
+ * A malformed bracket token is REFUSED here, never read as ungraded: swallowing
+ * it would quietly exempt that comment from the report forever.
+ */
+function collectContradictedComments(db: DatabaseSync, start: number, endInclusive: number, dataType: DataType): ContradictedComment[] {
+  const rows = db
+    .prepare("select address, comment_type, text from anno_comment where address >= ? and address <= ? order by address, comment_type")
+    .all(start, endInclusive) as { address: number; comment_type: string; text: string }[];
+
+  const out: ContradictedComment[] = [];
+  for (const row of rows) {
+    let grade: string | null;
+    try {
+      const parsed = parseConfidencePrefix(row.text);
+      grade = parsed.grade === null ? null : parsed.grade.bracket;
+    } catch (e) {
+      if (e instanceof AnnoConfidenceGradeError) {
+        throw new AnnoCommentGradeError(
+          `the comment at address ${row.address} ($${row.address.toString(16).padStart(4, "0")}) carries a bracket token the store cannot ` +
+            `interpret, so it cannot say whether typing that address as ${dataType} makes the comment false: ${e.message}`,
+          { comment: row.text, cause: e },
+        );
+      }
+      throw e;
+    }
+    if (contradictedCommentsFor(grade, dataType)) {
+      out.push({
+        address: row.address,
+        commentType: row.comment_type as CommentType,
+        text: row.text,
+        grade: grade as string,
+        contradictedBy: dataType,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * What `setDataType()` returns: `AnnoWriteResult` plus the two things this
+ * retype has just cost that the row set alone does not show -- the comments it
+ * made false, and the split tables it re-interpreted.
+ *
+ * BOTH REPORT FIELDS ARE ALWAYS PRESENT AND OFTEN EMPTY, never absent, so a
+ * caller reads them unconditionally instead of guarding on them.
+ *
+ * BOTH ARE DATA ON A SUCCESSFUL RESULT -- never an error, never a refusal, and
+ * there is no option to make either one. For `contradictedComments` see the
+ * module header's trap 9: a refusal would push a caller toward deleting the
+ * comment to get the retype through, which converts a REPORTED loss into a
+ * SILENT one. `reinterpretedSplitTables` rides alongside it for the same reason
+ * and by the same pattern.
+ *
+ * `reinterpretedSplitTables` carries one record per OVERLAPPED SPLIT ROW that
+ * the accepted write fragmented -- the row's identity and span, the entry-address
+ * pairs it read before, every surviving remainder's span and the pairs it reads
+ * now, and the pairs PRESERVED (computed by comparing the two sets). It is empty
+ * whenever the write fragmented no split row: a non-split overlap, a full cover,
+ * an identical repeat. Its array order is ASCENDING OVERLAPPED-ROW ID, matching
+ * the gate's own `order by id`; within a record the survivors are ordered HEAD
+ * then TAIL. See `retype()`'s DECISION 1 for why this is a RETURN CHANNEL rather
+ * than an on-disk column.
+ */
+export interface SetDataTypeResult extends AnnoWriteResult {
+  contradictedComments: readonly ContradictedComment[];
+  reinterpretedSplitTables: readonly SplitTableReinterpretation[];
+}
+
+/**
+ * Types the inclusive range `start..endInclusive` as `dataType`, preserving
+ * whatever the overlapping rows said about the addresses outside it.
+ *
+ * Every argument is validated before any SQL runs -- the transport validates
+ * nothing (see `anno-types.ts`'s header).
+ */
+export function setDataType(
+  handle: AnnoStoreHandle,
+  args: { start: number | string; endInclusive: number | string; dataType: unknown; baseRevision?: number },
+): SetDataTypeResult {
+  const dataType = assertDataType(args.dataType);
+  // ORDERING IS LOAD-BEARING: `parseStoreAddress` owns the STRING forms only
+  // -- what base is this text in, and is it a form the store accepts at all --
+  // while `assertRangeShape` owns range-ness for both forms. A numeric
+  // argument is therefore passed straight through, so an end of 65536 or -1 is
+  // refused as a RANGE SHAPE rather than as an unparseable address. Collapsing
+  // the two makes a caller unable to tell "that is not an address" from "those
+  // two ends do not make a range".
+  const start = typeof args.start === "string" ? parseStoreAddress(args.start, { what: "start" }) : args.start;
+  const endInclusive = typeof args.endInclusive === "string" ? parseStoreAddress(args.endInclusive, { what: "endInclusive" }) : args.endInclusive;
+  assertRangeShape(start, endInclusive, dataType);
+
+  const { revision, result } = applyWrite(
+    handle,
+    (db) => {
+      // The query precedes the mutation and shares its transaction: the rows it
+      // reads are the ones the retype is about to contradict, and no concurrent
+      // writer can slip a comment in between the two.
+      const contradictedComments = collectContradictedComments(db, start, endInclusive, dataType);
+      const { changed, reinterpretedSplitTables } = retype(db, start, endInclusive, dataType);
+      return { changed, contradictedComments, reinterpretedSplitTables };
+    },
+    { baseRevision: args.baseRevision },
+  );
+  return {
+    revision,
+    changed: result.changed,
+    contradictedComments: result.contradictedComments,
+    reinterpretedSplitTables: result.reinterpretedSplitTables,
+  };
+}
+
+/** Every typed range, in insertion order. The `bank` column is read HERE and
+ * nowhere else in this module. */
+export function listRanges(handle: AnnoStoreHandle): RangeRow[] {
+  const rows = handle.db.prepare("select id, start, end_inclusive, data_type, bank from anno_range order by id").all() as {
+    id: number;
+    start: number;
+    end_inclusive: number;
+    data_type: string;
+    bank: number | null;
+  }[];
+  return rows.map((row) => ({
+    id: row.id,
+    start: row.start,
+    endInclusive: row.end_inclusive,
+    dataType: row.data_type as DataType,
+    bank: row.bank,
+  }));
+}
+
+/**
+ * Restores the whole store to the state it had at `revision`, by replacing the
+ * store file with that revision's snapshot. Whole-store restore rather than an
+ * inverted changeset because the changeset INVERSION primitive is the one part
+ * of `node:sqlite`'s session surface that is missing (see the third measured
+ * fact in the header).
+ *
+ * The replacement is atomic from a reader's point of view: the snapshot is
+ * copied to a staging file beside the store, both the file and its directory
+ * are fsynced, and only then is the staging file renamed over the store path.
+ * Returns a NEW handle -- the old one is closed and must not be reused.
+ *
+ * ON THE REFUSAL PATH AND ON A STAGING FAILURE THE CALLER'S HANDLE IS STILL
+ * OPEN. `revertTo` refuses an unretained revision before it touches the
+ * filesystem, and it stages and fsyncs the copy before it closes anything. The
+ * steps are numbered in the body and each number's POSITION is commented,
+ * because the ordering is the guarantee.
+ *
+ * THE REFUSAL SET HAS THREE ARMS, and all three are `AnnoStoreError`:
+ *   * NO POINTER ROW claims the revision (step 2, first arm) -- "no snapshot is
+ *     retained for it", with the oldest retained revision, the bound and the
+ *     available list.
+ *   * A ROW CLAIMS IT BUT ITS IMAGE WILL NOT OPEN as an annotation store (step
+ *     2, second arm) -- the arm CR-08 added, covering an absent image and a
+ *     present-but-unusable one alike, with the underlying reason quoted so the
+ *     caller can tell which. This is the arm the old presence-only gate did not
+ *     have, and its absence is what let the store be destroyed installing an
+ *     image that was not a database.
+ *   * THE STAGED COPY WILL NOT OPEN (step 3b) -- the same witness in its third
+ *     position, on the exact bytes step 5 renames.
+ *
+ * AND THE ORDERING RULE IS NOW STATED IN FULL, because "stages and fsyncs the
+ * copy before it closes anything" was the whole of it and it was not enough.
+ * NOTHING IS CLOSED AND NOTHING IS RENAMED UNTIL THE STAGED IMAGE HAS BEEN
+ * OPENED AS AN ANNOTATION STORE THIS BUILD CAN SPEAK TO. Step 3b sits between
+ * the staging and the close and does exactly that, and it is the step the whole
+ * guarantee now rests on: presence was the only witness before it, and presence
+ * proves nothing (a ZERO-LENGTH FILE OPENS -- the module header's first measured
+ * fact). Reproduced before step 3b existed: a 0-byte retained snapshot took the
+ * live 69,632-byte store to 0 bytes, returned no handle at all, and made every
+ * later `openStore` refuse. The sentence above about the refusal path and the
+ * staging failure stays exactly true; step 3b widens the set of failures it
+ * covers rather than qualifying it.
+ */
+/**
+ * The one gate on a revision-shaped argument, and it exists because ONE
+ * unvalidated value lands in TWO places that can then disagree (WR-22): a bound
+ * SQL parameter, and a snapshot FILENAME.
+ *
+ * Accepts a non-negative safe integer and nothing else. A numeric STRING is
+ * refused ON PURPOSE rather than coerced: SQLite applies the pointer column's
+ * INTEGER affinity to a bound TEXT operand, so `"0001"` MATCHES revision 1's
+ * row -- while `snapshotPathFor` builds `r0001.db` from the string. Coercing
+ * would hide the caller's mistake; matching-then-failing reports it as a damaged
+ * ring, which is the confusion `AnnoRevisionArgumentError`'s doc comment records
+ * in full.
+ *
+ * DELIBERATELY NOT REUSED FOR `baseRevision`. The round-5 review's WR-22 sketch
+ * suggests it; that is WR-06, which the round-5 verification does not route to
+ * this round, so the declination is recorded here rather than left looking like
+ * an omission -- `runWriteSequence`'s existing `baseRevision` staleness refusal
+ * is this validator's SIBLING, not its client.
+ */
+function assertRevisionArgument(value: unknown, parameter: string): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    // `JSON.stringify` is the right rendering for every value EXCEPT the three
+    // numbers JSON cannot represent: it turns `NaN` and both infinities into the
+    // string `null`, which would name a value the caller never passed -- the
+    // opposite of the verbatim naming this refusal exists to provide.
+    const shown = typeof value === "number" && !Number.isFinite(value) ? String(value) : JSON.stringify(value);
+    throw new AnnoRevisionArgumentError(
+      `${parameter} ${shown} is not a revision -- expected a non-negative integer. A numeric STRING is refused on ` +
+        `purpose rather than coerced: SQLite's column affinity would match the pointer row while the snapshot FILENAME is built from ` +
+        `the string, so the two would disagree about which revision is being reverted to. Nothing has been read and nothing has been ` +
+        `written.`,
+      { value, parameter },
+    );
+  }
+  return value;
+}
+
+export function revertTo(handle: AnnoStoreHandle, revision: number): AnnoStoreHandle {
+  // STEP 0, AND IT IS FIRST FOR THE REASON WR-22 RECORDS: this argument reaches
+  // a bound SQL parameter AND a filename, so it is judged before either exists.
+  // Before this line, `revertTo(handle, "1")` silently reverted the store and
+  // `revertTo(handle, "0001")` refused with CR-08's CORRUPTION message.
+  assertRevisionArgument(revision, "revision");
+
+  // STEP 1. The pointer row -- the INDEX half of "retained". An EXISTENCE check
+  // and nothing more: the row carries only its revision number, and the FILE's
+  // location is computed below from the handle rather than read from the row
+  // (see `retainedRevisions` for why a persisted path was removed).
+  const pointer = handle.db.prepare("select revision from anno_snapshot where revision = ?").get(revision) as
+    | { revision: number }
+    | undefined;
+  const snapPath = snapshotPathFor(handle, revision);
+
+  // STEP 2, AND ITS POSITION IS THE WHOLE POINT: refuse BEFORE anything is
+  // destroyed. It has TWO ARMS, and both of them are before any filesystem
+  // mutation, so both leave the caller's handle open and the store untouched.
+  //
+  // THE FILE HALF NOW READS `snapshotOpenFailure` -- the same witness
+  // `retainedRevisions` reads, in its other position. It used to read
+  // `existsSync` and nothing more, which is CR-08: a present image that was not
+  // a database passed this gate, and the store was destroyed installing it. The
+  // "oldest retained" and "available revisions" figures are built from
+  // `retainedRevisions()` and never from the raw rows, so a refusal cannot
+  // steer the caller at a revision the very next call would also refuse.
+  //
+  // THE ARMS SPLIT ON THE ROW, NOT ON THE FILE'S PRESENCE, and that is
+  // deliberate rather than an omission. Asking "is the image absent" separately
+  // from "does the image open" would put a SECOND predicate back on a snapshot
+  // path -- a second truth about one file, which is how CR-03 and CR-08 both
+  // happened. The two file-half sub-cases are distinguished by the QUOTED
+  // REASON instead: an absent image quotes "the file does not exist", a corrupt
+  // one quotes what SQLite or `openStore` said. One witness, one message, and
+  // the caller can still tell them apart.
+  if (!pointer) {
+    const available = retainedRevisions(handle);
+    const oldest = available.length === 0 ? NO_RETAINED_REVISION : available[0];
+    throw new AnnoStoreError(
+      `cannot revert to revision ${revision}: no snapshot is retained for it. The oldest retained revision is ` +
+        `${oldest === NO_RETAINED_REVISION ? "(none -- the ring is empty)" : oldest} and the current revision is ${currentRevision(handle)}; ` +
+        `the ring holds at most ${MAX_SNAPSHOT_REVISIONS} revisions. The request is REFUSED rather than substituting the nearest retained ` +
+        `revision, because returning a revision other than the one asked for changes the caller's intent with nothing recording that it ` +
+        `happened. Available revisions: ${available.length === 0 ? "(none)" : available.join(", ")}`,
+      { data: { path: handle.path, revision } },
+    );
+  }
+
+  const openFailure = snapshotOpenFailure(handle, revision);
+  if (openFailure !== null) {
+    const available = retainedRevisions(handle);
+    throw new AnnoStoreError(
+      `cannot revert to revision ${revision}: a pointer row claims it, but its snapshot ${snapPath} is not a readable annotation store ` +
+        `(${openFailure}). Presence was never the witness -- a ZERO-LENGTH FILE OPENS as a SQLite database and reports integrity_check ` +
+        `ok -- so the image is OPENED before anything is replaced, and this one did not open. NOTHING has been replaced: ${handle.path} is ` +
+        `still at revision ${currentRevision(handle)} and this handle is still open and usable. The snapshot is left on disk for ` +
+        `inspection rather than unlinked, because a corrupt image a pointer row still claims is EVIDENCE. Available revisions: ` +
+        `${available.length === 0 ? "(none)" : available.join(", ")}`,
+      { data: { path: handle.path, snapshotPath: snapPath, operation: "validate", revision } },
+    );
+  }
+
+  const storePath = handle.path;
+  const dir = handle.dir;
+  // THE STAGING NAME IS UNIQUE PER ATTEMPT, NOT PER (PID, REVISION) (WR-24),
+  // and it is built from `randomUUID` -- the SAME primitive `stageSnapshot`
+  // uses, so there is ONE answer in this module to "how is a staging name made
+  // unique" rather than two that can drift. `stageSnapshot`'s own doc comment
+  // states the rule in capitals and states why: a revision number can recur
+  // after a revert, and two attempts at the same revision -- in this process or
+  // another -- must not share a path. That sentence was never applied here.
+  //
+  // THE TWO FAILURE MODES THIS CLOSES, named rather than implied. (1) A second
+  // attempt at the same revision copies over the first attempt's staged bytes
+  // BETWEEN that attempt's step-3b validation and its step-5 rename, so the
+  // image judged is not the image installed -- the exact window step 3b exists
+  // to remove. (2) Any of the three cleanups below removes another attempt's
+  // IN-FLIGHT file, because under the old name all attempts at one revision
+  // addressed the same path.
+  //
+  // AND WHAT IT DOES NOT CLOSE, stated because a comment that implied otherwise
+  // would be prohibition 28-07 P3's exact shape: THE LEAK HALF STAYS OPEN UNDER
+  // WR-11. A process killed between the copy and any of the three cleanups
+  // still leaves this file behind, and it sits beside the store rather than
+  // inside the ring directory, so `reconcileSnapshotRing`'s sweep -- anchored on
+  // `r<digits>.db` inside `snapshotDirFor()` -- does not and must not match it.
+  // Nothing reclaims it. That is WR-11's other half and it is not closed here.
+  //
+  // THE PID IS KEPT deliberately: it is the diagnostic that lets a human finding
+  // a leaked file say which process produced it, and the `.revert-` marker is
+  // kept for the same reason -- uniqueness was the defect, not the labelling.
+  const staging = `${storePath}.revert-${process.pid}.${randomUUID()}.tmp`;
+
+  // STEP 3. Stage and fsync the copy WITH THE CONNECTION STILL OPEN. Every
+  // failure reachable here -- `ENOENT`, `ENOSPC`, `EACCES` -- therefore leaves
+  // the caller a USABLE handle: nothing has been replaced yet, so
+  // `currentRevision(handle)` and `listRanges(handle)` still answer and the
+  // caller can decide what to do. That is WR-02's entire complaint, and it is
+  // fixed by ordering rather than by a rescue path.
+  try {
+    copyFileSync(snapPath, staging);
+    fsyncPath(staging);
+    fsyncPath(dir);
+  } catch (e) {
+    discardSnapshot(staging);
+    throw new AnnoStoreError(
+      `cannot revert ${storePath} to revision ${revision}: staging the snapshot ${snapPath} failed during copy/fsync ` +
+        `(${(e as Error).message}). Nothing has been replaced and the store connection is deliberately still OPEN and usable.`,
+      { data: { path: storePath, snapshotPath: snapPath, operation: "copy/fsync", revision } },
+    );
+  }
+
+  // STEP 3b, AND ITS POSITION IS THE GUARANTEE (CR-08). OPEN THE STAGED IMAGE
+  // BEFORE ANYTHING IS CLOSED AND BEFORE ANYTHING IS RENAMED. Until this step
+  // existed the only witness that the image about to be installed was a store at
+  // all was `existsSync` -- and this module's own FIRST MEASURED FACT (see the
+  // header, `:22-31`) is that a ZERO-LENGTH FILE OPENS as a SQLite database and
+  // reports `integrity_check ok`, so presence proves nothing and the refusal has
+  // to be the store's OWN job. That reasoning was applied to `openStore` and
+  // never applied to the image `revertTo` installs, which is exactly the gap: a
+  // 0-byte retained snapshot took the live store from 69,632 bytes to 0, with no
+  // handle returned and no route back, because the bytes destroyed are the only
+  // copy of the CURRENT revision -- `revertTo` refuses the current revision by
+  // design, precisely because no snapshot records it.
+  //
+  // THE STAGED COPY AND NOT ONLY THE SOURCE IMAGE, and the difference is a
+  // window rather than a nicety: the staged file is the exact bytes step 5
+  // renames over the store, so judging it is what leaves no interval in which
+  // the judged bytes and the installed bytes can differ. Step 2's gate on the
+  // SOURCE image is the same witness in its other position -- one witness, two
+  // positions, not two witnesses.
+  //
+  // A FAILURE HERE COSTS THE CALLER NOTHING. The connection is still open, so
+  // `currentRevision(handle)` and `listRanges(handle)` still answer; the live
+  // store has not been touched; and the snapshot is left on disk for inspection
+  // rather than unlinked, because a corrupt image a pointer row still claims is
+  // EVIDENCE.
+  try {
+    // MODULE-DERIVED PATH: `staging`, the per-attempt staging name this function
+    // built next to the store it is reverting. `mustExist` is unchanged.
+    closeStore(openStore(staging, { mustExist: true, unconfinedModuleDerivedPath: true }));
+  } catch (e) {
+    discardSnapshot(staging);
+    throw new AnnoStoreError(
+      `cannot revert ${storePath} to revision ${revision}: the retained snapshot ${snapPath} is not a readable annotation store ` +
+        `(${(e as Error).message}). NOTHING has been replaced -- the store is still at revision ${currentRevision(handle)} and this ` +
+        `handle is still open and usable. The snapshot is left on disk for inspection.`,
+      { data: { path: storePath, snapshotPath: snapPath, operation: "validate", revision } },
+    );
+  }
+
+  // STEP 4. Only now, with a durable staged image beside the store that has been
+  // OPENED as an annotation store this build can speak to.
+  closeStore(handle);
+
+  // STEP 5. The rename is the ONE step that cannot be done with the connection
+  // open, so the residual is stated rather than claimed closed: a failure HERE
+  // does leave the caller without a handle. The staging file is removed so a
+  // retry is not blocked by its own leftovers, and the error names the
+  // operation so the caller can tell this case from step 3's.
+  try {
+    renameSync(staging, storePath);
+    fsyncPath(dir);
+  } catch (e) {
+    discardSnapshot(staging);
+    throw new AnnoStoreError(
+      `cannot revert ${storePath} to revision ${revision}: renaming the staged snapshot over the store failed ` +
+        `(${(e as Error).message}). The store connection was already closed for the rename -- that is the one residual this path ` +
+        `cannot remove, because the rename cannot be done with the connection open -- so reopen the store to inspect it.`,
+      { data: { path: storePath, snapshotPath: snapPath, operation: "rename", revision } },
+    );
+  }
+
+  // STEP 6. Reconcile the RESTORED ring before the handle leaves this
+  // function. The image just restored carries `anno_snapshot` rows for
+  // revisions whose files an earlier prune removed, and it leaves every
+  // snapshot taken AFTER `revision` unclaimed by any row. ONLY THE FILE HALF IS
+  // RESOLVED HERE, and the ROW half is deliberately left: since CR-05 the sweep
+  // abstains from the pointer-row direction entirely, because it cannot
+  // establish ownership of a row under a second spelling of the store file, so
+  // the restored image's stale rows are TOLERATED rather than deleted. This
+  // sentence previously claimed BOTH halves were resolved here -- the reversal
+  // is RECORDED RATHER THAN QUIETLY REWRITTEN, because a rationale that became
+  // false is evidence; the falsified sentence itself is not repeated verbatim,
+  // because the next reader greps this file for the guarantee it asserts, not
+  // for its refutation.
+  // The handle this function hands back still never advertises a revision it
+  // cannot deliver, and that does not depend on the sweep at all: the published
+  // floor routes through `retainedRevisions`, which requires BOTH halves of a
+  // revision's record regardless of whether either half was ever swept.
+  //
+  // The directory bound is the OTHER clause of the original sentence, and it
+  // was already qualified once for a different reason -- that qualification is
+  // still exactly true and is extended, not replaced. It
+  // previously ended "and the directory bound holds after a revert as well as
+  // before one", which is now an over-claim: `reconcileSnapshotRing` takes the
+  // store's write lock before it judges, and under contention it DECLINES and
+  // reports `deferred`, handing back a ring it did not reconcile.
+  //
+  //   * THE FIRST CLAUSE SURVIVES UNCHANGED, and is not weakened: the handle
+  //     still never advertises a revision it cannot deliver, because the
+  //     published floor routes through `retainedRevisions`, which requires BOTH
+  //     halves of a revision's record regardless of whether the sweep ran.
+  //   * THE SECOND CLAUSE IS CONDITIONAL. The directory bound holds after a
+  //     revert as well as before one unless the sweep deferred, in which case
+  //     the restored ring stays over-full until the next accepted write sweeps
+  //     it -- extra FILES, the harmless direction, reported rather than silent.
+  //
+  // AND THIS IS THE SECOND OF THE TWO BLOCKING SITES. Under contention the
+  // sweep below can itself stall for up to the connection's five-second
+  // `busy_timeout` before `revertTo` returns.
+  //
+  // CR-07's THIRD PROPERTY: THE SWEEP IS HOUSEKEEPING AND MUST NEVER COST THE
+  // CALLER A HANDLE. By this line the revert has ALREADY SUCCEEDED ON DISK --
+  // step 5's rename and directory fsync have returned, so the store file at
+  // `storePath` IS the reverted image whatever happens next. Round 3 observed
+  // this exact line throw a bare, non-family `Error: EACCES` from
+  // `readdirSync` on an unreadable ring directory AFTER a successful
+  // `rev 4 -> rev 2`: the caller got no handle at all for a revert that had
+  // landed, and the connection opened one statement above was left with nothing
+  // able to close it.
+  //
+  // THE HANDLER CLOSES AND REOPENS RATHER THAN RETURNING `restored`, and that
+  // is deliberate, not defensive noise. If the sweep threw, that connection's
+  // transaction state is UNKNOWN -- handing back a connection that may still
+  // hold the store's write lock is the defect being closed, not a repair of it.
+  // The reopen routes through `openStore`, which is already inside the
+  // `ViceError` family, so a genuine failure to reopen refuses BY NAME rather
+  // than escaping as a bare error. The inner `try` around `closeStore` swallows
+  // for the same reason every other inner rollback in this module does: there
+  // is nothing useful to do with a second error while unwinding the first.
+  //
+  // STATED HONESTLY: AFTER PLAN 28-13 THIS `catch` IS NOT REACHABLE FROM ANY
+  // INPUT. That plan bracketed `reconcileSnapshotRing`'s whole body in a handler
+  // that rolls back and returns `{ droppedFiles: [], deferred: true }` without
+  // rethrowing, so no reachable input makes the sweep throw. This handler is
+  // therefore DEFENCE IN DEPTH against a future edit that reintroduces a throw
+  // -- not a currently reachable arm -- and `anno-store.test.ts` says the same
+  // thing in both of its controls rather than letting a green test imply a
+  // behavioural proof it does not carry.
+  //
+  // AND THE REOPEN IS NOW INSIDE THE SAME GUARANTEE (WR-17), WHICH IS WHERE IT
+  // BELONGED. The sentence above -- "a housekeeping failure never costs the
+  // caller a handle" -- used to hold only for the branch that CANNOT fire. The
+  // sweep call was guarded and is unreachable; the two `openStore` calls were
+  // NOT guarded and are by far the likelier to throw, because each one runs the
+  // `anno_meta` read, the `schema_version` comparison and `pragma
+  // integrity_check` against the image this function has just installed. Round
+  // 4 reproduced exactly that: a bad snapshot made the reopen throw, the
+  // caller's original handle had been closed at step 4, and `revertTo` returned
+  // nothing at all.
+  //
+  // ITS INTERACTION WITH STEP 3b, STATED BECAUSE IT NARROWS THE CLAIM RATHER
+  // THAN CLOSING IT. Step 3b now opens the staged image BEFORE the rename, so
+  // the reopen's most likely failure -- the image is not a store -- cannot reach
+  // this line at all. What is left is a store that became unopenable BETWEEN the
+  // rename and the reopen: another process truncating it, a device error, a
+  // permission change. This handler covers that remainder.
+  //
+  // AND IT MUST REPORT A LANDED REVERT, NEVER A FAILED ONE (prohibition
+  // 28-11 P5). By this line step 5's rename and directory fsync have returned,
+  // so the file at `storePath` IS the reverted image whatever happens next.
+  // Presenting that as a failed revert would convert a committed write into a
+  // caller-visible failure and send the caller looking for a revert that
+  // already happened. A `ViceError` is rethrown UNCHANGED -- it is already
+  // named, already carries the path, and re-wrapping it would bury the reason
+  // one layer deeper; anything else is wrapped so no route out of step 6
+  // reaches the caller as a bare OS error.
+  let restored: AnnoStoreHandle;
+  try {
+    // MODULE-DERIVED PATH: `storePath` is `handle.path`, already confined by the
+    // open that produced the caller's handle.
+    restored = openStore(storePath, { unconfinedModuleDerivedPath: true });
+  } catch (e) {
+    if (e instanceof ViceError) throw e;
+    throw new AnnoStoreError(
+      `the revert of ${storePath} to revision ${revision} LANDED ON DISK, but reopening the store afterwards failed ` +
+        `(${(e as Error).message}). The revert is NOT undone and must not be retried as though it had failed: the file at ${storePath} ` +
+        `IS the restored image, so reopen it with openStore to inspect it.`,
+      { data: { path: storePath, revision, step: "reopen after revert" } },
+    );
+  }
+  //
+  // AND THE SWEEP'S RESULT IS BOUND RATHER THAN DISCARDED (WR-18), WHICH IS THE
+  // ARM THE `catch` ABOVE CANNOT SEE. `reconcileSnapshotRing` does not throw
+  // when its own `rollback` fails -- rethrowing there is forbidden by 28-11 P5,
+  // because on this very call site it would convert a LANDED revert into a
+  // caller-visible failure -- so it REPORTS the fact in `rollbackFailed`
+  // instead. Reaching that state WITHOUT a throw is exactly why the existing
+  // catch arm alone was not enough: `revertTo` would hand back a connection that
+  // may still hold the store's write lock, which is CR-07's reported symptom
+  // re-created on the revert path.
+  //
+  // THE REMEDY IS THE SAME BLOCK, REUSED RATHER THAN COPIED: close the
+  // connection whose transaction state is unknown and hand back a freshly opened
+  // one. `revertTo` must not return a handle it cannot vouch for, and a second
+  // copy of the remedy is a second place it can drift.
+  let reopenNeeded: boolean;
+  try {
+    reopenNeeded = reconcileSnapshotRing(restored).rollbackFailed;
+  } catch {
+    reopenNeeded = true;
+  }
+  if (reopenNeeded) {
+    try {
+      closeStore(restored);
+    } catch {
+      // deliberately ignored -- see above
+    }
+    try {
+      // MODULE-DERIVED PATH: `storePath` is `handle.path`, as above.
+      return openStore(storePath, { unconfinedModuleDerivedPath: true });
+    } catch (e) {
+      if (e instanceof ViceError) throw e;
+      throw new AnnoStoreError(
+        `the revert of ${storePath} to revision ${revision} LANDED ON DISK, but reopening the store after a failed ring reconciliation ` +
+          `failed too (${(e as Error).message}). The revert is NOT undone: the file at ${storePath} IS the restored image, so reopen it ` +
+          `with openStore to inspect it.`,
+        { data: { path: storePath, revision, step: "reopen after revert" } },
+      );
+    }
+  }
+  return restored;
+}
+
+/** The paint index over this store's current rows, rebuilt from the rows every
+ * time (`anno-index.ts` traps 2 and 4). A convenience over
+ * `buildPaintIndex(listRanges(handle))` -- it holds nothing between calls. */
+export function paintIndexOf(handle: AnnoStoreHandle): PaintIndex {
+  return buildPaintIndex(listRanges(handle));
+}
+
+// ---------------------------------------------------------------------------
+// The five annotation kinds: labels, comments, scopes, project enums and
+// cross-references. Every entry point below VALIDATES FIRST and only then goes
+// through `applyWrite`, so no SQL runs on an unvalidated argument. Every
+// statement is `prepare().run()` with bound parameters -- `exec()` stays
+// restricted to the fixed `DDL`, the transaction keywords and the one escaped
+// `vacuum into` (trap 3).
+// ---------------------------------------------------------------------------
+
+/**
+ * Binds `name` to `address` with label kind `kind`.
+ *
+ * THE COLLISION IS REFUSED, NEVER RESOLVED. A name already bound to a
+ * DIFFERENT address throws `AnnoLabelError` naming the name and both addresses.
+ * It is not rebound, not suffixed and not sanitised: see `anno-types.ts` trap 7
+ * for the hazard, which is that any of those silently merges or moves a name a
+ * human deliberately chose, with nothing recording that it happened.
+ *
+ * The DDL's `unique(name)` constraint is a SECOND LINE OF DEFENCE and is
+ * deliberately not the observable refusal. The named error is thrown first, from
+ * inside the mutation's own transaction so a concurrent writer cannot bind the
+ * name between the read and the insert; the constraint only catches a path that
+ * bypassed this function entirely.
+ *
+ * The name-versus-name comparison is EXACT BYTE EQUALITY -- the SQL `=` on a
+ * text column with the default (binary) collation, matching the definition
+ * `assertLegalLabel()`'s doc comment states. No case folding, no Unicode
+ * normalisation, no trimming.
+ */
+export function setLabel(
+  handle: AnnoStoreHandle,
+  args: { address: number | string; name: unknown; kind: unknown; baseRevision?: number },
+): AnnoWriteResult {
+  const address = parseStoreAddress(args.address, { what: "address" });
+  const name = assertLegalLabel(args.name);
+  const kind: LabelKind = assertLabelKind(args.kind);
+
+  const { revision, result } = applyWrite(
+    handle,
+    (db) => {
+      const existing = db.prepare("select id, address, kind from anno_label where name = ?").get(name) as
+        | { id: number; address: number; kind: string }
+        | undefined;
+
+      if (existing && existing.address !== address) {
+        throw new AnnoLabelError(
+          `label name ${JSON.stringify(name)} is already bound to address ${existing.address} ` +
+            `($${existing.address.toString(16).padStart(4, "0")}) and cannot also name address ${address} ` +
+            `($${address.toString(16).padStart(4, "0")}) -- the write is REFUSED rather than rebinding the name or inventing a variant of it, ` +
+            `because either would silently merge or move a name somebody chose on purpose`,
+          { identifier: name, reason: "name already bound to a different address", existingAddress: existing.address, requestedAddress: address },
+        );
+      }
+
+      if (existing) {
+        if (existing.kind === kind) return false;
+        db.prepare("update anno_label set kind = ? where id = ?").run(kind, existing.id);
+        return true;
+      }
+
+      db.prepare("insert into anno_label(address, name, kind, bank) values (?, ?, ?, ?)").run(address, name, kind, null);
+      return true;
+    },
+    { baseRevision: args.baseRevision },
+  );
+  return { revision, changed: result };
+}
+
+/** Every label, in ascending `id` order. One of the row mappers that read the
+ * reserved `bank` column -- see `listRanges()` for why nothing else may. */
+export function listLabels(handle: AnnoStoreHandle): LabelRow[] {
+  const rows = handle.db.prepare("select id, address, name, kind, bank from anno_label order by id").all() as {
+    id: number;
+    address: number;
+    name: string;
+    kind: string;
+    bank: number | null;
+  }[];
+  return rows.map((row) => ({
+    id: row.id,
+    address: row.address,
+    name: row.name,
+    kind: row.kind as LabelKind,
+    bank: row.bank,
+  }));
+}
+
+/**
+ * Stores `text` as the `commentType` comment at `address`, replacing whatever
+ * was there. One comment per `(address, comment_type)` pair -- the DDL's own
+ * unique constraint -- so the two placements coexist at one address and a
+ * repeated write of the same placement replaces rather than accumulates.
+ *
+ * A byte-identical repeat reports `changed:false`: it is accepted, not refused,
+ * and the revision still advances (see `AnnoWriteResult`).
+ */
+export function setComment(
+  handle: AnnoStoreHandle,
+  args: { address: number | string; commentType: unknown; text: unknown; baseRevision?: number },
+): AnnoWriteResult {
+  const address = parseStoreAddress(args.address, { what: "address" });
+  const commentType: CommentType = assertCommentType(args.commentType);
+  const text = assertCommentText(args.text);
+
+  const { revision, result } = applyWrite(
+    handle,
+    (db) => {
+      const existing = db.prepare("select id, text from anno_comment where address = ? and comment_type = ?").get(address, commentType) as
+        | { id: number; text: string }
+        | undefined;
+
+      if (existing) {
+        if (existing.text === text) return false;
+        db.prepare("update anno_comment set text = ? where id = ?").run(text, existing.id);
+        return true;
+      }
+
+      db.prepare("insert into anno_comment(address, comment_type, text, bank) values (?, ?, ?, ?)").run(address, commentType, text, null);
+      return true;
+    },
+    { baseRevision: args.baseRevision },
+  );
+  return { revision, changed: result };
+}
+
+/** Every comment, in ascending `id` order. Reads the reserved `bank` column. */
+export function listComments(handle: AnnoStoreHandle): CommentRow[] {
+  const rows = handle.db.prepare("select id, address, comment_type, text, bank from anno_comment order by id").all() as {
+    id: number;
+    address: number;
+    comment_type: string;
+    text: string;
+    bank: number | null;
+  }[];
+  return rows.map((row) => ({
+    id: row.id,
+    address: row.address,
+    commentType: row.comment_type as CommentType,
+    text: row.text,
+    bank: row.bank,
+  }));
+}
+
+/**
+ * Adds a lexical scope over the inclusive range `start..endInclusive`.
+ *
+ * NO NESTING, and that is a faithful mirror rather than a shortcut: the schema
+ * this store mirrors says in as many words that nested scopes are not supported
+ * (`anno-tools.ts:320-324`). Inventing nesting here would create annotations no
+ * exporter downstream can express.
+ *
+ * The shape check passes a NON-SPLIT data type on purpose. `assertRangeShape()`
+ * carries the split-table even-count rule, and a scope is not a table -- a
+ * three-byte routine is a perfectly good scope. Passing `"byte"` selects the
+ * two rules that do apply (both ends inside the address space; the end not below
+ * the start) and none of the ones that do not.
+ *
+ * ENFORCED, as of 28-21, by the overlap refusal below: a scope that is nested
+ * inside, contains, or partially overlaps an existing scope is REFUSED with an
+ * `AnnoRangeShapeError` naming BOTH scopes -- the incoming one's two ends and
+ * the existing one's id and two ends. Before that refusal existed this comment
+ * and `ScopeRow`'s made a claim the code did not honour, which is exactly the
+ * shape prohibition 28-07 P3 forbids. Adjacency is NOT overlap: two scopes that
+ * merely touch at a boundary are two scopes, consistent with STORE-02's
+ * treatment of ranges.
+ *
+ * A BYTE-IDENTICAL REPEAT IS AN ACCEPTED NO-OP reporting `changed: false`, and
+ * this REVERSES a decision recorded here in as many words. The deleted
+ * paragraph read "ADDITIVE, matching the verb's own name in the schema
+ * (`add_scope`): two identical calls produce two rows [...] collapsing
+ * duplicates here would be this module inventing a policy the surface does not
+ * have." That reading is rejected on two grounds it could not see. First,
+ * `AnnoWriteResult`'s own doc comment states that `changed` is the ONLY signal
+ * distinguishing a no-op from a real edit -- and for scopes it could never say
+ * no-op, so the module already had the policy and simply could not express it
+ * here. Second, Phase 29's success criterion 5 requires a repeated edit to
+ * SUCCEED reporting no change, so the surface this store mirrors does have the
+ * policy after all. The repeat is therefore accepted rather than refused, and
+ * the revision still advances by one, exactly like every other write entry
+ * point in this module.
+ */
+export function addScope(
+  handle: AnnoStoreHandle,
+  args: { start: number | string; endInclusive: number | string; baseRevision?: number },
+): AnnoWriteResult {
+  const start = parseStoreAddress(args.start, { what: "start" });
+  const endInclusive = parseStoreAddress(args.endInclusive, { what: "endInclusive" });
+  assertRangeShape(start, endInclusive, "byte");
+
+  const { revision, result } = applyWrite(
+    handle,
+    (db) => {
+      // IDEMPOTENCE FIRST, in the same shape `setLabel` and `setComment` use:
+      // read the existing row inside the transaction and return `false`. It has
+      // to run before the overlap check, because a byte-identical scope
+      // overlaps itself and would otherwise be refused rather than accepted as
+      // the no-op Phase 29's criterion 5 requires.
+      const identical = db.prepare("select id from anno_scope where start = ? and end_inclusive = ?").get(start, endInclusive) as
+        | { id: number }
+        | undefined;
+      if (identical) return false;
+
+      // TWO RANGES OVERLAP IFF each starts at or before the other ends.
+      // ADJACENCY FALLS OUT OF THE `>=`: an existing scope ending at exactly
+      // `start - 1` fails `end_inclusive >= start`, so touching is not
+      // overlapping. `order by id limit 1` reports the FIRST conflicting row
+      // rather than an arbitrary one, so the message is reproducible.
+      const overlapper = db
+        .prepare("select id, start, end_inclusive from anno_scope where start <= ? and end_inclusive >= ? order by id limit 1")
+        .get(endInclusive, start) as { id: number; start: number; end_inclusive: number } | undefined;
+      if (overlapper) {
+        throw new AnnoRangeShapeError(
+          `scope ${start}..${endInclusive} ($${start.toString(16).padStart(4, "0")}..$${endInclusive.toString(16).padStart(4, "0")}) ` +
+            `overlaps the existing scope id=${overlapper.id} ${overlapper.start}..${overlapper.end_inclusive} ` +
+            `($${overlapper.start.toString(16).padStart(4, "0")}..$${overlapper.end_inclusive.toString(16).padStart(4, "0")}) -- ` +
+            `nested and overlapping scopes are UNSUPPORTED by the schema this store mirrors, so the write is REFUSED rather than stored ` +
+            `as a shape nothing downstream can express. The incoming scope is NOT trimmed and NOT split: supply a range disjoint from ` +
+            `every existing scope. Two scopes that merely TOUCH at a boundary are disjoint and both accepted.`,
+          { start, endInclusive },
+        );
+      }
+
+      db.prepare("insert into anno_scope(start, end_inclusive) values (?, ?)").run(start, endInclusive);
+      return true;
+    },
+    { baseRevision: args.baseRevision },
+  );
+  return { revision, changed: result };
+}
+
+/** Every scope, in ascending `id` order. `anno_scope` has no `bank` column --
+ * a scope is a lexical region, not a memory view. */
+export function listScopes(handle: AnnoStoreHandle): ScopeRow[] {
+  const rows = handle.db.prepare("select id, start, end_inclusive from anno_scope order by id").all() as {
+    id: number;
+    start: number;
+    end_inclusive: number;
+  }[];
+  return rows.map((row) => ({ id: row.id, start: row.start, endInclusive: row.end_inclusive }));
+}
+
+/**
+ * Removes the scope whose span is EXACTLY `start..endInclusive`, and returns
+ * `changed: false` when no scope has that span.
+ *
+ * WHY THIS EXISTS, and why it is not an omission being corrected quietly.
+ * `28-VERIFICATION.md`'s `WR-28` recorded that `addScope`'s overlap refusal had
+ * no inverse and carried the finding to Phase 29 in as many words, "which puts
+ * `addScope` on an agent-driven surface where a mistyped span is likelier".
+ * `28-REVIEW.md:1788-1814` spells out the consequence: one transposed end --
+ * `addScope($1000, $ffff)` -- makes every future scope from `$1000` upward
+ * permanently unaddable, recoverable only through `revertTo` inside the
+ * 32-revision ring, after which the mistake is permanent for the life of the
+ * project file. Its stated fix is to ship the inverse in the same phase as the
+ * refusal. This is that inverse.
+ *
+ * THE SPAN MUST MATCH EXACTLY -- both ends, as stored. A scope is not trimmed,
+ * split, or partially removed, for the same reason `addScope` does not trim an
+ * overlapping incoming scope: a partial removal would leave a shape the schema
+ * this store mirrors cannot express, and it would do so while reporting
+ * success. A caller that does not know the stored span reads it from
+ * `listScopes()` first.
+ *
+ * REMOVING A SCOPE THAT IS NOT THERE IS AN ACCEPTED NO-OP reporting
+ * `changed: false`, matching `clearEnumUsage`'s direction: an inverse that
+ * refuses when there is nothing to undo makes "undo this" conditional on
+ * knowing whether it was ever done.
+ *
+ * THIS IS THE MODULE'S FOURTH ROW-DELETING STATEMENT. `clearEnumUsage`'s doc
+ * block states the count as three; that sentence was true when it was written
+ * and this one supersedes it. The count is written in prose, deliberately
+ * without spelling the SQL prefix a census greps for, so a census over this
+ * module counts STATEMENTS and not the sentences describing them. The statement
+ * runs inside the write sequence's transaction, so a refusal raised anywhere in
+ * the sequence rolls it back with everything else.
+ */
+export function removeScope(
+  handle: AnnoStoreHandle,
+  args: { start: number | string; endInclusive: number | string; baseRevision?: number },
+): AnnoWriteResult {
+  const start = parseStoreAddress(args.start, { what: "start" });
+  const endInclusive = parseStoreAddress(args.endInclusive, { what: "endInclusive" });
+  // The SAME non-split shape check `addScope` uses, and for the same reason: a
+  // scope is not a table, so the split-table even-count rule must not apply to
+  // it. Passing a different type here would make the inverse refuse spans the
+  // forward verb accepts.
+  assertRangeShape(start, endInclusive, "byte");
+
+  const { revision, result } = applyWrite(
+    handle,
+    (db) => {
+      const existing = db.prepare("select id from anno_scope where start = ? and end_inclusive = ?").get(start, endInclusive) as
+        | { id: number }
+        | undefined;
+      if (!existing) return false;
+      db.prepare("delete from anno_scope where id = ?").run(existing.id);
+      return true;
+    },
+    { baseRevision: args.baseRevision },
+  );
+  return { revision, changed: result };
+}
+
+/**
+ * Validates one project enum's variants mapping and returns it with its KEYS
+ * VERBATIM.
+ *
+ * Every key goes through `parseVariantKey()`, which accepts exactly the forms
+ * the schema names -- decimal, `0x`/`$` hex, `0b`/`%` binary -- and refuses
+ * anything else. The parsed VALUE is used only to detect two keys naming the
+ * same number, which is refused: `"64"` and `"$40"` in one mapping would mean
+ * two variant names for one value, and nothing downstream could say which one
+ * was meant.
+ *
+ * The keys are NOT canonicalised. A caller that wrote `"$40"` reads back
+ * `"$40"`, because round-tripping by value is the store's contract and a
+ * rewritten key is a value the caller never supplied.
+ *
+ * Every variant NAME is checked as an identifier, for the same reason a label
+ * name is: it is emitted as a symbol downstream, so garbage accepted here
+ * becomes an export failure a long way from its cause.
+ */
+function validatedVariants(variants: unknown): Record<string, string> {
+  if (typeof variants !== "object" || variants === null || Array.isArray(variants)) {
+    throw new AnnoTypeError(`enum variants ${JSON.stringify(variants)} is not a mapping of numeric-string keys to variant names`, {
+      dataType: variants,
+    });
+  }
+  const out: Record<string, string> = {};
+  const seenValues = new Map<number, string>();
+  for (const [key, value] of Object.entries(variants as Record<string, unknown>)) {
+    const numeric = parseVariantKey(key);
+    const alreadyAt = seenValues.get(numeric);
+    if (alreadyAt !== undefined) {
+      throw new AnnoTypeError(
+        `enum variant keys ${JSON.stringify(alreadyAt)} and ${JSON.stringify(key)} both name the value ${numeric} -- refusing a mapping ` +
+          `with two names for one value, because nothing downstream could say which was meant`,
+        { dataType: key },
+      );
+    }
+    seenValues.set(numeric, key);
+    out[key] = assertEnumName(value);
+  }
+  return out;
+}
+
+/** Bounds a project enum's free-text description with the same byte bound
+ * comment text carries, and without the semicolon rule -- a description is not
+ * assembler comment text, so a leading `';'` is merely a character. */
+function validatedDescription(description: unknown): string | null {
+  if (description === undefined || description === null) return null;
+  return assertCommentText(description, { what: "description", allowLeadingSemicolon: true });
+}
+
+function readEnumRow(db: DatabaseSync, name: string): { id: number; name: string; variants: string; description: string | null } | undefined {
+  return db.prepare("select id, name, variants, description from anno_enum where name = ?").get(name) as
+    | { id: number; name: string; variants: string; description: string | null }
+    | undefined;
+}
+
+/**
+ * Creates a project-local enum.
+ *
+ * A byte-identical repeat is a no-op reporting `changed:false`, so re-running a
+ * generation pass is safe. A DIFFERENT enum under an existing name is REFUSED
+ * with `AnnoLabelError` naming the collision, rather than overwritten -- the
+ * same rule as a label, for the same reason.
+ *
+ * THERE IS NO DELETE VERB, here or anywhere in this module, and that is a
+ * decision rather than an omission: the delete tool on the surface this store
+ * mirrors has zero callers, and a regenerated enum set replaces an old one
+ * through create-then-update. A delete verb whose only exercise is a test is a
+ * data-loss path with no user.
+ */
+export function createProjectEnum(
+  handle: AnnoStoreHandle,
+  args: { name: unknown; variants: unknown; description?: unknown; baseRevision?: number },
+): AnnoWriteResult {
+  const name = assertEnumName(args.name);
+  const variants = validatedVariants(args.variants);
+  const description = validatedDescription(args.description);
+  const variantsJson = JSON.stringify(variants);
+
+  const { revision, result } = applyWrite(
+    handle,
+    (db) => {
+      const existing = readEnumRow(db, name);
+      if (existing) {
+        if (existing.variants === variantsJson && existing.description === description) return false;
+        throw new AnnoLabelError(
+          `project enum ${JSON.stringify(name)} already exists with different contents -- the write is REFUSED rather than overwriting it. ` +
+            `Use the update entry point, which replaces the variants mapping wholesale and says so.`,
+          { identifier: name, reason: "enum name already in use with different contents" },
+        );
+      }
+      db.prepare("insert into anno_enum(name, variants, description) values (?, ?, ?)").run(name, variantsJson, description);
+      return true;
+    },
+    { baseRevision: args.baseRevision },
+  );
+  return { revision, changed: result };
+}
+
+/**
+ * Updates a project-local enum: renames it, replaces its variants mapping, and
+ * replaces its description, in any combination.
+ *
+ * THE VARIANTS MAPPING IS REPLACED WHOLESALE when one is supplied, matching the
+ * schema's own words ("complete updated variants mapping"). It is not merged: a
+ * merge would make a variant impossible to REMOVE, since there would be no way
+ * to express its absence.
+ *
+ * A rename onto a name another enum already holds is refused, not merged.
+ */
+export function updateProjectEnum(
+  handle: AnnoStoreHandle,
+  args: { name: unknown; newName?: unknown; variants?: unknown; description?: unknown; baseRevision?: number },
+): AnnoWriteResult {
+  const name = assertEnumName(args.name);
+  const newName = args.newName === undefined ? undefined : assertEnumName(args.newName);
+  const variants = args.variants === undefined ? undefined : validatedVariants(args.variants);
+  const variantsJson = variants === undefined ? undefined : JSON.stringify(variants);
+  const description = args.description === undefined ? undefined : validatedDescription(args.description);
+
+  const { revision, result } = applyWrite(
+    handle,
+    (db) => {
+      const existing = readEnumRow(db, name);
+      if (!existing) {
+        throw new AnnoLabelError(`project enum ${JSON.stringify(name)} does not exist, so there is nothing to update`, {
+          identifier: name,
+          reason: "no such enum",
+        });
+      }
+      if (newName !== undefined && newName !== name) {
+        const clash = readEnumRow(db, newName);
+        if (clash) {
+          throw new AnnoLabelError(
+            `cannot rename project enum ${JSON.stringify(name)} to ${JSON.stringify(newName)}: that name is already held by another enum -- ` +
+              `the rename is REFUSED rather than merging two enums into one`,
+            { identifier: newName, reason: "rename target already in use" },
+          );
+        }
+      }
+
+      const nextName = newName ?? existing.name;
+      const nextVariants = variantsJson ?? existing.variants;
+      const nextDescription = description === undefined ? existing.description : description;
+      if (nextName === existing.name && nextVariants === existing.variants && nextDescription === existing.description) {
+        return false;
+      }
+
+      db.prepare("update anno_enum set name = ?, variants = ?, description = ? where id = ?").run(
+        nextName,
+        nextVariants,
+        nextDescription,
+        existing.id,
+      );
+      return true;
+    },
+    { baseRevision: args.baseRevision },
+  );
+  return { revision, changed: result };
+}
+
+/** Every project enum, in ascending `id` order, with its variants mapping
+ * parsed back out of the single JSON text column. */
+export function listProjectEnums(handle: AnnoStoreHandle): ProjectEnumRow[] {
+  const rows = handle.db.prepare("select id, name, variants, description from anno_enum order by id").all() as {
+    id: number;
+    name: string;
+    variants: string;
+    description: string | null;
+  }[];
+  return rows.map((row) => ({
+    id: row.id,
+    name: row.name,
+    variants: JSON.parse(row.variants) as Record<string, string>,
+    description: row.description,
+  }));
+}
+
+/**
+ * Associates ONE address with ONE project enum, so the address's operand is
+ * formatted through that enum's variants (`SCHEMA_VERSION` 3, D-15).
+ *
+ * THE ASSOCIATION IS BY `anno_enum.id`, NEVER BY NAME, and that is the whole
+ * design of the table. `updateProjectEnum` renames an enum in place, keeping
+ * its id; a usage row that persisted the NAME would either be orphaned by the
+ * rename or -- worse, because it is silent -- re-pointed at whatever enum next
+ * took the old name. The name a caller passes here is resolved to an id ONCE,
+ * at write time, and `listEnumUsage` resolves it back through a join at read
+ * time.
+ *
+ * AN ENUM NAME NO `anno_enum` ROW CARRIES IS REFUSED BY NAME, naming the enum
+ * that was not found, and nothing is written. The alternative -- creating the
+ * enum implicitly -- would let a typo produce a real, empty enum that formats
+ * nothing and looks deliberate.
+ *
+ * THE IDEMPOTENCY SHAPE IS `putXref`'s, COPIED RATHER THAN REINVENTED: the
+ * existing row is selected first and `changed: false` is returned when the same
+ * enum is already applied at the same address. The REVISION still advances --
+ * see `AnnoWriteResult`, where that is the module's stated invariant for every
+ * accepted write, `changed` being the only signal that separates a no-op from
+ * a real edit.
+ *
+ * Every argument is validated through `anno-types.ts`'s own assertions before
+ * any SQL runs. `parseStoreAddress` in particular refuses an UNPREFIXED numeric
+ * string such as `"53280"` outright rather than guessing a base -- WR-22's
+ * recorded failure, in which a JSON `"1"` arrived verbatim and SQLite's column
+ * affinity turned an argument error into a corruption refusal.
+ */
+export function applyEnumUsage(
+  handle: AnnoStoreHandle,
+  args: { address: number | string; name: unknown; baseRevision?: number },
+): AnnoWriteResult {
+  const address = parseStoreAddress(args.address, { what: "address" });
+  const name = assertEnumName(args.name);
+
+  const { revision, result } = applyWrite(
+    handle,
+    (db) => {
+      // READ INSIDE THE TRANSACTION, for the reason the write sequence's own
+      // rollback comment gives: resolving the enum outside it would open a
+      // window in which a concurrent writer renames or removes it between the
+      // read and the insert.
+      const target = readEnumRow(db, name);
+      if (!target) {
+        throw new AnnoLabelError(
+          `project enum ${JSON.stringify(name)} does not exist, so there is nothing to apply at $${address.toString(16).padStart(4, "0")} -- the write is ` +
+            `REFUSED rather than creating the enum implicitly, because a mistyped name would otherwise become a real, empty enum that ` +
+            `formats nothing and looks deliberate. Create it first.`,
+          { identifier: name, reason: "no such enum" },
+        );
+      }
+
+      const existing = db.prepare("select id, enum_id from anno_enum_usage where address = ? and bank is ?").get(address, null) as
+        | { id: number; enum_id: number }
+        | undefined;
+      if (existing) {
+        if (existing.enum_id === target.id) return false;
+        // ONE ADDRESS CARRIES AT MOST ONE ENUM (the `unique(address, bank)`
+        // constraint), so applying a DIFFERENT enum replaces rather than
+        // refuses: the schema's own words for the verb are "Applies an enum
+        // definition to format the immediate operand ... at a specific
+        // address", which is a set, not an add.
+        db.prepare("update anno_enum_usage set enum_id = ? where id = ?").run(target.id, existing.id);
+        return true;
+      }
+      db.prepare("insert into anno_enum_usage(address, enum_id, bank) values (?, ?, ?)").run(address, target.id, null);
+      return true;
+    },
+    { baseRevision: args.baseRevision },
+  );
+  return { revision, changed: result };
+}
+
+/**
+ * Clears the enum usage at one address. An address that carries none returns
+ * `changed: false` and is NOT an error -- clearing is idempotent in the same
+ * direction applying is, and the schema's own words make the empty name the
+ * clear ("Omit or send empty to clear"), so a caller clearing twice is doing
+ * the ordinary thing rather than a mistake worth refusing.
+ *
+ * THIS IS THE MODULE'S **THIRD** ROW-DELETING STATEMENT, and the count is
+ * stated here rather than left to be rediscovered. `28-REVIEW` recorded exactly
+ * TWO -- the snapshot ring's prune, which removes an `anno_snapshot` pointer
+ * row, and `retype()`, which removes an overlapped `anno_range` row -- and a
+ * reader who checks that number against this tree will find THREE. The third is
+ * this one.
+ *
+ * The count is written in prose, deliberately without spelling the SQL prefix a
+ * census greps for, so that a `grep` over this module counts STATEMENTS and not
+ * the sentence describing them. Nothing else about the deletion discipline
+ * changed: this statement runs inside the write sequence's transaction, so a
+ * refusal raised anywhere in the sequence rolls it back with everything else.
+ */
+export function clearEnumUsage(handle: AnnoStoreHandle, args: { address: number | string; baseRevision?: number }): AnnoWriteResult {
+  const address = parseStoreAddress(args.address, { what: "address" });
+
+  const { revision, result } = applyWrite(
+    handle,
+    (db) => {
+      const existing = db.prepare("select id from anno_enum_usage where address = ? and bank is ?").get(address, null) as
+        | { id: number }
+        | undefined;
+      if (!existing) return false;
+      db.prepare("delete from anno_enum_usage where id = ?").run(existing.id);
+      return true;
+    },
+    { baseRevision: args.baseRevision },
+  );
+  return { revision, changed: result };
+}
+
+/** Every enum usage, in ascending ADDRESS order, with the enum's name resolved
+ * through a join on `anno_enum.id` rather than read from a second on-disk copy
+ * of it. Reads the reserved `bank` column. */
+export function listEnumUsage(handle: AnnoStoreHandle): EnumUsageRow[] {
+  const rows = handle.db
+    .prepare(
+      // ONE LITERAL, NOT A CONCATENATION. The statement is long enough to want
+      // wrapping and is deliberately not wrapped: the module's SQL is written
+      // as bare statement literals so a census over this file reads the
+      // statement it executes, and so no reader has to prove that a `+` between
+      // two fragments joined only literals.
+      "select u.id as id, u.address as address, u.enum_id as enum_id, e.name as enum_name, u.bank as bank from anno_enum_usage u join anno_enum e on e.id = u.enum_id order by u.address, u.id",
+    )
+    .all() as { id: number; address: number; enum_id: number; enum_name: string; bank: number | null }[];
+  return rows.map((row) => ({
+    id: row.id,
+    address: row.address,
+    enumId: row.enum_id,
+    enumName: row.enum_name,
+    bank: row.bank,
+  }));
+}
+
+/**
+ * Records ONE NON-DERIVABLE cross-reference.
+ *
+ * THIS IS THE C-5 RECONCILIATION, written down here for a reader of the code
+ * rather than left in a plan. Two requirement texts look like they conflict:
+ * `STORE-05` requires cross-reference rows to carry their access kind from the
+ * first write, while the cross-reference criterion requires references to be
+ * DERIVED on every query and never cached on disk. Both hold at once, and this
+ * entry point is where:
+ *
+ *   * the table and its `access_kind` column exist from the first write (the
+ *     `DDL` above), so `STORE-05` is satisfied structurally;
+ *   * the only rows ever written here are references that CANNOT be recovered
+ *     from the bytes -- hand-asserted, or resolved from something outside the
+ *     program image. The `COMPUTED_JUMP` case is exactly that: a computed
+ *     dispatch produces no reference derivable from the bytes at all, which is
+ *     why it needs somewhere to live;
+ *   * nothing derivable is ever written here. A cached derivation would be a
+ *     SECOND ON-DISK TRUTH that can disagree with the range table it came from,
+ *     and the disagreement is invisible because both answers look
+ *     authoritative. `resolveSplitTargets()` in `anno-types.ts` derives and
+ *     returns; it never writes.
+ *
+ * The positive pin is in `anno-store.test.ts`: typing a `lo_hi_address` range,
+ * whose targets are fully derivable from its bytes, leaves this table with zero
+ * rows.
+ *
+ * Two references sharing a `from`/`to` pair but carrying different access kinds
+ * are TWO ROWS. They are not merged: `READ` and `WRITE` at one pair of
+ * addresses are two different facts, and merging them would invent a third.
+ */
+export function putXref(
+  handle: AnnoStoreHandle,
+  args: { fromAddress: number | string; toAddress: number | string; accessKind: unknown; baseRevision?: number },
+): AnnoWriteResult {
+  const fromAddress = parseStoreAddress(args.fromAddress, { what: "fromAddress" });
+  const toAddress = parseStoreAddress(args.toAddress, { what: "toAddress" });
+  const accessKind: XrefAccessKind = assertAccessKind(args.accessKind);
+
+  const { revision, result } = applyWrite(
+    handle,
+    (db) => {
+      const existing = db
+        .prepare("select id from anno_xref where from_address = ? and to_address = ? and access_kind = ?")
+        .get(fromAddress, toAddress, accessKind) as { id: number } | undefined;
+      if (existing) return false;
+      db.prepare("insert into anno_xref(from_address, to_address, access_kind, bank) values (?, ?, ?, ?)").run(
+        fromAddress,
+        toAddress,
+        accessKind,
+        null,
+      );
+      return true;
+    },
+    { baseRevision: args.baseRevision },
+  );
+  return { revision, changed: result };
+}
+
+/** Every stored cross-reference, in ascending `id` order. Empty unless
+ * something called `putXref()` -- typing a range never puts a row here, and a
+ * test pins that. Reads the reserved `bank` column. */
+export function listXrefs(handle: AnnoStoreHandle): XrefRow[] {
+  const rows = handle.db.prepare("select id, from_address, to_address, access_kind, bank from anno_xref order by id").all() as {
+    id: number;
+    from_address: number;
+    to_address: number;
+    access_kind: string;
+    bank: number | null;
+  }[];
+  return rows.map((row) => ({
+    id: row.id,
+    fromAddress: row.from_address,
+    toAddress: row.to_address,
+    accessKind: row.access_kind as XrefAccessKind,
+    bank: row.bank,
+  }));
+}