@nicia-ai/typegraph 0.47.0 → 0.49.0

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

@@ -1,14 +1,15 @@
-import { bf as NodeId, u as NodeType, b6 as JsonValue, aA as EdgeId, d as GraphDef, bg as NodeKinds, aR as GetNodeType, y as GraphBackend, b7 as KindAnnotations, bb as MetaEdge, a5 as EdgeType, aw as DeleteBehavior, T as TemporalMode, I as IndexDeclaration, aX as GraphExtensionVersion, cs as ExtensionNodeDef, ct as ExtensionEdgeDef, cu as ExtensionOntologyRelation, cv as ExtensionIndex } from '../types-DKkMJZjR.cjs';
-export { C as ContributionDiagnostic, a as ContributionDiagnosticState, b as ContributionRepairEntry, c as ContributionRepairResult } from '../types-DKkMJZjR.cjs';
-import { a as Store, aP as Node, ce as UniqueIntrospection } from '../store-CFedKGU5.cjs';
-import { aj as TypeGraphError, ak as TypeGraphErrorOptions } from '../index-CHTv4XMZ.cjs';
+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.cjs';
+export { u as ContributionDiagnostic, v as ContributionDiagnosticState, J as ContributionRepairEntry, K as ContributionRepairResult } from '../types-BqFZTQmV.cjs';
+import { I as IngestionImportTarget } from '../ingestion-import-target-XPxZYw89.cjs';
+import { a as Store, az as IdentityAssertionWriteFacade, aQ as Node, cf as UniqueIntrospection } from '../store-bphCSo7z.cjs';
+import { aj as TypeGraphError, ak as TypeGraphErrorOptions } from '../index-COs_z6nV.cjs';
 import { R as Result } from '../result-DWo6mUVz.cjs';
 export { i as isErr, a as isOk, u as unwrap } from '../result-DWo6mUVz.cjs';
 import { z } from 'zod';
-import '../temporal-Ce1pG0S1.cjs';
-import '../searchable-0Cn_lY8U.cjs';
-import '../manager-DlY1vlla.cjs';
-import '../materialize-indexes-sskhp-c_.cjs';
+import '../temporal-5GqpYCk2.cjs';
+import '../searchable-DHJMh_nj.cjs';
+import '../manager-CYaff3n3.cjs';
+import '../materialize-indexes-DTtAnvfY.cjs';
 
 /**
  * The composite MERGE IDENTITY key for a node: the pair `(kind, id)`.
@@ -200,6 +201,35 @@ 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> = IngestionImportTarget<G> & Readonly<{
+    [INGESTION_BRANCH_BRAND]: true;
+    id: BranchId;
+    base: BaseVersion;
+    nodes: IngestionNodeCollections<G>;
+    edges: Store<G>["edges"];
+    close: () => Promise<void>;
+}> & ("identity" extends keyof Store<G> ? Readonly<{
+    identity: IdentityAssertionWriteFacade<G>;
+}> : Readonly<Record<never, never>>);
+/** 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.
@@ -470,7 +500,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">;
 }>;
 /**
@@ -967,9 +997,11 @@ declare class MatchEvidenceError 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
@@ -1085,6 +1117,27 @@ 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>>;
 
+/**
+ * Constraint-aware working copies for untrusted ingestion.
+ *
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+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).
  *
@@ -1379,7 +1432,7 @@ 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>, branches: readonly GraphBranch<G>[], optionsInput?: MergeOptions<G>): Promise<Result<MergePlanArtifact, MergeError>>;
+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. */
@@ -1408,7 +1461,7 @@ declare function applyMergePlan<G extends GraphDef>(target: Store<G>, input: Mer
  *   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
@@ -1722,4 +1775,4 @@ type KeylessConfig = Readonly<{
     sortFields: readonly string[];
 }>;
 
-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, 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, 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, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, planMerge, planMergeIncremental, 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, IdentityAssertionWriteFacade, IdentityMergeConflictError, type IngestionBranch, IngestionImportTarget, 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 };

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

