@holmes-lab/holmes-kit 0.19.6 → 0.20.1

package/dist/holmes/mcp/handlers/adoption.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAdoptionHandlers = createAdoptionHandlers;
+const spec_store_1 = require("../../spec/spec-store");
+const validator_1 = require("../../spec/validator");
+const legacy_format_1 = require("../../spec/legacy-format");
+const approval_blockers_1 = require("../../spec/approval-blockers");
+const scan_1 = require("../../reverse/scan");
+const draft_1 = require("../../reverse/draft");
+const anchor_1 = require("../../reverse/anchor");
+function createAdoptionHandlers(context) {
+    return {
+        // @implements A-SPEC-126
+        // Brownfield reverse engineering. Three explicitly-invoked tools, nothing running as a side
+        // effect of an ordinary session, and every write path opt-in: scan writes nothing at all, draft
+        // and anchor are dry-run by DEFAULT.
+        /**
+         * Read-only inventory of a brownfield target: candidate clusters, coverage, and what the scan
+         * could not resolve. Deliberately does NOT call assertRepoTopLevel — a target that is not a git
+         * repository is a supported case here, reported as `isGit: false`.
+         */
+        async reverse_scan(a) {
+            // @implements A-SPEC-189 §10 (round 11) — `reverse_scan`/`reverse_draft` never call
+            // `projectRootOf`, so §7's refusal marker never reached them and their own POINTED sentence
+            // ("<root> is not a directory") arrived at the wire as a raw -32603 fault. A refusal about the
+            // caller's own argument is a refusal wherever it is authored.
+            context.assertReadableRoot('reverse_scan', a.root);
+            // `surfaceByCluster` is drafting evidence, not reading material. On the calibration target it
+            // is 11,460 characters across 15 clusters, and this response enters context on every scan —
+            // paying that to READ what only DRAFTING consumes. `reverse_draft` reads it in-process instead.
+            const { surfaceByCluster: _drafting, ...response } = (0, scan_1.reverseScan)(a.root, { maxFlagged: a.maxFlagged });
+            return response;
+        },
+        /**
+         * Draft H-SPEC/A-SPEC/T-SPEC documents for the recovered clusters under an EXISTING parent REQ.
+         *
+         * The REQ is the human's to write and this tool refuses without one — a requirement states
+         * business intent, which is not in the code. Everything emitted is `status: draft`, and writing
+         * requires an explicit `dryRun: false`.
+         *
+         * WHERE THE DOCUMENTS LAND: in the SERVER's configured spec store (`HOLMES_SPECS`, default
+         * `.ax/specs` relative to the server's working directory) — not inside `root`. In the intended
+         * adoption the two are the same directory, because the server runs inside the target it governs;
+         * pointing `root` at a different repository drafts that repository's slices into THIS store,
+         * which is a governance decision the caller has to make deliberately.
+         */
+        async reverse_draft(a) {
+            context.assertReadableRoot('reverse_draft', a.root);
+            if (typeof a.parentReqId !== 'string' || a.parentReqId.trim() === '') {
+                return {
+                    ok: false,
+                    reason: 'parentReqId is required. A REQ states business intent, which does not exist in the code ' +
+                        'and cannot be recovered from it — write the REQ first, then re-run with its id.',
+                };
+            }
+            const parentReqId = a.parentReqId.trim();
+            const specs = await context.listSpecs();
+            const req = specs.find((s) => s.id === parentReqId);
+            // An unresolvable parent would emit an orphan H-SPEC: a chain that only looks complete.
+            if (!req)
+                return { ok: false, reason: `parent REQ ${parentReqId} was not found in the spec store — create it first` };
+            // @implements A-SPEC-184
+            // A document with no `type:` is not a wrong-kind parent — it is an older-format one, and saying
+            // "is a undefined" left the adopter holding a visible document with nowhere to go. When the type
+            // IS declared, `legacyMessage` returns null and the original wording stands: that path was
+            // already accurate and REQ-184 does not touch it.
+            const formatWhy = (0, legacy_format_1.legacyMessage)(req);
+            if (formatWhy)
+                return { ok: false, reason: formatWhy };
+            if (req.type !== 'REQ')
+                return { ok: false, reason: `${parentReqId} is a ${req.type}; drafts must hang off a REQ` };
+            const report = (0, scan_1.reverseScan)(a.root);
+            // A cluster already drafted is recognised by the `reverse_cluster` key its documents carry, so
+            // re-running over the same tree never duplicates a slice.
+            const alreadyDrafted = new Set(specs.map((s) => s.frontmatter.reverse_cluster).filter((k) => typeof k === 'string'));
+            const selected = a.cluster ? report.clusters.filter((c) => (0, draft_1.clusterKeyOf)(c) === a.cluster) : report.clusters;
+            // A key that matches nothing must not read as success: "drafted 0" is indistinguishable from
+            // "everything was already drafted", so a mistyped key would silently skip the work.
+            if (a.cluster && selected.length === 0) {
+                const keys = report.clusters.map(draft_1.clusterKeyOf);
+                return {
+                    ok: false,
+                    reason: `no cluster matches key "${a.cluster}" — reverse_scan reports ${keys.length} cluster(s)`,
+                    availableClusters: keys.slice(0, 50),
+                };
+            }
+            let base = (0, draft_1.nextIdBase)(specs.map((s) => s.id));
+            const drafted = [];
+            const skipped = [];
+            const refused = [];
+            for (const cluster of selected) {
+                const key = (0, draft_1.clusterKeyOf)(cluster);
+                if (alreadyDrafted.has(key)) {
+                    skipped.push({ clusterKey: key, reason: 'already drafted' });
+                    continue;
+                }
+                const d = (0, draft_1.draftSpecs)(cluster, req.id, String(base), {
+                    surface: report.surfaceByCluster[key] ?? [],
+                    testFiles: cluster.testFiles ?? [],
+                    testsUnmatched: report.coverage.testsUnmatched,
+                });
+                if (!d.ok) {
+                    refused.push({ clusterKey: key, reason: d.reason });
+                    continue;
+                }
+                // Validate BEFORE writing: a draft that fails the project's own validator is not evidence of
+                // anything, and emitting one would put a broken document into the chain.
+                const known = [...specs, ...drafted.flatMap((x) => x.specs), ...d.specs];
+                const resolve = (id) => known.find((s) => s.id === id) ?? null;
+                const errors = d.specs.flatMap((s) => (0, validator_1.validateSpec)(s, resolve).findings.filter((f) => f.level === 'error').map((f) => ({ spec: s.id, ...f })));
+                if (errors.length) {
+                    refused.push({ clusterKey: key, reason: 'drafted documents failed validation', findings: errors });
+                    continue;
+                }
+                drafted.push(d);
+                base++;
+            }
+            const dryRun = a.dryRun !== false; // opt IN to writing
+            // @implements A-SPEC-188 — the minted id sits above every PARSEABLE id, but a file list()
+            // cannot read is invisible to nextIdBase, so its path can collide with a fresh draft. Same
+            // rule as spec_create: a path already occupied is a human's to look at, never overwritten.
+            // The whole cluster moves to `refused` — a partially-written chain only looks complete.
+            // Judged in the DRY RUN too (round-3): a preview that lists a cluster as drafted which the
+            // real run would refuse is a preview that lies.
+            const written = [];
+            for (const d of drafted) {
+                const clash = context.occupiedTarget(d.specs);
+                if (clash) {
+                    refused.push({ clusterKey: d.clusterKey, reason: `초안 목적지(${clash})에 스토어가 읽지 못하는 파일이 이미 있습니다 — 덮어쓰지 않습니다. 사람이 확인해 옮기거나 고친 뒤 다시 실행하십시오.` });
+                    continue;
+                }
+                if (!dryRun) {
+                    try {
+                        for (const s of d.specs)
+                            await context.writeSpec(s);
+                    }
+                    catch (e) {
+                        if (e instanceof spec_store_1.TargetPathOccupiedError) {
+                            refused.push({ clusterKey: d.clusterKey, reason: `초안 목적지(${e.occupiedPath})에 스토어가 읽지 못하는 파일이 이미 있습니다 — 덮어쓰지 않습니다. 사람이 확인해 옮기거나 고친 뒤 다시 실행하십시오.` });
+                            continue;
+                        }
+                        throw e;
+                    }
+                }
+                written.push(d);
+            }
+            // @implements A-SPEC-299
+            // Deliberately NOT changed. This looked like the same false pass as spec_slice_approve, but an
+            // approved store-integrity test pins `ok: true` for a run that refused every cluster because a
+            // destination held an unreadable file: nothing was written, nothing was damaged, and `ok` here
+            // means the call completed without harm. That is a defensible contract, and the case against
+            // it was analogy rather than an observed failure. Evidence beats symmetry.
+            return { ok: true, dryRun, parentReqId: req.id, clusters: report.clusters.length, drafted: written, skipped, refused };
+        },
+        /**
+         * Insert `@implements` anchors into source files. Dry-run by DEFAULT, and anchoring to a
+         * non-approved A-SPEC is refused — a reverse-engineered draft describes code; description does
+         * not confer approval.
+         */
+        async reverse_anchor(a) {
+            const specs = await context.listSpecs();
+            const approved = specs.filter((s) => s.type === 'A-SPEC' && s.status === 'approved').map((s) => s.id);
+            const plan = (0, anchor_1.planAnchors)(a.root, a.mapping ?? [], approved);
+            // @implements A-SPEC-182
+            // The third place the harness refuses over an unapproved A-SPEC. Enriched HERE rather than
+            // inside planAnchors, which is a pure planner holding only the approved-id list — this is the
+            // boundary that has the spec objects, so the planner stays testable without them.
+            const byId = new Map(specs.map((s) => [s.id, s]));
+            // ONE payload per distinct A-SPEC, on a sibling field — not appended to every refused entry.
+            // Review measured the first attempt, which memoized only the COMPUTATION: 149 files mapped to
+            // one draft A-SPEC still concatenated the same 361-character sentence 149 times, 48 KB of pure
+            // duplication in a single tool result. The comment claimed a property the code did not have,
+            // which is how it survived a round of review — hence the size assertion in the test.
+            const blockers = {};
+            for (const r of plan.refused) {
+                if (!/is not approved$/.test(r.reason) || blockers[r.aspec] !== undefined)
+                    continue;
+                const why = (0, approval_blockers_1.blockerSummary)(byId.get(r.aspec), (id) => byId.get(id) ?? null, r.aspec);
+                if (why)
+                    blockers[r.aspec] = why.trim();
+            }
+            const applied = (0, anchor_1.applyAnchors)(a.root, plan.edits, { dryRun: a.dryRun !== false });
+            return { ...plan, ...applied, blockers };
+        },
+    };
+}

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

