@holmes-lab/holmes-kit 0.19.6 → 0.20.1

package/dist/holmes/spec/approval-status.js

@@ -18,9 +18,12 @@ function describeApproval(spec, resolve) {
             ? { id: pid, status: parent.status, sealed: !!(0, spec_digest_1.sealOf)(parent).approvedDigest, resolved: true }
             : { id: pid, status: 'missing', sealed: false, resolved: false };
     });
-    // An approved spec has, by definition, cleared every blocker; recomputing would only re-report
-    // the placeholder/parent checks against a document that already passed them.
-    const blockers = spec.status === 'approved' ? [] : (0, approval_blockers_1.approvalBlockers)(spec, resolve);
+    // `blockers` keeps its meaning — what stands between this document and its approval — so an
+    // approved document reports none. The same predicate evaluated on the document AS IT STANDS is
+    // what a re-seal would be refused on; a document sealed by hand never passed it, and the acts
+    // that re-seal (renumber, integration, re-approval) judge exactly this list (A-SPEC-641).
+    const resealBlockers = (0, approval_blockers_1.approvalBlockers)(spec, resolve);
+    const blockers = spec.status === 'approved' ? [] : resealBlockers;
     return {
         id: spec.id,
         type: spec.type,
@@ -29,5 +32,6 @@ function describeApproval(spec, resolve) {
         approvedDigest: seal.approvedDigest,
         parents,
         blockers,
+        resealBlockers,
     };
 }

package/dist/holmes/spec/entity-git-snapshot.d.ts

@@ -0,0 +1,50 @@
+export interface EntityGitSnapshot {
+    schema: 'holmes-entity-git-snapshot/1';
+    commit: string;
+    tree: string;
+    workspacePrefix: string;
+    workspaceId: string;
+    storeId: string;
+    storeLocator: string;
+    /** Names occupied outside the selected store; immutable reads always populate this inventory. */
+    otherStoreDisplayIds?: string[];
+    entities: Array<{
+        entityId: string;
+        displayId: string;
+        documentLocator: string;
+        recordLocator: string;
+        documentBlob: string;
+        recordBlob: string;
+        document: string;
+        record: string;
+    }>;
+    files: Array<{
+        path: string;
+        mode: string;
+        oid: string;
+    }>;
+}
+export interface EntityGitInputs {
+    base: EntityGitSnapshot;
+    left: EntityGitSnapshot;
+    right: EntityGitSnapshot;
+}
+/** Version of the workspace-scoped logical stage inventory, not the on-disk index bytes/stat cache. */
+export declare function readEntityGitIndex(root: string): {
+    version: string;
+    entries: Array<{
+        path: string;
+        mode: string;
+        oid: string;
+        stage: number;
+    }>;
+};
+/** Binary-safe object reads; names, paths and replace refs cannot redirect an OID request. */
+export declare function readEntityGitBlobs(root: string, oids: string[]): Map<string, Buffer>;
+export declare function readEntityGitInputs(root: string, revisions: {
+    base: string;
+    left: string;
+    right: string;
+}, storeLocator: string): EntityGitInputs;
+/** Read immutable objects only; dirty files, local identity and Git replace refs are not input truth. */
+export declare function readEntityGitSnapshot(root: string, revision: string, storeLocator: string): EntityGitSnapshot;

package/dist/holmes/spec/entity-git-snapshot.js

