@nicia-ai/typegraph 0.46.2 → 0.48.0

package/dist/graph-merge/index.d.ts

@@ -1,14 +1,139 @@
-import { _ as NodeId, u as NodeType, $ as EdgeId, a0 as JsonValue, d as GraphDef, a1 as NodeKinds, a2 as GetNodeType, y as GraphBackend, a3 as KindAnnotations, a4 as MetaEdge, a5 as EdgeType, a6 as DeleteBehavior, T as TemporalMode, I as IndexDeclaration, a7 as GraphExtensionVersion, a8 as ExtensionNodeDef, a9 as ExtensionEdgeDef, aa as ExtensionOntologyRelation, ab as ExtensionIndex } from '../types-Du78EvpN.js';
-export { C as ContributionDiagnostic, a as ContributionDiagnosticState, b as ContributionRepairEntry, c as ContributionRepairResult } from '../types-Du78EvpN.js';
-import { a as Store, N as Node, m as UniqueIntrospection } from '../store-Bo1psfVZ.js';
-import { T as TypeGraphError, b as TypeGraphErrorOptions } from '../index-Deyu8IXL.js';
+import { dP as NodeId, dg as NodeType, bh as JsonValue, dw as EdgeId, d8 as GraphDef, dQ as NodeKinds, dD as GetNodeType, aM as GraphBackend, bi as KindAnnotations, dN as MetaEdge, dr as EdgeType, S as DeleteBehavior, ce as TemporalMode, I as IndexDeclaration, aQ as GraphExtensionVersion, ak as ExtensionNodeDef, ae as ExtensionEdgeDef, ap as ExtensionOntologyRelation, ai as ExtensionIndex } from '../types-BqFZTQmV.js';
+export { u as ContributionDiagnostic, v as ContributionDiagnosticState, J as ContributionRepairEntry, K as ContributionRepairResult } from '../types-BqFZTQmV.js';
+import { a as Store, aP as Node, ce as UniqueIntrospection } from '../store-UzrGvZOo.js';
+import { aj as TypeGraphError, ak as TypeGraphErrorOptions } from '../index-D7d1u2gr.js';
 import { R as Result } from '../result-DWo6mUVz.js';
 export { i as isErr, a as isOk, u as unwrap } from '../result-DWo6mUVz.js';
 import { z } from 'zod';
