@holmes-lab/holmes-kit 0.19.6 → 0.20.1

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

@@ -0,0 +1,760 @@
+"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.unchangedNonRegular = unchangedNonRegular;
+exports.planEntityGitMergedSources = planEntityGitMergedSources;
+exports.mergeToolEnv = mergeToolEnv;
+exports.mergeEntityGitFile = mergeEntityGitFile;
+exports.planEntityGitSources = planEntityGitSources;
+exports.planEntityGitDocuments = planEntityGitDocuments;
+exports.planEntityGitNumbering = planEntityGitNumbering;
+exports.classifyEntityGitChanges = classifyEntityGitChanges;
+// @implements A-SPEC-629.1, A-SPEC-629
+// @implements A-SPEC-636
+// @implements A-SPEC-637
+const entity_git_snapshot_1 = require("./entity-git-snapshot");
+const entity_transaction_1 = require("./entity-transaction");
+const spec_parser_1 = require("./spec-parser");
+const spec_types_1 = require("./spec-types");
+const entity_renumber_1 = require("./entity-renumber");
+const renumber_1 = require("./renumber");
+const ignore_1 = require("../project/ignore");
+const change_source_1 = require("../project/change-source");
+const cpg_scanner_1 = require("../cpg/cpg-scanner");
+const node_util_1 = require("node:util");
+const path = __importStar(require("node:path"));
+const spec_digest_1 = require("./spec-digest");
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const REGULAR = new Set(['100644', '100755']);
+/**
+ * @implements A-SPEC-637 — non-regular entries (symlinks, gitlinks) identical in base, left and right:
+ * excluded from integration and never read as blobs. Anything else non-regular is a refusal.
+ */
+function unchangedNonRegular(inputs) {
+    const untouched = new Map();
+    const left = new Map(inputs.left.files.map(file => [file.path, file])), right = new Map(inputs.right.files.map(file => [file.path, file]));
+    for (const file of inputs.base.files) {
+        if (REGULAR.has(file.mode))
+            continue;
+        const l = left.get(file.path), r = right.get(file.path);
+        if (l && r && l.mode === file.mode && r.mode === file.mode && l.oid === file.oid && r.oid === file.oid)
+            untouched.set(file.path, file.mode);
+    }
+    return untouched;
+}
+/** Ordinary tracked files only; excluded canonical paths remain obligations of the integration executor. */
+async function planEntityGitMergedSources(root, revisions, storeLocator) {
+    const inputs = (0, entity_git_snapshot_1.readEntityGitInputs)(root, revisions, storeLocator), sides = ['base', 'left', 'right'];
+    const commits = { base: inputs.base.commit, left: inputs.left.commit, right: inputs.right.commit };
+    const normalization = await planEntityGitSourceInputs(root, inputs, true);
+    const result = { ok: normalization.ok, conflicts: [...normalization.conflicts], evidence: [], commits, normalization, validation: { diagnostics: [], proseCandidates: [], anchors: [] }, files: [], excluded: [] };
+    const untouched = unchangedNonRegular(inputs);
+    if (!normalization.ok) {
+        // @implements A-SPEC-637 — a changed symlink or gitlink fails normalization on its side; give the
+        // refusal the same per-side objects every other source conflict carries.
+        const flagged = new Set();
+        for (const side of sides)
+            for (const diagnostic of normalization.branches[side].diagnostics) {
+                if (!/^(Symlinked source|Gitlink source)/.test(diagnostic.reason) || flagged.has(diagnostic.file))
+                    continue;
+                flagged.add(diagnostic.file);
+                const objects = {};
+                for (const which of sides) {
+                    const entry = inputs[which].files.find(file => file.path === diagnostic.file);
+                    objects[which] = entry ? { commit: commits[which], oid: entry.oid, mode: entry.mode, path: entry.path } : null;
+                }
+                result.evidence.push({ kind: 'source', file: diagnostic.file, reason: 'unsupported-mode', objects });
+            }
+        return result;
+    }
+    const stores = new Set([storeLocator]);
+    const owners = new Map();
+    const own = (id, entityId) => { const entities = owners.get(id) ?? new Set(); entities.add(entityId); owners.set(id, entities); };
+    for (const assignment of planEntityGitNumbering(inputs).assignments)
+        own(assignment.newDisplayId, assignment.entityId);
+    for (const side of sides) {
+        const registrations = inputs[side].files.filter(file => /^\.ax\/entities\/(?:stores|records)\/[^/]+\.json$/.test(file.path));
+        const blobs = (0, entity_git_snapshot_1.readEntityGitBlobs)(root, registrations.map(file => file.oid));
+        for (const registration of registrations) {
+            const metadata = JSON.parse(blobs.get(registration.oid).toString('utf8'));
+            if (registration.path.startsWith('.ax/entities/stores/'))
+                stores.add(metadata.storeLocator);
+            else if (metadata.storeId !== inputs[side].storeId)
+                own(metadata.displayId, metadata.entityId);
+        }
+    }
+    const paths = [...new Set(sides.flatMap(side => inputs[side].files.map(file => file.path)))].sort();
+    const ordinary = [];
+    for (const file of paths) {
+        const reason = [...stores].some(store => file === store || file.startsWith(store + '/')) ? 'canonical-entity'
+            : (0, change_source_1.isDerivedState)(file) ? 'derived-state' : file === '.ax' || file.startsWith('.ax/') ? 'workspace-control'
+                : untouched.has(file) ? (untouched.get(file) === '120000' ? 'unchanged-symlink' : 'unchanged-gitlink') : undefined;
+        if (reason)
+            result.excluded.push({ file, reason });
+        else
+            ordinary.push(file);
+    }
+    const inventory = Object.fromEntries(sides.map(side => [side, new Map(inputs[side].files.map(file => [file.path, file]))]));
+    const normalized = Object.fromEntries(sides.map(side => [side, new Map(normalization.branches[side].files.map(file => [file.file, file.after]))]));
+    const blobs = (0, entity_git_snapshot_1.readEntityGitBlobs)(root, ordinary.flatMap(file => sides.flatMap(side => {
+        const entry = inventory[side].get(file);
+        return entry && entry.mode !== '160000' ? [entry.oid] : [];
+    })));
+    const bytesAt = (side, file) => {
+        if (normalized[side].has(file))
+            return Buffer.from(normalized[side].get(file));
+        const entry = inventory[side].get(file);
+        return entry.mode === '160000' ? Buffer.alloc(0) : blobs.get(entry.oid);
+    };
+    const renames = { left: new Map(), right: new Map() };
+    for (const side of ['left', 'right']) {
+        const groups = new Map();
+        for (const file of ordinary) {
+            const removed = inventory.base.has(file) && !inventory[side].has(file), added = !inventory.base.has(file) && inventory[side].has(file);
+            if (!removed && !added)
+                continue;
+            const versionSide = removed ? 'base' : side, entry = inventory[versionSide].get(file);
+            if (!['100644', '100755'].includes(entry.mode))
+                continue;
+            const key = (0, node_crypto_1.createHash)('sha256').update(bytesAt(versionSide, file)).digest('hex');
+            const group = groups.get(key) ?? { removed: [], added: [] };
+            group[removed ? 'removed' : 'added'].push(file);
+            groups.set(key, group);
+        }
+        for (const group of groups.values())
+            if (group.removed.length === 1 && group.added.length === 1 && bytesAt('base', group.removed[0]).equals(bytesAt(side, group.added[0]))) {
+                renames[side].set(group.removed[0], group.added[0]);
+            }
+    }
+    // An independently occupied destination is not evidence of a rename from this base path.
+    const rejected = [];
+    for (const side of ['left', 'right'])
+        for (const [file, target] of renames[side]) {
+            const other = side === 'left' ? 'right' : 'left';
+            if (inventory[other].has(target) && renames[other].get(file) !== target) {
+                result.conflicts.push(file + ': rename-destination conflict at ' + target);
+                rejected.push({ side, file });
+                const at = (which, path) => { const entry = inventory[which].get(path); return entry ? { commit: commits[which], oid: entry.oid, mode: entry.mode, path } : null; };
+                result.evidence.push({ kind: 'source', file, reason: 'rename-destination', target, objects: { base: at('base', file), left: at('left', side === 'left' ? target : file), right: at('right', side === 'right' ? target : file) } });
+            }
+        }
+    for (const { side, file } of rejected)
+        renames[side].delete(file);
+    const destinations = new Set([...renames.left.values(), ...renames.right.values()]);
+    for (const file of ordinary) {
+        if (!inventory.base.has(file) && destinations.has(file))
+            continue;
+        const versions = {};
+        const objects = {};
+        for (const side of sides) {
+            const origin = side === 'base' ? file : renames[side].get(file) ?? file, entry = inventory[side].get(origin);
+            objects[side] = entry ? { commit: commits[side], oid: entry.oid, mode: entry.mode, path: origin } : null;
+            versions[side] = entry ? { mode: entry.mode, bytes: bytesAt(side, origin) } : null;
+        }
+        let merge = mergeEntityGitFile(versions.base, versions.left, versions.right);
+        const leftPath = renames.left.get(file), rightPath = renames.right.get(file), moved = leftPath || rightPath;
+        if (moved && (!versions.left || !versions.right))
+            merge = { ...merge, ok: false, result: null, reason: 'rename-delete' };
+        if (leftPath && rightPath && leftPath !== rightPath)
+            merge = { ...merge, ok: false, result: null, reason: 'rename-rename' };
+        const destination = leftPath && rightPath && leftPath !== rightPath ? file : moved || file;
+        result.files.push({ file: destination, merge, objects });
+        if (merge.ok && destination !== file)
+            result.files.push({ file, merge: { ...merge, result: null, reason: 'renamed' }, objects });
+        if (!merge.ok)
+            result.conflicts.push(file + ': ' + merge.reason);
+    }
+    result.files.sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
+    const surviving = new Set(result.files.filter(file => file.merge.ok && file.merge.result).map(file => file.file));
+    for (const file of surviving) {
+        const segments = file.split('/');
+        for (let length = 1; length < segments.length; length++) {
+            const ancestor = segments.slice(0, length).join('/');
+            if (surviving.has(ancestor)) {
+                result.conflicts.push(ancestor + ': file-directory conflict with ' + file);
+                const objects = {};
+                for (const side of sides) {
+                    const entry = inventory[side].get(ancestor);
+                    objects[side] = entry ? { commit: commits[side], oid: entry.oid, mode: entry.mode, path: ancestor } : null;
+                }
+                result.evidence.push({ kind: 'source', file: ancestor, reason: 'file-directory', other: file, objects });
+            }
+        }
+    }
+    const ignoreBytes = result.files.find(file => file.file === '.gitignore')?.merge.result?.bytes ?? Buffer.alloc(0);
+    const ignoreText = ignoreBytes.toString('utf8');
+    if (!Buffer.from(ignoreText).equals(ignoreBytes) || ignoreText.includes('\0'))
+        result.validation.diagnostics.push({ file: '.gitignore', reason: 'Merged ignore policy is not UTF-8 text.' });
+    const ignore = (0, ignore_1.parseIgnore)(ignoreText);
+    for (const pattern of ignore.unsupportedPatterns())
+        result.validation.diagnostics.push({ file: '.gitignore', reason: 'Unsupported merged ignore pattern: ' + pattern });
+    const venvs = [...surviving].filter(file => file.endsWith('/pyvenv.cfg')).map(file => file.slice(0, -'/pyvenv.cfg'.length));
+    for (const file of result.files) {
+        if (!file.merge.ok || !file.merge.result || file.file === '.gitignore' || ignore.isIgnored(file.file) || file.file.split('/').slice(0, -1).some(part => cpg_scanner_1.SKIP.has(part)) || venvs.some(venv => file.file.startsWith(venv + '/')))
+            continue;
+        const checked = await (0, renumber_1.planSourceTextRenumber)(file.file, file.merge.result.bytes, [], { inspectAllAnchors: true });
+        result.validation.diagnostics.push(...checked.diagnostics);
+        result.validation.proseCandidates.push(...checked.proseCandidates);
+        for (const candidate of checked.files)
+            for (const displayId of candidate.anchorIds) {
+                const targets = owners.get(displayId);
+                const deleted = sides.some(side => normalization.branches[side].files.some(prior => prior.file === (file.objects[side]?.path ?? file.file) && prior.anchors.some(anchor => anchor.displayId === displayId && anchor.targetDeleted)));
+                if (deleted)
+                    result.validation.diagnostics.push({ file: file.file, reason: 'Deleted merged anchor target: ' + displayId });
+                else if (targets?.size !== 1)
+                    result.validation.diagnostics.push({ file: file.file, reason: (targets?.size ? 'Ambiguous' : 'Unknown') + ' merged anchor owner: ' + displayId });
+                else
+                    result.validation.anchors.push({ file: file.file, displayId, entityId: [...targets][0] });
+            }
+    }
+    result.conflicts.push(...result.validation.diagnostics.map(diagnostic => diagnostic.file + ': ' + diagnostic.reason));
+    for (const diagnostic of result.validation.diagnostics) {
+        const merged = result.files.find(file => file.file === diagnostic.file);
+        result.evidence.push({ kind: 'source', file: diagnostic.file, reason: diagnostic.reason, objects: merged ? { ...merged.objects } : { base: null, left: null, right: null } });
+    }
+    result.ok = result.conflicts.length === 0;
+    return result;
+}
+/** Merge already-normalized bytes. Scratch files are not a materialized Holmes workspace. */
+/**
+ * @implements A-SPEC-652.6 — the environment `git merge-file` runs in: the caller's GIT_* stripped,
+ * the system and global configs blocked, the ceiling at the scratch parent. The "empty global
+ * config" is `os.devNull` on POSIX; on Windows `os.devNull` is `\\.\nul`, which git cannot open as
+ * a config file (`fatal: unable to access '\\.\nul': Invalid argument`, status 128 — measured
+ * 2026-09-15), so every content merge there was reported as a merge-tool-failure conflict. `NUL`
+ * is the spelling git accepts on that platform.
+ */
+function mergeToolEnv(base, scratch, platform = process.platform) {
+    const env = { ...base };
+    for (const key of Object.keys(env))
+        if (key.startsWith('GIT_'))
+            delete env[key];
+    env.GIT_CONFIG_NOSYSTEM = '1';
+    env.GIT_CONFIG_GLOBAL = platform === 'win32' ? 'NUL' : os.devNull;
+    env.GIT_CEILING_DIRECTORIES = path.dirname(scratch);
+    return env;
+}
+function mergeEntityGitFile(base, left, right) {
+    const copy = (version) => version && ({ mode: version.mode, bytes: Buffer.from(version.bytes) });
+    const inputs = { base: copy(base), left: copy(left), right: copy(right) };
+    const conflict = (reason) => ({ ok: false, result: null, reason, inputs });
+    const success = (result) => ({ ok: true, result: copy(result), reason: result ? 'merged' : 'deleted', inputs });
+    const versions = [base, left, right].filter((version) => version !== null);
+    if (versions.some(version => !['100644', '100755'].includes(version.mode)))
+        return conflict('unsupported-mode');
+    const limit = 64 * 1024 * 1024;
+    if (versions.reduce((total, version) => total + version.bytes.length, 0) > limit)
+        return conflict('merge-input-limit');
+    const equal = (a, b) => a === null || b === null ? a === b : a.mode === b.mode && a.bytes.equals(b.bytes);
+    if (equal(left, right))
+        return success(left);
+    if (equal(base, left))
+        return success(right);
+    if (equal(base, right))
+        return success(left);
+    if (!left || !right)
+        return conflict('delete-modify');
+    if (!base)
+        return conflict('add-add');
+    const mode = left.mode === right.mode ? left.mode : left.mode === base.mode ? right.mode : right.mode === base.mode ? left.mode : undefined;
+    if (!mode)
+        return conflict('mode-conflict');
+    if (left.bytes.equals(right.bytes))
+        return success({ mode, bytes: left.bytes });
+    if (left.bytes.equals(base.bytes))
+        return success({ mode, bytes: right.bytes });
+    if (right.bytes.equals(base.bytes))
+        return success({ mode, bytes: left.bytes });
+    if (versions.some(version => version.bytes.includes(0) || !Buffer.from(version.bytes.toString('utf8')).equals(version.bytes)))
+        return conflict('binary-conflict');
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'holmes-source-merge-'));
+    try {
+        for (const [name, version] of Object.entries({ base, left, right }))
+            fs.writeFileSync(path.join(scratch, name), version.bytes, { mode: 0o600 });
+        const env = mergeToolEnv(process.env, scratch);
+        const merged = (0, node_child_process_1.spawnSync)('git', ['merge-file', '--stdout', '--diff3', '-L', 'left', '-L', 'base', '-L', 'right', '--', 'left', 'base', 'right'], { cwd: scratch, env, maxBuffer: limit });
+        if (merged.error || merged.status === null || merged.status > 127)
+            return conflict('merge-tool-failure');
+        if (merged.status !== 0)
+            return conflict('text-conflict');
+        return success({ mode, bytes: merged.stdout });
+    }
+    finally {
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+}
+/** Branch proposals retain provenance; ordinary three-way source merging and publication follow separately. */
+async function planEntityGitSources(root, revisions, storeLocator) {
+    return planEntityGitSourceInputs(root, (0, entity_git_snapshot_1.readEntityGitInputs)(root, revisions, storeLocator), false);
+}
+/** Only the final merger may defer deleted-target checks until surviving source is known. */
+async function planEntityGitSourceInputs(root, inputs, deferDeletedTargets) {
+    const numbering = planEntityGitNumbering(inputs);
+    const untouched = unchangedNonRegular(inputs);
+    const empty = () => ({ files: [], diagnostics: [], proseCandidates: [] });
+    const branches = { base: empty(), left: empty(), right: empty() };
+    if (!numbering.ok)
+        return { ok: false, conflicts: numbering.conflicts, evidence: numbering.evidence, branches };
+    const finalIds = new Map(numbering.assignments.map(assignment => [assignment.entityId, assignment.newDisplayId]));
+    for (const side of ['base', 'left', 'right']) {
+        const snapshot = inputs[side], branch = branches[side];
+        // These records were validated by the fresh snapshot loader, including all registered stores.
+        const metadata = snapshot.files.filter(file => /^\.ax\/entities\/(?:stores|records)\/[^/]+\.json$/.test(file.path));
+        const metadataBlobs = (0, entity_git_snapshot_1.readEntityGitBlobs)(root, metadata.map(file => file.oid));
+        const stores = [];
+        const owners = new Map();
+        for (const file of metadata) {
+            const record = JSON.parse(metadataBlobs.get(file.oid).toString('utf8'));
+            if (file.path.startsWith('.ax/entities/stores/'))
+                stores.push(record.storeLocator);
+            else {
+                const ids = owners.get(record.displayId) ?? [];
+                ids.push({ entityId: record.entityId, storeId: record.storeId });
+                owners.set(record.displayId, ids);
+            }
+        }
+        // Registration/record schema alone does not prove a foreign target document exists.
+        // Validate each foreign store's one-to-one document mapping at the same immutable commit.
+        for (const locator of stores)
+            if (locator !== snapshot.storeLocator)
+                (0, entity_git_snapshot_1.readEntityGitSnapshot)(root, snapshot.commit, locator);
+        let ignoreText = '';
+        const ignoreFile = snapshot.files.find(file => file.path === '.gitignore');
+        if (ignoreFile) {
+            if (!['100644', '100755'].includes(ignoreFile.mode))
+                branch.diagnostics.push({ file: '.gitignore', reason: 'Ignore policy is not a regular Git blob.' });
+            else {
+                const bytes = (0, entity_git_snapshot_1.readEntityGitBlobs)(root, [ignoreFile.oid]).get(ignoreFile.oid);
+                ignoreText = bytes.toString('utf8');
+                if (!Buffer.from(ignoreText).equals(bytes) || ignoreText.includes('\0')) {
+                    branch.diagnostics.push({ file: '.gitignore', reason: 'Ignore policy is not UTF-8 text.' });
+                    ignoreText = '';
+                }
+            }
+        }
+        const ignore = (0, ignore_1.parseIgnore)(ignoreText);
+        for (const pattern of ignore.unsupportedPatterns())
+            branch.diagnostics.push({ file: '.gitignore', reason: 'Unsupported ignore pattern: ' + pattern });
+        const venvs = snapshot.files.filter(file => file.path.endsWith('/pyvenv.cfg')).map(file => file.path.slice(0, -'/pyvenv.cfg'.length));
+        const under = (file, directory) => file === directory || file.startsWith(directory + '/');
+        const candidates = snapshot.files.filter(({ path: file }) => file !== '.gitignore' && !untouched.has(file) &&
+            !under(file, '.ax/entities') && !under(file, '.ax/approvals') && !(0, change_source_1.isDerivedState)(file) &&
+            !stores.some(store => under(file, store)) && !venvs.some(venv => under(file, venv)) &&
+            !file.split('/').slice(0, -1).some(part => cpg_scanner_1.SKIP.has(part)) && !ignore.isIgnored(file));
+        const blobs = (0, entity_git_snapshot_1.readEntityGitBlobs)(root, candidates.filter(file => file.mode !== '120000' && file.mode !== '160000').map(file => file.oid));
+        const pairs = snapshot.entities.map(entity => ({ oldId: entity.displayId, newId: finalIds.get(entity.entityId) ?? entity.displayId }));
+        for (const file of candidates) {
+            if (file.mode === '120000') {
+                branch.diagnostics.push({ file: file.path, reason: 'Symlinked source is not followed.' });
+                continue;
+            }
+            if (file.mode === '160000') {
+                branch.diagnostics.push({ file: file.path, reason: 'Gitlink source is not integrated.' });
+                continue;
+            }
+            const planned = await (0, renumber_1.planSourceTextRenumber)(file.path, blobs.get(file.oid), pairs, { inspectAllAnchors: true });
+            branch.diagnostics.push(...planned.diagnostics);
+            branch.proseCandidates.push(...planned.proseCandidates);
+            for (const proposal of planned.files) {
+                const anchors = [];
+                for (const displayId of proposal.anchorIds) {
+                    const targets = owners.get(displayId) ?? [];
+                    if (targets.length !== 1) {
+                        branch.diagnostics.push({ file: file.path, reason: (targets.length ? 'Ambiguous' : 'Unknown') + ' anchor owner: ' + displayId });
+                        continue;
+                    }
+                    const target = targets[0];
+                    const newDisplayId = target.storeId === snapshot.storeId ? finalIds.get(target.entityId) : displayId;
+                    if (!newDisplayId) {
+                        if (deferDeletedTargets)
+                            anchors.push({ displayId, entityId: target.entityId, newDisplayId: displayId, targetDeleted: true });
+                        else
+                            branch.diagnostics.push({ file: file.path, reason: 'Deleted anchor target: ' + displayId });
+                        continue;
+                    }
+                    anchors.push({ displayId, entityId: target.entityId, newDisplayId });
+                }
+                branch.files.push({ file: file.path, oid: file.oid, mode: file.mode, before: proposal.before, after: proposal.after, anchors });
+            }
+        }
+    }
+    const conflicts = ['base', 'left', 'right'].flatMap(side => branches[side].diagnostics.map(diagnostic => side + ': ' + diagnostic.file + ': ' + diagnostic.reason));
+    return { ok: conflicts.length === 0, conflicts, branches };
+}
+/** Keep each original namespace until references have been rewritten; never merge ID maps first. */
+function planEntityGitDocuments(inputs) {
+    const numbering = planEntityGitNumbering(inputs);
+    if (!numbering.ok)
+        return { ok: false, documents: [], conflicts: numbering.conflicts, evidence: numbering.evidence };
+    const propose = (snapshot) => {
+        const ids = new Map(snapshot.entities.map(entity => [entity.entityId, entity.displayId]));
+        return (0, entity_renumber_1.planEntityRenumber)(snapshot.entities.map(entity => ({ entityId: entity.entityId, documentLocator: entity.documentLocator, text: entity.document })), numbering.assignments.filter(assignment => ids.has(assignment.entityId) && assignment.newDisplayId !== ids.get(assignment.entityId)).map(assignment => ({ entityId: assignment.entityId, newDisplayId: assignment.newDisplayId })));
+    };
+    const branches = { base: propose(inputs.base), left: propose(inputs.left), right: propose(inputs.right) };
+    const conflicts = ['base', 'left', 'right'].flatMap(side => branches[side].conflicts.map(reason => side + ': ' + reason));
+    if (conflicts.length)
+        return { ok: false, documents: [], conflicts, branches };
+    const documents = [];
+    for (const decision of classifyEntityGitChanges(inputs, 'meaning').decisions) {
+        if (decision.outcome === 'deleted')
+            continue;
+        const source = decision.outcome === 'unchanged' ? 'base' : decision.outcome === 'right' ? 'right' : 'left';
+        const proposal = branches[source].entries.find(entry => entry.entityId === decision.entityId);
+        if (!proposal)
+            return { ok: false, documents: [], conflicts: ['Missing selected document proposal: ' + decision.entityId], branches };
+        documents.push({ ...proposal, source, sourceCommit: inputs[source].commit });
+    }
+    // Each branch can be valid while the combined dependency graph is cyclic or dangling.
+    const combined = (0, entity_renumber_1.planEntityRenumber)(documents.map(document => ({ entityId: document.entityId, documentLocator: document.newDocumentLocator, text: document.after })), []);
+    if (!combined.ok)
+        return { ok: false, documents: [], conflicts: combined.conflicts, branches };
+    return { ok: true, documents, conflicts: [], branches, approval: combinedApprovalObligations(documents) };
+}
+/** Requirements for later official transitions, not grants or newly generated seals. */
+function combinedApprovalObligations(documents) {
+    const specs = new Map(documents.map(document => [document.newId, (0, spec_parser_1.parseSpec)(document.after)]));
+    const reasons = new Map();
+    for (const [id, spec] of specs) {
+        if (spec.status !== 'approved')
+            continue;
+        const issues = new Set();
+        if (spec.frontmatter.approved_digest !== (0, spec_digest_1.specDigest)(spec))
+            issues.add('content-seal');
+        const expected = {};
+        for (const parentId of spec.dependsOn) {
+            const parent = specs.get(parentId);
+            expected[parentId] = (0, spec_digest_1.specDigest)(parent);
+            if (parent.status !== 'approved')
+                issues.add('parent-not-approved');
+        }
+        const pinned = spec.frontmatter.parent_digests;
+        if (!(pinned === undefined && spec.dependsOn.length === 0) && !(0, node_util_1.isDeepStrictEqual)(pinned, expected))
+            issues.add('parent-snapshot');
+        if (issues.size)
+            reasons.set(id, issues);
+    }
+    // planEntityRenumber has already validated the combined graph and all dependency targets.
+    const remaining = new Set(specs.keys()), order = [], affected = new Set(reasons.keys());
+    while (remaining.size) {
+        const ready = [...remaining].filter(id => specs.get(id).dependsOn.every(parent => !remaining.has(parent))).sort();
+        if (!ready.length)
+            throw new entity_transaction_1.EntityStoreError('identity-conflict', 'Combined approval graph contains a cycle.');
+        for (const id of ready) {
+            const spec = specs.get(id);
+            if (spec.dependsOn.some(parent => affected.has(parent))) {
+                affected.add(id);
+                if (spec.status === 'approved') {
+                    const issues = reasons.get(id) ?? new Set();
+                    issues.add('approval-descendant');
+                    reasons.set(id, issues);
+                }
+            }
+            remaining.delete(id);
+            order.push(id);
+        }
+    }
+    const approveOrder = order.filter(id => reasons.has(id));
+    const targets = documents.filter(document => reasons.has(document.newId)).map(document => ({ entityId: document.entityId, displayId: document.newId, reasons: [...reasons.get(document.newId)].sort() }));
+    return { targets, approveOrder, unsealOrder: [...approveOrder].reverse() };
+}
+/** Namespace proposal only: these assignments still need reference rewriting, authorization and publication. */
+function planEntityGitNumbering(inputs) {
+    const classification = classifyEntityGitChanges(inputs, 'meaning'), conflicts = [], evidence = [];
+    const evidenceKey = (record) => record.kind + '\0' + (record.kind === 'mirror' ? record.entityIds.join(',') : record.entityId) + '\0' + (record.kind === 'reference' ? record.reference : '');
+    const refused = () => {
+        const unique = new Map(evidence.map(record => [evidenceKey(record), record]));
+        return { ok: false, assignments: [], conflicts: [...new Set(conflicts)].sort(), evidence: [...unique.entries()].sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0).map(([, record]) => record) };
+    };
+    const decisionOf = new Map(classification.decisions.map(decision => [decision.entityId, decision]));
+    const displayIdsOf = (entityId) => {
+        const decision = decisionOf.get(entityId);
+        return { base: decision?.base?.displayId ?? null, left: decision?.left?.displayId ?? null, right: decision?.right?.displayId ?? null };
+    };
+    for (const decision of classification.decisions)
+        if (decision.outcome === 'conflict')
+            conflicts.push(decision.entityId + ': ' + decision.reason);
+    if (conflicts.length)
+        return refused();
+    const selected = new Map();
+    const desiredIds = new Map();
+    const exact = new Map(classifyEntityGitChanges(inputs).decisions.map(decision => [decision.entityId, decision]));
+    for (const decision of classification.decisions) {
+        const original = exact.get(decision.entityId);
+        const unchanged = original.outcome === 'left' ? decision.left : original.outcome === 'right' ? decision.right : decision.base;
+        const entity = decision.outcome === 'unchanged' ? unchanged : decision.outcome === 'right' ? decision.right : ['left', 'equal'].includes(decision.outcome) ? decision.left : null;
+        if (entity) {
+            selected.set(entity.entityId, entity);
+            const b = decision.base?.displayId, l = decision.left?.displayId, r = decision.right?.displayId;
+            const desired = l === r ? l : l === b ? r : r === b ? l : !l ? r : !r ? l : undefined;
+            if (!desired) {
+                conflicts.push('Concurrent display ID changes: ' + decision.entityId);
+                evidence.push({ kind: 'numbering', entityId: decision.entityId, reason: 'concurrent-display-id', displayIds: displayIdsOf(decision.entityId) });
+            }
+            else
+                desiredIds.set(decision.entityId, desired);
+        }
+    }
+    if (conflicts.length)
+        return refused();
+    const contexts = [inputs.base, inputs.left, inputs.right].map(snapshot => ({ entities: new Map(snapshot.entities.map(entity => [entity.entityId, entity])), ids: new Map(snapshot.entities.map(entity => [entity.displayId, entity.entityId])) }));
+    const specs = new Map([...selected].map(([id, entity]) => [id, (0, spec_parser_1.parseSpec)(entity.document)]));
+    const parts = new Map();
+    const parents = new Map();
+    for (const [id, entity] of selected) {
+        const spec = specs.get(id), match = /^(.*-)(\d+)(\.\d+)?$/.exec(desiredIds.get(id));
+        if (spec.id !== entity.displayId) {
+            conflicts.push('Document ID differs from its display ID: ' + entity.displayId);
+            evidence.push({ kind: 'document', entityId: id, reason: 'id-mismatch', displayIds: displayIdsOf(id) });
+            continue;
+        }
+        if (!(0, spec_types_1.specTypeDef)(spec.type)) {
+            conflicts.push('Unsupported spec type for ' + entity.displayId);
+            evidence.push({ kind: 'document', entityId: id, reason: 'unsupported-type', displayIds: displayIdsOf(id) });
+            continue;
+        }
+        if (!match || !(0, spec_types_1.specTypeDef)(spec.type).idRegex.test(entity.displayId)) {
+            conflicts.push('Unsupported display ID: ' + entity.displayId);
+            evidence.push({ kind: 'document', entityId: id, reason: 'unsupported-display-id', displayIds: displayIdsOf(id) });
+            continue;
+        }
+        parts.set(id, { prefix: match[1], base: match[2], dot: match[3] ?? '' });
+        const matching = contexts.filter(context => {
+            const candidate = context.entities.get(id);
+            return candidate?.document === entity.document && candidate.record === entity.record;
+        });
+        const targets = [];
+        for (const reference of spec.dependsOn) {
+            const meanings = new Set(matching.map(context => context.ids.get(reference)));
+            const resolution = { base: contexts[0].ids.get(reference) ?? null, left: contexts[1].ids.get(reference) ?? null, right: contexts[2].ids.get(reference) ?? null };
+            if (meanings.size !== 1 || meanings.has(undefined)) {
+                conflicts.push('Ambiguous or unresolved reference: ' + id + ' -> ' + reference);
+                evidence.push({ kind: 'reference', entityId: id, reference, reason: meanings.has(undefined) ? 'unresolved' : 'ambiguous', targets: resolution });
+                continue;
+            }
+            const target = [...meanings][0];
+            if (!selected.has(target)) {
+                conflicts.push('Deleted reference target: ' + id + ' -> ' + reference);
+                evidence.push({ kind: 'reference', entityId: id, reference, reason: 'deleted-target', targets: resolution });
+                continue;
+            }
+            targets.push(target);
+        }
+        parents.set(id, targets);
+    }
+    if (conflicts.length)
+        return refused();
+    // Union only an A/T relationship proven in the originating document's namespace.
+    const groupParent = new Map([...selected.keys()].map(id => [id, id]));
+    const groupOf = (id) => { let current = id; while (groupParent.get(current) !== current)
+        current = groupParent.get(current); return current; };
+    for (const [id, spec] of specs)
+        if (spec.type === 'T-SPEC') {
+            for (const target of parents.get(id)) {
+                const originalReference = spec.dependsOn[parents.get(id).indexOf(target)];
+                if (!originalReference.startsWith('A-SPEC-') || originalReference.slice(7) !== spec.id.slice(7))
+                    continue;
+                const a = groupOf(id), b = groupOf(target);
+                groupParent.set(a < b ? b : a, a < b ? a : b);
+            }
+        }
+    const groups = new Map();
+    for (const id of selected.keys()) {
+        const key = groupOf(id), members = groups.get(key) ?? [];
+        members.push(id);
+        groups.set(key, members);
+    }
+    for (const members of groups.values())
+        if (new Set(members.map(id => parts.get(id).base + parts.get(id).dot)).size !== 1) {
+            const sorted = [...members].sort();
+            conflicts.push('Incompatible mirror number changes: ' + members.join(', '));
+            evidence.push({ kind: 'mirror', entityIds: sorted, reason: 'incompatible-mirror-numbers', displayIds: Object.fromEntries(sorted.map(id => [id, displayIdsOf(id)])) });
+        }
+    if (conflicts.length)
+        return refused();
+    const counts = new Map();
+    for (const id of selected.keys()) {
+        const desired = desiredIds.get(id);
+        counts.set(desired, (counts.get(desired) ?? 0) + 1);
+    }
+    const ancestors = new Set(inputs.base.entities.map(entity => entity.entityId));
+    const reserved = new Map(inputs.base.entities.map(entity => [entity.displayId, entity.entityId]));
+    for (const id of selected.keys()) {
+        const desired = desiredIds.get(id);
+        if (counts.get(desired) === 1 && !reserved.has(desired))
+            reserved.set(desired, id);
+    }
+    let largest = BigInt(0);
+    for (const snapshot of [inputs.base, inputs.left, inputs.right])
+        for (const displayId of [...snapshot.entities.map(entity => entity.displayId), ...(snapshot.otherStoreDisplayIds ?? [])]) {
+            const match = /-(\d+)(?:\.\d+)?$/.exec(displayId);
+            if (match && BigInt(match[1]) > largest)
+                largest = BigInt(match[1]);
+        }
+    const priority = (members) => members.some(id => ancestors.has(id)) ? 0 : members.some(id => counts.get(desiredIds.get(id)) === 1) ? 1 : 2;
+    const ordered = [...groups.values()].map(members => members.sort()).sort((a, b) => priority(a) - priority(b) || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    const assignments = [];
+    for (const members of ordered) {
+        const keep = members.every(id => !reserved.has(desiredIds.get(id)) || reserved.get(desiredIds.get(id)) === id);
+        const next = keep ? undefined : (++largest).toString().padStart(3, '0');
+        for (const id of members) {
+            const entity = selected.get(id), part = parts.get(id);
+            const newDisplayId = next === undefined ? desiredIds.get(id) : part.prefix + next + part.dot;
+            reserved.set(newDisplayId, id);
+            assignments.push({ entityId: id, oldDisplayId: entity.displayId, newDisplayId });
+        }
+    }
+    assignments.sort((a, b) => a.entityId < b.entityId ? -1 : a.entityId > b.entityId ? 1 : 0);
+    return { ok: true, assignments, conflicts: [] };
+}
+/** Projection for comparison only; original bytes remain on each decision. */
+function entityMeaning(entity, snapshot) {
+    const spec = (0, spec_parser_1.parseSpec)(entity.document), header = /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/.exec(entity.document);
+    if (!header || spec.id !== entity.displayId)
+        throw new Error('Invalid comparison document');
+    const bindReferences = (document) => document.dependsOn.map(displayId => {
+        const matches = snapshot.entities.filter(candidate => candidate.displayId === displayId);
+        if (matches.length !== 1)
+            throw new Error('Unresolved comparison reference');
+        return matches[0].entityId;
+    });
+    const references = bindReferences(spec);
+    const metadata = { ...spec.frontmatter, id: entity.entityId,
+        ...(Array.isArray(spec.frontmatter.depends_on) ? { depends_on: references } : {}) };
+    const validSeal = (document) => document.status === 'approved' && document.frontmatter.approved_digest === (0, spec_digest_1.specDigest)(document);
+    const rawSeal = (field) => ({ kind: 'raw', present: Object.prototype.hasOwnProperty.call(spec.frontmatter, field), value: spec.frontmatter[field] });
+    const ownSeal = validSeal(spec) ? { kind: 'verified', digest: (0, spec_digest_1.specDigest)({ ...spec, dependsOn: references }) } : rawSeal('approved_digest');
+    const pinned = spec.frontmatter.parent_digests;
+    let parentSeal = rawSeal('parent_digests');
+    if (pinned && typeof pinned === 'object' && !Array.isArray(pinned)) {
+        const entries = Object.entries(pinned);
+        const targets = entries.map(([id, digest]) => {
+            const matches = snapshot.entities.filter(candidate => candidate.displayId === id);
+            if (matches.length !== 1 || !spec.dependsOn.includes(id))
+                return null;
+            const parent = (0, spec_parser_1.parseSpec)(matches[0].document);
+            if (!validSeal(parent) || digest !== parent.frontmatter.approved_digest)
+                return null;
+            return [matches[0].entityId, (0, spec_digest_1.specDigest)({ ...parent, dependsOn: bindReferences(parent) })];
+        });
+        if (entries.length === new Set(spec.dependsOn).size && targets.every(target => target !== null)) {
+            parentSeal = { kind: 'verified', targets: targets.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0) };
+        }
+    }
+    // Tags distinguish proven equivalent seal contents from raw or malformed metadata.
+    // No document bytes, statuses or approval grants are written by this comparison.
+    delete metadata.approved_digest;
+    delete metadata.parent_digests;
+    const locator = path.posix.basename(entity.documentLocator) === entity.displayId + '.md'
+        ? path.posix.join(path.posix.dirname(entity.documentLocator), entity.entityId + '.md') : entity.documentLocator;
+    const record = JSON.parse(entity.record);
+    return {
+        entityId: entity.entityId, locator, recordLocator: entity.recordLocator,
+        metadata, ownSeal, parentSeal,
+        body: entity.document.slice(header[0].length),
+        record: { ...record, displayId: entity.entityId, documentLocator: locator },
+        documentMode: snapshot.files.find(file => file.path === snapshot.storeLocator + '/' + entity.documentLocator)?.mode,
+        recordMode: snapshot.files.find(file => file.path === entity.recordLocator)?.mode,
+    };
+}
+/** Exact remains the default; meaning mode changes comparison, never retained inputs. */
+function classifyEntityGitChanges(inputs, comparison = 'exact') {
+    const snapshots = [inputs.base, inputs.left, inputs.right];
+    for (const snapshot of snapshots) {
+        if (snapshot.workspaceId !== inputs.base.workspaceId || snapshot.storeId !== inputs.base.storeId)
+            throw new entity_transaction_1.EntityStoreError('identity-conflict', 'Classification requires the same workspace and store identity.');
+        if (new Set(snapshot.entities.map(entity => entity.entityId)).size !== snapshot.entities.length)
+            throw new entity_transaction_1.EntityStoreError('identity-conflict', 'Duplicate entity UUID in classification input.');
+    }
+    const [baseMap, leftMap, rightMap] = snapshots.map(snapshot => new Map(snapshot.entities.map(entity => [entity.entityId, entity])));
+    const ids = [...new Set(snapshots.flatMap(snapshot => snapshot.entities.map(entity => entity.entityId)))].sort();
+    const equal = (a, b, sa, sb) => {
+        if (a === null || b === null)
+            return a === b;
+        if (comparison === 'meaning') {
+            try {
+                return (0, node_util_1.isDeepStrictEqual)(entityMeaning(a, sa), entityMeaning(b, sb));
+            }
+            catch {
+                return false;
+            }
+        }
+        return a.entityId === b.entityId && a.displayId === b.displayId && a.documentLocator === b.documentLocator && a.recordLocator === b.recordLocator && a.document === b.document && a.record === b.record;
+    };
+    const decisions = ids.map(entityId => {
+        const base = baseMap.get(entityId) ?? null, left = leftMap.get(entityId) ?? null, right = rightMap.get(entityId) ?? null;
+        let outcome, reason;
+        if (equal(left, right, inputs.left, inputs.right)) {
+            if (equal(base, left, inputs.base, inputs.left)) {
+                outcome = 'unchanged';
+                reason = 'unchanged';
+            }
+            else if (left === null) {
+                outcome = 'deleted';
+                reason = 'both-deleted';
+            }
+            else {
+                outcome = 'equal';
+                reason = 'identical-change';
+            }
+        }
+        else if (equal(base, left, inputs.base, inputs.left)) {
+            outcome = right ? 'right' : 'deleted';
+            reason = right ? (base ? 'one-sided-change' : 'independent-create') : 'delete-unchanged';
+        }
+        else if (equal(base, right, inputs.base, inputs.right)) {
+            outcome = left ? 'left' : 'deleted';
+            reason = left ? (base ? 'one-sided-change' : 'independent-create') : 'delete-unchanged';
+        }
+        else {
+            outcome = 'conflict';
+            reason = !left || !right ? 'delete-modify' : 'concurrent-change';
+        }
+        return { entityId, outcome, reason, base, left, right };
+    });
+    const displayIds = new Map();
+    for (const decision of decisions) {
+        const selected = decision.outcome === 'unchanged' ? decision.base : decision.outcome === 'right' ? decision.right : ['left', 'equal'].includes(decision.outcome) ? decision.left : null;
+        if (!selected)
+            continue;
+        const group = displayIds.get(selected.displayId) ?? [];
+        group.push(selected.entityId);
+        displayIds.set(selected.displayId, group);
+    }
+    const collisions = [...displayIds].filter(([, entities]) => entities.length > 1).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([displayId, entityIds]) => ({ displayId, entityIds: entityIds.sort() }));
+    return { schema: 'holmes-entity-git-classification/1', commits: { base: inputs.base.commit, left: inputs.left.commit, right: inputs.right.commit }, decisions, collisions };
+}