@holmes-lab/holmes-kit 0.19.5 → 0.20.0

package/dist/holmes/mcp/handlers/entity-renumber.js

@@ -0,0 +1,228 @@
+"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.createEntityRenumberHandlers = createEntityRenumberHandlers;
+// @implements A-SPEC-628
+// @implements A-SPEC-642
+// @implements A-SPEC-639
+const fs = __importStar(require("node:fs"));
+const entity_store_1 = require("../../spec/entity-store");
+const entity_renumber_1 = require("../../spec/entity-renumber");
+const root_1 = require("../../project/root");
+const renumber_1 = require("../../spec/renumber");
+const entity_transaction_1 = require("../../spec/entity-transaction");
+const path = __importStar(require("node:path"));
+const entity_renumber_transaction_1 = require("../../spec/entity-renumber-transaction");
+const approval_grants_1 = require("../../governance/approval-grants");
+const approval_queue_1 = require("../../governance/approval-queue");
+const ledger_store_1 = require("../../governance/ledger-store");
+const provenance_chain_1 = require("../../governance/provenance-chain");
+function createEntityRenumberHandlers(context) {
+    return {
+        async entity_renumber(a) {
+            try {
+                if (!context.storeRoot)
+                    throw new entity_store_1.EntityStoreError('unsupported-store', 'Entity renumbering requires a configured filesystem spec store.');
+                const bound = (0, entity_store_1.entityStoreBinding)(context.storeRoot);
+                if (a.root !== undefined && fs.realpathSync((0, root_1.resolveProjectRoot)(a.root, { includeGit: false }).root) !== bound.root)
+                    throw new entity_store_1.EntityStoreError('foreign-workspace', 'The requested workspace differs from the configured store.');
+                if (a.operation === 'recovery-plan')
+                    return { ok: true, plan: (0, entity_renumber_transaction_1.planEntityRenumberRecovery)(context.storeRoot) };
+                // @implements A-SPEC-642 — an authority-spending operation is refused, naming the exit, while the
+                // merged ledger holds an unreconciled double-spend; the audit adapter's `audit-conflict` stays behind.
+                if (a.operation === 'apply' || a.operation === 'recover' || a.operation === 'abandon') {
+                    const conflict = (0, ledger_store_1.ledgerConflictReason)(path.join(bound.root, '.ax', 'ledger'));
+                    if (conflict)
+                        throw new entity_store_1.EntityStoreError('ledger-conflict', conflict);
+                }
+                if (a.operation === 'abandon') {
+                    // @implements A-SPEC-639 — an authorized exit for a pending renumber a third state blocked.
+                    const recovery = (0, entity_renumber_transaction_1.validateEntityRenumberRecoveryPlan)(a.plan);
+                    const target = 'entity-store:renumber-abandon:' + (0, entity_transaction_1.entityContentVersion)(JSON.stringify(a.plan));
+                    let env;
+                    try {
+                        env = process.env.HOLMES_APPROVAL ? JSON.parse(process.env.HOLMES_APPROVAL) : undefined;
+                    }
+                    catch {
+                        env = undefined;
+                    }
+                    const authorities = new Set();
+                    const requireAuthority = () => {
+                        const action = { kind: 'config-write', target };
+                        const resolved = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString());
+                        if (!resolved)
+                            throw new entity_store_1.EntityStoreError('approval-required', 'Current authority is required to abandon this renumber operation.' + (0, approval_queue_1.queueHint)(bound.root, { ...action, why: 'Abandon the blocked renumber: revert its own publications, preserve foreign bytes, release ownership.' }));
+                        authorities.add((0, provenance_chain_1.authorizationRef)(resolved.approval.actor, resolved.approval.token));
+                        return resolved;
+                    };
+                    requireAuthority();
+                    const audit = (operation, outcome) => {
+                        const authority = requireAuthority(), ledger = new ledger_store_1.FileLedgerStore(path.join(bound.root, '.ax/ledger'));
+                        if (!ledger.verifyAll().ok)
+                            throw new entity_store_1.EntityStoreError('audit-conflict', 'Abandonment audit cannot extend an invalid ledger.');
+                        const ref = 'entity-operation:' + operation.operationId;
+                        if (ledger.loadAll().some(event => event.kind === 'entity-renumber-abandoned' && event.inputs?.includes(ref)))
+                            return;
+                        ledger.append({ ts: new Date().toISOString(), actor: authority.approval.actor, kind: 'entity-renumber-abandoned', summary: 'Abandoned entity renumbering ' + operation.operationId,
+                            inputs: [ref, (0, entity_renumber_transaction_1.entityRenumberTarget)(operation), 'workspace:' + operation.snapshot.workspaceId, 'store:' + operation.snapshot.storeId, recovery.journalVersion, target,
+                                ...outcome.restored.map(locator => 'restored:' + locator), ...outcome.preserved.map(locator => 'preserved:' + locator), ...authorities],
+                            rationale: authority.approval.rationale, authorization: (0, provenance_chain_1.authorizationRef)(authority.approval.actor, authority.approval.token) });
+                    };
+                    return await (0, entity_renumber_transaction_1.abandonEntityRenumber)(context.storeRoot, recovery, requireAuthority, audit);
+                }
+                if (a.operation === 'apply' || a.operation === 'recover') {
+                    const recovery = a.operation === 'recover' ? (0, entity_renumber_transaction_1.validateEntityRenumberRecoveryPlan)(a.plan) : undefined;
+                    const plan = recovery ? undefined : (0, entity_renumber_transaction_1.validateEntityRenumberPlan)(a.plan), target = recovery ? (0, entity_renumber_transaction_1.entityRenumberRecoveryTarget)(recovery) : (0, entity_renumber_transaction_1.entityRenumberTarget)(plan);
+                    let env;
+                    try {
+                        env = process.env.HOLMES_APPROVAL ? JSON.parse(process.env.HOLMES_APPROVAL) : undefined;
+                    }
+                    catch {
+                        env = undefined;
+                    }
+                    const grants = new Set(), authorities = new Set();
+                    const usedGrantRefs = new Set();
+                    const grantRef = (approval) => 'grant-use:' + (0, entity_transaction_1.entityContentVersion)(JSON.stringify({ actor: approval.actor, token: approval.token, nonce: approval.nonce, scope: approval.scope, expires: approval.expires }));
+                    const requireAuthority = (specId) => {
+                        const action = { kind: specId ? 'spec-approve' : 'config-write', target: specId ?? target };
+                        const resolved = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString());
+                        if (!resolved)
+                            throw new entity_store_1.EntityStoreError(specId ? 'spec-approval-required' : 'approval-required', 'Current authority is required for this renumber operation.' + (0, approval_queue_1.queueHint)(bound.root, { ...action, why: 'Preserve UUIDs and the official approval closure while renumbering.' }));
+                        if (resolved.source === 'grant' && resolved.approval.nonce)
+                            grants.add(resolved.approval.nonce);
+                        if (resolved.source === 'grant')
+                            usedGrantRefs.add(grantRef(resolved.approval));
+                        authorities.add((0, provenance_chain_1.authorizationRef)(resolved.approval.actor, resolved.approval.token));
+                        return resolved;
+                    };
+                    requireAuthority();
+                    const bindingFor = (operation) => ['entity-operation:' + operation.operationId, (0, entity_renumber_transaction_1.entityRenumberTarget)(operation), 'workspace:' + operation.snapshot.workspaceId, 'store:' + operation.snapshot.storeId];
+                    const priorGrantUses = (ledger, operation) => {
+                        if (!ledger.verifyAll().ok)
+                            throw new entity_store_1.EntityStoreError('audit-conflict', 'Grant usage cannot rely on an invalid ledger.');
+                        const binding = bindingFor(operation), refs = new Set();
+                        for (const event of ledger.loadAll().filter(event => event.kind === 'entity-renumber-grant-used' && event.inputs?.includes(binding[0]))) {
+                            const usages = (event.inputs ?? []).filter(ref => ref.startsWith('grant-use:'));
+                            if (binding.some(ref => !event.inputs?.includes(ref)) || usages.length === 0 || usages.some(ref => !/^grant-use:sha256:[0-9a-f]{64}$/.test(ref) || refs.has(ref)))
+                                throw new entity_store_1.EntityStoreError('audit-conflict', 'Grant usage has conflicting operation or plan bindings.');
+                            for (const ref of usages)
+                                refs.add(ref);
+                        }
+                        return refs;
+                    };
+                    const recordGrantUse = (operation) => {
+                        const authority = requireAuthority(), ledger = new ledger_store_1.FileLedgerStore(path.join(bound.root, '.ax/ledger'));
+                        const prior = priorGrantUses(ledger, operation);
+                        const additional = [...usedGrantRefs].filter(ref => !prior.has(ref));
+                        for (const ref of prior)
+                            usedGrantRefs.add(ref);
+                        if (additional.length === 0)
+                            return;
+                        ledger.append({ ts: new Date().toISOString(), actor: authority.approval.actor, kind: 'entity-renumber-grant-used',
+                            summary: 'Reserved grant usage before renumber publication ' + operation.operationId,
+                            inputs: [...bindingFor(operation), target, ...additional, ...authorities], rationale: authority.approval.rationale,
+                            authorization: (0, provenance_chain_1.authorizationRef)(authority.approval.actor, authority.approval.token) });
+                    };
+                    const audit = (completed, verifyOnly = false) => {
+                        const authority = requireAuthority(), ledger = new ledger_store_1.FileLedgerStore(path.join(bound.root, '.ax/ledger'));
+                        if (!ledger.verifyAll().ok)
+                            throw new entity_store_1.EntityStoreError('audit-conflict', 'Renumber completion cannot extend an invalid ledger.');
+                        const operation = 'entity-operation:' + completed.operationId;
+                        const binding = bindingFor(completed);
+                        for (const ref of priorGrantUses(ledger, completed))
+                            usedGrantRefs.add(ref);
+                        const existing = ledger.loadAll().filter(event => event.kind === 'entity-renumbered' && event.inputs?.includes(operation));
+                        if (existing.length) {
+                            if (existing.length !== 1 || binding.some(ref => !existing[0].inputs?.includes(ref)))
+                                throw new entity_store_1.EntityStoreError('audit-conflict', 'Renumber audit has conflicting completion bindings.');
+                            for (const ref of existing[0].inputs ?? [])
+                                if (ref.startsWith('grant-use:'))
+                                    usedGrantRefs.add(ref);
+                            return;
+                        }
+                        if (verifyOnly)
+                            throw new entity_store_1.EntityStoreError('audit-conflict', 'Completion receipt has no matching completion audit.');
+                        const proposal = (0, entity_renumber_1.planEntityRenumber)(completed.snapshot.entries, completed.changes);
+                        ledger.append({ ts: new Date().toISOString(), actor: authority.approval.actor, kind: 'entity-renumbered', summary: 'Completed entity renumbering ' + completed.operationId,
+                            inputs: [...binding, target,
+                                ...proposal.entries.filter(e => e.oldId !== e.newId).flatMap(e => ['entity:' + e.entityId, 'old-id:' + e.oldId, 'new-id:' + e.newId]), ...authorities, ...usedGrantRefs],
+                            rationale: authority.approval.rationale, authorization: (0, provenance_chain_1.authorizationRef)(authority.approval.actor, authority.approval.token) });
+                    };
+                    const result = recovery
+                        ? await (0, entity_renumber_transaction_1.recoverEntityRenumber)(context.storeRoot, recovery, requireAuthority, audit, recordGrantUse)
+                        : await (0, entity_renumber_transaction_1.applyEntityRenumber)(context.storeRoot, plan, requireAuthority, verifyOnly => audit(plan, verifyOnly), recordGrantUse);
+                    for (const grant of (0, approval_grants_1.readGrants)(bound.root).grants)
+                        if (grant.nonce && usedGrantRefs.has(grantRef(grant)))
+                            grants.add(grant.nonce);
+                    for (const nonce of grants)
+                        (0, approval_grants_1.consumeGrantFile)(bound.root, nonce);
+                    return result;
+                }
+                if (a.operation !== undefined && a.operation !== 'plan')
+                    return { ok: false, code: 'unsupported-operation', reason: 'Use plan, apply, recovery-plan, recover or abandon.' };
+                if (!Array.isArray(a.changes) || a.changes.some(change => !change || typeof change.entityId !== 'string' || typeof change.newDisplayId !== 'string'))
+                    throw new entity_store_1.EntityStoreError('invalid-request', 'Provide entityId/newDisplayId changes.');
+                const changes = a.changes.map(change => ({ entityId: change.entityId, newDisplayId: change.newDisplayId }));
+                const snapshot = (0, entity_store_1.readEntityRenumberSnapshot)(context.storeRoot);
+                const proposal = (0, entity_renumber_1.planEntityRenumber)(snapshot.entries, changes);
+                if (!proposal.ok)
+                    return { ok: false, code: 'plan-conflict', conflicts: proposal.conflicts };
+                const pairs = proposal.entries.filter(entry => entry.oldId !== entry.newId).map(entry => ({ oldId: entry.oldId, newId: entry.newId }));
+                const sources = await (0, renumber_1.planSourceRenumber)(bound.root, pairs, path.relative(bound.root, bound.store).split(path.sep).join('/'));
+                if (JSON.stringify((0, entity_store_1.readEntityRenumberSnapshot)(context.storeRoot)) !== JSON.stringify(snapshot))
+                    throw new entity_store_1.EntityStoreError('plan-changed', 'Documents or identity mappings changed during source inventory.');
+                const ambiguous = new Set();
+                for (const file of sources.files)
+                    for (const id of file.anchorIds) {
+                        if (snapshot.referenceNamespaces.some(record => record.displayId === id && record.storeId !== snapshot.storeId))
+                            ambiguous.add(id);
+                    }
+                if (ambiguous.size)
+                    return { ok: false, code: 'ambiguous-reference', ids: [...ambiguous].sort(), reason: 'Source anchors name display IDs owned by more than one activated store.' };
+                const preview = { schema: 'holmes-entity-renumber-preview/1', ...snapshot, proposal, sources };
+                if (sources.diagnostics.length)
+                    return { ok: true, executable: false, blockers: sources.diagnostics.map(d => d.file + ': ' + d.reason), inputVersion: (0, entity_transaction_1.entityContentVersion)(JSON.stringify(preview)), preview };
+                const plan = (0, entity_renumber_transaction_1.prepareEntityRenumberPlan)(bound.root, snapshot, changes, sources);
+                return { ok: true, executable: true, plan, blockers: [], recoveryAvailable: true,
+                    inputVersion: (0, entity_transaction_1.entityContentVersion)(JSON.stringify(preview)), preview };
+            }
+            catch (error) {
+                if (error instanceof entity_store_1.EntityStoreError)
+                    return { ok: false, code: error.code, reason: error.message };
+                throw error;
+            }
+        },
+    };
+}