@@ -0,0 +1,100 @@
+import { type DerivedRebuild } from '../../spec/entity-integration-discharge';
+import { EntityIntegrationPlan } from '../../spec/entity-integration-transaction';
+export type IntegrationSealTransition = {
+    kind: 'spec-unsealed';
+    id: string;
+} | {
+    kind: 'spec-approved';
+    id: string;
+    digest: string;
+};
+/**
+ * @implements A-SPEC-635 — the seal transitions an integration performs, derived from its plan: every
+ * `unseal` step withdraws a seal, every `approve` step issues one whose digest is read from the
+ * published document bytes and must be that document's own `specDigest` (otherwise the seal is not
+ * what the transition policy computed → `audit-conflict`). Through the public tool a forged step is
+ * already refused `plan-changed` by step revalidation; this check is the audit's own invariant.
+ */
+/**
+ * @implements A-SPEC-645
+ * The `entity:`/`old-id:`/`new-id:` inputs for every mapping step whose record changes its display id,
+ * so an integration's renumbers are readable from the ledger like entity_renumber's. Without them the
+ * evidence consumers had no way to follow a document an integration renamed.
+ */
+export declare function renumberedMappingInputs(steps: ReadonlyArray<{
+    phase: string;
+    entityId?: string;
+    change: {
+        locator: string;
+        before: string | null;
+        after: string | null;
+    };
+}>, renames?: ReadonlyArray<{
+    entityId: string;
+    oldDisplayId: string;
+    newDisplayId: string;
+}>): string[];
+export declare function integrationSealTransitions(operation: EntityIntegrationPlan): IntegrationSealTransition[];
+export declare function createEntityIntegrationHandlers(context: {
+    storeRoot?: string;
+    rebuildFor?: (root: string) => DerivedRebuild;
+}): {
+    entity_integrate(a: {
+        root?: string;
+        operation?: string;
+        base?: string;
+        left?: string;
+        right?: string;
+        operationId?: string;
+        plan?: unknown;
+    }): Promise<{
+        ok: true;
+        state: "completed";
+        operationId: string;
+    } | {
+        ok: true;
+        state: "abandoned";
+        operationId: string;
+        restored: string[];
+        untouched: string[];
+        preserved: string[];
+    } | {
+        ok: true;
+        record: import("../../spec/entity-integration-discharge").DerivedDischargeRecord;
+        alreadyDischarged: boolean;
+    } | {
+        ok: boolean;
+        obligations: import("../../spec/entity-integration-discharge").DerivedObligationStatus[];
+        plan?: undefined;
+        target?: undefined;
+        executable?: undefined;
+        code?: undefined;
+        reason?: undefined;
+    } | {
+        ok: boolean;
+        plan: import("../../spec/entity-integration-transaction").EntityIntegrationRecoveryInspection;
+        target: string;
+        executable: boolean;
+        obligations?: undefined;
+        code?: undefined;
+        reason?: undefined;
+    } | {
+        blockers: string[];
+        target?: string | undefined;
+        plan?: EntityIntegrationPlan | undefined;
+        preview: import("../../spec/entity-integration-transaction").EntityIntegrationCandidate;
+        ok: boolean;
+        executable: boolean;
+        obligations?: undefined;
+        code?: undefined;
+        reason?: undefined;
+    } | {
+        ok: boolean;
+        code: string;
+        reason: string;
+        obligations?: undefined;
+        plan?: undefined;
+        target?: undefined;
+        executable?: undefined;
+    }>;
+};

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