@@ -1,14 +1,15 @@
-import { bf as NodeId, u as NodeType, b6 as JsonValue, aA as EdgeId, d as GraphDef, bg as NodeKinds, aR as GetNodeType, y as GraphBackend, b7 as KindAnnotations, bb as MetaEdge, a5 as EdgeType, aw as DeleteBehavior, T as TemporalMode, I as IndexDeclaration, aX as GraphExtensionVersion, cs as ExtensionNodeDef, ct as ExtensionEdgeDef, cu as ExtensionOntologyRelation, cv as ExtensionIndex } from '../types-DKkMJZjR.js';
-export { C as ContributionDiagnostic, a as ContributionDiagnosticState, b as ContributionRepairEntry, c as ContributionRepairResult } from '../types-DKkMJZjR.js';
-import { a as Store, aP as Node, ce as UniqueIntrospection } from '../store-5j-w5onJ.js';
-import { aj as TypeGraphError, ak as TypeGraphErrorOptions } from '../index-CzoJ3MUw.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 { I as IngestionImportTarget } from '../ingestion-import-target-dNeL7iAv.js';
+import { a as Store, az as IdentityAssertionWriteFacade, aQ as Node, cf as UniqueIntrospection } from '../store-DRrFCx5x.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-CjO9FH1l.js';
-import '../searchable-D9gMiwcS.js';
-import '../manager-B6sOQzcQ.js';
-import '../materialize-indexes-DQL4xcpf.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)`.
@@ -200,6 +201,35 @@ 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> = IngestionImportTarget<G> & Readonly<{
+    [INGESTION_BRANCH_BRAND]: true;
+    id: BranchId;
+    base: BaseVersion;
+    nodes: IngestionNodeCollections<G>;
+    edges: Store<G>["edges"];
+    close: () => Promise<void>;
+}> & ("identity" extends keyof Store<G> ? Readonly<{
+    identity: IdentityAssertionWriteFacade<G>;
+}> : Readonly<Record<never, never>>);
+/** 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.
@@ -470,7 +500,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">;
 }>;
 /**
@@ -967,9 +997,11 @@ declare class MatchEvidenceError 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
@@ -1085,6 +1117,27 @@ 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>>;
 
+/**
+ * Constraint-aware working copies for untrusted ingestion.
+ *
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+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).
  *
@@ -1379,7 +1432,7 @@ 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>, branches: readonly GraphBranch<G>[], optionsInput?: MergeOptions<G>): Promise<Result<MergePlanArtifact, MergeError>>;
+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. */
@@ -1408,7 +1461,7 @@ declare function applyMergePlan<G extends GraphDef>(target: Store<G>, input: Mer
  *   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
@@ -1722,4 +1775,4 @@ type KeylessConfig = Readonly<{
     sortFields: readonly string[];
 }>;
 
-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, 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, 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, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, planMerge, planMergeIncremental, 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, IdentityAssertionWriteFacade, IdentityMergeConflictError, type IngestionBranch, IngestionImportTarget, 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 };

package/dist/graph-merge/index.js

@@ -1,20 +1,20 @@
-import { createStoreWithSchema } from '../chunk-DJZTXBWY.js';
-import '../chunk-LEWHMOUY.js';
-import { importGraphStream, exportGraphStream, importGraph, exportGraph } from '../chunk-QS3NQZVC.js';
-import '../chunk-SE6EGQSD.js';
-import { storeBackend, storeRuntime, transactionBackend } from '../chunk-FNOMT74T.js';
-import { computeSchemaHash, serializeSchema } from '../chunk-XYBQI6LE.js';
+import { createStoreWithSchema } from '../chunk-BRRP76WO.js';
+import '../chunk-YIURNGXI.js';
+import { importGraphStream, exportGraphStream, importGraph, exportGraph, registerIngestionImportTarget } from '../chunk-LTXQOEIC.js';
+import '../chunk-KF6K7TGH.js';
+import { storeBackend, storeRuntime, transactionBackend } from '../chunk-I4GAZH5Z.js';
+import { computeSchemaHash, serializeSchema } from '../chunk-2TYSSBU5.js';
 import { defineNode } from '../chunk-SHFBB23Q.js';
