@nicia-ai/typegraph 0.30.0 → 0.32.0

package/dist/graph-merge/index.js

@@ -0,0 +1,3935 @@
+import { createStoreWithSchema, generateId, computeUniqueKey } from '../chunk-WNORITK6.js';
+import '../chunk-3EUKJEQ3.js';
+import { exportGraph, importGraph } from '../chunk-HFBRAOF7.js';
+import { defineNode, computeSchemaHash, serializeSchema } from '../chunk-2BVHPOIG.js';
+import { getNodeKinds, getEdgeKinds, defineGraph } from '../chunk-W4ZX2GCP.js';
+import '../chunk-PIHXFF73.js';
+import '../chunk-IJORSAC3.js';
+import '../chunk-MXE2U3EX.js';
+import '../chunk-454I6GDF.js';
+import { ok, err, isErr, computeTransitiveClosure, isReachable } from '../chunk-YCV72E6L.js';
+export { isErr, isOk, unwrap } from '../chunk-YCV72E6L.js';
+import '../chunk-SAJSMR2B.js';
+import { sortedReplacer } from '../chunk-M6OC455F.js';
+import '../chunk-C4C4Q7A6.js';
+import { sha256Hex } from '../chunk-2YMGNYXY.js';
+import { TypeGraphError } from '../chunk-TQOYM4LN.js';
+import '../chunk-K5P5OZXS.js';
+import { z } from 'zod';
+
+// src/graph-merge/canonical-props.ts
+function canonicalizeProps(props) {
+  return JSON.stringify(props, sortedReplacer);
+}
+function canonicalValueKey(value) {
+  return JSON.stringify(value, sortedReplacer);
+}
+function parseRowProps(props) {
+  let parsed;
+  try {
+    parsed = JSON.parse(props);
+  } catch {
+    return {};
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return {};
+  }
+  return parsed;
+}
+
+// src/graph-merge/node-key.ts
+var SEPARATOR = String.fromCharCode(0);
+function mergeKey(kind, id) {
+  if (kind.includes(SEPARATOR)) {
+    throw new Error(
+      `Node kind ${JSON.stringify(kind)} contains a NUL byte, which collides the (kind, id) merge-identity separator.`
+    );
+  }
+  return `${kind}${SEPARATOR}${id}`;
+}
+function compareStrings(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+function mergeKeyOf(node) {
+  return mergeKey(node.kind, node.id);
+}
+function kindOf(key) {
+  const separator = key.indexOf(SEPARATOR);
+  return separator === -1 ? key : key.slice(0, separator);
+}
+function idOf(key) {
+  const separator = key.indexOf(SEPARATOR);
+  return separator === -1 ? key : key.slice(separator + 1);
+}
+function compareMergeKeys(left, right) {
+  const leftId = idOf(left);
+  const rightId = idOf(right);
+  if (leftId !== rightId) {
+    return leftId < rightId ? -1 : 1;
+  }
+  const leftKind = kindOf(left);
+  const rightKind = kindOf(right);
+  return leftKind < rightKind ? -1 : leftKind > rightKind ? 1 : 0;
+}
+
+// src/graph-merge/state-diff.ts
+var ENUMERATION_PAGE_SIZE = 1e3;
+async function enumerateAllNodes(backend, graphId, kind) {
+  const collected = [];
+  let after = void 0;
+  for (; ; ) {
+    const page = await backend.findNodesByKind({
+      graphId,
+      kind,
+      excludeDeleted: false,
+      orderBy: "id",
+      limit: ENUMERATION_PAGE_SIZE,
+      ...after === void 0 ? {} : { after }
+    });
+    for (const row of page) {
+      collected.push(row);
+    }
+    if (page.length < ENUMERATION_PAGE_SIZE) {
+      break;
+    }
+    after = page.at(-1).id;
+  }
+  return collected;
+}
+async function enumerateAllEdges(backend, graphId, kind) {
+  const collected = [];
+  let after = void 0;
+  for (; ; ) {
+    const page = await backend.findEdgesByKind({
+      graphId,
+      kind,
+      excludeDeleted: false,
+      orderBy: "id",
+      limit: ENUMERATION_PAGE_SIZE,
+      ...after === void 0 ? {} : { after }
+    });
+    for (const row of page) {
+      collected.push(row);
+    }
+    if (page.length < ENUMERATION_PAGE_SIZE) {
+      break;
+    }
+    after = page.at(-1).id;
+  }
+  return collected;
+}
+function isLive(row) {
+  return row.deleted_at === void 0;
+}
+function indexById(rows) {
+  const index = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    index.set(row.id, row);
+  }
+  return index;
+}
+function diffNodeKind(kind, baseRows, forkRows) {
+  const baseIndex = indexById(baseRows);
+  const forkIndex = indexById(forkRows);
+  const created = [];
+  const modified = [];
+  const deleted = [];
+  for (const forkRow of forkRows) {
+    if (!isLive(forkRow)) {
+      continue;
+    }
+    const baseRow = baseIndex.get(forkRow.id);
+    const forkProps = parseRowProps(forkRow.props);
+    if (baseRow === void 0 || !isLive(baseRow)) {
+      created.push({
+        id: forkRow.id,
+        kind,
+        props: forkProps,
+        row: forkRow
+      });
+      continue;
+    }
+    const baseProps = parseRowProps(baseRow.props);
+    if (canonicalizeProps(baseProps) !== canonicalizeProps(forkProps)) {
+      modified.push({
+        id: forkRow.id,
+        kind,
+        baseProps,
+        forkProps,
+        row: forkRow
+      });
+    }
+  }
+  for (const baseRow of baseRows) {
+    if (!isLive(baseRow)) {
+      continue;
+    }
+    const forkRow = forkIndex.get(baseRow.id);
+    if (forkRow === void 0 || !isLive(forkRow)) {
+      deleted.push({ id: baseRow.id, kind });
+    }
+  }
+  return { new: created, modified, deleted };
+}
+function diffEdgeKind(kind, baseRows, forkRows) {
+  const baseIndex = indexById(baseRows);
+  const forkIndex = indexById(forkRows);
+  const created = [];
+  const modified = [];
+  const deleted = [];
+  for (const forkRow of forkRows) {
+    if (!isLive(forkRow)) {
+      continue;
+    }
+    const baseRow = baseIndex.get(forkRow.id);
+    const forkProps = parseRowProps(forkRow.props);
+    if (baseRow === void 0 || !isLive(baseRow)) {
+      created.push({
+        id: forkRow.id,
+        kind,
+        fromId: forkRow.from_id,
+        toId: forkRow.to_id,
+        fromKind: forkRow.from_kind,
+        toKind: forkRow.to_kind,
+        props: forkProps,
+        row: forkRow
+      });
+      continue;
+    }
+    const baseProps = parseRowProps(baseRow.props);
+    if (canonicalizeProps(baseProps) !== canonicalizeProps(forkProps)) {
+      modified.push({
+        id: forkRow.id,
+        kind,
+        fromId: forkRow.from_id,
+        toId: forkRow.to_id,
+        fromKind: forkRow.from_kind,
+        toKind: forkRow.to_kind,
+        baseProps,
+        forkProps,
+        row: forkRow
+      });
+    }
+  }
+  for (const baseRow of baseRows) {
+    if (!isLive(baseRow)) {
+      continue;
+    }
+    const forkRow = forkIndex.get(baseRow.id);
+    if (forkRow === void 0 || !isLive(forkRow)) {
+      deleted.push({ id: baseRow.id, kind });
+    }
+  }
+  return { new: created, modified, deleted };
+}
+function byId(left, right) {
+  return compareStrings(left.id, right.id);
+}
+async function diffAgainstBase(baseStore, forkStore) {
+  const graph = baseStore.graph;
+  const nodeKinds = getNodeKinds(graph);
+  const edgeKinds = getEdgeKinds(graph);
+  const newNodes = [];
+  const modifiedNodes = [];
+  const deletedNodes = [];
+  for (const kind of nodeKinds) {
+    const baseRows = await enumerateAllNodes(
+      baseStore.backend,
+      baseStore.graphId,
+      kind
+    );
+    const forkRows = await enumerateAllNodes(
+      forkStore.backend,
+      forkStore.graphId,
+      kind
+    );
+    const delta = diffNodeKind(kind, baseRows, forkRows);
+    for (const entry of delta.new) {
+      newNodes.push(entry);
+    }
+    for (const entry of delta.modified) {
+      modifiedNodes.push(entry);
+    }
+    for (const entry of delta.deleted) {
+      deletedNodes.push(entry);
+    }
+  }
+  const newEdges = [];
+  const modifiedEdges = [];
+  const deletedEdges = [];
+  for (const kind of edgeKinds) {
+    const baseRows = await enumerateAllEdges(
+      baseStore.backend,
+      baseStore.graphId,
+      kind
+    );
+    const forkRows = await enumerateAllEdges(
+      forkStore.backend,
+      forkStore.graphId,
+      kind
+    );
+    const delta = diffEdgeKind(kind, baseRows, forkRows);
+    for (const entry of delta.new) {
+      newEdges.push(entry);
+    }
+    for (const entry of delta.modified) {
+      modifiedEdges.push(entry);
+    }
+    for (const entry of delta.deleted) {
+      deletedEdges.push(entry);
+    }
+  }
+  return {
+    nodes: {
+      new: newNodes.sort((left, right) => byId(left, right)),
+      modified: modifiedNodes.sort((left, right) => byId(left, right)),
+      deleted: deletedNodes.sort((left, right) => byId(left, right))
+    },
+    edges: {
+      new: newEdges.sort((left, right) => byId(left, right)),
+      modified: modifiedEdges.sort((left, right) => byId(left, right)),
+      deleted: deletedEdges.sort((left, right) => byId(left, right))
+    }
+  };
+}
+
+// src/graph-merge/types.ts
+function asBranchId(value) {
+  return value;
+}
+function asBaseVersion(value) {
+  return value;
+}
+
+// src/graph-merge/base-version.ts
+var TOKEN_SEPARATOR = "\0";
+var FALLBACK_SCHEMA_VERSION = 1;
+async function readActiveSchemaVersion(backend, graphId) {
+  const active = await backend.getActiveSchema(graphId);
+  return active?.version ?? FALLBACK_SCHEMA_VERSION;
+}
+async function computeSchemaComponent(store) {
+  const version = await readActiveSchemaVersion(store.backend, store.graphId);
+  return computeSchemaHash(serializeSchema(store.graph, version));
+}
+function byDigestEntry(left, right) {
+  const byKind = compareStrings(left.kind, right.kind);
+  return byKind === 0 ? compareStrings(left.id, right.id) : byKind;
+}
+var CONTENT_FINGERPRINT_BYTES = 16;
+async function computeContentComponent(backend, graphId, graph) {
+  const nodeKinds = getNodeKinds(graph);
+  const edgeKinds = getEdgeKinds(graph);
+  const nodeDigest = [];
+  for (const kind of nodeKinds) {
+    const rows = await enumerateAllNodes(backend, graphId, kind);
+    for (const row of rows) {
+      if (row.deleted_at === void 0) {
+        nodeDigest.push({
+          id: row.id,
+          kind: row.kind,
+          updatedAt: row.updated_at,
+          validFrom: row.valid_from,
+          validTo: row.valid_to,
+          props: canonicalizeProps(parseRowProps(row.props))
+        });
+      }
+    }
+  }
+  const edgeDigest = [];
+  for (const kind of edgeKinds) {
+    const rows = await enumerateAllEdges(backend, graphId, kind);
+    for (const row of rows) {
+      if (row.deleted_at === void 0) {
+        edgeDigest.push({
+          id: row.id,
+          kind: row.kind,
+          fromId: row.from_id,
+          toId: row.to_id,
+          updatedAt: row.updated_at,
+          validFrom: row.valid_from,
+          validTo: row.valid_to,
+          props: canonicalizeProps(parseRowProps(row.props))
+        });
+      }
+    }
+  }
+  return sha256Hex(
+    canonicalizeProps({
+      nodes: nodeDigest.sort((left, right) => byDigestEntry(left, right)),
+      edges: edgeDigest.sort((left, right) => byDigestEntry(left, right))
+    }),
+    CONTENT_FINGERPRINT_BYTES
+  );
+}
+async function computeBaseVersion(store) {
+  const [schemaComponent, contentComponent] = await Promise.all([
+    computeSchemaComponent(store),
+    computeContentComponent(store.backend, store.graphId, store.graph)
+  ]);
+  return asBaseVersion(
+    `${schemaComponent}${TOKEN_SEPARATOR}${contentComponent}`
+  );
+}
+function contentComponentOf(version) {
+  const separatorIndex = version.indexOf(TOKEN_SEPARATOR);
+  return separatorIndex === -1 ? version : version.slice(separatorIndex + 1);
+}
+
+// src/graph-merge/errors.ts
+var MERGE_ERROR_CODES = {
+  merge: "GRAPH_MERGE_ERROR",
+  branch: "GRAPH_MERGE_BRANCH_ERROR",
+  similarityUnavailable: "GRAPH_MERGE_SIMILARITY_UNAVAILABLE",
+  conflict: "GRAPH_MERGE_CONFLICT",
+  baseVersionMismatch: "GRAPH_MERGE_BASE_VERSION_MISMATCH"
+};
+function toTypeGraphErrorOptions(category, options) {
+  return {
+    category,
+    ...options.details === void 0 ? {} : { details: options.details },
+    ...options.suggestion === void 0 ? {} : { suggestion: options.suggestion },
+    ...options.cause === void 0 ? {} : { cause: options.cause }
+  };
+}
+var MergeError = class extends TypeGraphError {
+  constructor(message, options = {}) {
+    super(
+      message,
+      MERGE_ERROR_CODES.merge,
+      toTypeGraphErrorOptions("system", options)
+    );
+    this.name = "MergeError";
+  }
+};
+var BranchError = class extends TypeGraphError {
+  constructor(message, options = {}) {
+    super(
+      message,
+      MERGE_ERROR_CODES.branch,
+      toTypeGraphErrorOptions("system", options)
+    );
+    this.name = "BranchError";
+  }
+};
+var SimilarityUnavailableError = class extends MergeError {
+  code = MERGE_ERROR_CODES.similarityUnavailable;
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      suggestion: options.suggestion ?? "Pass MergeOptions.embedder (a local model), or use a fulltext/custom similarity strategy."
+    });
+    this.name = "SimilarityUnavailableError";
+  }
+};
+var MergeConflictError = class extends MergeError {
+  code = MERGE_ERROR_CODES.conflict;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "MergeConflictError";
+  }
+};
+var BaseVersionMismatchError = class extends MergeError {
+  code = MERGE_ERROR_CODES.baseVersionMismatch;
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      suggestion: options.suggestion ?? "Re-branch from the current target so the branch base matches before merging."
+    });
+    this.name = "BaseVersionMismatchError";
+  }
+};
+
+// src/graph-merge/working-copy.ts
+var CLONE_IMPORT_BATCH_SIZE = 1e3;
+function cloneWorkingCopyStrategy(makeBackend) {
+  return {
+    create: async (baseStore) => {
+      const data = await exportGraph(baseStore, {
+        includeMeta: true,
+        includeDeleted: false
+      });
+      const backend = await makeBackend();
+      try {
+        const [freshStore] = await createStoreWithSchema(
+          baseStore.graph,
+          backend
+        );
+        const result = await importGraph(freshStore, data, {
+          onConflict: "error",
+          onUnknownProperty: "error",
+          validateReferences: true,
+          batchSize: CLONE_IMPORT_BATCH_SIZE
+        });
+        if (!result.success) {
+          throw new BranchError(
+            "Clone import failed: the working copy could not be seeded from the base store. The backend returned by makeBackend() must be empty.",
+            { details: { errors: result.errors } }
+          );
+        }
+        return freshStore;
+      } catch (error) {
+        try {
+          await backend.close();
+        } catch {
+        }
+        throw error;
+      }
+    }
+  };
+}
+
+// src/graph-merge/branch.ts
+async function branch(baseStore, makeBackend, options, strategy) {
+  try {
+    const base = await computeBaseVersion(baseStore);
+    const id = options?.id ?? asBranchId(generateId());
+    const workingCopyStrategy = strategy ?? cloneWorkingCopyStrategy(makeBackend);
+    const store = await workingCopyStrategy.create(baseStore);
+    return ok({ id, base, store });
+  } catch (error) {
+    return err(
+      new BranchError("Failed to create working-copy branch of base store", {
+        cause: error
+      })
+    );
+  }
+}
+
+// src/graph-merge/blocking.ts
+var UNBLOCKED_BUCKET_KEY = "unblocked";
+var KEY_PART_SEPARATOR = "\0";
+var BLOCK_KEY_PREFIX = "b";
+var UNIQUE_KEY_PREFIX = "u";
+function isUniqueBucketKey(key) {
+  return key.startsWith(`${UNIQUE_KEY_PREFIX}${KEY_PART_SEPARATOR}`);
+}
+function constraintSignature(node, constraint) {
+  const props = node;
+  for (const field of constraint.fields) {
+    const value = props[field];
+    if (value === void 0 || value === null) {
+      return void 0;
+    }
+  }
+  return `${constraint.name}${KEY_PART_SEPARATOR}${computeUniqueKey(
+    props,
+    constraint.fields,
+    constraint.collation
+  )}`;
+}
+function bucketKeysFor(node, block, constraints) {
+  const keys = [];
+  const blockKey = block?.(node);
+  if (blockKey !== void 0) {
+    keys.push(`${BLOCK_KEY_PREFIX}${KEY_PART_SEPARATOR}${blockKey}`);
+  }
+  for (const constraint of constraints) {
+    const signature = constraintSignature(node, constraint);
+    if (signature !== void 0) {
+      keys.push(`${UNIQUE_KEY_PREFIX}${KEY_PART_SEPARATOR}${signature}`);
+    }
+  }
+  return keys.length === 0 ? [UNBLOCKED_BUCKET_KEY] : keys;
+}
+function blockNodes(newNodes, resolveConfig, uniqueConstraints = []) {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const node of newNodes) {
+    for (const key of bucketKeysFor(
+      node,
+      resolveConfig.block,
+      uniqueConstraints
+    )) {
+      const bucket = buckets.get(key);
+      if (bucket === void 0) {
+        buckets.set(key, [node]);
+      } else {
+        bucket.push(node);
+      }
+    }
+  }
+  const sortedKeys = [...buckets.keys()].sort(
+    (left, right) => compareStrings(left, right)
+  );
+  const ordered = /* @__PURE__ */ new Map();
+  for (const key of sortedKeys) {
+    const members = [...buckets.get(key)].sort(
+      (left, right) => compareStrings(left.id, right.id)
+    );
+    ordered.set(key, members);
+  }
+  return ordered;
+}
+
+// src/graph-merge/conflict-policy.ts
+function buildBranchRank(branchOrder, allBranchIds) {
+  const rank = /* @__PURE__ */ new Map();
+  let next = 0;
+  for (const branchId of branchOrder) {
+    if (!rank.has(branchId)) {
+      rank.set(branchId, next);
+      next += 1;
+    }
+  }
+  const remaining = allBranchIds.filter((branchId) => !rank.has(branchId)).sort((left, right) => compareStrings(left, right));
+  for (const branchId of remaining) {
+    if (!rank.has(branchId)) {
+      rank.set(branchId, next);
+      next += 1;
+    }
+  }
+  return rank;
+}
+function pickByPriority(values, branchRank) {
+  let chosen = values[0];
+  let chosenRank = branchRank.get(chosen.branchId) ?? Number.MAX_SAFE_INTEGER;
+  for (const candidate of values.slice(1)) {
+    const candidateRank = branchRank.get(candidate.branchId) ?? Number.MAX_SAFE_INTEGER;
+    if (candidateRank < chosenRank) {
+      chosen = candidate;
+      chosenRank = candidateRank;
+    } else if (candidateRank === chosenRank && canonicalValueKey(candidate.value) < canonicalValueKey(chosen.value)) {
+      chosen = candidate;
+    }
+  }
+  return chosen.value;
+}
+function pickByWeight(values, weights, branchRank) {
+  let chosen = values[0];
+  let chosenWeight = weights.get(chosen.branchId) ?? 0;
+  let chosenRank = branchRank.get(chosen.branchId) ?? Number.MAX_SAFE_INTEGER;
+  for (const candidate of values.slice(1)) {
+    const candidateWeight = weights.get(candidate.branchId) ?? 0;
+    const candidateRank = branchRank.get(candidate.branchId) ?? Number.MAX_SAFE_INTEGER;
+    if (candidateWeight > chosenWeight) {
+      chosen = candidate;
+      chosenWeight = candidateWeight;
+      chosenRank = candidateRank;
+      continue;
+    }
+    if (candidateWeight === chosenWeight) {
+      if (candidateRank < chosenRank) {
+        chosen = candidate;
+        chosenRank = candidateRank;
+      } else if (candidateRank === chosenRank && canonicalValueKey(candidate.value) < canonicalValueKey(chosen.value)) {
+        chosen = candidate;
+      }
+    }
+  }
+  return chosen.value;
+}
+function allValuesEqual(values) {
+  if (values.length <= 1) {
+    return true;
+  }
+  const first = canonicalValueKey(values[0].value);
+  return values.every(
+    (candidate) => canonicalValueKey(candidate.value) === first
+  );
+}
+function collectConflictingValues(property, contributions) {
+  const seen = /* @__PURE__ */ new Set();
+  const values = [];
+  for (const { branchId, props } of contributions) {
+    if (!(property in props)) {
+      continue;
+    }
+    const value = props[property];
+    const dedupeKey2 = `${branchId}\0${canonicalValueKey(value)}`;
+    if (seen.has(dedupeKey2)) {
+      continue;
+    }
+    seen.add(dedupeKey2);
+    values.push({ branchId, value });
+  }
+  return [...values].sort((left, right) => {
+    const byBranch = compareStrings(left.branchId, right.branchId);
+    return byBranch === 0 ? compareStrings(
+      canonicalValueKey(left.value),
+      canonicalValueKey(right.value)
+    ) : byBranch;
+  });
+}
+function resolveConflictValue(input, context, branchRank, makeConflict) {
+  if (allValuesEqual(input.values)) {
+    return {
+      value: input.values[0]?.value ?? input.canonicalValue,
+      conflicted: false
+    };
+  }
+  const { policy } = context;
+  if (policy === "flag") {
+    return { value: input.canonicalValue, conflicted: true };
+  }
+  if (policy === "lastWriteWins") {
+    return {
+      value: pickByPriority(input.values, branchRank),
+      conflicted: true
+    };
+  }
+  if (policy === "provenanceWeighted") {
+    const weights = context.weights ?? /* @__PURE__ */ new Map();
+    return {
+      value: pickByWeight(input.values, weights, branchRank),
+      conflicted: true
+    };
+  }
+  const provisional = pickByPriority(input.values, branchRank);
+  const resolved = policy(makeConflict(provisional));
+  return { value: resolved, conflicted: true };
+}
+function resolvePropertyUnion(input, context, branchRank) {
+  const makeRecord = (resolution) => ({
+    entityId: input.entityId,
+    kind: input.kind,
+    property: input.property,
+    values: input.reportedValues,
+    resolution
+  });
+  const resolved = resolveConflictValue(
+    {
+      property: input.property,
+      values: input.values,
+      canonicalValue: input.canonicalValue
+    },
+    context,
+    branchRank,
+    (resolution) => makeRecord(resolution)
+  );
+  return {
+    value: resolved.value,
+    conflict: resolved.conflicted ? makeRecord(resolved.value) : void 0
+  };
+}
+
+// src/graph-merge/canonicalize.ts
+var BASE_PROVENANCE_BRANCH = asBranchId("__committed_base__");
+function pickClusterSurvivor(members, cluster, canonicalOverride, preferKind) {
+  const byKey = (left, right) => compareMergeKeys(mergeKeyOf(left), mergeKeyOf(right));
+  const baseMembers = members.filter((member) => member.origin === "base").sort(byKey);
+  if (baseMembers.length > 0) {
+    return baseMembers[0];
+  }
+  let canonicalId;
+  if (canonicalOverride !== void 0) {
+    const chosen = canonicalOverride({ members: cluster.members.map(idOf) });
+    if (members.some((member) => member.id === chosen)) {
+      canonicalId = chosen;
+    }
+  }
+  if (canonicalId === void 0) {
+    const minIdentity = [...cluster.members].sort(
+      (left, right) => compareMergeKeys(left, right)
+    )[0];
+    canonicalId = minIdentity === void 0 ? members[0].id : idOf(minIdentity);
+  }
+  const membersAtId = members.filter((member) => member.id === canonicalId);
+  if (membersAtId.length === 0) {
+    return [...members].sort(byKey)[0];
+  }
+  const kinds = [...new Set(membersAtId.map((member) => member.kind))];
+  const chosenKind = preferKind !== void 0 && kinds.length > 1 ? preferKind(kinds) : void 0;
+  return (chosenKind === void 0 ? void 0 : membersAtId.find((member) => member.kind === chosenKind)) ?? [...membersAtId].sort(byKey)[0];
+}
+function findPreferredMember(members, property, preferredBranchId) {
+  if (preferredBranchId === void 0) {
+    return void 0;
+  }
+  return members.find(
+    (member) => member.branchId === preferredBranchId && property in member.props
+  );
+}
+function memberPropertyValue(member, property) {
+  if (!(property in member.props)) {
+    return void 0;
+  }
+  return member.props[property];
+}
+function pickCanonicalPropertyValue(canonicalMember, members, property, values, preferredBranchId) {
+  const preferredMember = findPreferredMember(
+    members,
+    property,
+    preferredBranchId
+  );
+  const preferredValue = preferredMember === void 0 ? void 0 : memberPropertyValue(preferredMember, property);
+  if (preferredValue !== void 0) {
+    return preferredValue;
+  }
+  const canonicalValue = memberPropertyValue(canonicalMember, property);
+  return canonicalValue === void 0 ? values[0].value : canonicalValue;
+}
+function unionProperties(canonicalMember, members, context, baseContext, branchRank, preferredBranchId) {
+  const canonicalId = canonicalMember.id;
+  const kind = canonicalMember.kind;
+  const hasBaseMember = members.some((member) => member.origin === "base");
+  const propertyNames = /* @__PURE__ */ new Set();
+  for (const member of members) {
+    for (const name of Object.keys(member.props)) {
+      propertyNames.add(name);
+    }
+  }
+  const props = {};
+  const conflicts = [];
+  for (const property of [...propertyNames].sort(
+    (left, right) => compareStrings(left, right)
+  )) {
+    const values = collectConflictingValues(property, members);
+    if (values.length === 0) {
+      continue;
+    }
+    const canonicalValue = pickCanonicalPropertyValue(
+      canonicalMember,
+      members,
+      property,
+      values,
+      preferredBranchId
+    );
+    const baseInvolved = hasBaseMember && members.some(
+      (member) => member.origin === "base" && property in member.props
+    );
+    const reportedValues = values.filter(
+      (value2) => value2.branchId !== BASE_PROVENANCE_BRANCH && value2.branchId !== preferredBranchId
+    );
+    const { value, conflict } = resolvePropertyUnion(
+      {
+        entityId: canonicalId,
+        kind,
+        property,
+        values,
+        reportedValues,
+        canonicalValue
+      },
+      baseInvolved ? baseContext : context,
+      branchRank
+    );
+    props[property] = value;
+    if (conflict !== void 0) {
+      conflicts.push(conflict);
+    }
+  }
+  return { props, conflicts };
+}
+function canonicalizeCluster(cluster, members, policy, branchRank, weights, canonicalOverride, basePolicy = "flag", preferKind, preferredBranchId) {
+  const survivor = pickClusterSurvivor(
+    members,
+    cluster,
+    canonicalOverride,
+    preferKind
+  );
+  const canonicalId = survivor.id;
+  const kind = survivor.kind;
+  const context = {
+    policy,
+    ...weights === void 0 ? {} : { weights }
+  };
+  const baseContext = {
+    policy: basePolicy,
+    ...weights === void 0 ? {} : { weights }
+  };
+  const { props, conflicts } = unionProperties(
+    survivor,
+    members,
+    context,
+    baseContext,
+    branchRank,
+    preferredBranchId
+  );
+  const memberIds = [
+    ...new Set(cluster.members.map((member) => idOf(member)))
+  ].sort((left, right) => compareStrings(left, right));
+  const branchOrigins = [
+    ...new Set(
+      members.map((member) => member.branchId).filter(
+        (branchId) => branchId !== BASE_PROVENANCE_BRANCH && branchId !== preferredBranchId
+      )
+    )
+  ].sort((left, right) => compareStrings(left, right));
+  const resolution = {
+    canonicalId,
+    memberIds,
+    kind,
+    branchOrigins
+  };
+  return { canonicalId, kind, props, resolution, conflicts };
+}
+
+// src/graph-merge/union-find.ts
+var UnionFind = class {
+  constructor(compare) {
+    this.compare = compare;
+  }
+  parent = /* @__PURE__ */ new Map();
+  /** Adds `value` as its own singleton set if it is not already present. */
+  add(value) {
+    if (!this.parent.has(value)) {
+      this.parent.set(value, value);
+    }
+  }
+  /** Returns the representative of `value`'s set, compressing the path to it. */
+  find(value) {
+    this.add(value);
+    let root = value;
+    while (this.parent.get(root) !== root) {
+      root = this.parent.get(root);
+    }
+    let cursor = value;
+    while (cursor !== root) {
+      const next = this.parent.get(cursor);
+      this.parent.set(cursor, root);
+      cursor = next;
+    }
+    return root;
+  }
+  /** Merges the sets of `left` and `right`; the `compare`-minimal root wins. */
+  union(left, right) {
+    const leftRoot = this.find(left);
+    const rightRoot = this.find(right);
+    if (leftRoot === rightRoot) {
+      return;
+    }
+    if (this.compare(leftRoot, rightRoot) <= 0) {
+      this.parent.set(rightRoot, leftRoot);
+    } else {
+      this.parent.set(leftRoot, rightRoot);
+    }
+  }
+  /** Every value seen by {@link add}/{@link find}/{@link union}, insertion order. */
+  members() {
+    return [...this.parent.keys()];
+  }
+};
+
+// src/graph-merge/closures.ts
+var SUB_CLASS_OF_META_EDGE = "subClassOf";
+var EQUIVALENT_TO_META_EDGE = "equivalentTo";
+function buildSubClassClosure(ontology) {
+  const unionFind = new UnionFind(compareStrings);
+  for (const relation of ontology) {
+    unionFind.add(relation.from);
+    unionFind.add(relation.to);
+    if (relation.metaEdge === EQUIVALENT_TO_META_EDGE) {
+      unionFind.union(relation.from, relation.to);
+    }
+  }
+  const canonicalOf = /* @__PURE__ */ new Map();
+  for (const value of unionFind.members()) {
+    canonicalOf.set(value, unionFind.find(value));
+  }
+  const relationKeys = /* @__PURE__ */ new Set();
+  const relations = [];
+  for (const relation of ontology) {
+    if (relation.metaEdge !== SUB_CLASS_OF_META_EDGE) {
+      continue;
+    }
+    const child = canonicalOf.get(relation.from) ?? relation.from;
+    const parent = canonicalOf.get(relation.to) ?? relation.to;
+    if (child === parent) {
+      continue;
+    }
+    const key = `${child}\0${parent}`;
+    if (relationKeys.has(key)) {
+      continue;
+    }
+    relationKeys.add(key);
+    relations.push([child, parent]);
+  }
+  return {
+    closure: computeTransitiveClosure(relations),
+    canonicalOf
+  };
+}
+function canonicalType(closure, type) {
+  return closure.canonicalOf.get(type) ?? type;
+}
+function isReachable2(closure, from, to) {
+  const fromRep = canonicalType(closure, from);
+  const toRep = canonicalType(closure, to);
+  if (fromRep === toRep) {
+    return from !== to;
+  }
+  return isReachable(closure.closure, fromRep, toRep);
+}
+
+// src/graph-merge/similarity.ts
+var MIN_SCORE = 0;
+var MAX_SCORE = 1;
+var NO_EVIDENCE_SCORE = -1;
+var TRIGRAM_LENGTH = 3;
+var TRIGRAM_PAD = " ";
+function clampScore(value) {
+  if (Number.isNaN(value)) {
+    return MIN_SCORE;
+  }
+  if (value < MIN_SCORE) {
+    return MIN_SCORE;
+  }
+  if (value > MAX_SCORE) {
+    return MAX_SCORE;
+  }
+  return value;
+}
+function readField(node, field) {
+  return node[field];
+}
+function fieldText(node, fields) {
+  const parts = [];
+  for (const field of fields) {
+    const value = readField(node, field);
+    if (value === void 0 || value === null) {
+      continue;
+    }
+    parts.push(stringifyFieldValue(value));
+  }
+  return parts.join(TRIGRAM_PAD).toLowerCase();
+}
+function stringifyFieldValue(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  return canonicalValueKey(value);
+}
+function trigramMultiset(text) {
+  const counts = /* @__PURE__ */ new Map();
+  if (text.length === 0) {
+    return counts;
+  }
+  const padded = `${TRIGRAM_PAD}${text}${TRIGRAM_PAD}`;
+  for (let index = 0; index + TRIGRAM_LENGTH <= padded.length; index += 1) {
+    const gram = padded.slice(index, index + TRIGRAM_LENGTH);
+    counts.set(gram, (counts.get(gram) ?? 0) + 1);
+  }
+  return counts;
+}
+function multisetSize(counts) {
+  let total = 0;
+  for (const count of counts.values()) {
+    total += count;
+  }
+  return total;
+}
+function multisetIntersectionSize(left, right) {
+  let shared = 0;
+  for (const [gram, leftCount] of left) {
+    const rightCount = right.get(gram);
+    if (rightCount !== void 0) {
+      shared += Math.min(leftCount, rightCount);
+    }
+  }
+  return shared;
+}
+function diceFromMultisets(left, right) {
+  const leftSize = multisetSize(left);
+  const rightSize = multisetSize(right);
+  if (leftSize === 0 && rightSize === 0) {
+    return MAX_SCORE;
+  }
+  if (leftSize === 0 || rightSize === 0) {
+    return MIN_SCORE;
+  }
+  const shared = multisetIntersectionSize(left, right);
+  return 2 * shared / (leftSize + rightSize);
+}
+function embeddingFields(strategy) {
+  switch (strategy.kind) {
+    case "vector": {
+      return [strategy.field];
+    }
+    case "hybrid": {
+      return strategy.fields;
+    }
+    case "fulltext":
+    case "custom": {
+      return void 0;
+    }
+    default: {
+      const exhaustive = strategy;
+      throw new Error(
+        `Unhandled similarity strategy: ${JSON.stringify(exhaustive)}`
+      );
+    }
+  }
+}
+function cosineSimilarity(left, right) {
+  if (left.length !== right.length || left.length === 0) {
+    return MIN_SCORE;
+  }
+  let dot = 0;
+  let leftMagnitude = 0;
+  let rightMagnitude = 0;
+  for (let index = 0; index < left.length; index += 1) {
+    const leftComponent = left[index];
+    const rightComponent = right[index];
+    dot += leftComponent * rightComponent;
+    leftMagnitude += leftComponent * leftComponent;
+    rightMagnitude += rightComponent * rightComponent;
+  }
+  if (leftMagnitude === 0 || rightMagnitude === 0) {
+    return MIN_SCORE;
+  }
+  return dot / (Math.sqrt(leftMagnitude) * Math.sqrt(rightMagnitude));
+}
+function cosineFromLookup(embeddings, leftText, rightText) {
+  const leftVector = embeddings.get(leftText);
+  const rightVector = embeddings.get(rightText);
+  if (leftVector === void 0 || rightVector === void 0) {
+    return MIN_SCORE;
+  }
+  return cosineSimilarity(leftVector, rightVector);
+}
+var DEFAULT_HYBRID_WEIGHT = 0.5;
+function nonNegativeFinite(value) {
+  return Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+function normalizeHybridWeights(weights) {
+  const vector = nonNegativeFinite(weights?.vector ?? DEFAULT_HYBRID_WEIGHT);
+  const fulltext = nonNegativeFinite(
+    weights?.fulltext ?? DEFAULT_HYBRID_WEIGHT
+  );
+  const total = vector + fulltext;
+  if (total === 0) {
+    return { vector: DEFAULT_HYBRID_WEIGHT, fulltext: DEFAULT_HYBRID_WEIGHT };
+  }
+  return { vector: vector / total, fulltext: fulltext / total };
+}
+function embedderUnavailable(kind, ctx) {
+  return new SimilarityUnavailableError(
+    `Similarity strategy "${kind}" requires a configured embedder (MergeOptions.embedder); none was provided.`,
+    { details: { strategy: kind, dialect: ctx.backend.dialect } }
+  );
+}
+function scoringFields(strategy) {
+  switch (strategy.kind) {
+    case "fulltext":
+    case "hybrid": {
+      return strategy.fields;
+    }
+    case "vector": {
+      return [strategy.field];
+    }
+    case "custom": {
+      return [];
+    }
+    default: {
+      const exhaustive = strategy;
+      throw new Error(
+        `Unhandled similarity strategy: ${JSON.stringify(exhaustive)}`
+      );
+    }
+  }
+}
+var NO_GRAMS = /* @__PURE__ */ new Map();
+function prepareNode(node, strategy) {
+  const text = fieldText(node, scoringFields(strategy));
+  const grams = strategy.kind === "fulltext" || strategy.kind === "hybrid" ? trigramMultiset(text) : NO_GRAMS;
+  return { node, text, grams };
+}
+function scorePrepared(left, right, strategy, ctx) {
+  switch (strategy.kind) {
+    case "custom": {
+      const raw = strategy.score(left.node, right.node);
+      return ok(clampScore(raw));
+    }
+    case "fulltext": {
+      if (left.text.length === 0 || right.text.length === 0) {
+        return ok(NO_EVIDENCE_SCORE);
+      }
+      return ok(clampScore(diceFromMultisets(left.grams, right.grams)));
+    }
+    case "vector": {
+      if (ctx.embeddings === void 0) {
+        return err(embedderUnavailable("vector", ctx));
+      }
+      if (left.text.length === 0 || right.text.length === 0) {
+        return ok(NO_EVIDENCE_SCORE);
+      }
+      const cosine = cosineFromLookup(ctx.embeddings, left.text, right.text);
+      return ok(clampScore(cosine));
+    }
+    case "hybrid": {
+      if (ctx.embeddings === void 0) {
+        return err(embedderUnavailable("hybrid", ctx));
+      }
+      if (left.text.length === 0 || right.text.length === 0) {
+        return ok(NO_EVIDENCE_SCORE);
+      }
+      const vectorScore = clampScore(
+        cosineFromLookup(ctx.embeddings, left.text, right.text)
+      );
+      const fulltextScore = diceFromMultisets(left.grams, right.grams);
+      const weights = normalizeHybridWeights(strategy.weights);
+      return ok(
+        clampScore(
+          weights.vector * vectorScore + weights.fulltext * fulltextScore
+        )
+      );
+    }
+    default: {
+      const exhaustive = strategy;
+      throw new Error(
+        `Unhandled similarity strategy: ${JSON.stringify(exhaustive)}`
+      );
+    }
+  }
+}
+function createPairScorer(strategy, ctx) {
+  const prepared = /* @__PURE__ */ new Map();
+  const prepare = (key, node) => {
+    const cached = prepared.get(key);
+    if (cached !== void 0) {
+      return cached;
+    }
+    const fresh = prepareNode(node, strategy);
+    prepared.set(key, fresh);
+    return fresh;
+  };
+  return (a, left, b, right) => scorePrepared(prepare(a, left), prepare(b, right), strategy, ctx);
+}
+
+// src/graph-merge/scoring.ts
+var FORCED_MATCH_SCORE = 1;
+function compareCandidateEdges(left, right) {
+  const byA = compareMergeKeys(left.a, right.a);
+  return byA === 0 ? compareMergeKeys(left.b, right.b) : byA;
+}
+function endpointKey(a, b) {
+  return JSON.stringify([a, b]);
+}
+function scoreCandidates(input, resolveConfig, ctx, ceilingPolicy, maxComparisonsPerKind) {
+  const { similarity, threshold } = resolveConfig;
+  const seen = /* @__PURE__ */ new Set();
+  const forced = [];
+  for (const edge of input.forcedEdges) {
+    const key = endpointKey(edge.a, edge.b);
+    if (!seen.has(key)) {
+      seen.add(key);
+      forced.push(edge);
+    }
+  }
+  const fuzzy = [];
+  for (const pair of input.pairs) {
+    const key = endpointKey(pair.a, pair.b);
+    if (!seen.has(key)) {
+      seen.add(key);
+      fuzzy.push(pair);
+    }
+  }
+  if (maxComparisonsPerKind !== void 0 && fuzzy.length > maxComparisonsPerKind) {
+    if (ceilingPolicy === "error") {
+      return err(
+        new MergeError(
+          `Comparison ceiling exceeded: ${fuzzy.length} candidate pairs > maxComparisonsPerKind ${maxComparisonsPerKind}.`,
+          {
+            details: {
+              comparisons: fuzzy.length,
+              limit: maxComparisonsPerKind
+            },
+            suggestion: `Tighten the kind's block() to shrink buckets, or set onComparisonCeiling: "mergeByIdOnly".`
+          }
+        )
+      );
+    }
+    return ok({
+      edges: [...forced].sort(
+        (left, right) => compareCandidateEdges(left, right)
+      ),
+      warnings: [
+        {
+          kind: "comparisonCeiling",
+          comparisons: fuzzy.length,
+          limit: maxComparisonsPerKind,
+          message: `Skipped similarity for this kind: ${fuzzy.length} candidate pairs exceeded maxComparisonsPerKind ${maxComparisonsPerKind}; nodes will merge by id and exact unique match only.`
+        }
+      ]
+    });
+  }
+  const scorer = createPairScorer(similarity, ctx);
+  const edges = [...forced];
+  for (const { left, right, a, b } of fuzzy) {
+    const scored = scorer(a, left, b, right);
+    if (isErr(scored)) {
+      return err(scored.error);
+    }
+    if (scored.data >= threshold) {
+      edges.push({ a, b, score: scored.data });
+    }
+  }
+  return ok({
+    edges: edges.sort((left, right) => compareCandidateEdges(left, right)),
+    warnings: []
+  });
+}
+
+// src/graph-merge/clustering.ts
+function buildComponents(edges, nodeIds, edgesSorted = false) {
+  const forest = new UnionFind(compareMergeKeys);
+  const seed = new Set(nodeIds);
+  for (const id of nodeIds) {
+    forest.add(id);
+  }
+  const orderedEdges = edgesSorted ? edges : [...edges].sort((left, right) => compareCandidateEdges(left, right));
+  for (const edge of orderedEdges) {
+    if (!seed.has(edge.a) || !seed.has(edge.b)) {
+      continue;
+    }
+    forest.union(edge.a, edge.b);
+  }
+  const byRoot = /* @__PURE__ */ new Map();
+  for (const id of forest.members()) {
+    const root = forest.find(id);
+    const bucket = byRoot.get(root);
+    if (bucket === void 0) {
+      byRoot.set(root, [id]);
+    } else {
+      bucket.push(id);
+    }
+  }
+  const clusters = [];
+  for (const members of byRoot.values()) {
+    clusters.push({
+      members: [...members].sort(
+        (left, right) => compareMergeKeys(left, right)
+      )
+    });
+  }
+  clusters.sort(
+    (left, right) => compareMergeKeys(left.members[0], right.members[0])
+  );
+  return clusters;
+}
+function adjacencyOf(members, edges) {
+  const memberSet = new Set(members);
+  const adjacency = /* @__PURE__ */ new Map();
+  for (const id of members) {
+    adjacency.set(id, /* @__PURE__ */ new Set());
+  }
+  for (const edge of edges) {
+    if (memberSet.has(edge.a) && memberSet.has(edge.b)) {
+      adjacency.get(edge.a).add(edge.b);
+      adjacency.get(edge.b).add(edge.a);
+    }
+  }
+  return adjacency;
+}
+function exceedsDiameter(members, edges, maxDiameter) {
+  if (members.length <= 1) {
+    return false;
+  }
+  const adjacency = adjacencyOf(members, edges);
+  for (const source of members) {
+    const distance = /* @__PURE__ */ new Map([[source, 0]]);
+    const queue = [source];
+    let head = 0;
+    while (head < queue.length) {
+      const current = queue[head];
+      head += 1;
+      const currentDistance = distance.get(current);
+      for (const neighbor of adjacency.get(current)) {
+        if (!distance.has(neighbor)) {
+          const neighborDistance = currentDistance + 1;
+          if (neighborDistance > maxDiameter) {
+            return true;
+          }
+          distance.set(neighbor, neighborDistance);
+          queue.push(neighbor);
+        }
+      }
+    }
+    if (distance.size < members.length) {
+      return true;
+    }
+  }
+  return false;
+}
+function internalEdges(members, edges) {
+  const memberSet = new Set(members);
+  return edges.filter((edge) => memberSet.has(edge.a) && memberSet.has(edge.b)).sort((left, right) => compareCandidateEdges(left, right));
+}
+function weakestEdge(edges) {
+  return edges.reduce((current, candidate) => {
+    if (candidate.score !== current.score) {
+      return candidate.score < current.score ? candidate : current;
+    }
+    return compareCandidateEdges(candidate, current) < 0 ? candidate : current;
+  });
+}
+function splitUntil(members, edges, isOffending) {
+  let surviving = internalEdges(members, edges);
+  for (; ; ) {
+    const components = buildComponents(surviving, members, true);
+    const offending = components.filter(
+      (component) => isOffending(component.members, surviving)
+    );
+    if (offending.length === 0) {
+      return components;
+    }
+    let splittable;
+    for (const component of offending) {
+      const componentEdges = internalEdges(component.members, surviving);
+      if (componentEdges.length > 0) {
+        splittable = componentEdges;
+        break;
+      }
+    }
+    if (splittable === void 0) {
+      const offendingSet = new Set(offending);
+      return components.flatMap(
+        (component) => offendingSet.has(component) ? component.members.map((id) => ({ members: [id] })) : [component]
+      );
+    }
+    const weakest = weakestEdge(splittable);
+    surviving = surviving.filter((edge) => edge !== weakest);
+  }
+}
+function splitByDropWeakest(members, edges, maxDiameter) {
+  return splitUntil(
+    members,
+    edges,
+    (componentMembers, surviving) => exceedsDiameter(componentMembers, surviving, maxDiameter)
+  );
+}
+function connectedComponents(candidateEdges, nodeIds) {
+  return buildComponents(candidateEdges, nodeIds);
+}
+function enforceDiameter(clusters, candidateEdges, clusterMaxDiameter) {
+  const guarded = [];
+  for (const component of clusters) {
+    if (exceedsDiameter(component.members, candidateEdges, clusterMaxDiameter)) {
+      guarded.push(
+        ...splitByDropWeakest(
+          component.members,
+          candidateEdges,
+          clusterMaxDiameter
+        )
+      );
+    } else {
+      guarded.push(component);
+    }
+  }
+  guarded.sort(
+    (left, right) => compareMergeKeys(left.members[0], right.members[0])
+  );
+  return guarded;
+}
+function countBaseMembers(members, baseIds) {
+  let count = 0;
+  for (const id of members) {
+    if (baseIds.has(id)) {
+      count += 1;
+    }
+  }
+  return count;
+}
+function splitByBaseMultiplicity(members, edges, baseIds) {
+  return splitUntil(
+    members,
+    edges,
+    (componentMembers) => countBaseMembers(componentMembers, baseIds) >= 2
+  );
+}
+function enforceBaseGuard(clusters, candidateEdges, baseIds) {
+  if (baseIds.size === 0) {
+    return { clusters, events: [] };
+  }
+  const result = [];
+  const events = [];
+  for (const cluster of clusters) {
+    const clusterBaseIds = cluster.members.filter((id) => baseIds.has(id));
+    if (clusterBaseIds.length < 2) {
+      result.push(cluster);
+      continue;
+    }
+    events.push({
+      baseIds: [...clusterBaseIds].sort(
+        (left, right) => compareMergeKeys(left, right)
+      ),
+      memberIds: [...cluster.members].sort(
+        (left, right) => compareMergeKeys(left, right)
+      )
+    });
+    result.push(
+      ...splitByBaseMultiplicity(cluster.members, candidateEdges, baseIds)
+    );
+  }
+  result.sort(
+    (left, right) => compareMergeKeys(left.members[0], right.members[0])
+  );
+  return { clusters: result, events };
+}
+
+// src/graph-merge/delete-modify.ts
+var DELETED_NODE_DROP_REASON = "delete-modify:deleteWins";
+function pickHighestPriorityBranch(branchIds, branchRank) {
+  let chosen = branchIds[0];
+  let chosenRank = branchRank.get(chosen) ?? Number.MAX_SAFE_INTEGER;
+  for (const candidate of branchIds.slice(1)) {
+    const candidateRank = branchRank.get(candidate) ?? Number.MAX_SAFE_INTEGER;
+    if (candidateRank < chosenRank || candidateRank === chosenRank && compareStrings(candidate, chosen) < 0) {
+      chosen = candidate;
+      chosenRank = candidateRank;
+    }
+  }
+  return chosen;
+}
+function effectiveDeleteModifyPolicy(policy, deletions, modifications, preferredBranchId) {
+  if (preferredBranchId !== void 0 && deletions.some((deletion) => deletion.branchId === preferredBranchId)) {
+    return "deleteWins";
+  }
+  if (policy === "deleteWins" && preferredBranchId !== void 0 && modifications.some(
+    (modification) => modification.branchId === preferredBranchId
+  )) {
+    return "modifyWins";
+  }
+  return policy;
+}
+function groupByEntity(items, entityOf) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const entity = entityOf(item);
+    const key = mergeKey(entity.kind, entity.id);
+    const bucket = grouped.get(key);
+    if (bucket === void 0) {
+      grouped.set(key, [item]);
+    } else {
+      bucket.push(item);
+    }
+  }
+  return grouped;
+}
+function resolveDeleteModifyOver(modified, deleted, modifiedEntity, deletedEntity, droppedKind, policy, branchRank, preferredBranchId) {
+  const modifiedByKey = groupByEntity(modified, modifiedEntity);
+  const deletedByKey = groupByEntity(deleted, deletedEntity);
+  const survivingModifications = [];
+  const deletions = [];
+  const conflicts = [];
+  const dropped = [];
+  const conflictedKeys = /* @__PURE__ */ new Set();
+  for (const key of deletedByKey.keys()) {
+    if (modifiedByKey.has(key)) {
+      conflictedKeys.add(key);
+    }
+  }
+  for (const [key, modifications] of modifiedByKey) {
+    if (!conflictedKeys.has(key)) {
+      for (const modification of modifications) {
+        survivingModifications.push(modification);
+      }
+      continue;
+    }
+    const deletionsForKey = deletedByKey.get(key);
+    const { id, kind } = modifiedEntity(modifications[0]);
+    const deletedBy = pickHighestPriorityBranch(
+      deletionsForKey.map((deletion) => deletion.branchId),
+      branchRank
+    );
+    const modifiedBy = pickHighestPriorityBranch(
+      modifications.map((modification) => modification.branchId),
+      branchRank
+    );
+    const effectivePolicy = effectiveDeleteModifyPolicy(
+      policy,
+      deletionsForKey,
+      modifications,
+      preferredBranchId
+    );
+    conflicts.push({
+      entityId: id,
+      kind,
+      deletedBy,
+      modifiedBy,
+      resolution: effectivePolicy
+    });
+    if (effectivePolicy === "deleteWins") {
+      deletions.push({ id, kind });
+      dropped.push({ kind: droppedKind, id, reason: DELETED_NODE_DROP_REASON });
+      continue;
+    }
+    for (const modification of modifications) {
+      survivingModifications.push(modification);
+    }
+  }
+  for (const [key, deletionsForKey] of deletedByKey) {
+    if (conflictedKeys.has(key)) {
+      continue;
+    }
+    const { id, kind } = deletedEntity(deletionsForKey[0]);
+    deletions.push({ id, kind });
+  }
+  return {
+    survivingModifications: [...survivingModifications].sort((left, right) => {
+      const byId2 = compareStrings(
+        modifiedEntity(left).id,
+        modifiedEntity(right).id
+      );
+      return byId2 === 0 ? compareStrings(left.branchId, right.branchId) : byId2;
+    }),
+    deletions: [...deletions].sort(
+      (left, right) => compareStrings(left.id, right.id)
+    ),
+    conflicts: [...conflicts].sort(
+      (left, right) => compareStrings(left.entityId, right.entityId)
+    ),
+    dropped: [...dropped].sort(
+      (left, right) => compareStrings(left.id, right.id)
+    )
+  };
+}
+function reconcileOver(survivingModifications, entityOf, rebuild, policy, branchRank, weights, preferredBranchId) {
+  const context = {
+    policy,
+    ...weights === void 0 ? {} : { weights }
+  };
+  const grouped = groupByEntity(survivingModifications, entityOf);
+  const out = [];
+  const conflicts = [];
+  for (const modifications of grouped.values()) {
+    if (modifications.length === 1) {
+      out.push(modifications[0]);
+      continue;
+    }
+    const first = entityOf(modifications[0]);
+    const { props, conflicts: propertyConflicts } = threeWayMergeProps(
+      first.id,
+      first.kind,
+      first.baseProps,
+      modifications.map((modification) => ({
+        branchId: modification.branchId,
+        forkProps: entityOf(modification).forkProps
+      })),
+      context,
+      branchRank,
+      preferredBranchId
+    );
+    const chosenBranch = pickHighestPriorityBranch(
+      modifications.map((modification) => modification.branchId),
+      branchRank
+    );
+    const representative = modifications.find(
+      (modification) => modification.branchId === chosenBranch
+    ) ?? modifications[0];
+    out.push(rebuild(representative, chosenBranch, props));
+    for (const conflict of propertyConflicts) {
+      conflicts.push(conflict);
+    }
+  }
+  return {
+    survivingModifications: [...out].sort((left, right) => {
+      const byId2 = compareStrings(entityOf(left).id, entityOf(right).id);
+      return byId2 === 0 ? compareStrings(left.branchId, right.branchId) : byId2;
+    }),
+    conflicts: conflicts.sort(
+      (left, right) => compareStrings(
+        `${left.entityId}|${left.property}`,
+        `${right.entityId}|${right.property}`
+      )
+    )
+  };
+}
+function resolveDeleteModify(staging, policy, branchRank, preferredBranchId) {
+  const resolved = resolveDeleteModifyOver(
+    staging.modifiedNodes,
+    staging.deletedNodes,
+    (item) => item.node,
+    (item) => item.node,
+    "node",
+    policy,
+    branchRank,
+    preferredBranchId
+  );
+  return {
+    survivingModifications: resolved.survivingModifications,
+    nodeDeletions: resolved.deletions,
+    conflicts: resolved.conflicts,
+    dropped: resolved.dropped
+  };
+}
+function threeWayMergeProps(entityId, kind, baseProps, contributions, context, branchRank, preferredBranchId) {
+  const merged = {};
+  const conflicts = [];
+  const propertyNames = new Set(Object.keys(baseProps));
+  for (const contribution of contributions) {
+    for (const name of Object.keys(contribution.forkProps)) {
+      propertyNames.add(name);
+    }
+  }
+  for (const property of [...propertyNames].sort(compareStrings)) {
+    const baseHas = property in baseProps;
+    const baseKey = baseHas ? canonicalValueKey(baseProps[property]) : void 0;
+    const changed = contributions.filter((contribution) => {
+      if (!(property in contribution.forkProps)) {
+        return false;
+      }
+      const value2 = contribution.forkProps[property];
+      return !baseHas || canonicalValueKey(value2) !== baseKey;
+    }).map((contribution) => ({
+      branchId: contribution.branchId,
+      props: contribution.forkProps
+    }));
+    const values = collectConflictingValues(property, changed);
+    if (values.length === 0) {
+      const deletedByFork = baseHas && contributions.some(
+        (contribution) => !(property in contribution.forkProps)
+      );
+      if (baseHas && !deletedByFork) {
+        merged[property] = baseProps[property];
+      }
+      continue;
+    }
+    const distinctValues = new Set(
+      values.map((candidate) => canonicalValueKey(candidate.value))
+    );
+    if (distinctValues.size === 1) {
+      merged[property] = values[0].value;
+      continue;
+    }
+    const preferredValue = values.find(
+      (value2) => value2.branchId === preferredBranchId
+    )?.value;
+    const canonicalValue = preferredValue ?? (baseHas ? baseProps[property] : values[0].value);
+    const reportedValues = preferredBranchId === void 0 ? values : values.filter((value2) => value2.branchId !== preferredBranchId);
+    const { value, conflict } = resolvePropertyUnion(
+      { entityId, kind, property, values, reportedValues, canonicalValue },
+      context,
+      branchRank
+    );
+    merged[property] = value;
+    if (conflict !== void 0) {
+      conflicts.push(conflict);
+    }
+  }
+  return { props: merged, conflicts };
+}
+function reconcileModifications(survivingModifications, policy, branchRank, weights, preferredBranchId) {
+  return reconcileOver(
+    survivingModifications,
+    (item) => item.node,
+    (representative, chosenBranch, mergedProps) => ({
+      branchId: chosenBranch,
+      node: { ...representative.node, forkProps: mergedProps }
+    }),
+    policy,
+    branchRank,
+    weights,
+    preferredBranchId
+  );
+}
+function resolveEdgeDeleteModify(staging, policy, branchRank, preferredBranchId) {
+  const resolved = resolveDeleteModifyOver(
+    staging.modifiedEdges,
+    staging.deletedEdges,
+    (item) => item.edge,
+    (item) => item.edge,
+    "edge",
+    policy,
+    branchRank,
+    preferredBranchId
+  );
+  return {
+    survivingModifications: resolved.survivingModifications,
+    edgeDeletions: resolved.deletions,
+    conflicts: resolved.conflicts,
+    dropped: resolved.dropped
+  };
+}
+function reconcileEdgeModifications(survivingModifications, policy, branchRank, weights, preferredBranchId) {
+  return reconcileOver(
+    survivingModifications,
+    (item) => item.edge,
+    (representative, chosenBranch, mergedProps) => ({
+      branchId: chosenBranch,
+      edge: { ...representative.edge, forkProps: mergedProps }
+    }),
+    policy,
+    branchRank,
+    weights,
+    preferredBranchId
+  );
+}
+
+// src/graph-merge/edge-repoint.ts
+var ENDPOINT_DELETED_DROP_REASON = "edge:endpoint-deleted";
+function buildCanonicalMap(clusters, canonicalOf) {
+  const map = /* @__PURE__ */ new Map();
+  for (const cluster of clusters) {
+    const canonical = canonicalOf(cluster);
+    for (const member of cluster.members) {
+      map.set(member, canonical);
+    }
+  }
+  return map;
+}
+function repoint(key, canonicalOf) {
+  return canonicalOf.get(key) ?? key;
+}
+function dedupeKey(fromKey, type, toKey, props) {
+  return JSON.stringify([fromKey, type, toKey, canonicalizeProps(props)]);
+}
+function groupKey(fromKey, type, toKey) {
+  return JSON.stringify([fromKey, type, toKey]);
+}
+function pickSurvivor(edges, preferredBranchId) {
+  const preferred = preferredBranchId === void 0 ? [] : edges.filter((edge) => edge.staged.branchId === preferredBranchId);
+  const candidates = preferred.length > 0 ? preferred : edges;
+  let survivor = candidates[0];
+  for (const candidate of candidates.slice(1)) {
+    if (candidate.staged.id < survivor.staged.id) {
+      survivor = candidate;
+    }
+  }
+  return survivor;
+}
+function unionEdgeProps(survivorId, kind, survivor, edges, context, branchRank, preferredBranchId) {
+  const propertyNames = /* @__PURE__ */ new Set();
+  for (const edge of edges) {
+    for (const name of Object.keys(edge.staged.props)) {
+      propertyNames.add(name);
+    }
+  }
+  const props = {};
+  const conflicts = [];
+  const contributions = edges.map((edge) => edge.staged);
+  for (const property of [...propertyNames].sort(
+    (left, right) => compareStrings(left, right)
+  )) {
+    const values = collectConflictingValues(property, contributions);
+    if (values.length === 0) {
+      continue;
+    }
+    const survivorValue = property in survivor.staged.props ? survivor.staged.props[property] : values[0].value;
+    const canonicalValue = values.find((value2) => value2.branchId === preferredBranchId)?.value ?? survivorValue;
+    const reportedValues = preferredBranchId === void 0 ? values : values.filter((value2) => value2.branchId !== preferredBranchId);
+    const { value, conflict } = resolvePropertyUnion(
+      {
+        entityId: survivorId,
+        kind,
+        property,
+        values,
+        reportedValues,
+        canonicalValue
+      },
+      context,
+      branchRank
+    );
+    props[property] = value;
+    if (conflict !== void 0) {
+      conflicts.push(conflict);
+    }
+  }
+  return { props, conflicts };
+}
+function repointEdges(stagedEdges, canonicalOf, deletedNodeIds, policy, branchRank, weights, preferredBranchId) {
+  const dropped = [];
+  const liveByDedupeKey = /* @__PURE__ */ new Map();
+  const dedupeKeyByGroup = /* @__PURE__ */ new Map();
+  for (const staged of stagedEdges) {
+    const fromKey = repoint(
+      mergeKey(staged.fromKind, staged.fromId),
+      canonicalOf
+    );
+    const toKey = repoint(mergeKey(staged.toKind, staged.toId), canonicalOf);
+    if (deletedNodeIds.has(fromKey) || deletedNodeIds.has(toKey)) {
+      dropped.push({
+        kind: "edge",
+        id: staged.id,
+        reason: ENDPOINT_DELETED_DROP_REASON
+      });
+      continue;
+    }
+    const repointed = { staged, fromKey, toKey };
+    const key = dedupeKey(fromKey, staged.kind, toKey, staged.props);
+    const bucket = liveByDedupeKey.get(key);
+    if (bucket === void 0) {
+      liveByDedupeKey.set(key, [repointed]);
+    } else {
+      bucket.push(repointed);
+    }
+    const group = groupKey(fromKey, staged.kind, toKey);
+    const keysForGroup = dedupeKeyByGroup.get(group);
+    if (keysForGroup === void 0) {
+      dedupeKeyByGroup.set(group, /* @__PURE__ */ new Set([key]));
+    } else {
+      keysForGroup.add(key);
+    }
+  }
+  const context = {
+    policy,
+    ...weights === void 0 ? {} : { weights }
+  };
+  const merged = [];
+  const conflicts = [];
+  const sortedGroups = [...dedupeKeyByGroup.keys()].sort(
+    (left, right) => compareStrings(left, right)
+  );
+  for (const group of sortedGroups) {
+    const dedupeKeys = [...dedupeKeyByGroup.get(group)];
+    const groupEdges = [];
+    for (const key of dedupeKeys) {
+      for (const edge of liveByDedupeKey.get(key)) {
+        groupEdges.push(edge);
+      }
+    }
+    const survivor = pickSurvivor(groupEdges, preferredBranchId);
+    const survivorId = survivor.staged.id;
+    const mergedIds = [...groupEdges].map((edge) => edge.staged.id).sort((left, right) => compareStrings(left, right));
+    const fromId = idOf(survivor.fromKey);
+    const fromKind = kindOf(survivor.fromKey);
+    const toId = idOf(survivor.toKey);
+    const toKind = kindOf(survivor.toKey);
+    if (dedupeKeys.length === 1) {
+      merged.push({
+        id: survivorId,
+        kind: survivor.staged.kind,
+        fromId,
+        toId,
+        fromKind,
+        toKind,
+        props: survivor.staged.props,
+        mergedIds
+      });
+      continue;
+    }
+    const { props, conflicts: groupConflicts } = unionEdgeProps(
+      survivorId,
+      survivor.staged.kind,
+      survivor,
+      groupEdges,
+      context,
+      branchRank,
+      preferredBranchId
+    );
+    for (const conflict of groupConflicts) {
+      conflicts.push(conflict);
+    }
+    merged.push({
+      id: survivorId,
+      kind: survivor.staged.kind,
+      fromId,
+      toId,
+      fromKind,
+      toKind,
+      props,
+      mergedIds
+    });
+  }
+  const sortedEdges = merged.map((edge) => ({
+    edge,
+    sortKey: dedupeKey(
+      mergeKey(edge.fromKind, edge.fromId),
+      edge.kind,
+      mergeKey(edge.toKind, edge.toId),
+      edge.props
+    )
+  })).sort((left, right) => compareStrings(left.sortKey, right.sortKey)).map(({ edge }) => edge);
+  return {
+    edges: sortedEdges,
+    dropped: dropped.sort((left, right) => compareStrings(left.id, right.id)),
+    conflicts: conflicts.sort(
+      (left, right) => compareStrings(
+        `${left.entityId}|${left.property}`,
+        `${right.entityId}|${right.property}`
+      )
+    )
+  };
+}
+var MERGE_OPTION_DEFAULTS = {
+  reconcileTypes: "off",
+  onPropertyConflict: "flag",
+  onBasePropertyConflict: "flag",
+  onDeleteModifyConflict: "flag",
+  onComparisonCeiling: "error",
+  provenance: true,
+  persistProvenance: false
+};
+var propertyConflictPolicySchema = z.enum([
+  "flag",
+  "lastWriteWins",
+  "provenanceWeighted"
+]);
+var resolveConfigScalarSchema = z.object({
+  threshold: z.number().min(0, { message: "threshold must be >= 0" }).max(1, { message: "threshold must be <= 1" })
+});
+var mergeOptionsScalarSchema = z.object({
+  reconcileTypes: z.enum(["ontology", "off"]).default(MERGE_OPTION_DEFAULTS.reconcileTypes),
+  onDeleteModifyConflict: z.enum(["deleteWins", "modifyWins", "flag"]).default(MERGE_OPTION_DEFAULTS.onDeleteModifyConflict),
+  onComparisonCeiling: z.enum(["error", "mergeByIdOnly"]).default(MERGE_OPTION_DEFAULTS.onComparisonCeiling),
+  provenance: z.boolean().default(MERGE_OPTION_DEFAULTS.provenance),
+  persistProvenance: z.boolean().default(MERGE_OPTION_DEFAULTS.persistProvenance),
+  maxComparisonsPerKind: z.number().int({ message: "maxComparisonsPerKind must be an integer" }).min(0, { message: "maxComparisonsPerKind must be >= 0" }).optional(),
+  clusterMaxDiameter: z.number().positive({ message: "clusterMaxDiameter must be positive" }).optional()
+});
+function validatePropertyConflictPolicy(policy, label) {
+  if (typeof policy === "string" && !propertyConflictPolicySchema.safeParse(policy).success) {
+    throw new Error(
+      `Invalid ${label} "${policy}": expected "flag", "lastWriteWins", "provenanceWeighted", or a function.`
+    );
+  }
+  return policy;
+}
+function validateResolveMap(resolve) {
+  if (resolve === void 0) {
+    return {};
+  }
+  const configs = resolve;
+  const validated = {};
+  for (const [kind, config] of Object.entries(configs)) {
+    const parsed = resolveConfigScalarSchema.safeParse({
+      threshold: config.threshold
+    });
+    if (!parsed.success) {
+      throw new Error(
+        `Invalid resolve config for kind "${kind}": ${parsed.error.message}`
+      );
+    }
+    if (config.keyless !== void 0 && (!Number.isInteger(config.keyless.window) || config.keyless.window < 1)) {
+      throw new Error(
+        `Invalid resolve config for kind "${kind}": keyless.window must be a positive integer, got ${config.keyless.window}.`
+      );
+    }
+    const strategy = config.similarity;
+    if (strategy.kind === "hybrid") {
+      for (const component of ["vector", "fulltext"]) {
+        const weight = strategy.weights?.[component];
+        if (weight !== void 0 && (!Number.isFinite(weight) || weight < 0)) {
+          throw new Error(
+            `Invalid resolve config for kind "${kind}": similarity.weights.${component} must be a finite number >= 0, got ${String(weight)}.`
+          );
+        }
+      }
+    }
+    validated[kind] = config;
+  }
+  return validated;
+}
+function validateProvenanceWeights(weights) {
+  for (const [branchId, weight] of weights) {
+    if (!Number.isFinite(weight) || weight < 0) {
+      throw new Error(
+        `Invalid provenanceWeights for branch "${branchId}": weight must be a finite number >= 0, got ${String(weight)}.`
+      );
+    }
+  }
+  return weights;
+}
+function normalizeMergeOptions(options = {}) {
+  const scalar = mergeOptionsScalarSchema.parse({
+    reconcileTypes: options.reconcileTypes,
+    onDeleteModifyConflict: options.onDeleteModifyConflict,
+    onComparisonCeiling: options.onComparisonCeiling,
+    provenance: options.provenance,
+    persistProvenance: options.persistProvenance,
+    ...options.maxComparisonsPerKind === void 0 ? {} : { maxComparisonsPerKind: options.maxComparisonsPerKind },
+    ...options.clusterMaxDiameter === void 0 ? {} : { clusterMaxDiameter: options.clusterMaxDiameter }
+  });
+  const onPropertyConflict = validatePropertyConflictPolicy(
+    options.onPropertyConflict ?? MERGE_OPTION_DEFAULTS.onPropertyConflict,
+    "onPropertyConflict"
+  );
+  const onBasePropertyConflict = validatePropertyConflictPolicy(
+    options.onBasePropertyConflict ?? MERGE_OPTION_DEFAULTS.onBasePropertyConflict,
+    "onBasePropertyConflict"
+  );
+  const provenanceWeights = options.provenanceWeights === void 0 ? void 0 : validateProvenanceWeights(options.provenanceWeights);
+  const usesProvenanceWeighting = onPropertyConflict === "provenanceWeighted" || onBasePropertyConflict === "provenanceWeighted";
+  if (usesProvenanceWeighting && (provenanceWeights === void 0 || provenanceWeights.size === 0)) {
+    throw new Error(
+      'A "provenanceWeighted" property-conflict policy requires a non-empty provenanceWeights map.'
+    );
+  }
+  return {
+    resolve: validateResolveMap(options.resolve),
+    reconcileTypes: scalar.reconcileTypes,
+    onPropertyConflict,
+    onBasePropertyConflict,
+    onDeleteModifyConflict: scalar.onDeleteModifyConflict,
+    onComparisonCeiling: scalar.onComparisonCeiling,
+    provenance: scalar.provenance,
+    persistProvenance: scalar.persistProvenance,
+    ...options.canonical === void 0 ? {} : { canonical: options.canonical },
+    ...options.embedder === void 0 ? {} : { embedder: options.embedder },
+    ...options.target === void 0 ? {} : { target: options.target },
+    ...scalar.maxComparisonsPerKind === void 0 ? {} : { maxComparisonsPerKind: scalar.maxComparisonsPerKind },
+    ...scalar.clusterMaxDiameter === void 0 ? {} : { clusterMaxDiameter: scalar.clusterMaxDiameter },
+    ...options.branchOrder === void 0 ? {} : { branchOrder: options.branchOrder },
+    ...provenanceWeights === void 0 ? {} : { provenanceWeights }
+  };
+}
+var Provenance = defineNode("Provenance", {
+  schema: z.object({
+    targetGraphId: z.string(),
+    role: z.enum(["node", "edge"]),
+    canonicalId: z.string(),
+    canonicalKind: z.string(),
+    branchId: z.string(),
+    sourceId: z.string()
+  })
+});
+function provenanceGraphId(targetGraphId) {
+  return `${targetGraphId}::merge-provenance`;
+}
+function buildProvenanceGraph(targetGraphId) {
+  return defineGraph({
+    id: provenanceGraphId(targetGraphId),
+    nodes: { Provenance: { type: Provenance } },
+    edges: {}
+  });
+}
+async function openProvenanceStore(backend, targetGraphId) {
+  const [store] = await createStoreWithSchema(
+    buildProvenanceGraph(targetGraphId),
+    backend
+  );
+  return store;
+}
+var ID_SEPARATOR = "\0";
+var ID_DIGEST_BYTES = 16;
+async function provenanceNodeId(targetGraphId, record) {
+  const tuple = [
+    targetGraphId,
+    record.role,
+    // canonicalKind is part of node identity: two contributions to different-kind
+    // canonicals that share a bare id (e.g. base Patient:x and Encounter:x) must NOT
+    // hash to the same sidecar row and clobber each other (the (kind,id) identity model).
+    record.canonicalKind,
+    record.canonicalId,
+    record.branchId,
+    record.sourceId
+  ].join(ID_SEPARATOR);
+  const digest = await sha256Hex(tuple, ID_DIGEST_BYTES);
+  return `prov_${digest}`;
+}
+async function persistProvenanceRecords(store, targetGraphId, records) {
+  if (records.length === 0) {
+    return 0;
+  }
+  const items = await Promise.all(
+    records.map(async (record) => ({
+      id: await provenanceNodeId(targetGraphId, record),
+      props: {
+        targetGraphId,
+        role: record.role,
+        canonicalId: record.canonicalId,
+        canonicalKind: record.canonicalKind,
+        branchId: record.branchId,
+        sourceId: record.sourceId
+      }
+    }))
+  );
+  await store.nodes.Provenance.bulkUpsertById(items);
+  return items.length;
+}
+async function readProvenance(store, query = {}) {
+  const all = await store.nodes.Provenance.find();
+  return all.filter(
+    (node) => (query.branchId === void 0 || node.branchId === query.branchId) && (query.canonicalId === void 0 || node.canonicalId === query.canonicalId) && (query.role === void 0 || node.role === query.role)
+  ).sort((left, right) => compareStrings(left.id, right.id));
+}
+
+// src/graph-merge/sources.ts
+function orderEndpoints(left, right) {
+  const leftKey = mergeKeyOf(left);
+  const rightKey = mergeKeyOf(right);
+  return compareMergeKeys(leftKey, rightKey) <= 0 ? { a: leftKey, b: rightKey, left, right } : { a: rightKey, b: leftKey, left: right, right: left };
+}
+function sortMembersById(members) {
+  return [...members].sort((left, right) => compareStrings(left.id, right.id));
+}
+function sortedBucketKeys(blocks) {
+  return [...blocks.keys()].sort((left, right) => compareStrings(left, right));
+}
+var NODE_SYSTEM_FIELDS = /* @__PURE__ */ new Set(["id", "kind", "meta"]);
+function nodeProps(node) {
+  const props = {};
+  for (const [key, value] of Object.entries(
+    node
+  )) {
+    if (!NODE_SYSTEM_FIELDS.has(key)) {
+      props[key] = value;
+    }
+  }
+  return props;
+}
+function keylessConfigFor(resolveConfig) {
+  if (resolveConfig.keyless === void 0) {
+    return void 0;
+  }
+  const strategy = resolveConfig.similarity;
+  const sortFields = strategy.kind === "fulltext" || strategy.kind === "hybrid" ? strategy.fields : strategy.kind === "vector" ? [strategy.field] : [];
+  return { window: resolveConfig.keyless.window, sortFields };
+}
+function windowedPairs(members, config) {
+  const keyed = members.map((node) => ({
+    node,
+    key: fieldText(node, config.sortFields)
+  }));
+  keyed.sort(
+    (left, right) => left.key === right.key ? compareStrings(left.node.id, right.node.id) : compareStrings(left.key, right.key)
+  );
+  const pairs = [];
+  for (let index = 0; index < keyed.length; index += 1) {
+    const last = Math.min(index + config.window, keyed.length - 1);
+    for (let index_ = index + 1; index_ <= last; index_ += 1) {
+      pairs.push(orderEndpoints(keyed[index].node, keyed[index_].node));
+    }
+  }
+  return pairs;
+}
+function pairsFromBlocks(blocks, keyless) {
+  const pairs = [];
+  for (const bucketKey of sortedBucketKeys(blocks)) {
+    if (isUniqueBucketKey(bucketKey)) {
+      continue;
+    }
+    const members = sortMembersById(blocks.get(bucketKey) ?? []);
+    if (keyless !== void 0 && bucketKey === UNBLOCKED_BUCKET_KEY) {
+      pairs.push(...windowedPairs(members, keyless));
+      continue;
+    }
+    for (let index = 0; index < members.length; index += 1) {
+      for (let index_ = index + 1; index_ < members.length; index_ += 1) {
+        pairs.push(orderEndpoints(members[index], members[index_]));
+      }
+    }
+  }
+  return pairs;
+}
+function forcedEdgesFromBlocks(blocks) {
+  const edges = [];
+  for (const bucketKey of sortedBucketKeys(blocks)) {
+    if (!isUniqueBucketKey(bucketKey)) {
+      continue;
+    }
+    const members = sortMembersById(blocks.get(bucketKey) ?? []);
+    for (let index = 0; index < members.length; index += 1) {
+      for (let index_ = index + 1; index_ < members.length; index_ += 1) {
+        const { a, b } = orderEndpoints(members[index], members[index_]);
+        edges.push({ a, b, score: FORCED_MATCH_SCORE });
+      }
+    }
+  }
+  return edges;
+}
+function ontologyRetypeEdges(stagedIdentities, isRetypeCompatible) {
+  const identitiesById = /* @__PURE__ */ new Map();
+  for (const identity of stagedIdentities) {
+    const id = idOf(identity);
+    const bucket = identitiesById.get(id);
+    if (bucket === void 0) {
+      identitiesById.set(id, [identity]);
+    } else {
+      bucket.push(identity);
+    }
+  }
+  const edges = [];
+  for (const id of [...identitiesById.keys()].sort(compareStrings)) {
+    const identities = [...new Set(identitiesById.get(id))].sort(
+      compareMergeKeys
+    );
+    if (identities.length < 2) {
+      continue;
+    }
+    const group = unionByCompatibility(identities, isRetypeCompatible);
+    for (const members of groupsOf(identities, group)) {
+      if (members.length < 2 || !isRetypeCompatible(members.map((identity) => kindOf(identity)))) {
+        continue;
+      }
+      for (let index = 1; index < members.length; index += 1) {
+        edges.push({
+          a: members[0],
+          b: members[index],
+          score: FORCED_MATCH_SCORE
+        });
+      }
+    }
+  }
+  return edges;
+}
+function unionByCompatibility(identities, isRetypeCompatible) {
+  const forest = new UnionFind(compareMergeKeys);
+  for (const identity of identities) {
+    forest.add(identity);
+  }
+  for (let index = 0; index < identities.length; index += 1) {
+    for (let index_ = index + 1; index_ < identities.length; index_ += 1) {
+      if (isRetypeCompatible([
+        kindOf(identities[index]),
+        kindOf(identities[index_])
+      ])) {
+        forest.union(identities[index], identities[index_]);
+      }
+    }
+  }
+  return new Map(
+    identities.map((identity) => [identity, forest.find(identity)])
+  );
+}
+function groupsOf(identities, representativeOf) {
+  const byRoot = /* @__PURE__ */ new Map();
+  for (const identity of identities) {
+    const root = representativeOf.get(identity);
+    const bucket = byRoot.get(root);
+    if (bucket === void 0) {
+      byRoot.set(root, [identity]);
+    } else {
+      bucket.push(identity);
+    }
+  }
+  return [...byRoot.values()].map((group) => [...group].sort(compareMergeKeys));
+}
+var exactKeySource = {
+  id: "exactKey",
+  generate(scope) {
+    return Promise.resolve({
+      pairs: pairsFromBlocks(scope.blocks, scope.keyless),
+      forcedEdges: [],
+      baseMembers: []
+    });
+  }
+};
+var uniqueSource = {
+  id: "unique",
+  generate(scope) {
+    return Promise.resolve({
+      pairs: [],
+      forcedEdges: forcedEdgesFromBlocks(scope.blocks),
+      baseMembers: []
+    });
+  }
+};
+var baseUniqueSource = {
+  id: "baseUnique",
+  async generate(scope) {
+    const { kind, nodes, uniqueConstraints, store } = scope;
+    if (nodes === void 0 || uniqueConstraints === void 0 || store === void 0) {
+      throw new MergeError(
+        "baseUniqueSource requires nodes, uniqueConstraints, and store in the source scope.",
+        { details: { kind, source: "baseUnique" } }
+      );
+    }
+    const collection = store.nodes[kind];
+    if (collection === void 0 || nodes.length === 0) {
+      return { pairs: [], forcedEdges: [], baseMembers: [] };
+    }
+    const forcedEdges = [];
+    const baseMembers = /* @__PURE__ */ new Map();
+    const constraints = [...uniqueConstraints].sort(
+      (left, right) => compareStrings(left.name, right.name)
+    );
+    const items = nodes.map((node) => ({ props: nodeProps(node) }));
+    const matchesByConstraint = await Promise.all(
+      constraints.map(async (constraint) => {
+        try {
+          return await collection.bulkFindByConstraint(constraint.name, items);
+        } catch (error) {
+          throw new MergeError(
+            `baseUniqueSource: new-vs-base lookup for constraint "${constraint.name}" on kind "${kind}" failed \u2014 a staged node's props could not be validated against the kind's schema for constraint-key computation.`,
+            { details: { kind, constraint: constraint.name }, cause: error }
+          );
+        }
+      })
+    );
+    for (const matches of matchesByConstraint) {
+      for (const [index, node] of nodes.entries()) {
+        const base = matches[index];
+        if (base === void 0) {
+          continue;
+        }
+        const stagedNode = node;
+        const stagedKey = mergeKey(stagedNode.kind, stagedNode.id);
+        const baseKey = mergeKey(base.kind, base.id);
+        if (!baseMembers.has(baseKey)) {
+          baseMembers.set(baseKey, {
+            origin: "base",
+            id: base.id,
+            kind: base.kind,
+            props: nodeProps(base)
+          });
+        }
+        if (stagedKey === baseKey) {
+          continue;
+        }
+        const { a, b } = compareMergeKeys(stagedKey, baseKey) <= 0 ? { a: stagedKey, b: baseKey } : { a: baseKey, b: stagedKey };
+        forcedEdges.push({ a, b, score: FORCED_MATCH_SCORE });
+      }
+    }
+    return {
+      pairs: [],
+      forcedEdges,
+      baseMembers: [...baseMembers.values()].sort(
+        (left, right) => compareStrings(left.id, right.id)
+      )
+    };
+  }
+};
+var baseKeySource = {
+  id: "baseKey",
+  async generate(scope) {
+    const { kind, nodes, blockIndex, store } = scope;
+    if (blockIndex === void 0) {
+      return { pairs: [], forcedEdges: [], baseMembers: [] };
+    }
+    if (nodes === void 0 || store === void 0) {
+      throw new MergeError(
+        "baseKeySource requires nodes and store in the source scope.",
+        { details: { kind, source: "baseKey" } }
+      );
+    }
+    const collection = store.nodes[kind];
+    if (collection === void 0 || nodes.length === 0) {
+      return { pairs: [], forcedEdges: [], baseMembers: [] };
+    }
+    const items = nodes.map((node) => ({ props: nodeProps(node) }));
+    let matchesByNode;
+    try {
+      matchesByNode = await collection.bulkFindByIndex(blockIndex, items);
+    } catch (error) {
+      throw new MergeError(
+        `baseKeySource: new-vs-base lookup on index "${blockIndex}" for kind "${kind}" failed \u2014 the index is undeclared or a staged node's props are incompatible with its indexed fields.`,
+        { details: { kind, index: blockIndex }, cause: error }
+      );
+    }
+    const pairs = [];
+    const baseMembers = /* @__PURE__ */ new Map();
+    for (const [index, node] of nodes.entries()) {
+      const stagedNode = node;
+      const stagedKey = mergeKey(stagedNode.kind, stagedNode.id);
+      for (const base of matchesByNode[index] ?? []) {
+        const baseKey = mergeKey(base.kind, base.id);
+        if (!baseMembers.has(baseKey)) {
+          baseMembers.set(baseKey, {
+            origin: "base",
+            id: base.id,
+            kind: base.kind,
+            props: nodeProps(base)
+          });
+        }
+        if (stagedKey === baseKey) {
+          continue;
+        }
+        pairs.push(orderEndpoints(stagedNode, base));
+      }
+    }
+    return {
+      pairs,
+      forcedEdges: [],
+      baseMembers: [...baseMembers.values()].sort(
+        (left, right) => compareStrings(left.id, right.id)
+      )
+    };
+  }
+};
+var CANDIDATE_SOURCES = [
+  exactKeySource,
+  uniqueSource
+];
+
+// src/graph-merge/staging.ts
+function compareByIdThenBranch(left, right) {
+  const byId2 = compareStrings(left.id, right.id);
+  return byId2 === 0 ? compareStrings(left.branchId, right.branchId) : byId2;
+}
+function compareByKindIdBranch(left, right) {
+  const byKind = compareStrings(left.kind, right.kind);
+  if (byKind !== 0) {
+    return byKind;
+  }
+  const byId2 = compareStrings(left.id, right.id);
+  return byId2 === 0 ? compareStrings(left.branchId, right.branchId) : byId2;
+}
+function groupByKind(items) {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const bucket = buckets.get(item.kind);
+    if (bucket === void 0) {
+      buckets.set(item.kind, [item]);
+    } else {
+      bucket.push(item);
+    }
+  }
+  const ordered = /* @__PURE__ */ new Map();
+  for (const kind of [...buckets.keys()].sort(
+    (left, right) => compareStrings(left, right)
+  )) {
+    ordered.set(
+      kind,
+      [...buckets.get(kind)].sort(
+        (left, right) => compareByIdThenBranch(left, right)
+      )
+    );
+  }
+  return ordered;
+}
+async function stageBranches(baseStore, branches) {
+  const newNodes = [];
+  const modifiedNodes = [];
+  const deletedNodes = [];
+  const newEdges = [];
+  const modifiedEdges = [];
+  const deletedEdges = [];
+  for (const branch2 of branches) {
+    const diff = await diffAgainstBase(baseStore, branch2.store);
+    const branchId = branch2.id;
+    for (const node of diff.nodes.new) {
+      newNodes.push({ branchId, node, kind: node.kind, id: node.id });
+    }
+    for (const node of diff.nodes.modified) {
+      modifiedNodes.push({ branchId, node, kind: node.kind, id: node.id });
+    }
+    for (const node of diff.nodes.deleted) {
+      deletedNodes.push({ branchId, node, kind: node.kind, id: node.id });
+    }
+    for (const edge of diff.edges.new) {
+      newEdges.push({ branchId, edge, kind: edge.kind, id: edge.id });
+    }
+    for (const edge of diff.edges.modified) {
+      modifiedEdges.push({ branchId, edge, kind: edge.kind, id: edge.id });
+    }
+    for (const edge of diff.edges.deleted) {
+      deletedEdges.push({ branchId, edge, kind: edge.kind, id: edge.id });
+    }
+  }
+  return {
+    newNodesByKind: groupByKind(newNodes),
+    modifiedNodes: [...modifiedNodes].sort(
+      (left, right) => compareByKindIdBranch(left, right)
+    ),
+    deletedNodes: [...deletedNodes].sort(
+      (left, right) => compareByKindIdBranch(left, right)
+    ),
+    newEdgesByKind: groupByKind(newEdges),
+    modifiedEdges: [...modifiedEdges].sort(
+      (left, right) => compareByKindIdBranch(left, right)
+    ),
+    deletedEdges: [...deletedEdges].sort(
+      (left, right) => compareByKindIdBranch(left, right)
+    )
+  };
+}
+
+// src/graph-merge/tx-retry.ts
+var RETRYABLE_SQLSTATES = /* @__PURE__ */ new Set(["40001", "40P01"]);
+var RETRYABLE_MESSAGE_PATTERN = /could not serialize access|deadlock detected/i;
+var MAX_COMMIT_ATTEMPTS = 3;
+function isRetryableTxConflict(error) {
+  const seen = /* @__PURE__ */ new Set();
+  let current = error;
+  while (current !== void 0 && current !== null && typeof current === "object" && !seen.has(current)) {
+    seen.add(current);
+    const candidate = current;
+    if (typeof candidate.code === "string" && RETRYABLE_SQLSTATES.has(candidate.code)) {
+      return true;
+    }
+    if (typeof candidate.message === "string" && RETRYABLE_MESSAGE_PATTERN.test(candidate.message)) {
+      return true;
+    }
+    current = candidate.cause;
+  }
+  return false;
+}
+async function withTxConflictRetry(commit) {
+  let lastConflict;
+  for (let attempt = 1; attempt <= MAX_COMMIT_ATTEMPTS; attempt += 1) {
+    try {
+      return await commit();
+    } catch (error) {
+      if (!isRetryableTxConflict(error)) {
+        throw error;
+      }
+      lastConflict = error;
+    }
+  }
+  throw new MergeError(
+    `Merge commit aborted by transaction conflicts (serialization failure or deadlock) on ${MAX_COMMIT_ATTEMPTS} consecutive attempts; giving up.`,
+    {
+      cause: lastConflict,
+      details: { attempts: MAX_COMMIT_ATTEMPTS },
+      suggestion: "Reduce concurrent writes to the merge target, or serialize merges against it."
+    }
+  );
+}
+
+// src/graph-merge/type-reconcile.ts
+var INCOMPATIBLE_TYPES_FLAG_REASON = "type-reconcile:incompatible-kinds";
+function distinctKinds(kinds) {
+  return [...new Set(kinds)].sort((left, right) => compareStrings(left, right));
+}
+function areEquivalent(closure, left, right) {
+  return left !== right && isReachable2(closure, left, right) && isReachable2(closure, right, left);
+}
+function isAtOrBelow(closure, candidate, other) {
+  if (candidate === other) {
+    return true;
+  }
+  return isReachable2(closure, candidate, other) || areEquivalent(closure, candidate, other);
+}
+function mostSpecificCommonKind(closure, kinds) {
+  const qualifiers = kinds.filter(
+    (candidate) => kinds.every((other) => isAtOrBelow(closure, candidate, other))
+  );
+  if (qualifiers.length === 0) {
+    return void 0;
+  }
+  return [...qualifiers].sort((left, right) => compareStrings(left, right))[0];
+}
+function reconcileTypes(clusters, closure, mode) {
+  if (mode === "off") {
+    return {
+      reconciliations: [],
+      retypeMap: /* @__PURE__ */ new Map(),
+      dropped: []
+    };
+  }
+  const reconciliations = [];
+  const retypeMap = /* @__PURE__ */ new Map();
+  const dropped = [];
+  for (const cluster of clusters) {
+    const kinds = distinctKinds(cluster.memberKinds);
+    if (kinds.length <= 1) {
+      continue;
+    }
+    const entityId = idOf(cluster.canonicalId);
+    const toType = mostSpecificCommonKind(closure, kinds);
+    if (toType === void 0) {
+      dropped.push({
+        kind: "node",
+        id: entityId,
+        reason: INCOMPATIBLE_TYPES_FLAG_REASON
+      });
+      continue;
+    }
+    reconciliations.push({
+      entityId,
+      fromTypes: kinds,
+      toType
+    });
+    retypeMap.set(cluster.canonicalId, toType);
+  }
+  return {
+    reconciliations: reconciliations.sort(
+      (left, right) => compareStrings(left.entityId, right.entityId)
+    ),
+    retypeMap,
+    dropped: dropped.sort((left, right) => compareStrings(left.id, right.id))
+  };
+}
+
+// src/graph-merge/merge.ts
+var COMMITTED_TARGET_BRANCH = asBranchId("__committed_target__");
+function asNode(staged) {
+  return {
+    kind: staged.node.kind,
+    id: staged.node.id,
+    ...staged.node.props
+  };
+}
+function newNodesByKind(staging) {
+  const ordered = /* @__PURE__ */ new Map();
+  for (const [kind, items] of staging.newNodesByKind) {
+    ordered.set(
+      kind,
+      [...items].sort((left, right) => {
+        const byId2 = compareStrings(left.node.id, right.node.id);
+        return byId2 === 0 ? compareStrings(left.branchId, right.branchId) : byId2;
+      })
+    );
+  }
+  return ordered;
+}
+function uniqueConstraintsFor(introspectionKinds, kind) {
+  return introspectionKinds.get(kind) ?? [];
+}
+async function precomputeEmbeddings(byKind, resolve, embedder) {
+  const texts = /* @__PURE__ */ new Set();
+  for (const [kind, items] of byKind) {
+    const config = resolve[kind];
+    if (config === void 0) {
+      continue;
+    }
+    const fields = embeddingFields(config.similarity);
+    if (fields === void 0) {
+      continue;
+    }
+    for (const staged of items) {
+      const text = fieldText(asNode(staged), fields);
+      if (text.length > 0) {
+        texts.add(text);
+      }
+    }
+  }
+  const lookup = /* @__PURE__ */ new Map();
+  if (texts.size === 0) {
+    return lookup;
+  }
+  const orderedTexts = [...texts].sort(
+    (left, right) => compareStrings(left, right)
+  );
+  const vectors = await embedder(orderedTexts);
+  if (vectors.length !== orderedTexts.length) {
+    throw new MergeError(
+      `Embedder returned ${vectors.length} vectors for ${orderedTexts.length} texts; expected exactly one per text.`,
+      {
+        details: { texts: orderedTexts.length, vectors: vectors.length },
+        suggestion: "Ensure MergeOptions.embedder returns one vector per input text, in order."
+      }
+    );
+  }
+  for (const [index, text] of orderedTexts.entries()) {
+    lookup.set(text, vectors[index]);
+  }
+  return lookup;
+}
+async function embedMissingPairTexts(base, pairs, strategy, embedder) {
+  const existing = base ?? /* @__PURE__ */ new Map();
+  const fields = embeddingFields(strategy);
+  if (fields === void 0) {
+    return existing;
+  }
+  const missing = /* @__PURE__ */ new Set();
+  for (const pair of pairs) {
+    for (const node of [pair.left, pair.right]) {
+      const text = fieldText(node, fields);
+      if (text.length > 0 && !existing.has(text)) {
+        missing.add(text);
+      }
+    }
+  }
+  if (missing.size === 0) {
+    return existing;
+  }
+  const orderedTexts = [...missing].sort(
+    (left, right) => compareStrings(left, right)
+  );
+  const vectors = await embedder(orderedTexts);
+  if (vectors.length !== orderedTexts.length) {
+    throw new MergeError(
+      `Embedder returned ${vectors.length} vectors for ${orderedTexts.length} texts; expected exactly one per text.`,
+      {
+        details: { texts: orderedTexts.length, vectors: vectors.length },
+        suggestion: "Ensure MergeOptions.embedder returns one vector per input text, in order."
+      }
+    );
+  }
+  const augmented = new Map(existing);
+  for (const [index, text] of orderedTexts.entries()) {
+    augmented.set(text, vectors[index]);
+  }
+  return augmented;
+}
+async function generateAllCandidates(target, staging, options, introspectionKinds, ctx, useBaseSources, embedder) {
+  const allEdges = [];
+  const warnings = [];
+  const baseMembers = [];
+  const byKind = newNodesByKind(staging);
+  const sources = useBaseSources ? [...CANDIDATE_SOURCES, baseUniqueSource, baseKeySource] : CANDIDATE_SOURCES;
+  const baseStore = target;
+  const perKind = await Promise.all(
+    [...byKind].map(
+      async ([kind, items]) => {
+        const resolveConfig = options.resolve[kind];
+        if (resolveConfig === void 0) {
+          return ok({ edges: [], warnings: [], baseMembers: [] });
+        }
+        const nodes = items.map((staged) => asNode(staged));
+        const uniqueConstraints = uniqueConstraintsFor(
+          introspectionKinds,
+          kind
+        );
+        const blocks = blockNodes(nodes, resolveConfig, uniqueConstraints);
+        const keylessConfig = keylessConfigFor(resolveConfig);
+        const scope = {
+          kind,
+          blocks,
+          nodes,
+          uniqueConstraints,
+          store: baseStore,
+          ...resolveConfig.blockIndex === void 0 ? {} : { blockIndex: resolveConfig.blockIndex },
+          ...keylessConfig === void 0 ? {} : { keyless: keylessConfig }
+        };
+        const pairs = [];
+        const forcedEdges = [];
+        const kindBaseMembers = [];
+        for (const source of sources) {
+          const produced = await source.generate(scope);
+          pairs.push(...produced.pairs);
+          forcedEdges.push(...produced.forcedEdges);
+          kindBaseMembers.push(...produced.baseMembers);
+        }
+        const kindCtx = embedder === void 0 ? ctx : {
+          ...ctx,
+          embeddings: await embedMissingPairTexts(
+            ctx.embeddings,
+            pairs,
+            resolveConfig.similarity,
+            embedder
+          )
+        };
+        const scored = scoreCandidates(
+          { pairs, forcedEdges },
+          resolveConfig,
+          kindCtx,
+          options.onComparisonCeiling,
+          options.maxComparisonsPerKind
+        );
+        if (isErr(scored)) {
+          return err(scored.error);
+        }
+        return ok({
+          edges: scored.data.edges,
+          warnings: scored.data.warnings.map(
+            (warning) => `[${kind}] ${warning.message}`
+          ),
+          baseMembers: kindBaseMembers
+        });
+      }
+    )
+  );
+  for (const result of perKind) {
+    if (isErr(result)) {
+      return err(result.error);
+    }
+    allEdges.push(...result.data.edges);
+    warnings.push(...result.data.warnings);
+    baseMembers.push(...result.data.baseMembers);
+  }
+  return ok({
+    // The ONE shared `(a, b)` edge comparator (id-first `(kind, id)` order), so this
+    // stage emits edges in exactly the order clustering consumes them.
+    edges: allEdges.sort((left, right) => compareCandidateEdges(left, right)),
+    warnings,
+    // Total order over the composite `(kind, id)` identity (two same-id/different-kind
+    // base members would tie under a bare-id compare).
+    baseMembers: baseMembers.sort(
+      (left, right) => compareMergeKeys(mergeKeyOf(left), mergeKeyOf(right))
+    )
+  });
+}
+function clusterMembersFor(cluster, newNodesById, baseMembersById) {
+  const members = [];
+  for (const key of cluster.members) {
+    for (const staged of newNodesById.get(key) ?? []) {
+      members.push({
+        origin: "staged",
+        id: staged.node.id,
+        kind: staged.node.kind,
+        branchId: staged.branchId,
+        props: staged.node.props
+      });
+    }
+    const base = baseMembersById.get(key);
+    if (base !== void 0) {
+      members.push({
+        origin: "base",
+        id: base.id,
+        kind: base.kind,
+        branchId: BASE_PROVENANCE_BRANCH,
+        props: base.props
+      });
+    }
+  }
+  return members;
+}
+function indexNewNodesById(staging) {
+  const index = /* @__PURE__ */ new Map();
+  for (const items of staging.newNodesByKind.values()) {
+    for (const staged of items) {
+      const key = mergeKeyOf(staged.node);
+      const bucket = index.get(key);
+      if (bucket === void 0) {
+        index.set(key, [staged]);
+      } else {
+        bucket.push(staged);
+      }
+    }
+  }
+  return index;
+}
+function buildStagedEdges(staging, modifiedEdges) {
+  const staged = [];
+  for (const items of staging.newEdgesByKind.values()) {
+    for (const item of items) {
+      staged.push(toStagedEdge(item.branchId, item));
+    }
+  }
+  for (const item of modifiedEdges) {
+    staged.push({
+      id: item.edge.id,
+      kind: item.edge.kind,
+      fromId: item.edge.fromId,
+      toId: item.edge.toId,
+      fromKind: item.edge.fromKind,
+      toKind: item.edge.toKind,
+      props: item.edge.forkProps,
+      branchId: item.branchId
+    });
+  }
+  return staged;
+}
+function toStagedEdge(branchId, item) {
+  return {
+    id: item.edge.id,
+    kind: item.edge.kind,
+    fromId: item.edge.fromId,
+    toId: item.edge.toId,
+    fromKind: item.edge.fromKind,
+    toKind: item.edge.toKind,
+    props: item.edge.props,
+    branchId
+  };
+}
+function buildProvenanceIndex(records) {
+  const byBranch = /* @__PURE__ */ new Map();
+  for (const record of records) {
+    let entry = byBranch.get(record.branchId);
+    if (entry === void 0) {
+      entry = { nodeIds: /* @__PURE__ */ new Set(), edgeIds: /* @__PURE__ */ new Set() };
+      byBranch.set(record.branchId, entry);
+    }
+    if (record.role === "node") {
+      entry.nodeIds.add(record.canonicalId);
+    } else {
+      entry.edgeIds.add(record.canonicalId);
+    }
+  }
+  const frozen = /* @__PURE__ */ new Map();
+  for (const [branchId, sets] of byBranch) {
+    frozen.set(branchId, {
+      nodeIds: [...sets.nodeIds].sort(
+        (left, right) => compareStrings(left, right)
+      ),
+      edgeIds: [...sets.edgeIds].sort((left, right) => compareStrings(left, right)).map((id) => id)
+    });
+  }
+  return {
+    byBranch: (branchId) => frozen.get(branchId) ?? { nodeIds: [], edgeIds: [] }
+  };
+}
+function pushProvenance(records, role, branchId, canonicalId, canonicalKind, sourceId) {
+  records.push({ role, canonicalId, canonicalKind, branchId, sourceId });
+}
+var EMPTY_WEIGHTS = /* @__PURE__ */ new Map();
+function planMerge(staging, candidateEdges, candidateWarnings, baseMembers, options, branchRank, subClassClosure, preferredBranchId) {
+  const provenanceRecords = [];
+  const weights = options.provenanceWeights ?? EMPTY_WEIGHTS;
+  const recordProvenance = (role, branchId, canonicalId, canonicalKind, sourceId) => {
+    if (branchId === preferredBranchId) {
+      return;
+    }
+    pushProvenance(
+      provenanceRecords,
+      role,
+      branchId,
+      canonicalId,
+      canonicalKind,
+      sourceId
+    );
+  };
+  const newNodesById = indexNewNodesById(staging);
+  const acceptedEndpointKeys = /* @__PURE__ */ new Set();
+  for (const edge of candidateEdges) {
+    acceptedEndpointKeys.add(edge.a);
+    acceptedEndpointKeys.add(edge.b);
+  }
+  const baseMembersById = /* @__PURE__ */ new Map();
+  for (const member of baseMembers) {
+    const key = mergeKeyOf(member);
+    if (acceptedEndpointKeys.has(key) || newNodesById.has(key)) {
+      baseMembersById.set(key, member);
+    }
+  }
+  const newNodeIds = [...newNodesById.keys(), ...baseMembersById.keys()];
+  const isOntology = options.reconcileTypes === "ontology";
+  const preferKind = isOntology ? (kinds) => mostSpecificCommonKind(subClassClosure, kinds) : void 0;
+  const clusterEdges = isOntology ? [
+    ...candidateEdges,
+    ...ontologyRetypeEdges(
+      newNodesById.keys(),
+      (kinds) => mostSpecificCommonKind(subClassClosure, kinds) !== void 0
+    )
+  ] : candidateEdges;
+  const baseIds = new Set(baseMembersById.keys());
+  const guard = enforceBaseGuard(
+    connectedComponents(clusterEdges, newNodeIds),
+    clusterEdges,
+    baseIds
+  );
+  const clusters = options.clusterMaxDiameter === void 0 ? guard.clusters : enforceDiameter(guard.clusters, clusterEdges, options.clusterMaxDiameter);
+  const baseAmbiguities = guard.events.map((event) => ({
+    baseIds: event.baseIds.map((key) => ({ kind: kindOf(key), id: idOf(key) })),
+    memberIds: event.memberIds.map((key) => ({
+      kind: kindOf(key),
+      id: idOf(key)
+    }))
+  }));
+  const canonicalEntities = [];
+  const resolutions = [];
+  const propertyConflicts = [];
+  const reconcileInputs = [];
+  for (const cluster of clusters) {
+    const members = clusterMembersFor(cluster, newNodesById, baseMembersById);
+    if (members.length === 0) {
+      continue;
+    }
+    const entity = canonicalizeCluster(
+      cluster,
+      members,
+      options.onPropertyConflict,
+      branchRank,
+      weights,
+      options.canonical,
+      options.onBasePropertyConflict,
+      preferKind,
+      preferredBranchId
+    );
+    canonicalEntities.push(entity);
+    reconcileInputs.push({
+      canonicalId: mergeKey(entity.kind, entity.canonicalId),
+      memberKinds: members.map((member) => member.kind)
+    });
+    const distinctMergedIds = new Set(
+      cluster.members.map((member) => idOf(member))
+    );
+    if (distinctMergedIds.size > 1) {
+      resolutions.push(entity.resolution);
+    }
+    for (const conflict of entity.conflicts) {
+      propertyConflicts.push(conflict);
+    }
+    for (const member of members) {
+      recordProvenance(
+        "node",
+        member.branchId,
+        entity.canonicalId,
+        entity.kind,
+        member.id
+      );
+    }
+  }
+  const deleteModify = resolveDeleteModify(
+    staging,
+    options.onDeleteModifyConflict,
+    branchRank,
+    preferredBranchId
+  );
+  const nodeDeletions = /* @__PURE__ */ new Map();
+  for (const deletion of deleteModify.nodeDeletions) {
+    nodeDeletions.set(mergeKey(deletion.kind, deletion.id), deletion.kind);
+  }
+  for (const modification of deleteModify.survivingModifications) {
+    recordProvenance(
+      "node",
+      modification.branchId,
+      modification.node.id,
+      modification.node.kind,
+      modification.node.id
+    );
+  }
+  const reconciledModifications = reconcileModifications(
+    deleteModify.survivingModifications,
+    options.onPropertyConflict,
+    branchRank,
+    weights,
+    preferredBranchId
+  );
+  for (const conflict of reconciledModifications.conflicts) {
+    propertyConflicts.push(conflict);
+  }
+  const edgeDeleteModify = resolveEdgeDeleteModify(
+    staging,
+    options.onDeleteModifyConflict,
+    branchRank,
+    preferredBranchId
+  );
+  const edgeDeletions = /* @__PURE__ */ new Map();
+  for (const deletion of edgeDeleteModify.edgeDeletions) {
+    edgeDeletions.set(mergeKey(deletion.kind, deletion.id), deletion.kind);
+  }
+  for (const modification of edgeDeleteModify.survivingModifications) {
+    recordProvenance(
+      "edge",
+      modification.branchId,
+      modification.edge.id,
+      modification.edge.kind,
+      modification.edge.id
+    );
+  }
+  const reconciledEdgeModifications = reconcileEdgeModifications(
+    edgeDeleteModify.survivingModifications,
+    options.onPropertyConflict,
+    branchRank,
+    weights,
+    preferredBranchId
+  );
+  for (const conflict of reconciledEdgeModifications.conflicts) {
+    propertyConflicts.push(conflict);
+  }
+  const reconciliation = reconcileTypes(
+    reconcileInputs,
+    subClassClosure,
+    options.reconcileTypes
+  );
+  const entityByIdentity = /* @__PURE__ */ new Map();
+  for (const entity of canonicalEntities) {
+    entityByIdentity.set(mergeKey(entity.kind, entity.canonicalId), entity);
+  }
+  const canonicalOf = buildCanonicalMap(
+    clusters,
+    (cluster) => pickClusterCanonical(cluster, entityByIdentity)
+  );
+  const stagedEdges = buildStagedEdges(
+    staging,
+    reconciledEdgeModifications.survivingModifications
+  );
+  const stagedEdgeBranches = /* @__PURE__ */ new Map();
+  for (const staged of stagedEdges) {
+    const branches = stagedEdgeBranches.get(staged.id);
+    if (branches === void 0) {
+      stagedEdgeBranches.set(staged.id, /* @__PURE__ */ new Set([staged.branchId]));
+    } else {
+      branches.add(staged.branchId);
+    }
+  }
+  const deletedNodeIdSet = new Set(nodeDeletions.keys());
+  const repoint2 = repointEdges(
+    stagedEdges,
+    canonicalOf,
+    deletedNodeIdSet,
+    options.onPropertyConflict,
+    branchRank,
+    weights,
+    preferredBranchId
+  );
+  for (const merged of repoint2.edges) {
+    for (const sourceId of merged.mergedIds) {
+      for (const branchId of stagedEdgeBranches.get(sourceId) ?? []) {
+        recordProvenance("edge", branchId, merged.id, merged.kind, sourceId);
+      }
+    }
+  }
+  const dropped = [
+    ...deleteModify.dropped,
+    ...edgeDeleteModify.dropped,
+    ...repoint2.dropped,
+    ...reconciliation.dropped
+  ].sort(
+    (left, right) => compareStrings(`${left.kind}|${left.id}`, `${right.kind}|${right.id}`)
+  );
+  return {
+    canonicalEntities,
+    survivingModifications: reconciledModifications.survivingModifications,
+    nodeDeletions,
+    edgeDeletions,
+    mergedEdges: repoint2.edges,
+    inheritedEdgeBaseProps: new Map(
+      reconciledEdgeModifications.survivingModifications.map((modification) => [
+        modification.edge.id,
+        modification.edge.baseProps
+      ])
+    ),
+    retypeMap: reconciliation.retypeMap,
+    // Order report arrays by the composite (kind, id) identity — never a bare id
+    // or a `|`-joined string. A bare id ties two different-kind entities that
+    // share an id, and a `|` separator collides on caller-supplied ids/property
+    // names that contain `|`; either makes the comparator non-total, so the
+    // returned order would depend on stable-sort + insertion order and break the
+    // order-independence the whole subsystem guarantees.
+    resolutions: resolutions.sort(
+      (left, right) => compareMergeKeys(
+        mergeKey(left.kind, left.canonicalId),
+        mergeKey(right.kind, right.canonicalId)
+      )
+    ),
+    propertyConflicts: [...propertyConflicts, ...repoint2.conflicts].sort(
+      (left, right) => {
+        const byEntity = compareMergeKeys(
+          mergeKey(left.kind, left.entityId),
+          mergeKey(right.kind, right.entityId)
+        );
+        return byEntity === 0 ? compareStrings(left.property, right.property) : byEntity;
+      }
+    ),
+    deleteModifyConflicts: [
+      ...deleteModify.conflicts,
+      ...edgeDeleteModify.conflicts
+    ].sort(
+      (left, right) => compareMergeKeys(
+        mergeKey(left.kind, left.entityId),
+        mergeKey(right.kind, right.entityId)
+      )
+    ),
+    typeReconciliations: reconciliation.reconciliations,
+    dropped,
+    baseAmbiguities: baseAmbiguities.sort(
+      (left, right) => compareMergeKeys(
+        mergeKey(left.baseIds[0].kind, left.baseIds[0].id),
+        mergeKey(right.baseIds[0].kind, right.baseIds[0].id)
+      )
+    ),
+    provenanceRecords,
+    warnings: candidateWarnings
+  };
+}
+function pickClusterCanonical(cluster, entityByIdentity) {
+  for (const member of cluster.members) {
+    if (entityByIdentity.has(member)) {
+      return member;
+    }
+  }
+  throw new MergeError(
+    "Internal invariant: cluster has no canonical entity in pickClusterCanonical.",
+    { details: { members: cluster.members.map((member) => idOf(member)) } }
+  );
+}
+function commitModificationProps(baseProps, forkProps) {
+  const props = { ...forkProps };
+  for (const key of Object.keys(baseProps)) {
+    if (!(key in forkProps)) {
+      props[key] = void 0;
+    }
+  }
+  return props;
+}
+async function applyMergePlan(plan, nodesApi, edgesApi) {
+  const committedNodeIds = /* @__PURE__ */ new Set();
+  const canonicalIdentities = /* @__PURE__ */ new Set();
+  for (const entity of plan.canonicalEntities) {
+    canonicalIdentities.add(mergeKey(entity.kind, entity.canonicalId));
+  }
+  const survivingModProps = /* @__PURE__ */ new Map();
+  for (const modification of plan.survivingModifications) {
+    survivingModProps.set(mergeKeyOf(modification.node), {
+      baseProps: modification.node.baseProps,
+      forkProps: modification.node.forkProps
+    });
+  }
+  for (const modification of plan.survivingModifications) {
+    const identity = mergeKeyOf(modification.node);
+    if (plan.nodeDeletions.has(identity) || canonicalIdentities.has(identity)) {
+      continue;
+    }
+    const collection = nodeCollection(nodesApi, modification.node.kind);
+    await collection.upsertByIdFromRecord(
+      modification.node.id,
+      commitModificationProps(
+        modification.node.baseProps,
+        modification.node.forkProps
+      )
+    );
+    committedNodeIds.add(identity);
+  }
+  for (const entity of plan.canonicalEntities) {
+    const identity = mergeKey(entity.kind, entity.canonicalId);
+    if (plan.nodeDeletions.has(identity)) {
+      continue;
+    }
+    const kind = plan.retypeMap.get(identity) ?? entity.kind;
+    const modification = survivingModProps.get(identity);
+    const props = modification === void 0 ? entity.props : {
+      ...entity.props,
+      ...commitModificationProps(
+        modification.baseProps,
+        modification.forkProps
+      )
+    };
+    const collection = nodeCollection(nodesApi, kind);
+    await collection.upsertByIdFromRecord(entity.canonicalId, props);
+    committedNodeIds.add(mergeKey(kind, entity.canonicalId));
+  }
+  for (const [identity, kind] of plan.nodeDeletions) {
+    const collection = nodeCollection(nodesApi, kind);
+    await collection.delete(idOf(identity));
+  }
+  for (const [identity, kind] of plan.edgeDeletions) {
+    await edgeCollection(edgesApi, kind).delete(idOf(identity));
+  }
+  const edgesByKind = /* @__PURE__ */ new Map();
+  for (const edge of plan.mergedEdges) {
+    const fromKind = plan.retypeMap.get(mergeKey(edge.fromKind, edge.fromId));
+    const toKind = plan.retypeMap.get(mergeKey(edge.toKind, edge.toId));
+    const edgeBaseProps = plan.inheritedEdgeBaseProps.get(edge.id);
+    const props = edgeBaseProps === void 0 ? edge.props : commitModificationProps(edgeBaseProps, edge.props);
+    const item = {
+      id: edge.id,
+      from: { kind: fromKind ?? edge.fromKind, id: edge.fromId },
+      to: { kind: toKind ?? edge.toKind, id: edge.toId },
+      props
+    };
+    const existing = edgesByKind.get(edge.kind);
+    if (existing === void 0) {
+      edgesByKind.set(edge.kind, [item]);
+    } else {
+      existing.push(item);
+    }
+  }
+  let committedEdges = 0;
+  for (const [kind, items] of edgesByKind) {
+    await edgeCollection(edgesApi, kind).bulkUpsertById(items);
+    committedEdges += items.length;
+  }
+  return { nodes: committedNodeIds.size, edges: committedEdges };
+}
+async function commitPlan(target, plan, expectedBaseVersion) {
+  if (!target.backend.capabilities.transactions) {
+    throw new MergeError(
+      "merge() requires a transaction-capable target backend. The merged plan (canonical upserts, soft-deletes, edge upserts) must commit atomically; a non-transactional fallback would leave a partially-merged graph on a mid-commit failure. (mergeIncremental() enforces the same requirement.)",
+      { details: { capability: "transactions" } }
+    );
+  }
+  return withTxConflictRetry(
+    () => target.transaction(async (tx) => {
+      if (expectedBaseVersion !== void 0) {
+        await assertTargetUnchanged(tx.backend, target, expectedBaseVersion);
+      }
+      return applyMergePlan(
+        plan,
+        tx.nodes,
+        tx.edges
+      );
+    }, MERGE_COMMIT_TX_OPTIONS)
+  );
+}
+var MERGE_COMMIT_TX_OPTIONS = {
+  isolationLevel: "serializable"
+};
+async function assertTargetUnchanged(txBackend, target, expectedBaseVersion) {
+  const liveContent = await computeContentComponent(
+    txBackend,
+    target.graphId,
+    target.graph
+  );
+  const expectedContent = contentComponentOf(expectedBaseVersion);
+  if (liveContent !== expectedContent) {
+    throw new BaseVersionMismatchError(
+      "The merge target was modified between the base@V check and the commit transaction; the resolved plan no longer describes the live target and was not applied.",
+      {
+        details: {
+          expectedContentFingerprint: expectedContent,
+          liveContentFingerprint: liveContent
+        },
+        suggestion: "Re-run the merge (and re-branch if the divergence is real), or serialize writers against merges on this target."
+      }
+    );
+  }
+}
+function nodeCollection(nodes, kind) {
+  const collection = nodes[kind];
+  if (collection === void 0) {
+    throw new MergeError(`No node collection for kind "${kind}".`, {
+      details: { kind }
+    });
+  }
+  return collection;
+}
+function edgeCollection(edges, kind) {
+  const collection = edges[kind];
+  if (collection === void 0) {
+    throw new MergeError(`No edge collection for kind "${kind}".`, {
+      details: { kind }
+    });
+  }
+  return collection;
+}
+async function validateBaseVersions(target, branches) {
+  const targetVersion = await computeBaseVersion(target);
+  for (const branch2 of branches) {
+    if (branch2.base !== targetVersion) {
+      return err(
+        new BaseVersionMismatchError(
+          `Branch "${branch2.id}" forked from base@V "${branch2.base}", which does not match the merge target's current base@V "${targetVersion}".`,
+          {
+            details: {
+              branchId: branch2.id,
+              branchBase: branch2.base,
+              targetBase: targetVersion
+            }
+          }
+        )
+      );
+    }
+  }
+  return ok(targetVersion);
+}
+function tryNormalize(optionsInput) {
+  try {
+    return ok(normalizeMergeOptions(optionsInput));
+  } catch (error) {
+    return err(new MergeError("Invalid merge options.", { cause: error }));
+  }
+}
+async function resolveMerge(store, target, branches, options, useBaseSources, incremental, expectedBaseVersion) {
+  let targetBranchSeen = false;
+  for (const branch2 of branches) {
+    if (branch2.id === BASE_PROVENANCE_BRANCH) {
+      return err(
+        new MergeError(
+          `Branch id "${BASE_PROVENANCE_BRANCH}" is reserved for committed-base provenance and cannot be used as a branch id.`,
+          { details: { branchId: branch2.id } }
+        )
+      );
+    }
+    if (branch2.id === COMMITTED_TARGET_BRANCH) {
+      if (incremental?.targetBranchId !== COMMITTED_TARGET_BRANCH || targetBranchSeen) {
+        return err(
+          new MergeError(
+            `Branch id "${COMMITTED_TARGET_BRANCH}" is reserved for the committed incremental target and cannot be used as a branch id.`,
+            { details: { branchId: branch2.id } }
+          )
+        );
+      }
+      targetBranchSeen = true;
+    }
+  }
+  try {
+    const staging = await stageBranches(store, branches);
+    const preferredBranchId = incremental?.targetBranchId;
+    const branchIds = branches.map((branch2) => branch2.id);
+    const branchOrder = preferredBranchId === void 0 ? options.branchOrder ?? [] : [
+      preferredBranchId,
+      ...(options.branchOrder ?? []).filter(
+        (branchId) => branchId !== preferredBranchId
+      )
+    ];
+    const branchRank = buildBranchRank(branchOrder, branchIds);
+    const introspection = store.introspect();
+    const introspectionKinds = /* @__PURE__ */ new Map();
+    for (const kind of introspection.kinds) {
+      introspectionKinds.set(kind.name, kind.unique);
+    }
+    const subClassClosure = buildSubClassClosure(introspection.ontology);
+    const embeddings = options.embedder === void 0 ? void 0 : await precomputeEmbeddings(
+      newNodesByKind(staging),
+      options.resolve,
+      options.embedder
+    );
+    const ctx = {
+      backend: store.backend,
+      ...embeddings === void 0 ? {} : { embeddings }
+    };
+    const candidates = await generateAllCandidates(
+      target,
+      staging,
+      options,
+      introspectionKinds,
+      ctx,
+      useBaseSources,
+      options.embedder
+    );
+    if (isErr(candidates)) {
+      return err(candidates.error);
+    }
+    const plan = planMerge(
+      staging,
+      candidates.data.edges,
+      candidates.data.warnings,
+      candidates.data.baseMembers,
+      options,
+      branchRank,
+      subClassClosure,
+      preferredBranchId
+    );
+    const merged = incremental === void 0 ? await commitPlan(target, plan, expectedBaseVersion) : await commitIncrementalPlan(target, plan, {
+      stagedNewByKind: newNodesByKind(staging),
+      options,
+      introspectionKinds,
+      // The committed (kind, id) keys the base sources matched at PLAN time;
+      // anything NEW the in-tx re-probe surfaces is a window write.
+      plannedBaseMatchKeys: new Set(
+        candidates.data.baseMembers.map((member) => mergeKeyOf(member))
+      )
+    });
+    const provenance = options.provenance ? buildProvenanceIndex(plan.provenanceRecords) : { byBranch: () => ({ nodeIds: [], edgeIds: [] }) };
+    const warnings = [...plan.warnings];
+    let provenancePersisted;
+    if (options.persistProvenance) {
+      try {
+        const provenanceStore = await openProvenanceStore(
+          target.backend,
+          target.graphId
+        );
+        const count = await persistProvenanceRecords(
+          provenanceStore,
+          target.graphId,
+          plan.provenanceRecords
+        );
+        provenancePersisted = {
+          graphId: provenanceGraphId(target.graphId),
+          count
+        };
+      } catch (error) {
+        warnings.push(
+          "provenance persistence failed (graph committed; provenance not persisted): " + (error instanceof Error ? error.message : String(error))
+        );
+      }
+    }
+    const report = {
+      merged,
+      resolutions: plan.resolutions,
+      conflicts: plan.propertyConflicts,
+      deleteModifyConflicts: plan.deleteModifyConflicts,
+      typeReconciliations: plan.typeReconciliations,
+      dropped: plan.dropped,
+      baseAmbiguities: plan.baseAmbiguities,
+      provenance,
+      warnings,
+      ...provenancePersisted === void 0 ? {} : { provenancePersisted }
+    };
+    return ok(report);
+  } catch (error) {
+    if (error instanceof MergeError) {
+      return err(error);
+    }
+    return err(
+      new MergeError(
+        `Merge failed while staging or committing: ${describeCause(error)}`,
+        { cause: error }
+      )
+    );
+  }
+}
+async function merge(store, branches, optionsInput = {}) {
+  const normalized = tryNormalize(optionsInput);
+  if (isErr(normalized)) {
+    return err(normalized.error);
+  }
+  const options = normalized.data;
+  const target = options.target ?? store;
+  const precondition = await validateBaseVersions(target, branches);
+  if (isErr(precondition)) {
+    return err(precondition.error);
+  }
+  return resolveMerge(
+    store,
+    target,
+    branches,
+    options,
+    false,
+    void 0,
+    precondition.data
+  );
+}
+async function validateForkPointVersions(forkPoint, branches) {
+  const forkVersion = await computeBaseVersion(forkPoint);
+  for (const branch2 of branches) {
+    if (branch2.base !== forkVersion) {
+      return err(
+        new BaseVersionMismatchError(
+          `Branch "${branch2.id}" forked from base@V "${branch2.base}", which does not match the fork-point's base@V "${forkVersion}". mergeIncremental() requires every branch to have forked from the supplied forkPoint.`,
+          {
+            details: {
+              branchId: branch2.id,
+              branchBase: branch2.base,
+              forkPointBase: forkVersion
+            }
+          }
+        )
+      );
+    }
+  }
+  return ok(forkVersion);
+}
+function nodeSchemaFor(target, kind) {
+  const registry = target.graph.nodes;
+  return registry[kind]?.type?.schema;
+}
+function edgeSchemaFor(target, kind) {
+  const registry = target.graph.edges;
+  return registry[kind]?.type?.schema;
+}
+function analyzeRevalidatingWrite(schema, current, planned) {
+  const merged = { ...current, ...planned };
+  if (schema === void 0) {
+    const storageWouldChange = canonicalizeProps(merged) !== canonicalizeProps(current);
+    return {
+      status: "valid",
+      storageWouldChange,
+      schemaWouldChange: storageWouldChange,
+      stripsCurrentProps: false
+    };
+  }
+  const currentParsed = schema.safeParse(current);
+  const mergedParsed = schema.safeParse(merged);
+  if (!currentParsed.success || !mergedParsed.success) {
+    return { status: "invalid" };
+  }
+  const normalizedCurrent = currentParsed.data;
+  const normalizedMerged = mergedParsed.data;
+  return {
+    status: "valid",
+    storageWouldChange: canonicalizeProps(normalizedMerged) !== canonicalizeProps(current),
+    schemaWouldChange: canonicalizeProps(normalizedMerged) !== canonicalizeProps(normalizedCurrent),
+    stripsCurrentProps: canonicalizeProps(normalizedCurrent) !== canonicalizeProps(current)
+  };
+}
+function nodeProps2(node) {
+  const props = {};
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "id" || key === "kind" || key === "meta") continue;
+    props[key] = value;
+  }
+  return props;
+}
+function edgeProps(edge) {
+  const props = {};
+  for (const [key, value] of Object.entries(edge)) {
+    if (key === "id" || key === "kind" || key === "fromKind" || key === "fromId" || key === "toKind" || key === "toId" || key === "meta") {
+      continue;
+    }
+    props[key] = value;
+  }
+  return props;
+}
+var INCLUDE_TOMBSTONES = { temporalMode: "includeTombstones" };
+function finalEdgeFrom(edge, plan) {
+  return {
+    kind: plan.retypeMap.get(mergeKey(edge.fromKind, edge.fromId)) ?? edge.fromKind,
+    id: edge.fromId
+  };
+}
+function finalEdgeTo(edge, plan) {
+  return {
+    kind: plan.retypeMap.get(mergeKey(edge.toKind, edge.toId)) ?? edge.toKind,
+    id: edge.toId
+  };
+}
+function assertValidRevalidatingWrite(analysis, message, details) {
+  if (analysis.status === "invalid") {
+    throw new MergeError(message, { details });
+  }
+}
+function describeCause(cause) {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+function plannedNodeWrites(plan) {
+  const canonicalIdentities = /* @__PURE__ */ new Set();
+  for (const entity of plan.canonicalEntities) {
+    canonicalIdentities.add(mergeKey(entity.kind, entity.canonicalId));
+  }
+  const survivingModProps = /* @__PURE__ */ new Map();
+  for (const modification of plan.survivingModifications) {
+    survivingModProps.set(
+      mergeKeyOf(modification.node),
+      modification.node.forkProps
+    );
+  }
+  const writes = [];
+  for (const modification of plan.survivingModifications) {
+    const identity = mergeKeyOf(modification.node);
+    if (plan.nodeDeletions.has(identity) || canonicalIdentities.has(identity)) {
+      continue;
+    }
+    writes.push({
+      identity,
+      kind: modification.node.kind,
+      id: modification.node.id,
+      props: modification.node.forkProps
+    });
+  }
+  for (const entity of plan.canonicalEntities) {
+    const sourceIdentity = mergeKey(entity.kind, entity.canonicalId);
+    if (plan.nodeDeletions.has(sourceIdentity)) {
+      continue;
+    }
+    const kind = plan.retypeMap.get(sourceIdentity) ?? entity.kind;
+    const forkProps = survivingModProps.get(sourceIdentity);
+    writes.push({
+      identity: mergeKey(kind, entity.canonicalId),
+      kind,
+      id: entity.canonicalId,
+      props: forkProps === void 0 ? entity.props : { ...entity.props, ...forkProps }
+    });
+  }
+  return writes;
+}
+function edgeWriteSignature(edge, plan) {
+  const from = finalEdgeFrom(edge, plan);
+  const to = finalEdgeTo(edge, plan);
+  return JSON.stringify([
+    edge.kind,
+    from.kind,
+    from.id,
+    to.kind,
+    to.id,
+    canonicalizeProps(edge.props)
+  ]);
+}
+async function validateIncrementalNodeWrites(target, nodesApi, plan) {
+  const writes = plannedNodeWrites(plan);
+  const nodeIdsByKind = /* @__PURE__ */ new Map();
+  for (const write of writes) {
+    const bucket = nodeIdsByKind.get(write.kind) ?? [];
+    bucket.push(write.id);
+    nodeIdsByKind.set(write.kind, bucket);
+  }
+  const currentByIdentity = /* @__PURE__ */ new Map();
+  for (const [kind, ids] of nodeIdsByKind) {
+    const rows = await nodeCollection(nodesApi, kind).getByIds(
+      ids,
+      INCLUDE_TOMBSTONES
+    );
+    for (const [index, id] of ids.entries()) {
+      currentByIdentity.set(mergeKey(kind, id), rows[index]);
+    }
+  }
+  for (const write of writes) {
+    const current = currentByIdentity.get(write.identity);
+    if (current === void 0) {
+      continue;
+    }
+    if (current.meta.deletedAt !== void 0) {
+      throw new MergeError(
+        `mergeIncremental() would resurrect soft-deleted committed node "${write.id}" (kind "${write.kind}").`,
+        { details: { id: write.id, kind: write.kind } }
+      );
+    }
+    const analysis = analyzeRevalidatingWrite(
+      nodeSchemaFor(target, write.kind),
+      nodeProps2(current),
+      write.props
+    );
+    assertValidRevalidatingWrite(
+      analysis,
+      `mergeIncremental() found an existing committed node "${write.id}" (kind "${write.kind}") whose current props do not validate against the active schema.`,
+      { id: write.id, kind: write.kind }
+    );
+    if (analysis.stripsCurrentProps && analysis.schemaWouldChange) {
+      throw new MergeError(
+        `mergeIncremental() would update committed node "${write.id}" (kind "${write.kind}") but the write would strip existing props outside the active schema (lossy base update).`,
+        { details: { id: write.id, kind: write.kind } }
+      );
+    }
+  }
+}
+async function validateIncrementalEdgeWrites(target, edgesApi, plan) {
+  const signatureById = /* @__PURE__ */ new Map();
+  for (const edge of plan.mergedEdges) {
+    const signature = edgeWriteSignature(edge, plan);
+    const existing = signatureById.get(edge.id);
+    if (existing !== void 0 && existing !== signature) {
+      throw new MergeError(
+        `mergeIncremental() would overwrite committed edge "${edge.id}" with multiple planned endpoint/prop shapes (edge.id collision).`,
+        { details: { id: edge.id } }
+      );
+    }
+    signatureById.set(edge.id, signature);
+  }
+  const plannedKindById = /* @__PURE__ */ new Map();
+  const idsByKind = /* @__PURE__ */ new Map();
+  for (const edge of plan.mergedEdges) {
+    if (plannedKindById.has(edge.id)) {
+      continue;
+    }
+    plannedKindById.set(edge.id, edge.kind);
+    const bucket = idsByKind.get(edge.kind) ?? [];
+    bucket.push(edge.id);
+    idsByKind.set(edge.kind, bucket);
+  }
+  const existingById = /* @__PURE__ */ new Map();
+  for (const [kind, ids] of idsByKind) {
+    const rows = await edgeCollection(edgesApi, kind).getByIds(
+      ids,
+      INCLUDE_TOMBSTONES
+    );
+    for (const [index, id] of ids.entries()) {
+      const row = rows[index];
+      if (row !== void 0) {
+        existingById.set(id, row);
+      }
+    }
+  }
+  const notFound = [...plannedKindById.keys()].filter((id) => !existingById.has(id)).sort((left, right) => compareStrings(left, right));
+  if (notFound.length > 0) {
+    const crossKindById = /* @__PURE__ */ new Map();
+    for (const kind of Object.keys(target.graph.edges)) {
+      const rows = await edgeCollection(edgesApi, kind).getByIds(
+        notFound,
+        INCLUDE_TOMBSTONES
+      );
+      for (const [index, id] of notFound.entries()) {
+        const row = rows[index];
+        if (row !== void 0 && !crossKindById.has(id)) {
+          crossKindById.set(id, row);
+        }
+      }
+    }
+    for (const id of notFound) {
+      const row = crossKindById.get(id);
+      if (row === void 0) {
+        continue;
+      }
+      if (row.meta.deletedAt !== void 0) {
+        throw new MergeError(
+          `mergeIncremental() would resurrect soft-deleted committed edge "${id}" (kind "${row.kind}").`,
+          { details: { id, committedKind: row.kind } }
+        );
+      }
+      throw new MergeError(
+        `mergeIncremental() would overwrite committed edge "${id}" (kind "${row.kind}") with a different-kind edge "${plannedKindById.get(id)}" of the same id.`,
+        {
+          details: {
+            id,
+            committedKind: row.kind,
+            plannedKind: plannedKindById.get(id)
+          }
+        }
+      );
+    }
+  }
+  for (const edge of plan.mergedEdges) {
+    const current = existingById.get(edge.id);
+    if (current === void 0) {
+      continue;
+    }
+    if (current.meta.deletedAt !== void 0) {
+      throw new MergeError(
+        `mergeIncremental() would resurrect soft-deleted committed edge "${edge.id}" (kind "${current.kind}").`,
+        { details: { id: edge.id, committedKind: current.kind } }
+      );
+    }
+    const from = finalEdgeFrom(edge, plan);
+    const to = finalEdgeTo(edge, plan);
+    if (current.fromId !== from.id || current.fromKind !== from.kind || current.toId !== to.id || current.toKind !== to.kind) {
+      throw new MergeError(
+        `mergeIncremental() would overwrite committed edge "${edge.id}" (kind "${edge.kind}") with different endpoints.`,
+        { details: { id: edge.id, kind: edge.kind } }
+      );
+    }
+    const analysis = analyzeRevalidatingWrite(
+      edgeSchemaFor(target, edge.kind),
+      edgeProps(current),
+      edge.props
+    );
+    assertValidRevalidatingWrite(
+      analysis,
+      `mergeIncremental() found an existing committed edge "${edge.id}" (kind "${edge.kind}") whose current props do not validate against the active schema.`,
+      { id: edge.id, kind: edge.kind }
+    );
+    if (analysis.stripsCurrentProps && analysis.schemaWouldChange) {
+      throw new MergeError(
+        `mergeIncremental() would update committed edge "${edge.id}" (kind "${edge.kind}") but the write would strip existing props outside the active schema.`,
+        { details: { id: edge.id, kind: edge.kind } }
+      );
+    }
+  }
+}
+async function collectBaseMatchKeys(lookupStore, guard) {
+  const matched = /* @__PURE__ */ new Set();
+  for (const [kind, stagedNodes] of guard.stagedNewByKind) {
+    const resolveConfig = guard.options.resolve[kind];
+    if (resolveConfig === void 0) {
+      continue;
+    }
+    const collection = lookupStore.nodes[kind];
+    if (collection === void 0 || stagedNodes.length === 0) {
+      continue;
+    }
+    const items = stagedNodes.map((staged) => ({ props: staged.node.props }));
+    for (const constraint of uniqueConstraintsFor(
+      guard.introspectionKinds,
+      kind
+    )) {
+      const matches = await collection.bulkFindByConstraint(
+        constraint.name,
+        items
+      );
+      for (const base of matches) {
+        if (base !== void 0) {
+          matched.add(mergeKeyOf(base));
+        }
+      }
+    }
+    if (resolveConfig.blockIndex !== void 0) {
+      const matchesByItem = await collection.bulkFindByIndex(
+        resolveConfig.blockIndex,
+        items
+      );
+      for (const perItem of matchesByItem) {
+        for (const base of perItem) {
+          matched.add(mergeKeyOf(base));
+        }
+      }
+    }
+  }
+  return matched;
+}
+async function assertBaseResolutionStable(lookupStore, guard) {
+  const liveKeys = await collectBaseMatchKeys(lookupStore, guard);
+  const appeared = [...liveKeys].filter((key) => !guard.plannedBaseMatchKeys.has(key)).sort((left, right) => compareMergeKeys(left, right));
+  if (appeared.length === 0) {
+    return;
+  }
+  throw new BaseVersionMismatchError(
+    `mergeIncremental() resolved its branch additions against the target as of planning, but ${appeared.length} committed row(s) matching a branch addition's identity key (a unique constraint or block index) were inserted before the commit transaction. Committing the plan would create duplicate entities the base-source resolution would otherwise have collapsed.`,
+    {
+      details: { appeared },
+      suggestion: "Re-run mergeIncremental(); the re-planned merge resolves the branch additions against the now-committed rows."
+    }
+  );
+}
+async function commitIncrementalPlan(target, plan, guard) {
+  if (!target.backend.capabilities.transactions) {
+    throw new MergeError(
+      "mergeIncremental() requires a transaction-capable target backend. Incremental writes must preflight existing rows and commit atomically; non-transactional fallback would allow partial graph writes.",
+      { details: { capability: "transactions" } }
+    );
+  }
+  return withTxConflictRetry(
+    () => target.transaction(async (tx) => {
+      const nodesApi = tx.nodes;
+      const edgesApi = tx.edges;
+      await assertBaseResolutionStable(tx, guard);
+      await validateIncrementalNodeWrites(target, nodesApi, plan);
+      await validateIncrementalEdgeWrites(target, edgesApi, plan);
+      return applyMergePlan(plan, nodesApi, edgesApi);
+    }, MERGE_COMMIT_TX_OPTIONS)
+  );
+}
+async function mergeIncremental(args) {
+  const { forkPoint, target, branches } = args;
+  const normalized = tryNormalize(args.options ?? {});
+  if (isErr(normalized)) {
+    return err(normalized.error);
+  }
+  const options = normalized.data;
+  if (options.onBasePropertyConflict !== "flag") {
+    return err(
+      new MergeError(
+        'mergeIncremental() requires onBasePropertyConflict: "flag" (keep-base); a non-keep-base policy could overwrite a newer committed base value with a stale branch value.',
+        { details: {} }
+      )
+    );
+  }
+  const forkPrecondition = await validateForkPointVersions(forkPoint, branches);
+  if (isErr(forkPrecondition)) {
+    return err(forkPrecondition.error);
+  }
+  const forkVersion = forkPrecondition.data;
+  const [forkSchema, targetSchema] = await Promise.all([
+    computeSchemaComponent(forkPoint),
+    computeSchemaComponent(target)
+  ]);
+  if (forkSchema !== targetSchema) {
+    return err(
+      new MergeError(
+        "mergeIncremental() requires target and forkPoint to share a schema; schema drift is not supported (the target content may differ \u2014 only the schema must match).",
+        { details: {} }
+      )
+    );
+  }
+  const targetBranch = {
+    id: COMMITTED_TARGET_BRANCH,
+    base: forkVersion,
+    store: target
+  };
+  return resolveMerge(
+    forkPoint,
+    target,
+    [targetBranch, ...branches],
+    options,
+    true,
+    { targetBranchId: COMMITTED_TARGET_BRANCH }
+  );
+}
+
+export { BaseVersionMismatchError, BranchError, MERGE_ERROR_CODES, MERGE_OPTION_DEFAULTS, MergeConflictError, MergeError, SimilarityUnavailableError, asBaseVersion, asBranchId, branch, cloneWorkingCopyStrategy, computeBaseVersion, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, provenanceGraphId, readProvenance };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map