-import '../temporal-DPtn0HOu.js';
-import '../searchable-BOUuA83f.js';
-import '../manager-DX983gJ0.js';
-import '../materialize-indexes-CpXoggWU.js';
+import '../temporal-CbnLzTmM.js';
+import '../searchable-bpE1bBfc.js';
+import '../manager-D9eRT_ns.js';
+import '../materialize-indexes-DJ3ykH59.js';
+
+/**
+ * The composite MERGE IDENTITY key for a node: the pair `(kind, id)`.
+ *
+ * TypeGraph node identity is the PAIR `(kind, id)` — a bare id string is NOT unique
+ * on its own (a `Patient` and an `Encounter` may both carry the id "x" as two
+ * DISTINCT committed nodes; ids are caller-supplied). Every place the merge pipeline
+ * groups, clusters, de-dupes, repoints, retypes, or deletes BY NODE IDENTITY must
+ * key on this pair — never the bare id — or two different-kind nodes that happen to
+ * share an id string silently fuse into one cluster (wrong merge, dropped node,
+ * incoherent commit) and the §6.4-A base guard is bypassed.
+ *
+ * Represented as a NUL-joined string (a branded {@link MergeKey}) so it doubles as a
+ * `Map`/`Set` key and a deterministic ordering key. `kind` is a schema identifier
+ * (NUL-free), so the FIRST NUL unambiguously delimits kind from id even when a
+ * caller-supplied id itself contains a NUL byte. This matches the `(kind, id)`
+ * separator the commit-time write guard already uses.
+ *
+ * {@link compareMergeKeys} orders by the bare id FIRST (kind only breaks a same-id
+ * tie), so the merge's "minimum-id survivor" / id-sorted-members semantics are
+ * preserved unchanged for the common single-kind cluster — the composite key changes
+ * WHICH nodes share an identity, never the ordering among genuinely distinct ids.
+ */
+
+/**
+ * A composite `(kind, id)` node-identity key. Branded so it cannot be confused with
+ * a bare {@link NodeId} at the type level — the whole point is that the two are NOT
+ * interchangeable as identities.
+ */
+type MergeKey = string & {
+    readonly __mergeKey: unique symbol;
+};
+
+/** A complete graph-merge node identity. */
+type EntityRef = Readonly<{
+    kind: string;
+    id: NodeId<NodeType>;
+}>;
+/** Structured attribution for one candidate-recall path. */
+type MatchSource = Readonly<{
+    kind: "block";
+    sourceId: string;
+}> | Readonly<{
+    kind: "unique";
+    sourceId: string;
+    constraintName: string;
+}> | Readonly<{
+    kind: "baseUnique";
+    sourceId: string;
+    constraintName: string;
+}> | Readonly<{
+    kind: "baseIndex";
+    sourceId: string;
+    indexName: string;
+}> | Readonly<{
+    kind: "keyless";
+    sourceId: string;
+}> | Readonly<{
+    kind: "retype";
+    sourceId: string;
+}> | Readonly<{
+    kind: "custom";
+    sourceId: string;
+    metadata?: JsonValue | undefined;
+}>;
+/** JSON-safe description of the strategy that actually scored a pair. */
+type MatchStrategy = Readonly<{
+    kind: "fulltext";
+    fields: readonly string[];
+}> | Readonly<{
+    kind: "vector";
+    fields: readonly string[];
+}> | Readonly<{
+    kind: "hybrid";
+    fields: readonly string[];
+    weights: Readonly<{
+        vector: number;
+        fulltext: number;
+    }>;
+}> | Readonly<{
+    kind: "custom";
+}>;
+/** Serializable explanation for one accepted identity edge. */
+type MatchEvidence = Readonly<{
+    a: EntityRef;
+    b: EntityRef;
+    sources: readonly MatchSource[];
+    decision: "definitional";
+}> | Readonly<{
+    a: EntityRef;
+    b: EntityRef;
+    sources: readonly MatchSource[];
+    decision: "scored";
+    strategy: MatchStrategy;
+    score: number;
+    threshold: number;
+}>;
+/** One opt-in scorer observation, retained independently of cluster membership. */
+type CandidateDiagnostic = Readonly<{
+    evidence: Extract<MatchEvidence, Readonly<{
+        decision: "scored";
+    }>>;
+    scoreDecision: "accepted" | "rejected";
+    reason?: "noComparableValues";
+    clusterDisposition?: "retained" | Readonly<{
+        kind: "excluded";
+        reason: "diameter" | "baseAmbiguity";
+    }>;
+}> | Readonly<{
+    evidence: Extract<MatchEvidence, Readonly<{
+        decision: "definitional";
+    }>>;
+    scoreDecision: "accepted";
+    clusterDisposition: Readonly<{
+        kind: "excluded";
+        reason: "diameter" | "baseAmbiguity";
+    }>;
+}>;
+/** Bounded public diagnostic collection assembled by the merge planner. */
+type CandidateDiagnostics = Readonly<{
+    entries: readonly CandidateDiagnostic[];
+    total: number;
+    limit: number;
+    truncated: boolean;
+}>;
 
 /**
  * Core type model for the graph-merge primitive.
@@ -75,6 +200,33 @@ type GraphBranch<G extends GraphDef> = Readonly<{
         hash: string;
     }> | undefined;
 }>;
+declare const INGESTION_BRANCH_BRAND: unique symbol;
+/**
+ * Node collections exposed by an {@link IngestionBranch}. They retain normal
+ * validation, reads, and staging writes, but omit APIs that claim a declared
+ * uniqueness constraint exists on the relaxed physical working copy.
+ */
+type IngestionNodeCollections<G extends GraphDef> = Readonly<{
+    [K in keyof Store<G>["nodes"]]-?: Pick<Store<G>["nodes"][K], "create" | "getById" | "getByIds" | "update" | "updateWhere" | "delete" | "hardDelete" | "find" | "count" | "createFromRecord" | "upsertById" | "upsertByIdFromRecord" | "bulkCreate" | "bulkUpsertById" | "bulkInsert" | "bulkDelete" | "bulkFindByIndex">;
+}>;
+/**
+ * Opaque handle for an untrusted ingestion working copy.
+ *
+ * The ordinary {@link Store} is intentionally absent: callers may stage and
+ * inspect graph data through the typed collections, then pass this handle to
+ * merge planning, but cannot access schema evolution, transactions, or runtime
+ * internals. `close()` releases the private working-copy backend.
+ */
+type IngestionBranch<G extends GraphDef> = Readonly<{
+    [INGESTION_BRANCH_BRAND]: true;
+    id: BranchId;
+    base: BaseVersion;
+    nodes: IngestionNodeCollections<G>;
+    edges: Store<G>["edges"];
+    close: () => Promise<void>;
+}>;
+/** A normal branch or an opaque ingestion branch accepted by merge entrypoints. */
+type MergeBranch<G extends GraphDef> = GraphBranch<G> | IngestionBranch<G>;
 /**
  * Options for {@link GraphBranch} creation. `id` is optional — when omitted a
  * fresh id is generated.
@@ -226,6 +378,15 @@ type DeleteModifyPolicy = "deleteWins" | "modifyWins" | "flag";
  *   and records a report warning.
  */
 type ComparisonCeilingPolicy = "error" | "mergeByIdOnly";
+/**
+ * Opt-in retention policy for candidate-level scoring diagnostics. The limit is
+ * a deterministic global ceiling over the canonically ordered scored pairs;
+ * planning still evaluates candidates according to the normal comparison
+ * ceiling, then retains at most this many accepted/rejected decisions.
+ */
+type CandidateDiagnosticsOptions = Readonly<{
+    limit: number;
+}>;
 /**
  * Ontology type-reconciliation mode. `"off"` is a no-op (default); `"ontology"`
  * collapses compatible types to the most-specific via the public subClassOf
@@ -298,6 +459,11 @@ type MergeOptions<G extends GraphDef = GraphDef> = Readonly<{
     target?: Store<G>;
     /** Safety ceiling on candidate comparisons per kind. Default: unbounded. */
     maxComparisonsPerKind?: number;