-import { encodeTupleKey, forceWriteTransactionRevision, normalizeIdentityPair, identityReferenceKey, identityValidityWindowsOverlap, identityAssertionSemanticKey } from '../chunk-NNQ6A3RM.js';
-import { compareStrings, generateId, lockRecordedGraphWrite, readRevisionOrigin, readRecordedClock, forceRecordedGraphRevision, advanceRevisionClock, compareCodePoints } from '../chunk-AVGUJWVX.js';
+import { forceWriteTransactionRevision, normalizeIdentityPair, identityReferenceKey, identityValidityWindowsOverlap, identityAssertionSemanticKey } from '../chunk-ZFMCDJGB.js';
+import { compareStrings, generateId, encodeTupleKey, lockRecordedGraphWrite, readRevisionOrigin, readRecordedClock, forceRecordedGraphRevision, advanceRevisionClock, compareCodePoints } from '../chunk-S5TERQVW.js';
 import { sortedReplacer } from '../chunk-JBQQ7THH.js';
-import '../chunk-NAZ2RA4L.js';
+import { snapshotExportContention } from '../chunk-UGHG7PGX.js';
 import { createSqlSchema } from '../chunk-NVY5CJFP.js';
-import { snapshotExportContention } from '../chunk-SHSSRCFR.js';
+import '../chunk-6LN7FIVU.js';
 import { getNodeKinds, getEdgeKinds, defineInternalGraph } from '../chunk-HEV35TGT.js';
 import { validateEdgeEndpoints, computeUniqueKey } from '../chunk-GLHXM7C4.js';
-import '../chunk-XY5OMOJD.js';
-import { canonicalizeDatabaseTimestamp } from '../chunk-NG2RB5WL.js';
+import '../chunk-DZAICA5J.js';
+import { canonicalizeDatabaseTimestamp } from '../chunk-5K2BKEBD.js';
 import '../chunk-KKBDXCLQ.js';
 import '../chunk-SDBBMD4N.js';
 import '../chunk-P6YLZTRE.js';
