@holmes-lab/holmes-kit 0.19.5 → 0.20.0

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 };
+}

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

@@ -0,0 +1,179 @@
+import { EntityByteChange, entityLockOwner } from './entity-transaction';
+import { EntityGitDocuments, EntityGitMergedSources } from './entity-integration';
+import { entitySourcePublicationOwner } from './entity-renumber-transaction';
+import { EntityRenumberEntry } from './entity-renumber';
+export interface EntityIntegrationTransitions {
+    unseal: Array<{
+        entityId: string;
+        displayId: string;
+        documentLocator: string;
+        before: string;
+        after: string;
+    }>;
+    publication: EntityRenumberEntry[];
+    approve: EntityIntegrationTransitions['unseal'];
+    completed: EntityRenumberEntry[];
+}
+/** Produces document transitions only; authority and durable application belong to the executor. */
+export declare function prepareEntityIntegrationTransitions(current: EntityRenumberEntry[], desired: EntityRenumberEntry[], readFile: (file: string) => string | null): EntityIntegrationTransitions;
+export interface EntityIntegrationConflictEvidence {
+    kind: 'entity' | 'source' | 'numbering' | 'document' | 'reference' | 'mirror' | 'destination';
+    /** @implements A-SPEC-637 — the destination path a planned locator collides with (`destination` kind). */
+    existing?: string;
+    entityId?: string;
+    file?: string;
+    reason: string;
+    objects: EntityGitMergedSources['files'][number]['objects'];
+    records?: EntityGitMergedSources['files'][number]['objects'];
+    displayIds?: Record<'base' | 'left' | 'right', string | null> | Record<string, Record<'base' | 'left' | 'right', string | null>>;
+    targets?: Record<'base' | 'left' | 'right', string | null>;
+    reference?: string;
+    entityIds?: string[];
+    target?: string;
+    other?: string;
+}
+export interface EntityIntegrationCandidate {
+    schema: 'holmes-entity-integration-candidate/1';
+    stage: 'candidate';
+    ok: boolean;
+    workspaceId: string;
+    storeId: string;
+    storeLocator: string;
+    commits: Record<'base' | 'left' | 'right', string>;
+    destinationHead: string;
+    indexVersion: string;
+    membershipVersion: string;
+    changes: EntityByteChange[];
+    checks: Array<{
+        locator: string;
+        version: string | null;
+        mode: string | null;
+    }>;
+    conflicts: string[];
+    /** Original Git input objects, not normalized/generated replacement bytes. */
+    conflictEvidence?: EntityIntegrationConflictEvidence[];
+    pending: Array<{
+        file: string;
+        reason: string;
+    }>;
+    /** @implements A-SPEC-637 — non-regular entries identical in every input, left untouched. */
+    excluded?: Array<{
+        file: string;
+        reason: string;
+    }>;
+    approval: EntityGitDocuments['approval'];
+    transitions?: EntityIntegrationTransitions;
+    policyInputs: Array<{
+        locator: string;
+        version: string | null;
+        effectiveVersion: string | null;
+    }>;
+    steps?: EntityIntegrationStep[];
+    /**
+     * @implements A-SPEC-645 — documents this integration renumbers (old display id from the side's
+     * own record, new id from the numbering), present only when non-empty. A side-CREATED document
+     * has a `before: null` mapping step, so this is the only place its old id is known; the audit
+     * records these so evidence consumers can follow the document after the integration.
+     */
+    renumbered?: Array<{
+        entityId: string;
+        oldDisplayId: string;
+        newDisplayId: string;
+    }>;
+}
+export interface EntityIntegrationStep {
+    phase: 'unseal' | 'document' | 'mapping' | 'source' | 'approve';
+    entityId?: string;
+    specId?: string;
+    change: EntityByteChange;
+}
+export interface EntityIntegrationPlan {
+    schema: 'holmes-entity-integration/1';
+    operationId: string;
+    workspaceId: string;
+    storeId: string;
+    storeLocator: string;
+    commits: EntityIntegrationCandidate['commits'];
+    destination: {
+        head: string;
+        indexVersion: string;
+        membershipVersion: string;
+    };
+    configVersion: string | null;
+    checks: EntityIntegrationCandidate['checks'];
+    policyInputs: EntityIntegrationCandidate['policyInputs'];
+    steps: EntityIntegrationStep[];
+}
+/** A closed transport contract. Application must additionally regenerate it from current authorized inputs. */
+export declare function validateEntityIntegrationPlan(value: unknown): EntityIntegrationPlan;
+export declare function entityIntegrationTarget(plan: EntityIntegrationPlan): string;
+/** Internal execution core; the public adapter supplies current authority and durable audit. */
+export declare function applyEntityIntegration(root: string, inspected: unknown, authorize: (specId?: string) => void, audit: (plan: EntityIntegrationPlan, verifyOnly?: boolean, renumbered?: NonNullable<EntityIntegrationCandidate['renumbered']>) => void, beforePublish?: (plan: EntityIntegrationPlan, index: number) => void): Promise<{
+    ok: true;
+    state: 'completed';
+    operationId: string;
+}>;
+/**
+ * @implements A-SPEC-639 — abandon a PENDING integration a third state blocked: claim both dead
+ * generations exactly as recovery does, revert the operation's own publications, preserve every
+ * foreign byte, audit, and retire the operation as abandoned. A completed operation is refused.
+ */
+export declare function abandonEntityIntegration(root: string, inspected: unknown, authorize: () => void, audit: (plan: EntityIntegrationPlan, outcome: {
+    restored: string[];
+    untouched: string[];
+    preserved: string[];
+}) => void): Promise<{
+    ok: true;
+    state: 'abandoned';
+    operationId: string;
+    restored: string[];
+    untouched: string[];
+    preserved: string[];
+}>;
+export declare function recoverEntityIntegration(root: string, inspected: EntityIntegrationRecoveryInspection, authorize: (specId?: string) => void, audit: (plan: EntityIntegrationPlan, verifyOnly?: boolean) => void, beforePublish?: (plan: EntityIntegrationPlan, index: number) => void): Promise<{
+    ok: true;
+    state: 'completed';
+    operationId: string;
+}>;
+export interface EntityIntegrationRecoveryInspection {
+    schema: 'holmes-entity-integration-recovery-inspection/2';
+    state: 'pending' | 'completed';
+    operationId: string;
+    journalVersion: string;
+    completionVersion: string | null;
+    plan: EntityIntegrationPlan;
+    observedPrefixes: number[];
+    conflicts: string[];
+    storeOwner: ReturnType<typeof entityLockOwner>;
+    sourceOwner: ReturnType<typeof entitySourcePublicationOwner>;
+}
+/** Keep the original approval target while binding a lost-response retry to durable completion. */
+export declare function validateEntityIntegrationRecoveryRequest(root: string, inspected: unknown): EntityIntegrationRecoveryInspection;
+/** Observation only; matching bytes do not authorize replay of a journal's program. */
+export declare function inspectEntityIntegrationRecovery(root: string, operationId: string): EntityIntegrationRecoveryInspection;
+/** Re-derive the pending journal program before any recovery writer may use it. */
+export declare function validateEntityIntegrationRecoveryProgram(root: string, operationId: string): Promise<EntityIntegrationRecoveryInspection>;
+/** Executor boundary: a shape-valid plan still needs regeneration and current destination registration. */
+export declare function withValidatedEntityIntegrationPlan<T>(root: string, inspected: unknown, act: (plan: EntityIntegrationPlan, candidate: EntityIntegrationCandidate) => T | Promise<T>): Promise<T>;
+export declare function prepareEntityIntegrationPlan(root: string, revisions: {
+    base: string;
+    left: string;
+    right: string;
+}, storeLocator: string, operationId?: string): Promise<EntityIntegrationPlan>;
+/** Public review keeps the candidate and executable plan within the same owned inspection. */
+export declare function reviewEntityIntegration(root: string, revisions: {
+    base: string;
+    left: string;
+    right: string;
+}, storeLocator: string): Promise<{
+    plan?: EntityIntegrationPlan | undefined;
+    preview: EntityIntegrationCandidate;
+}>;
+/** Internal compilation, not validation or authorization of a caller-supplied execution payload. */
+export declare function compileEntityIntegrationSteps(candidate: EntityIntegrationCandidate): EntityIntegrationStep[];
+/** A reviewable candidate, not an authorized executable journal or a source of replacement authority. */
+export declare function planEntityIntegrationCandidate(root: string, revisions: {
+    base: string;
+    left: string;
+    right: string;
+}, storeLocator: string): Promise<EntityIntegrationCandidate>;