@dzhechkov/harness-core 0.8.30 → 0.8.31

package/src/agentdb-snapshot-rotation.ts

@@ -0,0 +1,393 @@
+/**
+ * Pre-reindex snapshot rotation (feature `reindex-snapshot-rotation`, FR-1..FR-8).
+ *
+ * `reindexAgentdbRows` copies the store to `<db>.pre-reindex-<ms>.bak` (+ `.embed-manifest.json` /
+ * `-shm` / `-wal` siblings) before every reindex, as an undo point. Nothing has ever pruned them,
+ * so they accumulate without bound — 13 snapshots / 50 MB observed on the owner's hub, and no
+ * command removed a single one.
+ *
+ * This module is the PURE planning half (NFR-2) — {@link listPreReindexSnapshots} (fs READ) and
+ * {@link planSnapshotRotation} (no fs at all) — plus the thin fs-EFFECT wrapper
+ * {@link rotatePreReindexSnapshots} that acts on the plan. A snapshot is a FAMILY of files sharing
+ * one `<ms>` timestamp (FR-2): the family is removed or kept as a unit, never partially.
+ *
+ * @packageDocumentation
+ */
+
+import { lstatSync, readdirSync, unlinkSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+
+import { readLiveReindexMarkers, withAgentdbSnapshotLock } from './agentdb-reindex-marker.js';
+import { NamedLockTimeoutError } from './named-lock.js';
+
+/** One file belonging to a snapshot family — always a basename, never a full path. */
+export interface SnapshotFile {
+  readonly name: string;
+  readonly bytes: number;
+}
+
+/** Every file sharing one `<ms>` timestamp — the unit rotation acts on (FR-2). */
+export interface SnapshotFamily {
+  readonly ms: number;
+  readonly files: readonly SnapshotFile[];
+  readonly bytes: number;
+}
+
+/** A rotation decision: which families survive, which are slated for removal. */
+export interface SnapshotRotationPlan {
+  readonly kept: readonly SnapshotFamily[];
+  readonly removed: readonly SnapshotFamily[];
+}
+
+/** The fs-effect outcome (FR-4) — reported poimённо (by file name), never just a count. */
+export interface SnapshotRotationReport {
+  readonly kept: string[];
+  readonly removed: string[];
+  readonly removedBytes: number;
+  readonly keep: number;
+  /** Per-file unlink failures (FR-5) — never fatal to the caller's own success. */
+  readonly errors?: string[];
+  /**
+   * AM-4 (fix-round after Codex review Grade D): a `readdirSync`/`lstatSync` failure other than
+   * ENOENT makes the candidate list INCOMPLETE — a family the scan never saw would look "not old"
+   * only because it was invisible, never because it truly survives review. Present ⇒ this call
+   * removed NOTHING, however conservative that looks against a nonzero `kept`.
+   */
+  readonly scanErrors?: string[];
+  /**
+   * AM-2: `<ms>` of every family where a sibling unlink failed and the family's `.bak` — the one
+   * file that alone still proves the snapshot ever existed — was therefore left in place rather
+   * than deleted out from under a family whose removal turned out to be only partial.
+   */
+  readonly partialFamilies?: number[];
+  /**
+   * FR-3 (agentdb-snapshot-lock): honest observations that are neither an error nor a removal —
+   * today, exactly one shape: a reindex-in-progress marker found PAST its TTL, ignored and deleted.
+   * Never populated for a marker that is still live (it simply protects its family silently) nor
+   * for the ordinary case of no marker at all.
+   */
+  readonly notes?: string[];
+}
+
+/** AM-3: a family younger than this survives rotation even beyond `keep` — no override flag exists;
+ * the intent is "never delete something from the last few minutes", not a tunable retention window. */
+const DEFAULT_GRACE_MS = 10 * 60 * 1000;
+
+/** Escape a string for literal use inside a `RegExp` — basenames may carry `.`, `+`, etc. */
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * The strict per-db snapshot-family pattern (FR-3): only names literally derived from `dbBasename`
+ * match — `agentdb.db.bak`, `other.pre-reindex-1.bak`, or anything else in the directory is left
+ * alone. Group 1 is the `<ms>` timestamp; group 2 (optional) is the sibling suffix.
+ */
+function snapshotNamePattern(dbBasename: string): RegExp {
+  return new RegExp(`^${escapeRegExp(dbBasename)}\\.pre-reindex-(\\d+)\\.bak(\\.embed-manifest\\.json|-shm|-wal)?$`);
+}
+
+/**
+ * Scan the directory next to `dbFile` for candidate families — the shared innards of
+ * {@link listPreReindexSnapshots} (which drops `scanErrors` for callers that only ever listed) and
+ * {@link rotatePreReindexSnapshots} (which must see them, per AM-4: an incomplete scan must never be
+ * read as "these are all the old ones").
+ *
+ * NFR-1: symlinks are never followed and never treated as candidates. `lstatSync` — never `stat` —
+ * decides this, so a matching NAME that resolves to a symlink is excluded entirely (AC-3), not
+ * "rotated by its link size". An orphaned sibling (e.g. a `-shm` with no `.bak`) still forms its
+ * own one-file family under its `<ms>` (AC-5) — FR-2 groups by timestamp, not by which siblings
+ * happen to exist.
+ *
+ * AM-5: a `<ms>` that is not a safe non-negative integer within `Date`'s representable range
+ * (`±8.64e15`) is never grouped into a candidate family — so it never reaches `new Date(ms)`, which
+ * throws `RangeError` past that bound, and it is never silently treated as "the oldest one".
+ */
+export function scanSnapshotDir(dbFile: string): { families: SnapshotFamily[]; scanErrors: string[] } {
+  const dir = dirname(dbFile);
+  const pattern = snapshotNamePattern(basename(dbFile));
+  const scanErrors: string[] = [];
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== 'ENOENT') {
+      scanErrors.push(`readdir ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return { families: [], scanErrors };
+  }
+  const byMs = new Map<number, SnapshotFile[]>();
+  for (const name of entries) {
+    const match = pattern.exec(name);
+    if (match === null) continue;
+    const full = join(dir, name);
+    let size: number;
+    try {
+      const st = lstatSync(full);
+      if (!st.isFile()) continue; // symlinks (and anything else non-regular) are left alone (NFR-1)
+      size = st.size;
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code !== 'ENOENT') {
+        scanErrors.push(`lstat ${name}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      continue; // ENOENT: vanished between readdir and lstat — nothing left to rotate, not an error
+    }
+    const ms = Number(match[1]);
+    if (!Number.isSafeInteger(ms) || ms < 0 || ms > 8.64e15) continue; // AM-5: not a candidate
+    const list = byMs.get(ms) ?? [];
+    list.push({ name, bytes: size });
+    byMs.set(ms, list);
+  }
+  const families = [...byMs.entries()]
+    .map(([ms, files]) => ({
+      ms,
+      files: [...files].sort((a, b) => a.name.localeCompare(b.name)),
+      bytes: files.reduce((sum, f) => sum + f.bytes, 0),
+    }))
+    .sort((a, b) => b.ms - a.ms);
+  return { families, scanErrors };
+}
+
+/**
+ * List every pre-reindex snapshot family sitting next to `dbFile`, newest `ms` first (families
+ * unsorted internally are sorted here; per-family files are name-sorted for determinism). See
+ * {@link scanSnapshotDir} for the scan rules (NFR-1, AM-5); this wrapper drops `scanErrors` — callers
+ * that only ever want to LIST (never delete) have no unsafe decision to gate on them.
+ */
+export function listPreReindexSnapshots(dbFile: string): SnapshotFamily[] {
+  return scanSnapshotDir(dbFile).families;
+}
+
+/**
+ * Resolve a candidate path (typically the fresh `backupPath` a reindex just wrote) to the `<ms>` it
+ * belongs to, under the SAME strict pattern `listPreReindexSnapshots` uses. `undefined` when the
+ * path does not name this db's snapshot family at all — e.g. the db never existed, so no backup was
+ * ever written.
+ */
+function msOf(dbFile: string, candidatePath: string): number | undefined {
+  const match = snapshotNamePattern(basename(dbFile)).exec(basename(candidatePath));
+  return match === null ? undefined : Number(match[1]);
+}
+
+/**
+ * Pure decision (NFR-2, zero fs): given the families found in a directory, decide which survive.
+ * The newest `keep` families survive (`keep` clamped to ≥ 0); the freshly created backup is
+ * normally the newest family, so it is ordinarily already inside that top-`keep` slice. `protectMs`
+ * names it explicitly and is the FALLBACK that fires only when it would otherwise fall OUTSIDE that
+ * slice — the boundary case named by FR-1: at `keep=0` the top slice is empty, yet the snapshot this
+ * very call just wrote must never be deleted. `families` need not be pre-sorted.
+ *
+ * AM-3 (fix-round): a family younger than `graceMs` (default {@link DEFAULT_GRACE_MS}, 10 minutes;
+ * `ms > now - graceMs`) is rescued exactly like `protectMs`, even past `keep` — a fresh snapshot from
+ * a DIFFERENT process/run than the one calling this must never look "old" just because nobody named
+ * it via `protectMs`. There is no override: `now`/`graceMs` exist for deterministic tests, not for a
+ * CLI knob that would let someone talk the grace period down to zero.
+ */
+export function planSnapshotRotation(
+  families: readonly SnapshotFamily[],
+  opts: { readonly keep: number; readonly protectMs?: number; readonly now?: number; readonly graceMs?: number },
+): SnapshotRotationPlan {
+  const sorted = [...families].sort((a, b) => b.ms - a.ms);
+  const keepCount = Math.max(0, opts.keep);
+  const topKeep = sorted.slice(0, keepCount);
+  const protectMs = opts.protectMs;
+  const alreadyKept = protectMs !== undefined && topKeep.some((f) => f.ms === protectMs);
+  const rescued = protectMs !== undefined && !alreadyKept ? sorted.find((f) => f.ms === protectMs) : undefined;
+  const kept = rescued !== undefined ? [rescued, ...topKeep].sort((a, b) => b.ms - a.ms) : topKeep;
+  const keptMs = new Set(kept.map((f) => f.ms));
+  const removed = sorted.filter((f) => !keptMs.has(f.ms));
+  const now = opts.now ?? Date.now();
+  const graceMs = opts.graceMs ?? DEFAULT_GRACE_MS;
+  const graced = removed.filter((f) => f.ms > now - graceMs);
+  if (graced.length === 0) return { kept, removed };
+  const gracedMs = new Set(graced.map((f) => f.ms));
+  return {
+    kept: [...kept, ...graced].sort((a, b) => b.ms - a.ms),
+    removed: removed.filter((f) => !gracedMs.has(f.ms)),
+  };
+}
+
+/** Options shared by {@link rotatePreReindexSnapshotsUnlocked} and {@link rotatePreReindexSnapshots}. */
+export interface RotateSnapshotsOptions {
+  readonly keep?: number;
+  readonly protectPath?: string;
+  readonly now?: number;
+  readonly graceMs?: number;
+}
+
+/** A lock timeout is reported exactly like any other rotation refusal (FR-4): nothing removed,
+ * `errors: ['lock busy: …']` — never a throw out of the public rotation entry point. */
+function lockBusyReport(keep: number, err: Error): SnapshotRotationReport {
+  return { kept: [], removed: [], removedBytes: 0, keep, errors: [`lock busy: ${err.message}`] };
+}
+
+/** AM-1's guarantee ("an invalid `keep` reads nothing, touches nothing") checked ONCE and shared by
+ * both the unlocked primitive and the public locked wrapper — so an invalid `keep` short-circuits
+ * before the wrapper's own pre-scan `readdir`, not just before the unlocked primitive's. */
+function invalidKeepReport(keep: number): SnapshotRotationReport | undefined {
+  if (!Number.isSafeInteger(keep) || keep < 0) {
+    return { kept: [], removed: [], removedBytes: 0, keep, errors: [`invalid keep: ${keep} (must be a non-negative safe integer)`] };
+  }
+  return undefined;
+}
+
+/**
+ * The fs-effect half: list, plan, delete. A per-file `unlink` failure lands in `errors[]` and never
+ * stops the rest of the rotation (FR-5) — by the time this runs, the caller has already produced a
+ * successful reindex, and a rotation hiccup must never be read as a reindex failure. `removedBytes`
+ * counts only bytes of files ACTUALLY unlinked, so a partial failure never overstates what was freed.
+ *
+ * AM-1 (fix-round, Codex review Grade D): `keep` is validated HERE, before any fs read or delete.
+ * The bug this closes: `Math.max(0, NaN)` is `NaN`, and `sorted.slice(0, NaN)` is `[]` — an EMPTY
+ * kept slice, so every existing family looked "older than keep" and got removed. A `keep` that is
+ * not a non-negative safe integer is refused outright; nothing is read, nothing is touched.
+ *
+ * AM-4: a scan error (readdir/lstat failing with anything but ENOENT) makes the candidate list
+ * INCOMPLETE — deciding "these are the old ones" off a partial list is exactly the class of mistake
+ * this rotation exists to avoid for the snapshots themselves, so this call removes NOTHING.
+ *
+ * AM-2: within a removed family, siblings unlink FIRST and the `.bak` LAST, and only once every
+ * sibling actually unlinked — a failed sibling leaves the `.bak` in place (the one file that alone
+ * still proves the snapshot ever existed) and names the family in `partialFamilies` rather than
+ * guessing the family is gone.
+ *
+ * FR-3 (agentdb-snapshot-lock): a family named by a LIVE reindex-in-progress marker
+ * ({@link readLiveReindexMarkers}) is rescued from `removed` exactly like `protectPath`, even past
+ * `keep` and even past `graceMs` — a reindex that is still running must never lose the undo point it
+ * is relying on. An EXPIRED marker is not a scan error: it is removed and named in `notes`.
+ *
+ * UNLOCKED by design (NFR-2): this is the internal primitive `rotatePreReindexSnapshots` (the public,
+ * locked entry point) and `reindexAgentdbRows`'s own success-path rotation both call — each under
+ * their OWN `withAgentdbSnapshotLock`, so the lock is never acquired twice in one call stack.
+ */
+export function rotatePreReindexSnapshotsUnlocked(
+  dbFile: string,
+  opts: RotateSnapshotsOptions = {},
+): SnapshotRotationReport {
+  const keep = opts.keep ?? 3;
+  const invalid = invalidKeepReport(keep);
+  if (invalid !== undefined) return invalid;
+  const dir = dirname(dbFile);
+  const { families, scanErrors } = scanSnapshotDir(dbFile);
+  if (scanErrors.length > 0) {
+    return {
+      kept: families.flatMap((f) => f.files.map((file) => file.name)),
+      removed: [],
+      removedBytes: 0,
+      keep,
+      scanErrors,
+    };
+  }
+  const protectMs = opts.protectPath !== undefined ? msOf(dbFile, opts.protectPath) : undefined;
+  let { kept, removed } = planSnapshotRotation(families, {
+    keep,
+    ...(protectMs !== undefined ? { protectMs } : {}),
+    ...(opts.now !== undefined ? { now: opts.now } : {}),
+    ...(opts.graceMs !== undefined ? { graceMs: opts.graceMs } : {}),
+  });
+
+  // FR-3: rescue any family a LIVE reindex marker names, however `planSnapshotRotation` above
+  // decided — this protection is orthogonal to keep/grace/protectPath and must win over all of them.
+  const { protectedMs: markerProtectedMs, notes } = readLiveReindexMarkers(dbFile, opts.now);
+  if (markerProtectedMs.length > 0) {
+    const protect = new Set(markerProtectedMs);
+    const rescued = removed.filter((f) => protect.has(f.ms));
+    if (rescued.length > 0) {
+      removed = removed.filter((f) => !protect.has(f.ms));
+      kept = [...kept, ...rescued].sort((a, b) => b.ms - a.ms);
+    }
+  }
+
+  const errors: string[] = [];
+  const partialFamilies: number[] = [];
+  const removedNames: string[] = [];
+  let removedBytes = 0;
+  for (const family of removed) {
+    const bakFile = family.files.find((f) => f.name.endsWith('.bak'));
+    const siblings = family.files.filter((f) => f.name !== bakFile?.name);
+    let allOk = true;
+    for (const file of siblings) {
+      try {
+        unlinkSync(join(dir, file.name));
+        removedNames.push(file.name);
+        removedBytes += file.bytes;
+      } catch (err) {
+        allOk = false;
+        errors.push(`${file.name}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    if (bakFile !== undefined && allOk) {
+      try {
+        unlinkSync(join(dir, bakFile.name));
+        removedNames.push(bakFile.name);
+        removedBytes += bakFile.bytes;
+      } catch (err) {
+        allOk = false;
+        errors.push(`${bakFile.name}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    if (!allOk) partialFamilies.push(family.ms);
+  }
+  const keptNames = kept.flatMap((f) => f.files.map((file) => file.name));
+  return {
+    kept: keptNames,
+    removed: removedNames,
+    removedBytes,
+    keep,
+    ...(errors.length > 0 ? { errors } : {}),
+    ...(partialFamilies.length > 0 ? { partialFamilies } : {}),
+    ...(notes.length > 0 ? { notes } : {}),
+  };
+}
+
+/**
+ * The PUBLIC, locked rotation entry point (FR-1) — used by `dz brain snapshots --prune` and by any
+ * other caller outside `reindexAgentdbRows`'s own success path (which calls
+ * {@link rotatePreReindexSnapshotsUnlocked} directly under its own lock, per NFR-2). A
+ * `NamedLockTimeoutError` — the lock stayed held past the deadline — is reported exactly like any
+ * other rotation refusal: `{ removed: [], errors: ['lock busy: …'] }` (FR-4), never a throw.
+ *
+ * `lockTimeoutMs` is test/tuning-only: omitted, the lock uses its ordinary default deadline.
+ *
+ * AM-4 (carried forward): `withNamedLockSync` creates `<dirname(dbFile)>/.dz/locks/` before it ever
+ * runs `fn` — if `dirname(dbFile)` exists but is NOT a directory (a pathological store path, exactly
+ * the shape AM-4's own fixture uses), that `mkdirSync` throws `ENOTDIR` before any lock is even
+ * attempted. Scanning is therefore checked FIRST, outside the lock: an unreadable directory is a
+ * property of the directory, not of contention over it, and must report the SAME honest
+ * `scanErrors` (never touching, never throwing) whether or not locking is even reachable. MEASURED
+ * (fix round, this feature): omitting this pre-check turned the pre-existing
+ * `rotatePreReindexSnapshots(brokenDbFile, …)` / `dz brain snapshots --prune` "unscannable
+ * directory" fixtures from a clean `scanErrors` report into an uncaught `ENOTDIR` thrown out of the
+ * lock's own `mkdirSync` — reddening both `test/agentdb-snapshot-rotation.test.ts`'s AM-4 case and
+ * `harness-cli/test/brain-snapshots.test.ts`'s "prune mode: an unscannable store directory" case.
+ */
+export function rotatePreReindexSnapshots(
+  dbFile: string,
+  opts: RotateSnapshotsOptions & { readonly lockTimeoutMs?: number } = {},
+): SnapshotRotationReport {
+  const keep = opts.keep ?? 3;
+  const invalid = invalidKeepReport(keep);
+  if (invalid !== undefined) return invalid;
+  const preScan = scanSnapshotDir(dbFile);
+  if (preScan.scanErrors.length > 0) {
+    return {
+      kept: preScan.families.flatMap((f) => f.files.map((file) => file.name)),
+      removed: [],
+      removedBytes: 0,
+      keep,
+      scanErrors: preScan.scanErrors,
+    };
+  }
+  try {
+    return withAgentdbSnapshotLock(
+      dbFile,
+      () => rotatePreReindexSnapshotsUnlocked(dbFile, opts),
+      opts.lockTimeoutMs !== undefined ? { timeoutMs: opts.lockTimeoutMs } : {},
+    );
+  } catch (err) {
+    if (err instanceof NamedLockTimeoutError) return lockBusyReport(keep, err);
+    throw err;
+  }
+}

package/src/agentdb-snapshot.ts

@@ -0,0 +1,222 @@
+/**
+ * Consistent sqlite snapshot + restore for the pre-reindex undo point (feature
+ * `snapshot-wal-consistency`, FR-1..FR-4; fix round AM-1..AM-4).
+ *
+ * A WAL-mode sqlite database's committed data can live in TWO files: the main `dbFile` and its
+ * `-wal` sidecar (frames not yet checkpointed into the main file). The snapshot this module
+ * replaces was a bare `copyFileSync(dbFile, backupPath)` — one file, no `-wal` — so a reindex that
+ * ran while any writer held the WAL open (autocheckpoint disabled, or simply a live connection
+ * between commits) copied a "backup" that was MISSING committed rows. MEASURED (scratch repro,
+ * 2026-09-13, `node` + real `better-sqlite3`): a schema + one row checkpointed, then a second row
+ * inserted on a connection kept open (`wal_autocheckpoint = 0`) — `copyFileSync` alone yields a
+ * backup with 1 row; `VACUUM INTO` on a fresh read-only connection to the SAME live db yields 2.
+ * The live db's main file hash and `-wal` size are unchanged before/after the `VACUUM INTO` (the
+ * read-only connection never checkpoints or writes) — the safety property NFR-2 names.
+ *
+ * {@link snapshotSqliteDatabase} (FR-1/FR-2) takes the snapshot through `VACUUM INTO` on a fresh
+ * READ-ONLY connection — one self-contained output file with every committed transaction, WAL
+ * frames included. If `VACUUM INTO` cannot run (older sqlite, a locked/foreign file, no free disk)
+ * — or a caller forces it for a test — it falls back to copying `dbFile` plus its `-wal` sibling
+ * (present and non-empty) to `backupPath`/`backupPath-wal`; still strictly better than the old
+ * single-file copy, and the fallback is never silent: `method`/`note` name it honestly so a report
+ * downstream (`reindexAgentdbRows`'s `snapshotMethod`) never claims a guarantee it did not get.
+ *
+ * **AM-1 (fix round).** Codex review, Grade C: reusing a `backupPath` left a stale `-wal`/`-shm`
+ * sidecar from an EARLIER, unrelated snapshot family sitting next to the new one; `restoreSqliteSnapshot`
+ * used to decide whether to restore `-wal` by checking whether `backupPath-wal` merely EXISTS, so that
+ * stale sidecar could ride along onto a `vacuum-into` restore that never produced a matching `-wal` of
+ * its own. Fixed two ways: `snapshotSqliteDatabase` now clears any `backupPath-wal`/`-shm` sidecar
+ * BEFORE either strategy writes anything, and again right after a successful `VACUUM INTO` (whose
+ * output is one self-contained file and must never be shadowed); `restoreSqliteSnapshot` now takes the
+ * `method` the caller already knows and restores `-wal` ONLY when `method === 'copy+wal'` — never by
+ * re-deriving it from file presence.
+ *
+ * **AM-2 (fix round).** The old WAL-size probe was `existsSync` + best-effort `statSync` inside a
+ * `catch { walSize = 0 }` — ANY stat failure (`EACCES`, `EIO`, a raced deletion) was silently read as
+ * "no WAL", so a snapshot could report the honest-sounding `method: 'copy'` while actually having
+ * skipped a WAL it could not even check. {@link statSizeIfExists} now calls `statSync` directly and
+ * treats only a confirmed `ENOENT` as "does not exist" — every other error propagates and aborts the
+ * whole snapshot, so `reindexAgentdbRows` reports "snapshot failed", never a falsely-successful `copy`.
+ *
+ * **AM-4 (fix round).** `snapshotSqliteDatabase` used to happily write into (overwrite) an existing
+ * `backupPath`, silently discarding whatever it held — including, combined with AM-1's stale-sidecar
+ * bug, a backup that looked complete but carried a wrong-generation `-wal`. It now refuses up front
+ * (before `VACUUM INTO` or any copy) when `backupPath` already exists and is non-empty.
+ *
+ * {@link restoreSqliteSnapshot} (FR-4) is the paired rollback. MEASURED (same repro): copying the
+ * old main file back over `dbFile` WITHOUT removing a `-wal` left over from the aborted operation
+ * — reopening the "restored" db returned ZERO rows, not the restored one, because sqlite replayed
+ * the stale WAL frames (a since-superseded DELETE) on top of the reverted main file. Removing
+ * `dbFile-wal`/`dbFile-shm` as part of the restore fixed this: the reopened db then returned
+ * exactly the restored row. The caller MUST close its own write connection to `dbFile` before
+ * calling this — restoring a file sqlite still holds open is undefined behaviour.
+ *
+ * **AM-3 (fix round).** `restoreSqliteSnapshot` used to return `void` — a failing `copyFileSync`/
+ * `rmSync` inside it threw straight out of the best-effort `rollback()` wrapper in
+ * `agentdb-index.ts`, which swallowed it in an empty `catch` and reported nothing: "absence of a
+ * receipt is not success" applies to a rollback exactly as much as to a forward operation. It now
+ * returns `{ ok: true } | { ok: false, error }` so the caller can name a failed rollback as failed,
+ * never as restored.
+ *
+ * @packageDocumentation
+ */
+
+import { copyFileSync, existsSync, rmSync, statSync } from 'node:fs';
+
+/** How a snapshot was actually taken — always reported by the caller, never assumed. */
+export type SnapshotMethod = 'vacuum-into' | 'copy+wal' | 'copy';
+
+/** Outcome of {@link snapshotSqliteDatabase}. */
+export interface SnapshotOutcome {
+  readonly method: SnapshotMethod;
+  /** Present only when a fallback method was used — the reason `vacuum-into` did not run. */
+  readonly note?: string;
+}
+
+/** Outcome of {@link restoreSqliteSnapshot} (AM-3) — a failed restore is reported, never assumed. */
+export interface RestoreOutcome {
+  readonly ok: boolean;
+  /** Present only when `ok` is false — why the restore did not fully complete. */
+  readonly error?: string;
+}
+
+/** Minimal better-sqlite3 constructor surface this module needs (read-only open + exec + close). */
+export interface SnapshotDbCtor {
+  new (path: string, opts?: { readonly?: boolean }): { exec: (sql: string) => void; close: () => void };
+}
+
+/** Escape `path` as a single-quoted sqlite string literal (double any embedded `'`). */
+function sqlQuote(path: string): string {
+  return `'${path.replace(/'/g, "''")}'`;
+}
+
+/**
+ * AM-2: the size of `path`, or `undefined` when it does not exist — but ONLY on a confirmed
+ * `ENOENT`. Any other stat error (`EACCES`, `EIO`, a raced deletion mid-call, …) propagates to the
+ * caller instead of being folded into "does not exist": a snapshot that cannot even determine
+ * whether a `-wal` sidecar exists must abort, not silently report the weaker `copy` method as if it
+ * had made an informed choice.
+ */
+function statSizeIfExists(path: string): number | undefined {
+  try {
+    return statSync(path).size;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return undefined;
+    throw err;
+  }
+}
+
+/**
+ * AM-4: refuse to snapshot into an existing, non-empty `backupPath` — silently overwriting it would
+ * discard whatever it held (possibly itself a valid undo point) with no trace. An existing but EMPTY
+ * file is not a real prior snapshot and is allowed through untouched.
+ */
+function assertBackupTargetFree(backupPath: string): void {
+  const size = statSizeIfExists(backupPath);
+  if (size !== undefined && size > 0) {
+    throw new Error(`snapshot target exists and is non-empty: ${backupPath}`);
+  }
+}
+
+/**
+ * AM-1: remove any `-wal`/`-shm` sidecar already sitting at `backupPath` — a leftover from an
+ * earlier, unrelated snapshot family that happened to reuse this name. Called BEFORE either strategy
+ * below writes anything, and again immediately after a successful `VACUUM INTO` (whose output is one
+ * self-contained file that must never be shadowed by a stale sidecar from a previous attempt at the
+ * same path).
+ */
+function clearBackupSidecars(backupPath: string): void {
+  rmSync(`${backupPath}-wal`, { force: true });
+  rmSync(`${backupPath}-shm`, { force: true });
+}
+
+function copyWithWal(dbFile: string, backupPath: string, note: string): SnapshotOutcome {
+  // AM-2: statSync directly; only a confirmed ENOENT means "no -wal to copy" — any other stat error
+  // propagates out of this function (and out of snapshotSqliteDatabase) as a thrown exception.
+  // Lead edit after re-review: the stat runs BEFORE the main file is copied, so a stat failure leaves
+  // no half-written target behind (which AM-4 would otherwise refuse on the retry).
+  const walSize = statSizeIfExists(`${dbFile}-wal`) ?? 0;
+  copyFileSync(dbFile, backupPath);
+  if (walSize > 0) {
+    copyFileSync(`${dbFile}-wal`, `${backupPath}-wal`);
+    return { method: 'copy+wal', note };
+  }
+  return { method: 'copy', note };
+}
+
+/**
+ * Take a consistent snapshot of `dbFile` into `backupPath` (FR-1/FR-2). Default: open `dbFile`
+ * READ-ONLY and run `VACUUM INTO <backupPath>` — one output file holding every committed
+ * transaction (including `-wal` frames), with no write to the live database (NFR-2 — MEASURED:
+ * main-file hash and `-wal` size are unchanged across the call). On any failure — an older sqlite
+ * without `VACUUM INTO`, a locked file, no disk space — or when `opts.strategy` forces it (tests),
+ * falls back to `copyFileSync(dbFile, backupPath)` plus a copy of `dbFile-wal` to `backupPath-wal`
+ * when the WAL sibling exists and is non-empty; `method` is `'copy+wal'` when the sibling was
+ * copied, `'copy'` when there was none to copy. `note` names the fallback reason (FR-2) — set even
+ * for a forced-strategy test call, so a caller never has to guess why the fast path was skipped.
+ * The read-only connection opened for `VACUUM INTO` is always closed before returning.
+ *
+ * Throws (no snapshot taken, or an incomplete one left in a fully-cleared state) when: `backupPath`
+ * already names an existing, non-empty file (AM-4); or a `-wal` stat probe hits a non-ENOENT error
+ * (AM-2, inside the fallback path). Never silently overwrites, never mis-reports a lesser guarantee
+ * as a stronger one.
+ */
+export function snapshotSqliteDatabase(
+  Database: SnapshotDbCtor,
+  dbFile: string,
+  backupPath: string,
+  opts: { strategy?: 'vacuum-into' | 'copy+wal' } = {},
+): SnapshotOutcome {
+  assertBackupTargetFree(backupPath); // AM-4 — before any write, on either strategy
+  clearBackupSidecars(backupPath); // AM-1 — clean slate before either strategy writes anything
+  if (opts.strategy === 'copy+wal') {
+    return copyWithWal(dbFile, backupPath, 'snapshotStrategy=copy+wal forced by caller');
+  }
+  try {
+    const db = new Database(dbFile, { readonly: true });
+    try {
+      db.exec(`VACUUM INTO ${sqlQuote(backupPath)}`);
+    } finally {
+      db.close();
+    }
+    clearBackupSidecars(backupPath); // AM-1 — VACUUM INTO's output never has a matching -wal of its own
+    return { method: 'vacuum-into' };
+  } catch (err) {
+    return copyWithWal(dbFile, backupPath, `VACUUM INTO failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+/**
+ * Restore `dbFile` from a snapshot taken by {@link snapshotSqliteDatabase} (FR-4). The caller MUST
+ * close its write connection to `dbFile` BEFORE calling this — this restore is a plain file copy,
+ * not a sqlite-mediated rollback, and a live handle can reintroduce exactly the frames being undone.
+ *
+ * `method` is the EXACT {@link SnapshotMethod} the paired `snapshotSqliteDatabase` call returned
+ * (AM-1) — never re-derived from whether `backupPath-wal` happens to exist on disk, which a stale
+ * sidecar from an unrelated earlier snapshot at the same path could satisfy. Copies `backupPath`
+ * over `dbFile`; when `method === 'copy+wal'`, also restores `backupPath-wal` to `dbFile-wal`.
+ * Otherwise (`'vacuum-into'` or `'copy'`, neither of which produced a matching `-wal` of its own) any
+ * LIVE `dbFile-wal` — left over from the operation being undone — is removed instead: MEASURED,
+ * leaving it in place made a reopened "restored" db replay that WAL's frames (a since-superseded
+ * write) on top of the reverted main file, returning zero rows instead of the restored set.
+ * `dbFile-shm` is always removed — its offsets are valid only for the `-wal` that no longer matches.
+ *
+ * Returns `{ ok: true }`, or `{ ok: false, error }` (AM-3) when any step throws — a caller that
+ * reported a failed restore as a successful one would leave the store worse than before rollback was
+ * attempted, with nothing on record to say so.
+ */
+export function restoreSqliteSnapshot(dbFile: string, backupPath: string, method: SnapshotMethod): RestoreOutcome {
+  try {
+    if (!existsSync(backupPath)) return { ok: false, error: `snapshot missing at ${backupPath}` };
+    copyFileSync(backupPath, dbFile);
+    if (method === 'copy+wal') {
+      copyFileSync(`${backupPath}-wal`, `${dbFile}-wal`);
+    } else {
+      rmSync(`${dbFile}-wal`, { force: true });
+    }
+    rmSync(`${dbFile}-shm`, { force: true });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}