@dzhechkov/harness-core 0.8.30 → 0.8.31

package/dist/agentdb-reindex-marker.d.ts

@@ -0,0 +1,170 @@
+/**
+ * The agentdb snapshot lock + reindex-in-progress marker (feature `agentdb-snapshot-lock`,
+ * FR-1..FR-4; fix-round AM-1..AM-4/AM-7 after Codex review Grade D).
+ *
+ * WHY. Snapshot creation (in `reindexAgentdbRows`), snapshot rotation (`rotatePreReindexSnapshots`,
+ * including `dz brain snapshots --prune`) and snapshot restore (`restoreSqliteSnapshot` via
+ * `reindexAgentdbRows`'s rollback) are three writers of ONE directory with no mutual exclusion: a
+ * concurrent `rotate --keep 0` can delete the very snapshot family a live reindex is relying on as
+ * its undo point, with only a 10-minute grace period standing in the way.
+ *
+ * {@link withAgentdbSnapshotLock} is a thin, dbFile-addressed wrapper over `withNamedLockSync`: the
+ * lock lives at `<dirname(dbFile)>/.dz/locks/agentdb-snapshot.lock` — a pure function of the
+ * database's OWN directory, never of the caller's cwd, so a project store and the home brain each
+ * get their own lock (AC-5) regardless of where `dz` happens to be invoked from. AM-7: it defaults
+ * `staleMs` to {@link AGENTDB_SNAPSHOT_LOCK_STALE_MS} (5 minutes) rather than named-lock's ordinary
+ * 30-second default — MEASURED (lead, this fix round): `VACUUM INTO` on the owner's hub store
+ * (8.45 MB) took 96 ms, so 5 minutes leaves roughly 3000x headroom while staying inside
+ * named-lock's own 600 000 ms environment-override ceiling. A caller doing something unusually
+ * large may still override via `opts.staleMs`.
+ *
+ * The critical section this lock guards must stay SHORT and SYNCHRONOUS — file operations only
+ * (`VACUUM INTO` / copies / unlink / restore). MEASURED (named-lock.ts round-2, reused verbatim
+ * here): a 6s synchronous body under a 2s stale threshold let a THIRD process break in while the
+ * second was still inside its own critical section — a long body doesn't just block callers, it
+ * breaks the lock's own guarantee. The actual re-embedding (network/CPU-bound `EmbeddingService`
+ * calls, row writes) therefore runs OUTSIDE this lock — see `reindexAgentdbRows`.
+ *
+ * {@link writeReindexMarker} / {@link clearReindexMarker} / {@link readLiveReindexMarkers} implement
+ * the SECOND protection this feature adds — a "reindex is currently in flight" marker file beside
+ * the database, so a family a live reindex just created is protected from rotation for the
+ * DURATION of the reindex, not merely for the few milliseconds the snapshot lock itself is held
+ * (the embedding phase can run for a while, unlocked, per FR-2). The marker's liveness is judged by
+ * `startedAt` (a wall-clock age, {@link REINDEX_MARKER_TTL_MS}), never by `pid` — a pid is recorded
+ * for operator debugging only; a live pid on a different host, or a recycled pid, proves nothing
+ * ("pid is not authority over liveness" — the same lesson `store-lock.ts`/`named-lock.ts` already
+ * encode for lock staleness). A marker older than the TTL is treated as abandoned: it protects
+ * nothing, and rotation removes it, recording why in the report's `notes` — that is an honest
+ * observation about a stale marker, never a scan error.
+ *
+ * AM-1 (fix-round): {@link writeReindexMarker} creates the marker file EXCLUSIVELY
+ * (`openSync(path, 'wx')`) and stamps it with an ownership `token` (16 random hex chars). A LIVE
+ * marker already at that path (another reindex genuinely in flight) refuses this call outright —
+ * `{ ok: false, error }`, no snapshot ever taken for the refused call. A marker at or past the TTL
+ * is treated as abandoned and replaced. {@link clearReindexMarker} is compare-and-delete: it removes
+ * the marker only when the caller's `token` matches the one on disk, so a process can never tear
+ * down a marker it does not own (`{ cleared: false, reason }` otherwise). The narrow race this
+ * leaves — two `writeReindexMarker` calls racing the exclusive-create step itself — cannot happen
+ * in practice: every caller in this codebase invokes it from INSIDE the very snapshot lock this
+ * module also provides (see `reindexAgentdbRows`), so at most one writer is ever in this function
+ * at a time.
+ *
+ * @packageDocumentation
+ */
+import type { StoreLockOptions } from './store-lock.js';
+/** A marker older than this is abandoned — its family is no longer protected (FR-3). `pid` is
+ * recorded for operator debugging only and is NEVER consulted to decide liveness. */
+export declare const REINDEX_MARKER_TTL_MS: number;
+/** AM-7: MEASURED (lead, this fix round) — `VACUUM INTO` on the hub's 8.45 MB agentdb store took
+ * 96 ms. 5 minutes is ~3000x that, and stays inside named-lock's 600 000 ms override ceiling. A
+ * base whose snapshot genuinely needs longer than this needs external coordination, not a bigger
+ * default — see the README. */
+export declare const AGENTDB_SNAPSHOT_LOCK_STALE_MS = 300000;
+/** The reindex-in-progress marker written beside the database while a reindex is running. */
+export interface ReindexMarker {
+    /** The `<ms>` timestamp of THIS reindex's pre-reindex snapshot family — the value rotation must
+     * protect while the marker is live. AM-4: `null` when the reindex's `backupPath` does not match
+     * the standard `<db>.pre-reindex-<ms>.bak` family shape (a non-standard target names no family,
+     * so it is never a rotation candidate in the first place). */
+    readonly ms: number | null;
+    /** Operator-debugging only — never consulted for liveness (pid is not authority). */
+    readonly pid: number;
+    /** Wall-clock start time (`Date.now()`); liveness = `now - startedAt < REINDEX_MARKER_TTL_MS`. */
+    readonly startedAt: number;
+    /** AM-1: ownership token (16 random hex chars) — {@link clearReindexMarker} removes the marker
+     * only when the caller presents this exact token back. */
+    readonly token: string;
+    /** AM-4: the reindex's actual backup path, always recorded — the only way to identify the
+     * snapshot a `ms: null` marker is protecting (an operator debugging a stuck non-standard target
+     * has nothing else to go on). */
+    readonly backupPath?: string;
+    /** Lead edit after re-review (Codex D): set by {@link markReindexMarkerRecoveryRequired} when a
+     * rollback FAILED. Such a marker never expires — its family stays protected and every new reindex
+     * of this store is refused until an operator restores the snapshot and removes the marker. */
+    readonly requiresRecovery?: boolean;
+    readonly recoveryNote?: string;
+}
+/** The marker's path — always beside the database, never in a separate directory. */
+export declare function reindexMarkerPath(dbFile: string): string;
+/**
+ * AM-4: recompute a marker's `ms` from the ACTUAL backup path's filename — decoupled from whatever
+ * internal `ms` variable a caller used to build a DEFAULT `backupPath`. A caller-supplied
+ * `opts.backupPath` that does not end in the standard `.pre-reindex-<digits>.bak` shape (or whose
+ * digits overflow a safe integer) names no family at all, so it maps to `null` — such a target is
+ * never a rotation candidate, and the marker must not claim to protect one.
+ */
+export declare function msFromBackupPath(backupPath: string): number | null;
+/**
+ * Run `fn` while holding the agentdb snapshot lock for `dbFile` — a pure function of the
+ * database's own directory (AC-5), never of `process.cwd()`. Propagates `NamedLockTimeoutError`
+ * (FR-4): a caller that cannot acquire the lock by the deadline must report the failure explicitly,
+ * never proceed unlocked and never silently skip its work. AM-7: `staleMs` defaults to
+ * {@link AGENTDB_SNAPSHOT_LOCK_STALE_MS} unless the caller names its own.
+ */
+export declare function withAgentdbSnapshotLock<T>(dbFile: string, fn: () => T, opts?: StoreLockOptions): T;
+/**
+ * AM-1: write the reindex-in-progress marker EXCLUSIVELY. A marker already at this path that is
+ * still LIVE (younger than {@link REINDEX_MARKER_TTL_MS}) refuses this write outright —
+ * `{ ok: false, error }` naming the marker path, with no snapshot ever attempted by the caller for
+ * this call (the caller checks `ok` BEFORE touching the database — see `reindexAgentdbRows`). A
+ * marker that is missing, unreadable/corrupt, or past the TTL is replaced. The written marker
+ * carries a fresh ownership `token`; only {@link clearReindexMarker} presenting that SAME token may
+ * remove it.
+ */
+export declare function writeReindexMarker(dbFile: string, marker: {
+    readonly ms: number | null;
+    readonly pid: number;
+    readonly startedAt: number;
+    readonly backupPath?: string;
+}): {
+    ok: true;
+    token: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Lead edit after re-review (Codex D, finding 1): a marker left behind by a FAILED rollback must not
+ * quietly expire after the TTL — the snapshot it names may be the only good copy of the store. The
+ * owner (token) rewrites the marker atomically (tmp + rename) with `requiresRecovery: true`; from
+ * then on {@link readLiveReindexMarkers} protects its family without expiry and
+ * {@link writeReindexMarker} refuses every new reindex until an operator removes the marker.
+ * Call it under the snapshot lock, like every other marker mutation.
+ */
+export declare function markReindexMarkerRecoveryRequired(dbFile: string, token: string, recoveryNote: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * AM-1: compare-and-delete. Removes the marker ONLY when its `token` matches the one on disk — a
+ * caller can never tear down a marker it does not own. Absence of the marker file is treated as an
+ * already-cleared success (idempotent). Called from `reindexAgentdbRows`'s cleanup on every path
+ * that does NOT leave a failed rollback behind (AM-3) — "absence of a receipt is not success" cuts
+ * the other way here too: a marker left behind after its owner finished would falsely protect a
+ * family forever (until the TTL), so ownership-checked removal must still run unconditionally on
+ * every path that is safe to clear.
+ */
+export declare function clearReindexMarker(dbFile: string, token: string): {
+    cleared: true;
+} | {
+    cleared: false;
+    reason: string;
+};
+/**
+ * Read the marker beside `dbFile` and classify it: a marker younger than
+ * {@link REINDEX_MARKER_TTL_MS} protects its `ms` (FR-3) — but ONLY when `ms` is an actual number
+ * (AM-4: a `ms: null` marker names no family, so it protects nothing, live or not). A marker at or
+ * past the TTL is abandoned — it is removed here (rotation must not act on stale-but-still-present
+ * state on its NEXT call). AM-6: the note reports "ignored and removed" ONLY once `rmSync` actually
+ * succeeded; a removal failure (e.g. a permission error) is reported as "ignored, removal failed:
+ * <err>" — never silently claimed as removed. No marker, or a marker this function cannot parse
+ * (corrupt / missing fields), yields `{ protectedMs: [], notes: [] }` — never a throw: a malformed
+ * marker must not abort rotation, and it also cannot honestly claim to protect anything.
+ */
+export declare function readLiveReindexMarkers(dbFile: string, now?: number): {
+    protectedMs: number[];
+    notes: string[];
+};
+//# sourceMappingURL=agentdb-reindex-marker.d.ts.map

package/dist/agentdb-reindex-marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentdb-reindex-marker.d.ts","sourceRoot":"","sources":["../src/agentdb-reindex-marker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAOH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD;qFACqF;AACrF,eAAO,MAAM,qBAAqB,QAAiB,CAAC;AAEpD;;;+BAG+B;AAC/B,eAAO,MAAM,8BAA8B,SAAU,CAAC;AAEtD,6FAA6F;AAC7F,MAAM,WAAW,aAAa;IAC5B;;;kEAG8D;IAC9D,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,kGAAkG;IAClG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;8DAC0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;qCAEiC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;kGAE8F;IAC9F,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKlE;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,CAAC,EACX,IAAI,GAAE,gBAAqB,GAC1B,CAAC,CAKH;AAaD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACrH;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAyC5D;AAWD;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GACnB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAe9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAyBxD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,MAAmB,GACvB;IAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAuC5C"}

package/dist/agentdb-reindex-marker.js

@@ -0,0 +1,293 @@
+/**
+ * The agentdb snapshot lock + reindex-in-progress marker (feature `agentdb-snapshot-lock`,
+ * FR-1..FR-4; fix-round AM-1..AM-4/AM-7 after Codex review Grade D).
+ *
+ * WHY. Snapshot creation (in `reindexAgentdbRows`), snapshot rotation (`rotatePreReindexSnapshots`,
+ * including `dz brain snapshots --prune`) and snapshot restore (`restoreSqliteSnapshot` via
+ * `reindexAgentdbRows`'s rollback) are three writers of ONE directory with no mutual exclusion: a
+ * concurrent `rotate --keep 0` can delete the very snapshot family a live reindex is relying on as
+ * its undo point, with only a 10-minute grace period standing in the way.
+ *
+ * {@link withAgentdbSnapshotLock} is a thin, dbFile-addressed wrapper over `withNamedLockSync`: the
+ * lock lives at `<dirname(dbFile)>/.dz/locks/agentdb-snapshot.lock` — a pure function of the
+ * database's OWN directory, never of the caller's cwd, so a project store and the home brain each
+ * get their own lock (AC-5) regardless of where `dz` happens to be invoked from. AM-7: it defaults
+ * `staleMs` to {@link AGENTDB_SNAPSHOT_LOCK_STALE_MS} (5 minutes) rather than named-lock's ordinary
+ * 30-second default — MEASURED (lead, this fix round): `VACUUM INTO` on the owner's hub store
+ * (8.45 MB) took 96 ms, so 5 minutes leaves roughly 3000x headroom while staying inside
+ * named-lock's own 600 000 ms environment-override ceiling. A caller doing something unusually
+ * large may still override via `opts.staleMs`.
+ *
+ * The critical section this lock guards must stay SHORT and SYNCHRONOUS — file operations only
+ * (`VACUUM INTO` / copies / unlink / restore). MEASURED (named-lock.ts round-2, reused verbatim
+ * here): a 6s synchronous body under a 2s stale threshold let a THIRD process break in while the
+ * second was still inside its own critical section — a long body doesn't just block callers, it
+ * breaks the lock's own guarantee. The actual re-embedding (network/CPU-bound `EmbeddingService`
+ * calls, row writes) therefore runs OUTSIDE this lock — see `reindexAgentdbRows`.
+ *
+ * {@link writeReindexMarker} / {@link clearReindexMarker} / {@link readLiveReindexMarkers} implement
+ * the SECOND protection this feature adds — a "reindex is currently in flight" marker file beside
+ * the database, so a family a live reindex just created is protected from rotation for the
+ * DURATION of the reindex, not merely for the few milliseconds the snapshot lock itself is held
+ * (the embedding phase can run for a while, unlocked, per FR-2). The marker's liveness is judged by
+ * `startedAt` (a wall-clock age, {@link REINDEX_MARKER_TTL_MS}), never by `pid` — a pid is recorded
+ * for operator debugging only; a live pid on a different host, or a recycled pid, proves nothing
+ * ("pid is not authority over liveness" — the same lesson `store-lock.ts`/`named-lock.ts` already
+ * encode for lock staleness). A marker older than the TTL is treated as abandoned: it protects
+ * nothing, and rotation removes it, recording why in the report's `notes` — that is an honest
+ * observation about a stale marker, never a scan error.
+ *
+ * AM-1 (fix-round): {@link writeReindexMarker} creates the marker file EXCLUSIVELY
+ * (`openSync(path, 'wx')`) and stamps it with an ownership `token` (16 random hex chars). A LIVE
+ * marker already at that path (another reindex genuinely in flight) refuses this call outright —
+ * `{ ok: false, error }`, no snapshot ever taken for the refused call. A marker at or past the TTL
+ * is treated as abandoned and replaced. {@link clearReindexMarker} is compare-and-delete: it removes
+ * the marker only when the caller's `token` matches the one on disk, so a process can never tear
+ * down a marker it does not own (`{ cleared: false, reason }` otherwise). The narrow race this
+ * leaves — two `writeReindexMarker` calls racing the exclusive-create step itself — cannot happen
+ * in practice: every caller in this codebase invokes it from INSIDE the very snapshot lock this
+ * module also provides (see `reindexAgentdbRows`), so at most one writer is ever in this function
+ * at a time.
+ *
+ * @packageDocumentation
+ */
+import { closeSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { basename, dirname } from 'node:path';
+import { withNamedLockSync } from './named-lock.js';
+/** A marker older than this is abandoned — its family is no longer protected (FR-3). `pid` is
+ * recorded for operator debugging only and is NEVER consulted to decide liveness. */
+export const REINDEX_MARKER_TTL_MS = 60 * 60 * 1000;
+/** AM-7: MEASURED (lead, this fix round) — `VACUUM INTO` on the hub's 8.45 MB agentdb store took
+ * 96 ms. 5 minutes is ~3000x that, and stays inside named-lock's 600 000 ms override ceiling. A
+ * base whose snapshot genuinely needs longer than this needs external coordination, not a bigger
+ * default — see the README. */
+export const AGENTDB_SNAPSHOT_LOCK_STALE_MS = 300_000;
+/** The marker's path — always beside the database, never in a separate directory. */
+export function reindexMarkerPath(dbFile) {
+    return `${dbFile}.reindex-inprogress.json`;
+}
+/**
+ * AM-4: recompute a marker's `ms` from the ACTUAL backup path's filename — decoupled from whatever
+ * internal `ms` variable a caller used to build a DEFAULT `backupPath`. A caller-supplied
+ * `opts.backupPath` that does not end in the standard `.pre-reindex-<digits>.bak` shape (or whose
+ * digits overflow a safe integer) names no family at all, so it maps to `null` — such a target is
+ * never a rotation candidate, and the marker must not claim to protect one.
+ */
+export function msFromBackupPath(backupPath) {
+    const match = /\.pre-reindex-(\d+)\.bak$/.exec(basename(backupPath));
+    if (match === null)
+        return null;
+    const ms = Number(match[1]);
+    return Number.isSafeInteger(ms) ? ms : null;
+}
+/**
+ * Run `fn` while holding the agentdb snapshot lock for `dbFile` — a pure function of the
+ * database's own directory (AC-5), never of `process.cwd()`. Propagates `NamedLockTimeoutError`
+ * (FR-4): a caller that cannot acquire the lock by the deadline must report the failure explicitly,
+ * never proceed unlocked and never silently skip its work. AM-7: `staleMs` defaults to
+ * {@link AGENTDB_SNAPSHOT_LOCK_STALE_MS} unless the caller names its own.
+ */
+export function withAgentdbSnapshotLock(dbFile, fn, opts = {}) {
+    return withNamedLockSync(dirname(dbFile), 'agentdb-snapshot', fn, {
+        staleMs: AGENTDB_SNAPSHOT_LOCK_STALE_MS,
+        ...opts,
+    });
+}
+/** Read + best-effort-parse the marker at `path`; `undefined` on any missing/unreadable/corrupt
+ * field — callers treat that identically to "no marker" or "not provably live", never as live. */
+function tryReadStartedAt(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof parsed.startedAt === 'number' && Number.isFinite(parsed.startedAt) ? parsed.startedAt : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * AM-1: write the reindex-in-progress marker EXCLUSIVELY. A marker already at this path that is
+ * still LIVE (younger than {@link REINDEX_MARKER_TTL_MS}) refuses this write outright —
+ * `{ ok: false, error }` naming the marker path, with no snapshot ever attempted by the caller for
+ * this call (the caller checks `ok` BEFORE touching the database — see `reindexAgentdbRows`). A
+ * marker that is missing, unreadable/corrupt, or past the TTL is replaced. The written marker
+ * carries a fresh ownership `token`; only {@link clearReindexMarker} presenting that SAME token may
+ * remove it.
+ */
+export function writeReindexMarker(dbFile, marker) {
+    const path = reindexMarkerPath(dbFile);
+    const token = randomBytes(8).toString('hex'); // 16 hex chars
+    const full = { ...marker, token };
+    const content = `${JSON.stringify(full)}\n`;
+    const tryCreate = () => {
+        let fd;
+        try {
+            fd = openSync(path, 'wx'); // exclusive create — EEXIST if a marker is already there
+        }
+        catch (err) {
+            if (err.code === 'EEXIST')
+                return false;
+            throw err;
+        }
+        try {
+            writeFileSync(fd, content);
+        }
+        finally {
+            closeSync(fd);
+        }
+        return true;
+    };
+    if (tryCreate())
+        return { ok: true, token };
+    const existing = tryReadMarker(path);
+    if (existing?.requiresRecovery === true) {
+        return { ok: false, error: `recovery required: a previous reindex of this store failed to roll back — restore ${existing.backupPath ?? 'its snapshot'} manually, then remove marker ${path}` };
+    }
+    const existingStartedAt = tryReadStartedAt(path);
+    const live = existingStartedAt !== undefined && Date.now() - existingStartedAt < REINDEX_MARKER_TTL_MS;
+    if (live) {
+        return { ok: false, error: `reindex already in progress (marker ${path})` };
+    }
+    // Stale, missing-field, or unparseable — treated as abandoned and replaced.
+    rmSync(path, { force: true });
+    if (!tryCreate()) {
+        // Practically unreachable (nothing else writes this path outside this module's own lock), but
+        // never silently claim success over an unexplained race.
+        return { ok: false, error: `reindex already in progress (marker ${path})` };
+    }
+    return { ok: true, token };
+}
+function tryReadMarker(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed !== null && typeof parsed === 'object' ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Lead edit after re-review (Codex D, finding 1): a marker left behind by a FAILED rollback must not
+ * quietly expire after the TTL — the snapshot it names may be the only good copy of the store. The
+ * owner (token) rewrites the marker atomically (tmp + rename) with `requiresRecovery: true`; from
+ * then on {@link readLiveReindexMarkers} protects its family without expiry and
+ * {@link writeReindexMarker} refuses every new reindex until an operator removes the marker.
+ * Call it under the snapshot lock, like every other marker mutation.
+ */
+export function markReindexMarkerRecoveryRequired(dbFile, token, recoveryNote) {
+    const path = reindexMarkerPath(dbFile);
+    const existing = tryReadMarker(path);
+    if (existing === undefined)
+        return { ok: false, reason: `marker at ${path} is missing or unreadable` };
+    if (existing.token !== token)
+        return { ok: false, reason: `marker at ${path} is owned by a different token` };
+    const full = { ...existing, requiresRecovery: true, recoveryNote };
+    const tmp = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, `${JSON.stringify(full)}\n`);
+        renameSync(tmp, path);
+        return { ok: true };
+    }
+    catch (err) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch { /* best-effort */ }
+        return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * AM-1: compare-and-delete. Removes the marker ONLY when its `token` matches the one on disk — a
+ * caller can never tear down a marker it does not own. Absence of the marker file is treated as an
+ * already-cleared success (idempotent). Called from `reindexAgentdbRows`'s cleanup on every path
+ * that does NOT leave a failed rollback behind (AM-3) — "absence of a receipt is not success" cuts
+ * the other way here too: a marker left behind after its owner finished would falsely protect a
+ * family forever (until the TTL), so ownership-checked removal must still run unconditionally on
+ * every path that is safe to clear.
+ */
+export function clearReindexMarker(dbFile, token) {
+    const path = reindexMarkerPath(dbFile);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { cleared: true };
+        return { cleared: false, reason: `cannot read marker: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { cleared: false, reason: 'marker is not owned by this token (unparseable marker content)' };
+    }
+    const owner = parsed !== null && typeof parsed === 'object' ? parsed.token : undefined;
+    if (owner !== token) {
+        return { cleared: false, reason: `marker at ${path} is owned by a different token` };
+    }
+    try {
+        rmSync(path, { force: true });
+        return { cleared: true };
+    }
+    catch (err) {
+        return { cleared: false, reason: `removal failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/**
+ * Read the marker beside `dbFile` and classify it: a marker younger than
+ * {@link REINDEX_MARKER_TTL_MS} protects its `ms` (FR-3) — but ONLY when `ms` is an actual number
+ * (AM-4: a `ms: null` marker names no family, so it protects nothing, live or not). A marker at or
+ * past the TTL is abandoned — it is removed here (rotation must not act on stale-but-still-present
+ * state on its NEXT call). AM-6: the note reports "ignored and removed" ONLY once `rmSync` actually
+ * succeeded; a removal failure (e.g. a permission error) is reported as "ignored, removal failed:
+ * <err>" — never silently claimed as removed. No marker, or a marker this function cannot parse
+ * (corrupt / missing fields), yields `{ protectedMs: [], notes: [] }` — never a throw: a malformed
+ * marker must not abort rotation, and it also cannot honestly claim to protect anything.
+ */
+export function readLiveReindexMarkers(dbFile, now = Date.now()) {
+    const path = reindexMarkerPath(dbFile);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return { protectedMs: [], notes: [] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { protectedMs: [], notes: [] };
+    }
+    if (parsed === null || typeof parsed !== 'object')
+        return { protectedMs: [], notes: [] };
+    const { ms, startedAt } = parsed;
+    if (typeof startedAt !== 'number' || !Number.isFinite(startedAt)) {
+        return { protectedMs: [], notes: [] };
+    }
+    const hasFamily = typeof ms === 'number' && Number.isFinite(ms);
+    if (parsed.requiresRecovery === true) {
+        const label = hasFamily ? `ms=${ms}` : 'ms=(none — non-standard backupPath)';
+        return { protectedMs: hasFamily ? [ms] : [], notes: [`recovery-required reindex marker (${label}) protects its family without expiry — restore the snapshot manually, then remove ${path}`] };
+    }
+    if (now - startedAt < REINDEX_MARKER_TTL_MS) {
+        return { protectedMs: hasFamily ? [ms] : [], notes: [] };
+    }
+    // AM-6: only claim "removed" once `rmSync` actually succeeded.
+    let removalError;
+    try {
+        rmSync(path, { force: true });
+    }
+    catch (err) {
+        removalError = err instanceof Error ? err.message : String(err);
+    }
+    const label = hasFamily ? `ms=${ms}` : 'ms=(none — non-standard backupPath)';
+    const note = removalError === undefined
+        ? `stale reindex marker (${label}, startedAt=${new Date(startedAt).toISOString()}) ignored and removed`
+        : `stale reindex marker (${label}, startedAt=${new Date(startedAt).toISOString()}) ignored, removal failed: ${removalError}`;
+    return { protectedMs: [], notes: [note] };
+}
+//# sourceMappingURL=agentdb-reindex-marker.js.map

package/dist/agentdb-reindex-marker.js.map

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

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

@@ -0,0 +1,169 @@
+/**
+ * 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
+ */
+/** 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[];
+}
+/**
+ * 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 declare function scanSnapshotDir(dbFile: string): {
+    families: SnapshotFamily[];
+    scanErrors: string[];
+};
+/**
+ * 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 declare function listPreReindexSnapshots(dbFile: string): SnapshotFamily[];
+/**
+ * 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 declare function planSnapshotRotation(families: readonly SnapshotFamily[], opts: {
+    readonly keep: number;
+    readonly protectMs?: number;
+    readonly now?: number;
+    readonly graceMs?: number;
+}): SnapshotRotationPlan;
+/** Options shared by {@link rotatePreReindexSnapshotsUnlocked} and {@link rotatePreReindexSnapshots}. */
+export interface RotateSnapshotsOptions {
+    readonly keep?: number;
+    readonly protectPath?: string;
+    readonly now?: number;
+    readonly graceMs?: number;
+}
+/**
+ * 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 declare function rotatePreReindexSnapshotsUnlocked(dbFile: string, opts?: RotateSnapshotsOptions): SnapshotRotationReport;
+/**
+ * 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 declare function rotatePreReindexSnapshots(dbFile: string, opts?: RotateSnapshotsOptions & {
+    readonly lockTimeoutMs?: number;
+}): SnapshotRotationReport;
+//# sourceMappingURL=agentdb-snapshot-rotation.d.ts.map