@@ -0,0 +1,276 @@
+"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.readEntityGitIndex = readEntityGitIndex;
+exports.readEntityGitBlobs = readEntityGitBlobs;
+exports.readEntityGitInputs = readEntityGitInputs;
+exports.readEntityGitSnapshot = readEntityGitSnapshot;
+// @implements A-SPEC-629.1, A-SPEC-629
+// @implements A-SPEC-636
+// @implements A-SPEC-637
+const fs = __importStar(require("node:fs"));
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const spec_parser_1 = require("./spec-parser");
+const entity_transaction_1 = require("./entity-transaction");
+/** Version of the workspace-scoped logical stage inventory, not the on-disk index bytes/stat cache. */
+function readEntityGitIndex(root) {
+    const git = gitReader(root);
+    const prefix = utf8(git(['rev-parse', '--show-prefix'])).replace(/\n$/, '');
+    if (prefix && (!prefix.endsWith('/') || !locator(prefix.slice(0, -1))))
+        fail('Unsafe workspace prefix.');
+    const bytes = git(['ls-files', '--stage', '-z', '--full-name']);
+    const entries = [];
+    const seen = new Set();
+    for (const entry of utf8(bytes).split('\0')) {
+        if (!entry)
+            continue;
+        const tab = entry.indexOf('\t'), header = entry.slice(0, tab).split(' '), fullPath = entry.slice(tab + 1);
+        if (tab < 0 || header.length !== 3 || !/^[0-7]{6}$/.test(header[0]) || !OID.test(header[1]) || !/^[0-3]$/.test(header[2]) || !locator(fullPath) || !fullPath.startsWith(prefix))
+            fail('Malformed Git index inventory.');
+        const file = fullPath.slice(prefix.length), key = header[2] + ':' + file;
+        if (!locator(file) || seen.has(key))
+            fail('Unsafe or duplicate Git index entry.');
+        seen.add(key);
+        entries.push({ path: file, mode: header[0], oid: header[1], stage: Number(header[2]) });
+    }
+    return { version: 'sha256:' + (0, node_crypto_1.createHash)('sha256').update(prefix).update('\0').update(bytes).digest('hex'), entries };
+}
+/** Binary-safe object reads; names, paths and replace refs cannot redirect an OID request. */
+function readEntityGitBlobs(root, oids) {
+    if (!Array.isArray(oids) || oids.some(oid => typeof oid !== 'string' || !OID.test(oid)))
+        fail('Git blob reads require immutable object OIDs.');
+    const ids = [...new Set(oids)], blobs = new Map();
+    if (!ids.length)
+        return blobs;
+    const output = gitReader(root)(['cat-file', '--batch'], ids.join('\n') + '\n');
+    let offset = 0;
+    for (const oid of ids) {
+        const end = output.indexOf(10, offset);
+        if (end < 0)
+            fail('Truncated Git blob response.');
+        const header = output.subarray(offset, end).toString('ascii').split(' '), size = Number(header[2]);
+        if (header.length !== 3 || header[0] !== oid || header[1] !== 'blob' || !Number.isSafeInteger(size) || size < 0 || end + 1 + size >= output.length || output[end + 1 + size] !== 10)
+            fail('Invalid or missing Git blob response.');
+        blobs.set(oid, output.subarray(end + 1, end + 1 + size));
+        offset = end + size + 2;
+    }
+    if (offset !== output.length)
+        fail('Unexpected trailing Git blob response.');
+    return blobs;
+}
+function readEntityGitInputs(root, revisions, storeLocator) {
+    if (!revisions || typeof revisions !== 'object' || Object.keys(revisions).length !== 3 || !['base', 'left', 'right'].every(key => Object.prototype.hasOwnProperty.call(revisions, key)))
+        fail('Expected exactly base, left and right revisions.');
+    const git = gitReader(root);
+    // Pin all names before loading any tree; subsequent checks never resolve the names again.
+    const commits = { base: resolveCommit(git, revisions.base), left: resolveCommit(git, revisions.left), right: resolveCommit(git, revisions.right) };
+    for (const side of [commits.left, commits.right])
+        git(['merge-base', '--is-ancestor', commits.base, side], undefined, 'Selected base is not a proven ancestor of both Git inputs.');
+    // @implements A-SPEC-636 — a refusal caused by one input names that side and its commit.
+    const sideSnapshot = (side) => {
+        try {
+            return readEntityGitSnapshot(root, commits[side], storeLocator);
+        }
+        catch (error) {
+            if (error instanceof entity_transaction_1.EntityStoreError && error.code === 'invalid-git-snapshot')
+                throw new entity_transaction_1.EntityStoreError('invalid-git-snapshot', side + ' ' + commits[side] + ': ' + error.message);
+            throw error;
+        }
+    };
+    const inputs = { base: sideSnapshot('base'), left: sideSnapshot('left'), right: sideSnapshot('right') };
+    for (const side of [inputs.left, inputs.right]) {
+        if (side.workspaceId !== inputs.base.workspaceId)
+            fail('Git inputs have different canonical workspace identity.');
+        if (side.storeId !== inputs.base.storeId)
+            fail('Git inputs have different canonical store identity.');
+    }
+    return inputs;
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const OID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+function fail(message) { throw new entity_transaction_1.EntityStoreError('invalid-git-snapshot', message); }
+function locator(value) {
+    return typeof value === 'string' && value.length > 0 && !/[\\:\x00]/.test(value) && value.split('/').every(part => part && part !== '.' && part !== '..');
+}
+function uuid(value) { return typeof value === 'string' && UUID.test(value); }
+function object(text, keys) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return fail('Canonical record contains invalid JSON.');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length !== keys.length || keys.some(key => !Object.prototype.hasOwnProperty.call(value, key)))
+        fail('Unsupported canonical record schema or fields.');
+    return value;
+}
+function utf8(bytes) {
+    const text = bytes.toString('utf8');
+    if (!Buffer.from(text, 'utf8').equals(bytes))
+        fail('Unsupported non-UTF-8 canonical bytes or path.');
+    return text;
+}
+function gitReader(root) {
+    const cwd = fs.realpathSync(root);
+    // A caller's Git environment must not redirect a root-bound read to another repository or index.
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+    env.GIT_NO_REPLACE_OBJECTS = '1';
+    env.GIT_OPTIONAL_LOCKS = '0';
+    return (args, input, failure = 'Git snapshot read failed: unavailable revision/object, unsupported repository or 64 MiB response limit.') => {
+        try {
+            return (0, node_child_process_1.execFileSync)('git', ['-C', cwd, ...args], { env, input, maxBuffer: 64 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] });
+        }
+        catch {
+            return fail(failure);
+        }
+    };
+}
+function resolveCommit(git, revision) {
+    if (typeof revision !== 'string' || !revision || /^-/.test(revision) || /[\x00\r\n]/.test(revision))
+        fail('Unsafe Git revision.');
+    const commit = utf8(git(['rev-parse', '--verify', '--end-of-options', revision + '^{commit}'])).trim();
+    if (!OID.test(commit))
+        fail('Git revision did not resolve to a commit object.');
+    return commit;
+}
+/** Read immutable objects only; dirty files, local identity and Git replace refs are not input truth. */
+function readEntityGitSnapshot(root, revision, storeLocator) {
+    if (!locator(storeLocator))
+        fail('Unsafe store locator.');
+    const git = gitReader(root), commit = resolveCommit(git, revision);
+    const tree = utf8(git(['rev-parse', '--verify', '--end-of-options', commit + '^{tree}'])).trim();
+    if (!OID.test(tree))
+        fail('Git commit has no supported tree object.');
+    const workspacePrefix = utf8(git(['rev-parse', '--show-prefix'])).replace(/\n$/, '');
+    if (workspacePrefix && (!workspacePrefix.endsWith('/') || !locator(workspacePrefix.slice(0, -1))))
+        fail('Unsafe workspace prefix.');
+    const files = [];
+    for (const entry of utf8(git(['ls-tree', '-r', '-z', '--full-tree', commit])).split('\0')) {
+        if (!entry)
+            continue;
+        const tab = entry.indexOf('\t'), header = entry.slice(0, tab).split(' '), fullPath = entry.slice(tab + 1);
+        if (tab < 0 || header.length !== 3 || !OID.test(header[2]) || !locator(fullPath))
+            fail('Malformed Git tree inventory.');
+        if (!fullPath.startsWith(workspacePrefix))
+            continue;
+        const file = fullPath.slice(workspacePrefix.length);
+        if (!locator(file))
+            fail('Unsafe workspace file locator.');
+        // @implements A-SPEC-637 — gitlinks enter the inventory (mode 160000) so the planner can exclude or refuse them.
+        const gitlink = header[1] === 'commit' && header[0] === '160000';
+        if (!gitlink && (header[1] !== 'blob' || !['100644', '100755', '120000'].includes(header[0])))
+            fail('Unsupported Git tree object mode: ' + file);
+        files.push({ path: file, mode: header[0], oid: header[2] });
+    }
+    files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    const byPath = new Map(files.map(file => [file.path, file]));
+    if (byPath.size !== files.length)
+        fail('Duplicate Git file inventory.');
+    const regular = (file) => {
+        const entry = byPath.get(file);
+        if (!entry)
+            return fail('Missing canonical document or mapping: ' + file);
+        if (!['100644', '100755'].includes(entry.mode))
+            fail('Canonical document/mapping requires regular mode, not a symlink: ' + file);
+        return entry;
+    };
+    const blobs = new Map();
+    const read = (paths) => {
+        const ids = [...new Set(paths.map(file => regular(file).oid))].filter(oid => !blobs.has(oid));
+        for (const [oid, bytes] of readEntityGitBlobs(root, ids))
+            blobs.set(oid, utf8(bytes));
+    };
+    const text = (file) => {
+        const value = blobs.get(regular(file).oid);
+        if (value === undefined)
+            return fail('Canonical blob was not loaded: ' + file);
+        return value;
+    };
+    const registrations = files.filter(file => /^\.ax\/entities\/stores\/[^/]+\.json$/.test(file.path));
+    const recordFiles = files.filter(file => /^\.ax\/entities\/records\/[^/]+\.json$/.test(file.path));
+    read(['.ax/workspace.json', ...registrations.map(file => file.path), ...recordFiles.map(file => file.path)]);
+    const manifest = object(text('.ax/workspace.json'), ['schema', 'workspaceId']);
+    if (manifest.schema !== 'holmes-workspace/1' || !uuid(manifest.workspaceId))
+        fail('Unsupported canonical workspace identity.');
+    const stores = new Map(), storePaths = new Set();
+    for (const file of registrations) {
+        const registration = object(text(file.path), ['schema', 'workspaceId', 'storeId', 'storeLocator', 'adoptionDigest']);
+        if (registration.schema !== 'holmes-entity-store/1' || registration.workspaceId !== manifest.workspaceId || !uuid(registration.storeId) || file.path !== '.ax/entities/stores/' + registration.storeId + '.json' || !locator(registration.storeLocator) || typeof registration.adoptionDigest !== 'string' || !DIGEST.test(registration.adoptionDigest) || storePaths.has(registration.storeLocator))
+            fail('Invalid or duplicate store registration mapping.');
+        stores.set(registration.storeId, registration.storeLocator);
+        storePaths.add(registration.storeLocator);
+    }
+    const selected = [...stores].find(([, value]) => value === storeLocator);
+    if (!selected)
+        fail('Configured store has no canonical adoption mapping.');
+    const selectedRecords = [];
+    const ids = new Set(), documents = new Set(), otherStoreDisplayIds = new Set();
+    for (const file of recordFiles) {
+        const record = object(text(file.path), ['schema', 'workspaceId', 'storeId', 'entityId', 'displayId', 'documentLocator', 'origin']);
+        const origin = object(JSON.stringify(record.origin), ['kind', 'operationId']);
+        if (record.schema !== 'holmes-entity/1' || record.workspaceId !== manifest.workspaceId || !uuid(record.entityId) || file.path !== '.ax/entities/records/' + record.entityId + '.json' || !uuid(record.storeId) || !stores.has(record.storeId) || typeof record.displayId !== 'string' || !record.displayId || !locator(record.documentLocator) || !record.documentLocator.endsWith('.md') || !['adopted', 'created'].includes(String(origin.kind)) || !uuid(origin.operationId))
+            fail('Invalid entity document mapping.');
+        if (record.storeId !== selected[0]) {
+            otherStoreDisplayIds.add(record.displayId);
+            continue;
+        }
+        if (ids.has(record.displayId) || documents.has(record.documentLocator))
+            fail('Duplicate display ID or document mapping.');
+        ids.add(record.displayId);
+        documents.add(record.documentLocator);
+        selectedRecords.push({ entityId: record.entityId, displayId: record.displayId, documentLocator: record.documentLocator, recordLocator: file.path });
+    }
+    const documentFiles = files.filter(file => file.path.startsWith(storeLocator + '/') && file.path.endsWith('.md'));
+    if (documentFiles.length !== selectedRecords.length || documentFiles.some(file => !documents.has(file.path.slice(storeLocator.length + 1))))
+        fail('Document inventory differs from canonical entity mappings.');
+    read(selectedRecords.map(record => storeLocator + '/' + record.documentLocator));
+    const entities = selectedRecords.map(record => {
+        const documentPath = storeLocator + '/' + record.documentLocator, document = text(documentPath);
+        let parsed;
+        try {
+            parsed = (0, spec_parser_1.parseSpec)(document);
+        }
+        catch {
+            return fail('Unparseable canonical document: ' + documentPath);
+        }
+        if (parsed.id !== record.displayId)
+            fail('Document ID differs from its entity mapping: ' + documentPath);
+        return { ...record, documentBlob: regular(documentPath).oid, recordBlob: regular(record.recordLocator).oid, document, record: text(record.recordLocator) };
+    }).sort((a, b) => a.entityId < b.entityId ? -1 : a.entityId > b.entityId ? 1 : 0);
+    return { schema: 'holmes-entity-git-snapshot/1', commit, tree, workspacePrefix, workspaceId: manifest.workspaceId, storeId: selected[0], storeLocator, entities, files, otherStoreDisplayIds: [...otherStoreDisplayIds].sort() };
+}

