@nicia-ai/typegraph 0.30.0 → 0.32.0

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

@@ -0,0 +1,1191 @@
+import { G as GraphDef, t as NodeKinds, u as GetNodeType } from '../manager-aVgxbGt-.cjs';
+import { S as Store, N as Node, U as UniqueIntrospection } from '../store-view-lTcb_cnp.cjs';
+import { d as NodeId, N as NodeType, e as EdgeId, J as JsonValue, f as KindAnnotations, g as EdgeType, D as DeleteBehavior, T as TemporalMode, h as GraphExtensionVersion, i as ExtensionNodeDef, j as ExtensionEdgeDef, k as ExtensionOntologyRelation, l as ExtensionIndex } from '../extension-types-D1k0inWU.cjs';
+import { T as TypeGraphError } from '../index-C8sSTErx.cjs';
+import { R as Result } from '../result-DWo6mUVz.cjs';
+export { i as isErr, a as isOk, u as unwrap } from '../result-DWo6mUVz.cjs';
+import { G as GraphBackend, M as MetaEdge, I as IndexDeclaration } from '../types-Dvmn-eal.cjs';
+import { z } from 'zod';
+import 'drizzle-orm';
+import '../materialize-indexes-DEYkU-wr.cjs';
+import 'drizzle-orm/pg-core';
+import 'drizzle-orm/sqlite-core';
+
+/**
+ * Core type model for the graph-merge primitive.
+ *
+ * Finalized against TypeGraph's real generic machinery: the design's illustrative
+ * `Node<G, K>` / `NodeId<NodeKinds<G>>` collapse onto TypeGraph's public
+ * `Node` / `Edge` / `NodeId<NodeType>` / `EdgeId` (which are themselves branded
+ * over `NodeType` / `EdgeType`). The merge surface is parameterized over
+ * `G extends GraphDef` so `Store<G>` and `GraphBranch<G>` thread the caller's
+ * concrete graph definition end-to-end.
+ *
+ * This module is pure type declarations plus the two branding helpers — no
+ * runtime merge logic.
+ */
+
+/**
+ * Opaque identifier for a branch (working copy) of a base store. Branded so a
+ * raw string cannot be passed where a deliberately-minted branch id is required.
+ */
+type BranchId = string & Readonly<{
+    readonly __brand: "BranchId";
+}>;
+/**
+ * Opaque token identifying the immutable `base@V` a branch was forked from.
+ * Combines a schema hash with a content fingerprint (computed in T3). Branded so
+ * it cannot be confused with an arbitrary string.
+ */
+type BaseVersion = string & Readonly<{
+    readonly __brand: "BaseVersion";
+}>;
+/**
+ * Mints a {@link BranchId} from a raw string. Centralizes the brand cast so the
+ * unsafe assertion lives in exactly one place.
+ */
+declare function asBranchId(value: string): BranchId;
+/**
+ * Mints a {@link BaseVersion} from a raw string. Centralizes the brand cast so
+ * the unsafe assertion lives in exactly one place.
+ */
+declare function asBaseVersion(value: string): BaseVersion;
+/**
+ * A working-copy handle for one branch: its id, the `base@V` it forked from, and
+ * a {@link Store} over the branch's own backend.
+ */
+type GraphBranch<G extends GraphDef> = Readonly<{
+    id: BranchId;
+    base: BaseVersion;
+    store: Store<G>;
+}>;
+/**
+ * Options for {@link GraphBranch} creation. `id` is optional — when omitted a
+ * fresh id is generated.
+ */
+type BranchOptions = Readonly<{
+    id?: BranchId;
+}>;
+/**
+ * Turns text into an embedding vector. Injected via {@link MergeOptions.embedder}
+ * and used by the `vector` / `hybrid` similarity strategies to score candidate
+ * pairs by cosine IN MEMORY — the staged candidate nodes are unindexed in the
+ * working copy, so a backend ANN index cannot score them pairwise (see
+ * `scorePair`). Exact in-memory cosine over real model vectors is both the right
+ * scale for bounded candidate dedup and deterministic, which the merge contract
+ * requires.
+ *
+ * Batched and async: given N texts it returns N vectors in the SAME order, each a
+ * fixed-dimension `Float32Array` (every vector a given embedder returns shares one
+ * length — the model's embedding dimension). The function MUST be deterministic —
+ * the same text always yields the same vector — because the whole merge is
+ * order-independent and reproducible. Vectors need NOT be pre-normalized; cosine
+ * scoring normalizes internally.
+ *
+ * The concrete local model lives in the CONSUMER (the harness ships an
+ * all-MiniLM-L6-v2 embedder); this package depends only on the function shape, so
+ * it stays model-agnostic and lean inside the TypeGraph core package.
+ */
+type Embedder = (texts: readonly string[]) => Promise<readonly Float32Array[]>;
+/**
+ * Pluggable per-kind similarity strategy (design §8).
+ *
+ * - `vector` / `hybrid` score candidate pairs by cosine over an injected
+ *   {@link Embedder} ({@link MergeOptions.embedder}), computed in memory; they
+ *   fail with `SimilarityUnavailableError` when no embedder is configured.
+ * - `fulltext` and `custom` run with ZERO embeddings — the cross-DB-safe
+ *   default. `fulltext` uses an in-memory Sørensen–Dice trigram scorer (T6).
+ *
+ * The generic mirrors the design's `SimilarityStrategy<G, K>`: `K` constrains the
+ * `custom` score function's node arguments to the resolved kind.
+ */
+type SimilarityStrategy<G extends GraphDef = GraphDef, K extends NodeType = NodeType> = Readonly<{
+    kind: "hybrid";
+    fields: readonly string[];
+    weights?: Readonly<{
+        vector?: number;
+        fulltext?: number;
+    }>;
+    readonly __graph?: G;
+}> | Readonly<{
+    kind: "vector";
+    field: string;
+    readonly __graph?: G;
+}> | Readonly<{
+    kind: "fulltext";
+    fields: readonly string[];
+    readonly __graph?: G;
+}> | Readonly<{
+    kind: "custom";
+    score: (a: Node<K>, b: Node<K>) => number;
+    readonly __graph?: G;
+}>;
+/**
+ * Per-kind entity-resolution configuration.
+ */
+type ResolveConfig<G extends GraphDef = GraphDef, K extends NodeType = NodeType> = Readonly<{
+    /**
+     * Cheap exact-equality blocking key, evaluated before similarity to bound the
+     * O(n²) candidate comparisons. Returning `undefined` places the node in the
+     * shared `"unblocked"` bucket (compared all-vs-all within its kind).
+     *
+     * STAGED-vs-staged only: it is an arbitrary JS function, so it cannot be queried
+     * against the committed base. To recall committed entities by a block key
+     * (new-vs-base, the `baseKey` source §6.2), declare the key as a TypeGraph node
+     * index and name it via {@link ResolveConfig.blockIndex} instead.
+     */
+    block?: (node: Node<K>) => string | undefined;
+    /**
+     * Name of a declared TypeGraph node index (`defineNodeIndex`) whose key is this
+     * kind's NEW-vs-BASE block key (design §6.2). When set and the new-vs-base scope is
+     * driven, the `baseKey` source issues an indexed `bulkFindByIndex` lookup of
+     * committed nodes sharing each staged node's index key and proposes them as scored
+     * candidate pairs (a shared block key is a candidate, not a definitional match).
+     *
+     * The index keys on real fields (a field-set + scope + optional partial-`where`), so
+     * only a FIELD-SET block key migrates here; a transform key (`slice`/`soundex`/…)
+     * stays on the staged-only {@link block}. Unused on the public snapshot `merge()`
+     * path. An undeclared name surfaces a typed error at lookup time.
+     */
+    blockIndex?: string;
+    /**
+     * Bounded coarse candidate generation for the NO-KEY case (design §6.2, the
+     * `keyless` source). A node whose {@link block} returns `undefined` (and has no
+     * unique signature) lands in the shared `"unblocked"` bucket, which is otherwise
+     * compared ALL-vs-all — an O(n²) cliff that `maxComparisonsPerKind` then truncates
+     * to id-only. Set `keyless` to bound that bucket by single-pass SORTED-NEIGHBOURHOOD
+     * instead: the unblocked nodes are sorted by their similarity-field text (tie-broken
+     * by id) and each is proposed only against its next `window` neighbours — O(n·window),
+     * deterministic. Unset preserves today's all-vs-all behaviour. Only the `"unblocked"`
+     * bucket is affected; keyed `block()` buckets are unchanged.
+     */
+    keyless?: Readonly<{
+        /** Forward-neighbour window: each unblocked node is paired with its next `window`
+         * neighbours in the sort. Must be a positive integer. Larger → more recall, more
+         * comparisons (→ all-vs-all as `window` ≥ bucket size). */
+        window: number;
+    }>;
+    /** Similarity strategy (design §8). */
+    similarity: SimilarityStrategy<G, K>;
+    /** Candidate-merge threshold in `[0, 1]`. */
+    threshold: number;
+}>;
+/**
+ * A resolved cluster of node ids that the merge collapses into one canonical
+ * survivor.
+ */
+type ResolvedCluster = Readonly<{
+    members: readonly NodeId<NodeType>[];
+}>;
+/**
+ * Policy for resolving conflicting property values across cluster members.
+ *
+ * - `"flag"` keeps the canonical's value and records a {@link PropertyConflict}
+ *   without auto-resolving.
+ * - `"lastWriteWins"` picks by the stable branch/logical total order — NEVER
+ *   wall-clock arrival.
+ * - `"provenanceWeighted"` picks by per-branch trust weight.
+ * - A function delegates the decision, returning the surviving {@link JsonValue}.
+ */
+type PropertyConflictPolicy<G extends GraphDef = GraphDef> = "flag" | "lastWriteWins" | "provenanceWeighted" | ((conflict: PropertyConflict<G>) => JsonValue);
+/**
+ * Policy for resolving an inherited node that is deleted by one branch and
+ * modified by another (design §6.2).
+ *
+ * - `"deleteWins"` — the node is finally DELETED; the modification is discarded.
+ * - `"modifyWins"` — the node is RESURRECTED; the modification survives.
+ * - `"flag"` (default) — the **modification SURVIVES in the merged output** (as
+ *   with `"modifyWins"`) AND an **unresolved {@link DeleteModifyConflict} is
+ *   recorded** in `report.deleteModifyConflicts` for human review. `"flag"` is
+ *   therefore NOT neutral — it keeps data and surfaces the disagreement, on the
+ *   posture that a merge must never silently destroy the only branch still
+ *   carrying data. Choose `"deleteWins"` to honor the delete by default instead.
+ */
+type DeleteModifyPolicy = "deleteWins" | "modifyWins" | "flag";
+/**
+ * Behavior when `maxComparisonsPerKind` is exceeded for a kind.
+ *
+ * - `"error"` fails the merge with a typed error (default).
+ * - `"mergeByIdOnly"` skips similarity for that kind, emits no candidate edges,
+ *   and records a report warning.
+ */
+type ComparisonCeilingPolicy = "error" | "mergeByIdOnly";
+/**
+ * Ontology type-reconciliation mode. `"off"` is a no-op (default); `"ontology"`
+ * collapses compatible types to the most-specific via the public subClassOf
+ * closure (T2a / T10).
+ */
+type ReconcileTypesMode = "ontology" | "off";
+/**
+ * Map of node kind name → its {@link ResolveConfig}. Keys are constrained to the
+ * graph's node kinds (`keyof G["nodes"]`), so a typo or a kind that does not
+ * belong to the graph is a COMPILE error rather than a silently-ignored config
+ * (which would let those nodes merge by id only without warning). Each kind's
+ * config is bound to that kind's concrete `NodeType`, so `block(node)` and the
+ * `custom` scorer see the right node shape. All keys are optional: kinds omitted
+ * from this map merge by ID only (new fork nodes added as-is, no fuzzy
+ * resolution). For the default unparameterized `GraphDef` the keys widen back to
+ * `string`.
+ */
+type ResolveMap<G extends GraphDef = GraphDef> = Readonly<Partial<{
+    [K in NodeKinds<G>]: ResolveConfig<G, GetNodeType<G, K>>;
+}>>;
+/**
+ * Caller-facing options for {@link merge}. All fields are optional with frozen
+ * defaults applied by `normalizeMergeOptions` (see `options.ts`).
+ */
+type MergeOptions<G extends GraphDef = GraphDef> = Readonly<{
+    /** Per-kind entity resolution. Omitted kinds merge by ID only. */
+    resolve?: ResolveMap<G>;
+    /** Reconcile differing types across forks. Default `"off"`. */
+    reconcileTypes?: ReconcileTypesMode;
+    /** Property-conflict policy for staged-vs-staged disagreements. Default `"flag"`. */
+    onPropertyConflict?: PropertyConflictPolicy<G>;
+    /**
+     * Property-conflict policy for BASE↔branch disagreements in a new-vs-base merge
+     * (§6.4-C). DISTINCT from {@link onPropertyConflict} and DOES NOT inherit it:
+     * `onPropertyConflict` can be `"lastWriteWins"` / `"provenanceWeighted"` / a
+     * function, any of which would let a fuzzy branch match silently OVERWRITE
+     * committed data. Default `"flag"` keeps the committed base value (and records the
+     * conflict). Mirrors how `onDeleteModifyConflict` is kept separate. Only consulted
+     * when a cluster contains a base member; the staged path never uses it.
+     */
+    onBasePropertyConflict?: PropertyConflictPolicy<G>;
+    /** Delete/modify-conflict policy. Default `"flag"`. */
+    onDeleteModifyConflict?: DeleteModifyPolicy;
+    /** Comparison-ceiling behavior. Default `"error"`. */
+    onComparisonCeiling?: ComparisonCeilingPolicy;
+    /**
+     * Deterministic survivor selection within a cluster. Default: the member with
+     * the lexicographically-minimal node id.
+     */
+    canonical?: (cluster: ResolvedCluster) => NodeId<NodeType>;
+    /** Populate the report-only provenance index. Default `true`. */
+    provenance?: boolean;
+    /**
+     * Persist provenance ON-GRAPH: after the commit, upsert one `{branch, sourceId}`
+     * row per contribution into a sidecar provenance graph on the target's backend
+     * (queryable via `openProvenanceStore` / `readProvenance`). Default `false`
+     * (report-only). Best-effort and post-commit — a persistence failure surfaces as
+     * a {@link MergeReport.warnings} entry, never a failed merge.
+     */
+    persistProvenance?: boolean;
+    /**
+     * Local embedder for `vector` / `hybrid` similarity (in-memory cosine over the
+     * staged candidate pairs). Required ONLY when a kind's resolve strategy is
+     * `vector` or `hybrid`; `fulltext` / `custom` ignore it. A vector/hybrid
+     * strategy with no embedder configured fails with a typed
+     * {@link import("./errors").SimilarityUnavailableError}.
+     */
+    embedder?: Embedder;
+    /** Merge receiver. Default: the base `store`, written transactionally. */
+    target?: Store<G>;
+    /** Safety ceiling on candidate comparisons per kind. Default: unbounded. */
+    maxComparisonsPerKind?: number;
+    /**
+     * Optional single-link diameter guard. When set, clusters whose pairwise
+     * distance exceeds it are split by the deterministic drop-weakest rule (T8).
+     */
+    clusterMaxDiameter?: number;
+    /**
+     * Explicit stable branch order used by `lastWriteWins` / tie-breaking. When
+     * omitted, branch ids sorted lexicographically are used. NEVER wall-clock.
+     */
+    branchOrder?: readonly BranchId[];
+    /**
+     * Per-branch trust weights consulted ONLY by the `"provenanceWeighted"`
+     * property-conflict policy ({@link onPropertyConflict} /
+     * {@link onBasePropertyConflict}): when branches disagree on a property value,
+     * the value contributed by the highest-weight branch wins. Ties fall back to
+     * {@link branchOrder} (then canonical value order); branches absent from the map
+     * default to weight `0`. Ignored by every other policy. Keyed by
+     * {@link BranchId}, like {@link branchOrder}. Without this map,
+     * `"provenanceWeighted"` has no weights to consult and degrades to
+     * `"lastWriteWins"` semantics.
+     */
+    provenanceWeights?: ReadonlyMap<BranchId, number>;
+}>;
+/**
+ * Object-form arguments for {@link mergeIncremental} (§6.6). The two same-typed
+ * stores are NAMED so `forkPoint` (the frozen ancestor the branches forked from, the
+ * diff reference) and `target` (the live committed graph that base lookups and the
+ * commit land on) cannot be swapped. `options.target` is ignored — `target` is the
+ * explicit arg.
+ */
+type MergeIncrementalArgs<G extends GraphDef = GraphDef> = Readonly<{
+    forkPoint: Store<G>;
+    target: Store<G>;
+    branches: readonly GraphBranch<G>[];
+    options?: MergeOptions<G>;
+}>;
+/**
+ * Records that a set of fork node ids resolved to a single canonical survivor.
+ */
+type EntityResolution = Readonly<{
+    canonicalId: NodeId<NodeType>;
+    memberIds: readonly NodeId<NodeType>[];
+    kind: string;
+    branchOrigins: readonly BranchId[];
+}>;
+/**
+ * One candidate value contributing to a property conflict, tagged by its origin
+ * branch.
+ */
+type ConflictingValue = Readonly<{
+    branchId: BranchId;
+    value: JsonValue;
+}>;
+/**
+ * A property whose value differed across cluster members (or across the two
+ * collapsed edges for an edge conflict). `resolution` records the value the
+ * policy selected.
+ */
+type PropertyConflict<G extends GraphDef = GraphDef> = Readonly<{
+    entityId: NodeId<NodeType> | EdgeId;
+    kind: string;
+    property: string;
+    values: readonly ConflictingValue[];
+    resolution: JsonValue;
+    readonly __graph?: G;
+}>;
+/**
+ * An inherited node OR edge deleted by one branch and modified by another, with
+ * the resolution the {@link DeleteModifyPolicy} produced. `entityId` is a
+ * {@link NodeId} for a node conflict and an {@link EdgeId} for an edge conflict.
+ */
+type DeleteModifyConflict = Readonly<{
+    entityId: NodeId<NodeType> | EdgeId;
+    kind: string;
+    deletedBy: BranchId;
+    modifiedBy: BranchId;
+    resolution: DeleteModifyPolicy;
+}>;
+/**
+ * Records that a cluster's mixed member kinds were collapsed to a single
+ * canonical (most-specific) type via ontology reconciliation.
+ */
+type TypeReconciliation = Readonly<{
+    entityId: NodeId<NodeType>;
+    fromTypes: readonly string[];
+    toType: string;
+}>;
+/**
+ * An item omitted from the merged result (e.g. an edge whose endpoint was
+ * deleted, or an incompatible-typed cluster member).
+ */
+type DroppedItem = Readonly<{
+    kind: "edge" | "node";
+    id: NodeId<NodeType> | EdgeId;
+    reason: string;
+}>;
+/**
+ * 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),
+ * so report shapes that name nodes carry both halves.
+ */
+type ReportNodeIdentity = Readonly<{
+    kind: string;
+    id: NodeId<NodeType>;
+}>;
+/**
+ * An AMBIGUOUS new-vs-base match (design §6.4-A): a connected component that
+ * bridged ≥2 distinct committed base entities (directly, `baseA ~ new ~ baseB`, or
+ * through staged hops, `baseA ~ new1 ~ new2 ~ baseB`). `baseIds` are the committed
+ * entities the component spanned; `memberIds` are all of its members. Both are full
+ * `(kind, id)` identities — the guard keys on the composite identity, so a component
+ * spanning two SAME-id/different-kind bases stays distinguishable in the report. The
+ * base↔base collapse is ALWAYS REFUSED — the component is split so the committed
+ * entities stay separate. Reported regardless of how the component split. (A
+ * deliberate-collapse trust path is deferred until committed-entity re-keying + edge
+ * repoint exist; §6.4-C.)
+ */
+type BaseAmbiguity = Readonly<{
+    baseIds: readonly ReportNodeIdentity[];
+    memberIds: readonly ReportNodeIdentity[];
+}>;
+/**
+ * The contribution one branch made to the merged result. Returned by
+ * {@link ProvenanceIndex.byBranch}. EXPLICITLY in-memory / report-only for P0 —
+ * no on-graph prop tagging (deferred to the AgentFS phase).
+ */
+type BranchProvenance = Readonly<{
+    nodeIds: readonly NodeId<NodeType>[];
+    edgeIds: readonly EdgeId[];
+}>;
+/**
+ * Report-only, in-memory provenance index. `byBranch` answers "which
+ * nodes/edges did this branch contribute to the merged result?".
+ */
+type ProvenanceIndex = Readonly<{
+    byBranch: (branchId: BranchId) => BranchProvenance;
+}>;
+/**
+ * One `{branch, sourceId}` → canonical contribution — the unit of provenance.
+ *
+ * The in-memory {@link ProvenanceIndex} collapses these to `branch → {canonical
+ * ids}`; the full record (which keeps the contributing `sourceId` and kind) is what
+ * `persistProvenance` writes to the sidecar provenance graph. `sourceId` is the
+ * fork-local id the contribution had in its branch BEFORE the merge collapsed it to
+ * `canonicalId` (equal to `canonicalId` for an in-place modification).
+ */
+type ProvenanceRecord = Readonly<{
+    role: "node" | "edge";
+    canonicalId: string;
+    canonicalKind: string;
+    branchId: BranchId;
+    sourceId: string;
+}>;
+/**
+ * The full result of a {@link merge}: counts, every resolution/conflict/
+ * reconciliation/drop, and the report-only provenance index.
+ */
+type MergeReport<G extends GraphDef = GraphDef> = Readonly<{
+    merged: Readonly<{
+        nodes: number;
+        edges: number;
+    }>;
+    resolutions: readonly EntityResolution[];
+    conflicts: readonly PropertyConflict<G>[];
+    deleteModifyConflicts: readonly DeleteModifyConflict[];
+    typeReconciliations: readonly TypeReconciliation[];
+    dropped: readonly DroppedItem[];
+    /**
+     * Ambiguous new-vs-base matches (§6.4-A): components that bridged ≥2 committed
+     * base entities. Empty on the staged-vs-staged snapshot path.
+     */
+    baseAmbiguities: readonly BaseAmbiguity[];
+    provenance: ProvenanceIndex;
+    /**
+     * Non-fatal advisories from the merge — comparison-ceiling skips and, when
+     * `persistProvenance` is set, a best-effort provenance-persistence failure (the
+     * graph still committed). Empty on a clean merge.
+     */
+    warnings: readonly string[];
+    /**
+     * Present only when `persistProvenance` ran and SUCCEEDED: the sidecar provenance
+     * graph id and how many `{branch, sourceId}` rows were upserted. Absent when
+     * persistence was off or failed (a failure adds a {@link MergeReport.warnings}).
+     */
+    provenancePersisted?: Readonly<{
+        graphId: string;
+        count: number;
+    }>;
+}>;
+
+/**
+ * `base@V` stamping.
+ *
+ * A {@link BaseVersion} is the immutable token a branch is forked from. It must
+ * change whenever either the schema OR the live content of the base store
+ * changes, so that `merge()`'s precondition check (T11) can reject a branch that
+ * forked from a divergent base.
+ *
+ * The token is two stable components joined by a separator:
+ *
+ *   1. A **schema hash** — `computeSchemaHash(serializeSchema(graph, version))`.
+ *      This is content-addressed (the public `computeSchemaHash` deliberately
+ *      excludes the version number and `generatedAt`, so it is stable across
+ *      re-saves of the same schema).
+ *   2. A **content fingerprint** — a SHA-256 digest (truncated to a fixed-width
+ *      hex string) of every LIVE node and edge over the base store (`id`,
+ *      `updated_at`, the bitemporal `valid_from`/`valid_to`, and canonicalized
+ *      `props`; edges also carry their endpoint ids), sorted by id, so two stores
+ *      with identical live content fingerprint identically regardless of row
+ *      enumeration order or insertion order. Props AND validity are folded in so
+ *      the token changes on a content or validity edit even when `updated_at` ties
+ *      at millisecond granularity. Hashing keeps the token fixed-width instead of
+ *      growing linearly with store size.
+ *
+ * The token MUST be computed off the ORIGINAL base store, never off a clone:
+ * `exportGraph`/`importGraph` regenerate `created_at`/`updated_at`, so a clone's
+ * fingerprint would not match its source. (See the working-copy fidelity note in
+ * T4.)
+ *
+ * `computeBaseVersion` is async because schema hashing and live-content
+ * enumeration go through async TypeGraph internals. The design's synchronous
+ * illustrative signature does not survive contact with the real store surface.
+ */
+
+/**
+ * Computes the immutable `base@V` token for a store. Combines the schema hash
+ * with a live-content fingerprint into a single branded {@link BaseVersion}.
+ *
+ * MUST be called on the ORIGINAL base store, not a clone (clones regenerate
+ * timestamps and would fingerprint differently).
+ */
+declare function computeBaseVersion<G extends GraphDef>(store: Store<G>): Promise<BaseVersion>;
+
+/**
+ * Error hierarchy for the graph-merge primitive.
+ *
+ * Every error extends the publicly-exported {@link TypeGraphError}, so consumers
+ * can use the same `isTypeGraphError`/category machinery they already use for
+ * TypeGraph itself. Each subclass carries a stable machine-readable `code`, a
+ * fixed `ErrorCategory`, and a cause chain for debugging.
+ */
+/**
+ * Machine-readable error codes for the merge primitive. Stable identifiers so
+ * callers can branch on `error.code` without string-matching messages.
+ */
+declare const MERGE_ERROR_CODES: {
+    readonly merge: "GRAPH_MERGE_ERROR";
+    readonly branch: "GRAPH_MERGE_BRANCH_ERROR";
+    readonly similarityUnavailable: "GRAPH_MERGE_SIMILARITY_UNAVAILABLE";
+    readonly conflict: "GRAPH_MERGE_CONFLICT";
+    readonly baseVersionMismatch: "GRAPH_MERGE_BASE_VERSION_MISMATCH";
+};
+/**
+ * Options shared by every merge error. Mirrors the relevant subset of
+ * TypeGraphError's options while making `cause`/`details`/`suggestion`
+ * uniformly optional at the merge-error boundary.
+ */
+type MergeErrorOptions = Readonly<{
+    details?: Record<string, unknown>;
+    suggestion?: string;
+    cause?: unknown;
+}>;
+/**
+ * Generic failure raised while computing or committing a merge. The catch-all
+ * for the orchestrator (comparison-ceiling overruns, commit failures, etc.).
+ */
+declare class MergeError extends TypeGraphError {
+    constructor(message: string, options?: MergeErrorOptions);
+}
+/**
+ * Failure raised while creating a working-copy branch of a base store
+ * (clone/export/import failures, backend construction failures).
+ */
+declare class BranchError extends TypeGraphError {
+    constructor(message: string, options?: MergeErrorOptions);
+}
+/**
+ * Raised when a `vector`/`hybrid` similarity strategy is requested but no
+ * {@link import("./types").Embedder} was configured (`MergeOptions.embedder` is
+ * absent). The `vector`/`hybrid` scorers compute cosine over real embeddings in
+ * memory, so an embedder is mandatory for them; `fulltext`/`custom` need none.
+ */
+declare class SimilarityUnavailableError extends MergeError {
+    readonly code: "GRAPH_MERGE_SIMILARITY_UNAVAILABLE";
+    constructor(message: string, options?: MergeErrorOptions);
+}
+/**
+ * Raised when a conflict cannot be resolved by the configured policy and the
+ * caller has opted into hard-failing rather than flagging.
+ */
+declare class MergeConflictError extends MergeError {
+    readonly code: "GRAPH_MERGE_CONFLICT";
+    constructor(message: string, options?: MergeErrorOptions);
+}
+/**
+ * Raised by the `merge()` precondition check when a branch's `base@V` token
+ * does not match the merge target's current base version (the branch forked
+ * from a divergent schema or content fingerprint).
+ */
+declare class BaseVersionMismatchError extends MergeError {
+    readonly code: "GRAPH_MERGE_BASE_VERSION_MISMATCH";
+    constructor(message: string, options?: MergeErrorOptions);
+}
+
+/**
+ * Pluggable working-copy strategy: how `branch()` produces an isolated,
+ * independently-mutable copy of a base store.
+ *
+ * The P0 default is a faithful CLONE via the public interchange API
+ * ({@link cloneWorkingCopyStrategy}): `exportGraph` the base, then `importGraph`
+ * into a fresh store on a caller-provided backend. IDs are preserved by
+ * interchange, so the diff engine (T3) can key on stable ids across base and
+ * fork. This leverages public entrypoints only, needs zero schema changes, and
+ * behaves identically across SQLite and Postgres.
+ *
+ * INTERCHANGE FIDELITY LIMITATION (verified, design §13.x): the interchange
+ * `meta` schema has no `deletedAt` field, so a base row that is already
+ * soft-deleted would round-trip into the clone as LIVE (its tombstone lost). A
+ * resurrected row would then read as a spurious `new` node in the fork's diff —
+ * the base row is non-live, so `diffNodeKind` takes its `!isLive(base)` branch and
+ * reports the (live, clone-resurrected) row as an addition — silently re-creating a
+ * deleted node on commit. We therefore export with `includeDeleted: false`: the
+ * clone carries only the base's LIVE state, exactly what `branch()` needs. The
+ * merge state-diff is still computed against the ORIGINAL base store (live rows
+ * only) as the immutable reference, never against the clone (clones regenerate
+ * `created_at`/`updated_at`, which would otherwise destabilize `base@V`).
+ *
+ * Logical-namespace (copy-on-write within one backend, no full data copy) is a
+ * future strategy slot — see the `WorkingCopyStrategy` interface — deferred past
+ * P0.
+ */
+
+/**
+ * How `branch()` materializes a working copy of a base store.
+ *
+ * `create` receives the live base store and returns a fresh, independently
+ * mutable {@link Store} over the SAME graph definition, seeded with the base's
+ * current state. Mutating the returned store MUST NOT affect the base.
+ *
+ * The single method is the only extension point: alternative strategies
+ * (e.g. a future logical-namespace copy-on-write within one backend) implement
+ * the same contract.
+ */
+type WorkingCopyStrategy<G extends GraphDef> = Readonly<{
+    create: (baseStore: Store<G>) => Promise<Store<G>>;
+}>;
+/**
+ * Factory for a caller-provided backend. `branch()` stays backend-agnostic by
+ * delegating backend construction to the caller: the clone strategy calls this
+ * once per `create()` to obtain the fresh backend that backs the working copy.
+ *
+ * Returning a promise lets async backends (e.g. PGlite, which boots an
+ * in-process Postgres engine) be constructed lazily at branch time.
+ *
+ * The returned backend MUST be EMPTY (no rows for the base graph): the clone
+ * seeds it from the base via `importGraph` with `onConflict: "error"`, so a
+ * pre-existing row is surfaced as a {@link BranchError} rather than silently
+ * skipped (which would leave the working copy diverging from the base).
+ */
+type MakeBackend = () => Promise<GraphBackend>;
+/**
+ * The P0 default working-copy strategy: faithful clone via export/import.
+ *
+ * On each `create(baseStore)`:
+ *   1. `exportGraph(baseStore, { includeMeta: true, includeDeleted: false })` —
+ *      `includeMeta: true` carries `created_at`/`updated_at`; `includeDeleted:
+ *      false` keeps the clone to LIVE rows only. Shipping soft-deleted rows is
+ *      unsafe: the meta schema has no `deletedAt`, so they would import as live and
+ *      resurrect on the fork's diff (see the fidelity note above). `branch()` only
+ *      needs the base's live state.
+ *   2. Create a fresh store over the caller-provided backend with the SAME graph
+ *      definition via `createStoreWithSchema`.
+ *   3. `importGraph(freshStore, data, { onConflict: "error", ... })` — ids are
+ *      preserved so the diff engine can key on them. `onConflict: "error"`
+ *      requires the backend to be EMPTY: a pre-existing row is a contract
+ *      violation that must surface loudly, never be silently skipped (a skipped
+ *      row would leave the clone diverging from the base, so the fork's diff would
+ *      report phantom modifications/deletions). `importGraph` RETURNS
+ *      `{ success, errors }` rather than throwing on a per-row rejection, so its
+ *      result is checked and any failure fails the branch.
+ *
+ * The backend `makeBackend()` returns is opened here, so any failure AFTER it is
+ * created closes it before rethrowing — only the success path hands the backend
+ * (via the returned store) to the caller, who then owns its lifecycle.
+ *
+ * @param makeBackend - Constructs the fresh, EMPTY backend the working copy is
+ *   built on.
+ */
+declare function cloneWorkingCopyStrategy<G extends GraphDef>(makeBackend: MakeBackend): WorkingCopyStrategy<G>;
+
+/**
+ * `branch()` — fork an isolated, independently-mutable working copy of a base
+ * store (design §7.1).
+ *
+ * A branch is a {@link GraphBranch}: a fresh {@link BranchId}, the immutable
+ * `base@V` token the copy forked from (computed off the ORIGINAL base store via
+ * {@link computeBaseVersion}, never off the clone), and a {@link Store} over the
+ * branch's own backend seeded with the base's live state.
+ *
+ * The copy mechanism is pluggable behind {@link WorkingCopyStrategy}. The P0
+ * default is the faithful export/import clone ({@link cloneWorkingCopyStrategy}),
+ * which keeps this primitive backend-agnostic: the caller supplies a
+ * `makeBackend` factory, and `branch()` never names a concrete backend.
+ */
+
+/**
+ * Creates an isolated working-copy branch of `baseStore`.
+ *
+ * Stamps the `base@V` token off the original base store, mints (or accepts) a
+ * {@link BranchId}, and materializes the working copy via the resolved strategy.
+ * The default strategy is a faithful clone over a fresh backend produced by
+ * `makeBackend`; pass an explicit `strategy` to override (e.g. a future
+ * logical-namespace copy-on-write).
+ *
+ * Returns a {@link Result}: success yields the {@link GraphBranch}; any failure
+ * (base-version stamping, backend construction, export/import) is wrapped in a
+ * {@link BranchError} with the underlying cause attached. Errors are returned,
+ * never thrown — this is internal-logic surface (the caller converts to a thrown
+ * error at the framework boundary).
+ *
+ * @param baseStore - The store to fork. Remains untouched.
+ * @param makeBackend - Factory for the working copy's backend (keeps the
+ *   primitive backend-agnostic). Used only by the default clone strategy; ignored
+ *   when an explicit `strategy` is supplied.
+ * @param options - Optional `{ id }` to set an explicit branch id.
+ * @param strategy - Optional working-copy strategy override.
+ */
+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)`.
+ *
+ * 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;
+};
+
+/**
+ * The shared SCORING stage (design §4, the single match-decision point).
+ *
+ * Candidate generation is three layers — sources → scoring → reconciler (§4).
+ * This module is the MIDDLE layer: it turns the candidate PROPOSALS every source
+ * emits into the {@link CandidateEdge} set the reconciler consumes, applying the
+ * EXACT same scorer + threshold regardless of which source proposed a pair. A
+ * source proposes (recall); scoring disposes (the match decision).
+ *
+ * Two proposal kinds enter:
+ *
+ *   - {@link CandidatePair}s — unscored `(a, b)` node pairs from any source. They
+ *     are deduped by canonical `(a, b)` and each scored EXACTLY ONCE by
+ *     {@link scorePair}; only pairs clearing the kind's threshold become edges.
+ *   - FORCED {@link CandidateEdge}s — DEFINITIONAL matches (a shared unique value)
+ *     that BYPASS scoring entirely, emitted at {@link FORCED_MATCH_SCORE}. A forced
+ *     pair is never also fuzzy-scored: forced `(a, b)` keys are reserved first, so
+ *     a fuzzy pair proposing the same endpoints is dropped before scoring.
+ *
+ * This was previously fused into `candidate-gen.ts`'s `generateCandidates` (which
+ * scored AND thresholded inline); naming scoring as its own stage is what makes
+ * "the scorer — not a source — decides matches" concrete (§4). `generateCandidates`
+ * now composes the bucket sources over this stage.
+ *
+ * Determinism: the emitted edge set is a pure function of the proposal SETS — pairs
+ * are deduped by canonical `(a, b)`, scored by the symmetric {@link scorePair}, and
+ * the final list is sorted by `(a, b)`, so neither the order proposals arrive in
+ * nor the directionality of a pair affects the result.
+ *
+ * The {@link ComparisonCeilingPolicy} bounds only the FUZZY scoring work (the
+ * embedder step for vector/hybrid); FORCED edges are definitional, not
+ * similarity-based, so they are emitted regardless of the ceiling:
+ *
+ *   - `"error"`         — exceeding the ceiling fails with a typed {@link MergeError}.
+ *   - `"mergeByIdOnly"` — fuzzy similarity is SKIPPED for the kind (no
+ *                         threshold-scored edges), FORCED edges are still emitted,
+ *                         and a {@link CandidateWarning} is recorded.
+ */
+
+/**
+ * An undirected candidate-merge edge between two nodes that should merge.
+ * Endpoints are stored in ascending id order (`a < b`) so the edge has a single
+ * canonical representation. Fuzzy edges carry their similarity score; FORCED
+ * (definitional) edges carry {@link FORCED_MATCH_SCORE}.
+ */
+type CandidateEdge = Readonly<{
+    a: MergeKey;
+    b: MergeKey;
+    score: number;
+}>;
+/**
+ * An unscored candidate pair a source proposes for scoring: the canonical
+ * endpoint ids `(a, b)` (`a < b`) plus the two node objects the scorer reads
+ * fields off of. `left`/`right` carry the nodes whose ids are `a`/`b`
+ * respectively, but {@link scorePair} is symmetric so their roles are
+ * interchangeable for scoring.
+ */
+type CandidatePair<K extends NodeType = NodeType> = Readonly<{
+    a: MergeKey;
+    b: MergeKey;
+    left: Node<K>;
+    right: Node<K>;
+}>;
+
+/**
+ * `merge()` orchestrator (design §7.2, T11).
+ *
+ * Composes every phase built in T3–T10 into one DB-agnostic primitive:
+ *
+ *   1. PRECONDITION — compute the target's `base@V` and reject any branch whose
+ *      `base` token does not match it (`BaseVersionMismatchError`). A branch
+ *      forked from a divergent schema or content fingerprint cannot be merged
+ *      safely (design §5.2 / §13.6).
+ *   2. STAGE — `stageBranches` (T7): the provenance-tagged UNION of every
+ *      branch's state-diff against the immutable base.
+ *   3. CANDIDATE-GEN — per resolved kind: build node-shaped objects from the
+ *      staged NEW nodes, `blockNodes` (T5, folding in unique constraints from
+ *      `introspect()`), `generateCandidates` (T6, fulltext Dice + custom; vector/
+ *      hybrid guarded). Kinds NOT in `options.resolve` merge by id only.
+ *   4. CLUSTER — `connectedComponents` (T8) over the accumulated candidate edges
+ *      and every staged new-node id, with the optional diameter guard.
+ *   5. CANONICALIZE — `canonicalizeCluster` (T8): min-id survivor + commutative
+ *      property union under the stable, non-wall-clock conflict policy.
+ *   6. DELETE/MODIFY — `resolveDeleteModify` (T8a): the authoritative final
+ *      liveness of every inherited node + the delete/modify conflicts.
+ *   7. TYPE-RECONCILE — `reconcileTypes` (T10) over the public-closure glue when
+ *      `reconcileTypes: "ontology"`; otherwise a no-op.
+ *   8. EDGE REPOINT — `repointEdges` (T9): repoint every staged edge onto its
+ *      cluster canonical, drop edges to finally-deleted endpoints, dedupe + union
+ *      edge props under the same conflict policy.
+ *   9. COMMIT — apply everything to `target` (default = base store) in a single
+ *      `store.transaction` when the backend is transactional, else non-atomically
+ *      with a report warning (out of the P0 acceptance path — SQLite + Postgres
+ *      are both transactional).
+ *  10. REPORT — assemble the {@link MergeReport} with merged counts, every
+ *      resolution / conflict / reconciliation / drop, and the in-memory
+ *      {@link ProvenanceIndex}. With `persistProvenance`, ALSO upsert the
+ *      `{branch, sourceId}` records to a sidecar provenance graph (post-commit,
+ *      best-effort — a failure surfaces as a report warning, never a failed merge).
+ *
+ * DETERMINISM: every phase is order-independent (pure functions over the
+ * unordered branch / staged sets, with a branch order captured ONCE for
+ * conflict resolution), so shuffling `branches` yields a deep-equal report and an
+ * identical committed graph. T12 proves this with a fast-check shuffle property.
+ */
+
+/**
+ * Merges a set of branches back into a target store (design §7.2).
+ *
+ * Validates that every branch forked from the target's current `base@V`, stages
+ * the union of their diffs, resolves entities / conflicts / types through the
+ * T3–T10 phases, and commits the merged result to `target` (default: the base
+ * `store`) in a single transaction. Returns a {@link MergeReport} on success.
+ *
+ * This is the SNAPSHOT entry point: candidate generation runs the staged sources
+ * only (`exactKey`, `unique`) — it never resolves a staged node against the
+ * committed base. New-vs-base resolution is the separate {@link mergeAgainstBase}
+ * scope, which has a weaker `base@V` contract.
+ *
+ * Errors are RETURNED (never thrown) as a typed {@link MergeError} subclass:
+ * `BaseVersionMismatchError` for the precondition, `MergeError` for a
+ * comparison-ceiling overrun / commit failure, `SimilarityUnavailableError` for a
+ * `vector`/`hybrid` strategy with no configured vector strategy.
+ *
+ * @param store The base store the branches forked from. Used as the default merge
+ *   target and as the immutable diff reference.
+ * @param branches The branches to merge. ORDER DOES NOT AFFECT THE RESULT — the
+ *   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>>;
+/**
+ * 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
+ * `target` in as a preferred committed branch, resolves branch additions against
+ * committed rows, and propagates inherited node/edge modifications and deletions
+ * through the same three-way merge planner.
+ *
+ * Object-form args so the two same-typed stores (`forkPoint`, `target`) cannot be
+ * swapped. `options.target` is ignored — `target` is the explicit arg.
+ *
+ * Preconditions (typed errors): every branch forked from `forkPoint`
+ * (`branch.base === computeBaseVersion(forkPoint)`); `forkPoint` and `target` share a
+ * schema hash (schema drift is fatal; target CONTENT may have advanced); and
+ * `onBasePropertyConflict` is `"flag"` (keep-base for committed-row conflicts).
+ */
+declare function mergeIncremental<G extends GraphDef>(args: MergeIncrementalArgs<G>): Promise<Result<MergeReport<G>, MergeError>>;
+
+/**
+ * Validation + default-application for {@link MergeOptions}.
+ *
+ * The zod schema validates the scalar / enum surface (thresholds, ceilings,
+ * enums) and applies the frozen P0 defaults. Function- and store-valued fields
+ * (`canonical`, a function `onPropertyConflict`, `target`, per-kind `block` /
+ * `custom.score`, `branchOrder`) are not meaningfully validatable by zod, so they
+ * are threaded through unchanged after the scalar surface validates.
+ *
+ * `normalizeMergeOptions` is the single entry point: it returns a
+ * {@link NormalizedMergeOptions} with every default resolved, so downstream
+ * phases never branch on `undefined`.
+ */
+
+/**
+ * Frozen P0 defaults. Exported so tests and downstream phases assert against the
+ * same constants rather than re-typing literals.
+ */
+declare const MERGE_OPTION_DEFAULTS: {
+    readonly reconcileTypes: "off";
+    readonly onPropertyConflict: "flag";
+    readonly onBasePropertyConflict: "flag";
+    readonly onDeleteModifyConflict: "flag";
+    readonly onComparisonCeiling: "error";
+    readonly provenance: true;
+    readonly persistProvenance: false;
+};
+/**
+ * Fully-normalized merge options: every default resolved, the (validated)
+ * pass-through fields attached. Downstream phases consume this, never the raw
+ * {@link MergeOptions}.
+ */
+type NormalizedMergeOptions<G extends GraphDef = GraphDef> = Readonly<{
+    resolve: Readonly<Record<string, ResolveConfig<G>>>;
+    reconcileTypes: ReconcileTypesMode;
+    onPropertyConflict: PropertyConflictPolicy<G>;
+    onBasePropertyConflict: PropertyConflictPolicy<G>;
+    onDeleteModifyConflict: DeleteModifyPolicy;
+    onComparisonCeiling: ComparisonCeilingPolicy;
+    provenance: boolean;
+    persistProvenance: boolean;
+    canonical?: (cluster: ResolvedCluster) => ReturnType<NonNullable<MergeOptions<G>["canonical"]>>;
+    embedder?: Embedder;
+    target?: MergeOptions<G>["target"];
+    maxComparisonsPerKind?: number;
+    clusterMaxDiameter?: number;
+    branchOrder?: readonly BranchId[];
+    provenanceWeights?: ReadonlyMap<BranchId, number>;
+}>;
+/**
+ * Validates and normalizes {@link MergeOptions}, applying every P0 default.
+ *
+ * Throws (not a `Result`) on invalid scalar input — option validation is a
+ * caller-boundary concern, surfaced as a thrown error per project conventions;
+ * `merge()` converts it back to a typed `MergeError` at its own boundary.
+ *
+ * @throws if a threshold is outside `[0, 1]`, `maxComparisonsPerKind` is
+ *   negative/non-integer, or `clusterMaxDiameter` is non-positive.
+ */
+declare function normalizeMergeOptions<G extends GraphDef>(options?: MergeOptions<G>): NormalizedMergeOptions<G>;
+
+/** The Provenance node: one row per `{branch, sourceId}` → canonical contribution. */
+declare const Provenance: Readonly<{
+    kind: "Provenance";
+    schema: z.ZodObject<{
+        targetGraphId: z.ZodString;
+        role: z.ZodEnum<{
+            node: "node";
+            edge: "edge";
+        }>;
+        canonicalId: z.ZodString;
+        canonicalKind: z.ZodString;
+        branchId: z.ZodString;
+        sourceId: z.ZodString;
+    }, z.core.$strip>;
+    description: string | undefined;
+    annotations: KindAnnotations | undefined;
+    __nodeType: true;
+}>;
+/**
+ * Derives the sidecar graph id for a target graph. Suffixing the target's own id
+ * keeps each target graph's provenance in its own `graphId`-namespaced tables on a
+ * shared backend, while a single `Provenance` schema serves all of them.
+ */
+declare function provenanceGraphId(targetGraphId: string): string;
+/** Builds the sidecar provenance graph definition for a target graph. */
+declare function buildProvenanceGraph(targetGraphId: string): Readonly<{
+    id: string;
+    nodes: {
+        readonly Provenance: {
+            readonly type: Readonly<{
+                kind: "Provenance";
+                schema: z.ZodObject<{
+                    targetGraphId: z.ZodString;
+                    role: z.ZodEnum<{
+                        node: "node";
+                        edge: "edge";
+                    }>;
+                    canonicalId: z.ZodString;
+                    canonicalKind: z.ZodString;
+                    branchId: z.ZodString;
+                    sourceId: z.ZodString;
+                }, z.core.$strip>;
+                description: string | undefined;
+                annotations: KindAnnotations | undefined;
+                __nodeType: true;
+            }>;
+        };
+    };
+    edges: {};
+    ontology: readonly Readonly<{
+        metaEdge: MetaEdge;
+        from: NodeType | EdgeType | string;
+        to: NodeType | EdgeType | string;
+    }>[];
+    defaults: Readonly<{
+        onNodeDelete: DeleteBehavior;
+        temporalMode: TemporalMode;
+    }>;
+    indexes: readonly IndexDeclaration[] | undefined;
+    extension: Readonly<{
+        version?: GraphExtensionVersion;
+        nodes?: Readonly<Record<string, ExtensionNodeDef>>;
+        edges?: Readonly<Record<string, ExtensionEdgeDef>>;
+        ontology?: readonly ExtensionOntologyRelation[];
+        indexes?: readonly ExtensionIndex[];
+    }> | undefined;
+    deprecatedKinds: ReadonlySet<string>;
+    __graphDef: true;
+}>;
+/** The concrete sidecar provenance graph type. */
+type ProvenanceGraph = ReturnType<typeof buildProvenanceGraph>;
+/** A persisted provenance node (the queryable record). */
+type ProvenanceNode = Node<typeof Provenance>;
+/**
+ * Opens — materializing the schema if needed — the provenance store for a target
+ * graph on the given backend. Idempotent: safe to call before every persist/query,
+ * and shares the backend with the target (so the caller must NOT close it
+ * separately — closing the shared backend is the target owner's job).
+ */
+declare function openProvenanceStore(backend: GraphBackend, targetGraphId: string): Promise<Store<ProvenanceGraph>>;
+/**
+ * Upserts one `Provenance` node per record into the sidecar store, keyed by the
+ * deterministic id (re-running the same merge is a no-op upsert, never a
+ * duplicate). Returns the row count written. The caller wraps this for best-effort
+ * behavior — a failure here must not fail an already-committed merge.
+ */
+declare function persistProvenanceRecords(store: Store<ProvenanceGraph>, targetGraphId: string, records: readonly ProvenanceRecord[]): Promise<number>;
+/** Filter for {@link readProvenance}. Each field, when set, narrows the result. */
+type ProvenanceQuery = Readonly<{
+    branchId?: BranchId | string;
+    canonicalId?: string;
+    role?: "node" | "edge";
+}>;
+/**
+ * Reads persisted provenance back, filtered and stably ordered. The sidecar is a
+ * normal typed graph, so this is a thin ergonomic wrapper over
+ * `store.nodes.Provenance.find()` (filtered in memory — provenance volumes are
+ * modest; a query-builder `where` is the scale path). Answers "which canonical
+ * entities did branch X contribute to?" and "who contributed canonical Y?".
+ */
+declare function readProvenance(store: Store<ProvenanceGraph>, query?: ProvenanceQuery): Promise<readonly ProvenanceNode[]>;
+
+/**
+ * Candidate SOURCES (design §4 / §6.1) — the RECALL layer of candidate generation.
+ *
+ * Candidate generation is three layers — sources → scoring → reconciler (§4). This
+ * module is the FIRST layer: each source PROPOSES candidates and decides nothing
+ * about a fuzzy match. A source emits three things:
+ *
+ *   - `pairs`       — unscored `(a, b)` node pairs handed to the shared scoring
+ *                     stage (`scoring.ts`), which makes every fuzzy match decision.
+ *   - `forcedEdges` — DEFINITIONAL matches (a shared unique value) that bypass
+ *                     scoring at {@link FORCED_MATCH_SCORE}.
+ *   - `baseMembers` — committed base nodes the source pulled into scope, so the
+ *                     reconciler can seed + canonicalize a base endpoint without
+ *                     re-querying the backend. EMPTY for staged-only sources.
+ *
+ * Two sources ship here — today's two blocking strategies (`blocking.ts`),
+ * refactored behind the source interface:
+ *
+ *   - {@link exactKeySource} (`exactKey`, §6.1) — the `block(node) => string`
+ *     bucket: same-bucket node pairs become fuzzy `pairs`. Staged-vs-staged.
+ *   - {@link uniqueSource} (`unique`, §6.1) — the unique-constraint signature
+ *     buckets: every same-signature pair is a FORCED edge (a shared unique value
+ *     is definitionally the same entity). Staged-vs-staged.
+ *
+ * Both read the SAME pre-computed `blockNodes` map off the scope (the UNION of the
+ * `block()` key and the per-constraint signatures, `blocking.ts`), filtering it by
+ * {@link isUniqueBucketKey}: `exactKey` owns the non-unique buckets, `unique` owns
+ * the unique buckets. Sharing one blocked map (vs. re-blocking per source) keeps the
+ * source split byte-identical to the old fused `generateCandidates` — a node with a
+ * unique signature but no `block()` key lands ONLY in its unique bucket, never the
+ * all-vs-all `unblocked` bucket.
+ *
+ * Determinism: the extraction visits buckets in sorted-key order over id-sorted
+ * members and enumerates `i < j`, so proposals are emitted in a canonical order;
+ * the scoring stage additionally dedups + sorts, so neither source's emission order
+ * leaks into the merge result.
+ */
+
+/**
+ * A committed BASE node a source pulled into the cluster universe (design §4
+ * member contribution / §6.4-D). It carries the same `(id, kind, props)` a staged
+ * member does, plus a reserved `"base"` origin so the reconciler can enforce
+ * base-id-wins (§6.4-C) and tag provenance with the base sentinel (§6.4-D). EMPTY
+ * for staged-only sources (`exactKey`, `unique`).
+ */
+type BaseMember = Readonly<{
+    id: NodeId<NodeType>;
+    kind: string;
+    props: Readonly<Record<string, JsonValue>>;
+    origin: "base";
+}>;
+/**
+ * What a candidate source emits for one kind: fuzzy `pairs` to score, FORCED
+ * (definitional) edges to pass through unscored, and the committed `baseMembers`
+ * it pulled into scope.
+ */
+type SourceResult = Readonly<{
+    pairs: readonly CandidatePair[];
+    forcedEdges: readonly CandidateEdge[];
+    baseMembers: readonly BaseMember[];
+}>;
+/**
+ * The minimal node-collection surface a base-querying source needs: the public
+ * `bulkFindByConstraint` (typegraph 0.29.0). It computes each item's constraint key
+ * from its props, returns the live committed match per item in INPUT ORDER
+ * (`undefined` for misses, soft-deleted excluded), and is indexed by the `uniques`
+ * table PK — so graph-merge never reconstructs constraint keys itself. A runtime,
+ * kind-string-keyed view (like the commit's `TxNodes`) so a source can dispatch on
+ * a kind string without threading the caller's concrete `Store<G>` generic.
+ */
+type BaseNodeLookup = Readonly<{
+    bulkFindByConstraint: (constraintName: string, items: readonly Readonly<{
+        props: Record<string, unknown>;
+    }>[]) => Promise<readonly (Node<NodeType> | undefined)[]>;
+    /**
+     * The non-unique sibling (typegraph 0.30): for each item, the live committed nodes
+     * sharing its declared-INDEX key (computed from props), returned per item in input
+     * order, each inner array id-sorted, soft-deleted excluded. `limitPerInput` bounds
+     * per-item fan-out (id-ordered, so the cap is deterministic). Candidate retrieval —
+     * NOT a uniqueness/identity guarantee — so `baseKey` emits scored pairs, not forced
+     * edges.
+     */
+    bulkFindByIndex: (indexName: string, items: readonly Readonly<{
+        props: Record<string, unknown>;
+    }>[], options?: Readonly<{
+        limitPerInput?: number;
+    }>) => Promise<readonly (readonly Node<NodeType>[])[]>;
+}>;
+/** Runtime, kind-string-keyed view of a store's node collections for base lookups. */
+type BaseLookupStore = Readonly<{
+    nodes: Readonly<Record<string, BaseNodeLookup>>;
+}>;
+/**
+ * The per-kind input a source generates over. `blocks` is the UNION `blockNodes`
+ * result (`block()` key + per-constraint signatures) the staged sources read.
+ *
+ * The remaining fields are present only when a BASE-querying source (`baseUnique` /
+ * `baseKey`, §6.2) is driven: the kind's materialized staged new `nodes` (the lookup
+ * items), its `uniqueConstraints` (for `baseUnique`), the declared `blockIndex` name
+ * (for `baseKey`, when the kind configured one), and the committed `store` to query
+ * against. Staged-only sources (`exactKey`, `unique`) ignore them, so the public
+ * `merge()` candidate path leaves them unset.
+ */
+type SourceScope = Readonly<{
+    kind: string;
+    blocks: ReadonlyMap<string, readonly Node<NodeType>[]>;
+    nodes?: readonly Node<NodeType>[];
+    uniqueConstraints?: readonly UniqueIntrospection[];
+    blockIndex?: string;
+    /** When set, `exactKey` bounds the no-key (`"unblocked"`) bucket by sorted-
+     * neighbourhood instead of all-vs-all (the `keyless` source, §6.2). */
+    keyless?: KeylessConfig;
+    store?: BaseLookupStore;
+}>;
+/**
+ * A candidate source (design §4): proposes pairs (recall) + definitional forced
+ * edges, and supplies the base members it pulled into scope. The `id` attributes
+ * a source in reports and pins its determinism level (§7).
+ */
+type CandidateSource = Readonly<{
+    readonly id: string;
+    generate(scope: SourceScope): Promise<SourceResult>;
+}>;
+/**
+ * The bounded coarse source for the NO-KEY case (design §6.2, `keyless`): which
+ * unblocked nodes to compare, and how far. `window` is the forward-neighbour count;
+ * `sortFields` is the kind's similarity text fields, so the SORTED-NEIGHBOURHOOD sort
+ * groups lexically-similar values adjacently (the same text the scorer reads).
+ */
+type KeylessConfig = Readonly<{
+    window: number;
+    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, type KeylessConfig, MERGE_ERROR_CODES, MERGE_OPTION_DEFAULTS, type MakeBackend, MergeConflictError, MergeError, type MergeIncrementalArgs, type MergeOptions, type MergeReport, 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, type WorkingCopyStrategy, asBaseVersion, asBranchId, branch, cloneWorkingCopyStrategy, computeBaseVersion, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, provenanceGraphId, readProvenance };