@holmes-lab/holmes-kit 0.19.6 → 0.20.1

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

@@ -0,0 +1,216 @@
+import { EntityGitInputs, EntityGitSnapshot } from './entity-git-snapshot';
+import { EntityRenumberProposal } from './entity-renumber';
+type Entity = EntityGitSnapshot['entities'][number];
+export interface EntityGitFileVersion {
+    mode: string;
+    bytes: Buffer;
+}
+export type EntityGitObject = {
+    commit: string;
+    oid: string;
+    mode: string;
+    path: string;
+} | null;
+export type EntityGitSideRecord<T> = Record<'base' | 'left' | 'right', T>;
+/** @implements A-SPEC-636 — a source-level conflict with the immutable per-side objects of the involved path. */
+export interface EntityGitSourceEvidence {
+    kind: 'source';
+    file: string;
+    reason: string;
+    target?: string;
+    other?: string;
+    objects: EntityGitSideRecord<EntityGitObject>;
+}
+/** @implements A-SPEC-636 — an entity-level numbering, document, reference or mirror conflict with per-side facts. */
+export type EntityGitNumberingEvidence = {
+    kind: 'numbering';
+    entityId: string;
+    reason: 'concurrent-display-id';
+    displayIds: EntityGitSideRecord<string | null>;
+} | {
+    kind: 'document';
+    entityId: string;
+    reason: 'unsupported-type' | 'id-mismatch' | 'unsupported-display-id';
+    displayIds: EntityGitSideRecord<string | null>;
+} | {
+    kind: 'reference';
+    entityId: string;
+    reference: string;
+    reason: 'ambiguous' | 'unresolved' | 'deleted-target';
+    targets: EntityGitSideRecord<string | null>;
+} | {
+    kind: 'mirror';
+    entityIds: string[];
+    reason: 'incompatible-mirror-numbers';
+    displayIds: Record<string, EntityGitSideRecord<string | null>>;
+};
+/**
+ * @implements A-SPEC-637 — non-regular entries (symlinks, gitlinks) identical in base, left and right:
+ * excluded from integration and never read as blobs. Anything else non-regular is a refusal.
+ */
+export declare function unchangedNonRegular(inputs: EntityGitInputs): Map<string, string>;
+export interface EntityGitMergedSources {
+    ok: boolean;
+    conflicts: string[];
+    evidence: EntityGitSourceEvidence[];
+    commits: Record<'base' | 'left' | 'right', string>;
+    normalization: EntityGitSources;
+    validation: {
+        diagnostics: Array<{
+            file: string;
+            reason: string;
+        }>;
+        proseCandidates: Array<{
+            file: string;
+            line: number;
+            text: string;
+        }>;
+        anchors: Array<{
+            file: string;
+            displayId: string;
+            entityId: string;
+        }>;
+    };
+    files: Array<{
+        file: string;
+        merge: EntityGitFileMerge;
+        objects: Record<'base' | 'left' | 'right', {
+            commit: string;
+            oid: string;
+            mode: string;
+            path: string;
+        } | null>;
+    }>;
+    excluded: Array<{
+        file: string;
+        reason: string;
+    }>;
+}
+/** Ordinary tracked files only; excluded canonical paths remain obligations of the integration executor. */
+export declare function planEntityGitMergedSources(root: string, revisions: {
+    base: string;
+    left: string;
+    right: string;
+}, storeLocator: string): Promise<EntityGitMergedSources>;
+export interface EntityGitFileMerge {
+    ok: boolean;
+    result: EntityGitFileVersion | null;
+    reason: string;
+    inputs: {
+        base: EntityGitFileVersion | null;
+        left: EntityGitFileVersion | null;
+        right: EntityGitFileVersion | null;
+    };
+}
+/** Merge already-normalized bytes. Scratch files are not a materialized Holmes workspace. */
+/**
+ * @implements A-SPEC-652.6 — the environment `git merge-file` runs in: the caller's GIT_* stripped,
+ * the system and global configs blocked, the ceiling at the scratch parent. The "empty global
+ * config" is `os.devNull` on POSIX; on Windows `os.devNull` is `\\.\nul`, which git cannot open as
+ * a config file (`fatal: unable to access '\\.\nul': Invalid argument`, status 128 — measured
+ * 2026-09-15), so every content merge there was reported as a merge-tool-failure conflict. `NUL`
+ * is the spelling git accepts on that platform.
+ */
+export declare function mergeToolEnv(base: NodeJS.ProcessEnv, scratch: string, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
+export declare function mergeEntityGitFile(base: EntityGitFileVersion | null, left: EntityGitFileVersion | null, right: EntityGitFileVersion | null): EntityGitFileMerge;
+export interface EntityGitSourceBranch {
+    files: Array<{
+        file: string;
+        oid: string;
+        mode: string;
+        before: string;
+        after: string;
+        anchors: Array<{
+            displayId: string;
+            entityId: string;
+            newDisplayId: string;
+            targetDeleted?: true;
+        }>;
+    }>;
+    diagnostics: Array<{
+        file: string;
+        reason: string;
+    }>;
+    proseCandidates: Array<{
+        file: string;
+        line: number;
+        text: string;
+    }>;
+}
+export interface EntityGitSources {
+    ok: boolean;
+    conflicts: string[];
+    evidence?: EntityGitNumberingEvidence[];
+    branches: {
+        base: EntityGitSourceBranch;
+        left: EntityGitSourceBranch;
+        right: EntityGitSourceBranch;
+    };
+}
+/** Branch proposals retain provenance; ordinary three-way source merging and publication follow separately. */
+export declare function planEntityGitSources(root: string, revisions: {
+    base: string;
+    left: string;
+    right: string;
+}, storeLocator: string): Promise<EntityGitSources>;
+export interface EntityGitNumbering {
+    ok: boolean;
+    assignments: Array<{
+        entityId: string;
+        oldDisplayId: string;
+        newDisplayId: string;
+    }>;
+    conflicts: string[];
+    /** @implements A-SPEC-636 — one structured record per conflict string, with per-side facts; present only when refused. */
+    evidence?: EntityGitNumberingEvidence[];
+}
+export interface EntityGitDocuments {
+    ok: boolean;
+    conflicts: string[];
+    evidence?: EntityGitNumberingEvidence[];
+    documents: Array<EntityRenumberProposal['entries'][number] & {
+        source: 'base' | 'left' | 'right';
+        sourceCommit: string;
+    }>;
+    branches?: {
+        base: EntityRenumberProposal;
+        left: EntityRenumberProposal;
+        right: EntityRenumberProposal;
+    };
+    approval?: {
+        targets: Array<{
+            entityId: string;
+            displayId: string;
+            reasons: string[];
+        }>;
+        unsealOrder: string[];
+        approveOrder: string[];
+    };
+}
+/** Keep each original namespace until references have been rewritten; never merge ID maps first. */
+export declare function planEntityGitDocuments(inputs: EntityGitInputs): EntityGitDocuments;
+/** Namespace proposal only: these assignments still need reference rewriting, authorization and publication. */
+export declare function planEntityGitNumbering(inputs: EntityGitInputs): EntityGitNumbering;
+export interface EntityGitClassification {
+    schema: 'holmes-entity-git-classification/1';
+    commits: {
+        base: string;
+        left: string;
+        right: string;
+    };
+    decisions: Array<{
+        entityId: string;
+        outcome: 'unchanged' | 'left' | 'right' | 'equal' | 'deleted' | 'conflict';
+        reason: string;
+        base: Entity | null;
+        left: Entity | null;
+        right: Entity | null;
+    }>;
+    collisions: Array<{
+        displayId: string;
+        entityIds: string[];
+    }>;
+}
+/** Exact remains the default; meaning mode changes comparison, never retained inputs. */
+export declare function classifyEntityGitChanges(inputs: EntityGitInputs, comparison?: 'exact' | 'meaning'): EntityGitClassification;
+export {};