@holmes-lab/holmes-kit 0.19.6 → 0.20.0

package/dist/holmes/spec/entity-transaction.js

@@ -0,0 +1,701 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCK_STAGING_STALE_MS = exports.SOURCE_PUBLICATION_LOCATOR = exports.EntityStoreError = void 0;
+exports.entityContentVersion = entityContentVersion;
+exports.entityStat = entityStat;
+exports.entityDirectory = entityDirectory;
+exports.readEntityBytes = readEntityBytes;
+exports.publishEntityRecord = publishEntityRecord;
+exports.abandonPublishedSteps = abandonPublishedSteps;
+exports.abandonEntityOperation = abandonEntityOperation;
+exports.entityLockOwner = entityLockOwner;
+exports.entityCompletionRecord = entityCompletionRecord;
+exports.retireEntityOperation = retireEntityOperation;
+exports.assertEntityByteInput = assertEntityByteInput;
+exports.isEntityTransientName = isEntityTransientName;
+exports.observeEntityTarget = observeEntityTarget;
+exports.settleEntityTransients = settleEntityTransients;
+exports.applyEntityByteChange = applyEntityByteChange;
+exports.withEntityStoreLock = withEntityStoreLock;
+exports.withEntityStoreLockAsync = withEntityStoreLockAsync;
+exports.entityLockHolderAlive = entityLockHolderAlive;
+exports.withEntityRecoveryLock = withEntityRecoveryLock;
+// @implements A-SPEC-629, A-SPEC-627
+// @implements A-SPEC-640
+// @implements A-SPEC-639
+// @implements A-SPEC-638
+// @implements A-SPEC-634
+// @implements A-SPEC-633
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+class EntityStoreError extends Error {
+    code;
+    holmesRefusal = true;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'EntityStoreError';
+    }
+}
+exports.EntityStoreError = EntityStoreError;
+function entityContentVersion(bytes) {
+    return 'sha256:' + (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex');
+}
+function entityStat(file) {
+    try {
+        return fs.lstatSync(file);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return undefined;
+        throw e;
+    }
+}
+function entityDirectory(root, relative, create = false) {
+    let current = root;
+    if (relative === '.')
+        return current;
+    for (const part of relative.replace(/\\/g, '/').split('/').filter(Boolean)) {
+        if (part === '..' || part === '.')
+            throw new EntityStoreError('unsafe-path', 'Entity paths must be canonical relative locators.');
+        current = path.join(current, part);
+        if (create && !entityStat(current)) {
+            try {
+                fs.mkdirSync(current);
+            }
+            catch (e) {
+                if (e.code !== 'EEXIST')
+                    throw e;
+            }
+        }
+        const s = entityStat(current);
+        if (s && (!s.isDirectory() || s.isSymbolicLink()))
+            throw new EntityStoreError('unsafe-path', 'Entity directories must not be symlinks or non-directories.');
+    }
+    return current;
+}
+function readEntityBytes(file) {
+    const s = entityStat(file);
+    if (!s)
+        return undefined;
+    if (!s.isFile() || s.isSymbolicLink())
+        throw new EntityStoreError('unsafe-path', 'Entity records must be regular files.');
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+        const opened = fs.fstatSync(fd);
+        if (!opened.isFile() || opened.dev !== s.dev || opened.ino !== s.ino)
+            throw new EntityStoreError('entity-state-changed', 'Entity record changed while opening.');
+        return fs.readFileSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Stage and fsync complete bytes, then publish without replacing any existing target. */
+function publishEntityRecord(root, relative, bytes) {
+    const dir = entityDirectory(root, path.dirname(relative), true);
+    const destination = path.join(dir, path.basename(relative));
+    const temp = path.join(dir, `.entity-${(0, node_crypto_1.randomUUID)()}.tmp`);
+    const fd = fs.openSync(temp, 'wx', 0o600);
+    try {
+        fs.writeFileSync(fd, bytes);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    try {
+        fs.linkSync(temp, destination);
+    }
+    finally {
+        fs.unlinkSync(temp);
+    }
+}
+/**
+ * @implements A-SPEC-639 — roll an operation's own publications back. Steps are judged in reverse
+ * order, one verdict per locator (its last step): bytes equal to `after` are the operation's own
+ * publication and are restored to `before`; bytes equal to `before` were never published; anything
+ * else is a third state and is preserved untouched.
+ */
+function abandonPublishedSteps(root, steps) {
+    const last = new Map();
+    for (const step of steps)
+        last.set(step.locator, step);
+    const restored = [], untouched = [], preserved = [];
+    for (const step of [...steps].reverse()) {
+        if (last.get(step.locator) !== step)
+            continue;
+        const dir = entityDirectory(root, path.dirname(step.locator)), target = path.join(dir, path.basename(step.locator));
+        const bytes = readEntityBytes(target), current = bytes?.toString('base64') ?? null;
+        if (current === step.after && step.after !== step.before) {
+            const beforeMode = bytes ? ((entityStat(target).mode & 0o100) ? '100755' : '100644') : null;
+            applyEntityByteChange(root, { locator: step.locator, before: current, after: step.before, beforeMode, afterMode: step.before === null ? null : (step.beforeMode ?? '100644') });
+            restored.push(step.locator);
+        }
+        else if (current === step.before)
+            untouched.push(step.locator);
+        else
+            preserved.push(step.locator);
+    }
+    return { restored: restored.sort(), untouched: untouched.sort(), preserved: preserved.sort() };
+}
+/** @implements A-SPEC-639 — retire a pending operation as ABANDONED: its journal and owners move under `.ax/state/entity-abandoned`. */
+function abandonEntityOperation(root, operationId, locator, expectedJournalVersion, outcome) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(operationId))
+        throw new EntityStoreError('invalid-entity-state', 'Invalid operation abandonment identifier.');
+    const pending = entityDirectory(root, '.ax/state/entity-transactions/' + operationId);
+    const journal = readEntityBytes(path.join(pending, 'journal.json'));
+    if (!journal)
+        throw new EntityStoreError('invalid-entity-state', 'Operation abandonment requires its journal.');
+    if (entityContentVersion(journal) !== expectedJournalVersion)
+        throw new EntityStoreError('plan-changed', 'Abandonment cannot certify a journal different from the inspected operation.');
+    const lockOwner = entityLockOwner(root, locator);
+    if (!lockOwner)
+        throw new EntityStoreError('unknown-owner', 'Abandonment requires owned store exclusion.');
+    const record = JSON.stringify({ schema: 'holmes-entity-abandonment/1', operationId, storeLocator: locator, lockOwner, journalVersion: expectedJournalVersion, ...outcome, abandonedAt: new Date().toISOString() });
+    publishEntityRecord(root, path.join('.ax/state/entity-transactions', operationId, 'abandoned.json'), record);
+    const abandoned = entityDirectory(root, '.ax/state/entity-abandoned', true);
+    const destination = path.join(abandoned, operationId);
+    if (entityStat(destination))
+        throw new EntityStoreError('retirement-conflict', 'An abandoned operation already occupies the destination; preserve both records.');
+    fs.renameSync(pending, destination);
+}
+/** Keep the complete journal as a receipt; never expose an empty pending operation. */
+function entityLockOwner(root, locator) {
+    const dir = entityDirectory(root, path.join('.ax/state/entity-locks', (0, node_crypto_1.createHash)('sha256').update(locator).digest('hex')));
+    if (!entityStat(dir))
+        return null;
+    // @implements A-SPEC-633 — the lock can be RETIRED (renamed away by its owner) between the stat
+    // above and this read. That is "no owner", never a raw filesystem error: a read-only inspection
+    // must not fail because a writer finished. A directory that still exists without a readable
+    // record is a different thing — legacy or foreign state — and stays `unknown-owner` below.
+    // A record that was present at stat time but vanished or was replaced before the open (ENOENT,
+    // or the inode changed under the read) was retired under the reader — whatever occupies the
+    // path now, including a fresh lock a tight writer published in between. Re-read once against
+    // the current state; if that is disrupted again, there was no stable owner at this instant.
+    // The record can also be simply ABSENT at read time (stat undefined, no throw) because the
+    // generation was renamed aside and a tight writer already published the next one at this path:
+    // the directory the reader stat'ed is not the directory it is reading. Decide by directory
+    // identity: a different inode is a new generation (re-read once, then "no stable owner"); the same
+    // inode without a record is foreign or legacy state and stays `unknown-owner` below.
+    let bytes, generation = entityStat(dir);
+    for (let attempt = 0;; attempt++) {
+        let vanished = false;
+        try {
+            bytes = readEntityBytes(path.join(dir, 'owner.json'));
+        }
+        catch (e) {
+            vanished = e.code === 'ENOENT' || (e instanceof EntityStoreError && e.code === 'entity-state-changed');
+            if (!vanished)
+                throw e;
+        }
+        if (bytes)
+            break;
+        const now = entityStat(dir);
+        if (!now || !generation)
+            return null;
+        if (!vanished && now.ino === generation.ino && now.dev === generation.dev)
+            break;
+        if (attempt >= 1)
+            return null;
+        generation = now;
+    }
+    if (!bytes && !entityStat(dir))
+        return null;
+    let owner;
+    try {
+        owner = JSON.parse(bytes?.toString('utf8') ?? 'null');
+    }
+    catch {
+        throw new EntityStoreError('unknown-owner', 'Malformed initial lock owner.');
+    }
+    if (!owner || Object.keys(owner).length !== 3 || typeof owner.token !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(owner.token) || typeof owner.pid !== 'number' || !Number.isSafeInteger(owner.pid) || owner.pid <= 0 || owner.storeLocator !== locator || !bytes)
+        throw new EntityStoreError('unknown-owner', 'Initial lock ownership is invalid or missing.');
+    return { token: owner.token, version: entityContentVersion(bytes) };
+}
+function entityCompletionRecord(root, operationId, locator, journal) {
+    const lockOwner = entityLockOwner(root, locator);
+    if (!lockOwner)
+        throw new EntityStoreError('unknown-owner', 'Completion requires owned store exclusion.');
+    return JSON.stringify({ schema: 'holmes-entity-completion/1', operationId, storeLocator: locator, lockOwner, journalVersion: entityContentVersion(journal) });
+}
+function retireEntityOperation(root, operationId, locator, expectedJournalVersion) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(operationId))
+        throw new EntityStoreError('invalid-entity-state', 'Invalid operation retirement identifier.');
+    const pending = entityDirectory(root, '.ax/state/entity-transactions/' + operationId);
+    const journal = readEntityBytes(path.join(pending, 'journal.json'));
+    if (!journal)
+        throw new EntityStoreError('invalid-entity-state', 'Operation retirement requires its journal.');
+    if (entityContentVersion(journal) !== expectedJournalVersion)
+        throw new EntityStoreError('plan-changed', 'Completion cannot certify a journal different from the executed operation.');
+    const record = entityCompletionRecord(root, operationId, locator, journal);
+    const receipt = readEntityBytes(path.join(pending, 'completion.json'));
+    if (receipt && receipt.toString('utf8') !== record)
+        throw new EntityStoreError('retirement-conflict', 'Completion belongs to different inputs or ownership.');
+    if (!receipt)
+        publishEntityRecord(root, path.join('.ax/state/entity-transactions', operationId, 'completion.json'), record);
+    const completed = entityDirectory(root, '.ax/state/entity-completed', true);
+    const destination = path.join(completed, operationId);
+    if (entityStat(destination))
+        throw new EntityStoreError('retirement-conflict', 'A completed operation already occupies the destination; preserve both records.');
+    if (!readEntityBytes(path.join(pending, 'journal.json'))?.equals(journal))
+        throw new EntityStoreError('plan-changed', 'Journal changed during completion; preserve the operation and its receipt.');
+    fs.renameSync(pending, destination);
+}
+function assertEntityByteInput(root, change) {
+    const dir = entityDirectory(root, path.dirname(change.locator));
+    const target = path.join(dir, path.basename(change.locator));
+    const actual = readEntityBytes(target)?.toString('base64') ?? null;
+    if (actual !== change.before)
+        throw new EntityStoreError('external-change', 'A transaction target changed outside the store; preserve it and recover explicitly.');
+    if ('beforeMode' in change || 'afterMode' in change) {
+        for (const phase of ['before', 'after']) {
+            const mode = change[phase === 'before' ? 'beforeMode' : 'afterMode'];
+            if (change[phase] === null ? mode !== null : mode !== '100644' && mode !== '100755')
+                throw new EntityStoreError('invalid-entity-state', 'File mode and byte-presence preconditions must agree.');
+        }
+        const stat = entityStat(target), mode = stat ? (stat.mode & 0o100 ? '100755' : '100644') : null;
+        if (mode !== change.beforeMode)
+            throw new EntityStoreError('external-change', 'A transaction target mode changed outside the store; preserve it and recover explicitly.');
+    }
+}
+/**
+ * @implements A-SPEC-640 — transient names the publication primitive may leave beside a target: its
+ * temp (`.entity-<uuid>.tmp`) and the aside an update or deletion moves the original to
+ * (`<basename>.entity-aside-<uuid>`). Never tracked, never counted as foreign files.
+ */
+const TRANSIENT_TEMP = /^\.entity-[0-9a-f-]{36}\.tmp$/, TRANSIENT_ASIDE = /\.entity-aside-[0-9a-f-]{36}$/;
+function isEntityTransientName(name) { return TRANSIENT_TEMP.test(name) || TRANSIENT_ASIDE.test(name); }
+function asideEntries(dir, basename) {
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return names.filter(name => name.startsWith(basename + '.entity-aside-') && TRANSIENT_ASIDE.test(name) && name.length === basename.length + '.entity-aside-'.length + 36).sort();
+}
+const fileMode = (file) => { const s = entityStat(file); return s && s.isFile() ? ((s.mode & 0o100) ? '100755' : '100644') : null; };
+/**
+ * @implements A-SPEC-640 — read-only view of a target that sees through a lone aside: when the target
+ * is absent and exactly one aside exists beside it, the aside's bytes and mode are the target's current
+ * state (a crash between move-aside and link). Several asides are reported, not resolved.
+ */
+function observeEntityTarget(root, locator) {
+    const dir = entityDirectory(root, path.dirname(locator)), target = path.join(dir, path.basename(locator));
+    const bytes = readEntityBytes(target);
+    if (bytes)
+        return { bytes, mode: fileMode(target), asides: [] };
+    const asides = asideEntries(dir, path.basename(locator));
+    if (asides.length === 1) {
+        const file = path.join(dir, asides[0]), aside = readEntityBytes(file);
+        if (aside)
+            return { bytes: aside, mode: fileMode(file), aside: asides[0], asides };
+    }
+    return { mode: null, asides };
+}
+/**
+ * @implements A-SPEC-640 — executor-side settlement under ownership: a lone aside goes back to its
+ * absent target; temps in the steps' directories holding a step's own `after` bytes are removed.
+ * Anything else is preserved.
+ */
+function settleEntityTransients(root, steps) {
+    const restored = [], removed = [];
+    const afters = new Set(steps.map(step => step.after).filter((after) => after !== null));
+    const locators = [...new Set(steps.map(step => step.locator))];
+    const byLocator = new Map();
+    for (const step of steps)
+        byLocator.set(step.locator, [...(byLocator.get(step.locator) ?? []), step]);
+    for (const locator of locators) {
+        const dir = entityDirectory(root, path.dirname(locator));
+        if (!entityStat(dir))
+            continue;
+        const target = path.join(dir, path.basename(locator)), asides = asideEntries(dir, path.basename(locator));
+        if (!entityStat(target)) {
+            if (asides.length === 1) {
+                fs.renameSync(path.join(dir, asides[0]), target);
+                restored.push(locator);
+            }
+            continue;
+        }
+        // A step that crashed after its link and before removing its aside: the target holds the step's
+        // `after`, the aside its `before`. Only that exact pair is cleaned up; any other aside stays.
+        const current = readEntityBytes(target)?.toString('base64') ?? null;
+        for (const name of asides) {
+            const file = path.join(dir, name), bytes = readEntityBytes(file)?.toString('base64') ?? null;
+            if ((byLocator.get(locator) ?? []).some(step => step.after === current && step.before === bytes)) {
+                fs.unlinkSync(file);
+                removed.push(path.dirname(locator) === '.' ? name : path.dirname(locator) + '/' + name);
+            }
+        }
+    }
+    for (const relative of [...new Set(locators.map(locator => path.dirname(locator)))]) {
+        const dir = entityDirectory(root, relative);
+        if (!entityStat(dir))
+            continue;
+        for (const name of fs.readdirSync(dir).sort()) {
+            if (!TRANSIENT_TEMP.test(name))
+                continue;
+            const file = path.join(dir, name), s = fs.lstatSync(file);
+            if (!s.isFile() || s.isSymbolicLink())
+                continue;
+            if (afters.has(fs.readFileSync(file).toString('base64'))) {
+                fs.unlinkSync(file);
+                removed.push(relative === '.' ? name : relative + '/' + name);
+            }
+        }
+    }
+    return { restored: restored.sort(), removed: removed.sort() };
+}
+/**
+ * Changes are generated by the owning store, not executed from an untrusted recovery payload.
+ * @implements A-SPEC-640 — updates and deletions publish through a verified aside: the original is
+ * moved aside, checked byte-for-byte (and by mode) against the expected `before`, and only then the
+ * new bytes are linked into place (or the aside removed for a deletion). A foreign write inside the
+ * window is therefore refused with the original back in place; a file that appears at the target
+ * after the move-aside is refused and both files are preserved.
+ */
+function applyEntityByteChange(root, change) {
+    assertEntityByteInput(root, change);
+    if (change.before === change.after && change.beforeMode === change.afterMode)
+        return;
+    const dir = entityDirectory(root, path.dirname(change.locator), true);
+    const target = path.join(dir, path.basename(change.locator));
+    const originalMode = entityStat(target)?.mode;
+    const sameBefore = () => {
+        assertEntityByteInput(root, change);
+        return entityStat(target)?.mode === originalMode;
+    };
+    if (!sameBefore())
+        throw new EntityStoreError('external-change', 'A transaction target changed outside the store; preserve it and recover explicitly.');
+    const aside = target + '.entity-aside-' + (0, node_crypto_1.randomUUID)();
+    const moveAside = () => {
+        fs.renameSync(target, aside);
+        const bytes = readEntityBytes(aside)?.toString('base64') ?? null;
+        const modeAgrees = change.beforeMode === undefined || fileMode(aside) === change.beforeMode;
+        if (bytes !== change.before || !modeAgrees) {
+            fs.renameSync(aside, target);
+            throw new EntityStoreError('external-change', 'A transaction target changed inside the publication window; the original is back in place.');
+        }
+    };
+    if (change.after === null) {
+        moveAside();
+        fs.unlinkSync(aside);
+        return;
+    }
+    const bytes = Buffer.from(change.after, 'base64');
+    const temp = path.join(dir, `.entity-${(0, node_crypto_1.randomUUID)()}.tmp`);
+    const fd = fs.openSync(temp, 'wx', 0o600);
+    try {
+        fs.writeFileSync(fd, bytes);
+        const mode = change.afterMode === '100755' ? 0o755 : change.afterMode === '100644' ? 0o644 : originalMode === undefined ? 0o600 : originalMode & 0o777;
+        fs.fchmodSync(fd, mode);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    const publish = (message) => {
+        try {
+            fs.linkSync(temp, target);
+        }
+        catch (e) {
+            if (e.code === 'EEXIST')
+                throw new EntityStoreError('external-change', message);
+            throw e;
+        }
+    };
+    try {
+        if (!sameBefore())
+            throw new EntityStoreError('external-change', 'A transaction target changed before publication.');
+        if (change.before === null)
+            publish('A file appeared at the target during publication; it is preserved.');
+        else {
+            moveAside();
+            publish('A file appeared at the target during publication; it and the aside are preserved.');
+            fs.unlinkSync(aside);
+        }
+    }
+    finally {
+        if (entityStat(temp))
+            fs.unlinkSync(temp);
+    }
+}
+function retireOwnedLock(root, dir, expected, owned) {
+    const current = entityStat(dir);
+    if (current?.dev !== expected.dev || current?.ino !== expected.ino)
+        throw new EntityStoreError('unknown-owner', 'Lock directory changed before retirement.');
+    for (const name of fs.readdirSync(dir))
+        if (!owned.has(path.join(dir, name)))
+            throw new EntityStoreError('cleanup-conflict', 'Unknown lock contents must be preserved.');
+    const retired = entityDirectory(root, '.ax/state/entity-retired-locks', true);
+    const destination = path.join(retired, (0, node_crypto_1.randomUUID)());
+    if (entityStat(destination))
+        throw new EntityStoreError('retirement-conflict', 'Lock retirement destination is occupied.');
+    // Release the active pathname in one step, retaining owner evidence until then.
+    fs.renameSync(dir, destination);
+    for (const file of owned)
+        fs.unlinkSync(path.join(destination, path.basename(file)));
+    fs.rmdirSync(destination);
+}
+/** The shared source-publication coordination namespace, independent of every configured spec store (A-SPEC-634: exported so recovery can release it without importing the renumber module). */
+exports.SOURCE_PUBLICATION_LOCATOR = '.ax/state/entity-renumber-source-publication';
+/** Age after which a `.staging-*` entry beside the locks is treated as abandoned by a publisher that died before its rename (A-SPEC-633). */
+exports.LOCK_STAGING_STALE_MS = 10 * 60_000;
+/** Never steals a live or uncertain hold by age. Crash-owner recovery is a separate act. */
+function acquireEntityStoreLock(root, locator) {
+    const locks = entityDirectory(root, path.join('.ax', 'state', 'entity-locks'), true);
+    const dir = path.join(locks, (0, node_crypto_1.createHash)('sha256').update(locator).digest('hex'));
+    // @implements A-SPEC-633 — the lock APPEARS atomically. Measured 2026-09-13 with the previous
+    // mkdir-then-write order: a reader looping entityLockOwner beside a looping writer saw the
+    // directory before its owner record 17,518 times in four seconds. So the owner record is written
+    // and fsynced inside a private staging directory, and the staging directory is renamed into the
+    // lock path: a contender observes no lock or a complete one, and loses the rename with
+    // EEXIST/ENOTEMPTY (POSIX) or EPERM/EEXIST (Windows) — all "busy", never "unknown owner".
+    sweepAbandonedStaging(locks);
+    // An existing directory is busy whatever it holds: rename(2) would silently REPLACE an empty
+    // one, and an empty lock directory is exactly the legacy/foreign state that must be preserved
+    // for explicit recovery (a live winner between this check and the rename loses it with
+    // ENOTEMPTY/EEXIST below).
+    if (entityStat(dir))
+        throw new EntityStoreError('store-busy', 'Entity store is owned by another or interrupted operation; inspect before recovery.');
+    const staging = path.join(locks, '.staging-' + (0, node_crypto_1.randomUUID)()), token = (0, node_crypto_1.randomUUID)();
+    fs.mkdirSync(staging);
+    const record = JSON.stringify({ token, pid: process.pid, storeLocator: locator });
+    try {
+        // No fsync: the guarantee is atomic VISIBILITY to concurrent processes (the rename), not
+        // durability across power loss — the previous protocol never synced either, and measured
+        // 2026-09-13 an fsync per acquisition cut throughput from thousands to ~76 per second, on a
+        // lock every adopted-store read takes.
+        fs.writeFileSync(path.join(staging, 'owner.json'), record, { flag: 'wx', mode: 0o600 });
+        fs.renameSync(staging, dir);
+    }
+    catch (e) {
+        try {
+            fs.rmSync(staging, { recursive: true, force: true });
+        }
+        catch { /* best effort */ }
+        const code = e.code;
+        if (code === 'EEXIST' || code === 'ENOTEMPTY' || code === 'EPERM')
+            throw new EntityStoreError('store-busy', 'Entity store is owned by another or interrupted operation; inspect before recovery.');
+        throw e;
+    }
+    const ownership = fs.lstatSync(dir);
+    const release = () => {
+        const current = entityStat(dir);
+        if (current?.dev === ownership.dev && current?.ino === ownership.ino) {
+            const ownerFile = path.join(dir, 'owner.json');
+            const owner = readEntityBytes(ownerFile);
+            if (owner && JSON.parse(owner.toString('utf8')).token === token) {
+                retireOwnedLock(root, dir, ownership, new Set([ownerFile]));
+            }
+        }
+    };
+    return release;
+}
+/** Remove `.staging-*` entries older than the bound: a publisher that died before its rename. Younger entries may belong to a live acquirer; hashed lock directories are never touched. */
+function sweepAbandonedStaging(locks) {
+    let names;
+    try {
+        names = fs.readdirSync(locks);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (!name.startsWith('.staging-'))
+            continue;
+        const entry = path.join(locks, name);
+        try {
+            if (Date.now() - fs.lstatSync(entry).mtimeMs > exports.LOCK_STAGING_STALE_MS)
+                fs.rmSync(entry, { recursive: true, force: true });
+        }
+        catch { /* raced with its owner or already gone */ }
+    }
+}
+function withEntityStoreLock(root, locator, act) {
+    const release = acquireEntityStoreLock(root, locator);
+    try {
+        return act();
+    }
+    finally {
+        release();
+    }
+}
+/** Keep ownership through asynchronous repository lookups and final publication. */
+async function withEntityStoreLockAsync(root, locator, act) {
+    const release = acquireEntityStoreLock(root, locator);
+    try {
+        const result = act();
+        // Synchronous activated publication is already complete. Do not retain its
+        // lock for an artificial microtask and turn a stale-version error into busy.
+        return result instanceof Promise ? await result : result;
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * @implements A-SPEC-638 — whether the current generation of a store lock is held by a live process.
+ * Follows the owner/successor chain the recovery lock follows; a missing, malformed or released
+ * chain end, or a holder that no longer answers a signal probe, is "not alive".
+ */
+function entityLockHolderAlive(root, locator) {
+    const dir = entityDirectory(root, path.join('.ax/state/entity-locks', (0, node_crypto_1.createHash)('sha256').update(locator).digest('hex')));
+    if (!entityStat(dir))
+        return false;
+    const claims = path.join(root, '.ax/state/entity-recovery-claims', (0, node_crypto_1.createHash)('sha256').update(locator).digest('hex'));
+    let file = path.join(dir, 'owner.json');
+    for (let depth = 0; depth < 128; depth++) {
+        let owner;
+        try {
+            owner = JSON.parse(readEntityBytes(file)?.toString('utf8') ?? 'null');
+        }
+        catch {
+            return false;
+        }
+        if (!owner || typeof owner.token !== 'string' || !Number.isSafeInteger(owner.pid) || owner.pid <= 0)
+            return false;
+        const successor = [path.join(dir, 'successor-' + owner.token + '.json'), path.join(claims, 'successor-' + owner.token + '.json')].find(candidate => entityStat(candidate));
+        if (successor) {
+            file = successor;
+            continue;
+        }
+        if (owner.released)
+            return false;
+        // A generation this very process holds is not a foreign publication in progress: whoever wrote
+        // the pending record under an earlier generation is gone, or we could not hold the lock now.
+        if (owner.pid === process.pid)
+            return false;
+        try {
+            process.kill(owner.pid, 0);
+            return true;
+        }
+        catch (e) {
+            return e.code !== 'ESRCH';
+        }
+    }
+    return false;
+}
+/** Claim a dead owner's immutable generation without deleting or replacing its lock. */
+function withEntityRecoveryLock(root, locator, act) {
+    const relative = path.join('.ax/state/entity-locks', (0, node_crypto_1.createHash)('sha256').update(locator).digest('hex'));
+    const dir = entityDirectory(root, relative);
+    if (!entityStat(dir))
+        return withEntityStoreLock(root, locator, act);
+    const directory = fs.lstatSync(dir), records = [], tokens = new Set();
+    let file = path.join(dir, 'owner.json');
+    const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+    for (let depth = 0; depth < 128; depth++) {
+        const bytes = readEntityBytes(file);
+        let owner;
+        try {
+            owner = JSON.parse(bytes?.toString('utf8') ?? 'null');
+        }
+        catch {
+            throw new EntityStoreError('unknown-owner', 'Malformed lock ownership must be preserved.');
+        }
+        if (!owner || !uuid.test(owner.token) || !Number.isSafeInteger(owner.pid) || owner.pid <= 0 || owner.storeLocator !== locator || Object.keys(owner).some(k => !['token', 'pid', 'storeLocator', 'released'].includes(k)) || (owner.released !== undefined && owner.released !== true) || (records.length === 0 && owner.released) || tokens.has(owner.token))
+            throw new EntityStoreError('unknown-owner', 'Invalid or cyclic lock ownership must be preserved.');
+        tokens.add(owner.token);
+        records.push(file);
+        if (!owner.released) {
+            try {
+                process.kill(owner.pid, 0);
+                throw new EntityStoreError('store-busy', 'The lock owner is still running; elapsed time does not permit recovery.');
+            }
+            catch (e) {
+                if (e.code !== 'ESRCH')
+                    throw e instanceof EntityStoreError ? e : new EntityStoreError('unknown-owner', 'Cannot establish that the lock owner stopped.');
+            }
+        }
+        const legacySuccessor = path.join(dir, 'successor-' + owner.token + '.json');
+        const claims = entityDirectory(root, path.join('.ax/state/entity-recovery-claims', (0, node_crypto_1.createHash)('sha256').update(locator).digest('hex')), true);
+        const externalSuccessor = path.join(claims, 'successor-' + owner.token + '.json');
+        if (entityStat(legacySuccessor) && entityStat(externalSuccessor))
+            throw new EntityStoreError('unknown-owner', 'Conflicting ownership generations must be preserved.');
+        const successor = entityStat(legacySuccessor) ? legacySuccessor : externalSuccessor;
+        if (entityStat(successor)) {
+            file = successor;
+            continue;
+        }
+        const claim = { token: (0, node_crypto_1.randomUUID)(), pid: process.pid, storeLocator: locator };
+        try {
+            publishEntityRecord(root, path.relative(root, successor), JSON.stringify(claim));
+        }
+        catch (e) {
+            if (e.code === 'EEXIST')
+                throw new EntityStoreError('store-busy', 'Another recovery owns this generation.');
+            throw e;
+        }
+        records.push(successor);
+        try {
+            const current = entityStat(dir);
+            if (current?.dev !== directory.dev || current?.ino !== directory.ino)
+                throw new EntityStoreError('unknown-owner', 'Lock directory changed during recovery claim.');
+            // Only known generation files and their same-inode publication hardlinks belong to us.
+            // External generation claims survive retirement so delayed contenders cannot
+            // claim an old token against a newer directory at the reused active path.
+            const localRecords = records.filter(r => path.dirname(r) === dir);
+            const owned = new Set(localRecords);
+            const inodes = localRecords.map(r => fs.lstatSync(r));
+            for (const name of fs.readdirSync(dir)) {
+                const candidate = path.join(dir, name);
+                if (owned.has(candidate))
+                    continue;
+                const s = fs.lstatSync(candidate);
+                if (/^\.entity-[0-9a-f-]+\.tmp$/.test(name) && s.isFile() && !s.isSymbolicLink() && inodes.some(i => i.dev === s.dev && i.ino === s.ino))
+                    owned.add(candidate);
+                else
+                    throw new EntityStoreError('cleanup-conflict', 'Unknown lock contents are preserved for inspection.');
+            }
+            const result = act();
+            retireOwnedLock(root, dir, directory, owned);
+            return result;
+        }
+        catch (e) {
+            // A failed live recovery must not strand its PID as an active owner forever.
+            // Mark only our generation released; another claimant appends a new generation.
+            const bytes = readEntityBytes(successor);
+            if (bytes?.toString('utf8') === JSON.stringify(claim))
+                applyEntityByteChange(root, { locator: path.relative(root, successor), before: bytes.toString('base64'), after: Buffer.from(JSON.stringify({ ...claim, released: true })).toString('base64') });
+            throw e;
+        }
+    }
+    throw new EntityStoreError('unknown-owner', 'Recovery ownership chain exceeds the supported inspection bound.');
+}