@holmes-lab/holmes-kit 0.19.6 → 0.20.0

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

@@ -0,0 +1,1221 @@
+"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.prepareEntityIntegrationTransitions = prepareEntityIntegrationTransitions;
+exports.validateEntityIntegrationPlan = validateEntityIntegrationPlan;
+exports.entityIntegrationTarget = entityIntegrationTarget;
+exports.applyEntityIntegration = applyEntityIntegration;
+exports.abandonEntityIntegration = abandonEntityIntegration;
+exports.recoverEntityIntegration = recoverEntityIntegration;
+exports.validateEntityIntegrationRecoveryRequest = validateEntityIntegrationRecoveryRequest;
+exports.inspectEntityIntegrationRecovery = inspectEntityIntegrationRecovery;
+exports.validateEntityIntegrationRecoveryProgram = validateEntityIntegrationRecoveryProgram;
+exports.withValidatedEntityIntegrationPlan = withValidatedEntityIntegrationPlan;
+exports.prepareEntityIntegrationPlan = prepareEntityIntegrationPlan;
+exports.reviewEntityIntegration = reviewEntityIntegration;
+exports.compileEntityIntegrationSteps = compileEntityIntegrationSteps;
+exports.planEntityIntegrationCandidate = planEntityIntegrationCandidate;
+// @implements A-SPEC-629
+// @implements A-SPEC-645
+// @implements A-SPEC-641
+// @implements A-SPEC-640
+// @implements A-SPEC-639
+// @implements A-SPEC-636
+// @implements A-SPEC-637
+// @implements A-SPEC-634
+const entity_transaction_1 = require("./entity-transaction");
+const entity_integration_1 = require("./entity-integration");
+const entity_git_snapshot_1 = require("./entity-git-snapshot");
+const entity_renumber_transaction_1 = require("./entity-renumber-transaction");
+const entity_store_1 = require("./entity-store");
+const node_util_1 = require("node:util");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const ignore_1 = require("../project/ignore");
+const change_source_1 = require("../project/change-source");
+const cpg_scanner_1 = require("../cpg/cpg-scanner");
+const entity_renumber_1 = require("./entity-renumber");
+const spec_parser_1 = require("./spec-parser");
+const spec_digest_1 = require("./spec-digest");
+const transition_policy_1 = require("./transition-policy");
+const node_crypto_1 = require("node:crypto");
+const workspace_identity_1 = require("../project/workspace-identity");
+/** Produces document transitions only; authority and durable application belong to the executor. */
+function prepareEntityIntegrationTransitions(current, desired, readFile) {
+    const graph = (entries) => {
+        const validation = (0, entity_renumber_1.planEntityRenumber)(entries, []);
+        if (!validation.ok)
+            throw new entity_transaction_1.EntityStoreError('plan-conflict', validation.conflicts.join('\n'));
+        const byEntity = new Map(entries.map(entry => [entry.entityId, { ...entry }]));
+        const specs = new Map(entries.map(entry => [entry.entityId, (0, spec_parser_1.parseSpec)(entry.text)]));
+        const byId = new Map([...specs].map(([id, spec]) => [spec.id, id]));
+        const order = [], visited = new Set();
+        const visit = (id) => {
+            if (visited.has(id))
+                return;
+            visited.add(id);
+            for (const parent of specs.get(id).dependsOn.map(parent => byId.get(parent)).sort())
+                visit(parent);
+            order.push(id);
+        };
+        for (const id of [...byEntity.keys()].sort())
+            visit(id);
+        return { byEntity, specs, byId, order };
+    };
+    const before = graph(current), after = graph(desired), affected = new Set();
+    for (const id of new Set([...before.byEntity.keys(), ...after.byEntity.keys()])) {
+        const old = before.byEntity.get(id), next = after.byEntity.get(id);
+        if (!old || !next || old.text !== next.text || old.documentLocator !== next.documentLocator)
+            affected.add(id);
+    }
+    for (const [id, spec] of after.specs)
+        if (spec.status === 'approved') {
+            const parents = {};
+            let validParents = true;
+            for (const parentId of spec.dependsOn) {
+                const parent = after.specs.get(after.byId.get(parentId));
+                if (parent.status !== 'approved' || typeof parent.frontmatter.approved_digest !== 'string' || parent.frontmatter.approved_digest !== (0, spec_digest_1.specDigest)(parent))
+                    validParents = false;
+                else
+                    parents[parentId] = parent.frontmatter.approved_digest;
+            }
+            if (spec.frontmatter.approved_digest !== (0, spec_digest_1.specDigest)(spec) || !validParents || !(0, node_util_1.isDeepStrictEqual)(spec.frontmatter.parent_digests, parents))
+                affected.add(id);
+        }
+    // Current dependents may have different parents after integration. Close both graphs to a fixed point.
+    let previousSize = -1;
+    while (previousSize !== affected.size) {
+        previousSize = affected.size;
+        for (const g of [before, after])
+            for (const id of g.order) {
+                if (g.specs.get(id).dependsOn.some(parent => affected.has(g.byId.get(parent))))
+                    affected.add(id);
+            }
+    }
+    const result = { unseal: [], publication: [], approve: [], completed: [] };
+    const all = (g) => [...g.specs.values()];
+    const withdraw = (g, id, record) => {
+        const entry = g.byEntity.get(id), spec = g.specs.get(id);
+        const prepared = (0, transition_policy_1.prepareLifecycleSpec)(spec, all(g), 'unseal');
+        if (!prepared.ok)
+            throw new entity_transaction_1.EntityStoreError('spec-policy-refused', prepared.reason);
+        const text = (0, entity_renumber_1.replaceFrontmatter)(entry.text, prepared.candidate);
+        if (record)
+            result.unseal.push({ entityId: id, displayId: spec.id, documentLocator: entry.documentLocator, before: entry.text, after: text });
+        entry.text = text;
+        g.specs.set(id, prepared.candidate);
+    };
+    for (const id of [...before.order].reverse())
+        if (affected.has(id) && before.specs.get(id).status === 'approved')
+            withdraw(before, id, true);
+    const approve = after.order.filter(id => affected.has(id) && after.specs.get(id).status === 'approved');
+    // Imported historical seals are not the seal of a new publication. Stage these documents as drafts.
+    for (const id of [...approve].reverse())
+        withdraw(after, id, false);
+    result.publication = [...after.byEntity.values()].map(entry => ({ ...entry }));
+    for (const id of approve) {
+        const entry = after.byEntity.get(id), spec = after.specs.get(id);
+        const prepared = (0, transition_policy_1.prepareApprovedSpec)(spec, all(after), specs => parent => specs.find(s => s.id === parent) ?? null, readFile);
+        // A-SPEC-641: a multi-document act names the document it refuses on.
+        if (!prepared.ok)
+            throw new entity_transaction_1.EntityStoreError('spec-policy-refused', spec.id + ': ' + prepared.reason);
+        const text = (0, entity_renumber_1.replaceFrontmatter)(entry.text, prepared.candidate);
+        result.approve.push({ entityId: id, displayId: spec.id, documentLocator: entry.documentLocator, before: entry.text, after: text });
+        entry.text = text;
+        after.specs.set(id, prepared.candidate);
+    }
+    result.completed = [...after.byEntity.values()].map(entry => ({ ...entry }));
+    return result;
+}
+/** A closed transport contract. Application must additionally regenerate it from current authorized inputs. */
+function validateEntityIntegrationPlan(value) {
+    const fail = () => { throw new entity_transaction_1.EntityStoreError('invalid-plan', 'Invalid or unsupported integration plan fields or step continuity.'); };
+    const object = (input, keys) => {
+        if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).length !== keys.length || keys.some(key => !Object.prototype.hasOwnProperty.call(input, key)))
+            fail();
+    };
+    const uuid = (input) => typeof input === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(input);
+    const oid = (input) => typeof input === 'string' && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(input);
+    const digest = (input) => typeof input === 'string' && /^sha256:[0-9a-f]{64}$/.test(input);
+    const locator = (input) => typeof input === 'string' && !!input && !/[\\:\x00]/.test(input) && input.split('/').every(part => !!part && part !== '.' && part !== '..' && part.toLowerCase() !== '.git');
+    const mode = (input) => input === '100644' || input === '100755';
+    const bytes = (input) => input === null || typeof input === 'string' && Buffer.from(input, 'base64').toString('base64') === input;
+    object(value, ['schema', 'operationId', 'workspaceId', 'storeId', 'storeLocator', 'commits', 'destination', 'configVersion', 'checks', 'policyInputs', 'steps']);
+    const plan = value;
+    object(plan.commits, ['base', 'left', 'right']);
+    object(plan.destination, ['head', 'indexVersion', 'membershipVersion']);
+    if (plan.schema !== 'holmes-entity-integration/1' || !uuid(plan.operationId) || !uuid(plan.workspaceId) || !uuid(plan.storeId) || !locator(plan.storeLocator) ||
+        Object.values(plan.commits).some(commit => !oid(commit)) || !oid(plan.destination.head) || !Object.values(plan.commits).includes(plan.destination.head) ||
+        !digest(plan.destination.indexVersion) || !digest(plan.destination.membershipVersion) || (plan.configVersion !== null && !digest(plan.configVersion)) ||
+        !Array.isArray(plan.checks) || !Array.isArray(plan.policyInputs) || !Array.isArray(plan.steps))
+        fail();
+    const states = new Map();
+    const checks = plan.checks.map(check => {
+        object(check, ['locator', 'version', 'mode']);
+        if (!locator(check.locator) || states.has(check.locator) || (check.version === null ? check.mode !== null : !digest(check.version) || !mode(check.mode)))
+            fail();
+        states.set(check.locator, { version: check.version, mode: check.mode });
+        return { locator: check.locator, version: check.version, mode: check.mode };
+    });
+    if (states.has('.ax/config.json') && states.get('.ax/config.json').version !== plan.configVersion)
+        fail();
+    const policySeen = new Set();
+    const policyInputs = plan.policyInputs.map(input => {
+        object(input, ['locator', 'version', 'effectiveVersion']);
+        if (!locator(input.locator) || policySeen.has(input.locator) || (input.version !== null && !digest(input.version)) || (input.effectiveVersion !== null && !digest(input.effectiveVersion)))
+            fail();
+        if (states.has(input.locator) && states.get(input.locator).version !== input.version)
+            fail();
+        policySeen.add(input.locator);
+        return { locator: input.locator, version: input.version, effectiveVersion: input.effectiveVersion };
+    });
+    let stage = 0;
+    const steps = plan.steps.map(step => {
+        object(step, ['phase', 'change', ...(step?.entityId === undefined ? [] : ['entityId']), ...(step?.specId === undefined ? [] : ['specId'])]);
+        object(step.change, ['locator', 'before', 'after', 'beforeMode', 'afterMode']);
+        const change = step.change;
+        if (!['unseal', 'document', 'mapping', 'source', 'approve'].includes(step.phase) || !locator(change.locator) || !bytes(change.before) || !bytes(change.after) ||
+            (change.before === null ? change.beforeMode !== null : !mode(change.beforeMode)) || (change.after === null ? change.afterMode !== null : !mode(change.afterMode)) ||
+            (step.entityId !== undefined && !uuid(step.entityId)) || (step.specId !== undefined && (typeof step.specId !== 'string' || !/^(?:REQ|H-SPEC|A-SPEC|C-SPEC|T-SPEC|ADR)-\d{3,}(?:\.\d+)?$/.test(step.specId))))
+            fail();
+        const nextStage = step.phase === 'unseal' ? 0 : step.phase === 'approve' ? 2 : 1;
+        if (nextStage < stage || (change.before === change.after && change.beforeMode === change.afterMode))
+            fail();
+        stage = nextStage;
+        if (step.phase === 'unseal' || step.phase === 'approve') {
+            if (!step.entityId || !step.specId || change.before === null || change.after === null || !under(change.locator, plan.storeLocator))
+                fail();
+        }
+        else if (step.phase === 'document') {
+            if (!under(change.locator, plan.storeLocator) || !change.locator.endsWith('.md'))
+                fail();
+        }
+        else if (step.phase === 'mapping') {
+            if (!/^\.ax\/entities\/records\/[0-9a-f-]+\.json$/.test(change.locator))
+                fail();
+        }
+        else if (under(change.locator, '.ax') || under(change.locator, plan.storeLocator))
+            fail();
+        const prior = states.get(change.locator), beforeVersion = change.before === null ? null : (0, entity_transaction_1.entityContentVersion)(Buffer.from(change.before, 'base64'));
+        if (!prior || prior.version !== beforeVersion || prior.mode !== change.beforeMode)
+            fail();
+        states.set(change.locator, { version: change.after === null ? null : (0, entity_transaction_1.entityContentVersion)(Buffer.from(change.after, 'base64')), mode: change.afterMode });
+        return { phase: step.phase, ...(step.entityId === undefined ? {} : { entityId: step.entityId }), ...(step.specId === undefined ? {} : { specId: step.specId }),
+            change: { locator: change.locator, before: change.before, after: change.after, beforeMode: change.beforeMode, afterMode: change.afterMode } };
+    });
+    return { schema: plan.schema, operationId: plan.operationId, workspaceId: plan.workspaceId, storeId: plan.storeId, storeLocator: plan.storeLocator,
+        commits: { base: plan.commits.base, left: plan.commits.left, right: plan.commits.right }, destination: { head: plan.destination.head, indexVersion: plan.destination.indexVersion, membershipVersion: plan.destination.membershipVersion },
+        configVersion: plan.configVersion, checks, policyInputs, steps };
+}
+function entityIntegrationTarget(plan) { return 'entity-store:integrate:' + (0, entity_transaction_1.entityContentVersion)(JSON.stringify(validateEntityIntegrationPlan(plan))); }
+/** Internal execution core; the public adapter supplies current authority and durable audit. */
+async function applyEntityIntegration(root, inspected, authorize, audit, beforePublish) {
+    if (typeof authorize !== 'function' || typeof audit !== 'function')
+        throw new entity_transaction_1.EntityStoreError('authority-required', 'Integration requires current authority and durable audit adapters.');
+    root = fs.realpathSync(root);
+    const requested = validateEntityIntegrationPlan(inspected), completed = await retryCompletedEntityIntegration(root, requested, authorize, audit);
+    if (completed)
+        return completed;
+    return withValidatedEntityIntegrationPlan(root, requested, (plan, candidate) => {
+        const storeOwner = (0, entity_transaction_1.entityLockOwner)(root, plan.storeLocator), sourceOwner = (0, entity_renumber_transaction_1.entitySourcePublicationOwner)(root);
+        if (!storeOwner || !sourceOwner)
+            throw new entity_transaction_1.EntityStoreError('unknown-owner', 'Integration publication requires both owners.');
+        const pending = '.ax/state/entity-transactions/' + plan.operationId, journalFile = pending + '/journal.json';
+        if (integrationRead(root, '.ax/state/entity-completed/' + plan.operationId + '/journal.json'))
+            throw new entity_transaction_1.EntityStoreError('recovery-required', 'This operation already has a completion receipt; verify it through recovery.');
+        const program = JSON.stringify(plan), journal = JSON.stringify({ schema: 'holmes-entity-integration-journal/1', plan, storeOwner, sourceOwner });
+        const progress = integrationProgress(root, plan), targets = [...new Set(plan.steps.flatMap(step => step.specId ? [step.specId] : []))].sort();
+        const authority = () => { authorize(); for (const id of targets)
+            authorize(id); };
+        let persisted = false;
+        const verify = () => {
+            if (JSON.stringify(plan) !== program)
+                throw new entity_transaction_1.EntityStoreError('plan-changed', 'Integration program changed after regeneration.');
+            if (!(0, node_util_1.isDeepStrictEqual)((0, entity_transaction_1.entityLockOwner)(root, plan.storeLocator), storeOwner) || !(0, node_util_1.isDeepStrictEqual)((0, entity_renumber_transaction_1.entitySourcePublicationOwner)(root), sourceOwner))
+                throw new entity_transaction_1.EntityStoreError('unknown-owner', 'Integration publication ownership changed.');
+            if (persisted && integrationRead(root, journalFile)?.toString('utf8') !== journal)
+                throw new entity_transaction_1.EntityStoreError('plan-changed', 'Integration journal changed before publication.');
+            progress.verify();
+        };
+        authority();
+        verify();
+        (0, entity_transaction_1.publishEntityRecord)(root, journalFile, journal);
+        persisted = true;
+        for (let index = 0; index < plan.steps.length; index++) {
+            verify();
+            authority();
+            beforePublish?.(plan, index);
+            verify();
+            authority();
+            verify();
+            (0, entity_transaction_1.applyEntityByteChange)(root, plan.steps[index].change);
+            progress.advance(plan.steps[index].change);
+        }
+        verify();
+        authority();
+        (0, entity_transaction_1.publishEntityRecord)(root, pending + '/derived.json', JSON.stringify({ schema: 'holmes-integration-derived-obligations/1', operationId: plan.operationId,
+            workspaceId: plan.workspaceId, storeId: plan.storeId, target: entityIntegrationTarget(plan), graph: 'pending', semantic: 'pending',
+            changedPaths: [...new Set(plan.steps.map(step => step.change.locator))].sort() }));
+        audit(plan, undefined, candidate.renumbered ?? []);
+        verify();
+        authority(); // A-SPEC-645
+        (0, entity_transaction_1.retireEntityOperation)(root, plan.operationId, plan.storeLocator, (0, entity_transaction_1.entityContentVersion)(journal));
+        return { ok: true, state: 'completed', operationId: plan.operationId };
+    });
+}
+/**
+ * @implements A-SPEC-639 — abandon a PENDING integration a third state blocked: claim both dead
+ * generations exactly as recovery does, revert the operation's own publications, preserve every
+ * foreign byte, audit, and retire the operation as abandoned. A completed operation is refused.
+ */
+async function abandonEntityIntegration(root, inspected, authorize, audit) {
+    if (typeof authorize !== 'function' || typeof audit !== 'function')
+        throw new entity_transaction_1.EntityStoreError('authority-required', 'Abandonment requires current authority and durable audit adapters.');
+    root = fs.realpathSync(root);
+    authorize();
+    const request = validateEntityIntegrationRecoveryRequest(root, inspected);
+    const observed = inspectEntityIntegrationRecovery(root, request.operationId);
+    if (observed.state !== 'pending')
+        throw new entity_transaction_1.EntityStoreError('unsupported-recovery', 'Only a pending operation can be abandoned; a completed operation is already retired.');
+    if (!(0, node_util_1.isDeepStrictEqual)(observed, request))
+        throw new entity_transaction_1.EntityStoreError('plan-changed', 'Inspect the current integration recovery state before authorizing its abandonment.');
+    const plan = observed.plan, directory = '.ax/state/entity-transactions/' + plan.operationId, journalFile = directory + '/journal.json';
+    const identity = (0, workspace_identity_1.workspaceIdentity)(root);
+    if (identity.state !== 'registered' || identity.workspaceId !== plan.workspaceId)
+        throw new entity_transaction_1.EntityStoreError('workspace-mismatch', 'Abandonment requires the registered destination workspace.');
+    const ownStore = observed.storeOwner ? entity_transaction_1.withEntityRecoveryLock : entity_transaction_1.withEntityStoreLock;
+    return ownStore(root, plan.storeLocator, () => {
+        const storeOwner = (0, entity_transaction_1.entityLockOwner)(root, plan.storeLocator);
+        if (!storeOwner || (observed.storeOwner && !(0, node_util_1.isDeepStrictEqual)(observed.storeOwner, storeOwner)))
+            throw new entity_transaction_1.EntityStoreError('unknown-owner', 'Abandonment store ownership changed before claim.');
+        if ((0, entity_transaction_1.entityContentVersion)(integrationRead(root, journalFile) ?? Buffer.alloc(0)) !== observed.journalVersion)
+            throw new entity_transaction_1.EntityStoreError('plan-changed', 'Recovery journal changed before claim.');
+        if (!observed.storeOwner)
+            (0, entity_transaction_1.publishEntityRecord)(root, directory + '/store-owners/' + storeOwner.token + '.json', JSON.stringify({ schema: 'holmes-integration-store-owner/1', operationId: plan.operationId, journalVersion: observed.journalVersion, owner: storeOwner }));
+        return (0, entity_renumber_transaction_1.withRecoveredSourcePublication)(root, plan.operationId, observed.sourceOwner, () => {
+            const sourceOwner = (0, entity_renumber_transaction_1.entitySourcePublicationOwner)(root);
+            if (!sourceOwner || (observed.sourceOwner && !(0, node_util_1.isDeepStrictEqual)(sourceOwner, observed.sourceOwner)))
+                throw new entity_transaction_1.EntityStoreError('unknown-owner', 'Abandonment requires unchanged shared source ownership.');
+            const current = inspectEntityIntegrationRecovery(root, plan.operationId);
+            if (current.journalVersion !== observed.journalVersion || current.state !== 'pending' || current.completionVersion !== null)
+                throw new entity_transaction_1.EntityStoreError('plan-changed', 'The pending operation changed before abandonment.');
+            authorize();
+            (0, entity_transaction_1.settleEntityTransients)(root, plan.steps.map(step => step.change)); // @implements A-SPEC-640 — after every refusal point, before the revert
+            const outcome = (0, entity_transaction_1.abandonPublishedSteps)(root, plan.steps.map(step => step.change));
+            audit(plan, outcome);
+            (0, entity_transaction_1.abandonEntityOperation)(root, plan.operationId, plan.storeLocator, observed.journalVersion, outcome);
+            return { ok: true, state: 'abandoned', operationId: plan.operationId, ...outcome };
+        }, { file: journalFile, version: observed.journalVersion });
+    });
+}
+async function recoverEntityIntegration(root, inspected, authorize, audit, beforePublish) {
+    if (typeof authorize !== 'function' || typeof audit !== 'function')
+        throw new entity_transaction_1.EntityStoreError('authority-required', 'Recovery requires current authority and durable audit adapters.');
+    root = fs.realpathSync(root);
+    authorize();
+    const request = validateEntityIntegrationRecoveryRequest(root, inspected);
+    const current = inspectEntityIntegrationRecovery(root, request.operationId);
+    if (current.state === 'completed') {
+        const completed = await retryCompletedEntityIntegration(root, validateEntityIntegrationPlan(request.plan), authorize, audit, current);
+        if (!completed)
+            throw new entity_transaction_1.EntityStoreError('plan-changed', 'Inspected completion is no longer present.');
+        return completed;
+    }
+    const observed = await validateEntityIntegrationRecoveryProgram(root, request.operationId);
+    if (!(0, node_util_1.isDeepStrictEqual)(observed, request))
+        throw new entity_transaction_1.EntityStoreError('plan-changed', 'Inspect the current integration recovery state before authorization.');
+    const plan = observed.plan, program = JSON.stringify(plan), directory = '.ax/state/entity-transactions/' + plan.operationId, journalFile = directory + '/journal.json';
+    const journalBytes = integrationRead(root, journalFile);
+    const journal = JSON.parse(journalBytes.toString('utf8'));
+    const targets = observed.completionVersion ? [] : [...new Set(plan.steps.flatMap(step => step.specId ? [step.specId] : []))].sort();
+    const authority = () => { authorize(); for (const id of targets)
+        authorize(id); };
+    const identity = () => {
+        const current = (0, workspace_identity_1.workspaceIdentity)(root);
+        if (current.state !== 'registered' || current.workspaceId !== plan.workspaceId)
+            throw new entity_transaction_1.EntityStoreError('workspace-mismatch', 'Recovery requires the registered destination workspace.');
+    };
+    identity();
+    authority();
+    const ownStore = observed.storeOwner ? entity_transaction_1.withEntityRecoveryLock : entity_transaction_1.withEntityStoreLock;
+    return ownStore(root, plan.storeLocator, () => {
+        const storeOwner = (0, entity_transaction_1.entityLockOwner)(root, plan.storeLocator);
+        if (!storeOwner || (observed.storeOwner && !(0, node_util_1.isDeepStrictEqual)(observed.storeOwner, storeOwner)))
+            throw new entity_transaction_1.EntityStoreError('unknown-owner', 'Recovery store ownership changed before claim.');
+        if ((0, entity_transaction_1.entityContentVersion)(integrationRead(root, journalFile) ?? Buffer.alloc(0)) !== observed.journalVersion)
+            throw new entity_transaction_1.EntityStoreError('plan-changed', 'Recovery journal changed before claim.');
+        if (!observed.storeOwner)
+            (0, entity_transaction_1.publishEntityRecord)(root, directory + '/store-owners/' + storeOwner.token + '.json', JSON.stringify({ schema: 'holmes-integration-store-owner/1', operationId: plan.operationId, journalVersion: observed.journalVersion, owner: storeOwner }));
+        return (0, entity_renumber_transaction_1.withRecoveredSourcePublication)(root, plan.operationId, observed.sourceOwner, () => {
+            const sourceOwner = (0, entity_renumber_transaction_1.entitySourcePublicationOwner)(root);
+            if (!sourceOwner || (observed.sourceOwner && !(0, node_util_1.isDeepStrictEqual)(sourceOwner, observed.sourceOwner)))
+                throw new entity_transaction_1.EntityStoreError('unknown-owner', 'Recovery requires unchanged shared source ownership.');
+            const receipts = [integrationOwnerBinding(root, directory, 'store', journal.storeOwner, storeOwner, plan.operationId, observed.journalVersion),
+                integrationOwnerBinding(root, directory, 'source', journal.sourceOwner, sourceOwner, plan.operationId, observed.journalVersion)].filter((receipt) => !!receipt);
+            const current = inspectEntityIntegrationRecovery(root, plan.operationId);
+            if (current.journalVersion !== observed.journalVersion || current.completionVersion !== observed.completionVersion || current.conflicts.length || !(0, node_util_1.isDeepStrictEqual)(current.observedPrefixes, observed.observedPrefixes))
+                throw new entity_transaction_1.EntityStoreError('plan-changed', 'Recovery prefix or completion receipt changed before publication.');
+            const progress = integrationProgress(root, plan), prefix = observed.observedPrefixes[0];
+            for (const step of plan.steps.slice(0, prefix))
+                progress.advance(step.change);
+            const verify = () => {
+                identity();
+                if (JSON.stringify(plan) !== program || !integrationRead(root, journalFile)?.equals(journalBytes))
+                    throw new entity_transaction_1.EntityStoreError('plan-changed', 'Recovery program or journal changed.');
+                const completion = integrationRead(root, directory + '/completion.json');
+                if ((completion ? (0, entity_transaction_1.entityContentVersion)(completion) : null) !== observed.completionVersion)
+                    throw new entity_transaction_1.EntityStoreError('plan-changed', 'Recovery completion receipt changed.');
+                if (!(0, node_util_1.isDeepStrictEqual)((0, entity_transaction_1.entityLockOwner)(root, plan.storeLocator), storeOwner) || !(0, node_util_1.isDeepStrictEqual)((0, entity_renumber_transaction_1.entitySourcePublicationOwner)(root), sourceOwner))
+                    throw new entity_transaction_1.EntityStoreError('unknown-owner', 'Recovery ownership changed.');
+                for (const receipt of receipts)
+                    if (!integrationRead(root, receipt.file)?.equals(receipt.bytes))
+                        throw new entity_transaction_1.EntityStoreError('plan-changed', 'Recovery ownership receipt changed.');
+                progress.verify();
+            };
+            (0, entity_transaction_1.settleEntityTransients)(root, plan.steps.map(step => step.change)); // @implements A-SPEC-640 — after every refusal point, before the replay
+            for (let index = prefix; index < plan.steps.length; index++) {
+                verify();
+                authority();
+                beforePublish?.(plan, index);
+                verify();
+                authority();
+                verify();
+                (0, entity_transaction_1.applyEntityByteChange)(root, plan.steps[index].change);
+                progress.advance(plan.steps[index].change);
+            }
+            verify();
+            authority();
+            const derivedFile = directory + '/derived.json', derived = JSON.stringify({ schema: 'holmes-integration-derived-obligations/1', operationId: plan.operationId,
+                workspaceId: plan.workspaceId, storeId: plan.storeId, target: entityIntegrationTarget(plan), graph: 'pending', semantic: 'pending',
+                changedPaths: [...new Set(plan.steps.map(step => step.change.locator))].sort() });
+            const existing = integrationRead(root, derivedFile);
+            if (existing && existing.toString('utf8') !== derived)
+                throw new entity_transaction_1.EntityStoreError('plan-changed', 'Derived integration obligations changed.');
+            if (!existing && observed.completionVersion)
+                throw new entity_transaction_1.EntityStoreError('completion-conflict', 'A completed publication is missing its derived obligations.');
+            if (!existing)
+                (0, entity_transaction_1.publishEntityRecord)(root, derivedFile, derived);
+            audit(plan, observed.completionVersion !== null);
+            verify();
+            authority();
+            if (observed.completionVersion)
+                retireExistingIntegrationCompletion(root, observed);
+            else
+                (0, entity_transaction_1.retireEntityOperation)(root, plan.operationId, plan.storeLocator, observed.journalVersion);
+            return { ok: true, state: 'completed', operationId: plan.operationId };
+        }, { file: journalFile, version: observed.journalVersion });
+    });
+}
+/** Archive an already certified publication; its historical owner and receipt remain immutable. */
+function retireExistingIntegrationCompletion(root, observed) {
+    const current = inspectEntityIntegrationRecovery(root, observed.operationId);
+    if (!observed.completionVersion || current.state !== 'pending' || current.completionVersion !== observed.completionVersion || current.journalVersion !== observed.journalVersion ||
+        !(0, node_util_1.isDeepStrictEqual)(current.plan, observed.plan) || current.conflicts.length || !(0, node_util_1.isDeepStrictEqual)(current.observedPrefixes, [observed.plan.steps.length]) || !current.storeOwner || !current.sourceOwner) {
+        throw new entity_transaction_1.EntityStoreError('completion-conflict', 'Retirement requires an unchanged, owned and verified completion receipt.');
+    }
+    const pending = (0, entity_transaction_1.entityDirectory)(root, '.ax/state/entity-transactions/' + observed.operationId);
+    const destination = path.join((0, entity_transaction_1.entityDirectory)(root, '.ax/state/entity-completed', true), observed.operationId);
+    try {
+        fs.lstatSync(destination);
+        throw new entity_transaction_1.EntityStoreError('retirement-conflict', 'Another completed operation occupies the retirement destination.');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const journal = (0, entity_transaction_1.readEntityBytes)(path.join(pending, 'journal.json')), receipt = (0, entity_transaction_1.readEntityBytes)(path.join(pending, 'completion.json'));
+    if (!journal || !receipt || (0, entity_transaction_1.entityContentVersion)(journal) !== observed.journalVersion || (0, entity_transaction_1.entityContentVersion)(receipt) !== observed.completionVersion ||
+        !(0, node_util_1.isDeepStrictEqual)((0, entity_transaction_1.entityLockOwner)(root, observed.plan.storeLocator), current.storeOwner) || !(0, node_util_1.isDeepStrictEqual)((0, entity_renumber_transaction_1.entitySourcePublicationOwner)(root), current.sourceOwner)) {
+        throw new entity_transaction_1.EntityStoreError('plan-changed', 'Completion or ownership changed before retirement.');
+    }
+    fs.renameSync(pending, destination);
+}
+/** Completed retries verify existing evidence; they never publish files or repair missing audit. */
+async function retryCompletedEntityIntegration(root, plan, authorize, audit, request) {
+    const directory = '.ax/state/entity-completed/' + plan.operationId;
+    const journalBytes = integrationRead(root, directory + '/journal.json'), receiptBytes = integrationRead(root, directory + '/completion.json');
+    if (!journalBytes && !receiptBytes)
+        return undefined;
+    if (!journalBytes || !receiptBytes)
+        throw new entity_transaction_1.EntityStoreError('completion-conflict', 'Completed retry requires both journal and receipt.');
+    authorize();
+    const observed = inspectEntityIntegrationRecovery(root, plan.operationId);
+    if (observed.state !== 'completed' || observed.conflicts.length || !(0, node_util_1.isDeepStrictEqual)(observed.plan, plan) || (request && !(0, node_util_1.isDeepStrictEqual)(request, observed)))
+        throw new entity_transaction_1.EntityStoreError('completion-conflict', 'The completed operation differs from the requested plan or current files.');
+    const derivedBytes = integrationRead(root, directory + '/derived.json');
+    const derived = { schema: 'holmes-integration-derived-obligations/1', operationId: plan.operationId, workspaceId: plan.workspaceId, storeId: plan.storeId,
+        target: entityIntegrationTarget(plan), graph: 'pending', semantic: 'pending', changedPaths: [...new Set(plan.steps.map(step => step.change.locator))].sort() };
+    if (!derivedBytes || !(0, node_util_1.isDeepStrictEqual)(JSON.parse(derivedBytes.toString('utf8')), derived))
+        throw new entity_transaction_1.EntityStoreError('completion-conflict', 'Completed derived-state obligations are missing or changed.');
+    const identity = () => {
+        const current = (0, workspace_identity_1.workspaceIdentity)(root);
+        if (current.state !== 'registered' || current.workspaceId !== plan.workspaceId)
+            throw new entity_transaction_1.EntityStoreError('workspace-mismatch', 'Completed retry requires the registered destination workspace.');
+    };
+    identity();
+    const journal = JSON.parse(journalBytes.toString('utf8')), receipt = JSON.parse(receiptBytes.toString('utf8'));
+    if (observed.storeOwner && !(0, node_util_1.isDeepStrictEqual)(observed.storeOwner, receipt.lockOwner))
+        throw new entity_transaction_1.EntityStoreError('unknown-owner', 'Current store ownership belongs to another operation.');
+    const bindings = [];
+    const storeBinding = integrationOwnerBinding(root, directory, 'store', journal.storeOwner, receipt.lockOwner, plan.operationId, observed.journalVersion);
+    if (storeBinding)
+        bindings.push(storeBinding);
+    if (observed.sourceOwner) {
+        const sourceBinding = integrationOwnerBinding(root, directory, 'source', journal.sourceOwner, observed.sourceOwner, plan.operationId, observed.journalVersion);
+        if (sourceBinding)
+            bindings.push(sourceBinding);
+    }
+    const gitBasis = { head: (0, entity_git_snapshot_1.readEntityGitSnapshot)(root, 'HEAD', plan.storeLocator).commit, indexVersion: (0, entity_git_snapshot_1.readEntityGitIndex)(root).version };
+    const candidate = await compileEntityIntegrationCandidate(root, (0, entity_git_snapshot_1.readEntityGitInputs)(root, plan.commits, plan.storeLocator), plan.storeLocator, plan, true);
+    if (!(0, node_util_1.isDeepStrictEqual)(integrationPlanFromCandidate(candidate, root, plan.operationId), plan))
+        throw new entity_transaction_1.EntityStoreError('plan-changed', 'Completed journal differs from its original program.');
+    if (!(0, node_util_1.isDeepStrictEqual)(inspectEntityIntegrationRecovery(root, plan.operationId), observed))
+        throw new entity_transaction_1.EntityStoreError('plan-changed', 'Completion changed while regenerating the original program.');
+    const ownStore = observed.storeOwner ? entity_transaction_1.withEntityRecoveryLock : entity_transaction_1.withEntityStoreLock;
+    return ownStore(root, plan.storeLocator, () => (0, entity_renumber_transaction_1.withRecoveredSourcePublication)(root, plan.operationId, observed.sourceOwner, () => {
+        const storeOwner = (0, entity_transaction_1.entityLockOwner)(root, plan.storeLocator), sourceOwner = (0, entity_renumber_transaction_1.entitySourcePublicationOwner)(root), program = JSON.stringify(plan);
+        if (!storeOwner || (observed.storeOwner && !(0, node_util_1.isDeepStrictEqual)(storeOwner, observed.storeOwner)) || !(0, node_util_1.isDeepStrictEqual)(sourceOwner, observed.sourceOwner))
+            throw new entity_transaction_1.EntityStoreError('unknown-owner', 'Completed retry ownership changed.');
+        const progress = integrationProgress(root, plan, gitBasis);
+        for (const step of plan.steps)
+            progress.advance(step.change);
+        const verify = () => {
+            identity();
+            if (JSON.stringify(plan) !== program || !integrationRead(root, directory + '/journal.json')?.equals(journalBytes) || !integrationRead(root, directory + '/completion.json')?.equals(receiptBytes) ||
+                integrationRead(root, '.ax/state/entity-transactions/' + plan.operationId + '/journal.json'))
+                throw new entity_transaction_1.EntityStoreError('completion-conflict', 'Completion evidence changed.');
+            if (!integrationRead(root, directory + '/derived.json')?.equals(derivedBytes))
+                throw new entity_transaction_1.EntityStoreError('completion-conflict', 'Completed derived-state obligations changed.');
+            for (const binding of bindings)
+                if (!integrationRead(root, binding.file)?.equals(binding.bytes))
+                    throw new entity_transaction_1.EntityStoreError('unknown-owner', 'Completed ownership binding changed.');
+            if (!(0, node_util_1.isDeepStrictEqual)((0, entity_transaction_1.entityLockOwner)(root, plan.storeLocator), storeOwner) || !(0, node_util_1.isDeepStrictEqual)((0, entity_renumber_transaction_1.entitySourcePublicationOwner)(root), sourceOwner))
+                throw new entity_transaction_1.EntityStoreError('unknown-owner', 'Completed retry ownership changed.');
+            progress.verify();
+        };
+        verify();
+        authorize();
+        audit(plan, true);
+        verify();
+        authorize();
+        return { ok: true, state: 'completed', operationId: plan.operationId };
+    }));
+}
+/** Bind replacement owners to this immutable journal; old dead-owner generations remain unchanged. */
+function integrationOwnerBinding(root, directory, kind, original, current, operationId, journalVersion) {
+    if ((0, node_util_1.isDeepStrictEqual)(original, current))
+        return undefined;
+    const file = directory + '/' + kind + '-owners/' + current.token + '.json', bytes = integrationRead(root, file);
+    const expected = { schema: kind === 'store' ? 'holmes-integration-store-owner/1' : 'holmes-renumber-source-owner/1', operationId, journalVersion, owner: current };
+    if (!bytes || !(0, node_util_1.isDeepStrictEqual)(JSON.parse(bytes.toString('utf8')), expected))
+        throw new entity_transaction_1.EntityStoreError('unknown-owner', 'Recovery owner is not bound to this integration journal.');
+    return { file, bytes };
+}
+function integrationRead(root, locator) {
+    if (!locator || /[\\:\x00]/.test(locator) || locator.split('/').some(part => !part || part === '.' || part === '..'))
+        throw new entity_transaction_1.EntityStoreError('unsafe-path', 'Integration input must be a workspace-relative file.');
+    return (0, entity_transaction_1.readEntityBytes)(path.join((0, entity_transaction_1.entityDirectory)(root, path.posix.dirname(locator)), path.posix.basename(locator)));
+}
+/** Keep the original approval target while binding a lost-response retry to durable completion. */
+function validateEntityIntegrationRecoveryRequest(root, inspected) {
+    const fail = () => { throw new entity_transaction_1.EntityStoreError('plan-changed', 'Provide an unchanged recovery request bound to the current integration journal.'); };
+    if (!inspected || typeof inspected !== 'object' || Array.isArray(inspected))
+        return fail();
+    const request = JSON.parse(JSON.stringify(inspected));
+    if (typeof request.operationId !== 'string')
+        return fail();
+    const current = inspectEntityIntegrationRecovery(root, request.operationId);
+    if ((0, node_util_1.isDeepStrictEqual)(request, current))
+        return request;
+    // Only completed verification tolerates obsolete prefix/ownership observations.
+    // A pending writer must still match the complete current inspection exactly.
+    if (current.state !== 'completed' || request.state !== 'pending' || current.conflicts.length ||
+        !Array.isArray(request.conflicts) || request.conflicts.length || !Array.isArray(request.observedPrefixes) || request.observedPrefixes.length !== 1 ||
+        !Number.isSafeInteger(request.observedPrefixes[0]) || request.observedPrefixes[0] < 0 || request.observedPrefixes[0] > current.plan.steps.length ||
+        (request.completionVersion !== null && request.completionVersion !== current.completionVersion))
+        return fail();
+    if (!(0, node_util_1.isDeepStrictEqual)({ ...request, state: current.state, observedPrefixes: current.observedPrefixes,
+        storeOwner: current.storeOwner, sourceOwner: current.sourceOwner, completionVersion: current.completionVersion }, current))
+        return fail();
+    const directory = '.ax/state/entity-completed/' + current.operationId;
+    const journalBytes = integrationRead(root, directory + '/journal.json');
+    if (!journalBytes || (0, entity_transaction_1.entityContentVersion)(journalBytes) !== current.journalVersion)
+        return fail();
+    const journal = JSON.parse(journalBytes.toString('utf8'));
+    for (const [kind, original, observed] of [['store', journal.storeOwner, request.storeOwner], ['source', journal.sourceOwner, request.sourceOwner]]) {
+        if (observed === null)
+            continue;
+        if (!observed || typeof observed !== 'object' || Array.isArray(observed) ||
+            !(0, node_util_1.isDeepStrictEqual)(Object.keys(observed).sort(), ['token', 'version']) ||
+            typeof observed.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(observed.token) ||
+            typeof observed.version !== 'string' || !/^sha256:[0-9a-f]{64}$/.test(observed.version))
+            return fail();
+        integrationOwnerBinding(root, directory, kind, original, observed, current.operationId, current.journalVersion);
+    }
+    if (!(0, node_util_1.isDeepStrictEqual)(inspectEntityIntegrationRecovery(root, request.operationId), current))
+        return fail();
+    return request;
+}
+/** Observation only; matching bytes do not authorize replay of a journal's program. */
+function inspectEntityIntegrationRecovery(root, operationId) {
+    const invalid = () => { throw new entity_transaction_1.EntityStoreError('invalid-plan', 'Invalid integration recovery journal or completion receipt.'); };
+    const uuid = (value) => typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value);
+    const exact = (value, keys) => !!value && typeof value === 'object' && !Array.isArray(value) && (0, node_util_1.isDeepStrictEqual)(Object.keys(value).sort(), [...keys].sort());
+    const owner = (value) => exact(value, ['token', 'version']) && uuid(value.token) && typeof value.version === 'string' && /^sha256:[0-9a-f]{64}$/.test(value.version);
+    if (!uuid(operationId))
+        invalid();
+    root = fs.realpathSync(root);
+    const pendingFile = '.ax/state/entity-transactions/' + operationId + '/journal.json';
+    const completedDirectory = '.ax/state/entity-completed/' + operationId;
+    const completedFile = completedDirectory + '/journal.json';
+    const pending = integrationRead(root, pendingFile), completed = integrationRead(root, completedFile);
+    // @implements A-SPEC-634 — a pending directory without a journal is an operation that died between
+    // its locks and its journal; it is recovered through entity_store, not through this inspection.
+    if (!pending && !completed && (0, entity_transaction_1.entityStat)(path.join((0, entity_transaction_1.entityDirectory)(root, '.ax/state/entity-transactions'), operationId)))
+        throw new entity_transaction_1.EntityStoreError('no-journal', 'Operation ' + operationId + ' was interrupted before its journal existed; inspect entity_store recovery-plan and recover it there.');
+    if ((!pending && !completed) || (pending && completed))
+        invalid();
+    const state = pending ? 'pending' : 'completed', bytes = (pending ?? completed);
+    const journal = JSON.parse(bytes.toString('utf8'));
+    if (!exact(journal, ['schema', 'plan', 'storeOwner', 'sourceOwner']))
+        return invalid();
+    if (journal.schema !== 'holmes-entity-integration-journal/1' || !owner(journal.storeOwner) || !owner(journal.sourceOwner))
+        invalid();
+    const plan = validateEntityIntegrationPlan(journal.plan), journalVersion = (0, entity_transaction_1.entityContentVersion)(bytes);
+    if (plan.operationId !== operationId)
+        invalid();
+    const bindings = [];
+    const receiptDirectory = state === 'completed' ? completedDirectory : path.posix.dirname(pendingFile);
+    const receiptBytes = integrationRead(root, receiptDirectory + '/completion.json');
+    if (state === 'completed' && !receiptBytes)
+        return invalid();
+    if (receiptBytes) {
+        const receipt = JSON.parse(receiptBytes.toString('utf8'));
+        if (!exact(receipt, ['schema', 'operationId', 'storeLocator', 'lockOwner', 'journalVersion']))
+            return invalid();
+        if (receipt.schema !== 'holmes-entity-completion/1' || receipt.operationId !== operationId || receipt.storeLocator !== plan.storeLocator ||
+            receipt.journalVersion !== journalVersion || !owner(receipt.lockOwner))
+            invalid();
+        const binding = integrationOwnerBinding(root, receiptDirectory, 'store', journal.storeOwner, receipt.lockOwner, operationId, journalVersion);
+        if (binding)
+            bindings.push(binding);
+    }
+    const destination = (0, entity_git_snapshot_1.readEntityGitSnapshot)(root, plan.destination.head, plan.storeLocator);
+    if (destination.workspaceId !== plan.workspaceId || destination.storeId !== plan.storeId)
+        invalid();
+    const storeOwner = (0, entity_transaction_1.entityLockOwner)(root, plan.storeLocator), sourceOwner = (0, entity_renumber_transaction_1.entitySourcePublicationOwner)(root);
+    if (state === 'pending') {
+        for (const [kind, original, current] of [['store', journal.storeOwner, storeOwner], ['source', journal.sourceOwner, sourceOwner]])
+            if (current) {
+                const binding = integrationOwnerBinding(root, path.posix.dirname(pendingFile), kind, original, current, operationId, journalVersion);
+                if (binding)
+                    bindings.push(binding);
+            }
+    }
+    const asideConflicts = [];
+    const observe = (locator) => {
+        // @implements A-SPEC-640 — a lone aside beside an absent target IS the target's current state.
+        if (!locator || /[\\:\x00]/.test(locator) || locator.split('/').some(part => !part || part === '.' || part === '..'))
+            throw new entity_transaction_1.EntityStoreError('unsafe-path', 'Integration input must be a workspace-relative file.');
+        const observed = (0, entity_transaction_1.observeEntityTarget)(root, locator);
+        if (observed.asides.length > 1)
+            asideConflicts.push(locator + ': multiple aside files');
+        return { version: observed.bytes ? (0, entity_transaction_1.entityContentVersion)(observed.bytes) : null, mode: observed.mode };
+    };
+    const actual = new Map(), expected = new Map(), mismatches = new Set();
+    for (const check of plan.checks) {
+        actual.set(check.locator, observe(check.locator));
+        expected.set(check.locator, { version: check.version, mode: check.mode });
+        if (!(0, node_util_1.isDeepStrictEqual)(actual.get(check.locator), expected.get(check.locator)))
+            mismatches.add(check.locator);
+    }
+    const observedPrefixes = [], conflicts = [...asideConflicts];
+    if (!mismatches.size)
+        observedPrefixes.push(0);
+    plan.steps.forEach(({ change }, index) => {
+        const next = { version: change.after === null ? null : (0, entity_transaction_1.entityContentVersion)(Buffer.from(change.after, 'base64')), mode: change.afterMode };
+        expected.set(change.locator, next);
+        if ((0, node_util_1.isDeepStrictEqual)(actual.get(change.locator), next))
+            mismatches.delete(change.locator);
+        else
+            mismatches.add(change.locator);
+        if (!mismatches.size)
+            observedPrefixes.push(index + 1);
+    });
+    if (!observedPrefixes.length)
+        conflicts.push('Actual bytes or modes match no integration prefix.');
+    if (observedPrefixes.length > 1)
+        conflicts.push('Actual bytes and modes match multiple integration prefixes; progress is ambiguous.');
+    if (state === 'completed' && !observedPrefixes.includes(plan.steps.length))
+        conflicts.push('Completed receipt exists, but current files differ from its final prefix.');
+    if (state === 'pending' && receiptBytes && !observedPrefixes.includes(plan.steps.length))
+        conflicts.push('Pending completion receipt differs from the actual final prefix.');
+    // Pending observations also expose Git, configuration, policy and membership changes.
+    if (state === 'pending' && observedPrefixes.length) {
+        const progress = integrationProgress(root, plan);
+        let advanced = 0;
+        for (const prefix of observedPrefixes) {
+            while (advanced < prefix)
+                progress.advance(plan.steps[advanced++].change);
+            try {
+                progress.verify();
+            }
+            catch (error) {
+                conflicts.push('prefix ' + prefix + ': ' + (error instanceof Error ? error.message : 'Input verification failed.'));
+            }
+        }
+    }
+    for (const [locator, value] of actual)
+        if (!(0, node_util_1.isDeepStrictEqual)(observe(locator), value))
+            conflicts.push('File changed during recovery inspection: ' + locator);
+    if (!(0, node_util_1.isDeepStrictEqual)(integrationRead(root, pendingFile), pending) || !(0, node_util_1.isDeepStrictEqual)(integrationRead(root, completedFile), completed) ||
+        bindings.some(binding => !integrationRead(root, binding.file)?.equals(binding.bytes)) ||
+        !(0, node_util_1.isDeepStrictEqual)(integrationRead(root, receiptDirectory + '/completion.json'), receiptBytes) ||
+        !(0, node_util_1.isDeepStrictEqual)((0, entity_transaction_1.entityLockOwner)(root, plan.storeLocator), storeOwner) || !(0, node_util_1.isDeepStrictEqual)((0, entity_renumber_transaction_1.entitySourcePublicationOwner)(root), sourceOwner)) {
+        throw new entity_transaction_1.EntityStoreError('plan-changed', 'Recovery journal, receipt or ownership changed during inspection.');
+    }
+    return { schema: 'holmes-entity-integration-recovery-inspection/2', state, operationId, journalVersion, completionVersion: receiptBytes ? (0, entity_transaction_1.entityContentVersion)(receiptBytes) : null, plan, observedPrefixes, conflicts, storeOwner, sourceOwner };
+}
+/** Re-derive the pending journal program before any recovery writer may use it. */
+async function validateEntityIntegrationRecoveryProgram(root, operationId) {
+    root = fs.realpathSync(root);
+    const observed = inspectEntityIntegrationRecovery(root, operationId);
+    if (observed.state !== 'pending' || observed.conflicts.length || observed.observedPrefixes.length !== 1)
+        throw new entity_transaction_1.EntityStoreError('recovery-required', 'A pending, unambiguous and unchanged integration prefix is required.');
+    const plan = observed.plan, inputs = (0, entity_git_snapshot_1.readEntityGitInputs)(root, plan.commits, plan.storeLocator);
+    const candidate = await compileEntityIntegrationCandidate(root, inputs, plan.storeLocator, plan);
+    const regenerated = integrationPlanFromCandidate(candidate, root, plan.operationId);
+    if (!(0, node_util_1.isDeepStrictEqual)(regenerated, plan))
+        throw new entity_transaction_1.EntityStoreError('plan-changed', 'Recovery program differs from its original Git and current policy inputs.');
+    const after = inspectEntityIntegrationRecovery(root, operationId);
+    if (!(0, node_util_1.isDeepStrictEqual)(after, observed))
+        throw new entity_transaction_1.EntityStoreError('plan-changed', 'Integration recovery state changed during program regeneration.');
+    return after;
+}
+/** Expected state advances only after a successful byte publication. No persisted prefix counter is trusted. */
+function integrationProgress(root, plan, gitBasis = plan.destination) {
+    const destination = (0, entity_git_snapshot_1.readEntityGitSnapshot)(root, plan.destination.head, plan.storeLocator);
+    const registrations = destination.files.filter(file => /^\.ax\/entities\/stores\/[^/]+\.json$/.test(file.path));
+    const blobs = (0, entity_git_snapshot_1.readEntityGitBlobs)(root, registrations.map(file => file.oid));
+    const canonicalRoots = ['.ax/entities', ...registrations.map(file => JSON.parse(blobs.get(file.oid).toString()).storeLocator)];
+    const expected = new Map(plan.checks.map(check => [check.locator, { version: check.version, mode: check.mode }]));
+    const version = (bytes) => bytes ? (0, entity_transaction_1.entityContentVersion)(bytes) : null;
+    const verify = () => {
+        if ((0, entity_git_snapshot_1.readEntityGitSnapshot)(root, 'HEAD', plan.storeLocator).commit !== gitBasis.head || (0, entity_git_snapshot_1.readEntityGitIndex)(root).version !== gitBasis.indexVersion)
+            throw new entity_transaction_1.EntityStoreError('plan-changed', 'Git HEAD or index changed during integration.');
+        if (version(integrationRead(root, '.ax/config.json')) !== plan.configVersion)
+            throw new entity_transaction_1.EntityStoreError('plan-changed', 'Integration config changed.');
+        for (const [locator, state] of expected) {
+            // @implements A-SPEC-640 — a lone aside beside an absent target is the target's current state.
+            const observed = (0, entity_transaction_1.observeEntityTarget)(root, locator);
+            if (version(observed.bytes) !== state.version || observed.mode !== state.mode)
+                throw new entity_transaction_1.EntityStoreError('external-change', 'Integration input changed outside the expected prefix: ' + locator);
+        }
+        for (const input of plan.policyInputs)
+            if (!expected.has(input.locator) && version(integrationRead(root, input.locator)) !== input.version)
+                throw new entity_transaction_1.EntityStoreError('plan-changed', 'Integration policy input changed: ' + input.locator);
+        const files = new Map(destination.files.map(file => [file.path, file.mode]));
+        for (const [locator, state] of expected) {
+            if (state.version === null)
+                files.delete(locator);
+            else
+                files.set(locator, state.mode ?? '100644');
+        }
+        const membership = destinationMembership(root, [...files].map(([file, mode]) => ({ path: file, mode })), canonicalRoots, integrationRead(root, '.gitignore')?.toString('utf8') ?? '');
+        if (membership.conflicts.length)
+            throw new entity_transaction_1.EntityStoreError('external-change', membership.conflicts.join('\n'));
+    };
+    return { verify, advance: (change) => expected.set(change.locator, { version: change.after === null ? null : (0, entity_transaction_1.entityContentVersion)(Buffer.from(change.after, 'base64')), mode: change.afterMode }) };
+}
+/** Executor boundary: a shape-valid plan still needs regeneration and current destination registration. */
+async function withValidatedEntityIntegrationPlan(root, inspected, act) {
+    const plan = validateEntityIntegrationPlan(inspected);
+    return inspectEntityIntegration(root, plan.commits, plan.storeLocator, (candidate, actualRoot) => {
+        const fresh = integrationPlanFromCandidate(candidate, actualRoot, plan.operationId);
+        if (!(0, node_util_1.isDeepStrictEqual)(fresh, plan))
+            throw new entity_transaction_1.EntityStoreError('plan-changed', 'Integration plan differs from current Git, file or policy inputs.');
+        (0, entity_store_1.assertEntityRepositoryReadable)(path.join(actualRoot, plan.storeLocator));
+        return act(fresh, candidate); // A-SPEC-645 — the regenerated candidate rides along (renumbers live only there)
+    });
+}
+async function prepareEntityIntegrationPlan(root, revisions, storeLocator, operationId = (0, node_crypto_1.randomUUID)()) {
+    return inspectEntityIntegration(root, revisions, storeLocator, (candidate, actualRoot) => integrationPlanFromCandidate(candidate, actualRoot, operationId));
+}
+/** Public review keeps the candidate and executable plan within the same owned inspection. */
+async function reviewEntityIntegration(root, revisions, storeLocator) {
+    return inspectEntityIntegration(root, revisions, storeLocator, (preview, actualRoot) => ({ preview,
+        ...(preview.ok ? { plan: integrationPlanFromCandidate(preview, actualRoot, (0, node_crypto_1.randomUUID)()) } : {}) }));
+}
+function integrationPlanFromCandidate(candidate, actualRoot, operationId) {
+    if (!candidate.ok || !candidate.steps)
+        throw new entity_transaction_1.EntityStoreError('plan-conflict', [...candidate.conflicts, ...candidate.pending.map(item => item.file + ': ' + item.reason)].join('\n'));
+    const config = (0, entity_transaction_1.readEntityBytes)(path.join((0, entity_transaction_1.entityDirectory)(actualRoot, '.ax'), 'config.json'));
+    return validateEntityIntegrationPlan({ schema: 'holmes-entity-integration/1', operationId, workspaceId: candidate.workspaceId, storeId: candidate.storeId, storeLocator: candidate.storeLocator,
+        commits: candidate.commits, destination: { head: candidate.destinationHead, indexVersion: candidate.indexVersion, membershipVersion: candidate.membershipVersion },
+        configVersion: config ? (0, entity_transaction_1.entityContentVersion)(config) : null, checks: candidate.checks, policyInputs: candidate.policyInputs, steps: candidate.steps });
+}
+/** Internal compilation, not validation or authorization of a caller-supplied execution payload. */
+function compileEntityIntegrationSteps(candidate) {
+    const refuse = (reason) => { throw new entity_transaction_1.EntityStoreError('invalid-plan', reason); };
+    if (!candidate.ok || candidate.conflicts.length || candidate.pending.length || !candidate.transitions)
+        refuse('Resolve candidate conflicts and transition obligations before compiling steps.');
+    const transitions = candidate.transitions;
+    const state = (bytes, mode) => {
+        if (bytes === null ? mode !== null : typeof bytes !== 'string' || (mode !== '100644' && mode !== '100755') || Buffer.from(bytes, 'base64').toString('base64') !== bytes)
+            refuse('Invalid byte/mode state.');
+        return { bytes, mode: mode };
+    };
+    const encoded = (text) => Buffer.from(text).toString('base64');
+    const checks = new Map(candidate.checks.map(check => [check.locator, check]));
+    if (checks.size !== candidate.checks.length)
+        refuse('Duplicate candidate input checks.');
+    const initial = new Map(), current = new Map(), final = new Map();
+    const bind = (locator, value) => {
+        if (!locator || /[\\:\x00]/.test(locator) || locator.split('/').some(part => !part || part === '.' || part === '..'))
+            refuse('Unsafe integration step locator.');
+        const check = checks.get(locator), version = value.bytes === null ? null : (0, entity_transaction_1.entityContentVersion)(Buffer.from(value.bytes, 'base64'));
+        if (!check || check.version !== version || check.mode !== value.mode)
+            refuse('Step input differs from inspected bytes/mode: ' + locator);
+        if (initial.has(locator) && !(0, node_util_1.isDeepStrictEqual)(initial.get(locator), value))
+            refuse('Conflicting initial state: ' + locator);
+        initial.set(locator, value);
+        current.set(locator, value);
+    };
+    for (const change of candidate.changes) {
+        if (final.has(change.locator))
+            refuse('Duplicate publication destination: ' + change.locator);
+        bind(change.locator, state(change.before, change.beforeMode));
+        final.set(change.locator, state(change.after, change.afterMode));
+    }
+    for (const step of transitions.unseal) {
+        const locator = candidate.storeLocator + '/' + step.documentLocator;
+        bind(locator, state(encoded(step.before), checks.get(locator)?.mode));
+    }
+    const documentIds = new Map();
+    for (const entry of transitions.publication) {
+        const locator = candidate.storeLocator + '/' + entry.documentLocator;
+        if (documentIds.has(locator))
+            refuse('Duplicate transition document path: ' + locator);
+        documentIds.set(locator, entry.entityId);
+        if (!initial.has(locator))
+            bind(locator, state(encoded(entry.text), checks.get(locator)?.mode));
+        const mode = final.get(locator)?.mode ?? initial.get(locator).mode;
+        final.set(locator, state(encoded(entry.text), mode));
+    }
+    for (const [oldPath, value] of initial)
+        if (value.bytes !== null)
+            for (const [newPath, next] of final) {
+                if (next.bytes !== null && oldPath !== newPath && (under(oldPath, newPath) || under(newPath, oldPath)))
+                    refuse('Directory/file transition requires explicit preparation: ' + oldPath + ' -> ' + newPath);
+            }
+    const steps = [];
+    const add = (phase, locator, next, meta = {}, expected) => {
+        const prior = current.get(locator);
+        if (!prior || (expected !== undefined && prior.bytes !== encoded(expected)))
+            refuse('Discontinuous integration step: ' + locator);
+        if ((0, node_util_1.isDeepStrictEqual)(prior, next))
+            return;
+        steps.push({ phase, ...meta, change: { locator, before: prior.bytes, after: next.bytes, beforeMode: prior.mode, afterMode: next.mode } });
+        current.set(locator, next);
+    };
+    for (const step of transitions.unseal) {
+        const locator = candidate.storeLocator + '/' + step.documentLocator;
+        add('unseal', locator, state(encoded(step.after), current.get(locator).mode), { entityId: step.entityId, specId: step.displayId }, step.before);
+    }
+    // Retire old paths before publishing replacements. No directory mutation is implicit in this plan.
+    const publication = [...final].sort(([a, av], [b, bv]) => Number(av.bytes !== null) - Number(bv.bytes !== null) || (a < b ? -1 : a > b ? 1 : 0));
+    for (const [locator, next] of publication) {
+        const phase = under(locator, candidate.storeLocator) && locator.endsWith('.md') ? 'document' : /^\.ax\/entities\/records\/[^/]+\.json$/.test(locator) ? 'mapping' : 'source';
+        const entityId = documentIds.get(locator);
+        add(phase, locator, next, entityId ? { entityId } : {});
+    }
+    for (const step of transitions.approve) {
+        const locator = candidate.storeLocator + '/' + step.documentLocator;
+        add('approve', locator, state(encoded(step.after), current.get(locator)?.mode), { entityId: step.entityId, specId: step.displayId }, step.before);
+    }
+    for (const entry of transitions.completed) {
+        const locator = candidate.storeLocator + '/' + entry.documentLocator;
+        if (current.get(locator)?.bytes !== encoded(entry.text))
+            refuse('Final document differs from transition output: ' + locator);
+    }
+    return steps;
+}
+/** A reviewable candidate, not an authorized executable journal or a source of replacement authority. */
+async function planEntityIntegrationCandidate(root, revisions, storeLocator) {
+    return inspectEntityIntegration(root, revisions, storeLocator, candidate => candidate);
+}
+async function inspectEntityIntegration(root, revisions, storeLocator, inspect) {
+    root = fs.realpathSync(root);
+    const inputs = (0, entity_git_snapshot_1.readEntityGitInputs)(root, revisions, storeLocator);
+    return (0, entity_transaction_1.withEntityStoreLockAsync)(root, storeLocator, () => (0, entity_renumber_transaction_1.withEntitySourceInspection)(root, async () => {
+        const owner = (0, entity_transaction_1.entityLockOwner)(root, storeLocator);
+        (0, entity_store_1.assertNoPendingEntityPublication)(path.join(root, storeLocator));
+        const candidate = await compileEntityIntegrationCandidate(root, inputs, storeLocator);
+        const result = await inspect(candidate, root);
+        if (!owner || !(0, node_util_1.isDeepStrictEqual)((0, entity_transaction_1.entityLockOwner)(root, storeLocator), owner))
+            throw new entity_transaction_1.EntityStoreError('unknown-owner', 'Destination inspection ownership changed.');
+        (0, entity_store_1.assertNoPendingEntityPublication)(path.join(root, storeLocator));
+        return result;
+    }));
+}
+async function compileEntityIntegrationCandidate(root, inputs, storeLocator, recovery, completed = false) {
+    if (completed && !recovery)
+        throw new entity_transaction_1.EntityStoreError('invalid-plan', 'Completed program regeneration requires its original plan.');
+    const sides = ['base', 'left', 'right'];
+    const commits = { base: inputs.base.commit, left: inputs.left.commit, right: inputs.right.commit };
+    const destination = (0, entity_git_snapshot_1.readEntityGitSnapshot)(root, recovery?.destination.head ?? 'HEAD', storeLocator);
+    const index = (0, entity_git_snapshot_1.readEntityGitIndex)(root);
+    const documents = (0, entity_integration_1.planEntityGitDocuments)(inputs);
+    const registrations = destination.files.filter(file => /^\.ax\/entities\/stores\/[^/]+\.json$/.test(file.path));
+    const controlBlobs = (0, entity_git_snapshot_1.readEntityGitBlobs)(root, [...registrations.map(file => file.oid), ...destination.files.filter(file => file.path === '.gitignore').map(file => file.oid)]);
+    const canonicalRoots = ['.ax/entities', ...registrations.map(file => JSON.parse(controlBlobs.get(file.oid).toString('utf8')).storeLocator)];
+    const ignoreEntry = destination.files.find(file => file.path === '.gitignore');
+    const ignoreText = ignoreEntry ? controlBlobs.get(ignoreEntry.oid).toString('utf8') : '';
+    // Recovery verifies present membership against the observed prefix separately. The historical
+    // inventory digest is retained as an envelope field, never used to derive or authorize writes.
+    const membership = recovery ? { version: recovery.destination.membershipVersion, conflicts: [] }
+        : destinationMembership(root, destination.files, canonicalRoots, ignoreText);
+    const result = { schema: 'holmes-entity-integration-candidate/1', stage: 'candidate', ok: false,
+        workspaceId: inputs.base.workspaceId, storeId: inputs.base.storeId, storeLocator, commits, destinationHead: destination.commit,
+        indexVersion: completed ? recovery.destination.indexVersion : index.version, membershipVersion: membership.version, changes: [], checks: [], conflicts: [...documents.conflicts, ...membership.conflicts], pending: [], approval: documents.approval, policyInputs: [] };
+    const conflictEvidence = [];
+    result.conflictEvidence = conflictEvidence;
+    for (const decision of (0, entity_integration_1.classifyEntityGitChanges)(inputs, 'meaning').decisions)
+        if (decision.outcome === 'conflict') {
+            const objects = {};
+            for (const side of sides) {
+                const entity = decision[side], file = entity ? storeLocator + '/' + entity.documentLocator : undefined;
+                const entry = file ? inputs[side].files.find(entry => entry.path === file) : undefined;
+                objects[side] = entry ? { commit: commits[side], oid: entry.oid, mode: entry.mode, path: entry.path } : null;
+            }
+            conflictEvidence.push({ kind: 'entity', entityId: decision.entityId, reason: decision.reason, objects });
+        }
+    // @implements A-SPEC-636 — numbering, document, reference and mirror conflicts carry the entity's
+    // document and record objects per side beside the planner's per-side facts.
+    const entityObject = (side, entityId, which) => {
+        const entity = inputs[side].entities.find(candidate => candidate.entityId === entityId);
+        const file = entity ? (which === 'document' ? storeLocator + '/' + entity.documentLocator : entity.recordLocator) : undefined;
+        const entry = file ? inputs[side].files.find(candidate => candidate.path === file) : undefined;
+        return entry ? { commit: commits[side], oid: entry.oid, mode: entry.mode, path: entry.path } : null;
+    };
+    for (const record of documents.evidence ?? []) {
+        const primary = record.kind === 'mirror' ? record.entityIds[0] : record.entityId;
+        const objects = {}, records = {};
+        for (const side of sides) {
+            objects[side] = entityObject(side, primary, 'document');
+            records[side] = entityObject(side, primary, 'record');
+        }
+        conflictEvidence.push({ ...record, objects, records });
+    }
+    if (!Object.values(commits).includes(destination.commit))
+        result.conflicts.push('Destination HEAD is not one of the inspected Git inputs.');
+    if (destination.workspaceId !== result.workspaceId || destination.storeId !== result.storeId)
+        result.conflicts.push('Destination workspace/store identity differs from the integration inputs.');
+    const indexed = new Map(index.entries.filter(entry => entry.stage === 0).map(entry => [entry.path, entry]));
+    const headFiles = new Map(destination.files.map(entry => [entry.path, entry]));
+    for (const entry of completed ? [] : index.entries) {
+        if (entry.stage !== 0)
+            result.conflicts.push(entry.path + ': unmerged index stage ' + entry.stage);
+        else {
+            const head = headFiles.get(entry.path);
+            if (!head || head.oid !== entry.oid || head.mode !== entry.mode)
+                result.conflicts.push(entry.path + ': index differs from destination HEAD');
+        }
+    }
+    if (!completed)
+        for (const file of destination.files)
+            if (!indexed.has(file.path))
+                result.conflicts.push(file.path + ': missing stage-zero index entry');
+    if (result.conflicts.length)
+        return result;
+    const sources = await (0, entity_integration_1.planEntityGitMergedSources)(root, commits, storeLocator);
+    result.conflicts.push(...sources.conflicts);
+    for (const source of sources.files)
+        if (!source.merge.ok)
+            conflictEvidence.push({ kind: 'source', file: source.file, reason: source.merge.reason, objects: source.objects });
+    for (const record of sources.evidence)
+        conflictEvidence.push(record);
+    result.excluded = sources.excluded.filter(entry => entry.reason.startsWith('unchanged-'));
+    if (!sources.ok)
+        return result;
+    const desired = new Map(), primary = new Set(), assigned = new Set();
+    const regularMode = (mode) => {
+        if (mode !== '100644' && mode !== '100755')
+            throw new Error('Unsupported canonical publication mode.');
+        return mode;
+    };
+    const put = (locator, state) => {
+        if (assigned.has(locator))
+            result.conflicts.push(locator + ': multiple publication candidates');
+        assigned.add(locator);
+        desired.set(locator, state);
+    };
+    for (const snapshot of [...sides.map(side => inputs[side]), destination])
+        for (const entity of snapshot.entities) {
+            for (const locator of [storeLocator + '/' + entity.documentLocator, entity.recordLocator]) {
+                primary.add(locator);
+                desired.set(locator, null);
+            }
+        }
+    const renumbered = [];
+    for (const document of documents.documents) {
+        const snapshot = inputs[document.source], original = snapshot.entities.find(entity => entity.entityId === document.entityId);
+        const mapping = JSON.parse(original.record);
+        if (typeof mapping.displayId === 'string' && mapping.displayId !== document.newId)
+            renumbered.push({ entityId: document.entityId, oldDisplayId: mapping.displayId, newDisplayId: document.newId }); // A-SPEC-645
+        const record = mapping.displayId === document.newId && mapping.documentLocator === document.newDocumentLocator ? original.record
+            : JSON.stringify({ ...mapping, displayId: document.newId, documentLocator: document.newDocumentLocator });
+        put(storeLocator + '/' + document.newDocumentLocator, { bytes: Buffer.from(document.after), mode: regularMode(snapshot.files.find(file => file.path === storeLocator + '/' + original.documentLocator).mode) });
+        put(original.recordLocator, { bytes: Buffer.from(record), mode: regularMode(snapshot.files.find(file => file.path === original.recordLocator).mode) });
+    }
+    for (const source of sources.files)
+        put(source.file, source.merge.result ? { bytes: source.merge.result.bytes, mode: regularMode(source.merge.result.mode) } : null);
+    if (renumbered.length)
+        result.renumbered = renumbered.sort((a, b) => a.entityId < b.entityId ? -1 : a.entityId > b.entityId ? 1 : 0); // A-SPEC-645
+    const inventories = sides.map(side => new Map(inputs[side].files.map(file => [file.path, file])));
+    for (const excluded of sources.excluded) {
+        if (primary.has(excluded.file) || excluded.file === '.ax/workspace.json')
+            continue;
+        const states = inventories.map(inventory => { const file = inventory.get(excluded.file); return file ? file.mode + ':' + file.oid : null; });
+        if (states.some(state => state !== states[0]))
+            result.pending.push(excluded);
+    }
+    // @implements A-SPEC-637 — an excluded non-regular entry is never a publication path.
+    for (const excluded of result.excluded)
+        for (const locator of desired.keys())
+            if (under(locator, excluded.file))
+                result.conflicts.push(locator + ': path passes through excluded entry ' + excluded.file);
+    const inputObjects = (locator) => {
+        const objects = {};
+        for (const side of sides) {
+            const entry = inputs[side].files.find(file => file.path === locator);
+            objects[side] = entry ? { commit: commits[side], oid: entry.oid, mode: entry.mode, path: entry.path } : null;
+        }
+        return objects;
+    };
+    const current = new Map(destination.files.map(file => [file.path, file]));
+    const checked = new Set([...desired.keys(), '.ax/workspace.json', '.gitignore', ...destination.files.filter(file => canonicalRoots.some(dir => under(file.path, dir))).map(file => file.path)]);
+    const beforeBlobs = (0, entity_git_snapshot_1.readEntityGitBlobs)(root, [...checked].flatMap(locator => current.has(locator) ? [current.get(locator).oid] : []));
+    for (const locator of [...checked].sort()) {
+        const entry = current.get(locator), beforeBytes = entry ? beforeBlobs.get(entry.oid) : null;
+        const before = beforeBytes?.toString('base64') ?? null, beforeMode = entry ? regularMode(entry.mode) : null;
+        result.checks.push({ locator, version: beforeBytes ? (0, entity_transaction_1.entityContentVersion)(beforeBytes) : null, mode: beforeMode });
+        if (!recovery) {
+            try {
+                (0, entity_transaction_1.assertEntityByteInput)(root, { locator, before, after: before, beforeMode, afterMode: beforeMode });
+            }
+            catch (error) {
+                const collision = classifyDestinationCollision(root, locator, before, error);
+                if (collision) {
+                    result.conflicts.push(collision.message);
+                    conflictEvidence.push({ kind: 'destination', file: locator, reason: collision.reason, existing: collision.existing, objects: inputObjects(locator) });
+                }
+                else
+                    result.conflicts.push(locator + ': ' + (error instanceof Error ? error.message : 'Unsafe destination state.'));
+            }
+        }
+        if (!desired.has(locator))
+            continue;
+        const state = desired.get(locator), after = state?.bytes.toString('base64') ?? null, afterMode = state?.mode ?? null;
+        if (before !== after || beforeMode !== afterMode)
+            result.changes.push({ locator, before, after, beforeMode, afterMode });
+    }
+    const surviving = new Set([...current.keys()].filter(locator => !desired.has(locator) || desired.get(locator) !== null));
+    for (const [locator, state] of desired)
+        if (state)
+            surviving.add(locator);
+    for (const locator of surviving) {
+        const parts = locator.split('/');
+        for (let length = 1; length < parts.length; length++) {
+            const ancestor = parts.slice(0, length).join('/');
+            if (surviving.has(ancestor))
+                result.conflicts.push(ancestor + ': final file-directory conflict with ' + locator);
+        }
+    }
+    if (!completed && (0, entity_git_snapshot_1.readEntityGitSnapshot)(root, 'HEAD', storeLocator).commit !== destination.commit)
+        result.conflicts.push('Destination HEAD changed during candidate planning.');
+    if ((0, entity_git_snapshot_1.readEntityGitIndex)(root).version !== index.version)
+        result.conflicts.push('Destination index changed during candidate planning.');
+    const finalMembership = recovery ? membership : destinationMembership(root, destination.files, canonicalRoots, ignoreText);
+    result.conflicts.push(...finalMembership.conflicts);
+    if (finalMembership.version !== membership.version)
+        result.conflicts.push('Destination membership changed during candidate planning.');
+    result.ok = result.conflicts.length === 0 && result.pending.length === 0;
+    if (result.ok) {
+        const policyInputs = new Map();
+        try {
+            result.transitions = prepareEntityIntegrationTransitions(destination.entities.map(entry => ({ entityId: entry.entityId, documentLocator: entry.documentLocator, text: entry.document })), documents.documents.map(entry => ({ entityId: entry.entityId, documentLocator: entry.newDocumentLocator, text: entry.after })), file => {
+                if (!file || /[\\:\x00]/.test(file) || file.split('/').some(part => !part || part === '.' || part === '..'))
+                    throw new entity_transaction_1.EntityStoreError('unsafe-path', 'Policy input must be a workspace-relative file.');
+                let actual;
+                const original = recovery ? current.get(file) : undefined;
+                if (original) {
+                    if (original.mode !== '100644' && original.mode !== '100755')
+                        throw new entity_transaction_1.EntityStoreError('unsafe-path', 'Recovery policy input must be a regular Git blob.');
+                    actual = (0, entity_git_snapshot_1.readEntityGitBlobs)(root, [original.oid]).get(original.oid);
+                }
+                else if (recovery && checked.has(file)) {
+                    // This path was absent in the original tree but may already have been published.
+                    actual = undefined;
+                }
+                else {
+                    actual = (0, entity_transaction_1.readEntityBytes)(path.join((0, entity_transaction_1.entityDirectory)(root, path.posix.dirname(file)), path.posix.basename(file)));
+                    if (recovery) {
+                        // Non-Git policy files are not reconstructed from caller bytes. Their original
+                        // observed digest must still match the local file before current policy is evaluated.
+                        const bound = recovery.policyInputs.find(input => input.locator === file);
+                        if (!bound || bound.version !== (actual ? (0, entity_transaction_1.entityContentVersion)(actual) : null))
+                            throw new entity_transaction_1.EntityStoreError('plan-changed', 'Recovery local policy input changed: ' + file);
+                    }
+                }
+                const effective = desired.has(file) ? desired.get(file)?.bytes : actual;
+                policyInputs.set(file, { locator: file, version: actual ? (0, entity_transaction_1.entityContentVersion)(actual) : null, effectiveVersion: effective ? (0, entity_transaction_1.entityContentVersion)(effective) : null });
+                return effective?.toString('utf8') ?? null;
+            });
+        }
+        catch (error) {
+            result.conflicts.push('Integration transition policy: ' + (error instanceof Error ? error.message : 'Transition preparation failed.'));
+            result.ok = false;
+        }
+        result.policyInputs = [...policyInputs.values()].sort((a, b) => a.locator < b.locator ? -1 : a.locator > b.locator ? 1 : 0);
+        if (result.ok) {
+            try {
+                result.steps = compileEntityIntegrationSteps(result);
+            }
+            catch (error) {
+                result.conflicts.push(error instanceof Error ? error.message : 'Step compilation failed.');
+                result.ok = false;
+            }
+        }
+    }
+    return result;
+}
+function under(file, dir) { return file === dir || file.startsWith(dir + '/'); }
+/** Read local membership without following links; canonical roots take precedence over source exclusions. */
+/**
+ * @implements A-SPEC-637 — classify a failed destination pre-check as a shape collision the plan itself
+ * would run into: a file where a directory is needed, a directory where a file is needed, or a path
+ * that differs from a tracked one only by case on a case-insensitive filesystem.
+ */
+function classifyDestinationCollision(root, locator, before, error) {
+    if (!(error instanceof entity_transaction_1.EntityStoreError))
+        return undefined;
+    const stat = (relative) => { try {
+        return fs.lstatSync(path.join(root, relative));
+    }
+    catch {
+        return undefined;
+    } };
+    if (error.code === 'unsafe-path' && /directories/.test(error.message)) {
+        const parts = locator.split('/');
+        for (let depth = 1; depth < parts.length; depth++) {
+            const ancestor = parts.slice(0, depth).join('/'), s = stat(ancestor);
+            if (s && !s.isDirectory())
+                return { reason: 'file-directory-collision', existing: ancestor, message: locator + ': destination has file ' + ancestor + ' where the plan needs a directory' };
+        }
+        return undefined;
+    }
+    if (error.code === 'unsafe-path' && /regular files/.test(error.message) && stat(locator)?.isDirectory()) {
+        return { reason: 'directory-file-collision', existing: locator, message: locator + ': destination has directory ' + locator + ' where the plan needs a file' };
+    }
+    if (error.code === 'external-change' && before === null && stat(locator)?.isFile()) {
+        let real;
+        try {
+            real = path.relative(fs.realpathSync.native(root), fs.realpathSync.native(path.join(root, locator))).split(path.sep).join('/');
+        }
+        catch {
+            return undefined;
+        }
+        if (real !== locator && real.toLowerCase() === locator.toLowerCase())
+            return { reason: 'case-collision', existing: real, message: locator + ': destination path ' + real + ' differs only by case on a case-insensitive filesystem' };
+    }
+    return undefined;
+}
+function destinationMembership(root, files, canonicalRoots, ignoreText) {
+    const tracked = new Set(files.map(file => file.path)), inventory = [], conflicts = [];
+    // @implements A-SPEC-637 — tracked symlinks are members; tracked gitlink directories are boundaries.
+    const symlinks = new Set(files.filter(file => file.mode === '120000').map(file => file.path)), gitlinks = new Set(files.filter(file => file.mode === '160000').map(file => file.path));
+    const ignore = (0, ignore_1.parseIgnore)(ignoreText);
+    for (const pattern of ignore.unsupportedPatterns())
+        conflicts.push('.gitignore: unsupported destination ignore pattern: ' + pattern);
+    const walk = (relative) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(path.join(root, relative), { withFileTypes: true });
+        }
+        catch {
+            conflicts.push((relative || '.') + ': unreadable destination directory');
+            return;
+        }
+        for (const entry of entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+            const file = relative ? relative + '/' + entry.name : entry.name;
+            // Git itself resolves this administrative entry; linked worktrees use a file here.
+            if (file === '.git')
+                continue;
+            // @implements A-SPEC-640 — the publication primitive's own transients are never destination members.
+            if ((0, entity_transaction_1.isEntityTransientName)(entry.name))
+                continue;
+            const canonical = canonicalRoots.some(dir => under(file, dir) || under(dir, file));
+            if (!canonical && (under(file, '.ax/approvals') || (0, change_source_1.isDerivedState)(file + (entry.isDirectory() ? '/' : '')) ||
+                (entry.isDirectory() && cpg_scanner_1.SKIP.has(entry.name)) || ignore.isIgnored(file)))
+                continue;
+            if (entry.isSymbolicLink()) {
+                if (symlinks.has(file)) {
+                    inventory.push(file);
+                    continue;
+                }
+                conflicts.push(file + ': symlinked destination membership is unsupported');
+                continue;
+            }
+            if (entry.isDirectory()) {
+                if (gitlinks.has(file))
+                    continue;
+                if (!canonical && fs.existsSync(path.join(root, file, 'pyvenv.cfg')))
+                    continue;
+                walk(file);
+                continue;
+            }
+            if (!entry.isFile()) {
+                conflicts.push(file + ': unsupported destination file type');
+                continue;
+            }
+            inventory.push(file);
+            if (!tracked.has(file))
+                conflicts.push(file + ': untracked destination file');
+        }
+    };
+    walk('');
+    return { version: (0, entity_transaction_1.entityContentVersion)(JSON.stringify(inventory)), conflicts };
+}