package/dist/holmes/spec/entity-integration-discharge.d.ts

@@ -0,0 +1,73 @@
+import type { GraphBasis } from '../rtm/graph-store';
+export declare const DISCHARGE_SCHEMA = "holmes-integration-derived-discharge/1";
+export interface DerivedDischargeRecord {
+    schema: typeof DISCHARGE_SCHEMA;
+    operationId: string;
+    workspaceId: string;
+    storeId: string;
+    /** `entityContentVersion` of the exact `derived.json` bytes this record discharges. */
+    obligationVersion: string;
+    /** The plan's destination commit — what the integration was applied onto. */
+    destinationHead: string;
+    graph: {
+        basis: GraphBasis;
+        nodes: number;
+        edges: number;
+    };
+    semantic: {
+        status: 'discharged';
+        tier: string;
+        computed: number;
+        cached: number;
+    } | {
+        status: 'not-applicable';
+        tier: 'none';
+    };
+    /** Every changed locator of the plan, classified against the current working tree. */
+    changedPaths: {
+        intact: string[];
+        drifted: string[];
+        missing: string[];
+    };
+    dischargedAt: string;
+}
+export interface DerivedObligationStatus {
+    operationId: string;
+    obligationVersion?: string;
+    state: 'pending' | 'discharged' | 'invalid';
+    reason?: string;
+    dischargedAt?: string;
+    graphBasisCommit?: string;
+}
+/** The rebuild paths a discharge runs — injected so this module never reaches into the MCP layer. */
+export interface DerivedRebuild {
+    publishGraph(): Promise<{
+        basis: GraphBasis;
+        nodes: number;
+        edges: number;
+    }>;
+    warmSemantic(): Promise<{
+        status: 'discharged';
+        tier: string;
+        computed: number;
+        cached: number;
+    } | {
+        status: 'not-applicable';
+        tier: 'none';
+    } | {
+        status: 'unavailable';
+        tier: string;
+    }>;
+}
+/** Read-only: every completed operation on this replica that carries derived obligations, and where each stands. */
+export declare function inspectDerivedObligations(root: string): DerivedObligationStatus[];
+/**
+ * Discharge one completed operation's obligations on this replica. Verifies completion and the exact
+ * obligation bytes, rebuilds through the injected paths, verifies the changed paths and publishes one
+ * immutable record; a second writer (or a second call) returns the existing record instead.
+ */
+export declare function dischargeDerivedObligations(root: string, operationId: string, rebuild: DerivedRebuild): Promise<{
+    ok: true;
+    record: DerivedDischargeRecord;
+    alreadyDischarged: boolean;
+}>;

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

