@holmes-lab/holmes-kit 0.19.6 → 0.20.0

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

@@ -0,0 +1,1051 @@
+"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.LEGACY_RENUMBER_JOURNAL_SCHEMA = exports.entityContentVersion = exports.EntityStoreError = void 0;
+exports.entityStoreBinding = entityStoreBinding;
+exports.validateEntityAdoptionPlan = validateEntityAdoptionPlan;
+exports.entityAdoptionTarget = entityAdoptionTarget;
+exports.assertNoPendingEntityPublication = assertNoPendingEntityPublication;
+exports.inspectEntityStore = inspectEntityStore;
+exports.planEntityAdoption = planEntityAdoption;
+exports.assertEntityRepositoryReadable = assertEntityRepositoryReadable;
+exports.readEntityRepositorySnapshot = readEntityRepositorySnapshot;
+exports.readEntityRenumberSnapshot = readEntityRenumberSnapshot;
+exports.withEntityRenumberSnapshot = withEntityRenumberSnapshot;
+exports.writeEntityRepository = writeEntityRepository;
+exports.planEntityRecovery = planEntityRecovery;
+exports.validateEntityRecoveryPlan = validateEntityRecoveryPlan;
+exports.entityRecoveryTarget = entityRecoveryTarget;
+exports.recoverEntityStore = recoverEntityStore;
+exports.adoptEntityStore = adoptEntityStore;
+// @implements A-SPEC-629, A-SPEC-628, A-SPEC-627, A-SPEC-627.1
+// @implements A-SPEC-640
+// @implements A-SPEC-639
+// @implements A-SPEC-638
+// @implements A-SPEC-634
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const spec_parser_1 = require("./spec-parser");
+const spec_types_1 = require("./spec-types");
+const root_1 = require("../project/root");
+const workspace_identity_1 = require("../project/workspace-identity");
+const entity_transaction_1 = require("./entity-transaction");
+var entity_transaction_2 = require("./entity-transaction");
+Object.defineProperty(exports, "EntityStoreError", { enumerable: true, get: function () { return entity_transaction_2.EntityStoreError; } });
+Object.defineProperty(exports, "entityContentVersion", { enumerable: true, get: function () { return entity_transaction_2.entityContentVersion; } });
+function entityStoreBinding(storeRoot) {
+    const store = path.resolve(storeRoot);
+    let ancestor = store;
+    while (!(0, entity_transaction_1.entityStat)(ancestor) && path.dirname(ancestor) !== ancestor)
+        ancestor = path.dirname(ancestor);
+    const resolved = (0, root_1.resolveProjectRoot)(ancestor, { includeGit: false });
+    if (resolved.marker !== '.ax')
+        throw new entity_transaction_1.EntityStoreError('missing-workspace', 'The configured store must belong to a Holmes workspace.');
+    const root = fs.realpathSync(resolved.root);
+    // The workspace may be reached through a platform alias (/var on macOS).
+    // Normalize that prefix only; retain components inside it for symlink checks.
+    let spelling = ancestor;
+    while (fs.realpathSync(spelling) !== root && path.dirname(spelling) !== spelling)
+        spelling = path.dirname(spelling);
+    if (fs.realpathSync(spelling) !== root)
+        throw new entity_transaction_1.EntityStoreError('foreign-store', 'The configured store does not descend from the workspace.');
+    const relative = path.relative(spelling, store);
+    if (!relative || relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative))
+        throw new entity_transaction_1.EntityStoreError('foreign-store', 'The configured store must be a directory within the workspace.');
+    (0, entity_transaction_1.entityDirectory)(root, '.ax');
+    (0, entity_transaction_1.entityDirectory)(root, relative);
+    const canonical = physicalStoreLocator(root, relative);
+    const registrations = (0, entity_transaction_1.entityDirectory)(root, '.ax/entities/stores');
+    let registeredLocator;
+    if ((0, entity_transaction_1.entityStat)(registrations))
+        for (const name of fs.readdirSync(registrations).filter(name => name.endsWith('.json'))) {
+            const record = object(recordJson(path.join(registrations, name)), ['schema', 'workspaceId', 'storeId', 'storeLocator', 'adoptionDigest']);
+            if (record.schema !== 'holmes-entity-store/1' || !validUuid(record.workspaceId) || !validUuid(record.storeId) || name !== record.storeId + '.json' || !locator(record.storeLocator) || typeof record.adoptionDigest !== 'string' || !DIGEST.test(record.adoptionDigest))
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid entity store registration.');
+            if (physicalStoreLocator(root, record.storeLocator) !== canonical)
+                continue;
+            if (registeredLocator !== undefined)
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Multiple registrations identify the same physical store.');
+            registeredLocator = record.storeLocator;
+        }
+    // Keep an existing registration's persisted spelling; new stores use actual directory entries.
+    return { root, store: path.join(root, canonical), locator: registeredLocator ?? canonical };
+}
+function physicalStoreLocator(root, relative) {
+    (0, entity_transaction_1.entityDirectory)(root, relative);
+    const parts = relative.split(/[\\/]/), resolved = [];
+    let directory = root;
+    for (let index = 0; index < parts.length; index++) {
+        const part = parts[index];
+        let names, wanted;
+        try {
+            names = fs.readdirSync(directory);
+            wanted = fs.lstatSync(path.join(directory, part), { bigint: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [...resolved, ...parts.slice(index)].join('/');
+            throw error;
+        }
+        let name = part;
+        if (!names.includes(part)) {
+            const matches = names.filter(candidate => {
+                const actual = fs.lstatSync(path.join(directory, candidate), { bigint: true });
+                return actual.isDirectory() && !actual.isSymbolicLink() && actual.dev === wanted.dev && actual.ino === wanted.ino;
+            });
+            if (matches.length !== 1)
+                throw new entity_transaction_1.EntityStoreError('unsafe-path', 'Cannot uniquely bind the configured store to its physical directory entry.');
+            name = matches[0];
+        }
+        resolved.push(name);
+        directory = path.join(directory, name);
+    }
+    return resolved.join('/');
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+function object(value, keys) {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length !== keys.length || keys.some(k => !Object.prototype.hasOwnProperty.call(value, k)))
+        throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Unsupported entity record schema or fields.');
+    return value;
+}
+function validUuid(v) { return typeof v === 'string' && UUID.test(v); }
+function locator(v) {
+    return typeof v === 'string' && v.length > 0 && !/[\\:\x00]/.test(v) && v.split('/').every(p => p.length > 0 && p !== '.' && p !== '..');
+}
+function recordJson(file) {
+    const bytes = (0, entity_transaction_1.readEntityBytes)(file);
+    if (!bytes)
+        throw new entity_transaction_1.EntityStoreError('entity-state-changed', 'An entity record disappeared.');
+    try {
+        return JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Entity state contains malformed JSON.');
+    }
+}
+function validateEntityAdoptionPlan(value) {
+    const p = object(value, ['schema', 'operationId', 'workspaceId', 'storeId', 'storeLocator', 'entries']);
+    if (p.schema !== 'holmes-entity-adoption/1' || !validUuid(p.operationId) || !validUuid(p.workspaceId) || !validUuid(p.storeId) || !locator(p.storeLocator) || !Array.isArray(p.entries))
+        throw new entity_transaction_1.EntityStoreError('invalid-plan', 'Invalid adoption plan identifiers or schema.');
+    const entities = new Set(), ids = new Set(), paths = new Set();
+    const entries = p.entries.map(value => {
+        const e = object(value, ['entityId', 'displayId', 'documentLocator', 'version']);
+        if (!validUuid(e.entityId) || typeof e.displayId !== 'string' || !e.displayId || !locator(e.documentLocator) || !e.documentLocator.endsWith('.md') || typeof e.version !== 'string' || !DIGEST.test(e.version))
+            throw new entity_transaction_1.EntityStoreError('invalid-plan', 'Invalid adoption inventory entry.');
+        if (entities.has(e.entityId) || ids.has(e.displayId) || paths.has(e.documentLocator))
+            throw new entity_transaction_1.EntityStoreError('invalid-plan', 'Duplicate adoption identity or document.');
+        entities.add(e.entityId);
+        ids.add(e.displayId);
+        paths.add(e.documentLocator);
+        return { entityId: e.entityId, displayId: e.displayId, documentLocator: e.documentLocator, version: e.version };
+    });
+    return { schema: 'holmes-entity-adoption/1', operationId: p.operationId, workspaceId: p.workspaceId, storeId: p.storeId, storeLocator: p.storeLocator, entries };
+}
+function entityAdoptionTarget(plan) { return 'entity-store:adopt:' + (0, entity_transaction_1.entityContentVersion)(JSON.stringify(plan)); }
+function registration(bound) {
+    const dir = (0, entity_transaction_1.entityDirectory)(bound.root, path.join('.ax', 'entities', 'stores'));
+    if (!(0, entity_transaction_1.entityStat)(dir))
+        return undefined;
+    let found;
+    for (const name of fs.readdirSync(dir).sort()) {
+        if (!name.endsWith('.json'))
+            continue;
+        const r = object(recordJson(path.join(dir, name)), ['schema', 'workspaceId', 'storeId', 'storeLocator', 'adoptionDigest']);
+        if (r.schema !== 'holmes-entity-store/1' || !validUuid(r.workspaceId) || !validUuid(r.storeId) || name !== r.storeId + '.json' || !locator(r.storeLocator) || typeof r.adoptionDigest !== 'string' || !DIGEST.test(r.adoptionDigest))
+            throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid entity store registration.');
+        if (r.storeLocator === bound.locator) {
+            if (found)
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Multiple registrations name the configured store.');
+            found = r;
+        }
+    }
+    return found;
+}
+/** @implements A-SPEC-638 — a registered store whose subtree strictly contains or is contained by the bound locator. */
+function overlappingRegistration(bound) {
+    const dir = (0, entity_transaction_1.entityDirectory)(bound.root, path.join('.ax', 'entities', 'stores'));
+    if (!(0, entity_transaction_1.entityStat)(dir))
+        return undefined;
+    for (const name of fs.readdirSync(dir).sort()) {
+        if (!name.endsWith('.json'))
+            continue;
+        const r = object(recordJson(path.join(dir, name)), ['schema', 'workspaceId', 'storeId', 'storeLocator', 'adoptionDigest']);
+        if (r.schema !== 'holmes-entity-store/1' || !validUuid(r.workspaceId) || !validUuid(r.storeId) || name !== r.storeId + '.json' || !locator(r.storeLocator) || typeof r.adoptionDigest !== 'string' || !DIGEST.test(r.adoptionDigest))
+            throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid entity store registration.');
+        const registered = r.storeLocator;
+        if (registered !== bound.locator && (registered.startsWith(bound.locator + '/') || bound.locator.startsWith(registered + '/')))
+            return r;
+    }
+    return undefined;
+}
+function assertNoOverlap(bound) {
+    const overlap = overlappingRegistration(bound);
+    if (overlap)
+        throw new entity_transaction_1.EntityStoreError('store-overlap', 'This store overlaps the registered store ' + overlap.storeLocator + '.');
+}
+/** @implements A-SPEC-638 — the raw legacy renumber's rollback journal: the original bytes of every file it touches. */
+exports.LEGACY_RENUMBER_JOURNAL_SCHEMA = 'holmes-legacy-renumber-journal/1';
+function legacyRenumberJournal(raw, operationId) {
+    const j = object(raw, ['schema', 'operationId', 'workspaceId', 'storeLocator', 'oldBase', 'newBase', 'changes']);
+    if (j.schema !== exports.LEGACY_RENUMBER_JOURNAL_SCHEMA || j.operationId !== operationId || !validUuid(j.workspaceId) || !locator(j.storeLocator) || typeof j.oldBase !== 'string' || typeof j.newBase !== 'string' || !Array.isArray(j.changes))
+        throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid legacy renumber journal.');
+    const seen = new Set();
+    const changes = j.changes.map(value => {
+        const c = object(value, ['locator', 'before']);
+        if (!locator(c.locator) || !(c.before === null || (typeof c.before === 'string' && Buffer.from(c.before, 'base64').toString('base64') === c.before)) || seen.has(c.locator))
+            throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid legacy renumber journal change.');
+        seen.add(c.locator);
+        return { locator: c.locator, before: c.before };
+    });
+    return { schema: exports.LEGACY_RENUMBER_JOURNAL_SCHEMA, operationId, workspaceId: j.workspaceId, storeLocator: j.storeLocator, oldBase: j.oldBase, newBase: j.newBase, changes };
+}
+/** Inspection may use committed identity before local replica registration; pending writes still block it. */
+function assertNoPendingEntityPublication(storeRoot) {
+    assertNoPending(entityStoreBinding(storeRoot));
+}
+function assertNoPending(bound) {
+    const dir = (0, entity_transaction_1.entityDirectory)(bound.root, path.join('.ax', 'state', 'entity-transactions'));
+    if (!(0, entity_transaction_1.entityStat)(dir))
+        return;
+    for (const name of fs.readdirSync(dir)) {
+        const op = (0, entity_transaction_1.entityDirectory)(dir, name);
+        // @implements A-SPEC-634 — a pending directory without a journal is an operation that died
+        // between taking its locks and publishing; name it, do not fail on the missing record.
+        if (!(0, entity_transaction_1.readEntityBytes)(path.join(op, 'journal.json')))
+            throw new entity_transaction_1.EntityStoreError('recovery-required', 'Operation ' + name + ' was interrupted before its journal existed; inspect entity_store recovery-plan and recover it.');
+        const raw = recordJson(path.join(op, 'journal.json'));
+        if (raw?.schema === 'holmes-entity-integration-journal/1') {
+            const journal = object(raw, ['schema', 'plan', 'storeOwner', 'sourceOwner']);
+            const plan = journal.plan;
+            if (!plan || plan.operationId !== name || !validUuid(plan.operationId) || !locator(plan.storeLocator))
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid integration transaction binding.');
+            if (plan.storeLocator === bound.locator)
+                throw new entity_transaction_1.EntityStoreError('recovery-required', 'Integration publication is pending; inspect and recover that operation.');
+            continue;
+        }
+        if (['holmes-entity-renumber-journal/1', 'holmes-entity-renumber-journal/2'].includes(raw?.schema ?? '')) {
+            const journal = object(raw, raw.schema === 'holmes-entity-renumber-journal/2' ? ['schema', 'plan', 'sourceOwner'] : ['schema', 'plan']);
+            const plan = journal.plan;
+            if (!plan || plan.operationId !== name || !validUuid(plan.operationId) || !locator(plan.snapshot?.storeLocator))
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid renumber transaction binding.');
+            if (plan.snapshot.storeLocator === bound.locator)
+                throw new entity_transaction_1.EntityStoreError('recovery-required', 'Renumber publication is pending; use entity_renumber recovery.');
+            continue;
+        }
+        if (raw?.schema === exports.LEGACY_RENUMBER_JOURNAL_SCHEMA) {
+            // @implements A-SPEC-638 — an interrupted raw legacy renumber blocks its store until rolled back;
+            // while its holder is still alive the journal is a publication in progress, not an interruption.
+            const journal = legacyRenumberJournal(raw, name);
+            if (journal.storeLocator === bound.locator && !(0, entity_transaction_1.entityLockHolderAlive)(bound.root, bound.locator))
+                throw new entity_transaction_1.EntityStoreError('recovery-required', 'Legacy renumber was interrupted; inspect entity_store recovery-plan and recover it.');
+            continue;
+        }
+        if (raw?.schema === 'holmes-entity-write-journal/1') {
+            const journal = object(raw, ['schema', 'operationId', 'workspaceId', 'storeId', 'storeLocator', 'changes']);
+            if (journal.operationId !== name || !validUuid(journal.operationId) || !validUuid(journal.workspaceId) || !validUuid(journal.storeId) || !locator(journal.storeLocator) || !Array.isArray(journal.changes))
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid document transaction journal.');
+            if (journal.storeLocator === bound.locator)
+                throw new entity_transaction_1.EntityStoreError('recovery-required', 'Document publication was interrupted; inspect its journal before recovery.');
+            continue;
+        }
+        const journal = object(raw, ['schema', 'plan']);
+        if (journal.schema !== 'holmes-entity-adoption-journal/1')
+            throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Unknown entity transaction journal.');
+        const plan = validateEntityAdoptionPlan(journal.plan);
+        if (plan.operationId !== name)
+            throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Transaction directory does not match its operation.');
+        if (plan.storeLocator === bound.locator)
+            throw new entity_transaction_1.EntityStoreError('recovery-required', 'Entity adoption was interrupted; inspect its journal before recovery.');
+    }
+}
+function assertUnactivated(bound) {
+    assertNoPending(bound);
+    if (registration(bound))
+        throw new entity_transaction_1.EntityStoreError('entity-state-present', 'This store is already activated.');
+    assertNoOverlap(bound);
+}
+function inspectEntityStore(storeRoot) {
+    const bound = entityStoreBinding(storeRoot);
+    assertNoPending(bound);
+    const active = registration(bound);
+    if (active) {
+        validateMappedInventory(bound, active);
+        return { ok: true, state: 'active', storeLocator: bound.locator, storeId: active.storeId };
+    }
+    // @implements A-SPEC-638 — a path inside (or above) a registered store is never a legacy store.
+    assertNoOverlap(bound);
+    return { ok: true, state: 'legacy', storeLocator: bound.locator };
+}
+function planEntityAdoption(storeRoot) {
+    const bound = entityStoreBinding(storeRoot);
+    const identity = (0, workspace_identity_1.workspaceIdentity)(bound.root);
+    if (identity.state !== 'registered')
+        throw new workspace_identity_1.WorkspaceIdentityError('unregistered', 'Register workspace identity before planning entity adoption.');
+    assertUnactivated(bound);
+    return { schema: 'holmes-entity-adoption/1', operationId: (0, node_crypto_1.randomUUID)(), workspaceId: identity.workspaceId, storeId: (0, node_crypto_1.randomUUID)(), storeLocator: bound.locator, entries: inventory(bound) };
+}
+function inventory(bound, excluded = new Set()) {
+    const entries = [], ids = new Set();
+    function walk(dir) {
+        if (!(0, entity_transaction_1.entityStat)(dir))
+            return;
+        for (const name of fs.readdirSync(dir).sort()) {
+            const file = path.join(dir, name), s = fs.lstatSync(file);
+            if (s.isSymbolicLink())
+                throw new entity_transaction_1.EntityStoreError('unsafe-path', 'Adoption inventory cannot follow symlinks.');
+            if (s.isDirectory()) {
+                walk(file);
+                continue;
+            }
+            if (!name.endsWith('.md'))
+                continue;
+            if (excluded.has(path.relative(bound.store, file).split(path.sep).join('/')))
+                continue;
+            if (!s.isFile())
+                throw new entity_transaction_1.EntityStoreError('unsafe-path', 'Markdown inventory must contain regular files.');
+            const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+            let bytes;
+            try {
+                const opened = fs.fstatSync(fd);
+                if (!opened.isFile() || opened.dev !== s.dev || opened.ino !== s.ino)
+                    throw new entity_transaction_1.EntityStoreError('inventory-changed', 'Inventory changed while opening; retry planning.');
+                bytes = fs.readFileSync(fd);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            let displayId;
+            try {
+                displayId = (0, spec_parser_1.parseSpec)(bytes.toString('utf8')).id;
+            }
+            catch {
+                throw new entity_transaction_1.EntityStoreError('invalid-inventory', 'A Markdown document could not be parsed: ' + path.relative(bound.store, file));
+            }
+            if (!displayId || ids.has(displayId))
+                throw new entity_transaction_1.EntityStoreError('invalid-inventory', 'Missing or duplicate display ID in adoption inventory.');
+            ids.add(displayId);
+            entries.push({ entityId: (0, node_crypto_1.randomUUID)(), displayId, documentLocator: path.relative(bound.store, file).split(path.sep).join('/'), version: (0, entity_transaction_1.entityContentVersion)(bytes) });
+        }
+    }
+    walk(bound.store);
+    return entries;
+}
+function allEntityRecords(bound) {
+    const dir = (0, entity_transaction_1.entityDirectory)(bound.root, path.join('.ax', 'entities', 'records'));
+    const records = [];
+    if ((0, entity_transaction_1.entityStat)(dir))
+        for (const name of fs.readdirSync(dir).sort()) {
+            if (!name.endsWith('.json'))
+                continue;
+            const r = object(recordJson(path.join(dir, name)), ['schema', 'workspaceId', 'storeId', 'entityId', 'displayId', 'documentLocator', 'origin']);
+            const origin = object(r.origin, ['kind', 'operationId']);
+            if (r.schema !== 'holmes-entity/1' || !validUuid(r.workspaceId) || !validUuid(r.storeId) || !validUuid(r.entityId) || name !== r.entityId + '.json' || typeof r.displayId !== 'string' || !r.displayId || !locator(r.documentLocator) || !['adopted', 'created'].includes(String(origin.kind)) || !validUuid(origin.operationId))
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid entity mapping.');
+            records.push(r);
+        }
+    return records;
+}
+function validateMappedInventory(bound, active) {
+    const identity = (0, workspace_identity_1.workspaceIdentity)(bound.root);
+    if (identity.state !== 'registered' || identity.workspaceId !== active.workspaceId)
+        throw new entity_transaction_1.EntityStoreError('workspace-mismatch', 'Entity registration does not match the registered workspace.');
+    const records = allEntityRecords(bound).filter(record => record.storeId === active.storeId);
+    const docs = inventory(bound);
+    if (records.length !== docs.length || records.some(r => r.workspaceId !== active.workspaceId) || new Set(records.map(r => r.displayId)).size !== records.length || new Set(records.map(r => r.documentLocator)).size !== records.length || docs.some(d => !records.some(r => r.displayId === d.displayId && r.documentLocator === d.documentLocator)))
+        throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Canonical entity mappings and physical documents disagree.');
+    return records;
+}
+/** Read barrier for the real repository. Legacy stores without an entity subsystem remain untouched. */
+function assertEntityRepositoryReadable(storeRoot) {
+    let ancestor = path.resolve(storeRoot);
+    while (!(0, entity_transaction_1.entityStat)(ancestor) && path.dirname(ancestor) !== ancestor)
+        ancestor = path.dirname(ancestor);
+    const workspace = (0, root_1.resolveProjectRoot)(ancestor, { includeGit: false });
+    if (workspace.marker !== '.ax')
+        return;
+    if (!(0, entity_transaction_1.entityStat)(path.join(workspace.root, '.ax', 'entities')) && !(0, entity_transaction_1.entityStat)(path.join(workspace.root, '.ax', 'state', 'entity-transactions')))
+        return;
+    const bound = entityStoreBinding(storeRoot);
+    assertNoPending(bound);
+    const active = registration(bound);
+    if (active)
+        validateMappedInventory(bound, active);
+}
+function bindingWithEntityState(storeRoot, requireEntityState = true) {
+    let ancestor = path.resolve(storeRoot);
+    while (!(0, entity_transaction_1.entityStat)(ancestor) && path.dirname(ancestor) !== ancestor)
+        ancestor = path.dirname(ancestor);
+    const workspace = (0, root_1.resolveProjectRoot)(ancestor, { includeGit: false });
+    if (workspace.marker !== '.ax')
+        return undefined;
+    if (requireEntityState && !(0, entity_transaction_1.entityStat)(path.join(workspace.root, '.ax', 'entities')) && !(0, entity_transaction_1.entityStat)(path.join(workspace.root, '.ax', 'state', 'entity-transactions')))
+        return undefined;
+    // A workspace-root store cannot be adopted (it has no relative locator).
+    // Preserve its legacy path without silently changing its supported layout.
+    if (!requireEntityState && path.resolve(storeRoot) === path.resolve(workspace.root))
+        return undefined;
+    return entityStoreBinding(storeRoot);
+}
+function readEntityRepositorySnapshot(storeRoot) {
+    const bound = bindingWithEntityState(storeRoot);
+    if (!bound)
+        return undefined;
+    assertNoPending(bound);
+    if (!registration(bound))
+        return undefined;
+    return (0, entity_transaction_1.withEntityStoreLock)(bound.root, bound.locator, () => {
+        assertNoPending(bound);
+        const active = registration(bound);
+        if (!active)
+            throw new entity_transaction_1.EntityStoreError('entity-state-changed', 'Store registration disappeared.');
+        return validateMappedInventory(bound, active).map(r => {
+            const dir = (0, entity_transaction_1.entityDirectory)(bound.store, path.dirname(r.documentLocator));
+            const bytes = (0, entity_transaction_1.readEntityBytes)(path.join(dir, path.basename(r.documentLocator)));
+            if (!bytes)
+                throw new entity_transaction_1.EntityStoreError('entity-state-changed', 'A mapped document disappeared.');
+            const spec = (0, spec_parser_1.parseSpec)(bytes.toString('utf8'));
+            if (spec.id !== r.displayId)
+                throw new entity_transaction_1.EntityStoreError('entity-state-changed', 'A mapped document changed identity.');
+            return { spec, version: (0, entity_transaction_1.entityContentVersion)(bytes) };
+        });
+    });
+}
+/** A raw, UUID-bound snapshot for renumber planning; no identity allocation or canonical writes. */
+function readEntityRenumberSnapshot(storeRoot) {
+    const bound = entityStoreBinding(storeRoot);
+    assertNoPending(bound);
+    if (!registration(bound))
+        throw new entity_transaction_1.EntityStoreError('adoption-required', 'Explicitly adopt this store before entity renumbering.');
+    return (0, entity_transaction_1.withEntityStoreLock)(bound.root, bound.locator, () => renumberSnapshot(bound));
+}
+/** Supply a validated snapshot while retaining the same store ownership through publication. */
+function withEntityRenumberSnapshot(storeRoot, act) {
+    const bound = entityStoreBinding(storeRoot);
+    assertNoPending(bound);
+    return (0, entity_transaction_1.withEntityStoreLockAsync)(bound.root, bound.locator, () => {
+        const snapshot = renumberSnapshot(bound);
+        return act(snapshot, () => {
+            if (JSON.stringify(renumberSnapshot(bound)) !== JSON.stringify(snapshot))
+                throw new entity_transaction_1.EntityStoreError('plan-changed', 'The document or identity inventory changed during asynchronous planning.');
+        });
+    });
+}
+function renumberSnapshot(bound) {
+    assertNoPending(bound);
+    const active = registration(bound);
+    if (!active)
+        throw new entity_transaction_1.EntityStoreError('entity-state-changed', 'Store registration disappeared.');
+    const records = validateMappedInventory(bound, active);
+    const registrationBytes = (0, entity_transaction_1.readEntityBytes)(path.join(bound.root, '.ax/entities/stores', active.storeId + '.json'));
+    if (!registrationBytes)
+        throw new entity_transaction_1.EntityStoreError('entity-state-changed', 'Store registration disappeared.');
+    const entries = records.map(record => {
+        const document = path.join(bound.store, record.documentLocator);
+        const mapping = path.join(bound.root, '.ax/entities/records', record.entityId + '.json');
+        const text = (0, entity_transaction_1.readEntityBytes)(document), mappingBytes = (0, entity_transaction_1.readEntityBytes)(mapping);
+        if (!text || !mappingBytes || (0, spec_parser_1.parseSpec)(text.toString('utf8')).id !== record.displayId)
+            throw new entity_transaction_1.EntityStoreError('entity-state-changed', 'Document or mapping changed during renumber planning.');
+        return { entityId: record.entityId, documentLocator: record.documentLocator, text: text.toString('utf8'), mapping: mappingBytes.toString('utf8'), mappingVersion: (0, entity_transaction_1.entityContentVersion)(mappingBytes) };
+    });
+    const referenceNamespaces = allEntityRecords(bound).map(record => ({ entityId: record.entityId, displayId: record.displayId, storeId: record.storeId, workspaceId: record.workspaceId }));
+    return { workspaceId: active.workspaceId, storeId: active.storeId, storeLocator: bound.locator, registrationVersion: (0, entity_transaction_1.entityContentVersion)(registrationBytes), entries, referenceNamespaces };
+}
+async function writeEntityRepository(storeRoot, spec, targetPath, expectedVersion, legacyWrite) {
+    const bound = bindingWithEntityState(storeRoot, false);
+    if (!bound)
+        return legacyWrite();
+    targetPath = path.resolve(bound.store, path.relative(path.resolve(storeRoot), path.resolve(targetPath)));
+    return (0, entity_transaction_1.withEntityStoreLockAsync)(bound.root, bound.locator, () => {
+        assertNoPending(bound);
+        const active = registration(bound);
+        if (!active)
+            return legacyWrite();
+        const records = validateMappedInventory(bound, active), previous = records.find(r => r.displayId === spec.id);
+        const oldFile = previous ? path.join(bound.store, previous.documentLocator) : undefined;
+        const before = oldFile ? (0, entity_transaction_1.readEntityBytes)(oldFile) : undefined;
+        if (previous && !before)
+            throw new entity_transaction_1.EntityStoreError('external-change', 'A validated document disappeared before writing.');
+        const currentVersion = before ? (0, entity_transaction_1.entityContentVersion)(before) : undefined;
+        if (expectedVersion !== undefined && currentVersion !== expectedVersion)
+            throw new entity_transaction_1.EntityStoreError('version-conflict', `spec ${spec.id} changed since it was read (expected ${expectedVersion}, found ${currentVersion ?? 'nothing'})`);
+        const relative = path.relative(bound.store, path.resolve(targetPath)).split(path.sep).join('/');
+        if (!locator(relative))
+            throw new entity_transaction_1.EntityStoreError('unsafe-path', 'Document destination must stay inside the configured store.');
+        (0, entity_transaction_1.entityDirectory)(bound.store, path.dirname(relative));
+        if (oldFile !== targetPath && (0, entity_transaction_1.entityStat)(targetPath))
+            throw new entity_transaction_1.EntityStoreError('target-occupied', 'Document destination is occupied by another file.');
+        const previousMapFile = previous ? path.join(bound.root, '.ax/entities/records', previous.entityId + '.json') : undefined;
+        const mappingBefore = previousMapFile ? (0, entity_transaction_1.readEntityBytes)(previousMapFile) : undefined;
+        if (previous) {
+            let current;
+            try {
+                current = mappingBefore && JSON.parse(mappingBefore.toString('utf8'));
+            }
+            catch {
+                throw new entity_transaction_1.EntityStoreError('external-change', 'A validated entity mapping changed before writing.');
+            }
+            if (JSON.stringify(current) !== JSON.stringify(previous))
+                throw new entity_transaction_1.EntityStoreError('external-change', 'A validated entity mapping changed before writing.');
+        }
+        const operationId = (0, node_crypto_1.randomUUID)(), text = (0, spec_parser_1.serializeSpec)(spec);
+        const mapping = previous ? { ...previous, documentLocator: relative } : { schema: 'holmes-entity/1', workspaceId: active.workspaceId, storeId: active.storeId, entityId: (0, node_crypto_1.randomUUID)(), displayId: spec.id, documentLocator: relative, origin: { kind: 'created', operationId } };
+        const mapFile = path.join(bound.root, '.ax/entities/records', mapping.entityId + '.json');
+        if (!previous && (0, entity_transaction_1.entityStat)(mapFile))
+            throw new entity_transaction_1.EntityStoreError('entity-state-present', 'New entity identifier is occupied.');
+        // Journal the inputs that were validated, never a fresh read that could silently
+        // adopt an intervening external edit. New destinations must remain absent.
+        const change = (file, input, after) => ({ locator: path.relative(bound.root, file).split(path.sep).join('/'), before: input?.toString('base64') ?? null, after: after?.toString('base64') ?? null });
+        const changes = [change(targetPath, oldFile === targetPath ? before : undefined, Buffer.from(text)), change(mapFile, mappingBefore, Buffer.from(JSON.stringify(mapping) + '\n'))];
+        if (oldFile && oldFile !== targetPath)
+            changes.push(change(oldFile, before, null));
+        for (const c of changes)
+            (0, entity_transaction_1.assertEntityByteInput)(bound.root, c);
+        const journal = path.join('.ax/state/entity-transactions', operationId, 'journal.json');
+        const journalText = JSON.stringify({ schema: 'holmes-entity-write-journal/1', operationId, workspaceId: active.workspaceId, storeId: active.storeId, storeLocator: bound.locator, changes }) + '\n';
+        (0, entity_transaction_1.publishEntityRecord)(bound.root, journal, journalText);
+        for (const c of changes)
+            (0, entity_transaction_1.applyEntityByteChange)(bound.root, c);
+        // The old location is removed only after the new document and mapping were published.
+        (0, entity_transaction_1.retireEntityOperation)(bound.root, operationId, bound.locator, (0, entity_transaction_1.entityContentVersion)(journalText));
+        return { version: (0, entity_transaction_1.entityContentVersion)(text) };
+    });
+}
+function adoptionChanges(plan) {
+    const changes = plan.entries.map(e => ({ locator: '.ax/entities/records/' + e.entityId + '.json', before: null, after: Buffer.from(JSON.stringify({ schema: 'holmes-entity/1', workspaceId: plan.workspaceId, storeId: plan.storeId, entityId: e.entityId, displayId: e.displayId, documentLocator: e.documentLocator, origin: { kind: 'adopted', operationId: plan.operationId } }) + '\n').toString('base64') }));
+    changes.push({ locator: '.ax/entities/stores/' + plan.storeId + '.json', before: null, after: Buffer.from(JSON.stringify({ schema: 'holmes-entity-store/1', workspaceId: plan.workspaceId, storeId: plan.storeId, storeLocator: plan.storeLocator, adoptionDigest: (0, entity_transaction_1.entityContentVersion)(JSON.stringify(plan)) }) + '\n').toString('base64') });
+    return changes;
+}
+/** Inspection is not authorization to execute a journal or remove its lock. */
+function planEntityRecovery(storeRoot) {
+    const bound = entityStoreBinding(storeRoot), identity = (0, workspace_identity_1.workspaceIdentity)(bound.root);
+    if (identity.state !== 'registered')
+        throw new workspace_identity_1.WorkspaceIdentityError('unregistered', 'Register workspace identity before inspecting recovery.');
+    const transactionDir = (0, entity_transaction_1.entityDirectory)(bound.root, '.ax/state/entity-transactions');
+    const lockOwner = (0, entity_transaction_1.entityLockOwner)(bound.root, bound.locator);
+    const locations = ((0, entity_transaction_1.entityStat)(transactionDir) ? fs.readdirSync(transactionDir).sort() : []).map(name => ({ name, retired: false, dir: (0, entity_transaction_1.entityDirectory)(transactionDir, name) }));
+    const completedDir = (0, entity_transaction_1.entityDirectory)(bound.root, '.ax/state/entity-completed');
+    if (lockOwner && (0, entity_transaction_1.entityStat)(completedDir))
+        for (const name of fs.readdirSync(completedDir).sort()) {
+            if (!validUuid(name))
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid completed operation directory.');
+            const dir = (0, entity_transaction_1.entityDirectory)(completedDir, name), receiptFile = path.join(dir, 'completion.json');
+            if (!(0, entity_transaction_1.entityStat)(receiptFile))
+                continue; // Older receipts cannot establish ownership.
+            const receipt = object(recordJson(receiptFile), ['schema', 'operationId', 'storeLocator', 'lockOwner', 'journalVersion']);
+            if (receipt.schema !== 'holmes-entity-completion/1' || receipt.operationId !== name || !locator(receipt.storeLocator))
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid completed operation receipt.');
+            if (receipt.storeLocator !== bound.locator || JSON.stringify(receipt.lockOwner) !== JSON.stringify(lockOwner))
+                continue;
+            const journal = (0, entity_transaction_1.readEntityBytes)(path.join(dir, 'journal.json'));
+            if (!journal || receipt.journalVersion !== (0, entity_transaction_1.entityContentVersion)(journal))
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Completed journal no longer matches its receipt.');
+            locations.push({ name, retired: true, dir });
+        }
+    const operations = [];
+    let aborted = false;
+    for (const { name, retired, dir } of locations) {
+        if (!validUuid(name))
+            throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid transaction directory.');
+        const journalFile = path.join(dir, 'journal.json');
+        const bytes = (0, entity_transaction_1.readEntityBytes)(journalFile);
+        if (!bytes) {
+            if (retired)
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'A completed operation has no journal.');
+            // @implements A-SPEC-634 — aborted before its journal: the directory holds at most the staged
+            // temporary of the journal that never got published. Reported with its leftovers and both
+            // dead owners so the exact object the operator approves names everything recovery removes.
+            const active = registration(bound);
+            if (!active)
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'An aborted operation exists for a store without an active registration.');
+            operations.push({ operationId: name, kind: 'aborted', storeId: active.storeId, journalVersion: null, state: 'empty', targets: [], inventoryConflicts: [], leftovers: fs.readdirSync(dir).sort() });
+            aborted = true;
+            continue;
+        }
+        let raw;
+        try {
+            raw = JSON.parse(bytes.toString('utf8'));
+        }
+        catch {
+            throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Malformed recovery journal.');
+        }
+        let changes, storeId, kind;
+        const inventoryConflicts = [];
+        if (raw?.schema === 'holmes-entity-integration-journal/1') {
+            // @implements A-SPEC-639 — an integration journal belongs to entity_integrate; name that tool instead of failing on its shape.
+            const journal = object(raw, ['schema', 'plan', 'storeOwner', 'sourceOwner']);
+            const plan = journal.plan;
+            if (!plan || plan.operationId !== name || !validUuid(plan.operationId) || !locator(plan.storeLocator))
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid integration recovery binding.');
+            if (plan.storeLocator !== bound.locator)
+                continue;
+            throw new entity_transaction_1.EntityStoreError('integration-recovery-required', 'Use entity_integrate recovery-plan/recover/abandon for this pending integration operation.');
+        }
+        if (['holmes-entity-renumber-journal/1', 'holmes-entity-renumber-journal/2'].includes(raw?.schema ?? '')) {
+            const journal = object(raw, raw.schema === 'holmes-entity-renumber-journal/2' ? ['schema', 'plan', 'sourceOwner'] : ['schema', 'plan']);
+            const plan = journal.plan;
+            if (!plan || plan.operationId !== name || !validUuid(plan.operationId) || !validUuid(plan.snapshot?.workspaceId) || !validUuid(plan.snapshot?.storeId) || !locator(plan.snapshot?.storeLocator))
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid renumber recovery binding.');
+            if (plan.snapshot.storeLocator !== bound.locator)
+                continue;
+            throw new entity_transaction_1.EntityStoreError('renumber-recovery-required', 'Use entity_renumber recovery-plan/recover for this pending renumber operation.');
+        }
+        if (raw?.schema === exports.LEGACY_RENUMBER_JOURNAL_SCHEMA) {
+            // @implements A-SPEC-638 — a legacy renumber journal is a rollback program: every target that
+            // differs from its journaled original is `applied` and will be restored.
+            const journal = legacyRenumberJournal(raw, name);
+            if (journal.storeLocator !== bound.locator)
+                continue;
+            if (journal.workspaceId !== identity.workspaceId)
+                throw new entity_transaction_1.EntityStoreError('workspace-mismatch', 'Recovery journal belongs to another workspace.');
+            const version = (v) => v === null ? null : (0, entity_transaction_1.entityContentVersion)(Buffer.from(v, 'base64'));
+            const legacyTargets = journal.changes.map(c => {
+                const current = (0, entity_transaction_1.observeEntityTarget)(bound.root, c.locator).bytes?.toString('base64') ?? null; // @implements A-SPEC-640
+                return { locator: c.locator, beforeVersion: version(c.before), afterVersion: null, currentVersion: version(current), state: (current === c.before ? 'unchanged' : 'applied') };
+            });
+            const applied = legacyTargets.filter(t => t.state === 'applied').length;
+            const legacyState = applied === 0 ? 'unapplied' : applied === legacyTargets.length ? 'applied' : 'partial';
+            if (!(0, entity_transaction_1.readEntityBytes)(journalFile)?.equals(bytes))
+                throw new entity_transaction_1.EntityStoreError('entity-state-changed', 'Journal changed during inspection; inspect again.');
+            operations.push({ operationId: name, kind: 'legacy-renumber', storeId: null, journalVersion: (0, entity_transaction_1.entityContentVersion)(bytes), state: legacyState, targets: legacyTargets, inventoryConflicts: [], ...(retired ? { retired: true } : {}) });
+            continue;
+        }
+        if (raw?.schema === 'holmes-entity-adoption-journal/1') {
+            const journal = object(raw, ['schema', 'plan']), plan = validateEntityAdoptionPlan(journal.plan);
+            if (plan.operationId !== name)
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Journal operation does not match its directory.');
+            if (plan.storeLocator !== bound.locator)
+                continue;
+            if (plan.workspaceId !== identity.workspaceId)
+                throw new entity_transaction_1.EntityStoreError('workspace-mismatch', 'Recovery journal belongs to another workspace.');
+            kind = 'adoption';
+            storeId = plan.storeId;
+            changes = adoptionChanges(plan);
+            const actual = inventory(bound);
+            for (const e of plan.entries)
+                if (!actual.some(d => d.documentLocator === e.documentLocator && d.displayId === e.displayId && d.version === e.version))
+                    inventoryConflicts.push(e.documentLocator);
+            for (const d of actual)
+                if (!plan.entries.some(e => e.documentLocator === d.documentLocator))
+                    inventoryConflicts.push(d.documentLocator);
+        }
+        else {
+            const journal = object(raw, ['schema', 'operationId', 'workspaceId', 'storeId', 'storeLocator', 'changes']);
+            if (journal.schema !== 'holmes-entity-write-journal/1' || journal.operationId !== name || !validUuid(journal.storeId) || !validUuid(journal.workspaceId) || !locator(journal.storeLocator) || !Array.isArray(journal.changes))
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid write recovery journal.');
+            if (journal.storeLocator !== bound.locator)
+                continue;
+            if (journal.workspaceId !== identity.workspaceId)
+                throw new entity_transaction_1.EntityStoreError('workspace-mismatch', 'Recovery journal belongs to another workspace.');
+            const active = registration(bound);
+            if (!active || active.storeId !== journal.storeId || active.workspaceId !== identity.workspaceId)
+                throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Write recovery journal does not match the active store.');
+            kind = 'write';
+            storeId = journal.storeId;
+            const seen = new Set();
+            changes = journal.changes.map(value => {
+                const c = object(value, ['locator', 'before', 'after']);
+                const validBytes = (v) => v === null || (typeof v === 'string' && Buffer.from(v, 'base64').toString('base64') === v);
+                if (!locator(c.locator) || !validBytes(c.before) || !validBytes(c.after) || seen.has(c.locator))
+                    throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid recovery change.');
+                const document = c.locator.startsWith(bound.locator + '/') && c.locator.endsWith('.md');
+                const mapping = c.locator.startsWith('.ax/entities/records/') && validUuid(c.locator.slice('.ax/entities/records/'.length, -5)) && c.locator.endsWith('.json');
+                if (!document && !mapping)
+                    throw new entity_transaction_1.EntityStoreError('unsafe-path', 'A write journal target escapes the configured document/mapping scope.');
+                seen.add(c.locator);
+                return { locator: c.locator, before: c.before, after: c.after };
+            });
+        }
+        const targets = changes.map(c => {
+            const current = (0, entity_transaction_1.observeEntityTarget)(bound.root, c.locator).bytes?.toString('base64') ?? null; // @implements A-SPEC-640
+            const version = (v) => v === null ? null : (0, entity_transaction_1.entityContentVersion)(Buffer.from(v, 'base64'));
+            const state = current === c.before && c.before === c.after ? 'unchanged' : current === c.after ? 'applied' : current === c.before ? 'unapplied' : 'conflict';
+            return { locator: c.locator, beforeVersion: version(c.before), afterVersion: version(c.after), currentVersion: version(current), state };
+        });
+        const changed = targets.filter(t => t.state !== 'unchanged');
+        const state = inventoryConflicts.length || changed.some(t => t.state === 'conflict') ? 'conflict' : changed.every(t => t.state === 'applied') ? 'applied' : changed.every(t => t.state === 'unapplied') ? 'unapplied' : 'partial';
+        if (!(0, entity_transaction_1.readEntityBytes)(journalFile)?.equals(bytes))
+            throw new entity_transaction_1.EntityStoreError('entity-state-changed', 'Journal changed during inspection; inspect again.');
+        operations.push({ operationId: name, kind: kind, storeId: storeId, journalVersion: (0, entity_transaction_1.entityContentVersion)(bytes), state, targets, inventoryConflicts, ...(retired ? { retired: true } : {}) });
+    }
+    const sourceOwner = (0, entity_transaction_1.entityLockOwner)(bound.root, entity_transaction_1.SOURCE_PUBLICATION_LOCATOR);
+    // The shared source-publication owner is reported only beside an aborted operation (or a lock
+    // with nothing pending), where releasing it is part of what the operator approves.
+    const showSource = sourceOwner && (aborted || (lockOwner && operations.length === 0));
+    return { schema: 'holmes-entity-recovery/1', workspaceId: identity.workspaceId, storeLocator: bound.locator, operations, ...(lockOwner ? { lockOwner } : {}), ...(showSource ? { sourceOwner } : {}) };
+}
+function approvedRecoveryJournal(file, version) {
+    const bytes = (0, entity_transaction_1.readEntityBytes)(file);
+    if (!bytes || (0, entity_transaction_1.entityContentVersion)(bytes) !== version)
+        throw new entity_transaction_1.EntityStoreError('plan-changed', 'Recovery journal changed after approval; inspect and authorize the new plan.');
+    return bytes;
+}
+function recoverDraftDocument(bound, operationId, journalVersion, policy, onComplete) {
+    const opDir = (0, entity_transaction_1.entityDirectory)(bound.root, '.ax/state/entity-transactions/' + operationId), journalFile = path.join(opDir, 'journal.json');
+    const journalBytes = approvedRecoveryJournal(journalFile, journalVersion);
+    const journal = object(JSON.parse(journalBytes.toString('utf8')), ['schema', 'operationId', 'workspaceId', 'storeId', 'storeLocator', 'changes']);
+    const active = registration(bound);
+    if (!active || journal.schema !== 'holmes-entity-write-journal/1' || journal.operationId !== operationId || journal.storeId !== active.storeId || journal.workspaceId !== active.workspaceId || journal.storeLocator !== bound.locator || !Array.isArray(journal.changes))
+        throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Write journal does not belong to this active store.');
+    const changes = journal.changes; // The inspected plan validated byte encodings and containment.
+    if (changes.length < 2 || changes.length > 3)
+        throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Unsupported document transaction shape.');
+    const [document, mapping, deletion] = changes;
+    function decodeRecord(bytes) {
+        if (bytes === null)
+            return null;
+        let value;
+        try {
+            value = JSON.parse(Buffer.from(bytes, 'base64').toString('utf8'));
+        }
+        catch {
+            throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Malformed mapping payload.');
+        }
+        const r = object(value, ['schema', 'workspaceId', 'storeId', 'entityId', 'displayId', 'documentLocator', 'origin']);
+        const origin = object(r.origin, ['kind', 'operationId']);
+        if (r.schema !== 'holmes-entity/1' || !validUuid(r.workspaceId) || !validUuid(r.storeId) || !validUuid(r.entityId) || typeof r.displayId !== 'string' || !r.displayId || !locator(r.documentLocator) || !r.documentLocator.endsWith('.md') || !['adopted', 'created'].includes(String(origin.kind)) || !validUuid(origin.operationId))
+            throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid mapping payload.');
+        return r;
+    }
+    const before = decodeRecord(mapping.before), after = decodeRecord(mapping.after);
+    if (!after || after.storeId !== active.storeId || after.workspaceId !== active.workspaceId || mapping.locator !== '.ax/entities/records/' + after.entityId + '.json' || document.locator !== bound.locator + '/' + after.documentLocator || document.after === null)
+        throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Document and mapping destinations disagree.');
+    if (before ? JSON.stringify({ ...before, documentLocator: after.documentLocator }) !== JSON.stringify(after) : after.origin.kind !== 'created' || after.origin.operationId !== operationId)
+        throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Recovery cannot change entity identity or origin.');
+    const relocated = before && before.documentLocator !== after.documentLocator;
+    if (relocated ? !deletion || deletion.locator !== bound.locator + '/' + before.documentLocator || deletion.before === null || deletion.after !== null || document.before !== null : !!deletion || (before ? document.before === null : document.before !== null))
+        throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Invalid create/update/relocation source relationship.');
+    const specs = [document.before, document.after, deletion?.before].filter((s) => typeof s === 'string').map(bytes => (0, spec_parser_1.parseSpec)(Buffer.from(bytes, 'base64').toString('utf8')));
+    if (specs.some(s => s.id !== after.displayId || !(0, spec_types_1.specTypeDef)(s.type)?.idRegex.test(s.id)))
+        throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Document identity does not match its entity record.');
+    const needsPolicy = specs.some(s => s.status !== 'draft' || s.frontmatter.approved_digest !== undefined || s.frontmatter.parent_digests !== undefined);
+    if (needsPolicy && !policy)
+        throw new entity_transaction_1.EntityStoreError('spec-approval-required', 'Sealed or non-draft recovery requires the original spec transition authority and act-time validation; config-write approval is insufficient.');
+    const recordsDir = (0, entity_transaction_1.entityDirectory)(bound.root, '.ax/entities/records');
+    const records = ((0, entity_transaction_1.entityStat)(recordsDir) ? fs.readdirSync(recordsDir).filter(n => n.endsWith('.json')).map(n => {
+        const r = decodeRecord((0, entity_transaction_1.readEntityBytes)(path.join(recordsDir, n)).toString('base64'));
+        if (n !== r.entityId + '.json')
+            throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Mapping filename and identity disagree.');
+        return r;
+    }) : []).filter(r => r.storeId === active.storeId && r.entityId !== after.entityId).concat(after);
+    const excluded = new Set([document.locator, ...(deletion ? [deletion.locator] : [])].map(p => p.slice(bound.locator.length + 1)));
+    const policyInputs = inventory(bound, excluded);
+    const docs = policyInputs.map(d => ({ displayId: d.displayId, documentLocator: d.documentLocator })).concat({ displayId: after.displayId, documentLocator: after.documentLocator });
+    if (records.length !== docs.length || records.some(r => r.workspaceId !== active.workspaceId) || new Set(records.map(r => r.displayId)).size !== records.length || new Set(records.map(r => r.documentLocator)).size !== records.length || docs.some(d => !records.some(r => r.displayId === d.displayId && r.documentLocator === d.documentLocator)))
+        throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'The proposed recovered inventory is inconsistent.');
+    let recheckPolicy;
+    if (needsPolicy) {
+        const currentSpecs = policyInputs.map(input => {
+            const bytes = (0, entity_transaction_1.readEntityBytes)(path.join(bound.store, input.documentLocator));
+            if (!bytes || (0, entity_transaction_1.entityContentVersion)(bytes) !== input.version)
+                throw new entity_transaction_1.EntityStoreError('plan-changed', 'Policy inventory changed during recovery.');
+            return (0, spec_parser_1.parseSpec)(bytes.toString('utf8'));
+        });
+        const prior = deletion?.before ?? document.before;
+        const beforeSpec = prior === null ? null : (0, spec_parser_1.parseSpec)(Buffer.from(prior, 'base64').toString('utf8'));
+        const afterSpec = (0, spec_parser_1.parseSpec)(Buffer.from(document.after, 'base64').toString('utf8'));
+        recheckPolicy = policy(beforeSpec, afterSpec, currentSpecs.concat(beforeSpec ?? afterSpec));
+    }
+    const journalStat = fs.lstatSync(journalFile), cleanup = [];
+    for (const name of fs.readdirSync(opDir)) {
+        if (name === 'journal.json')
+            continue;
+        const file = path.join(opDir, name), s = fs.lstatSync(file);
+        if (name === 'completion.json' && (0, entity_transaction_1.readEntityBytes)(file)?.toString('utf8') === (0, entity_transaction_1.entityCompletionRecord)(bound.root, operationId, bound.locator, journalBytes))
+            continue;
+        if (/^\.entity-[0-9a-f-]+\.tmp$/.test(name) && s.isFile() && !s.isSymbolicLink() && s.dev === journalStat.dev && s.ino === journalStat.ino)
+            cleanup.push(file);
+        else
+            throw new entity_transaction_1.EntityStoreError('cleanup-conflict', 'Unowned transaction files are preserved.');
+    }
+    approvedRecoveryJournal(journalFile, journalVersion);
+    if (needsPolicy) {
+        const latest = inventory(bound, excluded);
+        if (latest.length !== policyInputs.length || latest.some((entry, i) => entry.documentLocator !== policyInputs[i].documentLocator || entry.version !== policyInputs[i].version))
+            throw new entity_transaction_1.EntityStoreError('plan-changed', 'Policy inventory changed before publication.');
+        recheckPolicy();
+    }
+    for (const change of changes) {
+        const dir = (0, entity_transaction_1.entityDirectory)(bound.root, path.dirname(change.locator));
+        if (((0, entity_transaction_1.readEntityBytes)(path.join(dir, path.basename(change.locator)))?.toString('base64') ?? null) !== change.after)
+            (0, entity_transaction_1.applyEntityByteChange)(bound.root, change);
+    }
+    validateMappedInventory(bound, active);
+    for (const file of cleanup)
+        fs.unlinkSync(file);
+    approvedRecoveryJournal(journalFile, journalVersion);
+    onComplete?.();
+    (0, entity_transaction_1.retireEntityOperation)(bound.root, operationId, bound.locator, journalVersion);
+    return inspectEntityStore(bound.store);
+}
+function validateEntityRecoveryPlan(value) {
+    const hasOwner = !!value && typeof value === 'object' && Object.prototype.hasOwnProperty.call(value, 'lockOwner');
+    const hasSource = !!value && typeof value === 'object' && Object.prototype.hasOwnProperty.call(value, 'sourceOwner');
+    const p = object(value, ['schema', 'workspaceId', 'storeLocator', 'operations', ...(hasOwner ? ['lockOwner'] : []), ...(hasSource ? ['sourceOwner'] : [])]);
+    for (const key of [...(hasOwner ? ['lockOwner'] : []), ...(hasSource ? ['sourceOwner'] : [])]) {
+        const owner = object(p[key], ['token', 'version']);
+        if (!validUuid(owner.token) || typeof owner.version !== 'string' || !DIGEST.test(owner.version))
+            throw new entity_transaction_1.EntityStoreError('invalid-plan', 'Invalid recovery lock owner.');
+    }
+    if (p.schema !== 'holmes-entity-recovery/1' || !validUuid(p.workspaceId) || !locator(p.storeLocator) || !Array.isArray(p.operations))
+        throw new entity_transaction_1.EntityStoreError('invalid-plan', 'Invalid recovery plan.');
+    for (const value of p.operations) {
+        // @implements A-SPEC-634 — an aborted operation: no journal, no targets, only its leftovers.
+        if (!!value && typeof value === 'object' && value.kind === 'aborted') {
+            const op = object(value, ['operationId', 'kind', 'storeId', 'journalVersion', 'state', 'targets', 'inventoryConflicts', 'leftovers']);
+            if (!validUuid(op.operationId) || !validUuid(op.storeId) || op.journalVersion !== null || op.state !== 'empty' || !Array.isArray(op.targets) || op.targets.length !== 0 || !Array.isArray(op.inventoryConflicts) || op.inventoryConflicts.length !== 0
+                || !Array.isArray(op.leftovers) || op.leftovers.some((n) => typeof n !== 'string' || !n || n.includes('/') || n.includes('\\') || n === '.' || n === '..'))
+                throw new entity_transaction_1.EntityStoreError('invalid-plan', 'Invalid aborted recovery operation.');
+            continue;
+        }
+        const retired = !!value && typeof value === 'object' && Object.prototype.hasOwnProperty.call(value, 'retired');
+        const op = object(value, ['operationId', 'kind', 'storeId', 'journalVersion', 'state', 'targets', 'inventoryConflicts', ...(retired ? ['retired'] : [])]);
+        if (retired && op.retired !== true)
+            throw new entity_transaction_1.EntityStoreError('invalid-plan', 'Invalid completed recovery operation.');
+        if (op.kind === 'legacy-renumber') {
+            // @implements A-SPEC-638 — a rollback program: no store id, no after state, targets unchanged or applied.
+            if (!validUuid(op.operationId) || op.storeId !== null || typeof op.journalVersion !== 'string' || !DIGEST.test(op.journalVersion) || !['unapplied', 'partial', 'applied'].includes(String(op.state)) || !Array.isArray(op.targets) || !Array.isArray(op.inventoryConflicts) || op.inventoryConflicts.length !== 0)
+                throw new entity_transaction_1.EntityStoreError('invalid-plan', 'Invalid legacy renumber recovery operation.');
+            for (const value of op.targets) {
+                const t = object(value, ['locator', 'beforeVersion', 'afterVersion', 'currentVersion', 'state']);
+                if (!locator(t.locator) || t.afterVersion !== null || !['unchanged', 'applied'].includes(String(t.state)) || ['beforeVersion', 'currentVersion'].some(k => t[k] !== null && (typeof t[k] !== 'string' || !DIGEST.test(t[k]))))
+                    throw new entity_transaction_1.EntityStoreError('invalid-plan', 'Invalid legacy renumber recovery target.');
+            }
+            continue;
+        }
+        if (!validUuid(op.operationId) || !validUuid(op.storeId) || !['adoption', 'write'].includes(String(op.kind)) || typeof op.journalVersion !== 'string' || !DIGEST.test(op.journalVersion) || !['unapplied', 'partial', 'applied', 'conflict'].includes(String(op.state)) || !Array.isArray(op.targets) || !Array.isArray(op.inventoryConflicts) || !op.inventoryConflicts.every(locator))
+            throw new entity_transaction_1.EntityStoreError('invalid-plan', 'Invalid recovery operation.');
+        for (const value of op.targets) {
+            const t = object(value, ['locator', 'beforeVersion', 'afterVersion', 'currentVersion', 'state']);
+            if (!locator(t.locator) || !['unchanged', 'applied', 'unapplied', 'conflict'].includes(String(t.state)) || ['beforeVersion', 'afterVersion', 'currentVersion'].some(k => t[k] !== null && (typeof t[k] !== 'string' || !DIGEST.test(t[k]))))
+                throw new entity_transaction_1.EntityStoreError('invalid-plan', 'Invalid recovery target.');
+            if (op.kind === 'adoption' && !/^\.ax\/entities\/(records|stores)\/[0-9a-f-]+\.json$/.test(t.locator))
+                throw new entity_transaction_1.EntityStoreError('unsafe-path', 'Adoption recovery cannot target documents or other workspace files.');
+            if (op.kind === 'write' && !(t.locator.startsWith(p.storeLocator + '/') && t.locator.endsWith('.md')) && !/^\.ax\/entities\/records\/[0-9a-f-]+\.json$/.test(t.locator))
+                throw new entity_transaction_1.EntityStoreError('unsafe-path', 'Document recovery targets must stay within the configured store and mappings.');
+        }
+    }
+    return p;
+}
+function entityRecoveryTarget(plan) { return 'entity-store:recover:' + (0, entity_transaction_1.entityContentVersion)(JSON.stringify(plan)); }
+function recoverEntityStore(storeRoot, plan, policy, onComplete) {
+    const bound = entityStoreBinding(storeRoot), identity = (0, workspace_identity_1.workspaceIdentity)(bound.root);
+    if (identity.state !== 'registered' || identity.workspaceId !== plan.workspaceId || bound.locator !== plan.storeLocator)
+        throw new entity_transaction_1.EntityStoreError('workspace-mismatch', 'Recovery plan does not belong to this store.');
+    // @implements A-SPEC-634 — zero operations is recoverable only as a lock-only release: a holder
+    // that died after taking the store lock and before creating its pending directory.
+    const lockOnly = plan.operations.length === 0 && !!plan.lockOwner;
+    if (plan.operations.length !== 1 && !lockOnly)
+        throw new entity_transaction_1.EntityStoreError('unsupported-recovery', 'Recover one inspected operation at a time.');
+    const owner = (0, entity_transaction_1.entityLockOwner)(bound.root, bound.locator);
+    if (owner && JSON.stringify(owner) !== JSON.stringify(plan.lockOwner))
+        throw new entity_transaction_1.EntityStoreError('plan-changed', 'The current lock belongs to a different operation; inspect and authorize its owner.');
+    if (lockOnly && !owner)
+        throw new entity_transaction_1.EntityStoreError('plan-changed', 'The lock this plan releases is no longer held.');
+    const runOwned = owner ? entity_transaction_1.withEntityRecoveryLock : entity_transaction_1.withEntityStoreLock;
+    return runOwned(bound.root, bound.locator, () => {
+        const current = planEntityRecovery(storeRoot), op = plan.operations[0];
+        if (owner && JSON.stringify(current.lockOwner) !== JSON.stringify(plan.lockOwner))
+            throw new entity_transaction_1.EntityStoreError('plan-changed', 'Lock ownership changed while claiming recovery.');
+        if (lockOnly || op.kind === 'aborted') {
+            // @implements A-SPEC-634 — the store generation is already claimed (a live owner refused
+            // store-busy above); claim the dead source-publication generation the plan names, remove only
+            // the operation's own staged temporaries and its empty directory, and let both recovery
+            // locks retire their generations on the way out. Anything unexpected is preserved.
+            if (JSON.stringify(current) !== JSON.stringify(plan))
+                throw new entity_transaction_1.EntityStoreError('plan-changed', 'Recovery inputs changed; inspect and authorize the new plan.');
+            const release = () => {
+                if (op) {
+                    const opDir = (0, entity_transaction_1.entityDirectory)(bound.root, '.ax/state/entity-transactions/' + op.operationId);
+                    if ((0, entity_transaction_1.entityStat)(opDir)) {
+                        const names = fs.readdirSync(opDir);
+                        for (const name of names) {
+                            const s = fs.lstatSync(path.join(opDir, name));
+                            if (!/^\.entity-[0-9a-f-]+\.tmp$/.test(name) || !s.isFile() || s.isSymbolicLink())
+                                throw new entity_transaction_1.EntityStoreError('cleanup-conflict', 'Unowned transaction files are preserved.');
+                        }
+                        for (const name of names)
+                            fs.unlinkSync(path.join(opDir, name));
+                        fs.rmdirSync(opDir);
+                    }
+                }
+                onComplete?.();
+            };
+            if (plan.sourceOwner) {
+                if (JSON.stringify((0, entity_transaction_1.entityLockOwner)(bound.root, entity_transaction_1.SOURCE_PUBLICATION_LOCATOR)) !== JSON.stringify(plan.sourceOwner))
+                    throw new entity_transaction_1.EntityStoreError('plan-changed', 'Source publication ownership changed; inspect and authorize the new plan.');
+                (0, entity_transaction_1.withEntityRecoveryLock)(bound.root, entity_transaction_1.SOURCE_PUBLICATION_LOCATOR, release);
+            }
+            else
+                release();
+            return inspectEntityStore(storeRoot);
+        }
+        if (!current.operations.length) {
+            const active = registration(bound);
+            if (!active || active.storeId !== op.storeId || !op.targets.length || op.targets.some(t => {
+                const dir = (0, entity_transaction_1.entityDirectory)(bound.root, path.dirname(t.locator));
+                const bytes = (0, entity_transaction_1.readEntityBytes)(path.join(dir, path.basename(t.locator)));
+                return (bytes ? (0, entity_transaction_1.entityContentVersion)(bytes) : null) !== t.afterVersion;
+            }))
+                throw new entity_transaction_1.EntityStoreError('plan-changed', 'The completed operation no longer matches this recovery plan.');
+            onComplete?.();
+            return inspectEntityStore(storeRoot);
+        }
+        if (JSON.stringify(current) !== JSON.stringify(plan))
+            throw new entity_transaction_1.EntityStoreError('plan-changed', 'Recovery inputs changed; inspect and authorize the new plan.');
+        if (op.state === 'conflict')
+            throw new entity_transaction_1.EntityStoreError('external-change', 'External changes must be preserved; recovery cannot overwrite a third state.');
+        // @implements A-SPEC-640 — after every refusal point: a lone aside goes back to its absent target before any replay.
+        (0, entity_transaction_1.settleEntityTransients)(bound.root, op.targets.map(t => ({ locator: t.locator, before: null, after: null })));
+        if (op.retired) {
+            if (op.kind === 'legacy-renumber') {
+                onComplete?.();
+                return inspectEntityStore(storeRoot);
+            }
+            const active = registration(bound);
+            if (op.state !== 'applied' || !active || active.storeId !== op.storeId)
+                throw new entity_transaction_1.EntityStoreError('plan-changed', 'Completed receipt does not describe the current active store.');
+            onComplete?.();
+            return inspectEntityStore(storeRoot);
+        }
+        if (op.kind === 'legacy-renumber') {
+            // @implements A-SPEC-638 — roll the raw legacy renumber back to its journaled originals:
+            // files it created are removed first, then every rewritten or moved file gets its original bytes.
+            const opDir = (0, entity_transaction_1.entityDirectory)(bound.root, '.ax/state/entity-transactions/' + op.operationId), journalFile = path.join(opDir, 'journal.json');
+            const journalBytes = approvedRecoveryJournal(journalFile, op.journalVersion);
+            const journal = legacyRenumberJournal(JSON.parse(journalBytes.toString('utf8')), op.operationId);
+            const currentOf = (target) => { const dir = (0, entity_transaction_1.entityDirectory)(bound.root, path.dirname(target)); const file = path.join(dir, path.basename(target)); const bytes = (0, entity_transaction_1.readEntityBytes)(file); return { file, bytes, base64: bytes?.toString('base64') ?? null }; };
+            const restore = (change) => {
+                const current = currentOf(change.locator);
+                if (current.base64 === change.before)
+                    return;
+                const beforeMode = current.bytes ? (((0, entity_transaction_1.entityStat)(current.file).mode & 0o100) ? '100755' : '100644') : null;
+                (0, entity_transaction_1.applyEntityByteChange)(bound.root, { locator: change.locator, before: current.base64, after: change.before, beforeMode, afterMode: change.before === null ? null : '100644' });
+            };
+            for (const change of journal.changes)
+                if (change.before === null)
+                    restore(change);
+            for (const change of journal.changes)
+                if (change.before !== null)
+                    restore(change);
+            for (const change of journal.changes)
+                if (currentOf(change.locator).base64 !== change.before)
+                    throw new entity_transaction_1.EntityStoreError('external-change', 'Legacy renumber rollback could not restore ' + change.locator + '.');
+            approvedRecoveryJournal(journalFile, op.journalVersion);
+            onComplete?.();
+            (0, entity_transaction_1.retireEntityOperation)(bound.root, op.operationId, bound.locator, op.journalVersion);
+            return inspectEntityStore(storeRoot);
+        }
+        if (op.kind === 'write')
+            return recoverDraftDocument(bound, op.operationId, op.journalVersion, policy, onComplete);
+        const opDir = (0, entity_transaction_1.entityDirectory)(bound.root, '.ax/state/entity-transactions/' + op.operationId), journalFile = path.join(opDir, 'journal.json');
+        const journalBytes = approvedRecoveryJournal(journalFile, op.journalVersion);
+        const journal = object(JSON.parse(journalBytes.toString('utf8')), ['schema', 'plan']);
+        if (journal.schema !== 'holmes-entity-adoption-journal/1')
+            throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Expected an adoption journal.');
+        const adoption = validateEntityAdoptionPlan(journal.plan);
+        const active = registration(bound);
+        if (active && (active.storeId !== adoption.storeId || active.adoptionDigest !== (0, entity_transaction_1.entityContentVersion)(JSON.stringify(adoption))))
+            throw new entity_transaction_1.EntityStoreError('entity-state-present', 'Another adoption owns this store.');
+        const journalStat = fs.lstatSync(journalFile), cleanup = [journalFile];
+        for (const name of fs.readdirSync(opDir)) {
+            if (name === 'journal.json')
+                continue;
+            if (name === 'completion.json') {
+                const bytes = (0, entity_transaction_1.readEntityBytes)(path.join(opDir, name));
+                if (bytes?.toString('utf8') !== (0, entity_transaction_1.entityCompletionRecord)(bound.root, op.operationId, bound.locator, journalBytes))
+                    throw new entity_transaction_1.EntityStoreError('retirement-conflict', 'Completion receipt does not match the owned journal.');
+                continue;
+            }
+            const file = path.join(opDir, name), s = fs.lstatSync(file);
+            if (/^\.entity-[0-9a-f-]+\.tmp$/.test(name) && s.isFile() && !s.isSymbolicLink() && s.dev === journalStat.dev && s.ino === journalStat.ino)
+                cleanup.push(file);
+            else
+                throw new entity_transaction_1.EntityStoreError('cleanup-conflict', 'Unowned transaction files are preserved.');
+        }
+        approvedRecoveryJournal(journalFile, op.journalVersion);
+        for (const change of adoptionChanges(adoption)) {
+            const dir = (0, entity_transaction_1.entityDirectory)(bound.root, path.dirname(change.locator));
+            if (((0, entity_transaction_1.readEntityBytes)(path.join(dir, path.basename(change.locator)))?.toString('base64') ?? null) !== change.after)
+                (0, entity_transaction_1.applyEntityByteChange)(bound.root, change);
+        }
+        const completed = registration(bound);
+        if (!completed)
+            throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Recovered adoption did not publish its registration.');
+        validateMappedInventory(bound, completed);
+        for (const file of cleanup.slice(1))
+            fs.unlinkSync(file);
+        approvedRecoveryJournal(journalFile, op.journalVersion);
+        onComplete?.();
+        (0, entity_transaction_1.retireEntityOperation)(bound.root, op.operationId, bound.locator, op.journalVersion);
+        return inspectEntityStore(storeRoot);
+    });
+}
+function adoptEntityStore(storeRoot, plan) {
+    const bound = entityStoreBinding(storeRoot), identity = (0, workspace_identity_1.workspaceIdentity)(bound.root);
+    if (identity.state !== 'registered' || identity.workspaceId !== plan.workspaceId || bound.locator !== plan.storeLocator)
+        throw new entity_transaction_1.EntityStoreError('workspace-mismatch', 'Adoption plan does not belong to this registered store.');
+    return (0, entity_transaction_1.withEntityStoreLock)(bound.root, bound.locator, () => {
+        assertNoPending(bound);
+        const active = registration(bound), digest = (0, entity_transaction_1.entityContentVersion)(JSON.stringify(plan));
+        if (active) {
+            if (active.storeId !== plan.storeId || active.adoptionDigest !== digest)
+                throw new entity_transaction_1.EntityStoreError('entity-state-present', 'A different adoption already activated this store.');
+            return inspectEntityStore(storeRoot);
+        }
+        assertNoOverlap(bound);
+        const actual = inventory(bound);
+        if (actual.length !== plan.entries.length || actual.some(d => !plan.entries.some(e => e.displayId === d.displayId && e.documentLocator === d.documentLocator && e.version === d.version)))
+            throw new entity_transaction_1.EntityStoreError('inventory-changed', 'Physical spec inventory changed after planning; preserve it and create a new plan.');
+        const records = plan.entries.map(e => ({ schema: 'holmes-entity/1', workspaceId: plan.workspaceId, storeId: plan.storeId, entityId: e.entityId, displayId: e.displayId, documentLocator: e.documentLocator, origin: { kind: 'adopted', operationId: plan.operationId } }));
+        (0, entity_transaction_1.entityDirectory)(bound.root, path.join('.ax', 'entities', 'records'));
+        for (const r of records)
+            if ((0, entity_transaction_1.entityStat)(path.join(bound.root, '.ax', 'entities', 'records', r.entityId + '.json')))
+                throw new entity_transaction_1.EntityStoreError('entity-state-present', 'A proposed entity identifier is already occupied.');
+        const marker = path.join('.ax', 'entities', 'stores', plan.storeId + '.json');
+        if ((0, entity_transaction_1.entityStat)(path.join(bound.root, marker)))
+            throw new entity_transaction_1.EntityStoreError('entity-state-present', 'The proposed store identifier is occupied.');
+        const journal = path.join('.ax', 'state', 'entity-transactions', plan.operationId, 'journal.json');
+        const journalText = JSON.stringify({ schema: 'holmes-entity-adoption-journal/1', plan }) + '\n';
+        (0, entity_transaction_1.publishEntityRecord)(bound.root, journal, journalText);
+        for (const r of records)
+            (0, entity_transaction_1.publishEntityRecord)(bound.root, path.join('.ax', 'entities', 'records', r.entityId + '.json'), JSON.stringify(r) + '\n');
+        // Documents are never rewritten by adoption. The activation marker is the last canonical write.
+        (0, entity_transaction_1.publishEntityRecord)(bound.root, marker, JSON.stringify({ schema: 'holmes-entity-store/1', workspaceId: plan.workspaceId, storeId: plan.storeId, storeLocator: plan.storeLocator, adoptionDigest: digest }) + '\n');
+        (0, entity_transaction_1.retireEntityOperation)(bound.root, plan.operationId, bound.locator, (0, entity_transaction_1.entityContentVersion)(journalText));
+        return inspectEntityStore(storeRoot);
+    });
+}