package/dist/holmes/mcp/handlers/entity-store.d.ts

@@ -0,0 +1,78 @@
+export declare function createEntityStoreHandlers(context: {
+    storeRoot?: string;
+}): {
+    entity_store(a: {
+        root?: string;
+        operation?: string;
+        plan?: unknown;
+    }): Promise<{
+        ok: true;
+        state: "active";
+        storeLocator: string;
+        storeId: string;
+    } | {
+        ok: true;
+        state: "legacy";
+        storeLocator: string;
+        storeId?: undefined;
+    } | {
+        ok: boolean;
+        plan: import("../../spec/entity-store").EntityAdoptionPlan;
+        code?: undefined;
+        reason?: undefined;
+    } | {
+        ok: boolean;
+        plan: {
+            sourceOwner?: {
+                token: string;
+                version: string;
+            } | undefined;
+            lockOwner?: {
+                token: string;
+                version: string;
+            } | undefined;
+            schema: "holmes-entity-recovery/1";
+            workspaceId: string;
+            storeLocator: string;
+            operations: ({
+                operationId: string;
+                kind: "aborted";
+                storeId: string;
+                journalVersion: null;
+                state: "empty";
+                targets: Array<{
+                    locator: string;
+                    beforeVersion: string | null;
+                    afterVersion: string | null;
+                    currentVersion: string | null;
+                    state: "unchanged" | "applied" | "unapplied" | "conflict";
+                }>;
+                inventoryConflicts: string[];
+                leftovers: string[];
+            } | {
+                retired?: true | undefined;
+                operationId: string;
+                kind: "adoption" | "write" | "legacy-renumber";
+                storeId: string | null;
+                journalVersion: string;
+                state: string;
+                targets: {
+                    locator: string;
+                    beforeVersion: string | null;
+                    afterVersion: string | null;
+                    currentVersion: string | null;
+                    state: string;
+                }[];
+                inventoryConflicts: string[];
+                leftovers?: undefined;
+            })[];
+        };
+        code?: undefined;
+        reason?: undefined;
+    } | {
+        ok: boolean;
+        code: string;
+        reason: string;
+        plan?: undefined;
+    }>;
+};