@@ -0,0 +1,233 @@
+"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.DISCHARGE_SCHEMA = void 0;
+exports.inspectDerivedObligations = inspectDerivedObligations;
+exports.dischargeDerivedObligations = dischargeDerivedObligations;
+// @implements A-SPEC-632
+/**
+ * Discharge of a completed integration's derived-state obligations.
+ *
+ * `applyEntityIntegration` ends by writing `derived.json` (graph: pending, semantic: pending) into
+ * the operation's completed directory and the completed retry verifies those bytes exactly, so the
+ * obligation itself is immutable history. This module adds the second, immutable half:
+ * `discharge.json` states what was rebuilt, from which basis, and whether the tree still holds the
+ * integration's bytes. The rebuild is not new machinery — the caller injects the graph publication
+ * (REQ-631) and the semantic warming path reindex already uses — so discharge is verification plus
+ * binding. Derived state is replica-local (`.ax/state`), therefore so is the record: nothing under
+ * `.ax/entities`, the specs, the shared ledger or Git is touched.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_util_1 = require("node:util");
+const entity_transaction_1 = require("./entity-transaction");
+const entity_integration_transaction_1 = require("./entity-integration-transaction");
+exports.DISCHARGE_SCHEMA = 'holmes-integration-derived-discharge/1';
+const OBLIGATION_SCHEMA = 'holmes-integration-derived-obligations/1';
+const COMPLETED = '.ax/state/entity-completed';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const RECORD_KEYS = ['schema', 'operationId', 'workspaceId', 'storeId', 'obligationVersion', 'destinationHead', 'graph', 'semantic', 'changedPaths', 'dischargedAt'];
+/** The obligation `applyEntityIntegration` wrote for this plan — the same computation the completed retry verifies. */
+function expectedObligation(plan) {
+    return {
+        schema: OBLIGATION_SCHEMA, operationId: plan.operationId, workspaceId: plan.workspaceId, storeId: plan.storeId,
+        target: (0, entity_integration_transaction_1.entityIntegrationTarget)(plan), graph: 'pending', semantic: 'pending',
+        changedPaths: [...new Set(plan.steps.map((step) => step.change.locator))].sort(),
+    };
+}
+function parseRecord(bytes) {
+    let value;
+    try {
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new entity_transaction_1.EntityStoreError('discharge-conflict', 'The discharge record is not valid JSON.');
+    }
+    const record = value;
+    const shaped = !!record && typeof record === 'object' && !Array.isArray(record)
+        && (0, node_util_1.isDeepStrictEqual)(Object.keys(record).sort(), [...RECORD_KEYS].sort())
+        && record.schema === exports.DISCHARGE_SCHEMA && typeof record.operationId === 'string' && typeof record.obligationVersion === 'string'
+        && typeof record.dischargedAt === 'string' && !!record.graph && typeof record.graph === 'object' && !!record.semantic && typeof record.semantic === 'object'
+        && !!record.changedPaths && typeof record.changedPaths === 'object';
+    if (!shaped)
+        throw new entity_transaction_1.EntityStoreError('discharge-conflict', 'The discharge record has an unknown shape.');
+    return record;
+}
+/** An existing record for this obligation, undefined when absent; a record bound elsewhere is a conflict. */
+function existingRecord(file, operationId, obligationVersion) {
+    const bytes = (0, entity_transaction_1.readEntityBytes)(file);
+    if (!bytes)
+        return undefined;
+    const record = parseRecord(bytes);
+    if (record.operationId !== operationId || record.obligationVersion !== obligationVersion) {
+        throw new entity_transaction_1.EntityStoreError('discharge-conflict', 'An existing discharge record binds a different operation or obligation; preserve it and inspect before retrying.');
+    }
+    return record;
+}
+/** Read-only: every completed operation on this replica that carries derived obligations, and where each stands. */
+function inspectDerivedObligations(root) {
+    let dir;
+    try {
+        dir = (0, entity_transaction_1.entityDirectory)(fs.realpathSync(root), COMPLETED);
+    }
+    catch {
+        return [];
+    }
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((name) => UUID.test(name)).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const operationId of names) {
+        const operation = path.join(dir, operationId);
+        let derivedBytes;
+        try {
+            derivedBytes = (0, entity_transaction_1.readEntityBytes)(path.join(operation, 'derived.json'));
+        }
+        catch {
+            out.push({ operationId, state: 'invalid', reason: 'derived.json is not a readable regular file' });
+            continue;
+        }
+        if (!derivedBytes)
+            continue; // a completed operation without derived obligations is not this module's concern
+        let derived = null;
+        try {
+            derived = JSON.parse(derivedBytes.toString('utf8'));
+        }
+        catch { /* reported below */ }
+        if (!derived || derived.schema !== OBLIGATION_SCHEMA || derived.operationId !== operationId) {
+            out.push({ operationId, state: 'invalid', reason: 'derived.json does not carry this operation\'s obligations' });
+            continue;
+        }
+        const obligationVersion = (0, entity_transaction_1.entityContentVersion)(derivedBytes);
+        try {
+            const record = existingRecord(path.join(operation, 'discharge.json'), operationId, obligationVersion);
+            if (!record)
+                out.push({ operationId, obligationVersion, state: 'pending' });
+            else
+                out.push({ operationId, obligationVersion, state: 'discharged', dischargedAt: record.dischargedAt, graphBasisCommit: record.graph.basis.sourceCommit });
+        }
+        catch (error) {
+            out.push({ operationId, obligationVersion, state: 'invalid', reason: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return out;
+}
+/** Classify every changed locator of the plan against the current tree; the last step for a locator is its final state. */
+function verifyChangedPaths(root, plan) {
+    const final = new Map();
+    for (const step of plan.steps)
+        final.set(step.change.locator, step.change);
+    const result = { intact: [], drifted: [], missing: [] };
+    for (const [locator, change] of [...final.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+        let current;
+        try {
+            current = (0, entity_transaction_1.readEntityBytes)(path.join((0, entity_transaction_1.entityDirectory)(root, path.posix.dirname(locator)), path.posix.basename(locator)));
+        }
+        catch {
+            current = undefined;
+        }
+        if (change.after === null) {
+            (current === undefined ? result.intact : result.drifted).push(locator);
+            continue;
+        }
+        if (current === undefined)
+            result.missing.push(locator);
+        else if (current.equals(Buffer.from(change.after, 'base64')))
+            result.intact.push(locator);
+        else
+            result.drifted.push(locator);
+    }
+    return result;
+}
+/**
+ * Discharge one completed operation's obligations on this replica. Verifies completion and the exact
+ * obligation bytes, rebuilds through the injected paths, verifies the changed paths and publishes one
+ * immutable record; a second writer (or a second call) returns the existing record instead.
+ */
+async function dischargeDerivedObligations(root, operationId, rebuild) {
+    if (!UUID.test(operationId))
+        throw new entity_transaction_1.EntityStoreError('invalid-plan', 'Provide the completed integration operation UUID.');
+    root = fs.realpathSync(root);
+    const observed = (0, entity_integration_transaction_1.inspectEntityIntegrationRecovery)(root, operationId);
+    if (observed.state !== 'completed') {
+        throw new entity_transaction_1.EntityStoreError('discharge-requires-completion', 'Derived obligations are discharged only for a completed integration; recover the pending operation first.');
+    }
+    const plan = observed.plan;
+    const directory = (0, entity_transaction_1.entityDirectory)(root, COMPLETED + '/' + operationId);
+    const derivedBytes = (0, entity_transaction_1.readEntityBytes)(path.join(directory, 'derived.json'));
+    if (!derivedBytes)
+        throw new entity_transaction_1.EntityStoreError('obligation-conflict', 'The completed integration has no derived obligations record.');
+    let derived;
+    try {
+        derived = JSON.parse(derivedBytes.toString('utf8'));
+    }
+    catch {
+        throw new entity_transaction_1.EntityStoreError('obligation-conflict', 'The derived obligations record is not valid JSON.');
+    }
+    if (!(0, node_util_1.isDeepStrictEqual)(derived, expectedObligation(plan))) {
+        throw new entity_transaction_1.EntityStoreError('obligation-conflict', 'Derived obligations differ from the completed plan; the historical record was altered and is preserved as-is.');
+    }
+    const obligationVersion = (0, entity_transaction_1.entityContentVersion)(derivedBytes);
+    const dischargeFile = path.join(directory, 'discharge.json');
+    const existing = existingRecord(dischargeFile, operationId, obligationVersion);
+    if (existing)
+        return { ok: true, record: existing, alreadyDischarged: true };
+    const changedPaths = verifyChangedPaths(root, plan);
+    const graph = await rebuild.publishGraph();
+    const semantic = await rebuild.warmSemantic();
+    if (semantic.status === 'unavailable') {
+        throw new entity_transaction_1.EntityStoreError('semantic-unavailable', `The configured semantic tier (${semantic.tier}) produced no embeddings; the graph was published and the obligation stays pending — retry once the tier is available.`);
+    }
+    const record = {
+        schema: exports.DISCHARGE_SCHEMA, operationId, workspaceId: plan.workspaceId, storeId: plan.storeId, obligationVersion,
+        destinationHead: plan.destination.head, graph, semantic, changedPaths, dischargedAt: new Date().toISOString(),
+    };
+    try {
+        (0, entity_transaction_1.publishEntityRecord)(root, COMPLETED + '/' + operationId + '/discharge.json', JSON.stringify(record));
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        const winner = existingRecord(dischargeFile, operationId, obligationVersion); // a concurrent discharger published first
+        if (!winner)
+            throw error;
+        return { ok: true, record: winner, alreadyDischarged: true };
+    }
+    return { ok: true, record, alreadyDischarged: false };
+}