akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/core/file-lock.js

@@ -1,11 +1,114 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
-import { isProcessAlive } from "./common.js";
+import path from "node:path";
+import { openDatabase } from "../storage/database.js";
+import { isProcessAlive, MAX_LOCK_METADATA_BYTES, readTextFileDescriptorWithLimit } from "./common.js";
+function readLockSnapshot(lockPath) {
+    let fd;
+    try {
+        fd = fs.openSync(lockPath, "r");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+    try {
+        const rawContent = readTextFileDescriptorWithLimit(fd, MAX_LOCK_METADATA_BYTES, "Lock metadata", lockPath);
+        const stat = fs.fstatSync(fd);
+        return {
+            rawContent,
+            identity: { dev: stat.dev, ino: stat.ino, size: stat.size, mtimeMs: stat.mtimeMs },
+        };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeMs === right.mtimeMs;
+}
+function operationMutexPath(lockPath) {
+    // `.sensitive` is an established non-asset suffix across stash walkers. The
+    // mutex may sit beside a secret/env lock and must never surface as an asset.
+    return path.join(path.dirname(lockPath), `.${path.basename(lockPath)}.operations.sensitive`);
+}
+/**
+ * Serialize every mutation of one canonical lock path. SQLite's write lock is
+ * released by the OS when a process dies, so this mutex needs no stale-owner
+ * deletion protocol (which would reproduce the same check/rename race it is
+ * meant to prevent).
+ */
+function withLockOperationMutex(lockPath, run) {
+    const db = openDatabase(operationMutexPath(lockPath));
+    let began = false;
+    try {
+        db.exec("PRAGMA busy_timeout = 30000");
+        for (let attempt = 0; attempt < 5 && !began; attempt += 1) {
+            db.exec("BEGIN IMMEDIATE");
+            began = db.inTransaction;
+            if (!began)
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2 ** attempt);
+        }
+        if (!began)
+            throw new Error(`Could not acquire lock operation mutex for ${lockPath}.`);
+        const result = run();
+        db.exec("COMMIT");
+        began = false;
+        return result;
+    }
+    catch (error) {
+        if (began && db.inTransaction) {
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch {
+                // Preserve the operation failure.
+            }
+        }
+        throw error;
+    }
+    finally {
+        db.close();
+    }
+}
+function tryAcquireLockRaw(lockPath, payload) {
+    try {
+        fs.writeFileSync(lockPath, payload, { flag: "wx" });
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            return undefined;
+        throw err;
+    }
+    let snapshot;
+    try {
+        snapshot = readLockSnapshot(lockPath);
+    }
+    catch (error) {
+        releaseLockRaw(lockPath);
+        throw error;
+    }
+    if (!snapshot) {
+        releaseLockRaw(lockPath);
+        throw new Error(`Could not read newly acquired lock at ${lockPath}.`);
+    }
+    return { lockPath, ...snapshot };
+}
+function releaseLockRaw(lockPath) {
+    try {
+        fs.unlinkSync(lockPath);
+    }
+    catch {
+        // Sentinel already gone — fine.
+    }
+}
 /**
  * Atomically create a sentinel at `lockPath` with `payload` as the body.
- * Returns true if we now own the lock, false if a sentinel already
+ * Returns an exact ownership handle if we now own the lock, or undefined if a sentinel already
  * exists (EEXIST). Throws any other error (permissions, missing parent
  * dir, etc.) — callers must ensure the parent directory exists.
  *
@@ -14,15 +117,11 @@ import { isProcessAlive } from "./common.js";
  * (improve.ts records pid + startedAt so audit can correlate runs).
  */
 export function tryAcquireLockSync(lockPath, payload) {
-    try {
-        fs.writeFileSync(lockPath, payload, { flag: "wx" });
-        return true;
-    }
-    catch (err) {
-        if (err.code === "EEXIST")
-            return false;
-        throw err;
-    }
+    return withLockOperationMutex(lockPath, () => tryAcquireLockRaw(lockPath, payload));
+}
+/** Build a PID-bearing payload with a unique token for one acquisition attempt. */
+export function createLockPayload(metadata = {}) {
+    return JSON.stringify({ ...metadata, pid: process.pid, lockId: randomUUID() });
 }
 /**
  * Inspect an existing sentinel at `lockPath` without modifying it.
@@ -36,70 +135,116 @@ export function tryAcquireLockSync(lockPath, payload) {
  * Does NOT remove the file. Callers decide recovery policy.
  */
 export function probeLock(lockPath, opts) {
-    let rawContent;
-    let ageMs;
-    try {
-        rawContent = fs.readFileSync(lockPath, "utf8");
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return { state: "absent" };
-        return { state: "stale", reason: "unreadable" };
-    }
+    let snapshot;
     try {
-        const stat = fs.statSync(lockPath);
-        ageMs = Date.now() - stat.mtimeMs;
+        snapshot = readLockSnapshot(lockPath);
     }
     catch {
-        // Stat failed even though read succeeded — race-y removal in flight.
-        return { state: "stale", reason: "unreadable", rawContent };
+        return { state: "stale", reason: "unreadable" };
     }
+    if (!snapshot)
+        return { state: "absent" };
+    const { rawContent, identity } = snapshot;
+    const ageMs = Date.now() - identity.mtimeMs;
     const holderPid = extractHolderPid(rawContent);
     if (holderPid === undefined) {
-        return { state: "stale", reason: "invalid_pid", ageMs, rawContent };
+        return { state: "stale", reason: "invalid_pid", ageMs, rawContent, identity };
     }
     if (!isProcessAlive(holderPid)) {
-        return { state: "stale", reason: "pid_dead", holderPid, ageMs, rawContent };
+        return { state: "stale", reason: "pid_dead", holderPid, ageMs, rawContent, identity };
     }
     if (opts?.staleAfterMs !== undefined && ageMs > opts.staleAfterMs) {
-        return { state: "stale", reason: "age_exceeded", holderPid, ageMs, rawContent };
+        return { state: "stale", reason: "age_exceeded", holderPid, ageMs, rawContent, identity };
     }
-    return { state: "held", holderPid, ageMs, rawContent };
+    return { state: "held", holderPid, ageMs, rawContent, identity };
 }
 /**
- * Remove a lock file. Idempotent — silently ignores ENOENT. Used both to
- * reclaim stale locks (after probeLock returns `state: "stale"`) and to
- * release locks we own (after a successful tryAcquireLockSync).
+ * Revalidate and quarantine the probed sentinel while holding the same operation
+ * mutex used by acquisitions. A newer owner therefore cannot be renamed in the
+ * check/quarantine window, and a third contender cannot acquire until cleanup
+ * has completed.
  */
-export function releaseLock(lockPath) {
-    try {
-        fs.unlinkSync(lockPath);
-    }
-    catch {
-        // Sentinel already gone — fine.
-    }
+export function reclaimStaleLock(lockPath, probe, options) {
+    if (probe.rawContent === undefined || probe.identity === undefined)
+        return false;
+    const expectedContent = probe.rawContent;
+    const expectedIdentity = probe.identity;
+    return withLockOperationMutex(lockPath, () => {
+        let current;
+        try {
+            current = readLockSnapshot(lockPath);
+        }
+        catch {
+            return false;
+        }
+        if (!current || current.rawContent !== expectedContent || !sameIdentity(current.identity, expectedIdentity)) {
+            return false;
+        }
+        const quarantinePath = `${lockPath}.stale-${process.pid}-${randomUUID()}`;
+        try {
+            fs.renameSync(lockPath, quarantinePath);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return false;
+            throw err;
+        }
+        let quarantined;
+        try {
+            quarantined = readLockSnapshot(quarantinePath);
+        }
+        catch {
+            quarantined = undefined;
+        }
+        if (!quarantined ||
+            quarantined.rawContent !== expectedContent ||
+            !sameIdentity(quarantined.identity, expectedIdentity)) {
+            try {
+                // Restore without replacing a non-cooperating lock installed after quarantine.
+                fs.linkSync(quarantinePath, lockPath);
+            }
+            catch (err) {
+                if (err.code !== "EEXIST")
+                    throw err;
+            }
+            releaseLockRaw(quarantinePath);
+            return false;
+        }
+        options?.afterQuarantineVerified?.();
+        try {
+            fs.unlinkSync(quarantinePath);
+            return true;
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return false;
+            throw err;
+        }
+    });
 }
 /**
- * Release a lock ONLY if it is still owned by `ownerPid`. Safe to call from a
- * `process.exit()` / `'exit'` handler as a backstop: `process.exit()` skips
- * `finally` blocks — so the normal lock-release never runs on signal death
- * (SIGTERM/SIGINT) — but it DOES fire `'exit'` listeners synchronously. Checking
- * ownership first means that if the lock was already released and re-acquired by
- * a different process, this leaves that process's lock intact (no cross-run
- * deletion / PID-reuse footgun). Synchronous so it is valid inside an exit handler.
+ * Release only the exact sentinel returned by `tryAcquireLockSync`. Content and
+ * file identity are revalidated while holding the acquisition operation mutex,
+ * so a stale holder cannot remove a successor. Synchronous and idempotent so it
+ * is safe in both `finally` blocks and process exit handlers.
  */
-export function releaseLockIfOwned(lockPath, ownerPid) {
-    let rawContent;
-    try {
-        rawContent = fs.readFileSync(lockPath, "utf8");
-    }
-    catch {
-        // Absent or unreadable — nothing of ours to release.
+export function releaseLock(ownership) {
+    const { lockPath } = ownership;
+    if (!fs.existsSync(lockPath) && !fs.existsSync(operationMutexPath(lockPath)))
         return;
-    }
-    if (extractHolderPid(rawContent) === ownerPid) {
-        releaseLock(lockPath);
-    }
+    withLockOperationMutex(lockPath, () => {
+        let current;
+        try {
+            current = readLockSnapshot(lockPath);
+        }
+        catch {
+            // Absent or unreadable — nothing of ours to release.
+            return;
+        }
+        if (current && current.rawContent === ownership.rawContent && sameIdentity(current.identity, ownership.identity)) {
+            releaseLockRaw(lockPath);
+        }
+    });
 }
 /**
  * Extract a PID from a sentinel body. Accepts the two shapes used across

package/dist/core/fs-txn.js

@@ -0,0 +1,392 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * The ONE durable filesystem-transaction engine (plan §2.2 / §4.5, Chunk 6
+ * WI-6.3). Replaces the three (+1) per-domain journal engines — proposal
+ * accept/revert, proposal reject, mv, consolidate — with a single journal
+ * home, journal format, fsync discipline, phase runner, and recovery scanner.
+ *
+ * ## Journal home
+ *
+ * `getDataDir()/txn/<rootNs24>/<transactionId>/journal.json`, namespaced by
+ * the sha256 of the resolved root the transaction mutates. Every legacy home
+ * (`proposal-transactions/`, `proposal-rejections/`, in-stash
+ * `.akm/mv-transactions/`, in-stash `consolidate-journal.json`) collapses
+ * onto this one.
+ *
+ * ## Phase model
+ *
+ * Each transaction KIND declares its ordered phase vocabulary and a commit
+ * point. A journal found at a phase strictly BEFORE the commit point rolls
+ * BACK (the batch never happened); at or after it rolls FORWARD (the kind's
+ * `finalize` resumes idempotently from the recorded phase). Phase writes are
+ * durable: tmp + fsync + rename + parent-dir fsync — the exact discipline
+ * every legacy engine used, now in one place.
+ *
+ * ## Kind handlers
+ *
+ * Domain logic (what the files are, how to roll back, which DB/index/event
+ * steps finalize) stays with the domain: each kind registers a
+ * {@link TxnKindHandler}. The engine owns discovery, safety fencing, journal
+ * I/O, ordering, and cleanup. Recovery entry points call
+ * {@link recoverTxnsForRoot} (after importing the domain registrar so the
+ * kinds are registered).
+ *
+ * ## Crash-window test seam
+ *
+ * `_setTxnMutationHookForTests` replaces the per-engine hooks; domain code
+ * fires named points through {@link txnMutationHook} exactly where the legacy
+ * engines fired theirs, so the subprocess crash runners re-key mechanically.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { getDataDir } from "./paths.js";
+import { warn } from "./warn.js";
+// ── Registry ─────────────────────────────────────────────────────────────────
+const kinds = new Map();
+/**
+ * Register (or replace) the handler for a transaction kind. Handlers are
+ * stored payload-erased; beginTxn/recovery re-associate `P` via the kind tag.
+ */
+export function registerTxnKind(kind, handler) {
+    kinds.set(kind, handler);
+}
+function requireKind(kind) {
+    const handler = kinds.get(kind);
+    if (!handler)
+        throw new Error(`No transaction handler registered for kind "${kind}".`);
+    return handler;
+}
+/** True when `kind` has a registered handler (see {@link recoverTxnsForRoot}). */
+function hasKind(kind) {
+    return kinds.has(kind);
+}
+// ── Test seam ────────────────────────────────────────────────────────────────
+let mutationHookForTests;
+/** TEST-ONLY crash-window hook used by subprocess recovery tests. */
+export function _setTxnMutationHookForTests(hook) {
+    mutationHookForTests = hook;
+}
+/** Fire a named crash-window point (no-op outside tests). */
+export function txnMutationHook(point) {
+    mutationHookForTests?.(point);
+}
+// ── Durable file I/O primitives (shared fsync discipline) ────────────────────
+export function txnHash(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+export function txnFileHash(filePath) {
+    return txnHash(fs.readFileSync(filePath));
+}
+export function fsyncTxnFile(filePath) {
+    const fd = fs.openSync(filePath, "r");
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+export function fsyncTxnDir(dirPath) {
+    try {
+        fsyncTxnFile(dirPath);
+    }
+    catch {
+        // Directory fsync is unavailable on some platforms.
+    }
+}
+/** Durably write `content` to `filePath` (tmp + fsync + rename + dir fsync). */
+export function writeTxnFileDurably(filePath, content, mode = 0o600) {
+    const tempPath = `${filePath}.tmp`;
+    fs.writeFileSync(tempPath, content, { mode });
+    fsyncTxnFile(tempPath);
+    fs.renameSync(tempPath, filePath);
+    fsyncTxnDir(path.dirname(filePath));
+}
+// ── Journal home / discovery ─────────────────────────────────────────────────
+/**
+ * Canonical spelling of a transaction root: realpath when the root exists
+ * (so symlinked spellings — e.g. a stash reached through macOS /tmp — hash
+ * to the SAME namespace and bind-compare equal), resolved otherwise.
+ */
+export function canonicalTxnRoot(root) {
+    try {
+        return fs.realpathSync(path.resolve(root));
+    }
+    catch {
+        return path.resolve(root);
+    }
+}
+/** Namespace directory for all transactions mutating `root`. */
+export function txnNamespaceDir(root) {
+    const ns = txnHash(canonicalTxnRoot(root)).slice(0, 24);
+    return path.join(getDataDir(), "txn", ns);
+}
+/** Mint a transaction id ahead of {@link beginTxn} (see its `transactionId`). */
+export function mintTxnId() {
+    return randomUUID();
+}
+/** The directory a transaction with `transactionId` on `root` will own. */
+export function txnDirFor(root, transactionId) {
+    return path.join(txnNamespaceDir(root), transactionId);
+}
+function writeJournal(txn) {
+    writeTxnFileDurably(txn.journalPath, `${JSON.stringify(txn.journal, null, 2)}\n`);
+}
+/** Durably record `phase` on the journal, then mirror it in memory. */
+export function advanceTxn(txn, phase) {
+    const handler = requireKind(txn.journal.kind);
+    if (!handler.phases.includes(phase)) {
+        throw new Error(`Unknown phase "${phase}" for transaction kind "${txn.journal.kind}".`);
+    }
+    const next = { ...txn.journal, phase };
+    writeTxnFileDurably(txn.journalPath, `${JSON.stringify(next, null, 2)}\n`);
+    txn.journal.phase = phase;
+}
+/**
+ * Open a new transaction: mint the id, create its directory, and durably
+ * write the journal at the kind's initial phase. The caller stages sidecar
+ * files under `txn.dir` and then applies/finalizes through the kind handler.
+ */
+export function beginTxn(args) {
+    const handler = requireKind(args.kind);
+    const transactionId = args.transactionId ?? randomUUID();
+    if (!/^[A-Za-z0-9._-]+$/.test(transactionId) || transactionId === "." || transactionId === "..") {
+        throw new Error(`Invalid transaction id "${transactionId}" — must be a plain path segment.`);
+    }
+    const dir = path.join(txnNamespaceDir(args.root), transactionId);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const journal = {
+        version: 1,
+        kind: args.kind,
+        phase: handler.phases[0],
+        transactionId,
+        root: canonicalTxnRoot(args.root),
+        changes: args.changes,
+        decidedAt: args.decidedAt ?? new Date().toISOString(),
+        payload: args.payload,
+    };
+    const txn = { journal, journalPath: path.join(dir, "journal.json"), dir };
+    writeJournal(txn);
+    return txn;
+}
+/** Remove a transaction directory (and its namespace dir when empty). */
+export function cleanupTxn(dir) {
+    try {
+        fs.rmSync(dir, { recursive: true, force: true });
+        try {
+            fs.rmdirSync(path.dirname(dir));
+        }
+        catch {
+            // Other transactions may still exist in the namespace.
+        }
+        return null;
+    }
+    catch (error) {
+        const message = `transaction committed but cleanup failed at ${dir}: ${error instanceof Error ? error.message : String(error)}`;
+        warn(`[txn] ${message}`);
+        return message;
+    }
+}
+/**
+ * Grace period (ms) before a transaction directory/journal with no other
+ * evidence of activity is treated as stale rather than possibly belonging to
+ * a still-running operation. Shared by {@link sweepJournallessTxnDir} (racing
+ * a sibling's mkdir→journal window, and the unknown-kind sweep in
+ * {@link recoverTxnsForRoot}) and by read-only reporting such as `akm
+ * health`'s stale-journal advisory (see {@link listTxnJournalsTolerant}).
+ */
+export const TXN_SWEEP_GRACE_MS = 300_000;
+/**
+ * Sweep a transaction directory that cannot be recovered — it has NO journal,
+ * or (from {@link recoverTxnsForRoot}) a journal whose kind has no registered
+ * handler — but only when it is demonstrably stale. All kinds share one
+ * namespace per root, so a scanner may encounter a SIBLING transaction inside
+ * `beginTxn`'s mkdir→journal window, or one whose registrar this process
+ * simply has not imported yet; a grace period keeps the sweep from racing
+ * either. Returns true when the directory was removed.
+ */
+export function sweepJournallessTxnDir(dir, graceMs = TXN_SWEEP_GRACE_MS) {
+    try {
+        const age = Date.now() - fs.statSync(dir).mtimeMs;
+        if (age < graceMs)
+            return false;
+        fs.rmSync(dir, { recursive: true, force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** True when `candidate` is inside `root` (both resolved). */
+export function isWithinTxnRoot(candidate, root) {
+    const rel = path.relative(path.resolve(root), path.resolve(candidate));
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+function readJournal(journalPath) {
+    let journal;
+    try {
+        journal = JSON.parse(fs.readFileSync(journalPath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Cannot read transaction journal at ${journalPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (journal.version !== 1 || typeof journal.kind !== "string" || typeof journal.phase !== "string") {
+        throw new Error(`Refusing unsafe transaction journal at ${journalPath}.`);
+    }
+    return journal;
+}
+/** Engine-level safety fences shared by every kind. */
+function fenceJournal(journal, txnDir, root, journalPath) {
+    if (canonicalTxnRoot(journal.root) !== canonicalTxnRoot(root)) {
+        throw new Error(`Refusing transaction journal bound to a different root at ${journalPath}.`);
+    }
+    const handler = requireKind(journal.kind);
+    if (!handler.phases.includes(journal.phase)) {
+        throw new Error(`Refusing transaction journal with unknown phase "${journal.phase}" at ${journalPath}.`);
+    }
+    for (const change of journal.changes) {
+        if (typeof change.path !== "string" || !isWithinTxnRoot(change.path, root)) {
+            throw new Error(`Refusing transaction journal touching paths outside its root at ${journalPath}.`);
+        }
+    }
+    handler.validate?.(journal, txnDir, root);
+}
+/** True when `journal.phase` is at or after the kind's commit point. */
+export function isCommittedPhase(journal) {
+    const handler = requireKind(journal.kind);
+    return handler.phases.indexOf(journal.phase) >= handler.phases.indexOf(handler.commitPhase);
+}
+/**
+ * Recover every interrupted transaction under `root`'s namespace: journals
+ * before their kind's commit point roll BACK; the rest roll FORWARD through
+ * the kind's `finalize`. Fully-finalized directories are swept. The domain
+ * registrar (which registers the kinds) must be imported by the caller.
+ *
+ * A journal whose `kind` has NO registered handler is SWEPT (same stale-dir
+ * grace period as {@link sweepJournallessTxnDir}) rather than thrown on. A
+ * kind can disappear for good — 0.9.0 deleted `akm mv` and with it the
+ * `kind:"mv"` handler — and an unrecoverable leftover journal must never
+ * brick every later recovery scan (index refresh, proposal accept/reject) run
+ * against the same root. Kinds that ARE registered keep failing LOUDLY on any
+ * fence violation: those journals may fence an interrupted, irreversible
+ * mutation. The grace period also covers the transient case where the caller
+ * has not imported a live kind's registrar yet.
+ *
+ * `filter` optionally narrows recovery (e.g. one kind, one proposal id). The
+ * unknown-kind sweep runs BEFORE the filter: such a journal is garbage no
+ * matter what the caller asked to recover, and leaving it behind is what
+ * bricks the next scan.
+ */
+export async function recoverTxnsForRoot(root, filter) {
+    const nsDir = txnNamespaceDir(root);
+    const recovered = [];
+    if (!fs.existsSync(nsDir))
+        return recovered;
+    for (const entry of fs.readdirSync(nsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(nsDir, entry.name);
+        const journalPath = path.join(dir, "journal.json");
+        if (!fs.existsSync(journalPath)) {
+            sweepJournallessTxnDir(dir);
+            continue;
+        }
+        const journal = readJournal(journalPath);
+        if (!hasKind(journal.kind)) {
+            if (sweepJournallessTxnDir(dir)) {
+                warn(`[txn] swept unrecoverable journal of unregistered kind "${journal.kind}" at ${journalPath}.`);
+            }
+            continue;
+        }
+        if (filter && !filter(journal))
+            continue;
+        fenceJournal(journal, dir, root, journalPath);
+        const handler = requireKind(journal.kind);
+        const txn = { journal, journalPath, dir };
+        const terminal = handler.phases[handler.phases.length - 1];
+        if (!isCommittedPhase(journal)) {
+            await handler.rollback(txn);
+        }
+        else if (journal.phase !== terminal) {
+            await handler.finalize(txn);
+        }
+        recovered.push(journal);
+        cleanupTxn(dir);
+    }
+    return recovered;
+}
+/**
+ * Enumerate (without recovering) every journal across ALL namespaces that
+ * matches `predicate`. Used by stash-scoped recovery entry points that don't
+ * know which roots their interrupted transactions were bound to.
+ */
+export function listTxnJournals(predicate) {
+    const home = path.join(getDataDir(), "txn");
+    const matches = [];
+    if (!fs.existsSync(home))
+        return matches;
+    for (const ns of fs.readdirSync(home, { withFileTypes: true })) {
+        if (!ns.isDirectory())
+            continue;
+        const nsDir = path.join(home, ns.name);
+        for (const entry of fs.readdirSync(nsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const journalPath = path.join(nsDir, entry.name, "journal.json");
+            if (!fs.existsSync(journalPath))
+                continue;
+            // Unreadable/invalid journals fail LOUDLY: a caller deciding what to
+            // recover must never silently overlook a damaged journal (it may fence
+            // an interrupted, irreversible mutation).
+            const journal = readJournal(journalPath);
+            if (predicate(journal))
+                matches.push(journal);
+        }
+    }
+    return matches;
+}
+/**
+ * Read-only, best-effort sibling of {@link listTxnJournals} for reporting
+ * (e.g. `akm health`'s stale-journal advisory): a corrupt `journal.json` is
+ * counted rather than thrown, so one damaged journal doesn't abort the whole
+ * scan. Recovery call sites (which must decide how to roll a journal forward
+ * or back) keep using {@link listTxnJournals} — it fails loudly on purpose,
+ * since silently skipping a damaged journal there could leave an interrupted,
+ * irreversible mutation unrecovered.
+ */
+export function listTxnJournalsTolerant(predicate) {
+    const home = path.join(getDataDir(), "txn");
+    const matches = [];
+    const unreadableMtimes = [];
+    if (!fs.existsSync(home))
+        return { matches, unreadableMtimes };
+    for (const ns of fs.readdirSync(home, { withFileTypes: true })) {
+        if (!ns.isDirectory())
+            continue;
+        const nsDir = path.join(home, ns.name);
+        for (const entry of fs.readdirSync(nsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const journalPath = path.join(nsDir, entry.name, "journal.json");
+            let mtimeMs;
+            try {
+                mtimeMs = fs.statSync(journalPath).mtimeMs;
+            }
+            catch {
+                continue; // no journal.json here, or it vanished mid-scan
+            }
+            try {
+                const journal = readJournal(journalPath);
+                if (predicate(journal))
+                    matches.push({ journal, mtimeMs });
+            }
+            catch {
+                unreadableMtimes.push(mtimeMs);
+            }
+        }
+    }
+    return { matches, unreadableMtimes };
+}