+    /**
+     * Retain bounded accepted/rejected scored-pair diagnostics. Omitted by
+     * default so ordinary plans and reports contain only decisive evidence.
+     */
+    candidateDiagnostics?: CandidateDiagnosticsOptions;
     /**
      * Optional single-link diameter guard. When set, clusters whose pairwise
      * distance exceeds it are split by the deterministic drop-weakest rule (T8).
@@ -331,7 +497,7 @@ type MergeOptions<G extends GraphDef = GraphDef> = Readonly<{
 type MergeIncrementalArgs<G extends GraphDef = GraphDef> = Readonly<{
     forkPoint: Store<G>;
     target: Store<G>;
-    branches: readonly GraphBranch<G>[];
+    branches: readonly MergeBranch<G>[];
     options?: Omit<MergeOptions<G>, "target">;
 }>;
 /**
@@ -342,6 +508,8 @@ type EntityResolution = Readonly<{
     memberIds: readonly NodeId<NodeType>[];
     kind: string;
     branchOrigins: readonly BranchId[];
+    /** Deterministic minimal accepted-edge witness for this resolution. */
+    decisiveEdges: readonly MatchEvidence[];
 }>;
 /**
  * One candidate value contributing to a property conflict, tagged by its origin
@@ -384,6 +552,8 @@ type TypeReconciliation = Readonly<{
     entityId: NodeId<NodeType>;
     fromTypes: readonly string[];
     toType: string;
+    /** Accepted ontology-retype witness, when emitted by graph merge. */
+    decisiveEdges?: readonly MatchEvidence[];
 }>;
 /**
  * An item omitted from the merged result (e.g. an edge whose endpoint was
@@ -414,9 +584,9 @@ type DroppedItem = Readonly<{
  */
 declare const VALIDITY_END_TARGET_PRECEDENCE: "target";
 /**
- * One inherited row whose end-of-validity the merge RESOLVED: the instant that
- * stands and every branch that claimed an end for the row (including the ones whose
- * claim lost the least-claim tie-break).
+ * One inherited row whose end-of-validity the merge RESOLVED: the explicit set or
+ * clear that stands and every branch that claimed a change for the row (including
+ * the ones whose claim lost arbitration).
  *
  * `id` is bare because `entity` + `kind` already disambiguate it — a node and an
  * edge, or two kinds, that share an id string are distinct entries.
@@ -425,26 +595,28 @@ type ValidityEndResolution = Readonly<{
     entity: "node" | "edge";
     kind: string;
     id: string;
-    /**
-     * The row's end-of-validity as a canonical UTC ISO 8601 string: the instant the
-     * commit WROTE, or — under {@link VALIDITY_END_TARGET_PRECEDENCE} — the instant
-     * the target already held and the merge left alone.
-     */
-    validTo: string;
-    /** Every branch that claimed an end, sorted; length > 1 means arbitration. */
+    /** Every branch that claimed a change, sorted; length > 1 means arbitration. */
     claimedBy: readonly BranchId[];
     /**
      * Present only as {@link VALIDITY_END_TARGET_PRECEDENCE}, marking an entry the
-     * merge did NOT decide: the incremental target had already moved this end, so
-     * `validTo` is the target's own committed instant, every claim in `claimedBy` was
-     * discarded, and nothing was written or credited for the row.
+     * merge did NOT decide: the incremental target had already changed this end, so
+     * the set/clear fields describe the target's own committed state, every claim in
+     * `claimedBy` was discarded, and nothing was written or credited for the row.
      *
-     * ABSENT means the merge decided the end — `validTo` is the instant it wrote and
-     * `claimedBy` names the claims it arbitrated between. A consumer that ignores the
-     * field therefore keeps reading the entries it always read.
+     * ABSENT means the merge decided the change — `validTo` or `clearValidTo` names
+     * what it wrote and `claimedBy` names the claims it arbitrated between. A consumer
+     * that ignores the field therefore keeps reading the entries it always read.
      */
     precedence?: typeof VALIDITY_END_TARGET_PRECEDENCE;
-}>;
+}> & (Readonly<{
+    /** The canonical instant the merge set, or the target already held. */
+    validTo: string;
+    clearValidTo?: never;
+}> | Readonly<{
+    /** Marks a resolution that reopened the row by clearing its upper bound. */
+    clearValidTo: true;
+    validTo?: never;
+}>);
 /**
  * A `(kind, id)` node identity as surfaced in the merge report. Node identity is the
  * PAIR, never the bare id (a `Doctor` and a `SpecialistDoctor` can share an id string),
@@ -531,8 +703,9 @@ type MergeReport<G extends GraphDef = GraphDef> = Readonly<{
     typeReconciliations: readonly TypeReconciliation[];
     dropped: readonly DroppedItem[];
     /**
-     * Every inherited row whose END-OF-VALIDITY the merge resolved, with the instant
-     * that stands and the branches that claimed an end.
+     * Every inherited row whose END-OF-VALIDITY the merge resolved, with the end
+     * update that stands and the branches that claimed it. A set carries `validTo`;
+     * a reopening carries `clearValidTo: true`.
      *
      * Reported because the resolution is silent by design: two branches ending the
      * same row at different instants are not in conflict (an ending is a monotone
@@ -557,6 +730,8 @@ type MergeReport<G extends GraphDef = GraphDef> = Readonly<{
      * graph still committed). Empty on a clean merge.
      */
     warnings: readonly string[];