package/dist/holmes/mcp/handlers/entity-store.js

@@ -0,0 +1,212 @@
+"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.createEntityStoreHandlers = createEntityStoreHandlers;
+// @implements A-SPEC-627, A-SPEC-627.1
+// @implements A-SPEC-642
+// @implements A-SPEC-641
+// @implements A-SPEC-638
+// @implements A-SPEC-634
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_util_1 = require("node:util");
+const transition_policy_1 = require("../../spec/transition-policy");
+const spec_parser_1 = require("../../spec/spec-parser");
+const ledger_store_1 = require("../../governance/ledger-store");
+const provenance_chain_1 = require("../../governance/provenance-chain");
+const entity_transaction_1 = require("../../spec/entity-transaction");
+const entity_store_1 = require("../../spec/entity-store");
+const root_1 = require("../../project/root");
+const workspace_identity_1 = require("../../project/workspace-identity");
+const approval_grants_1 = require("../../governance/approval-grants");
+const approval_queue_1 = require("../../governance/approval-queue");
+function createEntityStoreHandlers(context) {
+    return {
+        async entity_store(a) {
+            try {
+                if (!context.storeRoot)
+                    throw new entity_store_1.EntityStoreError('unsupported-store', 'Entity persistence requires a configured filesystem spec store.');
+                const bound = (0, entity_store_1.entityStoreBinding)(context.storeRoot);
+                if (a.root !== undefined && (0, root_1.resolveProjectRoot)(a.root).root !== bound.root)
+                    throw new entity_store_1.EntityStoreError('foreign-workspace', 'The requested workspace differs from the configured store.');
+                if (a.operation === undefined || a.operation === 'status')
+                    return (0, entity_store_1.inspectEntityStore)(context.storeRoot);
+                if (a.operation === 'plan-adoption')
+                    return { ok: true, plan: (0, entity_store_1.planEntityAdoption)(context.storeRoot) };
+                if (a.operation === 'recovery-plan')
+                    return { ok: true, plan: (0, entity_store_1.planEntityRecovery)(context.storeRoot) };
+                // @implements A-SPEC-642 — an authority-spending operation is refused, naming the exit, while the
+                // merged ledger holds an unreconciled double-spend; the audit adapter's `audit-conflict` stays behind.
+                if (a.operation === 'recover' || a.operation === 'adopt') {
+                    const conflict = (0, ledger_store_1.ledgerConflictReason)(path.join(bound.root, '.ax', 'ledger'));
+                    if (conflict)
+                        throw new entity_store_1.EntityStoreError('ledger-conflict', conflict);
+                }
+                if (a.operation === 'recover') {
+                    const plan = (0, entity_store_1.validateEntityRecoveryPlan)(a.plan);
+                    const action = { kind: 'config-write', target: (0, entity_store_1.entityRecoveryTarget)(plan) };
+                    let env;
+                    try {
+                        env = process.env.HOLMES_APPROVAL ? JSON.parse(process.env.HOLMES_APPROVAL) : undefined;
+                    }
+                    catch {
+                        env = undefined;
+                    }
+                    const resolved = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString());
+                    if (!resolved)
+                        return { ok: false, code: 'approval-required', reason: 'Recovery requires approval for this exact inspected plan.' + (0, approval_queue_1.queueHint)(bound.root, { ...action, why: 'Recover the interrupted entity operation while preserving external changes.' }) };
+                    const specGrants = new Set();
+                    const specAuthorizations = new Set();
+                    const usedGrantRefs = new Set();
+                    const grantRef = (approval) => 'grant-use:' + (0, entity_transaction_1.entityContentVersion)(JSON.stringify({ actor: approval.actor, token: approval.token, nonce: approval.nonce, scope: approval.scope, expires: approval.expires }));
+                    const auditRecovery = () => {
+                        // @implements A-SPEC-634 — an aborted operation binds journal:none; a lock-only release binds no operation.
+                        const op = plan.operations[0] ?? { operationId: 'lock-only', storeId: 'none', journalVersion: null, targets: [] }, operationRef = 'entity-operation:' + op.operationId;
+                        const ledger = new ledger_store_1.FileLedgerStore(path.join(bound.root, '.ax/ledger'));
+                        if (!ledger.verifyAll().ok)
+                            throw new entity_store_1.EntityStoreError('audit-conflict', 'Recovery audit cannot extend an invalid ledger.');
+                        const binding = [operationRef, 'workspace:' + plan.workspaceId, 'store:' + (op.storeId ?? 'legacy'), 'store-locator:' + plan.storeLocator, op.journalVersion ?? 'journal:none'];
+                        const existing = ledger.loadAll().filter(event => event.kind === 'entity-recovered' && event.inputs?.includes(operationRef));
+                        if (existing.length) {
+                            if (existing.length !== 1 || binding.some(ref => !existing[0].inputs?.includes(ref)))
+                                throw new entity_store_1.EntityStoreError('audit-conflict', 'Recovery audit has conflicting operation bindings.');
+                            for (const ref of existing[0].inputs ?? [])
+                                if (ref.startsWith('grant-use:'))
+                                    usedGrantRefs.add(ref);
+                            return;
+                        }
+                        const authority = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString());
+                        if (!authority)
+                            throw new entity_store_1.EntityStoreError('approval-required', 'Recovery approval expired before audit completion.');
+                        if (authority.source === 'grant')
+                            usedGrantRefs.add(grantRef(authority.approval));
+                        const ids = op.targets.filter(target => target.locator.startsWith(bound.locator + '/') && target.locator.endsWith('.md') && target.afterVersion !== null).map(target => {
+                            const bytes = (0, entity_transaction_1.readEntityBytes)(path.join(bound.root, target.locator));
+                            if (!bytes || (0, entity_transaction_1.entityContentVersion)(bytes) !== target.afterVersion)
+                                throw new entity_store_1.EntityStoreError('plan-changed', 'Recovered document changed before audit completion.');
+                            return (0, spec_parser_1.parseSpec)(bytes.toString('utf8')).id;
+                        });
+                        ledger.append({ ts: new Date().toISOString(), actor: authority.approval.actor, kind: 'entity-recovered', summary: 'Completed entity recovery ' + op.operationId,
+                            inputs: [...binding, ...ids, (0, entity_store_1.entityRecoveryTarget)(plan), ...specAuthorizations, ...usedGrantRefs], rationale: authority.approval.rationale,
+                            authorization: (0, provenance_chain_1.authorizationRef)(authority.approval.actor, authority.approval.token) });
+                    };
+                    const result = (0, entity_store_1.recoverEntityStore)(context.storeRoot, plan, (before, after, inventory) => {
+                        const specAction = { kind: 'spec-approve', target: after.id };
+                        const requireAuthority = () => {
+                            const authority = (0, approval_grants_1.resolveApproval)(bound.root, env, specAction, new Date().toISOString());
+                            if (!authority)
+                                throw new entity_store_1.EntityStoreError('spec-approval-required', 'This recovery also requires current spec transition authority.' + (0, approval_queue_1.queueHint)(bound.root, { ...specAction, why: 'Recover the interrupted specification transition.' }));
+                            return authority;
+                        };
+                        requireAuthority();
+                        if (!before || !['approved', 'draft', 'outdated'].includes(after.status))
+                            throw new entity_store_1.EntityStoreError('unsupported-recovery', 'Unsupported specification transition.');
+                        const files = new Map();
+                        const readFile = (relative) => {
+                            let text;
+                            try {
+                                text = fs.readFileSync(path.join(bound.root, relative), 'utf8');
+                            }
+                            catch {
+                                text = null;
+                            }
+                            files.set(relative, text);
+                            return text;
+                        };
+                        const prepared = after.status === 'approved'
+                            ? (0, transition_policy_1.prepareApprovedSpec)(before, inventory, specs => id => specs.find(s => s.id === id) ?? null, readFile)
+                            : (0, transition_policy_1.prepareLifecycleSpec)(before, inventory, after.status === 'draft' ? 'unseal' : 'retire', typeof after.frontmatter.retired_reason === 'string' ? after.frontmatter.retired_reason : undefined);
+                        if (!prepared.ok)
+                            throw new entity_store_1.EntityStoreError('spec-policy-refused', after.id + ': ' + prepared.reason); // A-SPEC-641
+                        if (!(0, node_util_1.isDeepStrictEqual)((0, spec_parser_1.parseSpec)((0, spec_parser_1.serializeSpec)(prepared.candidate)), after))
+                            throw new entity_store_1.EntityStoreError('spec-policy-refused', 'The journal differs from the canonical approved transition.');
+                        return () => {
+                            for (const [relative, expected] of files) {
+                                let actual;
+                                try {
+                                    actual = fs.readFileSync(path.join(bound.root, relative), 'utf8');
+                                }
+                                catch {
+                                    actual = null;
+                                }
+                                if (actual !== expected)
+                                    throw new entity_store_1.EntityStoreError('plan-changed', 'Compatibility policy inputs changed before recovery publication.');
+                            }
+                            const authority = requireAuthority();
+                            specAuthorizations.add('spec-authorization:' + (0, provenance_chain_1.authorizationRef)(authority.approval.actor, authority.approval.token));
+                            if (authority.source === 'grant')
+                                usedGrantRefs.add(grantRef(authority.approval));
+                            if (authority.source === 'grant' && authority.approval.nonce)
+                                specGrants.add(authority.approval.nonce);
+                        };
+                    }, auditRecovery);
+                    const consumed = new Set(specGrants);
+                    if (resolved.source === 'grant' && resolved.approval.nonce)
+                        consumed.add(resolved.approval.nonce);
+                    for (const grant of (0, approval_grants_1.readGrants)(bound.root).grants)
+                        if (grant.nonce && usedGrantRefs.has(grantRef(grant)))
+                            consumed.add(grant.nonce);
+                    for (const nonce of consumed)
+                        (0, approval_grants_1.consumeGrantFile)(bound.root, nonce);
+                    return result;
+                }
+                if (a.operation === 'adopt') {
+                    const plan = (0, entity_store_1.validateEntityAdoptionPlan)(a.plan);
+                    const action = { kind: 'config-write', target: (0, entity_store_1.entityAdoptionTarget)(plan) };
+                    let env;
+                    try {
+                        env = process.env.HOLMES_APPROVAL ? JSON.parse(process.env.HOLMES_APPROVAL) : undefined;
+                    }
+                    catch {
+                        env = undefined;
+                    }
+                    const resolved = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString());
+                    if (!resolved)
+                        return { ok: false, code: 'approval-required', reason: 'Entity adoption requires approval for this exact plan.' + (0, approval_queue_1.queueHint)(bound.root, { ...action, why: 'Adopt the configured spec store without changing sealed documents.' }) };
+                    const result = (0, entity_store_1.adoptEntityStore)(context.storeRoot, plan);
+                    if (resolved.source === 'grant' && resolved.approval.nonce)
+                        (0, approval_grants_1.consumeGrantFile)(bound.root, resolved.approval.nonce);
+                    return result;
+                }
+                throw new entity_store_1.EntityStoreError('unsupported-operation', 'Use status, plan-adoption, recovery-plan or explicitly authorized adopt/recover.');
+            }
+            catch (e) {
+                if (e instanceof entity_store_1.EntityStoreError || e instanceof workspace_identity_1.WorkspaceIdentityError)
+                    return { ok: false, code: e.code, reason: e.message };
+                throw e;
+            }
+        },
+    };
+}

