@dzhechkov/harness-core 0.8.30 → 0.8.31

package/dist/agentdb-snapshot-rotation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentdb-snapshot-rotation.d.ts","sourceRoot":"","sources":["../src/agentdb-snapshot-rotation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,sFAAsF;AACtF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,SAAS,cAAc,EAAE,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C;AAED,2FAA2F;AAC3F,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAoBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CA6CpG;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE,CAExE;AAaD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,IAAI,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7G,oBAAoB,CAmBtB;AAED,yGAAyG;AACzG,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,sBAA2B,GAChC,sBAAsB,CA2ExB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,sBAAsB,GAAG;IAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACtE,sBAAsB,CAwBxB"}

package/dist/agentdb-snapshot-rotation.js

@@ -0,0 +1,322 @@
+/**
+ * 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';
+/** 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) {
+    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) {
+    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) {
+    const dir = dirname(dbFile);
+    const pattern = snapshotNamePattern(basename(dbFile));
+    const scanErrors = [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'ENOENT') {
+            scanErrors.push(`readdir ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return { families: [], scanErrors };
+    }
+    const byMs = new Map();
+    for (const name of entries) {
+        const match = pattern.exec(name);
+        if (match === null)
+            continue;
+        const full = join(dir, name);
+        let size;
+        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.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) {
+    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, candidatePath) {
+    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, opts) {
+    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)),
+    };
+}
+/** 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, err) {
+    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) {
+    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, opts = {}) {
+    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 = [];
+    const partialFamilies = [];
+    const removedNames = [];
+    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, opts = {}) {
+    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;
+    }
+}
+//# sourceMappingURL=agentdb-snapshot-rotation.js.map

package/dist/agentdb-snapshot-rotation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentdb-snapshot-rotation.js","sourceRoot":"","sources":["../src/agentdb-snapshot-rotation.ts"],"names":[],"mappings":"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"}

package/dist/agentdb-snapshot.d.ts

@@ -0,0 +1,126 @@
+/**
+ * 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
+ */
+/** 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;
+    };
+}
+/**
+ * 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 declare function snapshotSqliteDatabase(Database: SnapshotDbCtor, dbFile: string, backupPath: string, opts?: {
+    strategy?: 'vacuum-into' | 'copy+wal';
+}): SnapshotOutcome;
+/**
+ * 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 declare function restoreSqliteSnapshot(dbFile: string, backupPath: string, method: SnapshotMethod): RestoreOutcome;
+//# sourceMappingURL=agentdb-snapshot.d.ts.map

package/dist/agentdb-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentdb-snapshot.d.ts","sourceRoot":"","sources":["../src/agentdb-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAIH,wFAAwF;AACxF,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,UAAU,GAAG,MAAM,CAAC;AAEjE,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qGAAqG;AACrG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,oGAAoG;AACpG,MAAM,WAAW,cAAc;IAC7B,KAAK,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;CACvG;AA6DD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,UAAU,CAAA;CAAO,GACnD,eAAe,CAkBjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,cAAc,CAchH"}