@holmes-lab/holmes-kit 0.19.6 → 0.20.1

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