@@ -0,0 +1,324 @@
+"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.renumberedMappingInputs = renumberedMappingInputs;
+exports.integrationSealTransitions = integrationSealTransitions;
+exports.createEntityIntegrationHandlers = createEntityIntegrationHandlers;
+// @implements A-SPEC-629
+// @implements A-SPEC-645
+// @implements A-SPEC-642
+// @implements A-SPEC-639
+// @implements A-SPEC-632
+// @implements A-SPEC-635
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const entity_store_1 = require("../../spec/entity-store");
+const root_1 = require("../../project/root");
+const entity_transaction_1 = require("../../spec/entity-transaction");
+const entity_integration_discharge_1 = require("../../spec/entity-integration-discharge");
+const entity_integration_transaction_1 = require("../../spec/entity-integration-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");
+const spec_parser_1 = require("../../spec/spec-parser");
+const spec_digest_1 = require("../../spec/spec-digest");
+/**
+ * @implements A-SPEC-635 — the seal transitions an integration performs, derived from its plan: every
+ * `unseal` step withdraws a seal, every `approve` step issues one whose digest is read from the
+ * published document bytes and must be that document's own `specDigest` (otherwise the seal is not
+ * what the transition policy computed → `audit-conflict`). Through the public tool a forged step is
+ * already refused `plan-changed` by step revalidation; this check is the audit's own invariant.
+ */
+/**
+ * @implements A-SPEC-645
+ * The `entity:`/`old-id:`/`new-id:` inputs for every mapping step whose record changes its display id,
+ * so an integration's renumbers are readable from the ledger like entity_renumber's. Without them the
+ * evidence consumers had no way to follow a document an integration renamed.
+ */
+function renumberedMappingInputs(steps, renames = []) {
+    const out = [];
+    for (const r of renames)
+        for (const input of ['entity:' + r.entityId, 'old-id:' + r.oldDisplayId, 'new-id:' + r.newDisplayId])
+            if (!out.includes(input))
+                out.push(input);
+    const decode = (bytes) => {
+        if (bytes === null)
+            return null;
+        try {
+            const value = JSON.parse(Buffer.from(bytes, 'base64').toString('utf8'));
+            return value && typeof value === 'object' ? value : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    for (const step of steps) {
+        if (step.phase !== 'mapping' || !step.change.locator.startsWith('.ax/entities/records/'))
+            continue;
+        const before = decode(step.change.before), after = decode(step.change.after);
+        if (!before || !after || typeof before.displayId !== 'string' || typeof after.displayId !== 'string' || before.displayId === after.displayId)
+            continue;
+        const entity = step.entityId ?? (typeof after.entityId === 'string' ? after.entityId : undefined);
+        for (const input of [...(entity ? ['entity:' + entity] : []), 'old-id:' + before.displayId, 'new-id:' + after.displayId])
+            if (!out.includes(input))
+                out.push(input);
+    }
+    return out;
+}
+function integrationSealTransitions(operation) {
+    const transitions = [];
+    for (const step of operation.steps) {
+        if (step.phase === 'unseal' && step.specId)
+            transitions.push({ kind: 'spec-unsealed', id: step.specId });
+        else if (step.phase === 'approve' && step.specId) {
+            if (typeof step.change.after !== 'string')
+                throw new entity_store_1.EntityStoreError('audit-conflict', 'Approve step ' + step.specId + ' publishes no document.');
+            let digest, computed;
+            try {
+                const parsed = (0, spec_parser_1.parseSpec)(Buffer.from(step.change.after, 'base64').toString('utf8'));
+                digest = parsed.frontmatter.approved_digest;
+                computed = (0, spec_digest_1.specDigest)(parsed);
+            }
+            catch {
+                throw new entity_store_1.EntityStoreError('audit-conflict', 'Approve step ' + step.specId + ' publishes an unreadable document.');
+            }
+            if (typeof digest !== 'string' || digest !== computed)
+                throw new entity_store_1.EntityStoreError('audit-conflict', 'Approve step ' + step.specId + ' is not sealed by its own digest.');
+            transitions.push({ kind: 'spec-approved', id: step.specId, digest });
+        }
+    }
+    return transitions;
+}
+function createEntityIntegrationHandlers(context) {
+    return {
+        async entity_integrate(a) {
+            try {
+                if (!context.storeRoot)
+                    throw new entity_store_1.EntityStoreError('unsupported-store', 'Git integration 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.');
+                const recoveryTarget = (plan) => 'entity-store:integrate-recover:' + (0, entity_transaction_1.entityContentVersion)(JSON.stringify(plan));
+                const requireStore = (plan) => {
+                    if (plan.storeLocator !== bound.locator)
+                        throw new entity_store_1.EntityStoreError('foreign-store', 'Integration plan differs from the configured store.');
+                };
+                // @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' || a.operation === 'discharge') {
+                    const conflict = (0, ledger_store_1.ledgerConflictReason)(path.join(bound.root, '.ax', 'ledger'));
+                    if (conflict)
+                        throw new entity_store_1.EntityStoreError('ledger-conflict', conflict);
+                }
+                // @implements A-SPEC-632 — replica-local discharge of a completed operation's derived obligations.
+                if (a.operation === 'obligations')
+                    return { ok: true, obligations: (0, entity_integration_discharge_1.inspectDerivedObligations)(bound.root) };
+                if (a.operation === 'discharge') {
+                    if (typeof a.operationId !== 'string')
+                        throw new entity_store_1.EntityStoreError('invalid-request', 'Provide the completed integration operationId.');
+                    if (!context.rebuildFor)
+                        throw new entity_store_1.EntityStoreError('unsupported-store', 'Discharge requires graph and semantic rebuild wiring.');
+                    return await (0, entity_integration_discharge_1.dischargeDerivedObligations)(bound.root, a.operationId, context.rebuildFor(bound.root));
+                }
+                if (a.operation === 'recovery-plan') {
+                    if (typeof a.operationId !== 'string')
+                        throw new entity_store_1.EntityStoreError('invalid-request', 'Provide the integration operationId.');
+                    const plan = (0, entity_integration_transaction_1.inspectEntityIntegrationRecovery)(bound.root, a.operationId);
+                    requireStore(plan.plan);
+                    return { ok: true, plan, target: recoveryTarget(plan), executable: plan.conflicts.length === 0 };
+                }
+                if (a.operation === 'abandon') {
+                    // @implements A-SPEC-639 — an authorized exit for a pending operation a third state blocked.
+                    const id = a.plan?.operationId;
+                    if (typeof id !== 'string')
+                        throw new entity_store_1.EntityStoreError('invalid-request', 'Provide the complete inspected recovery plan to abandon.');
+                    const recovery = (0, entity_integration_transaction_1.validateEntityIntegrationRecoveryRequest)(bound.root, a.plan);
+                    requireStore(recovery.plan);
+                    const target = 'entity-store:integrate-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 integration.' + (0, approval_queue_1.queueHint)(bound.root, { ...action, why: 'Abandon the blocked integration: 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-integration-abandoned' && event.inputs?.includes(ref)))
+                            return;
+                        ledger.append({ ts: new Date().toISOString(), actor: authority.approval.actor, kind: 'entity-integration-abandoned', summary: 'Abandoned Git entity integration ' + operation.operationId,
+                            inputs: [ref, (0, entity_integration_transaction_1.entityIntegrationTarget)(operation), 'workspace:' + operation.workspaceId, 'store:' + operation.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_integration_transaction_1.abandonEntityIntegration)(bound.root, recovery, requireAuthority, audit);
+                }
+                if (a.operation === 'apply' || a.operation === 'recover') {
+                    let recovery;
+                    if (a.operation === 'recover') {
+                        const id = a.plan?.operationId;
+                        if (typeof id !== 'string')
+                            throw new entity_store_1.EntityStoreError('invalid-request', 'Provide the complete inspected recovery plan.');
+                        recovery = (0, entity_integration_transaction_1.validateEntityIntegrationRecoveryRequest)(bound.root, a.plan);
+                    }
+                    const plan = recovery ? recovery.plan : (0, entity_integration_transaction_1.validateEntityIntegrationPlan)(a.plan);
+                    requireStore(plan);
+                    const target = recovery ? recoveryTarget(recovery) : (0, entity_integration_transaction_1.entityIntegrationTarget)(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(), 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 integration.' + (0, approval_queue_1.queueHint)(bound.root, { ...action, why: 'Integrate the exact Git inputs while preserving entity identity and official seal transitions.' }));
+                        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;
+                    };
+                    const bindingFor = (operation) => ['entity-operation:' + operation.operationId, (0, entity_integration_transaction_1.entityIntegrationTarget)(operation), 'workspace:' + operation.workspaceId, 'store:' + operation.storeId,
+                        ...['base', 'left', 'right'].map(side => 'git-' + side + ':' + operation.commits[side])];
+                    const priorGrantUses = (ledger, operation) => {
+                        if (!ledger.verifyAll().ok)
+                            throw new entity_store_1.EntityStoreError('audit-conflict', 'Integration cannot rely on an invalid ledger.');
+                        const binding = bindingFor(operation), refs = new Set();
+                        for (const event of ledger.loadAll().filter(event => event.kind === 'entity-integration-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', 'Integration grant usage has conflicting 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), additional = [...usedGrantRefs].filter(ref => !prior.has(ref));
+                        for (const ref of prior)
+                            usedGrantRefs.add(ref);
+                        if (!additional.length)
+                            return;
+                        ledger.append({ ts: new Date().toISOString(), actor: authority.approval.actor, kind: 'entity-integration-grant-used', summary: 'Recorded grant usage for integration ' + 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 = (operation, verifyOnly = false, renumbered = []) => {
+                        const authority = requireAuthority(), ledger = new ledger_store_1.FileLedgerStore(path.join(bound.root, '.ax/ledger'));
+                        const binding = bindingFor(operation);
+                        for (const ref of priorGrantUses(ledger, operation))
+                            usedGrantRefs.add(ref);
+                        const events = ledger.loadAll(), existing = events.filter(event => event.kind === 'entity-integrated' && event.inputs?.includes(binding[0]));
+                        if (existing.length) {
+                            if (existing.length !== 1 || binding.some(ref => !existing[0].inputs?.includes(ref)))
+                                throw new entity_store_1.EntityStoreError('audit-conflict', 'Integration completion audit has conflicting bindings.');
+                            for (const ref of existing[0].inputs ?? [])
+                                if (ref.startsWith('grant-use:'))
+                                    usedGrantRefs.add(ref);
+                            // Retain the original completion event, but persist any new authority use
+                            // before recovery/verification consumes that grant file.
+                            recordGrantUse(operation);
+                            return;
+                        }
+                        if (verifyOnly)
+                            throw new entity_store_1.EntityStoreError('audit-conflict', 'Completion receipt has no matching integration audit.');
+                        recordGrantUse(operation);
+                        // @implements A-SPEC-635 — the seal history the official acts would have written, attributed
+                        // to the per-spec authority and bound to this operation; skipped when already present so
+                        // recovery after an interrupted audit appends each exactly once.
+                        for (const transition of integrationSealTransitions(operation)) {
+                            if (events.some(event => event.kind === transition.kind && event.inputs?.includes(transition.id) && event.inputs?.includes(binding[0])))
+                                continue;
+                            const sealAuthority = requireAuthority(transition.id);
+                            ledger.append({ ts: new Date().toISOString(), actor: sealAuthority.approval.actor, kind: transition.kind,
+                                summary: transition.kind === 'spec-unsealed' ? 'unsealed ' + transition.id + ' (integration ' + operation.operationId + ')' : 'approved ' + transition.id + ' sealing ' + transition.digest,
+                                inputs: transition.kind === 'spec-unsealed' ? [transition.id, binding[0]] : [transition.id, transition.digest, binding[0]],
+                                rationale: sealAuthority.approval.rationale, authorization: (0, provenance_chain_1.authorizationRef)(sealAuthority.approval.actor, sealAuthority.approval.token) });
+                        }
+                        ledger.append({ ts: new Date().toISOString(), actor: authority.approval.actor, kind: 'entity-integrated', summary: 'Completed Git entity integration ' + operation.operationId,
+                            inputs: [...binding, target, ...new Set(operation.steps.flatMap(step => [
+                                    ...(step.entityId ? ['entity:' + step.entityId] : []), (step.change.after === null ? 'deleted-path:' : 'changed-path:') + step.change.locator
+                                ])),
+                                ...renumberedMappingInputs(operation.steps, renumbered).filter(input => !input.startsWith('entity:')), // A-SPEC-645
+                                'derived-obligations:' + operation.operationId, ...authorities, ...usedGrantRefs],
+                            rationale: authority.approval.rationale, authorization: (0, provenance_chain_1.authorizationRef)(authority.approval.actor, authority.approval.token) });
+                    };
+                    requireAuthority();
+                    const result = recovery ? await (0, entity_integration_transaction_1.recoverEntityIntegration)(bound.root, recovery, requireAuthority, audit, recordGrantUse)
+                        : await (0, entity_integration_transaction_1.applyEntityIntegration)(bound.root, plan, requireAuthority, audit, 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')
+                    throw new entity_store_1.EntityStoreError('unsupported-operation', 'Use plan, apply, recovery-plan, recover, abandon, discharge or obligations.');
+                if (typeof a.base !== 'string' || typeof a.left !== 'string' || typeof a.right !== 'string')
+                    throw new entity_store_1.EntityStoreError('invalid-request', 'Provide base, left and right Git revisions.');
+                const reviewed = await (0, entity_integration_transaction_1.reviewEntityIntegration)(bound.root, { base: a.base, left: a.left, right: a.right }, bound.locator);
+                return { ok: true, executable: !!reviewed.plan, ...reviewed, ...(reviewed.plan ? { target: (0, entity_integration_transaction_1.entityIntegrationTarget)(reviewed.plan) } : {}),
+                    blockers: [...reviewed.preview.conflicts, ...reviewed.preview.pending.map(item => item.file + ': ' + item.reason)] };
+            }
+            catch (error) {
+                if (error instanceof entity_store_1.EntityStoreError)
+                    return { ok: false, code: error.code, reason: error.message };
+                throw error;
+            }
+        },
+    };
+}