+    /** Bounded accepted/rejected scored-pair diagnostics when explicitly enabled. */
+    candidateDiagnostics?: CandidateDiagnostics;
     /**
      * Present only when `persistProvenance` ran and SUCCEEDED: the sidecar provenance
      * graph id and how many `{branch, sourceId}` rows were upserted. Absent when
@@ -638,8 +813,20 @@ declare const MERGE_ERROR_CODES: {
     readonly branch: "GRAPH_MERGE_BRANCH_ERROR";
     readonly similarityUnavailable: "GRAPH_MERGE_SIMILARITY_UNAVAILABLE";
     readonly conflict: "GRAPH_MERGE_CONFLICT";
+    readonly constraintConflict: "GRAPH_MERGE_CONSTRAINT_CONFLICT";
     readonly identityConflict: "GRAPH_MERGE_IDENTITY_CONFLICT";
     readonly baseVersionMismatch: "GRAPH_MERGE_BASE_VERSION_MISMATCH";
+    readonly planCapability: "GRAPH_MERGE_PLAN_CAPABILITY";
+    readonly planInvalid: "GRAPH_MERGE_PLAN_INVALID";
+    readonly planVersionUnsupported: "GRAPH_MERGE_PLAN_VERSION_UNSUPPORTED";
+    readonly planDigestMismatch: "GRAPH_MERGE_PLAN_DIGEST_MISMATCH";
+    readonly planTargetMismatch: "GRAPH_MERGE_PLAN_TARGET_MISMATCH";
+    readonly planSchemaMismatch: "GRAPH_MERGE_PLAN_SCHEMA_MISMATCH";
+    readonly planOriginMismatch: "GRAPH_MERGE_PLAN_ORIGIN_MISMATCH";
+    readonly planStale: "GRAPH_MERGE_PLAN_STALE";
+    readonly planningStale: "GRAPH_MERGE_PLANNING_STALE";
+    readonly candidateSource: "GRAPH_MERGE_CANDIDATE_SOURCE";
+    readonly evidence: "GRAPH_MERGE_EVIDENCE";
 };
 /**
  * Options shared by every merge error. Mirrors the relevant subset of
@@ -690,6 +877,25 @@ declare class MergeConflictError extends MergeError {
     readonly code: "GRAPH_MERGE_CONFLICT";
     constructor(message: string, options?: MergeErrorOptions);
 }
+/** Details copied from the deterministic store constraint that refused commit. */
+type MergeConstraintConflictErrorDetails = Readonly<{
+    /** Stable code of the underlying store constraint error. */
+    constraintCode: string;
+    /** Class name of the underlying store constraint error. */
+    constraintErrorName: string;
+    /** Constraint-specific fields, also copied onto this details object. */
+    constraintDetails: Readonly<Record<string, unknown>>;
+    [key: string]: unknown;
+}>;
+/** Raised when a resolved merge would commit a graph that violates a constraint. */
+declare class MergeConstraintConflictError extends MergeError {
+    protected static readonly errorCategory = "constraint";
+    readonly code: "GRAPH_MERGE_CONSTRAINT_CONFLICT";
+    readonly category: "constraint";
+    readonly cause: TypeGraphError;
+    readonly details: MergeConstraintConflictErrorDetails;
+    constructor(cause: TypeGraphError);
+}
 /** Raised when identity branches contain opposing or retract/reassert truth. */
 declare class IdentityMergeConflictError extends MergeError {
     readonly code: "GRAPH_MERGE_IDENTITY_CONFLICT";
@@ -704,6 +910,63 @@ declare class BaseVersionMismatchError extends MergeError {
     readonly code: "GRAPH_MERGE_BASE_VERSION_MISMATCH";
     constructor(message: string, options?: MergeErrorOptions);
 }
+/** Raised when a target cannot provide the durable plan/apply guarantees. */
+declare class MergePlanCapabilityError extends MergeError {
+    protected static readonly errorCategory = "user";
+    readonly code: "GRAPH_MERGE_PLAN_CAPABILITY";
+    constructor(message: string, options?: MergeErrorOptions);
+}
+/** Raised when a serialized plan is structurally or semantically malformed. */
+declare class InvalidMergePlanError extends MergeError {
+    protected static readonly errorCategory = "user";
+    readonly code: string;
+    constructor(message: string, options?: MergeErrorOptions);
+}
+/** Raised when a plan uses a wire format this library version cannot read. */
+declare class UnsupportedMergePlanVersionError extends InvalidMergePlanError {
+    readonly code: "GRAPH_MERGE_PLAN_VERSION_UNSUPPORTED";
+    constructor(message: string, options?: MergeErrorOptions);
+}
+/** Raised when a plan's canonical content no longer matches its digest. */
+declare class MergePlanDigestMismatchError extends InvalidMergePlanError {
+    readonly code: "GRAPH_MERGE_PLAN_DIGEST_MISMATCH";
+    constructor(message: string, options?: MergeErrorOptions);
+}
+/** Raised when a plan names a different target graph. */
+declare class MergePlanTargetMismatchError extends InvalidMergePlanError {
+    readonly code: "GRAPH_MERGE_PLAN_TARGET_MISMATCH";
+    constructor(message: string, options?: MergeErrorOptions);
+}
+/** Raised when a plan was produced for another active schema. */
+declare class MergePlanSchemaMismatchError extends InvalidMergePlanError {
+    readonly code: "GRAPH_MERGE_PLAN_SCHEMA_MISMATCH";
+    constructor(message: string, options?: MergeErrorOptions);
+}
+/** Raised when a plan belongs to an independently-created revision clock. */
+declare class MergePlanOriginMismatchError extends InvalidMergePlanError {
+    readonly code: "GRAPH_MERGE_PLAN_ORIGIN_MISMATCH";
+    constructor(message: string, options?: MergeErrorOptions);
+}
+/** Raised when the target revision no longer equals the plan's fence. */
+declare class StaleMergePlanError extends MergeError {
+    readonly code: string;
+    constructor(message: string, options?: MergeErrorOptions);
+}
+/** Raised when the target moved while a plan was being computed. */
+declare class MergePlanningStaleError extends StaleMergePlanError {
+    readonly code: "GRAPH_MERGE_PLANNING_STALE";
+    constructor(message: string, options?: MergeErrorOptions);
+}
+/** Raised when a built-in candidate source cannot produce attributed output. */
+declare class CandidateSourceError extends MergeError {
+    readonly code: "GRAPH_MERGE_CANDIDATE_SOURCE";
+    constructor(message: string, options?: MergeErrorOptions);
+}
+/** Raised when match evidence is invalid or contains a non-finite score. */
+declare class MatchEvidenceError extends MergeError {
+    readonly code: "GRAPH_MERGE_EVIDENCE";
+    constructor(message: string, options?: MergeErrorOptions);
+}
 
 /**
  * Pluggable working-copy strategy: how `branch()` produces an isolated,
@@ -731,9 +994,11 @@ declare class BaseVersionMismatchError extends MergeError {
  * `includeTemporal: true` carries `validFrom`/`validTo` through unchanged,
  * preserving the base's exact valid-time window on the clone: create-time
  * paths default an omitted `validFrom` to the row's own creation instant
- * (see #240), and export/import round-trip a still-open-left `valid_from`
- * (e.g. a row that predates the #240 fix) as an explicit `null` rather than
- * silently dropping it — see `InterchangeNodeSchema.validFrom`'s doc.
+ * (see #240) — except for a BORN-ENDED row, whose stated `validTo` at or before
+ * the write instant leaves it with no lower bound at all (see #407) — and
+ * export/import round-trip a still-open-left `valid_from` (a born-ended row, or
+ * one that predates the #240 fix) as an explicit `null` rather than silently
+ * dropping it — see `InterchangeNodeSchema.validFrom`'s doc.
  * Without either half of this, the clone's re-import would re-stamp the
  * affected base rows to the CLONE's creation instant instead — narrowing
  * their validity window and making `asOf` reads on the fork diverge from
@@ -850,36 +1115,25 @@ declare function cloneWorkingCopyStrategy<G extends GraphDef>(makeBackend: MakeB
 declare function branch<G extends GraphDef>(baseStore: GraphBranch<G>["store"], makeBackend: MakeBackend, options?: BranchOptions, strategy?: WorkingCopyStrategy<G>): Promise<Result<GraphBranch<G>, BranchError>>;
 
 /**
- * The composite MERGE IDENTITY key for a node: the pair `(kind, id)`.
+ * Constraint-aware working copies for untrusted ingestion.
  *
- * TypeGraph node identity is the PAIR `(kind, id)` — a bare id string is NOT unique
- * on its own (a `Patient` and an `Encounter` may both carry the id "x" as two
- * DISTINCT committed nodes; ids are caller-supplied). Every place the merge pipeline
- * groups, clusters, de-dupes, repoints, retypes, or deletes BY NODE IDENTITY must
- * key on this pair — never the bare id — or two different-kind nodes that happen to
- * share an id string silently fuse into one cluster (wrong merge, dropped node,
- * incoherent commit) and the §6.4-A base guard is bypassed.
- *
- * Represented as a NUL-joined string (a branded {@link MergeKey}) so it doubles as a
- * `Map`/`Set` key and a deterministic ordering key. `kind` is a schema identifier
- * (NUL-free), so the FIRST NUL unambiguously delimits kind from id even when a
- * caller-supplied id itself contains a NUL byte. This matches the `(kind, id)`
- * separator the commit-time write guard already uses.
- *
- * {@link compareMergeKeys} orders by the bare id FIRST (kind only breaks a same-id
- * tie), so the merge's "minimum-id survivor" / id-sorted-members semantics are
- * preserved unchanged for the common single-kind cluster — the composite key changes
- * WHICH nodes share an identity, never the ordering among genuinely distinct ids.
+ * An ingestion branch persists a mechanically-derived schema with node
+ * uniqueness declarations removed. That lets aliases reach merge planning,
+ * where canonical candidate generation and final resolved-write validation use
+ * the canonical graph's constraints. Every other working-copy constraint stays
+ * active during staging.
  */
 
 /**
- * A composite `(kind, id)` node-identity key. Branded so it cannot be confused with
- * a bare {@link NodeId} at the type level — the whole point is that the two are NOT
- * interchangeable as identities.
+ * Creates an isolated ingestion branch whose node uniqueness constraints are
+ * deferred until the resolved merge write set is applied.
+ *
+ * The returned handle deliberately exposes no ordinary Store. Its typed node
+ * and edge collections are sufficient to stage and inspect incoming data, and
+ * merge entrypoints accept the handle directly. Call `close()` when the working
+ * copy is no longer needed.
  */
-type MergeKey = string & {
-    readonly __mergeKey: unique symbol;
-};
+declare function ingestionBranch<G extends GraphDef>(baseStore: GraphBranch<G>["store"], makeBackend: MakeBackend, options?: BranchOptions): Promise<Result<IngestionBranch<G>, BranchError>>;
 
 /**
  * The shared SCORING stage (design §4, the single match-decision point).
@@ -929,7 +1183,9 @@ type MergeKey = string & {
 type CandidateEdge = Readonly<{
     a: MergeKey;
     b: MergeKey;
+    /** Internal drop-weakest rank. Definitional 1 is never copied to evidence. */
     score: number;
+    evidence: MatchEvidence;
 }>;
 /**
  * An unscored candidate pair a source proposes for scoring: the canonical
@@ -943,8 +1199,241 @@ type CandidatePair<K extends NodeType = NodeType> = Readonly<{
     b: MergeKey;
     left: Node<K>;
     right: Node<K>;
+    sources: readonly MatchSource[];
+}>;
+
+declare const MERGE_PLAN_FORMAT_VERSION: 1;
+declare const MERGE_PLAN_DIGEST_ALGORITHM: "sha256";
+type MergePlanEntityRef = Readonly<{
+    kind: string;
+    id: string;
+}>;
+type MergePlanSchemaFence = Readonly<{
+    managed: boolean;
+    version: number;
+    hash: string;
+}>;
+type MergePlanRevisionFence = Readonly<{
+    origin: string;
+    revision: string | null;
+}>;
+type MergePlanTargetFence = Readonly<{
+    graphId: string;
+    schema: MergePlanSchemaFence;
+    revision: MergePlanRevisionFence;
+}>;
+type MergePlanBranchAnchor = Readonly<{
+    branchId: string;
+    baseVersion: string;
+}>;
+type MergePlanAnchors = Readonly<{
+    kind: "snapshot";
+    base: Readonly<{
+        graphId: string;
+        baseVersion: string;
+    }>;
+    branches: readonly MergePlanBranchAnchor[];
+}> | Readonly<{
+    kind: "incremental";
+    forkPoint: Readonly<{
+        graphId: string;
+        baseVersion: string;
+        schema: MergePlanSchemaFence;
+    }>;
+    branches: readonly MergePlanBranchAnchor[];
+}>;
+type MergePlanNodeDelete = MergePlanEntityRef;
+type MergePlanNodeUpsert = Readonly<{
+    kind: string;
+    id: string;
+    setProps: Readonly<Record<string, JsonValue>>;
+    unsetProps: readonly string[];
+    validFrom?: string | undefined;
+    validTo?: string | undefined;
+}>;
+type MergePlanEdgeDelete = MergePlanEntityRef;
+type MergePlanEdgeUpsert = Readonly<{
+    kind: string;
+    id: string;
+    from: MergePlanEntityRef;
+    to: MergePlanEntityRef;
+    setProps: Readonly<Record<string, JsonValue>>;
+    unsetProps: readonly string[];
+    validFrom?: string | undefined;
+    validTo?: string | undefined;
+}>;
+type MergePlanIdentityAssertion = Readonly<{
+    id: string;
+    relation: "same" | "different";
+    a: MergePlanEntityRef;
+    b: MergePlanEntityRef;
+    validFrom: string;
+    validTo?: string | undefined;
+    endedBy?: MergePlanEntityRef | undefined;
+}>;
+type MergePlanWrites = Readonly<{
+    nodeDeletes: readonly MergePlanNodeDelete[];
+    nodeUpserts: readonly MergePlanNodeUpsert[];
+    edgeDeletes: readonly MergePlanEdgeDelete[];
+    edgeUpserts: readonly MergePlanEdgeUpsert[];
+    identityAssertions: readonly MergePlanIdentityAssertion[];
+    identityRetractions: readonly MergePlanIdentityAssertion[];
+}>;
+type MergePlanProposedSummary = Readonly<{
+    nodes: Readonly<{
+        upserts: number;
+        deletions: number;
+    }>;
+    edges: Readonly<{
+        upserts: number;
+        deletions: number;
+    }>;
+    identity: Readonly<{
+        assertions: number;
+        retractions: number;
+    }>;
+}>;
+type MergePlanCanonicalMapping = Readonly<{
+    member: MergePlanEntityRef;
+    canonical: MergePlanEntityRef;
+}>;
+type MergePlanRetype = Readonly<{
+    entity: MergePlanEntityRef;
+    toKind: string;
+}>;
+type MergePlanGuards = Readonly<{
+    canonicalMappings: readonly MergePlanCanonicalMapping[];
+    retypes: readonly MergePlanRetype[];
+    deletedNodes: readonly MergePlanEntityRef[];
+    incremental?: Readonly<{
+        tombstoneResurrection: "refuse";
+        lossyUpdates: "refuse";
+        edgeIdentity: "preserve";
+    }>;
+}>;
+type MergePlanMatchSource = Readonly<{
+    kind: "block";
+    sourceId: string;
+}> | Readonly<{
+    kind: "unique";
+    sourceId: string;
+    constraintName: string;
+}> | Readonly<{
+    kind: "baseUnique";
+    sourceId: string;
+    constraintName: string;
+}> | Readonly<{
+    kind: "baseIndex";
+    sourceId: string;
+    indexName: string;
+}> | Readonly<{
+    kind: "keyless";
+    sourceId: string;
+}> | Readonly<{
+    kind: "retype";
+    sourceId: string;
+}> | Readonly<{
+    kind: "custom";
+    sourceId: string;
+    metadata?: JsonValue | undefined;
+}>;
+type MergePlanSimilarityStrategy = Readonly<{
+    kind: "fulltext" | "vector";
+    fields: readonly string[];
+}> | Readonly<{
+    kind: "hybrid";
+    fields: readonly string[];
+    weights: Readonly<{
+        vector: number;
+        fulltext: number;
+    }>;
+}> | Readonly<{
+    kind: "custom";
+}>;
+type MergePlanMatchEvidence = Readonly<{
+    a: MergePlanEntityRef;
+    b: MergePlanEntityRef;
+    sources: readonly MergePlanMatchSource[];
+    decision: "definitional";
+}> | Readonly<{
+    a: MergePlanEntityRef;
+    b: MergePlanEntityRef;
+    sources: readonly MergePlanMatchSource[];
+    decision: "scored";
+    strategy: MergePlanSimilarityStrategy;
+    score: number;
+    threshold: number;
+}>;
+type MergePlanEntityResolution = Readonly<{
+    canonicalId: string;
+    memberIds: readonly string[];
+    kind: string;
+    branchOrigins: readonly string[];
+    decisiveEdges: readonly MergePlanMatchEvidence[];
+}>;
+type MergePlanCandidateDiagnostic = Readonly<{
+    evidence: MergePlanMatchEvidence;
+    scoreDecision: "accepted" | "rejected";
+    reason?: "noComparableValues" | undefined;
+    clusterDisposition?: "retained" | Readonly<{
+        kind: "excluded";
+        reason: "diameter" | "baseAmbiguity";
+    }> | undefined;
+}>;
+type MergePlanDiagnostics = Readonly<{
+    entries: readonly MergePlanCandidateDiagnostic[];
+    total: number;
+    limit: number;
+    truncated: boolean;
+}>;
+type MergePlanTypeReconciliation = Readonly<{
+    entityId: string;
+    fromTypes: readonly string[];
+    toType: string;
+    decisiveEdges?: readonly MergePlanMatchEvidence[] | undefined;
+}>;
+type MergePlanReview = Readonly<{
+    resolutions: readonly MergePlanEntityResolution[];
+    conflicts: readonly JsonValue[];
+    deleteModifyConflicts: readonly JsonValue[];
+    typeReconciliations: readonly MergePlanTypeReconciliation[];
+    dropped: readonly JsonValue[];
+    validityEnds: readonly JsonValue[];
+    baseAmbiguities: readonly JsonValue[];
+    provenanceRecords: readonly JsonValue[];
+    warnings: readonly string[];
+    diagnostics?: MergePlanDiagnostics | undefined;
+}>;
+type MergePlanProvenanceOptions = Readonly<{
+    includeInReport: boolean;
+    persist: boolean;
+}>;
+type MergePlanDigest = Readonly<{
+    algorithm: typeof MERGE_PLAN_DIGEST_ALGORITHM;
+    value: string;
+}>;
+type MergePlanArtifactV1 = Readonly<{
+    formatVersion: typeof MERGE_PLAN_FORMAT_VERSION;
+    digest: MergePlanDigest;
+    mode: "snapshot" | "incremental";
+    target: MergePlanTargetFence;
+    anchors: MergePlanAnchors;
+    proposed: MergePlanProposedSummary;
+    writes: MergePlanWrites;
+    guards: MergePlanGuards;
+    review: MergePlanReview;
+    provenance: MergePlanProvenanceOptions;
 }>;
+/** Current public merge-plan artifact type. */
+type MergePlanArtifact = MergePlanArtifactV1;
+type MergePlanArtifactV1Input = Omit<MergePlanArtifactV1, "digest">;
 