@@ -1885,12 +1885,24 @@ function contentComponentOf(version) {
 // src/graph-merge/working-copy.ts
 var CLONE_IMPORT_BATCH_SIZE = 1e3;
 function cloneWorkingCopyStrategy(makeBackend) {
+  return cloneWorkingCopyWithGraphStrategy(
+    makeBackend,
+    (baseStore) => baseStore.graph
+  );
+}
+function cloneIngestionWorkingCopyStrategy(makeBackend) {
+  return cloneWorkingCopyWithGraphStrategy(
+    makeBackend,
+    (baseStore) => graphWithoutNodeUniqueness(baseStore.graph)
+  );
+}
+function cloneWorkingCopyWithGraphStrategy(makeBackend, graphForClone) {
   return {
     create: async (baseStore) => {
       const backend = await makeBackend();
       try {
         const [freshStore] = await createStoreWithSchema(
-          baseStore.graph,
+          graphForClone(baseStore),
           backend,
           {
             // Keep descendants branchable with the same O(1) anchor contract,
@@ -1939,6 +1951,30 @@ function cloneWorkingCopyStrategy(makeBackend) {
     }
   };
 }
+function graphWithoutNodeUniqueness(graph) {
+  const nodes = Object.fromEntries(
+    Object.entries(graph.nodes).map(([name, registration]) => {
+      const { unique: _omitted, ...withoutUnique } = registration;
+      return [name, Object.freeze(withoutUnique)];
+    })
+  );
+  const extension = graph.extension?.nodes === void 0 ? graph.extension : Object.freeze({
+    ...graph.extension,
+    nodes: Object.freeze(
+      Object.fromEntries(
+        Object.entries(graph.extension.nodes).map(([name, node]) => {
+          const { unique: _omitted, ...withoutUnique } = node;
+          return [name, Object.freeze(withoutUnique)];
+        })
+      )
+    )
+  });
+  return Object.freeze({
+    ...graph,
+    nodes: Object.freeze(nodes),
+    extension
+  });
+}
 
 // src/graph-merge/branch.ts
 async function branch(baseStore, makeBackend, options, strategy) {
@@ -1947,7 +1983,7 @@ async function branch(baseStore, makeBackend, options, strategy) {
     const id = options?.id ?? asBranchId(generateId());
     const workingCopyStrategy = strategy ?? cloneWorkingCopyStrategy(makeBackend);
     const store = await workingCopyStrategy.create(baseStore);
-    const schemaAnchor = await readSchemaAnchor(store);
+    const schemaAnchor = await captureBranchSchemaAnchor(store);
     return ok({
       id,
       base,
@@ -1962,7 +1998,7 @@ async function branch(baseStore, makeBackend, options, strategy) {
     );
   }
 }
-async function readSchemaAnchor(store) {
+async function captureBranchSchemaAnchor(store) {
   try {
     const schemaRow = await storeBackend(store).getActiveSchema(store.graphId);
     return schemaRow === void 0 ? void 0 : { version: schemaRow.version, hash: schemaRow.schema_hash };
@@ -1975,6 +2011,76 @@ async function readSchemaAnchor(store) {
   }
 }
 
+// src/graph-merge/ingestion-branch.ts
+var PRIVATE_BRANCHES = /* @__PURE__ */ new WeakMap();
+function createIngestionIdentityFacade(identity) {
+  return Object.freeze({
+    assertSame(a, b, window) {
+      return identity.assertSame(a, b, window);
+    },
+    assertDifferent(a, b, window) {
+      return identity.assertDifferent(a, b, window);
+    },
+    bulkAssertSame(pairs) {
+      return identity.bulkAssertSame(pairs);
+    },
+    bulkAssertDifferent(pairs) {
+      return identity.bulkAssertDifferent(pairs);
+    }
+  });
+}
+async function ingestionBranch(baseStore, makeBackend, options) {
+  try {
+    const created = await branch(
+      baseStore,
+      makeBackend,
+      options,
+      cloneIngestionWorkingCopyStrategy(makeBackend)
+    );
+    if (isErr(created)) {
+      return err(
+        new BranchError("Failed to create constraint-aware ingestion branch", {
+          cause: created.error
+        })
+      );
+    }
+    const privateBranch = created.data;
+    const { base, id, store } = privateBranch;
+    const identityAccess = store.graph.identity === void 0 ? {} : {
+      identity: createIngestionIdentityFacade(
+        store.identity
+      )
+    };
+    const handle = Object.freeze({
+      id,
+      base,
+      nodes: store.nodes,
+      edges: store.edges,
+      ...identityAccess,
+      close: async () => storeBackend(store).close()
+    });
+    PRIVATE_BRANCHES.set(handle, privateBranch);
+    registerIngestionImportTarget(handle, store);
+    return ok(handle);
+  } catch (error) {
+    return err(
+      new BranchError("Failed to create constraint-aware ingestion branch", {
+        cause: error
+      })
+    );
+  }
+}
+function unwrapMergeBranch(input) {
+  const privateBranch = PRIVATE_BRANCHES.get(input);
+  if (privateBranch !== void 0) {
+    return privateBranch;
+  }
+  return input;
+}
+function unwrapMergeBranches(inputs) {
+  return inputs.map((input) => unwrapMergeBranch(input));
+}
+
 // src/graph-merge/blocking.ts
 var UNBLOCKED_BUCKET_KEY = "unblocked";
 var KEY_PART_SEPARATOR = "\0";
@@ -6658,20 +6764,67 @@ function nodeWriteWindowOptions(write) {
     ...write.validTo === void 0 ? {} : { validTo: write.validTo }
   };
 }
-async function applyNodeRows(nodesApi, deletions, upserts) {
-  for (const deletion of deletions) {
-    await nodeCollection(nodesApi, deletion.kind).delete(deletion.id);
-  }
-  const committed = /* @__PURE__ */ new Set();
+async function applyNodeRows(target, txBackend, nodesApi, deletions, upserts) {
+  const afterImages = /* @__PURE__ */ new Map();
+  const upsertsByKind = /* @__PURE__ */ new Map();
   for (const upsert of upserts) {
-    await nodeCollection(nodesApi, upsert.kind).upsertByIdFromRecord(
-      upsert.id,
-      upsert.props,
-      nodeWriteWindowOptions(upsert)
+    const items = upsertsByKind.get(upsert.kind);
+    if (items === void 0) upsertsByKind.set(upsert.kind, [upsert]);
+    else items.push(upsert);
+  }
+  for (const [kind, items] of upsertsByKind) {
+    const currentRows = await nodeCollection(nodesApi, kind).getByIds(
+      items.map((item) => item.id),
+      INCLUDE_TOMBSTONES
     );
-    committed.add(mergeKey(upsert.kind, upsert.id));
+    const currentById = /* @__PURE__ */ new Map();
+    for (const node of currentRows) {
+      if (node !== void 0) currentById.set(node.id, nodeProps2(node));
+    }
+    for (const item of items) {
+      const props = createDataKeyedBag();
+      const unset = new Set(
+        Object.entries(item.props).filter(([, value]) => value === void 0).map(([key]) => key)
+      );
+      for (const [key, value] of Object.entries(
+        currentById.get(item.id) ?? {}
+      )) {
+        if (!unset.has(key)) props[key] = value;
+      }
+      for (const [key, value] of Object.entries(item.props)) {
+        if (value !== void 0) props[key] = value;
+      }
+      afterImages.set(mergeKey(kind, item.id), props);
+    }
   }
-  return committed.size;
+  return storeRuntime(target).applyResolvedNodeUniqueness(
+    txBackend,
+    {
+      upserts: upserts.map((upsert) => ({
+        kind: upsert.kind,
+        id: upsert.id,
+        props: requireDefined(
+          afterImages.get(mergeKey(upsert.kind, upsert.id))
+        )
+      })),
+      releases: deletions
+    },
+    async () => {
+      for (const deletion of deletions) {
+        await nodeCollection(nodesApi, deletion.kind).delete(deletion.id);
+      }
+      const committed = /* @__PURE__ */ new Set();
+      for (const upsert of upserts) {
+        await nodeCollection(nodesApi, upsert.kind).upsertByIdFromRecord(
+          upsert.id,
+          upsert.props,
+          nodeWriteWindowOptions(upsert)
+        );
+        committed.add(mergeKey(upsert.kind, upsert.id));
+      }
+      return committed.size;
+    }
+  );
 }
 async function applyEdgeRows(edgesApi, deletions, upserts) {
   for (const deletion of deletions) {
@@ -6732,7 +6885,13 @@ async function applyInternalMergePlan(plan, nodesApi, edgesApi, target, txBacken
   );
   let committedNodes;
   try {
-    committedNodes = await applyNodeRows(nodesApi, nodeDeletions, nodeUpserts);
+    committedNodes = await applyNodeRows(
+      target,
+      txBackend,
+      nodesApi,
+      nodeDeletions,
+      nodeUpserts
+    );
   } catch (error) {
     throw error instanceof IdentityEndpointValidityError ? translateIdentityCommitError(error) : error;
   }
@@ -7396,7 +7555,8 @@ function incrementalSchemaError() {
     { details: {} }
   );
 }
-async function planMerge(store, branches, optionsInput = {}) {
+async function planMerge(store, branchInputs, optionsInput = {}) {
+  const branches = unwrapMergeBranches(branchInputs);
   const normalized = tryNormalize(optionsInput);
   if (isErr(normalized)) return err(normalized.error);
   const options = normalized.data;
@@ -7437,7 +7597,8 @@ async function planMerge(store, branches, optionsInput = {}) {
   );
 }
 async function planMergeIncremental(args) {
-  const { forkPoint, target, branches } = args;
+  const { forkPoint, target } = args;
+  const branches = unwrapMergeBranches(args.branches);
   const normalized = tryNormalize(args.options ?? {}, ["target"]);
   if (isErr(normalized)) return err(normalized.error);
   const options = normalized.data;
@@ -7878,6 +8039,8 @@ function identityConsistencySeeds(artifact, profile) {
 }
 async function applyWireMergeWrites(target, nodesApi, edgesApi, txBackend, artifact) {
   const committedNodes = await applyNodeRows(
+    target,
+    txBackend,
     nodesApi,
     artifact.writes.nodeDeletes,
     artifact.writes.nodeUpserts.map((upsert) => ({
@@ -8050,7 +8213,8 @@ async function applyMergePlan(target, input) {
     );
   }
 }
-async function merge(store, branches, optionsInput = {}) {
+async function merge(store, branchInputs, optionsInput = {}) {
+  const branches = unwrapMergeBranches(branchInputs);
   const normalized = tryNormalize(optionsInput);
   if (isErr(normalized)) {
     return err(normalized.error);
@@ -8527,7 +8691,8 @@ async function commitIncrementalPlan(target, plan, guard) {
   );
 }
 async function mergeIncremental(args) {
-  const { forkPoint, target, branches } = args;
+  const { forkPoint, target } = args;
+  const branches = unwrapMergeBranches(args.branches);
   const normalized = tryNormalize(args.options ?? {}, ["target"]);
   if (isErr(normalized)) {
     return err(normalized.error);
@@ -8571,6 +8736,6 @@ async function mergeIncremental(args) {
   );
 }
 
-export { BaseVersionMismatchError, BranchError, CandidateSourceError, IdentityMergeConflictError, InvalidMergeOptionsError, InvalidMergePlanError, MERGE_ERROR_CODES, MERGE_OPTION_DEFAULTS, MERGE_PLAN_DIGEST_ALGORITHM, MERGE_PLAN_FORMAT_VERSION, MatchEvidenceError, MergeConflictError, MergeConstraintConflictError, MergeError, MergePlanCapabilityError, MergePlanDigestMismatchError, MergePlanOriginMismatchError, MergePlanSchemaMismatchError, MergePlanTargetMismatchError, MergePlanningStaleError, SimilarityUnavailableError, StaleMergePlanError, UnsupportedMergePlanVersionError, VALIDITY_END_TARGET_PRECEDENCE, applyMergePlan, asBaseVersion, asBranchId, branch, cloneWorkingCopyStrategy, computeBaseVersion, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, planMerge, planMergeIncremental, provenanceGraphId, readProvenance };
+export { BaseVersionMismatchError, BranchError, CandidateSourceError, IdentityMergeConflictError, InvalidMergeOptionsError, InvalidMergePlanError, MERGE_ERROR_CODES, MERGE_OPTION_DEFAULTS, MERGE_PLAN_DIGEST_ALGORITHM, MERGE_PLAN_FORMAT_VERSION, MatchEvidenceError, MergeConflictError, MergeConstraintConflictError, MergeError, MergePlanCapabilityError, MergePlanDigestMismatchError, MergePlanOriginMismatchError, MergePlanSchemaMismatchError, MergePlanTargetMismatchError, MergePlanningStaleError, SimilarityUnavailableError, StaleMergePlanError, UnsupportedMergePlanVersionError, VALIDITY_END_TARGET_PRECEDENCE, applyMergePlan, asBaseVersion, asBranchId, branch, cloneWorkingCopyStrategy, computeBaseVersion, ingestionBranch, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, planMerge, planMergeIncremental, provenanceGraphId, readProvenance };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map