package/dist/holmes/mcp/handlers/graph-operations.d.ts

@@ -0,0 +1,90 @@
+import { Spec } from '../../spec/spec-parser';
+import { ScannedFile } from '../../cpg/cpg-scanner';
+import { ChangeSet, ChangeSourceInfo } from '../../project/change-source';
+import { type GraphBasis } from '../../rtm/graph-store';
+export interface GraphOperationsContext {
+    listSpecs(): Promise<Spec[]>;
+    assertStoreReachable(tool: string, root: unknown): void;
+    foreignRootReason(root?: string): string | null;
+    refusal(reason: string): Error;
+    projectRootOf(root: string): string;
+    cachedScan(root: string): ScannedFile[];
+    cacheDirFor(root: string): string;
+    deriveChangedContext(root: string, args: {
+        base?: string;
+        head?: string;
+        since?: string;
+    }, tool: string): Promise<{
+        root: string;
+        changes: ChangeSet;
+        specs: Spec[];
+        scanned: ScannedFile[];
+        bySourcePath: Map<string, ScannedFile>;
+        changeSource: ChangeSourceInfo;
+    }>;
+}
+/** Publish the complete graph for `specs` over `scanned` at the live path (A-SPEC-631 primitive). */
+export declare function publishCurrentGraph(root: string, specs: Spec[], scanned: ScannedFile[]): {
+    basis: GraphBasis;
+    nodes: number;
+    edges: number;
+};
+export type SemanticWarmOutcome = {
+    status: 'discharged';
+    tier: string;
+    computed: number;
+    cached: number;
+} | {
+    status: 'not-applicable';
+    tier: 'none';
+} | {
+    status: 'unavailable';
+    tier: string;
+};
+/**
+ * @implements A-SPEC-478 — the semantic cache WARMING lives in explicit heavy operations, so the
+ * ranking hot path only ever LOOKS UP vectors. Idempotent through the cache. The outcome says
+ * whether there was nothing to do (tier none), whether it happened, or whether a configured tier
+ * could not embed — a discharge must not record the last one as done.
+ */
+export declare function warmSemanticCache(root: string, scanned: readonly ScannedFile[]): Promise<SemanticWarmOutcome>;
+export declare function createGraphOperationsHandlers(context: GraphOperationsContext): {
+    rtm_impact(a: {
+        root: string;
+        changed: string[];
+    }): Promise<{
+        breadthWarning?: string | undefined;
+        rankedImpact: {
+            file: string;
+            score: number;
+        }[];
+        reachedByDepth: number[];
+        bounded: {
+            id: string;
+            reason: "hub" | "depth";
+            inDegree?: number;
+        }[] | undefined;
+        summariesOmitted?: number | undefined;
+        impacted: string[];
+        impactedSummaries: {
+            id: string;
+            summary: string | null;
+        }[];
+    }>;
+    rtm_reindex(a: {
+        root: string;
+        base?: string;
+        head?: string;
+        since?: string;
+    }): Promise<{
+        semanticWarm?: {
+            tier: string;
+            computed: number;
+            cached: number;
+        } | undefined;
+        changed: number;
+        nodes: number;
+        edges: number;
+        changeSource: ChangeSourceInfo;
+    }>;
+};