+/** Builds a durable, reviewable snapshot merge plan without mutating the target. */
+declare function planMerge<G extends GraphDef>(store: Store<G>, branchInputs: readonly MergeBranch<G>[], optionsInput?: MergeOptions<G>): Promise<Result<MergePlanArtifact, MergeError>>;
+/** Builds a durable, reviewable incremental merge plan without mutating the target. */
+declare function planMergeIncremental<G extends GraphDef>(args: MergeIncrementalArgs<G>): Promise<Result<MergePlanArtifact, MergeError>>;
+/** Validates and atomically applies an approved serialized merge plan. */
+declare function applyMergePlan<G extends GraphDef>(target: Store<G>, input: MergePlanArtifact): Promise<Result<MergeReport<G>, MergeError>>;
 /**
  * Merges a set of branches back into a target store (design §7.2).
  *
@@ -969,7 +1458,7 @@ type CandidatePair<K extends NodeType = NodeType> = Readonly<{
  *   report and committed graph are identical across any permutation.
  * @param optionsInput Caller-facing {@link MergeOptions}; normalized internally.
  */
-declare function merge<G extends GraphDef>(store: Store<G>, branches: readonly GraphBranch<G>[], optionsInput?: MergeOptions<G>): Promise<Result<MergeReport<G>, MergeError>>;
+declare function merge<G extends GraphDef>(store: Store<G>, branchInputs: readonly MergeBranch<G>[], optionsInput?: MergeOptions<G>): Promise<Result<MergeReport<G>, MergeError>>;
 /**
  * Incremental merge — the public fork-point-vs-live-target entry point (design
  * §6.4-B / §6.6). It treats `forkPoint` as the immutable ancestor, folds the live
@@ -1042,6 +1531,7 @@ type NormalizedMergeOptions<G extends GraphDef = GraphDef> = Readonly<{
     target?: MergeOptions<G>["target"];
     maxComparisonsPerKind?: number;
     clusterMaxDiameter?: number;
+    candidateDiagnostics?: CandidateDiagnosticsOptions;
     branchOrder?: readonly BranchId[];
     provenanceWeights?: ReadonlyMap<BranchId, number>;
 }>;
@@ -1196,6 +1686,8 @@ type BaseMember = Readonly<{
     kind: string;
     props: Readonly<Record<string, JsonValue>>;
     origin: "base";
+    validFrom?: string;
+    validTo?: string;
 }>;
 /**
  * What a candidate source emits for one kind: fuzzy `pairs` to score, FORCED
@@ -1280,4 +1772,4 @@ type KeylessConfig = Readonly<{
     sortFields: readonly string[];
 }>;
 
-export { type BaseAmbiguity, type BaseNodeLookup, type BaseVersion, BaseVersionMismatchError, BranchError, type BranchId, type BranchOptions, type BranchProvenance, type CandidateSource, type ComparisonCeilingPolicy, type ConflictingValue, type DeleteModifyConflict, type DeleteModifyPolicy, type DroppedItem, type Embedder, type EntityResolution, type GraphBranch, IdentityMergeConflictError, InvalidMergeOptionsError, type KeylessConfig, MERGE_ERROR_CODES, MERGE_OPTION_DEFAULTS, type MakeBackend, MergeConflictError, MergeError, type MergeIncrementalArgs, type MergeOptions, type MergeReport, type MergedCounts, type NormalizedMergeOptions, type PropertyConflict, type PropertyConflictPolicy, type ProvenanceGraph, type ProvenanceIndex, type ProvenanceNode, type ProvenanceQuery, type ProvenanceRecord, type ReconcileTypesMode, type ResolveConfig, type ResolveMap, type ResolvedCluster, Result, type SimilarityStrategy, SimilarityUnavailableError, type SourceScope, type TypeReconciliation, VALIDITY_END_TARGET_PRECEDENCE, type ValidityEndResolution, type WorkingCopyStrategy, asBaseVersion, asBranchId, branch, cloneWorkingCopyStrategy, computeBaseVersion, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, provenanceGraphId, readProvenance };
+export { type BaseAmbiguity, type BaseNodeLookup, type BaseVersion, BaseVersionMismatchError, BranchError, type BranchId, type BranchOptions, type BranchProvenance, type CandidateDiagnostic, type CandidateDiagnostics, type CandidateDiagnosticsOptions, type CandidateSource, CandidateSourceError, type ComparisonCeilingPolicy, type ConflictingValue, type DeleteModifyConflict, type DeleteModifyPolicy, type DroppedItem, type Embedder, type EntityRef, type EntityResolution, type GraphBranch, IdentityMergeConflictError, type IngestionBranch, type IngestionNodeCollections, InvalidMergeOptionsError, InvalidMergePlanError, type KeylessConfig, MERGE_ERROR_CODES, MERGE_OPTION_DEFAULTS, MERGE_PLAN_DIGEST_ALGORITHM, MERGE_PLAN_FORMAT_VERSION, type MakeBackend, type MatchEvidence, MatchEvidenceError, type MatchSource, type MatchStrategy, type MergeBranch, MergeConflictError, MergeConstraintConflictError, type MergeConstraintConflictErrorDetails, MergeError, type MergeIncrementalArgs, type MergeOptions, type MergePlanAnchors, type MergePlanArtifact, type MergePlanArtifactV1, type MergePlanArtifactV1Input, type MergePlanBranchAnchor, type MergePlanCandidateDiagnostic, type MergePlanCanonicalMapping, MergePlanCapabilityError, type MergePlanDiagnostics, type MergePlanDigest, MergePlanDigestMismatchError, type MergePlanEdgeDelete, type MergePlanEdgeUpsert, type MergePlanEntityRef, type MergePlanEntityResolution, type MergePlanGuards, type MergePlanIdentityAssertion, type MergePlanMatchEvidence, type MergePlanMatchSource, type MergePlanNodeDelete, type MergePlanNodeUpsert, MergePlanOriginMismatchError, type MergePlanProposedSummary, type MergePlanProvenanceOptions, type MergePlanRetype, type MergePlanReview, type MergePlanRevisionFence, type MergePlanSchemaFence, MergePlanSchemaMismatchError, type MergePlanSimilarityStrategy, type MergePlanTargetFence, MergePlanTargetMismatchError, type MergePlanTypeReconciliation, type MergePlanWrites, MergePlanningStaleError, type MergeReport, type MergedCounts, type NormalizedMergeOptions, type PropertyConflict, type PropertyConflictPolicy, type ProvenanceGraph, type ProvenanceIndex, type ProvenanceNode, type ProvenanceQuery, type ProvenanceRecord, type ReconcileTypesMode, type ResolveConfig, type ResolveMap, type ResolvedCluster, Result, type SimilarityStrategy, SimilarityUnavailableError, type SourceScope, StaleMergePlanError, type TypeReconciliation, UnsupportedMergePlanVersionError, VALIDITY_END_TARGET_PRECEDENCE, type ValidityEndResolution, type WorkingCopyStrategy, applyMergePlan, asBaseVersion, asBranchId, branch, cloneWorkingCopyStrategy, computeBaseVersion, ingestionBranch, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, planMerge, planMergeIncremental, provenanceGraphId, readProvenance };