@nicia-ai/typegraph 0.46.2 → 0.48.0

package/dist/graph-merge/index.js

@@ -1,34 +1,35 @@
-import { createStoreWithSchema } from '../chunk-YQ4JONWE.js';
-import '../chunk-IHRDX7K6.js';
-import { importGraphStream, exportGraphStream, importGraph, exportGraph } from '../chunk-AT3MLMJV.js';
-import '../chunk-WEJHA7AD.js';
-import { storeBackend, storeRuntime, transactionBackend } from '../chunk-LHYSY6SE.js';
-import { computeSchemaHash, serializeSchema } from '../chunk-KA4L2NZ3.js';
-import { defineNode } from '../chunk-36LIJXWC.js';
-import { encodeTupleKey, normalizeIdentityPair, identityReferenceKey, identityAssertionSemanticKey } from '../chunk-A2LJG5GM.js';
-import { generateId, compareStrings, compareCodePoints, lockRecordedGraphWrite, readRevisionOrigin, readRecordedClock } from '../chunk-EDHV4CBU.js';
+import { createStoreWithSchema } from '../chunk-BRRP76WO.js';
+import '../chunk-YIURNGXI.js';
+import { importGraphStream, exportGraphStream, importGraph, exportGraph } from '../chunk-AX6JGVTZ.js';
+import '../chunk-KF6K7TGH.js';
+import { storeBackend, storeRuntime, transactionBackend } from '../chunk-I4GAZH5Z.js';
+import { computeSchemaHash, serializeSchema } from '../chunk-2TYSSBU5.js';
+import { defineNode } from '../chunk-SHFBB23Q.js';
+import { forceWriteTransactionRevision, normalizeIdentityPair, identityReferenceKey, identityValidityWindowsOverlap, identityAssertionSemanticKey } from '../chunk-ZFMCDJGB.js';
+import { compareStrings, generateId, encodeTupleKey, lockRecordedGraphWrite, readRevisionOrigin, readRecordedClock, forceRecordedGraphRevision, advanceRevisionClock, compareCodePoints } from '../chunk-S5TERQVW.js';
 import { sortedReplacer } from '../chunk-JBQQ7THH.js';
-import '../chunk-DSAWGCMP.js';
-import { createSqlSchema } from '../chunk-72WUT4GG.js';
-import { snapshotExportContention } from '../chunk-FA6Z7B5L.js';
-import { getNodeKinds, getEdgeKinds, defineInternalGraph } from '../chunk-5ZJOB5YS.js';
-import { computeUniqueKey } from '../chunk-LNIWCQR4.js';
-import { canonicalizeDatabaseTimestamp } from '../chunk-R7EWHKID.js';
-import '../chunk-EDJDDY6H.js';
-import '../chunk-FSLTU57P.js';
-import '../chunk-WMKEGJG4.js';
+import { snapshotExportContention } from '../chunk-UGHG7PGX.js';
+import { createSqlSchema } from '../chunk-NVY5CJFP.js';
+import '../chunk-6LN7FIVU.js';
+import { getNodeKinds, getEdgeKinds, defineInternalGraph } from '../chunk-HEV35TGT.js';
+import { validateEdgeEndpoints, computeUniqueKey } from '../chunk-GLHXM7C4.js';
+import '../chunk-DZAICA5J.js';
+import { canonicalizeDatabaseTimestamp } from '../chunk-5K2BKEBD.js';
+import '../chunk-KKBDXCLQ.js';
+import '../chunk-SDBBMD4N.js';
+import '../chunk-P6YLZTRE.js';
 import { sha256Hex } from '../chunk-K34OPSJK.js';
 import '../chunk-2EBMPJBO.js';
-import '../chunk-EAMVXR5B.js';
-import { asCompiledStatementSql, sql, asCompiledRowsSql } from '../chunk-QOJ2L2AD.js';
+import '../chunk-ZDKTPBGV.js';
+import { asCompiledStatementSql, sql, asCompiledRowsSql } from '../chunk-3DMMGT6S.js';
 import '../chunk-AMKPPFUO.js';
 import '../chunk-W6OG3HDG.js';
 import '../chunk-PC2UBAUB.js';
-import { ok, err, isErr, computeTransitiveClosure, isReachable } from '../chunk-SXWLLQ3D.js';
-export { isErr, isOk, unwrap } from '../chunk-SXWLLQ3D.js';
+import { ok, err, isErr, computeTransitiveClosure, isReachable } from '../chunk-D5R42W5D.js';
+export { isErr, isOk, unwrap } from '../chunk-D5R42W5D.js';
 import { META_EDGE_EQUIVALENT_TO, META_EDGE_SAME_AS } from '../chunk-JXXDZTMN.js';
-import '../chunk-OZJCH7ZS.js';
-import { TypeGraphError, ConfigurationError, IdentityContradictionError, NodeNotFoundError } from '../chunk-62ZXBMSD.js';
+import '../chunk-XVWOYKIK.js';
+import { TypeGraphError, ConfigurationError, IdentityContradictionError, NodeNotFoundError, IdentityEndpointValidityError } from '../chunk-ZLONH2UD.js';
 import '../chunk-FWJKWH6U.js';
 import { createDataKeyedBag, hasOwnKey, requireDefined, readOwnProperty } from '../chunk-DYATYRY4.js';
 import { z } from 'zod';
@@ -106,8 +107,20 @@ var MERGE_ERROR_CODES = {
   branch: "GRAPH_MERGE_BRANCH_ERROR",
   similarityUnavailable: "GRAPH_MERGE_SIMILARITY_UNAVAILABLE",
   conflict: "GRAPH_MERGE_CONFLICT",
+  constraintConflict: "GRAPH_MERGE_CONSTRAINT_CONFLICT",
   identityConflict: "GRAPH_MERGE_IDENTITY_CONFLICT",
-  baseVersionMismatch: "GRAPH_MERGE_BASE_VERSION_MISMATCH"
+  baseVersionMismatch: "GRAPH_MERGE_BASE_VERSION_MISMATCH",
+  planCapability: "GRAPH_MERGE_PLAN_CAPABILITY",
+  planInvalid: "GRAPH_MERGE_PLAN_INVALID",
+  planVersionUnsupported: "GRAPH_MERGE_PLAN_VERSION_UNSUPPORTED",
+  planDigestMismatch: "GRAPH_MERGE_PLAN_DIGEST_MISMATCH",
+  planTargetMismatch: "GRAPH_MERGE_PLAN_TARGET_MISMATCH",
+  planSchemaMismatch: "GRAPH_MERGE_PLAN_SCHEMA_MISMATCH",
+  planOriginMismatch: "GRAPH_MERGE_PLAN_ORIGIN_MISMATCH",
+  planStale: "GRAPH_MERGE_PLAN_STALE",
+  planningStale: "GRAPH_MERGE_PLANNING_STALE",
+  candidateSource: "GRAPH_MERGE_CANDIDATE_SOURCE",
+  evidence: "GRAPH_MERGE_EVIDENCE"
 };
 function toTypeGraphErrorOptions(category, options) {
   return {
@@ -164,6 +177,31 @@ var MergeConflictError = class extends MergeError {
     this.name = "MergeConflictError";
   }
 };
+var MergeConstraintConflictError = class extends MergeError {
+  static errorCategory = "constraint";
+  code = MERGE_ERROR_CODES.constraintConflict;
+  constructor(cause) {
+    super(`The resolved merge would violate ${cause.name}: ${cause.message}`, {
+      cause,
+      details: {
+        ...cause.details,
+        constraintCode: cause.code,
+        constraintErrorName: cause.name,
+        constraintDetails: cause.details
+      },
+      suggestion: cause.suggestion ?? "Change the branch data or target state so the resolved graph satisfies its constraints, then retry the merge."
+    });
+    this.name = "MergeConstraintConflictError";
+  }
+};
+function translateMergeCommitError(error) {
+  if (error instanceof MergeError) return error;
+  if (!(error instanceof TypeGraphError)) return error;
+  if (error.category !== "constraint" || error.code.startsWith("IDENTITY_")) {
+    return error;
+  }
+  return new MergeConstraintConflictError(error);
+}
 var IdentityMergeConflictError = class extends MergeError {
   code = MERGE_ERROR_CODES.identityConflict;
   constructor(message, options = {}) {
@@ -181,56 +219,496 @@ var BaseVersionMismatchError = class extends MergeError {
     this.name = "BaseVersionMismatchError";
   }
 };
+var MergePlanCapabilityError = class extends MergeError {
+  static errorCategory = "user";
+  code = MERGE_ERROR_CODES.planCapability;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "MergePlanCapabilityError";
+  }
+};
+var InvalidMergePlanError = class extends MergeError {
+  static errorCategory = "user";
+  code = MERGE_ERROR_CODES.planInvalid;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "InvalidMergePlanError";
+  }
+};
+var UnsupportedMergePlanVersionError = class extends InvalidMergePlanError {
+  code = MERGE_ERROR_CODES.planVersionUnsupported;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "UnsupportedMergePlanVersionError";
+  }
+};
+var MergePlanDigestMismatchError = class extends InvalidMergePlanError {
+  code = MERGE_ERROR_CODES.planDigestMismatch;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "MergePlanDigestMismatchError";
+  }
+};
+var MergePlanTargetMismatchError = class extends InvalidMergePlanError {
+  code = MERGE_ERROR_CODES.planTargetMismatch;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "MergePlanTargetMismatchError";
+  }
+};
+var MergePlanSchemaMismatchError = class extends InvalidMergePlanError {
+  code = MERGE_ERROR_CODES.planSchemaMismatch;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "MergePlanSchemaMismatchError";
+  }
+};
+var MergePlanOriginMismatchError = class extends InvalidMergePlanError {
+  code = MERGE_ERROR_CODES.planOriginMismatch;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "MergePlanOriginMismatchError";
+  }
+};
+var StaleMergePlanError = class extends MergeError {
+  code = MERGE_ERROR_CODES.planStale;
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      suggestion: options.suggestion ?? "Create a new merge plan against the target's current revision, review it, and apply that plan instead."
+    });
+    this.name = "StaleMergePlanError";
+  }
+};
+var MergePlanningStaleError = class extends StaleMergePlanError {
+  code = MERGE_ERROR_CODES.planningStale;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "MergePlanningStaleError";
+  }
+};
+var CandidateSourceError = class extends MergeError {
+  code = MERGE_ERROR_CODES.candidateSource;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "CandidateSourceError";
+  }
+};
+var MatchEvidenceError = class extends MergeError {
+  code = MERGE_ERROR_CODES.evidence;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "MatchEvidenceError";
+  }
+};
 function describeCause(cause) {
   return cause instanceof Error ? cause.message : String(cause);
 }
 
-// src/graph-merge/union-find.ts
-var UnionFind = class {
-  constructor(compare) {
-    this.compare = compare;
+// src/graph-merge/temporal-identity-closure.ts
+function disjointCacheKey(left, right) {
+  return left <= right ? `${left}\0${right}` : `${right}\0${left}`;
+}
+function areDisjoint(state, left, right) {
+  const key = disjointCacheKey(left, right);
+  const cached = state.disjointCache.get(key);
+  if (cached !== void 0) return cached;
+  const result = state.context.areDisjoint(left, right);
+  state.disjointCache.set(key, result);
+  return result;
+}
+function findRoot(components, index) {
+  let root = index;
+  while (components.parent[root] !== root) {
+    root = requireDefined(components.parent[root]);
   }
-  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);
+  return root;
+}
+function componentKindsConflict(state, leftKinds, rightKinds) {
+  for (const left of leftKinds.keys()) {
+    for (const right of rightKinds.keys()) {
+      if (left !== right && areDisjoint(state, left, right)) return true;
     }
   }
-  /** 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 = requireDefined(this.parent.get(root));
+  return false;
+}
+function unionReferences(state, leftIndex, rightIndex) {
+  const { components } = state;
+  const leftRoot = findRoot(components, leftIndex);
+  const rightRoot = findRoot(components, rightIndex);
+  if (leftRoot === rightRoot) return;
+  const [parentRoot, childRoot] = requireDefined(components.sizes[leftRoot]) >= requireDefined(components.sizes[rightRoot]) ? [leftRoot, rightRoot] : [rightRoot, leftRoot];
+  const parentKinds = requireDefined(components.kindFirstReference[parentRoot]);
+  const childKinds = requireDefined(components.kindFirstReference[childRoot]);
+  const parentDifferent = requireDefined(
+    components.differentAssertions[parentRoot]
+  );
+  const childDifferent = requireDefined(
+    components.differentAssertions[childRoot]
+  );
+  const previousParentSize = requireDefined(components.sizes[parentRoot]);
+  const previousViolation = requireDefined(
+    components.violatesOntology[parentRoot]
+  );
+  const changedKinds = [...childKinds].flatMap(
+    ([kind, childFirstReference]) => {
+      const previousFirstReference = parentKinds.get(kind);
+      return previousFirstReference === void 0 || childFirstReference < previousFirstReference ? [
+        {
+          kind,
+          previousFirstReference,
+          nextFirstReference: childFirstReference
+        }
+      ] : [];
     }
-    let cursor = value;
-    while (cursor !== root) {
-      const next = requireDefined(this.parent.get(cursor));
-      this.parent.set(cursor, root);
-      cursor = next;
+  );
+  const addedDifferent = [...childDifferent].filter(
+    (assertionIndex) => !parentDifferent.has(assertionIndex)
+  );
+  const addedContradictions = [];
+  const crossesDisjointKinds = componentKindsConflict(
+    state,
+    parentKinds,
+    childKinds
+  );
+  components.parent[childRoot] = parentRoot;
+  components.sizes[parentRoot] = previousParentSize + requireDefined(components.sizes[childRoot]);
+  for (const { kind, nextFirstReference } of changedKinds) {
+    parentKinds.set(kind, nextFirstReference);
+  }
+  for (const assertionIndex of addedDifferent) {
+    parentDifferent.add(assertionIndex);
+  }
+  components.violatesOntology[parentRoot] = previousViolation || requireDefined(components.violatesOntology[childRoot]) || crossesDisjointKinds;
+  for (const assertionIndex of childDifferent) {
+    const assertion = requireDefined(state.assertions[assertionIndex]);
+    const aIndex = requireDefined(
+      state.referenceIndexByKey.get(mergeKeyOf(assertion.a))
+    );
+    const bIndex = requireDefined(
+      state.referenceIndexByKey.get(mergeKeyOf(assertion.b))
+    );
+    if (findRoot(components, aIndex) === findRoot(components, bIndex) && !state.contradictoryAssertions.has(assertionIndex)) {
+      state.contradictoryAssertions.add(assertionIndex);
+      addedContradictions.push(assertionIndex);
     }
-    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;
+  state.undo.push(() => {
+    for (const assertionIndex of addedContradictions) {
+      state.contradictoryAssertions.delete(assertionIndex);
     }
-    if (this.compare(leftRoot, rightRoot) <= 0) {
-      this.parent.set(rightRoot, leftRoot);
+    components.violatesOntology[parentRoot] = previousViolation;
+    for (const assertionIndex of addedDifferent) {
+      parentDifferent.delete(assertionIndex);
+    }
+    for (const { kind, previousFirstReference } of changedKinds) {
+      if (previousFirstReference === void 0) parentKinds.delete(kind);
+      else parentKinds.set(kind, previousFirstReference);
+    }
+    components.sizes[parentRoot] = previousParentSize;
+    components.parent[childRoot] = childRoot;
+  });
+}
+function activateReference(state, referenceIndex) {
+  if (state.activeReferences[referenceIndex] === true) return;
+  const reference = requireDefined(state.references[referenceIndex]);
+  const peers = [...state.activeReferencesById.get(reference.id) ?? []];
+  let addedSharedIdViolations = 0;
+  for (const peerIndex of peers) {
+    const peer = requireDefined(state.references[peerIndex]);
+    if (areDisjoint(state, reference.kind, peer.kind)) {
+      addedSharedIdViolations += 1;
+    }
+  }
+  state.sharedIdViolationCount.value += addedSharedIdViolations;
+  state.activeReferences[referenceIndex] = true;
+  const activeForId = state.activeReferencesById.get(reference.id) ?? /* @__PURE__ */ new Set();
+  activeForId.add(referenceIndex);
+  state.activeReferencesById.set(reference.id, activeForId);
+  state.undo.push(() => {
+    activeForId.delete(referenceIndex);
+    if (activeForId.size === 0) {
+      state.activeReferencesById.delete(reference.id);
+    }
+    state.activeReferences[referenceIndex] = false;
+    state.sharedIdViolationCount.value -= addedSharedIdViolations;
+  });
+  if (state.context.sameIdAcrossKinds === "fold") {
+    for (const peerIndex of peers) {
+      unionReferences(state, referenceIndex, peerIndex);
+    }
+  }
+}
+function addDifferentAssertion(state, assertionIndex) {
+  const assertion = requireDefined(state.assertions[assertionIndex]);
+  const aIndex = requireDefined(
+    state.referenceIndexByKey.get(mergeKeyOf(assertion.a))
+  );
+  const bIndex = requireDefined(
+    state.referenceIndexByKey.get(mergeKeyOf(assertion.b))
+  );
+  const aRoot = findRoot(state.components, aIndex);
+  const bRoot = findRoot(state.components, bIndex);
+  if (aRoot === bRoot) {
+    state.contradictoryAssertions.add(assertionIndex);
+    state.undo.push(() => {
+      state.contradictoryAssertions.delete(assertionIndex);
+    });
+    return;
+  }
+  const aDifferent = requireDefined(
+    state.components.differentAssertions[aRoot]
+  );
+  const bDifferent = requireDefined(
+    state.components.differentAssertions[bRoot]
+  );
+  aDifferent.add(assertionIndex);
+  bDifferent.add(assertionIndex);
+  state.undo.push(() => {
+    aDifferent.delete(assertionIndex);
+    bDifferent.delete(assertionIndex);
+  });
+}
+function rollback(state, snapshot) {
+  while (state.undo.length > snapshot) {
+    requireDefined(state.undo.pop())();
+  }
+}
+function firstDisjointPair(state, kinds) {
+  for (const [index, left] of kinds.entries()) {
+    for (const right of kinds.slice(index + 1)) {
+      if (areDisjoint(state, left, right)) return [left, right];
+    }
+  }
+  return void 0;
+}
+function firstAssertionIndex(assertionIndexes) {
+  let first = Number.POSITIVE_INFINITY;
+  for (const assertionIndex of assertionIndexes) {
+    first = Math.min(first, assertionIndex);
+  }
+  return first;
+}
+function activeClassMembers(state, root) {
+  return state.references.filter(
+    (_reference, index) => state.activeReferences[index] === true && findRoot(state.components, index) === root
+  ).toSorted(
+    (left, right) => compareMergeKeys(
+      mergeKey(left.kind, left.id),
+      mergeKey(right.kind, right.id)
+    )
+  );
+}
+function componentKindsInReferenceOrder(state, root) {
+  return [...requireDefined(state.components.kindFirstReference[root])].toSorted((left, right) => left[1] - right[1]).map(([kind]) => kind);
+}
+function assertCoordinateConsistent(state) {
+  if (state.sharedIdViolationCount.value > 0) {
+    const activeById = /* @__PURE__ */ new Map();
+    for (const [index, reference] of state.references.entries()) {
+      if (state.activeReferences[index] !== true) continue;
+      const references = activeById.get(reference.id) ?? [];
+      references.push(reference);
+      activeById.set(reference.id, references);
+    }
+    for (const [sharedId, references] of activeById) {
+      const disjointKinds = firstDisjointPair(state, [
+        ...new Set(references.map((reference) => reference.kind))
+      ]);
+      if (disjointKinds === void 0) continue;
+      throw new IdentityMergeConflictError(
+        "The merged graph would give one id to two ontology-disjoint kinds.",
+        { details: { disjointKinds, sharedId } }
+      );
+    }
+  }
+  if (state.contradictoryAssertions.size > 0) {
+    const assertionIndex = firstAssertionIndex(state.contradictoryAssertions);
+    const assertion = requireDefined(state.assertions[assertionIndex]);
+    const root = findRoot(
+      state.components,
+      requireDefined(state.referenceIndexByKey.get(mergeKeyOf(assertion.a)))
+    );
+    throw new IdentityMergeConflictError(
+      "The merged identity ledger would assert one pair of nodes is both the same and different.",
+      {
+        details: {
+          assertion,
+          sameClass: activeClassMembers(state, root)
+        }
+      }
+    );
+  }
+  const checkedRoots = /* @__PURE__ */ new Set();
+  for (const [referenceIndex, active] of state.activeReferences.entries()) {
+    if (!active) continue;
+    const root = findRoot(state.components, referenceIndex);
+    if (checkedRoots.has(root)) continue;
+    checkedRoots.add(root);
+    if (!requireDefined(state.components.violatesOntology[root])) continue;
+    const sameClass = activeClassMembers(state, root);
+    const disjointKinds = firstDisjointPair(
+      state,
+      componentKindsInReferenceOrder(state, root)
+    );
+    if (disjointKinds === void 0) continue;
+    throw new IdentityMergeConflictError(
+      "The merged identity ledger would join two ontology-disjoint kinds into one class.",
+      { details: { disjointKinds, sameClass } }
+    );
+  }
+}
+function addRangeEvent(events, node, left, right, start, end, add) {
+  if (start <= left && right <= end) {
+    add(requireDefined(events[node]));
+    return;
+  }
+  const middle = Math.floor((left + right) / 2);
+  if (start < middle) {
+    addRangeEvent(events, node * 2, left, middle, start, end, add);
+  }
+  if (middle < end) {
+    addRangeEvent(events, node * 2 + 1, middle, right, start, end, add);
+  }
+}
+function visitTemporalEvents(events, state, node, left, right) {
+  const snapshot = state.undo.length;
+  const event = requireDefined(events[node]);
+  for (const referenceIndex of event.references) {
+    activateReference(state, referenceIndex);
+  }
+  for (const assertionIndex of event.sameAssertions) {
+    const assertion = requireDefined(state.assertions[assertionIndex]);
+    unionReferences(
+      state,
+      requireDefined(state.referenceIndexByKey.get(mergeKeyOf(assertion.a))),
+      requireDefined(state.referenceIndexByKey.get(mergeKeyOf(assertion.b)))
+    );
+  }
+  for (const assertionIndex of event.differentAssertions) {
+    addDifferentAssertion(state, assertionIndex);
+  }
+  if (right - left === 1) {
+    assertCoordinateConsistent(state);
+  } else {
+    const middle = Math.floor((left + right) / 2);
+    visitTemporalEvents(events, state, node * 2, left, middle);
+    visitTemporalEvents(events, state, node * 2 + 1, middle, right);
+  }
+  rollback(state, snapshot);
+}
+function mergeRanges(ranges) {
+  const merged = [];
+  for (const range of ranges.toSorted(
+    (left, right) => left.start - right.start
+  )) {
+    const previous = merged.at(-1);
+    if (previous === void 0 || previous.end < range.start) {
+      merged.push({ ...range });
     } else {
-      this.parent.set(leftRoot, rightRoot);
+      previous.end = Math.max(previous.end, range.end);
     }
   }
-  /** Every value seen by {@link add}/{@link find}/{@link union}, insertion order. */
-  members() {
-    return [...this.parent.keys()];
+  return merged;
+}
+function assertTemporalIdentityClosureConsistent(assertions, identityContext, nodeUniverse) {
+  const boundaries = /* @__PURE__ */ new Set();
+  for (const assertion of assertions) {
+    boundaries.add(assertion.validFrom);
+    if (assertion.validTo !== void 0) boundaries.add(assertion.validTo);
   }
-};
+  const sortedBoundaries = [...boundaries].toSorted();
+  const leafCount = Math.max(1, sortedBoundaries.length);
+  const boundaryIndex = new Map(
+    sortedBoundaries.map((boundary, index) => [boundary, index])
+  );
+  const assertionRanges = assertions.map(
+    (assertion, assertionIndex) => ({
+      assertionIndex,
+      start: requireDefined(boundaryIndex.get(assertion.validFrom)),
+      end: assertion.validTo === void 0 ? leafCount : requireDefined(boundaryIndex.get(assertion.validTo))
+    })
+  );
+  const references = [];
+  const referenceIndexByKey = /* @__PURE__ */ new Map();
+  const addReference = (reference) => {
+    const key = mergeKey(reference.kind, reference.id);
+    const existing = referenceIndexByKey.get(key);
+    if (existing !== void 0) return existing;
+    const index = references.length;
+    references.push(reference);
+    referenceIndexByKey.set(key, index);
+    return index;
+  };
+  const alwaysActive = new Set(nodeUniverse.map((node) => addReference(node)));
+  const rangesByReference = /* @__PURE__ */ new Map();
+  for (const range of assertionRanges) {
+    if (range.start >= range.end) continue;
+    const assertion = requireDefined(assertions[range.assertionIndex]);
+    for (const endpoint of [assertion.a, assertion.b]) {
+      const referenceIndex = addReference(endpoint);
+      const ranges = rangesByReference.get(referenceIndex) ?? [];
+      ranges.push({ start: range.start, end: range.end });
+      rangesByReference.set(referenceIndex, ranges);
+    }
+  }
+  const events = Array.from(
+    { length: leafCount * 4 },
+    () => ({ references: [], sameAssertions: [], differentAssertions: [] })
+  );
+  for (const [referenceIndex, ranges] of rangesByReference) {
+    if (alwaysActive.has(referenceIndex)) continue;
+    for (const range of mergeRanges(ranges)) {
+      addRangeEvent(
+        events,
+        1,
+        0,
+        leafCount,
+        range.start,
+        range.end,
+        (event) => event.references.push(referenceIndex)
+      );
+    }
+  }
+  for (const range of assertionRanges) {
+    if (range.start >= range.end) continue;
+    const assertion = requireDefined(assertions[range.assertionIndex]);
+    addRangeEvent(
+      events,
+      1,
+      0,
+      leafCount,
+      range.start,
+      range.end,
+      (event) => assertion.relation === "same" ? event.sameAssertions.push(range.assertionIndex) : event.differentAssertions.push(range.assertionIndex)
+    );
+  }
+  const state = {
+    assertions,
+    context: identityContext,
+    references,
+    referenceIndexByKey,
+    activeReferences: references.map(() => false),
+    activeReferencesById: /* @__PURE__ */ new Map(),
+    components: {
+      parent: references.map((_reference, index) => index),
+      sizes: references.map(() => 1),
+      kindFirstReference: references.map(
+        (reference, index) => /* @__PURE__ */ new Map([[reference.kind, index]])
+      ),
+      differentAssertions: references.map(() => /* @__PURE__ */ new Set()),
+      violatesOntology: references.map(() => false)
+    },
+    contradictoryAssertions: /* @__PURE__ */ new Set(),
+    undo: [],
+    disjointCache: /* @__PURE__ */ new Map(),
+    sharedIdViolationCount: { value: 0 }
+  };
+  for (const referenceIndex of alwaysActive)
+    activateReference(state, referenceIndex);
+  state.undo.length = 0;
+  visitTemporalEvents(events, state, 1, 0, leafCount);
+}
 
 // src/graph-merge/merge-identity.ts
 function endpointTuple(assertion) {
@@ -246,12 +724,18 @@ function identitySemanticKey(assertion) {
     assertion.b
   );
 }
+function identityDedupeKey(assertion) {
+  const semantic = identitySemanticKey(assertion);
+  if (assertion.validTo === void 0) return semantic;
+  return encodeTupleKey([semantic, assertion.validFrom, assertion.validTo]);
+}
 function compareIdentitySurvivors(left, right) {
   const byValidity = compareCodePoints(left.validFrom, right.validFrom);
   return byValidity === 0 ? compareCodePoints(left.id, right.id) : byValidity;
 }
 var DUPLICATE_IDENTITY_ASSERTION_DROP_REASON = "identity:duplicate-assertion";
 var REDUNDANT_IDENTITY_ASSERTION_DROP_REASON = "identity:endpoints-collapsed";
+var EMPTY_REMAPPED_IDENTITY_WINDOW_DROP_REASON = "identity:empty-remapped-window";
 function droppedIdentityAssertion(assertion, reason) {
   return { kind: "identity", id: assertion.id, reason };
 }
@@ -259,7 +743,7 @@ function dedupeIdentityAssertions(assertions, committedIds) {
   const survivorBySemantic = /* @__PURE__ */ new Map();
   const dropped = [];
   for (const assertion of assertions) {
-    const key = identitySemanticKey(assertion);
+    const key = identityDedupeKey(assertion);
     const previous = survivorBySemantic.get(key);
     if (previous === void 0) {
       survivorBySemantic.set(key, assertion);
@@ -278,7 +762,7 @@ function dedupeIdentityAssertions(assertions, committedIds) {
   }
   return {
     survivors: [...survivorBySemantic.values()].toSorted(
-      (left, right) => compareCodePoints(identitySemanticKey(left), identitySemanticKey(right))
+      (left, right) => compareCodePoints(identityDedupeKey(left), identityDedupeKey(right))
     ),
     dropped
   };
@@ -292,13 +776,26 @@ function assertNoOpposingIdentityRelations(assertions) {
     byEndpoint.set(key, group);
   }
   for (const [endpoint, group] of byEndpoint) {
-    if (new Set(group.map((assertion) => assertion.relation)).size < 2) {
-      continue;
-    }
-    throw new IdentityMergeConflictError(
-      "Branches asserted opposing identity relations for one endpoint pair.",
-      { details: { endpoint, assertions: group } }
+    const same = group.filter((assertion) => assertion.relation === "same");
+    const different = group.filter(
+      (assertion) => assertion.relation === "different"
     );
+    for (const sameAssertion of same) {
+      for (const differentAssertion of different) {
+        if (!identityValidityWindowsOverlap(sameAssertion, differentAssertion)) {
+          continue;
+        }
+        throw new IdentityMergeConflictError(
+          "Branches asserted opposing identity relations for one endpoint pair.",
+          {
+            details: {
+              endpoint,
+              assertions: [sameAssertion, differentAssertion]
+            }
+          }
+        );
+      }
+    }
   }
 }
 function assertNoRetractReassertRace(staging) {
@@ -415,9 +912,10 @@ function resolveIdentityEndpoint(endpoint, canonicalOf, retypeMap) {
     id: idOf(canonical)
   };
 }
-function remapIdentityAssertionEndpoints(assertions, canonicalOf, retypeMap, storedRowsById) {
+function remapIdentityAssertionEndpoints(assertions, canonicalOf, retypeMap, storedRowsById, endpointWindows = /* @__PURE__ */ new Map()) {
   const remapped = [];
   const dropped = [];
+  const narrowingWarningById = /* @__PURE__ */ new Map();
   for (const assertion of assertions) {
     const remappedA = resolveIdentityEndpoint(
       assertion.a,
@@ -445,7 +943,47 @@ function remapIdentityAssertionEndpoints(assertions, canonicalOf, retypeMap, sto
       continue;
     }
     const [a, b] = normalizeIdentityPair(remappedA, remappedB);
-    const result = { ...assertion, a, b };
+    const endpointWindowA = endpointWindows.get(mergeKeyOf(a));
+    const endpointWindowB = endpointWindows.get(mergeKeyOf(b));
+    const validFrom = [
+      assertion.validFrom,
+      endpointWindowA?.validFrom,
+      endpointWindowB?.validFrom
+    ].filter((bound) => bound !== void 0).reduce(
+      (latest, bound) => compareCodePoints(latest, bound) < 0 ? bound : latest
+    );
+    const validTo = [
+      assertion.validTo,
+      endpointWindowA?.validTo,
+      endpointWindowB?.validTo
+    ].filter((bound) => bound !== void 0).reduce(
+      (earliest, bound) => earliest === void 0 || compareCodePoints(bound, earliest) < 0 ? bound : earliest,
+      void 0
+    );
+    if (validTo !== void 0 && compareCodePoints(validFrom, validTo) >= 0) {
+      dropped.push(
+        droppedIdentityAssertion(
+          assertion,
+          EMPTY_REMAPPED_IDENTITY_WINDOW_DROP_REASON
+        )
+      );
+      continue;
+    }
+    if (validFrom !== assertion.validFrom || validTo !== assertion.validTo) {
+      const originalUpper = assertion.validTo ?? "open";
+      const remappedUpper = validTo ?? "open";
+      narrowingWarningById.set(
+        assertion.id,
+        `Identity assertion ${JSON.stringify(assertion.id)} was narrowed from [${assertion.validFrom}, ${originalUpper}) to [${validFrom}, ${remappedUpper}) to fit its remapped endpoint windows.`
+      );
+    }
+    const result = {
+      ...assertion,
+      a,
+      b,
+      validFrom,
+      ...validTo === void 0 ? {} : { validTo }
+    };
     const stored = storedRowsById.get(assertion.id);
     if (stored !== void 0 && assertionTruthKey(stored) === assertionTruthKey(assertion) && assertionTruthKey(result) !== assertionTruthKey(assertion)) {
       throw new IdentityMergeConflictError(
@@ -468,7 +1006,11 @@ function remapIdentityAssertionEndpoints(assertions, canonicalOf, retypeMap, sto
   assertNoOpposingIdentityRelations(deduped.survivors);
   return {
     assertions: deduped.survivors,
-    dropped: [...dropped, ...deduped.dropped]
+    dropped: [...dropped, ...deduped.dropped],
+    warnings: deduped.survivors.flatMap((assertion) => {
+      const warning = narrowingWarningById.get(assertion.id);
+      return warning === void 0 ? [] : [warning];
+    })
   };
 }
 function assertIdentityEndpointsNotDeleted(assertions, nodeDeletions, retypeMap) {
@@ -505,89 +1047,11 @@ function assertNoContradictoryIdentityClosure(plannedAssertions, retractions, ba
       b: resolveIdentityEndpoint(assertion.b, canonicalOf, retypeMap)
     }))
   ];
-  const sameClasses = new UnionFind(
-    (left, right) => compareMergeKeys(left, right)
-  );
-  for (const node of nodeUniverse) {
-    sameClasses.add(mergeKey(node.kind, node.id));
-  }
-  for (const assertion of mergedLedger) {
-    if (assertion.relation === "same") {
-      sameClasses.union(mergeKeyOf(assertion.a), mergeKeyOf(assertion.b));
-    }
-  }
-  const membersOfClass = (root) => sameClasses.members().filter((member) => sameClasses.find(member) === root).map((member) => ({ kind: kindOf(member), id: idOf(member) })).toSorted(
-    (left, right) => compareMergeKeys(mergeKeyOf(left), mergeKeyOf(right))
+  assertTemporalIdentityClosureConsistent(
+    mergedLedger,
+    identityContext,
+    nodeUniverse
   );
-  const firstDisjointPair = (kinds) => {
-    for (const [index, left] of kinds.entries()) {
-      for (const right of kinds.slice(index + 1)) {
-        if (identityContext.areDisjoint(left, right)) return [left, right];
-      }
-    }
-    return void 0;
-  };
-  const refsById = /* @__PURE__ */ new Map();
-  const addRef = (kind, id) => {
-    const keys = refsById.get(id) ?? [];
-    keys.push(mergeKey(kind, id));
-    refsById.set(id, keys);
-  };
-  for (const node of nodeUniverse) addRef(node.kind, node.id);
-  for (const assertion of mergedLedger) {
-    addRef(assertion.a.kind, assertion.a.id);
-    addRef(assertion.b.kind, assertion.b.id);
-  }
-  for (const keys of refsById.values()) {
-    const disjointKinds = firstDisjointPair([
-      ...new Set(keys.map((key) => kindOf(key)))
-    ]);
-    if (disjointKinds === void 0) continue;
-    throw new IdentityMergeConflictError(
-      "The merged graph would give one id to two ontology-disjoint kinds.",
-      {
-        details: {
-          disjointKinds,
-          sharedId: idOf(requireDefined(keys[0]))
-        }
-      }
-    );
-  }
-  if (identityContext.sameIdAcrossKinds === "fold") {
-    for (const keys of refsById.values()) {
-      const [first, ...rest] = keys;
-      if (first === void 0) continue;
-      for (const other of rest) sameClasses.union(first, other);
-    }
-  }
-  for (const assertion of mergedLedger) {
-    if (assertion.relation !== "different") {
-      continue;
-    }
-    const root = sameClasses.find(mergeKeyOf(assertion.a));
-    if (root !== sameClasses.find(mergeKeyOf(assertion.b))) {
-      continue;
-    }
-    throw new IdentityMergeConflictError(
-      "The merged identity ledger would assert one pair of nodes is both the same and different.",
-      { details: { assertion, sameClass: membersOfClass(root) } }
-    );
-  }
-  const kindsByRoot = /* @__PURE__ */ new Map();
-  for (const member of sameClasses.members()) {
-    const root = sameClasses.find(member);
-    const kinds = kindsByRoot.get(root) ?? /* @__PURE__ */ new Set();
-    kinds.add(kindOf(member));
-    kindsByRoot.set(root, kinds);
-  }
-  for (const [root, kinds] of kindsByRoot) {
-    const disjointKinds = firstDisjointPair([...kinds]);
-    if (disjointKinds === void 0) continue;
-    throw new IdentityMergeConflictError(
-      "The merged identity ledger would join two ontology-disjoint kinds into one class.",
-      { details: { disjointKinds, sameClass: membersOfClass(root) } }
-    );
-  }
 }
 async function buildIdentityPeerProbe(target, probedIds, targetPeers, plan, profile) {
   const finalIds = /* @__PURE__ */ new Set([
@@ -608,9 +1072,9 @@ async function buildIdentityPeerProbe(target, probedIds, targetPeers, plan, prof
     seedsByKey.set(mergeKey(kind, id), { kind, id });
   };
   for (const entity of plan.canonicalEntities) {
-    const sourceKey = mergeKey(entity.kind, entity.canonicalId);
-    if (plan.nodeDeletions.has(sourceKey)) continue;
-    addSeed(plan.retypeMap.get(sourceKey) ?? entity.kind, entity.canonicalId);
+    const sourceKey2 = mergeKey(entity.kind, entity.canonicalId);
+    if (plan.nodeDeletions.has(sourceKey2)) continue;
+    addSeed(plan.retypeMap.get(sourceKey2) ?? entity.kind, entity.canonicalId);
   }
   for (const assertion of plan.identityAssertions) {
     addSeed(assertion.a.kind, assertion.a.id);
@@ -789,9 +1253,9 @@ function affectedIdentityClassSeeds(plan, profile) {
   }
   if (profile === "fold") {
     for (const entity of plan.canonicalEntities) {
-      const sourceKey = mergeKey(entity.kind, entity.canonicalId);
-      if (plan.nodeDeletions.has(sourceKey)) continue;
-      addSeed(plan.retypeMap.get(sourceKey) ?? entity.kind, entity.canonicalId);
+      const sourceKey2 = mergeKey(entity.kind, entity.canonicalId);
+      if (plan.nodeDeletions.has(sourceKey2)) continue;
+      addSeed(plan.retypeMap.get(sourceKey2) ?? entity.kind, entity.canonicalId);
     }
   }
   return [...seedsByKey.values()];
@@ -1126,30 +1590,22 @@ function classifyRetraction(assertion, deletedByKey, forkAssertion) {
   }
   return EXPLICIT_RETRACTION;
 }
-async function classifyRetractions(forkStore, retracted, deletedNodes) {
-  if (retracted.length === 0 || deletedNodes.length === 0) {
-    return retracted.map((assertion) => ({
-      assertion,
-      cause: EXPLICIT_RETRACTION
-    }));
-  }
+function classifyRetractions(retracted, deletedNodes, forkRowsById) {
+  if (retracted.length === 0) return [];
   const deletedByKey = new Map(
     deletedNodes.map((deletion) => [
       mergeKey(deletion.kind, deletion.id),
       deletion
     ])
   );
-  const forkRowsById = await storeRuntime(forkStore).identityAssertionRowsByIds(
-    retracted.map((assertion) => assertion.id)
-  );
-  return retracted.map((assertion) => ({
-    assertion,
-    cause: classifyRetraction(
-      assertion,
-      deletedByKey,
-      forkRowsById.get(assertion.id)
-    )
-  }));
+  return retracted.map((assertion) => {
+    const forkAssertion = forkRowsById.get(assertion.id);
+    const endedAssertion = forkAssertion?.validTo !== void 0 && assertionIdentityKey(forkAssertion) === assertionIdentityKey(assertion) ? forkAssertion : assertion;
+    return {
+      assertion: endedAssertion,
+      cause: classifyRetraction(assertion, deletedByKey, forkAssertion)
+    };
+  });
 }
 function byId(left, right) {
   return compareStrings(left.id, right.id);
@@ -1159,8 +1615,8 @@ async function diffAgainstBase(baseStore, forkStore, captureForkState = true) {
   const nodeKinds = getNodeKinds(graph);
   const edgeKinds = getEdgeKinds(graph);
   const [baseIdentity, forkIdentity] = await Promise.all([
-    storeRuntime(baseStore).readCurrentIdentityAssertions("state"),
-    storeRuntime(forkStore).readCurrentIdentityAssertions("state")
+    storeRuntime(baseStore).readCurrentIdentityAssertions("archival"),
+    storeRuntime(forkStore).readCurrentIdentityAssertions("archival")
   ]);
   const baseIdentityById = new Map(
     baseIdentity.map((assertion) => [assertion.id, assertion])
@@ -1252,10 +1708,10 @@ async function diffAgainstBase(baseStore, forkStore, captureForkState = true) {
     const fork = forkIdentityById.get(assertion.id);
     return fork === void 0 || assertionTruthKey(fork) !== assertionTruthKey(assertion);
   }).toSorted((left, right) => compareStrings(left.id, right.id));
-  const classifiedRetractions = await classifyRetractions(
-    forkStore,
+  const classifiedRetractions = classifyRetractions(
     retractedAssertions,
-    deletedNodes
+    deletedNodes,
+    forkIdentityById
   );
   return {
     nodes: {
@@ -1281,7 +1737,7 @@ async function diffAgainstBase(baseStore, forkStore, captureForkState = true) {
       // unsupported id reuse as a typed conflict.
       new: forkIdentity.filter((assertion) => {
         const base = baseIdentityById.get(assertion.id);
-        return base === void 0 || assertionTruthKey(base) !== assertionTruthKey(assertion);
+        return base === void 0 || assertionIdentityKey(base) !== assertionIdentityKey(assertion) && assertionTruthKey(base) !== assertionTruthKey(assertion);
       }).toSorted((left, right) => compareStrings(left.id, right.id)),
       retracted: classifiedRetractions
     },
@@ -1429,12 +1885,24 @@ function contentComponentOf(version) {
 // src/graph-merge/working-copy.ts
 var CLONE_IMPORT_BATCH_SIZE = 1e3;
 function cloneWorkingCopyStrategy(makeBackend) {
+  return cloneWorkingCopyWithGraphStrategy(
+    makeBackend,
+    (baseStore) => baseStore.graph
+  );
+}
+function cloneIngestionWorkingCopyStrategy(makeBackend) {
+  return cloneWorkingCopyWithGraphStrategy(
+    makeBackend,
+    (baseStore) => graphWithoutNodeUniqueness(baseStore.graph)
+  );
+}
+function cloneWorkingCopyWithGraphStrategy(makeBackend, graphForClone) {
   return {
     create: async (baseStore) => {
       const backend = await makeBackend();
       try {
         const [freshStore] = await createStoreWithSchema(
-          baseStore.graph,
+          graphForClone(baseStore),
           backend,
           {
             // Keep descendants branchable with the same O(1) anchor contract,
@@ -1483,6 +1951,30 @@ function cloneWorkingCopyStrategy(makeBackend) {
     }
   };
 }
+function graphWithoutNodeUniqueness(graph) {
+  const nodes = Object.fromEntries(
+    Object.entries(graph.nodes).map(([name, registration]) => {
+      const { unique: _omitted, ...withoutUnique } = registration;
+      return [name, Object.freeze(withoutUnique)];
+    })
+  );
+  const extension = graph.extension?.nodes === void 0 ? graph.extension : Object.freeze({
+    ...graph.extension,
+    nodes: Object.freeze(
+      Object.fromEntries(
+        Object.entries(graph.extension.nodes).map(([name, node]) => {
+          const { unique: _omitted, ...withoutUnique } = node;
+          return [name, Object.freeze(withoutUnique)];
+        })
+      )
+    )
+  });
+  return Object.freeze({
+    ...graph,
+    nodes: Object.freeze(nodes),
+    extension
+  });
+}
 
 // src/graph-merge/branch.ts
 async function branch(baseStore, makeBackend, options, strategy) {
@@ -1491,7 +1983,7 @@ async function branch(baseStore, makeBackend, options, strategy) {
     const id = options?.id ?? asBranchId(generateId());
     const workingCopyStrategy = strategy ?? cloneWorkingCopyStrategy(makeBackend);
     const store = await workingCopyStrategy.create(baseStore);
-    const schemaAnchor = await readSchemaAnchor(store);
+    const schemaAnchor = await captureBranchSchemaAnchor(store);
     return ok({
       id,
       base,
@@ -1506,7 +1998,7 @@ async function branch(baseStore, makeBackend, options, strategy) {
     );
   }
 }
-async function readSchemaAnchor(store) {
+async function captureBranchSchemaAnchor(store) {
   try {
     const schemaRow = await storeBackend(store).getActiveSchema(store.graphId);
     return schemaRow === void 0 ? void 0 : { version: schemaRow.version, hash: schemaRow.schema_hash };
@@ -1519,6 +2011,53 @@ async function readSchemaAnchor(store) {
   }
 }
 
+// src/graph-merge/ingestion-branch.ts
+var PRIVATE_BRANCHES = /* @__PURE__ */ new WeakMap();
+async function ingestionBranch(baseStore, makeBackend, options) {
+  try {
+    const created = await branch(
+      baseStore,
+      makeBackend,
+      options,
+      cloneIngestionWorkingCopyStrategy(makeBackend)
+    );
+    if (isErr(created)) {
+      return err(
+        new BranchError("Failed to create constraint-aware ingestion branch", {
+          cause: created.error
+        })
+      );
+    }
+    const privateBranch = created.data;
+    const { base, id, store } = privateBranch;
+    const handle = Object.freeze({
+      id,
+      base,
+      nodes: store.nodes,
+      edges: store.edges,
+      close: async () => storeBackend(store).close()
+    });
+    PRIVATE_BRANCHES.set(handle, privateBranch);
+    return ok(handle);
+  } catch (error) {
+    return err(
+      new BranchError("Failed to create constraint-aware ingestion branch", {
+        cause: error
+      })
+    );
+  }
+}
+function unwrapMergeBranch(input) {
+  const privateBranch = PRIVATE_BRANCHES.get(input);
+  if (privateBranch !== void 0) {
+    return privateBranch;
+  }
+  return input;
+}
+function unwrapMergeBranches(inputs) {
+  return inputs.map((input) => unwrapMergeBranch(input));
+}
+
 // src/graph-merge/blocking.ts
 var UNBLOCKED_BUCKET_KEY = "unblocked";
 var KEY_PART_SEPARATOR = "\0";
@@ -1527,6 +2066,14 @@ var UNIQUE_KEY_PREFIX = "u";
 function isUniqueBucketKey(key) {
   return key.startsWith(`${UNIQUE_KEY_PREFIX}${KEY_PART_SEPARATOR}`);
 }
+function uniqueConstraintNameForBucket(key) {
+  if (!isUniqueBucketKey(key)) {
+    return void 0;
+  }
+  const constraintStart = UNIQUE_KEY_PREFIX.length + KEY_PART_SEPARATOR.length;
+  const constraintEnd = key.indexOf(KEY_PART_SEPARATOR, constraintStart);
+  return constraintEnd === -1 ? void 0 : key.slice(constraintStart, constraintEnd);
+}
 function constraintSignature(node, constraint) {
   const props = node;
   for (const field of constraint.fields) {
@@ -1874,7 +2421,10 @@ function canonicalizeCluster(cluster, members, policy, branchRank, weights, cano
     canonicalId,
     memberIds,
     kind,
-    branchOrigins
+    branchOrigins,
+    // The merge orchestrator replaces this with the witness selected from the
+    // post-guard surviving edge set. Canonicalization never re-derives evidence.
+    decisiveEdges: []
   };
   const windowSource = members.find(
     (member) => member.branchId === COMMITTED_TARGET_BRANCH && member.kind === kind && member.id === canonicalId
@@ -1886,10 +2436,59 @@ function canonicalizeCluster(cluster, members, policy, branchRank, weights, cano
     resolution,
     conflicts,
     ...windowSource.validFrom === void 0 ? {} : { validFrom: windowSource.validFrom },
-    ...windowSource.validTo === void 0 ? {} : { validTo: windowSource.validTo }
+    ...windowSource.validTo === void 0 ? {} : { validTo: windowSource.validTo },
+    ...windowSource.validFrom === void 0 ? {} : { endpointValidFrom: windowSource.validFrom },
+    ...windowSource.validTo === void 0 ? {} : { endpointValidTo: windowSource.validTo }
   };
 }
 
+// src/graph-merge/union-find.ts
+var UnionFind = class {
+  constructor(compare) {
+    this.compare = 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 = requireDefined(this.parent.get(root));
+    }
+    let cursor = value;
+    while (cursor !== root) {
+      const next = requireDefined(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 EQUIVALENCE_META_EDGES = /* @__PURE__ */ new Set([
@@ -1944,6 +2543,101 @@ function isReachable2(closure, from, to) {
   return isReachable(closure.closure, fromRep, toRep);
 }
 
+// src/graph-merge/evidence.ts
+function entityRef(key) {
+  return { kind: kindOf(key), id: idOf(key) };
+}
+var SOURCE_KIND_ORDER = {
+  block: 0,
+  unique: 1,
+  baseUnique: 2,
+  baseIndex: 3,
+  keyless: 4,
+  retype: 5,
+  custom: 6
+};
+function sourceKey(source) {
+  switch (source.kind) {
+    case "block":
+    case "keyless":
+    case "retype": {
+      return JSON.stringify([SOURCE_KIND_ORDER[source.kind], source.sourceId]);
+    }
+    case "unique":
+    case "baseUnique": {
+      return JSON.stringify([
+        SOURCE_KIND_ORDER[source.kind],
+        source.sourceId,
+        source.constraintName
+      ]);
+    }
+    case "baseIndex": {
+      return JSON.stringify([
+        SOURCE_KIND_ORDER[source.kind],
+        source.sourceId,
+        source.indexName
+      ]);
+    }
+    case "custom": {
+      return JSON.stringify([
+        SOURCE_KIND_ORDER.custom,
+        source.sourceId,
+        source.metadata === void 0 ? "" : canonicalValueKey(source.metadata)
+      ]);
+    }
+    default: {
+      const exhaustive = source;
+      return exhaustive;
+    }
+  }
+}
+function compareMatchSources(left, right) {
+  return compareStrings(sourceKey(left), sourceKey(right));
+}
+function compareEntityRefs(left, right) {
+  return compareMergeKeys(
+    mergeKey(left.kind, left.id),
+    mergeKey(right.kind, right.id)
+  );
+}
+function normalizeMatchSources(sources) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const source of sources) {
+    byKey.set(sourceKey(source), source);
+  }
+  return [...byKey].sort(([, left], [, right]) => compareMatchSources(left, right)).map(([, source]) => source);
+}
+var DEFAULT_HYBRID_WEIGHT = 0.5;
+function describeMatchStrategy(strategy) {
+  switch (strategy.kind) {
+    case "fulltext": {
+      return { kind: "fulltext", fields: [...strategy.fields] };
+    }
+    case "vector": {
+      return { kind: "vector", fields: [strategy.field] };
+    }
+    case "hybrid": {
+      const vector = strategy.weights?.vector ?? DEFAULT_HYBRID_WEIGHT;
+      const fulltext = strategy.weights?.fulltext ?? DEFAULT_HYBRID_WEIGHT;
+      const total = vector + fulltext;
+      const weights = total === 0 ? { vector: DEFAULT_HYBRID_WEIGHT, fulltext: DEFAULT_HYBRID_WEIGHT } : { vector: vector / total, fulltext: fulltext / total };
+      return { kind: "hybrid", fields: [...strategy.fields], weights };
+    }
+    case "custom": {
+      return { kind: "custom" };
+    }
+    default: {
+      const exhaustive = strategy;
+      return exhaustive;
+    }
+  }
+}
+function compareMatchEvidence(left, right) {
+  const byA = compareEntityRefs(left.a, right.a);
+  if (byA !== 0) return byA;
+  return compareEntityRefs(left.b, right.b);
+}
+
 // src/graph-merge/similarity.ts
 var MIN_SCORE = 0;
 var MAX_SCORE = 1;
@@ -2073,18 +2767,18 @@ function cosineFromLookup(embeddings, leftText, rightText) {
   }
   return cosineSimilarity(leftVector, rightVector);
 }
-var DEFAULT_HYBRID_WEIGHT = 0.5;
+var DEFAULT_HYBRID_WEIGHT2 = 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 vector = nonNegativeFinite(weights?.vector ?? DEFAULT_HYBRID_WEIGHT2);
   const fulltext = nonNegativeFinite(
-    weights?.fulltext ?? DEFAULT_HYBRID_WEIGHT
+    weights?.fulltext ?? DEFAULT_HYBRID_WEIGHT2
   );
   const total = vector + fulltext;
   if (total === 0) {
-    return { vector: DEFAULT_HYBRID_WEIGHT, fulltext: DEFAULT_HYBRID_WEIGHT };
+    return { vector: DEFAULT_HYBRID_WEIGHT2, fulltext: DEFAULT_HYBRID_WEIGHT2 };
   }
   return { vector: vector / total, fulltext: fulltext / total };
 }
@@ -2123,7 +2817,36 @@ function prepareNode(node, strategy) {
 function scorePrepared(left, right, strategy, ctx) {
   switch (strategy.kind) {
     case "custom": {
-      const raw = strategy.score(left.node, right.node);
+      let raw;
+      try {
+        raw = strategy.score(left.node, right.node);
+      } catch (error) {
+        return err(
+          new MatchEvidenceError("Custom similarity scorer failed.", {
+            details: {
+              kind: left.node.kind,
+              sourceId: "similarity:custom",
+              operation: "score"
+            },
+            cause: error
+          })
+        );
+      }
+      if (!Number.isFinite(raw)) {
+        return err(
+          new MatchEvidenceError(
+            "Custom similarity scorer returned a non-finite score.",
+            {
+              details: {
+                kind: left.node.kind,
+                sourceId: "similarity:custom",
+                operation: "score",
+                score: String(raw)
+              }
+            }
+          )
+        );
+      }
       return ok(clampScore(raw));
     }
     case "fulltext": {
@@ -2191,25 +2914,51 @@ function compareCandidateEdges(left, right) {
 function endpointKey(a, b) {
   return JSON.stringify([a, b]);
 }
-function scoreCandidates(input, resolveConfig, ctx, ceilingPolicy, maxComparisonsPerKind) {
+function withSources(edge, sources) {
+  return {
+    ...edge,
+    evidence: {
+      ...edge.evidence,
+      sources: normalizeMatchSources([...edge.evidence.sources, ...sources])
+    }
+  };
+}
+function scoreCandidates(input, resolveConfig, ctx, ceilingPolicy, maxComparisonsPerKind, diagnosticLimit = 0) {
   const { similarity, threshold } = resolveConfig;
-  const seen = /* @__PURE__ */ new Set();
-  const forced = [];
+  const forcedByKey = /* @__PURE__ */ new Map();
   for (const edge of input.forcedEdges) {
     const key = endpointKey(edge.a, edge.b);
-    if (!seen.has(key)) {
-      seen.add(key);
-      forced.push(edge);
-    }
+    const previous = forcedByKey.get(key);
+    forcedByKey.set(
+      key,
+      previous === void 0 ? edge : withSources(previous, edge.evidence.sources)
+    );
   }
-  const fuzzy = [];
+  const fuzzyByKey = /* @__PURE__ */ new Map();
   for (const pair of input.pairs) {
     const key = endpointKey(pair.a, pair.b);
-    if (!seen.has(key)) {
-      seen.add(key);
-      fuzzy.push(pair);
+    const forced2 = forcedByKey.get(key);
+    if (forced2 !== void 0) {
+      forcedByKey.set(key, withSources(forced2, pair.sources));
+      continue;
     }
+    const previous = fuzzyByKey.get(key);
+    fuzzyByKey.set(
+      key,
+      previous === void 0 ? pair : {
+        ...previous,
+        sources: normalizeMatchSources([
+          ...previous.sources,
+          ...pair.sources
+        ])
+      }
+    );
   }
+  const forced = [...forcedByKey.values()];
+  const fuzzy = [...fuzzyByKey.values()].sort((left, right) => {
+    const byA = compareMergeKeys(left.a, right.a);
+    return byA === 0 ? compareMergeKeys(left.b, right.b) : byA;
+  });
   if (maxComparisonsPerKind !== void 0 && fuzzy.length > maxComparisonsPerKind) {
     if (ceilingPolicy === "error") {
       return err(
@@ -2236,23 +2985,81 @@ function scoreCandidates(input, resolveConfig, ctx, ceilingPolicy, maxComparison
           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.`
         }
-      ]
+      ],
+      diagnostics: [],
+      diagnosticsTotal: 0
     });
   }
   const scorer = createPairScorer(similarity, ctx);
   const edges = [...forced];
-  for (const { left, right, a, b } of fuzzy) {
+  const diagnostics = [];
+  let diagnosticsTotal = 0;
+  for (const { left, right, a, b, sources } of fuzzy) {
     const scored = scorer(a, left, b, right);
     if (isErr(scored)) {
+      if (similarity.kind === "custom" && scored.error instanceof MatchEvidenceError) {
+        return err(
+          new MatchEvidenceError(scored.error.message, {
+            cause: scored.error,
+            details: {
+              kind: left.kind,
+              operation: "score",
+              sourceIds: normalizeMatchSources(sources).map(
+                (source) => source.sourceId
+              ),
+              endpoints: [entityRef(a), entityRef(b)]
+            }
+          })
+        );
+      }
       return err(scored.error);
     }
-    if (scored.data >= threshold) {
-      edges.push({ a, b, score: scored.data });
+    if (!Number.isFinite(scored.data)) {
+      return err(
+        new MatchEvidenceError(
+          "Similarity scorer returned a non-finite score.",
+          {
+            details: {
+              kind: left.kind,
+              operation: "score",
+              sourceIds: normalizeMatchSources(sources).map(
+                (source) => source.sourceId
+              ),
+              score: String(scored.data)
+            }
+          }
+        )
+      );
+    }
+    const noComparableValues = scored.data < 0;
+    const publicScore = noComparableValues ? 0 : scored.data;
+    const accepted = !noComparableValues && scored.data >= threshold;
+    diagnosticsTotal += 1;
+    const retainsDiagnostic = diagnostics.length < diagnosticLimit;
+    if (accepted || retainsDiagnostic) {
+      const evidence = {
+        a: entityRef(a),
+        b: entityRef(b),
+        sources: normalizeMatchSources(sources),
+        decision: "scored",
+        strategy: describeMatchStrategy(similarity),
+        score: publicScore,
+        threshold
+      };
+      if (accepted) edges.push({ a, b, score: scored.data, evidence });
+      if (!retainsDiagnostic) continue;
+      diagnostics.push({
+        evidence,
+        scoreDecision: accepted ? "accepted" : "rejected",
+        ...noComparableValues ? { reason: "noComparableValues" } : {}
+      });
     }
   }
   return ok({
     edges: edges.sort((left, right) => compareCandidateEdges(left, right)),
-    warnings: []
+    warnings: [],
+    diagnostics,
+    diagnosticsTotal
   });
 }
 
@@ -2354,13 +3161,14 @@ function weakestEdge(edges) {
 }
 function splitUntil(members, edges, isOffending) {
   let surviving = internalEdges(members, edges);
+  const removedEdges = [];
   for (; ; ) {
     const components = buildComponents(surviving, members, true);
     const offending = components.filter(
       (component) => isOffending(component.members, surviving)
     );
     if (offending.length === 0) {
-      return components;
+      return { clusters: components, survivingEdges: surviving, removedEdges };
     }
     let splittable;
     for (const component of offending) {
@@ -2372,11 +3180,16 @@ function splitUntil(members, edges, isOffending) {
     }
     if (splittable === void 0) {
       const offendingSet = new Set(offending);
-      return components.flatMap(
-        (component) => offendingSet.has(component) ? component.members.map((id) => ({ members: [id] })) : [component]
-      );
+      return {
+        clusters: components.flatMap(
+          (component) => offendingSet.has(component) ? component.members.map((id) => ({ members: [id] })) : [component]
+        ),
+        survivingEdges: surviving,
+        removedEdges
+      };
     }
     const weakest = weakestEdge(splittable);
+    removedEdges.push(weakest);
     surviving = surviving.filter((edge) => edge !== weakest);
   }
 }
@@ -2390,16 +3203,30 @@ function splitByDropWeakest(members, edges, maxDiameter) {
 function connectedComponents(candidateEdges, nodeIds) {
   return buildComponents(candidateEdges, nodeIds);
 }
-function enforceDiameter(clusters, candidateEdges, clusterMaxDiameter) {
+function enforceDiameterWithEdges(clusters, candidateEdges, clusterMaxDiameter) {
   const guarded = [];
+  let survivingEdges = [...candidateEdges];
+  const excludedEdges = [];
   for (const component of clusters) {
     if (exceedsDiameter(component.members, candidateEdges, clusterMaxDiameter)) {
-      guarded.push(
-        ...splitByDropWeakest(
-          component.members,
-          candidateEdges,
-          clusterMaxDiameter
-        )
+      const split = splitByDropWeakest(
+        component.members,
+        survivingEdges,
+        clusterMaxDiameter
+      );
+      guarded.push(...split.clusters);
+      const memberSet = new Set(component.members);
+      survivingEdges = [
+        ...survivingEdges.filter(
+          (edge) => !(memberSet.has(edge.a) && memberSet.has(edge.b))
+        ),
+        ...split.survivingEdges
+      ].sort((left, right) => compareCandidateEdges(left, right));
+      excludedEdges.push(
+        ...split.removedEdges.map((edge) => ({
+          edge,
+          reason: "diameter"
+        }))
       );
     } else {
       guarded.push(component);
@@ -2411,7 +3238,7 @@ function enforceDiameter(clusters, candidateEdges, clusterMaxDiameter) {
       requireDefined(right.members[0])
     )
   );
-  return guarded;
+  return { clusters: guarded, survivingEdges, excludedEdges };
 }
 function countBaseMembers(members, baseIds) {
   let count = 0;
@@ -2431,10 +3258,19 @@ function splitByBaseMultiplicity(members, edges, baseIds) {
 }
 function enforceBaseGuard(clusters, candidateEdges, baseIds) {
   if (baseIds.size === 0) {
-    return { clusters, events: [] };
+    return {
+      clusters,
+      events: [],
+      survivingEdges: [...candidateEdges].sort(
+        (left, right) => compareCandidateEdges(left, right)
+      ),
+      excludedEdges: []
+    };
   }
   const result = [];
   const events = [];
+  let survivingEdges = [...candidateEdges];
+  const excludedEdges = [];
   for (const cluster of clusters) {
     const clusterBaseIds = cluster.members.filter((id) => baseIds.has(id));
     if (clusterBaseIds.length < 2) {
@@ -2449,8 +3285,24 @@ function enforceBaseGuard(clusters, candidateEdges, baseIds) {
         (left, right) => compareMergeKeys(left, right)
       )
     });
-    result.push(
-      ...splitByBaseMultiplicity(cluster.members, candidateEdges, baseIds)
+    const split = splitByBaseMultiplicity(
+      cluster.members,
+      survivingEdges,
+      baseIds
+    );
+    result.push(...split.clusters);
+    const memberSet = new Set(cluster.members);
+    survivingEdges = [
+      ...survivingEdges.filter(
+        (edge) => !(memberSet.has(edge.a) && memberSet.has(edge.b))
+      ),
+      ...split.survivingEdges
+    ].sort((left, right) => compareCandidateEdges(left, right));
+    excludedEdges.push(
+      ...split.removedEdges.map((edge) => ({
+        edge,
+        reason: "baseAmbiguity"
+      }))
     );
   }
   result.sort(
@@ -2459,7 +3311,20 @@ function enforceBaseGuard(clusters, candidateEdges, baseIds) {
       requireDefined(right.members[0])
     )
   );
-  return { clusters: result, events };
+  return { clusters: result, events, survivingEdges, excludedEdges };
+}
+function decisiveEdgesForCluster(cluster, survivingEdges) {
+  const members = new Set(cluster.members);
+  const forest = new UnionFind(compareMergeKeys);
+  for (const member of cluster.members) forest.add(member);
+  const decisive = [];
+  for (const edge of internalEdges(cluster.members, survivingEdges)) {
+    if (!members.has(edge.a) || !members.has(edge.b)) continue;
+    if (forest.find(edge.a) === forest.find(edge.b)) continue;
+    forest.union(edge.a, edge.b);
+    decisive.push(edge.evidence);
+  }
+  return decisive;
 }
 
 // src/graph-merge/delete-modify.ts
@@ -2756,8 +3621,9 @@ var WINDOW_NOT_APPLICABLE_DROP_REASON = "window-not-applicable";
 function earliestEnd(claims) {
   let earliest;
   for (const claim of claims) {
-    if (earliest === void 0 || compareStrings(claim.validTo, earliest) < 0) {
-      earliest = claim.validTo;
+    if (claim.change.kind !== "set") continue;
+    if (earliest === void 0 || compareStrings(claim.change.validTo, earliest) < 0) {
+      earliest = claim.change.validTo;
     }
   }
   return earliest;
@@ -2766,18 +3632,26 @@ function resolveEndClaims(claims, preferredBranchId) {
   const preferred = claims.filter(
     (claim) => claim.branchId === preferredBranchId
   );
-  return earliestEnd(preferred.length > 0 ? preferred : claims);
+  const candidates = preferred.length > 0 ? preferred : claims;
+  const earliest = earliestEnd(candidates);
+  return earliest === void 0 ? candidates.some((claim) => claim.change.kind === "clear") ? { kind: "clear" } : void 0 : { kind: "set", validTo: earliest };
 }
 function claimingBranches(claims) {
   return [...new Set(claims.map((claim) => claim.branchId))].sort(
     (left, right) => compareStrings(left, right)
   );
 }
+function sameValidToChange(left, right) {
+  if (left.kind !== right.kind) return false;
+  if (left.kind === "clear") return true;
+  return right.kind === "set" && left.validTo === right.validTo;
+}
 function classifyDelta(base, fork) {
+  const lowerBoundMoved = fork.validFrom !== base.validFrom;
   const endCleared = fork.validTo === void 0 && base.validTo !== void 0;
   return {
-    applicableEnd: fork.validTo !== void 0 && fork.validTo !== base.validTo ? fork.validTo : void 0,
-    unapplicable: endCleared || fork.validFrom !== base.validFrom
+    applicableEnd: fork.validTo !== void 0 && fork.validTo !== base.validTo ? { kind: "set", validTo: fork.validTo } : endCleared && !lowerBoundMoved ? { kind: "clear" } : void 0,
+    unapplicable: lowerBoundMoved
   };
 }
 function resolvePopulation(entity, deltas, deletions, preferredBranchId, dropItem) {
@@ -2812,7 +3686,7 @@ function resolvePopulation(entity, deltas, deletions, preferredBranchId, dropIte
         continue;
       }
       if (applicableEnd !== void 0) {
-        claims.push({ branchId: delta.branchId, validTo: applicableEnd });
+        claims.push({ branchId: delta.branchId, change: applicableEnd });
       }
       if (unapplicable && !reportedUnapplicable) {
         reportedUnapplicable = true;
@@ -2826,27 +3700,29 @@ function resolvePopulation(entity, deltas, deletions, preferredBranchId, dropIte
           entity,
           kind: first.kind,
           id: first.id,
-          validTo: targetEnd,
+          ...targetEnd.kind === "set" ? { validTo: targetEnd.validTo } : { clearValidTo: true },
           claimedBy: claimingBranches(claims),
           precedence: VALIDITY_END_TARGET_PRECEDENCE
         });
       }
       continue;
     }
-    const resolved = earliestEnd(claims);
+    const resolved = resolveEndClaims(claims, void 0);
     if (resolved === void 0) {
       continue;
     }
     ends.set(identity, resolved);
     credits.set(
       identity,
-      claimingBranches(claims.filter((claim) => claim.validTo === resolved))
+      claimingBranches(
+        claims.filter((claim) => sameValidToChange(claim.change, resolved))
+      )
     );
     resolutions.push({
       entity,
       kind: first.kind,
       id: first.id,
-      validTo: resolved,
+      ...resolved.kind === "set" ? { validTo: resolved.validTo } : { clearValidTo: true },
       claimedBy: claimingBranches(claims)
     });
   }
@@ -3070,17 +3946,19 @@ function foldEdgeSet(foldSet, context, branchRank, preferredBranchId) {
   const fromKind = kindOf(survivor.fromKey);
   const toId = idOf(survivor.toKey);
   const toKind = kindOf(survivor.toKey);
-  const preferredSurvivorEnd = survivor.staged.branchId === preferredBranchId ? survivor.staged.validTo : void 0;
+  const preferredSurvivorEnd = survivor.staged.branchId === preferredBranchId ? typeof survivor.staged.validTo === "string" ? { kind: "set", validTo: survivor.staged.validTo } : survivor.staged.clearValidTo === true ? { kind: "clear" } : void 0 : void 0;
   const foldedEnd = preferredSurvivorEnd ?? resolveEndClaims(
-    foldSet.filter((edge) => edge.staged.validTo !== void 0).map((edge) => ({
+    foldSet.filter(
+      (edge) => edge.staged.validTo !== void 0 || edge.staged.clearValidTo === true
+    ).map((edge) => ({
       branchId: edge.staged.branchId,
-      validTo: requireDefined(edge.staged.validTo)
+      change: typeof edge.staged.validTo === "string" ? { kind: "set", validTo: edge.staged.validTo } : { kind: "clear" }
     })),
     preferredBranchId
   );
   const window = {
     ...survivor.staged.validFrom === void 0 ? {} : { validFrom: survivor.staged.validFrom },
-    ...foldedEnd === void 0 ? {} : { validTo: foldedEnd }
+    ...foldedEnd?.kind === "set" ? { validTo: foldedEnd.validTo } : foldedEnd?.kind === "clear" ? { clearValidTo: true } : {}
   };
   const contentKeys = new Set(foldSet.map((edge) => edge.dedupeKey));
   if (contentKeys.size === 1) {
@@ -3225,7 +4103,10 @@ var mergeOptionsScalarSchema = z.object({
   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()
+  clusterMaxDiameter: z.number().positive({ message: "clusterMaxDiameter must be positive" }).optional(),
+  candidateDiagnostics: z.object({
+    limit: z.number().int({ message: "candidateDiagnostics.limit must be an integer" }).min(0, { message: "candidateDiagnostics.limit must be >= 0" })
+  }).strict().optional()
 });
 function validatePropertyConflictPolicy(policy, label) {
   if (typeof policy === "string" && !propertyConflictPolicySchema.safeParse(policy).success) {
@@ -3288,7 +4169,8 @@ function normalizeMergeOptions(options = {}) {
     provenance: options.provenance,
     persistProvenance: options.persistProvenance,
     ...options.maxComparisonsPerKind === void 0 ? {} : { maxComparisonsPerKind: options.maxComparisonsPerKind },
-    ...options.clusterMaxDiameter === void 0 ? {} : { clusterMaxDiameter: options.clusterMaxDiameter }
+    ...options.clusterMaxDiameter === void 0 ? {} : { clusterMaxDiameter: options.clusterMaxDiameter },
+    ...options.candidateDiagnostics === void 0 ? {} : { candidateDiagnostics: options.candidateDiagnostics }
   });
   const onPropertyConflict = validatePropertyConflictPolicy(
     options.onPropertyConflict ?? MERGE_OPTION_DEFAULTS.onPropertyConflict,
@@ -3319,78 +4201,693 @@ function normalizeMergeOptions(options = {}) {
     ...options.target === void 0 ? {} : { target: options.target },
     ...scalar.maxComparisonsPerKind === void 0 ? {} : { maxComparisonsPerKind: scalar.maxComparisonsPerKind },
     ...scalar.clusterMaxDiameter === void 0 ? {} : { clusterMaxDiameter: scalar.clusterMaxDiameter },
+    ...scalar.candidateDiagnostics === void 0 ? {} : { candidateDiagnostics: scalar.candidateDiagnostics },
     ...options.branchOrder === void 0 ? {} : { branchOrder: options.branchOrder },
     ...provenanceWeights === void 0 ? {} : { provenanceWeights }
   };
 }
-var PROVENANCE_KIND = "Provenance";
-var PROVENANCE_OWNER_KIND = "ProvenanceOwner";
-var Provenance = defineNode(PROVENANCE_KIND, {
-  schema: z.object({
-    targetGraphId: z.string(),
-    role: z.enum(["node", "edge"]),
-    canonicalId: z.string(),
-    canonicalKind: z.string(),
-    branchId: z.string(),
-    sourceId: z.string()
-  })
-});
-var PROVENANCE_OWNER = "@nicia-ai/typegraph/merge-provenance";
-var PROVENANCE_OWNER_VERSION = 1;
-var PROVENANCE_OWNER_ID = "merge-provenance-owner";
-var ProvenanceOwner = defineNode(PROVENANCE_OWNER_KIND, {
-  schema: z.object({
-    owner: z.literal(PROVENANCE_OWNER),
-    version: z.literal(PROVENANCE_OWNER_VERSION),
-    targetGraphId: z.string()
-  })
+var MERGE_PLAN_FORMAT_VERSION = 1;
+var MERGE_PLAN_DIGEST_ALGORITHM = "sha256";
+var nonEmptyStringSchema = z.string().min(1);
+var finiteNumberSchema = z.number();
+var nonNegativeIntegerSchema = finiteNumberSchema.int().nonnegative();
+var jsonObjectSchema = z.record(z.string(), z.json());
+var mergePlanEntityRefSchema = z.object({ kind: nonEmptyStringSchema, id: nonEmptyStringSchema }).strict();
+var mergePlanSchemaFenceSchema = z.object({
+  managed: z.boolean(),
+  version: nonNegativeIntegerSchema,
+  hash: nonEmptyStringSchema
+}).strict();
+var mergePlanRevisionFenceSchema = z.object({
+  origin: nonEmptyStringSchema,
+  revision: nonEmptyStringSchema.nullable()
+}).strict();
+var mergePlanTargetFenceSchema = z.object({
+  graphId: nonEmptyStringSchema,
+  schema: mergePlanSchemaFenceSchema,
+  revision: mergePlanRevisionFenceSchema
+}).strict();
+var branchAnchorSchema = z.object({
+  branchId: nonEmptyStringSchema,
+  baseVersion: nonEmptyStringSchema
+}).strict();
+var snapshotAnchorsSchema = z.object({
+  kind: z.literal("snapshot"),
+  base: z.object({
+    graphId: nonEmptyStringSchema,
+    baseVersion: nonEmptyStringSchema
+  }).strict(),
+  branches: z.array(branchAnchorSchema)
+}).strict();
+var incrementalAnchorsSchema = z.object({
+  kind: z.literal("incremental"),
+  forkPoint: z.object({
+    graphId: nonEmptyStringSchema,
+    baseVersion: nonEmptyStringSchema,
+    schema: mergePlanSchemaFenceSchema
+  }).strict(),
+  branches: z.array(branchAnchorSchema)
+}).strict();
+var mergePlanAnchorsSchema = z.discriminatedUnion("kind", [
+  snapshotAnchorsSchema,
+  incrementalAnchorsSchema
+]);
+var nodeUpsertSchema = z.object({
+  kind: nonEmptyStringSchema,
+  id: nonEmptyStringSchema,
+  setProps: jsonObjectSchema,
+  unsetProps: z.array(nonEmptyStringSchema),
+  validFrom: nonEmptyStringSchema.optional(),
+  validTo: nonEmptyStringSchema.optional()
+}).strict();
+var edgeUpsertSchema = z.object({
+  kind: nonEmptyStringSchema,
+  id: nonEmptyStringSchema,
+  from: mergePlanEntityRefSchema,
+  to: mergePlanEntityRefSchema,
+  setProps: jsonObjectSchema,
+  unsetProps: z.array(nonEmptyStringSchema),
+  validFrom: nonEmptyStringSchema.optional(),
+  validTo: nonEmptyStringSchema.optional()
+}).strict();
+var mergePlanIdentityAssertionSchema = z.object({
+  id: nonEmptyStringSchema,
+  relation: z.enum(["same", "different"]),
+  a: mergePlanEntityRefSchema,
+  b: mergePlanEntityRefSchema,
+  validFrom: nonEmptyStringSchema,
+  validTo: nonEmptyStringSchema.optional(),
+  endedBy: mergePlanEntityRefSchema.optional()
+}).strict();
+var mergePlanWritesSchema = z.object({
+  nodeDeletes: z.array(mergePlanEntityRefSchema),
+  nodeUpserts: z.array(nodeUpsertSchema),
+  edgeDeletes: z.array(mergePlanEntityRefSchema),
+  edgeUpserts: z.array(edgeUpsertSchema),
+  identityAssertions: z.array(mergePlanIdentityAssertionSchema),
+  identityRetractions: z.array(mergePlanIdentityAssertionSchema)
+}).strict();
+var proposedRoleSchema = z.object({
+  upserts: nonNegativeIntegerSchema,
+  deletions: nonNegativeIntegerSchema
+}).strict();
+var mergePlanProposedSummarySchema = z.object({
+  nodes: proposedRoleSchema,
+  edges: proposedRoleSchema,
+  identity: z.object({
+    assertions: nonNegativeIntegerSchema,
+    retractions: nonNegativeIntegerSchema
+  }).strict()
+}).strict();
+var mergePlanGuardsSchema = z.object({
+  canonicalMappings: z.array(
+    z.object({
+      member: mergePlanEntityRefSchema,
+      canonical: mergePlanEntityRefSchema
+    }).strict()
+  ),
+  retypes: z.array(
+    z.object({
+      entity: mergePlanEntityRefSchema,
+      toKind: nonEmptyStringSchema
+    }).strict()
+  ),
+  deletedNodes: z.array(mergePlanEntityRefSchema),
+  incremental: z.object({
+    tombstoneResurrection: z.literal("refuse"),
+    lossyUpdates: z.literal("refuse"),
+    edgeIdentity: z.literal("preserve")
+  }).strict().optional()
+}).strict();
+var matchSourceSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("block"), sourceId: nonEmptyStringSchema }).strict(),
+  z.object({
+    kind: z.literal("unique"),
+    sourceId: nonEmptyStringSchema,
+    constraintName: nonEmptyStringSchema
+  }).strict(),
+  z.object({
+    kind: z.literal("baseUnique"),
+    sourceId: nonEmptyStringSchema,
+    constraintName: nonEmptyStringSchema
+  }).strict(),
+  z.object({
+    kind: z.literal("baseIndex"),
+    sourceId: nonEmptyStringSchema,
+    indexName: nonEmptyStringSchema
+  }).strict(),
+  z.object({ kind: z.literal("keyless"), sourceId: nonEmptyStringSchema }).strict(),
+  z.object({ kind: z.literal("retype"), sourceId: nonEmptyStringSchema }).strict(),
+  z.object({
+    kind: z.literal("custom"),
+    sourceId: nonEmptyStringSchema,
+    metadata: z.json().optional()
+  }).strict()
+]);
+var similarityStrategySchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("fulltext"),
+    fields: z.array(nonEmptyStringSchema)
+  }).strict(),
+  z.object({
+    kind: z.literal("vector"),
+    fields: z.array(nonEmptyStringSchema)
+  }).strict(),
+  z.object({
+    kind: z.literal("hybrid"),
+    fields: z.array(nonEmptyStringSchema),
+    weights: z.object({ vector: finiteNumberSchema, fulltext: finiteNumberSchema }).strict()
+  }).strict(),
+  z.object({ kind: z.literal("custom") }).strict()
+]);
+var definitionalEvidenceSchema = z.object({
+  a: mergePlanEntityRefSchema,
+  b: mergePlanEntityRefSchema,
+  sources: z.array(matchSourceSchema),
+  decision: z.literal("definitional")
+}).strict();
+var scoredEvidenceSchema = z.object({
+  a: mergePlanEntityRefSchema,
+  b: mergePlanEntityRefSchema,
+  sources: z.array(matchSourceSchema),
+  decision: z.literal("scored"),
+  strategy: similarityStrategySchema,
+  score: finiteNumberSchema,
+  threshold: finiteNumberSchema
+}).strict();
+var mergePlanMatchEvidenceSchema = z.discriminatedUnion("decision", [
+  definitionalEvidenceSchema,
+  scoredEvidenceSchema
+]);
+var entityResolutionSchema = z.object({
+  canonicalId: nonEmptyStringSchema,
+  memberIds: z.array(nonEmptyStringSchema),
+  kind: nonEmptyStringSchema,
+  branchOrigins: z.array(nonEmptyStringSchema),
+  decisiveEdges: z.array(mergePlanMatchEvidenceSchema)
+}).strict();
+var diagnosticsSchema = z.object({
+  entries: z.array(
+    z.object({
+      evidence: mergePlanMatchEvidenceSchema,
+      scoreDecision: z.enum(["accepted", "rejected"]),
+      reason: z.literal("noComparableValues").optional(),
+      clusterDisposition: z.union([
+        z.literal("retained"),
+        z.object({
+          kind: z.literal("excluded"),
+          reason: z.enum(["diameter", "baseAmbiguity"])
+        }).strict()
+      ]).optional()
+    }).strict()
+  ),
+  total: nonNegativeIntegerSchema,
+  limit: nonNegativeIntegerSchema,
+  truncated: z.boolean()
+}).strict();
+var mergePlanReviewSchema = z.object({
+  resolutions: z.array(entityResolutionSchema),
+  conflicts: z.array(
+    z.object({
+      entityId: nonEmptyStringSchema,
+      kind: nonEmptyStringSchema,
+      property: nonEmptyStringSchema,
+      values: z.array(
+        z.object({ branchId: nonEmptyStringSchema, value: z.json() }).strict()
+      ),
+      resolution: z.json()
+    }).strict()
+  ),
+  deleteModifyConflicts: z.array(
+    z.object({
+      entityId: nonEmptyStringSchema,
+      kind: nonEmptyStringSchema,
+      deletedBy: nonEmptyStringSchema,
+      modifiedBy: nonEmptyStringSchema,
+      resolution: z.enum(["deleteWins", "modifyWins", "flag"])
+    }).strict()
+  ),
+  typeReconciliations: z.array(
+    z.object({
+      entityId: nonEmptyStringSchema,
+      fromTypes: z.array(nonEmptyStringSchema),
+      toType: nonEmptyStringSchema,
+      decisiveEdges: z.array(mergePlanMatchEvidenceSchema).optional()
+    }).strict()
+  ),
+  dropped: z.array(
+    z.discriminatedUnion("kind", [
+      z.object({
+        kind: z.literal("node"),
+        id: nonEmptyStringSchema,
+        reason: nonEmptyStringSchema
+      }).strict(),
+      z.object({
+        kind: z.literal("edge"),
+        id: nonEmptyStringSchema,
+        reason: nonEmptyStringSchema
+      }).strict(),
+      z.object({
+        kind: z.literal("identity"),
+        id: nonEmptyStringSchema,
+        reason: nonEmptyStringSchema
+      }).strict()
+    ])
+  ),
+  validityEnds: z.array(
+    z.object({
+      entity: z.enum(["node", "edge"]),
+      kind: nonEmptyStringSchema,
+      id: nonEmptyStringSchema,
+      validTo: nonEmptyStringSchema,
+      claimedBy: z.array(nonEmptyStringSchema),
+      precedence: z.literal("target").optional()
+    }).strict()
+  ),
+  baseAmbiguities: z.array(
+    z.object({
+      baseIds: z.array(mergePlanEntityRefSchema),
+      memberIds: z.array(mergePlanEntityRefSchema)
+    }).strict()
+  ),
+  provenanceRecords: z.array(
+    z.object({
+      role: z.enum(["node", "edge"]),
+      canonicalId: nonEmptyStringSchema,
+      canonicalKind: nonEmptyStringSchema,
+      branchId: nonEmptyStringSchema,
+      sourceId: nonEmptyStringSchema
+    }).strict()
+  ),
+  warnings: z.array(z.string()),
+  diagnostics: diagnosticsSchema.optional()
+}).strict();
+var mergePlanDigestSchema = z.object({
+  algorithm: z.literal(MERGE_PLAN_DIGEST_ALGORITHM),
+  value: z.string().regex(/^[\da-f]{64}$/)
+}).strict();
+var mergePlanArtifactV1BaseSchema = z.object({
+  formatVersion: z.literal(MERGE_PLAN_FORMAT_VERSION),
+  digest: mergePlanDigestSchema,
+  mode: z.enum(["snapshot", "incremental"]),
+  target: mergePlanTargetFenceSchema,
+  anchors: mergePlanAnchorsSchema,
+  proposed: mergePlanProposedSummarySchema,
+  writes: mergePlanWritesSchema,
+  guards: mergePlanGuardsSchema,
+  review: mergePlanReviewSchema,
+  provenance: z.object({ includeInReport: z.boolean(), persist: z.boolean() }).strict()
+}).strict();
+var mergePlanArtifactV1InputBaseSchema = mergePlanArtifactV1BaseSchema.omit({
+  digest: true
 });
-function provenanceGraphId(targetGraphId) {
-  return `${targetGraphId}::merge-provenance`;
-}
-function buildOwnedProvenanceGraph(targetGraphId) {
-  return defineInternalGraph({
-    id: provenanceGraphId(targetGraphId),
-    nodes: {
-      Provenance: { type: Provenance },
-      ProvenanceOwner: { type: ProvenanceOwner }
-    },
-    edges: {}
-  });
-}
-function buildProvenanceGraph(targetGraphId) {
-  return defineInternalGraph({
-    id: provenanceGraphId(targetGraphId),
-    nodes: { Provenance: { type: Provenance } },
-    edges: {}
-  });
-}
-async function openProvenanceStore(...args) {
-  const [backend, targetGraphId] = args.length === 1 ? [storeBackend(args[0]), args[0].graphId] : args;
-  const graph = buildOwnedProvenanceGraph(targetGraphId);
-  const preflight = await inspectSidecarGraphId(backend, graph, targetGraphId);
-  if (preflight.state === "refuse") {
-    throw provenanceGraphIdCollision(graph.id, targetGraphId, preflight.reason);
+function addSemanticIssues(artifact, ctx) {
+  if (artifact.mode !== artifact.anchors.kind) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["anchors", "kind"],
+      message: `Expected ${artifact.mode} anchors for a ${artifact.mode} plan.`
+    });
   }
-  if (preflight.state !== "owned") {
-    const claim = await claimSidecarOwnership(backend, graph, targetGraphId);
-    if (claim.state === "refuse") {
-      throw provenanceGraphIdCollision(graph.id, targetGraphId, claim.reason);
-    }
+  if (artifact.mode === "incremental" !== (artifact.guards.incremental !== void 0)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["guards", "incremental"],
+      message: "Incremental write guards must be present exactly for incremental plans."
+    });
   }
-  const [store] = await createStoreWithSchema(graph, backend);
-  return store;
-}
-async function claimSidecarOwnership(backend, graph, targetGraphId) {
-  const fence = backend.schemaWriteTransaction;
-  if (fence === void 0) {
-    throw provenanceClaimUnfenced(graph.id, targetGraphId);
+  const expectedCounts = {
+    nodeUpserts: artifact.writes.nodeUpserts.length,
+    nodeDeletions: artifact.writes.nodeDeletes.length,
+    edgeUpserts: artifact.writes.edgeUpserts.length,
+    edgeDeletions: artifact.writes.edgeDeletes.length,
+    assertions: artifact.writes.identityAssertions.length,
+    retractions: artifact.writes.identityRetractions.length
+  };
+  const receivedCounts = {
+    nodeUpserts: artifact.proposed.nodes.upserts,
+    nodeDeletions: artifact.proposed.nodes.deletions,
+    edgeUpserts: artifact.proposed.edges.upserts,
+    edgeDeletions: artifact.proposed.edges.deletions,
+    assertions: artifact.proposed.identity.assertions,
+    retractions: artifact.proposed.identity.retractions
+  };
+  if (JSON.stringify(expectedCounts) !== JSON.stringify(receivedCounts)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["proposed"],
+      message: "Proposed counts must equal the resolved write-set counts."
+    });
   }
-  return fence(graph.id, async (tx) => {
-    await drainUnfencedRowWriters(tx);
-    const verdict = await inspectSidecarGraphId(tx, graph, targetGraphId);
-    if (verdict.state === "refuse" || verdict.state === "owned") return verdict;
-    await tx.insertNode({
+  addOperationIssues(
+    artifact.writes.nodeDeletes,
+    artifact.writes.nodeUpserts,
+    "node",
+    ctx
+  );
+  addOperationIssues(
+    artifact.writes.edgeDeletes,
+    artifact.writes.edgeUpserts,
+    "edge",
+    ctx
+  );
+  for (const [index, upsert] of artifact.writes.nodeUpserts.entries()) {
+    addPropertyPatchIssues(upsert, ["writes", "nodeUpserts", index], ctx);
+  }
+  for (const [index, upsert] of artifact.writes.edgeUpserts.entries()) {
+    addPropertyPatchIssues(upsert, ["writes", "edgeUpserts", index], ctx);
+  }
+  const canonicalByMember = /* @__PURE__ */ new Map();
+  let invalidCanonicalMappings = false;
+  for (const mapping of artifact.guards.canonicalMappings) {
+    const member = entityKey(mapping.member);
+    const canonical = entityKey(mapping.canonical);
+    if (canonicalByMember.has(member)) invalidCanonicalMappings = true;
+    canonicalByMember.set(member, canonical);
+  }
+  for (const canonical of canonicalByMember.values()) {
+    if (canonicalByMember.get(canonical) !== canonical) {
+      invalidCanonicalMappings = true;
+    }
+  }
+  if (invalidCanonicalMappings) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["guards", "canonicalMappings"],
+      message: "Canonical mappings must name each member once and include a self-mapped canonical root."
+    });
+  }
+  const diagnostics = artifact.review.diagnostics;
+  if (diagnostics !== void 0) {
+    const expectedRetained = Math.min(diagnostics.total, diagnostics.limit);
+    if (diagnostics.entries.length !== expectedRetained || diagnostics.truncated !== diagnostics.total > diagnostics.entries.length) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["review", "diagnostics"],
+        message: "Diagnostic retention and truncation metadata must exactly match total and limit."
+      });
+    }
+    for (const [index, diagnostic] of diagnostics.entries.entries()) {
+      addEvidenceIssues(
+        diagnostic.evidence,
+        ["review", "diagnostics", "entries", index, "evidence"],
+        ctx
+      );
+      const accepted = diagnostic.evidence.decision === "definitional" || diagnostic.evidence.score >= diagnostic.evidence.threshold && diagnostic.reason === void 0;
+      if (diagnostic.scoreDecision !== (accepted ? "accepted" : "rejected") || diagnostic.evidence.decision === "scored" && diagnostic.reason === "noComparableValues" && diagnostic.evidence.score !== 0 || diagnostic.evidence.decision === "definitional" && (diagnostic.reason !== void 0 || typeof diagnostic.clusterDisposition !== "object") || diagnostic.scoreDecision === "rejected" && diagnostic.clusterDisposition !== void 0) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["review", "diagnostics", "entries", index],
+          message: "Diagnostic decision, reason, and cluster disposition must agree with its score evidence."
+        });
+      }
+    }
+  }
+  for (const [index, resolution] of artifact.review.resolutions.entries()) {
+    addResolutionEvidenceIssues(artifact, resolution, index, ctx);
+  }
+  for (const [
+    reconciliationIndex,
+    reconciliation
+  ] of artifact.review.typeReconciliations.entries()) {
+    for (const [edgeIndex, evidence] of (reconciliation.decisiveEdges ?? []).entries()) {
+      addEvidenceIssues(
+        evidence,
+        [
+          "review",
+          "typeReconciliations",
+          reconciliationIndex,
+          "decisiveEdges",
+          edgeIndex
+        ],
+        ctx
+      );
+    }
+  }
+}
+function addResolutionEvidenceIssues(artifact, resolution, resolutionIndex, ctx) {
+  const retypedKinds = new Map(
+    artifact.guards.retypes.map((retype) => [
+      entityKey(retype.entity),
+      retype.toKind
+    ])
+  );
+  const clusterMembers = artifact.guards.canonicalMappings.filter((mapping) => {
+    const canonicalKind = retypedKinds.get(entityKey(mapping.canonical)) ?? mapping.canonical.kind;
+    return mapping.canonical.id === resolution.canonicalId && canonicalKind === resolution.kind;
+  }).map((mapping) => mapping.member);
+  const uniqueMembers = new Map(
+    clusterMembers.map((member) => [entityKey(member), member])
+  );
+  const memberIds = new Set(
+    [...uniqueMembers.values()].map((member) => member.id)
+  );
+  const declaredMemberIds = new Set(resolution.memberIds);
+  if (uniqueMembers.size < 2 || declaredMemberIds.size !== resolution.memberIds.length || memberIds.size !== declaredMemberIds.size || [...memberIds].some((id) => !declaredMemberIds.has(id)) || resolution.decisiveEdges.length !== uniqueMembers.size - 1) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["review", "resolutions", resolutionIndex],
+      message: "A resolution must name its complete guarded cluster and carry exactly N-1 decisive edges."
+    });
+    return;
+  }
+  const parent = new Map([...uniqueMembers.keys()].map((key) => [key, key]));
+  const find = (key) => {
+    const next = parent.get(key);
+    if (next === void 0 || next === key) return key;
+    const root = find(next);
+    parent.set(key, root);
+    return root;
+  };
+  let invalidTree = false;
+  for (const [edgeIndex, evidence] of resolution.decisiveEdges.entries()) {
+    addEvidenceIssues(
+      evidence,
+      ["review", "resolutions", resolutionIndex, "decisiveEdges", edgeIndex],
+      ctx
+    );
+    const a = entityKey(evidence.a);
+    const b = entityKey(evidence.b);
+    if (!uniqueMembers.has(a) || !uniqueMembers.has(b)) {
+      invalidTree = true;
+      continue;
+    }
+    const rootA = find(a);
+    const rootB = find(b);
+    if (rootA === rootB) invalidTree = true;
+    else parent.set(rootB, rootA);
+  }
+  if (invalidTree || new Set([...uniqueMembers.keys()].map((key) => find(key))).size !== 1) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["review", "resolutions", resolutionIndex, "decisiveEdges"],
+      message: "Decisive edges must be an acyclic connected witness over the guarded cluster."
+    });
+  }
+}
+function addEvidenceIssues(evidence, path, ctx) {
+  const sourcesCanonical = evidence.sources.every((source, index) => {
+    const previous = evidence.sources[index - 1];
+    return previous === void 0 || compareMatchSources(previous, source) < 0;
+  });
+  const invalidStrategy = evidence.decision === "scored" && (evidence.strategy.kind === "vector" && evidence.strategy.fields.length !== 1 || evidence.strategy.kind === "hybrid" && (evidence.strategy.weights.vector < 0 || evidence.strategy.weights.vector > 1 || evidence.strategy.weights.fulltext < 0 || evidence.strategy.weights.fulltext > 1 || Math.abs(
+    evidence.strategy.weights.vector + evidence.strategy.weights.fulltext - 1
+  ) > Number.EPSILON));
+  if (compareEntityRefs(evidence.a, evidence.b) >= 0 || evidence.sources.length === 0 || !sourcesCanonical || evidence.decision === "scored" && (evidence.score < 0 || evidence.score > 1 || evidence.threshold < 0 || evidence.threshold > 1) || invalidStrategy) {
+    ctx.addIssue({
+      code: "custom",
+      path: [...path],
+      message: "Evidence endpoints and sources must be canonical, and scored values must be within [0, 1]."
+    });
+  }
+}
+function addOperationIssues(deletions, upserts, role, ctx) {
+  const deletionKeys = deletions.map((entry) => entityKey(entry));
+  const upsertKeys = upserts.map((entry) => entityKey(entry));
+  if (new Set(deletionKeys).size !== deletionKeys.length || new Set(upsertKeys).size !== upsertKeys.length) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["writes"],
+      message: `The ${role} write set must not contain duplicate identities.`
+    });
+  }
+  const deleted = new Set(deletionKeys);
+  if (upsertKeys.some((key) => deleted.has(key))) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["writes"],
+      message: `The same ${role} identity cannot be both deleted and upserted.`
+    });
+  }
+}
+function addPropertyPatchIssues(patch, path, ctx) {
+  const unset = new Set(patch.unsetProps);
+  if (unset.size !== patch.unsetProps.length || Object.keys(patch.setProps).some((key) => unset.has(key))) {
+    ctx.addIssue({
+      code: "custom",
+      path: [...path],
+      message: "unsetProps must be duplicate-free and disjoint from setProps keys."
+    });
+  }
+}
+function entityKey(entity) {
+  return JSON.stringify([entity.kind, entity.id]);
+}
+var mergePlanArtifactV1InputSchema = mergePlanArtifactV1InputBaseSchema.superRefine(
+  (artifact, ctx) => addSemanticIssues(artifact, ctx)
+);
+var mergePlanArtifactV1Schema = mergePlanArtifactV1BaseSchema.superRefine(
+  (artifact, ctx) => addSemanticIssues(artifact, ctx)
+);
+
+// src/graph-merge/plan-canonical.ts
+function canonicalMergePlanJson(artifact) {
+  const digestless = "digest" in artifact ? omitDigest(artifact) : artifact;
+  return JSON.stringify(digestless, sortedReplacer);
+}
+async function computeMergePlanDigest(artifact) {
+  return sha256Hex(canonicalMergePlanJson(artifact), 32);
+}
+async function finalizeMergePlanArtifact(artifact) {
+  const finalized = {
+    ...artifact,
+    digest: {
+      algorithm: MERGE_PLAN_DIGEST_ALGORITHM,
+      value: await computeMergePlanDigest(artifact)
+    }
+  };
+  const canonical = JSON.parse(
+    JSON.stringify(finalized, sortedReplacer)
+  );
+  return canonical;
+}
+function omitDigest(artifact) {
+  const { digest: _digest, ...digestless } = artifact;
+  return digestless;
+}
+
+// src/graph-merge/plan-wire.ts
+function parseMergePlanArtifact(input) {
+  const version = readFormatVersion(input);
+  if (version !== MERGE_PLAN_FORMAT_VERSION) {
+    return {
+      success: false,
+      error: { kind: "unsupported-version", received: version }
+    };
+  }
+  const parsed = mergePlanArtifactV1Schema.safeParse(input);
+  if (!parsed.success) {
+    return {
+      success: false,
+      error: { kind: "malformed", issues: parsed.error.issues }
+    };
+  }
+  return {
+    success: true,
+    artifact: parsed.data
+  };
+}
+async function verifyMergePlanDigest(artifact) {
+  const expected = await computeMergePlanDigest(artifact);
+  const received = artifact.digest.value;
+  return expected === received ? { valid: true } : { valid: false, expected, received };
+}
+async function validateMergePlanArtifact(input) {
+  const parsed = parseMergePlanArtifact(input);
+  if (!parsed.success) return parsed;
+  const digest = await verifyMergePlanDigest(parsed.artifact);
+  if (!digest.valid) {
+    return {
+      success: false,
+      error: {
+        kind: "digest-mismatch",
+        expected: digest.expected,
+        received: digest.received
+      }
+    };
+  }
+  return parsed;
+}
+async function constructMergePlanArtifact(input) {
+  const validatedInput = mergePlanArtifactV1InputSchema.parse(input);
+  return finalizeMergePlanArtifact(
+    validatedInput
+  );
+}
+function readFormatVersion(input) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    return void 0;
+  }
+  return Reflect.get(input, "formatVersion");
+}
+var PROVENANCE_KIND = "Provenance";
+var PROVENANCE_OWNER_KIND = "ProvenanceOwner";
+var Provenance = defineNode(PROVENANCE_KIND, {
+  schema: z.object({
+    targetGraphId: z.string(),
+    role: z.enum(["node", "edge"]),
+    canonicalId: z.string(),
+    canonicalKind: z.string(),
+    branchId: z.string(),
+    sourceId: z.string()
+  })
+});
+var PROVENANCE_OWNER = "@nicia-ai/typegraph/merge-provenance";
+var PROVENANCE_OWNER_VERSION = 1;
+var PROVENANCE_OWNER_ID = "merge-provenance-owner";
+var ProvenanceOwner = defineNode(PROVENANCE_OWNER_KIND, {
+  schema: z.object({
+    owner: z.literal(PROVENANCE_OWNER),
+    version: z.literal(PROVENANCE_OWNER_VERSION),
+    targetGraphId: z.string()
+  })
+});
+function provenanceGraphId(targetGraphId) {
+  return `${targetGraphId}::merge-provenance`;
+}
+function buildOwnedProvenanceGraph(targetGraphId) {
+  return defineInternalGraph({
+    id: provenanceGraphId(targetGraphId),
+    nodes: {
+      Provenance: { type: Provenance },
+      ProvenanceOwner: { type: ProvenanceOwner }
+    },
+    edges: {}
+  });
+}
+function buildProvenanceGraph(targetGraphId) {
+  return defineInternalGraph({
+    id: provenanceGraphId(targetGraphId),
+    nodes: { Provenance: { type: Provenance } },
+    edges: {}
+  });
+}
+async function openProvenanceStore(...args) {
+  const [backend, targetGraphId] = args.length === 1 ? [storeBackend(args[0]), args[0].graphId] : args;
+  const graph = buildOwnedProvenanceGraph(targetGraphId);
+  const preflight = await inspectSidecarGraphId(backend, graph, targetGraphId);
+  if (preflight.state === "refuse") {
+    throw provenanceGraphIdCollision(graph.id, targetGraphId, preflight.reason);
+  }
+  if (preflight.state !== "owned") {
+    const claim = await claimSidecarOwnership(backend, graph, targetGraphId);
+    if (claim.state === "refuse") {
+      throw provenanceGraphIdCollision(graph.id, targetGraphId, claim.reason);
+    }
+  }
+  const [store] = await createStoreWithSchema(graph, backend);
+  return store;
+}
+async function claimSidecarOwnership(backend, graph, targetGraphId) {
+  const fence = backend.schemaWriteTransaction;
+  if (fence === void 0) {
+    throw provenanceClaimUnfenced(graph.id, targetGraphId);
+  }
+  return fence(graph.id, async (tx) => {
+    await drainUnfencedRowWriters(tx);
+    const verdict = await inspectSidecarGraphId(tx, graph, targetGraphId);
+    if (verdict.state === "refuse" || verdict.state === "owned") return verdict;
+    await tx.insertNode({
       graphId: graph.id,
       kind: PROVENANCE_OWNER_KIND,
       id: PROVENANCE_OWNER_ID,
@@ -3673,10 +5170,10 @@ async function readProvenance(store, query = {}) {
 }
 
 // src/graph-merge/sources.ts
-function orderEndpoints(left, right) {
+function orderEndpoints(left, right, sources) {
   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 };
+  return compareMergeKeys(leftKey, rightKey) <= 0 ? { a: leftKey, b: rightKey, left, right, sources } : { a: rightKey, b: leftKey, left: right, right: left, sources };
 }
 function sortMembersById(members) {
   return [...members].sort((left, right) => compareStrings(left.id, right.id));
@@ -3719,7 +5216,8 @@ function windowedPairs(members, config) {
       pairs.push(
         orderEndpoints(
           requireDefined(keyed[index]).node,
-          requireDefined(keyed[index_]).node
+          requireDefined(keyed[index_]).node,
+          [{ kind: "keyless", sourceId: "keyless" }]
         )
       );
     }
@@ -3733,8 +5231,22 @@ function pairsFromBlocks(blocks, keyless) {
       continue;
     }
     const members = sortMembersById(blocks.get(bucketKey) ?? []);
-    if (keyless !== void 0 && bucketKey === UNBLOCKED_BUCKET_KEY) {
-      pairs.push(...windowedPairs(members, keyless));
+    if (bucketKey === UNBLOCKED_BUCKET_KEY) {
+      if (keyless !== void 0) {
+        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(
+              requireDefined(members[index]),
+              requireDefined(members[index_]),
+              [{ kind: "keyless", sourceId: "keyless" }]
+            )
+          );
+        }
+      }
       continue;
     }
     for (let index = 0; index < members.length; index += 1) {
@@ -3742,7 +5254,8 @@ function pairsFromBlocks(blocks, keyless) {
         pairs.push(
           orderEndpoints(
             requireDefined(members[index]),
-            requireDefined(members[index_])
+            requireDefined(members[index_]),
+            [{ kind: "block", sourceId: "exactKey" }]
           )
         );
       }
@@ -3757,13 +5270,37 @@ function forcedEdgesFromBlocks(blocks) {
       continue;
     }
     const members = sortMembersById(blocks.get(bucketKey) ?? []);
+    const constraintName = uniqueConstraintNameForBucket(bucketKey);
+    if (constraintName === void 0) {
+      throw new CandidateSourceError(
+        "Unique candidate bucket has no constraint name.",
+        {
+          details: {
+            operation: "candidateEvidence",
+            sourceId: "unique",
+            kind: members[0]?.kind ?? "unknown"
+          }
+        }
+      );
+    }
     for (let index = 0; index < members.length; index += 1) {
       for (let index_ = index + 1; index_ < members.length; index_ += 1) {
         const { a, b } = orderEndpoints(
           requireDefined(members[index]),
-          requireDefined(members[index_])
+          requireDefined(members[index_]),
+          []
         );
-        edges.push({ a, b, score: FORCED_MATCH_SCORE });
+        edges.push({
+          a,
+          b,
+          score: FORCED_MATCH_SCORE,
+          evidence: {
+            a: entityRef(a),
+            b: entityRef(b),
+            sources: [{ kind: "unique", sourceId: "unique", constraintName }],
+            decision: "definitional"
+          }
+        });
       }
     }
   }
@@ -3797,7 +5334,13 @@ function ontologyRetypeEdges(stagedIdentities, isRetypeCompatible) {
         edges.push({
           a: requireDefined(members[0]),
           b: requireDefined(members[index]),
-          score: FORCED_MATCH_SCORE
+          score: FORCED_MATCH_SCORE,
+          evidence: {
+            a: entityRef(requireDefined(members[0])),
+            b: entityRef(requireDefined(members[index])),
+            sources: [{ kind: "retype", sourceId: "retype" }],
+            decision: "definitional"
+          }
         });
       }
     }
@@ -3864,9 +5407,16 @@ var baseUniqueSource = {
   async generate(scope) {
     const { kind, nodes, uniqueConstraints, store } = scope;
     if (nodes === void 0 || uniqueConstraints === void 0 || store === void 0) {
-      throw new MergeError(
+      throw new CandidateSourceError(
         "baseUniqueSource requires nodes, uniqueConstraints, and store in the source scope.",
-        { details: { kind, source: "baseUnique" } }
+        {
+          details: {
+            kind,
+            source: "baseUnique",
+            sourceId: "baseUnique",
+            operation: "generate"
+          }
+        }
       );
     }
     const collection = store.nodes[kind];
@@ -3884,14 +5434,23 @@ var baseUniqueSource = {
         try {
           return await collection.bulkFindByConstraint(constraint.name, items);
         } catch (error) {
-          throw new MergeError(
+          throw new CandidateSourceError(
             `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 }
+            {
+              details: {
+                kind,
+                sourceId: "baseUnique",
+                operation: "lookupConstraint",
+                constraint: constraint.name
+              },
+              cause: error
+            }
           );
         }
       })
     );
-    for (const matches of matchesByConstraint) {
+    for (const [constraintIndex, matches] of matchesByConstraint.entries()) {
+      const constraint = requireDefined(constraints[constraintIndex]);
       for (const [index, node] of nodes.entries()) {
         const base = matches[index];
         if (base === void 0) {
@@ -3905,14 +5464,32 @@ var baseUniqueSource = {
             origin: "base",
             id: base.id,
             kind: base.kind,
-            props: nodeProps(base)
+            props: nodeProps(base),
+            ...base.meta.validFrom === void 0 ? {} : { validFrom: base.meta.validFrom },
+            ...base.meta.validTo === void 0 ? {} : { validTo: base.meta.validTo }
           });
         }
         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 });
+        forcedEdges.push({
+          a,
+          b,
+          score: FORCED_MATCH_SCORE,
+          evidence: {
+            a: entityRef(a),
+            b: entityRef(b),
+            sources: [
+              {
+                kind: "baseUnique",
+                sourceId: "baseUnique",
+                constraintName: constraint.name
+              }
+            ],
+            decision: "definitional"
+          }
+        });
       }
     }
     return {
@@ -3932,9 +5509,16 @@ var baseKeySource = {
       return { pairs: [], forcedEdges: [], baseMembers: [] };
     }
     if (nodes === void 0 || store === void 0) {
-      throw new MergeError(
+      throw new CandidateSourceError(
         "baseKeySource requires nodes and store in the source scope.",
-        { details: { kind, source: "baseKey" } }
+        {
+          details: {
+            kind,
+            source: "baseKey",
+            sourceId: "baseKey",
+            operation: "generate"
+          }
+        }
       );
     }
     const collection = store.nodes[kind];
@@ -3946,9 +5530,17 @@ var baseKeySource = {
     try {
       matchesByNode = await collection.bulkFindByIndex(blockIndex, items);
     } catch (error) {
-      throw new MergeError(
+      throw new CandidateSourceError(
         `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 }
+        {
+          details: {
+            kind,
+            sourceId: "baseKey",
+            operation: "lookupIndex",
+            index: blockIndex
+          },
+          cause: error
+        }
       );
     }
     const pairs = [];
@@ -3963,13 +5555,19 @@ var baseKeySource = {
             origin: "base",
             id: base.id,
             kind: base.kind,
-            props: nodeProps(base)
+            props: nodeProps(base),
+            ...base.meta.validFrom === void 0 ? {} : { validFrom: base.meta.validFrom },
+            ...base.meta.validTo === void 0 ? {} : { validTo: base.meta.validTo }
           });
         }
         if (stagedKey === baseKey) {
           continue;
         }
-        pairs.push(orderEndpoints(stagedNode, base));
+        pairs.push(
+          orderEndpoints(stagedNode, base, [
+            { kind: "baseIndex", sourceId: "baseKey", indexName: blockIndex }
+          ])
+        );
       }
     }
     return {
@@ -4321,6 +5919,8 @@ async function generateAllCandidates(target, staging, options, introspectionKind
   const allEdges = [];
   const warnings = [];
   const baseMembers = [];
+  const diagnostics = [];
+  let diagnosticsTotal = 0;
   const byKind = newNodesByKind(staging);
   const sources = useBaseSources ? [...CANDIDATE_SOURCES, baseUniqueSource, baseKeySource] : CANDIDATE_SOURCES;
   const baseStore = target;
@@ -4329,7 +5929,13 @@ async function generateAllCandidates(target, staging, options, introspectionKind
       async ([kind, items]) => {
         const resolveConfig = options.resolve[kind];
         if (resolveConfig === void 0) {
-          return ok({ edges: [], warnings: [], baseMembers: [] });
+          return ok({
+            edges: [],
+            warnings: [],
+            baseMembers: [],
+            diagnostics: [],
+            diagnosticsTotal: 0
+          });
         }
         const nodes = items.map((staged) => asNode(staged));
         const uniqueConstraints = uniqueConstraintsFor(
@@ -4370,7 +5976,8 @@ async function generateAllCandidates(target, staging, options, introspectionKind
           resolveConfig,
           kindCtx,
           options.onComparisonCeiling,
-          options.maxComparisonsPerKind
+          options.maxComparisonsPerKind,
+          options.candidateDiagnostics?.limit ?? 0
         );
         if (isErr(scored)) {
           return err(scored.error);
@@ -4380,7 +5987,9 @@ async function generateAllCandidates(target, staging, options, introspectionKind
           warnings: scored.data.warnings.map(
             (warning) => `[${kind}] ${warning.message}`
           ),
-          baseMembers: kindBaseMembers
+          baseMembers: kindBaseMembers,
+          diagnostics: scored.data.diagnostics,
+          diagnosticsTotal: scored.data.diagnosticsTotal
         });
       }
     )
@@ -4392,6 +6001,14 @@ async function generateAllCandidates(target, staging, options, introspectionKind
     allEdges.push(...result.data.edges);
     warnings.push(...result.data.warnings);
     baseMembers.push(...result.data.baseMembers);
+    if (options.candidateDiagnostics !== void 0) {
+      diagnostics.push(...result.data.diagnostics);
+      diagnostics.sort(
+        (left, right) => compareMatchEvidence(left.evidence, right.evidence)
+      );
+      diagnostics.splice(options.candidateDiagnostics.limit);
+    }
+    diagnosticsTotal += result.data.diagnosticsTotal;
   }
   return ok({
     // The ONE shared `(a, b)` edge comparator (id-first `(kind, id)` order), so this
@@ -4402,7 +6019,9 @@ async function generateAllCandidates(target, staging, options, introspectionKind
     // base members would tie under a bare-id compare).
     baseMembers: baseMembers.sort(
       (left, right) => compareMergeKeys(mergeKeyOf(left), mergeKeyOf(right))
-    )
+    ),
+    diagnostics,
+    diagnosticsTotal
   });
 }
 function clusterMembersFor(cluster, newNodesById, baseMembersById) {
@@ -4426,7 +6045,9 @@ function clusterMembersFor(cluster, newNodesById, baseMembersById) {
         id: base.id,
         kind: base.kind,
         branchId: BASE_PROVENANCE_BRANCH,
-        props: base.props
+        props: base.props,
+        ...base.validFrom === void 0 ? {} : { validFrom: base.validFrom },
+        ...base.validTo === void 0 ? {} : { validTo: base.validTo }
       });
     }
   }
@@ -4459,7 +6080,7 @@ function buildStagedEdges(staging, modifiedEdges, edgeValidityEnds, edgeDeletion
   for (const item of modifiedEdges) {
     const identity = mergeKeyOf(item.edge);
     stagedIdentities.add(identity);
-    const validTo = edgeValidityEnds.get(identity);
+    const validToChange = edgeValidityEnds.get(identity);
     staged.push({
       id: item.edge.id,
       kind: item.edge.kind,
@@ -4471,13 +6092,13 @@ function buildStagedEdges(staging, modifiedEdges, edgeValidityEnds, edgeDeletion
       props: item.edge.forkProps,
       baseProps: item.edge.baseProps,
       branchId: item.branchId,
-      ...validTo === void 0 ? {} : { validTo }
+      ...validToChange?.kind === "set" ? { validTo: validToChange.validTo } : validToChange?.kind === "clear" ? { clearValidTo: true } : {}
     });
   }
   for (const item of staging.windowedEdges) {
     const identity = mergeKeyOf(item.edge);
-    const validTo = edgeValidityEnds.get(identity);
-    if (validTo === void 0 || stagedIdentities.has(identity) || edgeDeletions.has(identity)) {
+    const validToChange = edgeValidityEnds.get(identity);
+    if (validToChange === void 0 || stagedIdentities.has(identity) || edgeDeletions.has(identity)) {
       continue;
     }
     stagedIdentities.add(identity);
@@ -4493,7 +6114,7 @@ function buildStagedEdges(staging, modifiedEdges, edgeValidityEnds, edgeDeletion
       props: item.edge.props,
       baseProps: item.edge.baseProps,
       branchId: item.branchId,
-      validTo
+      ...validToChange.kind === "set" ? { validTo: validToChange.validTo } : { clearValidTo: true }
     });
   }
   return { edges: staged, windowOnlyCarried };
@@ -4541,7 +6162,7 @@ function buildProvenanceIndex(records) {
   };
 }
 var EMPTY_WEIGHTS = /* @__PURE__ */ new Map();
-function planMerge(staging, candidateEdges, candidateWarnings, baseMembers, options, branchRank, subClassClosure, identityContext, storedIdentityRowsById, targetPeers, preferredBranchId) {
+function buildInternalMergePlan(staging, candidateEdges, candidateWarnings, candidateDiagnostics, candidateDiagnosticsTotal, baseMembers, options, branchRank, subClassClosure, identityContext, storedIdentityRowsById, targetPeers, preferredBranchId) {
   const identity = planIdentityChanges(staging, storedIdentityRowsById);
   const provenanceRecords = [];
   const recordedContributions = /* @__PURE__ */ new Set();
@@ -4593,7 +6214,56 @@ function planMerge(staging, candidateEdges, candidateWarnings, baseMembers, opti
     clusterEdges,
     baseIds
   );
-  const clusters = options.clusterMaxDiameter === void 0 ? guard.clusters : enforceDiameter(guard.clusters, clusterEdges, options.clusterMaxDiameter);
+  const diameterGuard = options.clusterMaxDiameter === void 0 ? {
+    clusters: guard.clusters,
+    survivingEdges: guard.survivingEdges,
+    excludedEdges: []
+  } : enforceDiameterWithEdges(
+    guard.clusters,
+    clusterEdges,
+    options.clusterMaxDiameter
+  );
+  const clusters = diameterGuard.clusters;
+  const baseSurvivingEdges = new Set(guard.survivingEdges);
+  const survivingEdges = diameterGuard.survivingEdges.filter(
+    (edge) => baseSurvivingEdges.has(edge)
+  );
+  const excludedByEndpoints = /* @__PURE__ */ new Map();
+  for (const excluded of [
+    ...guard.excludedEdges,
+    ...diameterGuard.excludedEdges
+  ]) {
+    excludedByEndpoints.set(
+      JSON.stringify([excluded.edge.a, excluded.edge.b]),
+      excluded.reason
+    );
+  }
+  const diagnosticsWithDisposition = candidateDiagnostics.map((diagnostic) => {
+    if (diagnostic.evidence.decision === "definitional") return diagnostic;
+    if (diagnostic.scoreDecision === "rejected") return diagnostic;
+    const a = mergeKey(diagnostic.evidence.a.kind, diagnostic.evidence.a.id);
+    const b = mergeKey(diagnostic.evidence.b.kind, diagnostic.evidence.b.id);
+    const reason = excludedByEndpoints.get(JSON.stringify([a, b]));
+    return {
+      ...diagnostic,
+      clusterDisposition: reason === void 0 ? "retained" : { kind: "excluded", reason }
+    };
+  });
+  const definitionalExclusions = [
+    ...guard.excludedEdges,
+    ...diameterGuard.excludedEdges
+  ].filter((excluded) => excluded.edge.evidence.decision === "definitional").map((excluded) => ({
+    evidence: excluded.edge.evidence,
+    scoreDecision: "accepted",
+    clusterDisposition: {
+      kind: "excluded",
+      reason: excluded.reason
+    }
+  }));
+  const retainedDiagnostics = [
+    ...diagnosticsWithDisposition,
+    ...definitionalExclusions
+  ].sort((left, right) => compareMatchEvidence(left.evidence, right.evidence));
   const baseAmbiguities = guard.events.map((event) => ({
     baseIds: event.baseIds.map((key) => ({ kind: kindOf(key), id: idOf(key) })),
     memberIds: event.memberIds.map((key) => ({
@@ -4603,6 +6273,7 @@ function planMerge(staging, candidateEdges, candidateWarnings, baseMembers, opti
   }));
   const canonicalEntities = [];
   const resolutions = [];
+  const clusterByCanonicalIdentity = /* @__PURE__ */ new Map();
   const propertyConflicts = [];
   const reconcileInputs = [];
   for (const cluster of clusters) {
@@ -4622,6 +6293,10 @@ function planMerge(staging, candidateEdges, candidateWarnings, baseMembers, opti
       preferredBranchId
     );
     canonicalEntities.push(entity);
+    clusterByCanonicalIdentity.set(
+      mergeKey(entity.kind, entity.canonicalId),
+      cluster
+    );
     reconcileInputs.push({
       canonicalId: mergeKey(entity.kind, entity.canonicalId),
       memberKinds: members.map((member) => member.kind)
@@ -4630,7 +6305,10 @@ function planMerge(staging, candidateEdges, candidateWarnings, baseMembers, opti
       cluster.members.map((member) => idOf(member))
     );
     if (distinctMergedIds.size > 1) {
-      resolutions.push(entity.resolution);
+      resolutions.push({
+        ...entity.resolution,
+        decisiveEdges: decisiveEdgesForCluster(cluster, survivingEdges)
+      });
     }
     for (const conflict of entity.conflicts) {
       propertyConflicts.push(conflict);
@@ -4761,6 +6439,21 @@ function planMerge(staging, candidateEdges, candidateWarnings, baseMembers, opti
     subClassClosure,
     options.reconcileTypes
   );
+  const reconciledClusterByEntityId = /* @__PURE__ */ new Map();
+  for (const identity2 of reconciliation.retypeMap.keys()) {
+    const entityId = idOf(identity2);
+    const cluster = clusterByCanonicalIdentity.get(identity2);
+    if (cluster !== void 0 && !reconciledClusterByEntityId.has(entityId)) {
+      reconciledClusterByEntityId.set(entityId, cluster);
+    }
+  }
+  const typeReconciliations = reconciliation.reconciliations.map((item) => {
+    const cluster = reconciledClusterByEntityId.get(item.entityId);
+    return cluster === void 0 ? item : {
+      ...item,
+      decisiveEdges: decisiveEdgesForCluster(cluster, survivingEdges)
+    };
+  });
   const entityByIdentity = /* @__PURE__ */ new Map();
   for (const entity of canonicalEntities) {
     entityByIdentity.set(mergeKey(entity.kind, entity.canonicalId), entity);
@@ -4769,11 +6462,24 @@ function planMerge(staging, candidateEdges, candidateWarnings, baseMembers, opti
     clusters,
     (cluster) => pickClusterCanonical(cluster, entityByIdentity)
   );
+  const canonicalEndpointWindows = /* @__PURE__ */ new Map();
+  for (const entity of canonicalEntities) {
+    if (entity.endpointValidFrom === void 0 && entity.endpointValidTo === void 0) {
+      continue;
+    }
+    const sourceKey2 = mergeKey(entity.kind, entity.canonicalId);
+    const finalKind = reconciliation.retypeMap.get(sourceKey2) ?? entity.kind;
+    canonicalEndpointWindows.set(mergeKey(finalKind, entity.canonicalId), {
+      ...entity.endpointValidFrom === void 0 ? {} : { validFrom: entity.endpointValidFrom },
+      ...entity.endpointValidTo === void 0 ? {} : { validTo: entity.endpointValidTo }
+    });
+  }
   const identityRemap = remapIdentityAssertionEndpoints(
     identity.assertions,
     canonicalOf,
     reconciliation.retypeMap,
-    storedIdentityRowsById
+    storedIdentityRowsById,
+    canonicalEndpointWindows
   );
   assertIdentityEndpointsNotDeleted(
     identityRemap.assertions,
@@ -4897,7 +6603,7 @@ function planMerge(staging, candidateEdges, candidateWarnings, baseMembers, opti
         mergeKey(right.kind, right.entityId)
       )
     ),
-    typeReconciliations: reconciliation.reconciliations,
+    typeReconciliations,
     dropped,
     baseAmbiguities: baseAmbiguities.sort(
       (left, right) => compareMergeKeys(
@@ -4912,7 +6618,18 @@ function planMerge(staging, candidateEdges, candidateWarnings, baseMembers, opti
       )
     ),
     provenanceRecords,
-    warnings: candidateWarnings,
+    warnings: [...candidateWarnings, ...identityRemap.warnings],
+    ...options.candidateDiagnostics === void 0 ? {} : {
+      candidateDiagnostics: {
+        entries: retainedDiagnostics.slice(
+          0,
+          options.candidateDiagnostics.limit
+        ),
+        total: candidateDiagnosticsTotal + definitionalExclusions.length,
+        limit: options.candidateDiagnostics.limit,
+        truncated: candidateDiagnosticsTotal + definitionalExclusions.length > options.candidateDiagnostics.limit
+      }
+    },
     identityAssertions: identityRemap.assertions,
     identityRetractions: survivingRetractions
   };
@@ -4963,13 +6680,13 @@ function plannedNodeWrites(plan) {
       continue;
     }
     written.add(identity);
-    const validTo = plan.nodeValidityEnds.get(identity);
+    const validToChange = plan.nodeValidityEnds.get(identity);
     writes.push({
       identity,
       kind: modification.node.kind,
       id: modification.node.id,
       modification: modification.node,
-      ...validTo === void 0 ? {} : { validTo }
+      ...validToChange?.kind === "set" ? { validTo: validToChange.validTo } : validToChange?.kind === "clear" ? { clearValidTo: true } : {}
     });
   }
   for (const entity of plan.canonicalEntities) {
@@ -4980,7 +6697,7 @@ function plannedNodeWrites(plan) {
     const kind = plan.retypeMap.get(sourceIdentity) ?? entity.kind;
     const modification = modificationsByIdentity.get(sourceIdentity);
     written.add(sourceIdentity);
-    const validTo = entity.validTo ?? plan.nodeValidityEnds.get(sourceIdentity);
+    const validToChange = plan.nodeValidityEnds.get(sourceIdentity);
     writes.push({
       identity: mergeKey(kind, entity.canonicalId),
       kind,
@@ -4988,7 +6705,7 @@ function plannedNodeWrites(plan) {
       entity,
       ...modification === void 0 ? {} : { modification },
       ...entity.validFrom === void 0 ? {} : { validFrom: entity.validFrom },
-      ...validTo === void 0 ? {} : { validTo }
+      ...typeof entity.validTo === "string" ? { validTo: entity.validTo } : validToChange?.kind === "set" ? { validTo: validToChange.validTo } : validToChange?.kind === "clear" ? { clearValidTo: true } : {}
     });
   }
   for (const identity of [...plan.nodeValidityEnds.keys()].sort(
@@ -4998,11 +6715,12 @@ function plannedNodeWrites(plan) {
       continue;
     }
     const kind = plan.retypeMap.get(identity) ?? kindOf(identity);
+    const validToChange = requireDefined(plan.nodeValidityEnds.get(identity));
     writes.push({
       identity: mergeKey(kind, idOf(identity)),
       kind,
       id: idOf(identity),
-      validTo: requireDefined(plan.nodeValidityEnds.get(identity))
+      ...validToChange.kind === "set" ? { validTo: validToChange.validTo } : { clearValidTo: true }
     });
   }
   return writes;
@@ -5013,67 +6731,181 @@ function nodeWriteProps(write, modificationProps) {
     ...write.modification === void 0 ? void 0 : modificationProps(write.modification)
   };
 }
-async function applyMergePlan(plan, nodesApi, edgesApi, target, txBackend) {
-  const committedNodeIds = /* @__PURE__ */ new Set();
-  for (const [identity, kind] of plan.nodeDeletions) {
-    const collection = nodeCollection(nodesApi, kind);
-    await collection.delete(idOf(identity));
+function nodeWriteWindowOptions(write) {
+  const validFrom = write.validFrom === void 0 ? {} : { validFrom: write.validFrom };
+  if (write.clearValidTo === true) {
+    return { ...validFrom, clearValidTo: true };
   }
-  for (const write of plannedNodeWrites(plan)) {
-    const collection = nodeCollection(nodesApi, write.kind);
-    await collection.upsertByIdFromRecord(
-      write.id,
-      nodeWriteProps(
-        write,
-        (modification) => commitModificationProps(modification.baseProps, modification.forkProps)
-      ),
-      {
-        ...write.validFrom === void 0 ? {} : { validFrom: write.validFrom },
-        ...write.validTo === void 0 ? {} : { validTo: write.validTo }
-      }
+  return {
+    ...validFrom,
+    ...write.validTo === void 0 ? {} : { validTo: write.validTo }
+  };
+}
+async function applyNodeRows(target, txBackend, nodesApi, deletions, upserts) {
+  const afterImages = /* @__PURE__ */ new Map();
+  const upsertsByKind = /* @__PURE__ */ new Map();
+  for (const upsert of upserts) {
+    const items = upsertsByKind.get(upsert.kind);
+    if (items === void 0) upsertsByKind.set(upsert.kind, [upsert]);
+    else items.push(upsert);
+  }
+  for (const [kind, items] of upsertsByKind) {
+    const currentRows = await nodeCollection(nodesApi, kind).getByIds(
+      items.map((item) => item.id),
+      INCLUDE_TOMBSTONES
     );
-    committedNodeIds.add(write.identity);
-  }
-  for (const [identity, kind] of plan.edgeDeletions) {
-    await edgeCollection(edgesApi, kind).delete(idOf(identity));
+    const currentById = /* @__PURE__ */ new Map();
+    for (const node of currentRows) {
+      if (node !== void 0) currentById.set(node.id, nodeProps2(node));
+    }
+    for (const item of items) {
+      const props = createDataKeyedBag();
+      const unset = new Set(
+        Object.entries(item.props).filter(([, value]) => value === void 0).map(([key]) => key)
+      );
+      for (const [key, value] of Object.entries(
+        currentById.get(item.id) ?? {}
+      )) {
+        if (!unset.has(key)) props[key] = value;
+      }
+      for (const [key, value] of Object.entries(item.props)) {
+        if (value !== void 0) props[key] = value;
+      }
+      afterImages.set(mergeKey(kind, item.id), props);
+    }
   }
-  const edgesByKind = /* @__PURE__ */ new Map();
-  for (const edge of plan.mergedEdges) {
-    const edgeBaseProps = plan.inheritedEdgeBaseProps.get(edge.id);
-    const props = edgeBaseProps === void 0 ? edge.props : commitModificationProps(edgeBaseProps, edge.props);
-    const item = {
-      id: edge.id,
-      from: finalEdgeEndpoint(plan, edge.fromKind, edge.fromId),
-      to: finalEdgeEndpoint(plan, edge.toKind, edge.toId),
-      props,
-      ...edge.validFrom === void 0 ? {} : { validFrom: edge.validFrom },
-      ...edge.validTo === void 0 ? {} : { validTo: edge.validTo }
-    };
-    const existing = edgesByKind.get(edge.kind);
-    if (existing === void 0) {
-      edgesByKind.set(edge.kind, [item]);
-    } else {
-      existing.push(item);
+  return storeRuntime(target).applyResolvedNodeUniqueness(
+    txBackend,
+    {
+      upserts: upserts.map((upsert) => ({
+        kind: upsert.kind,
+        id: upsert.id,
+        props: requireDefined(
+          afterImages.get(mergeKey(upsert.kind, upsert.id))
+        )
+      })),
+      releases: deletions
+    },
+    async () => {
+      for (const deletion of deletions) {
+        await nodeCollection(nodesApi, deletion.kind).delete(deletion.id);
+      }
+      const committed = /* @__PURE__ */ new Set();
+      for (const upsert of upserts) {
+        await nodeCollection(nodesApi, upsert.kind).upsertByIdFromRecord(
+          upsert.id,
+          upsert.props,
+          nodeWriteWindowOptions(upsert)
+        );
+        committed.add(mergeKey(upsert.kind, upsert.id));
+      }
+      return committed.size;
     }
+  );
+}
+async function applyEdgeRows(edgesApi, deletions, upserts) {
+  for (const deletion of deletions) {
+    await edgeCollection(edgesApi, deletion.kind).delete(deletion.id);
+  }
+  const byKind = /* @__PURE__ */ new Map();
+  for (const upsert of upserts) {
+    const items = byKind.get(upsert.kind);
+    if (items === void 0) byKind.set(upsert.kind, [upsert.item]);
+    else items.push(upsert.item);
   }
-  let committedEdges = 0;
-  for (const [kind, items] of edgesByKind) {
+  let committed = 0;
+  for (const [kind, items] of byKind) {
     await edgeCollection(edgesApi, kind).bulkUpsertById(items);
-    committedEdges += items.length;
+    committed += items.length;
   }
-  let appliedIdentity;
+  return committed;
+}
+async function applyIdentityRows(target, txBackend, assertions, retractions, assertConsistent) {
   try {
-    appliedIdentity = await storeRuntime(target).applyIdentityMergeAtTarget(
+    const applied = await storeRuntime(target).applyIdentityMergeAtTarget(
       txBackend,
-      plan.identityRetractions.map((retraction) => retraction.id),
-      plan.identityAssertions
+      retractions,
+      assertions
     );
-    await assertMergedIdentityClassesConsistent(target, txBackend, plan);
+    if (assertConsistent !== void 0) await assertConsistent();
+    return { asserted: applied.created, retracted: applied.retracted };
   } catch (error) {
     throw translateIdentityCommitError(error);
   }
-  return {
-    nodes: committedNodeIds.size,
+}
+async function applyInternalMergePlan(plan, nodesApi, edgesApi, target, txBackend) {
+  const nodeDeletions = [...plan.nodeDeletions].map(([identity, kind]) => ({
+    kind,
+    id: idOf(identity)
+  }));
+  const nodeUpserts = plannedNodeWrites(plan).map((write) => ({
+    kind: write.kind,
+    id: write.id,
+    props: nodeWriteProps(
+      write,
+      (modification) => commitModificationProps(modification.baseProps, modification.forkProps)
+    ),
+    ...write.validFrom === void 0 ? {} : { validFrom: write.validFrom },
+    ...write.clearValidTo === true ? { clearValidTo: true } : write.validTo === void 0 ? {} : { validTo: write.validTo }
+  }));
+  const validityEndedNodes = new Set(
+    nodeUpserts.filter((write) => "validTo" in write).map((write) => mergeKey(write.kind, write.id))
+  );
+  const earlyIdentityRetractions = plan.identityRetractions.filter(
+    (retraction) => validityEndedNodes.has(mergeKeyOf(retraction.a)) || validityEndedNodes.has(mergeKeyOf(retraction.b))
+  );
+  const earlyIdentity = await applyIdentityRows(
+    target,
+    txBackend,
+    [],
+    earlyIdentityRetractions
+  );
+  let committedNodes;
+  try {
+    committedNodes = await applyNodeRows(
+      target,
+      txBackend,
+      nodesApi,
+      nodeDeletions,
+      nodeUpserts
+    );
+  } catch (error) {
+    throw error instanceof IdentityEndpointValidityError ? translateIdentityCommitError(error) : error;
+  }
+  const edgeDeletions = [...plan.edgeDeletions].map(([identity, kind]) => ({
+    kind,
+    id: idOf(identity)
+  }));
+  const edgeUpserts = [];
+  for (const edge of plan.mergedEdges) {
+    const edgeBaseProps = plan.inheritedEdgeBaseProps.get(edge.id);
+    const props = edgeBaseProps === void 0 ? edge.props : commitModificationProps(edgeBaseProps, edge.props);
+    edgeUpserts.push({
+      kind: edge.kind,
+      item: {
+        id: edge.id,
+        from: finalEdgeEndpoint(plan, edge.fromKind, edge.fromId),
+        to: finalEdgeEndpoint(plan, edge.toKind, edge.toId),
+        props,
+        ...edge.validFrom === void 0 ? {} : { validFrom: edge.validFrom },
+        ...edge.clearValidTo === true ? { clearValidTo: true } : edge.validTo === void 0 ? {} : { validTo: edge.validTo }
+      }
+    });
+  }
+  const committedEdges = await applyEdgeRows(
+    edgesApi,
+    edgeDeletions,
+    edgeUpserts
+  );
+  const appliedIdentity = await applyIdentityRows(
+    target,
+    txBackend,
+    plan.identityAssertions,
+    plan.identityRetractions,
+    () => assertMergedIdentityClassesConsistent(target, txBackend, plan)
+  );
+  return {
+    nodes: committedNodes,
     edges: committedEdges,
     // ACTUAL ledger effects from the applier: rows created (idempotent
     // exact/pair matches the target already held are excluded — the normal
@@ -5082,8 +6914,8 @@ async function applyMergePlan(plan, nodesApi, edgesApi, target, txBackend) {
     // failure aborts the whole merge, so the counts never describe a
     // partial commit.
     identity: {
-      asserted: appliedIdentity.created,
-      retracted: appliedIdentity.retracted
+      asserted: appliedIdentity.asserted,
+      retracted: earlyIdentity.retracted + appliedIdentity.retracted
     }
   };
 }
@@ -5094,26 +6926,39 @@ async function commitPlan(target, plan, expectedBaseVersion) {
       { details: { capability: "transactions" } }
     );
   }
-  return withTxConflictRetry(
-    () => target.transaction(async (tx) => {
-      if (expectedBaseVersion !== void 0) {
-        await assertTargetUnchanged(
+  return runMergeCommit(
+    () => withTxConflictRetry(
+      () => target.transaction(async (tx) => {
+        if (expectedBaseVersion !== void 0) {
+          await assertTargetUnchanged(
+            transactionBackend(tx),
+            target,
+            expectedBaseVersion
+          );
+        }
+        await assertPlannedIdentityIdsFresh(
+          target,
           transactionBackend(tx),
+          plan
+        );
+        return applyInternalMergePlan(
+          plan,
+          tx.nodes,
+          tx.edges,
           target,
-          expectedBaseVersion
+          transactionBackend(tx)
         );
-      }
-      await assertPlannedIdentityIdsFresh(target, transactionBackend(tx), plan);
-      return applyMergePlan(
-        plan,
-        tx.nodes,
-        tx.edges,
-        target,
-        transactionBackend(tx)
-      );
-    }, mergeCommitTransactionOptions(target))
+      }, mergeCommitTransactionOptions(target))
+    )
   );
 }
+async function runMergeCommit(commit) {
+  try {
+    return await commit();
+  } catch (error) {
+    throw translateMergeCommitError(error);
+  }
+}
 var MERGE_COMMIT_TX_OPTIONS = {
   isolationLevel: "serializable"
 };
@@ -5250,7 +7095,169 @@ async function tryOpenProvenanceStore(target) {
     );
   }
 }
-async function resolveMerge(store, target, branches, options, useBaseSources, incremental, expectedBaseVersion) {
+function assertPublicPlanCapability(target) {
+  if (!storeBackend(target).capabilities.transactions) {
+    throw new MergePlanCapabilityError(
+      "Public merge plans require a transaction-capable target backend.",
+      { details: { capability: "transactions" } }
+    );
+  }
+  if (!target.revisionTrackingEnabled) {
+    throw new MergePlanCapabilityError(
+      "Public merge plans require durable target revision tracking.",
+      {
+        details: { capability: "revisionTracking" },
+        suggestion: "Create the target Store with { revisionTracking: true } (or history enabled), then create a new plan."
+      }
+    );
+  }
+}
+async function captureMergePlanTargetFence(target) {
+  assertPublicPlanCapability(target);
+  const [activeSchema, schemaHash, origin, revision] = await Promise.all([
+    storeBackend(target).getActiveSchema(target.graphId),
+    computeSchemaComponent(target),
+    target.revisionOriginNow(),
+    target.revisionNow()
+  ]);
+  return {
+    graphId: target.graphId,
+    schema: {
+      managed: activeSchema !== void 0,
+      version: activeSchema?.version ?? 1,
+      hash: activeSchema?.schema_hash ?? schemaHash
+    },
+    revision: { origin, revision: revision ?? null }
+  };
+}
+function sameMergePlanTargetFence(left, right) {
+  return left.graphId === right.graphId && left.schema.managed === right.schema.managed && left.schema.version === right.schema.version && left.schema.hash === right.schema.hash && left.revision.origin === right.revision.origin && left.revision.revision === right.revision.revision;
+}
+async function assertPlanningFenceUnchanged(target, startingFence) {
+  const endingFence = await captureMergePlanTargetFence(target);
+  if (sameMergePlanTargetFence(startingFence, endingFence)) return;
+  throw new MergePlanningStaleError(
+    "The merge target changed while the plan was being computed; no reviewable plan was produced.",
+    { details: { startingFence, endingFence } }
+  );
+}
+function splitWireProps(props) {
+  const setProps = createDataKeyedBag();
+  const unsetProps = [];
+  for (const key of Object.keys(props).sort(compareStrings)) {
+    const value = props[key];
+    if (value === void 0) {
+      unsetProps.push(key);
+    } else {
+      setProps[key] = value;
+    }
+  }
+  return { setProps, unsetProps };
+}
+function wireEntityRef(kind, id) {
+  return { kind, id };
+}
+function resolvedNodeUpserts(plan) {
+  return plannedNodeWrites(plan).map((write) => ({
+    kind: write.kind,
+    id: write.id,
+    ...splitWireProps(
+      nodeWriteProps(
+        write,
+        (modification) => commitModificationProps(modification.baseProps, modification.forkProps)
+      )
+    ),
+    ...write.validFrom === void 0 ? {} : { validFrom: write.validFrom },
+    ...write.validTo === void 0 ? {} : { validTo: write.validTo }
+  }));
+}
+async function resolvedMergeArtifact(resolved, mode, targetFence, anchors) {
+  const { plan, options } = resolved;
+  const nodeUpserts = resolvedNodeUpserts(plan);
+  const edgeUpserts = plan.mergedEdges.map((edge) => {
+    const baseProps = plan.inheritedEdgeBaseProps.get(edge.id);
+    const props = baseProps === void 0 ? edge.props : commitModificationProps(baseProps, edge.props);
+    return {
+      kind: edge.kind,
+      id: edge.id,
+      from: finalEdgeEndpoint(plan, edge.fromKind, edge.fromId),
+      to: finalEdgeEndpoint(plan, edge.toKind, edge.toId),
+      ...splitWireProps(props),
+      ...edge.validFrom === void 0 ? {} : { validFrom: edge.validFrom },
+      ...edge.validTo === void 0 ? {} : { validTo: edge.validTo }
+    };
+  });
+  const input = {
+    formatVersion: 1,
+    mode,
+    target: targetFence,
+    anchors,
+    proposed: {
+      nodes: {
+        upserts: nodeUpserts.length,
+        deletions: plan.nodeDeletions.size
+      },
+      edges: {
+        upserts: edgeUpserts.length,
+        deletions: plan.edgeDeletions.size
+      },
+      identity: {
+        assertions: plan.identityAssertions.length,
+        retractions: plan.identityRetractions.length
+      }
+    },
+    writes: {
+      nodeDeletes: [...plan.nodeDeletions].map(
+        ([identity, kind]) => wireEntityRef(kind, idOf(identity))
+      ),
+      nodeUpserts,
+      edgeDeletes: [...plan.edgeDeletions].map(
+        ([identity, kind]) => wireEntityRef(kind, idOf(identity))
+      ),
+      edgeUpserts,
+      identityAssertions: plan.identityAssertions,
+      identityRetractions: plan.identityRetractions
+    },
+    guards: {
+      canonicalMappings: [...plan.canonicalOf].sort(([left], [right]) => compareMergeKeys(left, right)).map(([member, canonical]) => ({
+        member: wireEntityRef(kindOf(member), idOf(member)),
+        canonical: wireEntityRef(kindOf(canonical), idOf(canonical))
+      })),
+      retypes: [...plan.retypeMap].sort(([left], [right]) => compareMergeKeys(left, right)).map(([entity, toKind]) => ({
+        entity: wireEntityRef(kindOf(entity), idOf(entity)),
+        toKind
+      })),
+      deletedNodes: [...plan.nodeDeletions].map(
+        ([identity, kind]) => wireEntityRef(kind, idOf(identity))
+      ),
+      ...resolved.incrementalGuard === void 0 ? {} : {
+        incremental: {
+          tombstoneResurrection: "refuse",
+          lossyUpdates: "refuse",
+          edgeIdentity: "preserve"
+        }
+      }
+    },
+    review: {
+      resolutions: plan.resolutions,
+      conflicts: plan.propertyConflicts,
+      deleteModifyConflicts: plan.deleteModifyConflicts,
+      typeReconciliations: plan.typeReconciliations,
+      dropped: plan.dropped,
+      validityEnds: plan.validityEnds,
+      baseAmbiguities: plan.baseAmbiguities,
+      provenanceRecords: plan.provenanceRecords,
+      warnings: plan.warnings,
+      ...plan.candidateDiagnostics === void 0 ? {} : { diagnostics: plan.candidateDiagnostics }
+    },
+    provenance: {
+      includeInReport: options.provenance,
+      persist: options.persistProvenance
+    }
+  };
+  return constructMergePlanArtifact(input);
+}
+async function resolveMerge(store, target, branches, options, useBaseSources, incremental, expectedBaseVersion, complete) {
   let targetBranchSeen = false;
   for (const branch2 of branches) {
     if (branch2.id === BASE_PROVENANCE_BRANCH) {
@@ -5303,10 +7310,6 @@ async function resolveMerge(store, target, branches, options, useBaseSources, in
       );
     }
   }
-  const provenanceStore = options.persistProvenance ? await tryOpenProvenanceStore(target) : void 0;
-  if (provenanceStore !== void 0 && isErr(provenanceStore)) {
-    return provenanceStore;
-  }
   try {
     const preferredBranchId = incremental?.targetBranchId;
     const staging = await stageBranches(store, branches, preferredBranchId);
@@ -5375,10 +7378,12 @@ async function resolveMerge(store, target, branches, options, useBaseSources, in
       sameIdAcrossKinds: target.graph.identity?.sameIdAcrossKinds,
       areDisjoint: (left, right) => target.registry.areDisjoint(left, right)
     };
-    const plan = planMerge(
+    const plan = buildInternalMergePlan(
       staging,
       candidates.data.edges,
       candidates.data.warnings,
+      candidates.data.diagnostics,
+      candidates.data.diagnosticsTotal,
       candidates.data.baseMembers,
       options,
       branchRank,
@@ -5434,29 +7439,731 @@ async function resolveMerge(store, target, branches, options, useBaseSources, in
       );
       identityGuard = built.probe;
     }
-    const merged = incremental === void 0 ? await commitPlan(target, plan, expectedBaseVersion) : await commitIncrementalPlan(target, plan, {
+    const incrementalGuard = incremental === void 0 ? void 0 : {
       stagedNewByKind,
       options,
       introspectionKinds,
       forkPoint: incremental.forkPoint,
       ...identityGuard === void 0 ? {} : { identityPeerProbe: identityGuard },
-      // 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))
       ),
       targetNodeVersions: staging.targetNodeVersions,
       targetEdgeSignatures: staging.targetEdgeSignatures
-    });
-    const provenance = options.provenance ? buildProvenanceIndex(plan.provenanceRecords) : { byBranch: () => ({ nodeIds: [], edgeIds: [] }) };
-    const warnings = [...plan.warnings];
+    };
+    return ok(
+      await complete({
+        target,
+        plan,
+        options,
+        ...expectedBaseVersion === void 0 ? {} : { expectedBaseVersion },
+        ...incrementalGuard === void 0 ? {} : { incrementalGuard }
+      })
+    );
+  } 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 commitResolvedMerge(resolved) {
+  const { target, plan, options } = resolved;
+  const provenanceStore = options.persistProvenance ? await tryOpenProvenanceStore(target) : void 0;
+  if (provenanceStore !== void 0 && isErr(provenanceStore)) {
+    throw provenanceStore.error;
+  }
+  const merged = resolved.incrementalGuard === void 0 ? await commitPlan(target, plan, resolved.expectedBaseVersion) : await commitIncrementalPlan(target, plan, resolved.incrementalGuard);
+  const provenance = options.provenance ? buildProvenanceIndex(plan.provenanceRecords) : { byBranch: () => ({ nodeIds: [], edgeIds: [] }) };
+  const warnings = [...plan.warnings];
+  let provenancePersisted;
+  if (provenanceStore !== void 0 && !isErr(provenanceStore)) {
+    try {
+      const count = await persistProvenanceRecords(
+        provenanceStore.data,
+        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))
+      );
+    }
+  }
+  return {
+    merged,
+    resolutions: plan.resolutions,
+    conflicts: plan.propertyConflicts,
+    deleteModifyConflicts: plan.deleteModifyConflicts,
+    typeReconciliations: plan.typeReconciliations,
+    dropped: plan.dropped,
+    validityEnds: plan.validityEnds,
+    baseAmbiguities: plan.baseAmbiguities,
+    provenance,
+    warnings,
+    ...plan.candidateDiagnostics === void 0 ? {} : { candidateDiagnostics: plan.candidateDiagnostics },
+    ...provenancePersisted === void 0 ? {} : { provenancePersisted }
+  };
+}
+function incrementalBaseConflictPolicyError(options) {
+  return new InvalidMergeOptionsError(
+    'mergeIncremental() requires onBasePropertyConflict: "flag" (keep-base); a non-keep-base policy could overwrite a newer committed base value with a stale branch value.',
+    {
+      details: {
+        option: "onBasePropertyConflict",
+        accepted: "flag",
+        received: options.onBasePropertyConflict
+      }
+    }
+  );
+}
+function incrementalSchemaError() {
+  return 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: {} }
+  );
+}
+async function planMerge(store, branchInputs, optionsInput = {}) {
+  const branches = unwrapMergeBranches(branchInputs);
+  const normalized = tryNormalize(optionsInput);
+  if (isErr(normalized)) return err(normalized.error);
+  const options = normalized.data;
+  const target = options.target ?? store;
+  let targetFence;
+  try {
+    targetFence = await captureMergePlanTargetFence(target);
+  } catch (error) {
+    return err(
+      error instanceof MergeError ? error : new MergePlanCapabilityError(
+        `Unable to capture the target's durable plan fence: ${describeCause(error)}`,
+        { cause: error }
+      )
+    );
+  }
+  const precondition = await validateBaseVersions(target, branches);
+  if (isErr(precondition)) return err(precondition.error);
+  const anchors = {
+    kind: "snapshot",
+    base: { graphId: store.graphId, baseVersion: precondition.data },
+    branches: [...branches].sort((left, right) => compareStrings(left.id, right.id)).map((branch2) => ({
+      branchId: branch2.id,
+      baseVersion: branch2.base
+    }))
+  };
+  return resolveMerge(
+    store,
+    target,
+    branches,
+    options,
+    false,
+    void 0,
+    precondition.data,
+    async (resolved) => {
+      await assertPlanningFenceUnchanged(target, targetFence);
+      return resolvedMergeArtifact(resolved, "snapshot", targetFence, anchors);
+    }
+  );
+}
+async function planMergeIncremental(args) {
+  const { forkPoint, target } = args;
+  const branches = unwrapMergeBranches(args.branches);
+  const normalized = tryNormalize(args.options ?? {}, ["target"]);
+  if (isErr(normalized)) return err(normalized.error);
+  const options = normalized.data;
+  if (options.onBasePropertyConflict !== "flag") {
+    return err(incrementalBaseConflictPolicyError(options));
+  }
+  let targetFence;
+  try {
+    targetFence = await captureMergePlanTargetFence(target);
+  } catch (error) {
+    return err(
+      error instanceof MergeError ? error : new MergePlanCapabilityError(
+        `Unable to capture the target's durable plan fence: ${describeCause(error)}`,
+        { cause: error }
+      )
+    );
+  }
+  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(incrementalSchemaError());
+  const forkActiveSchema = await storeBackend(forkPoint).getActiveSchema(
+    forkPoint.graphId
+  );
+  const targetBranch = {
+    id: COMMITTED_TARGET_BRANCH,
+    base: forkVersion,
+    store: target
+  };
+  const anchors = {
+    kind: "incremental",
+    forkPoint: {
+      graphId: forkPoint.graphId,
+      baseVersion: forkVersion,
+      schema: {
+        managed: forkActiveSchema !== void 0,
+        version: forkActiveSchema?.version ?? 1,
+        hash: forkActiveSchema?.schema_hash ?? forkSchema
+      }
+    },
+    branches: [...branches].sort((left, right) => compareStrings(left.id, right.id)).map((branch2) => ({
+      branchId: branch2.id,
+      baseVersion: branch2.base
+    }))
+  };
+  return resolveMerge(
+    forkPoint,
+    target,
+    [targetBranch, ...branches],
+    options,
+    true,
+    {
+      targetBranchId: COMMITTED_TARGET_BRANCH,
+      forkPoint: { store: forkPoint, version: forkVersion }
+    },
+    void 0,
+    async (resolved) => {
+      await assertPlanningFenceUnchanged(target, targetFence);
+      await assertForkPointUnchanged({
+        store: forkPoint,
+        version: forkVersion
+      });
+      return resolvedMergeArtifact(
+        resolved,
+        "incremental",
+        targetFence,
+        anchors
+      );
+    }
+  );
+}
+function mergePlanValidationError(failure) {
+  switch (failure.kind) {
+    case "unsupported-version": {
+      return new UnsupportedMergePlanVersionError(
+        `Unsupported merge plan format version ${String(failure.received)}.`,
+        { details: { received: failure.received } }
+      );
+    }
+    case "digest-mismatch": {
+      return new MergePlanDigestMismatchError(
+        "The merge plan digest does not match its canonical content.",
+        { details: { expected: failure.expected, received: failure.received } }
+      );
+    }
+    case "malformed": {
+      return new InvalidMergePlanError("The merge plan is malformed.", {
+        details: { issues: failure.issues }
+      });
+    }
+    default: {
+      const exhaustive = failure;
+      return exhaustive;
+    }
+  }
+}
+function wireWriteProps(setProps, unsetProps) {
+  const props = createDataKeyedBag();
+  for (const [key, value] of Object.entries(setProps)) props[key] = value;
+  for (const key of unsetProps) props[key] = void 0;
+  return props;
+}
+function resolvedWireProps(current, setProps, unsetProps) {
+  const props = createDataKeyedBag();
+  const unset = new Set(unsetProps);
+  for (const [key, value] of Object.entries(current)) {
+    if (!unset.has(key)) props[key] = value;
+  }
+  for (const [key, value] of Object.entries(setProps)) props[key] = value;
+  return props;
+}
+function invalidPlanForTarget(message, details) {
+  return new InvalidMergePlanError(message, { details });
+}
+async function preflightWireMergeWrites(target, nodesApi, edgesApi, artifact) {
+  const graphNodes = target.graph.nodes;
+  const graphEdges = target.graph.edges;
+  const assertNodeKind = (kind) => {
+    if (!hasOwnKey(graphNodes, kind)) {
+      throw invalidPlanForTarget(
+        `The merge plan references unknown node kind "${kind}".`,
+        { kind, role: "node" }
+      );
+    }
+  };
+  const assertEdgeKind = (kind) => {
+    if (!hasOwnKey(graphEdges, kind) || graphEdges[kind] === void 0) {
+      throw invalidPlanForTarget(
+        `The merge plan references unknown edge kind "${kind}".`,
+        { kind, role: "edge" }
+      );
+    }
+  };
+  for (const item of [
+    ...artifact.writes.nodeDeletes,
+    ...artifact.writes.nodeUpserts,
+    ...artifact.guards.deletedNodes,
+    ...artifact.guards.canonicalMappings.flatMap((mapping) => [
+      mapping.member,
+      mapping.canonical
+    ]),
+    ...artifact.guards.retypes.map((retype) => retype.entity),
+    ...artifact.writes.identityAssertions.flatMap((assertion) => [
+      assertion.a,
+      assertion.b
+    ]),
+    ...artifact.writes.identityRetractions.flatMap((assertion) => [
+      assertion.a,
+      assertion.b
+    ])
+  ]) {
+    assertNodeKind(item.kind);
+  }
+  for (const retype of artifact.guards.retypes) assertNodeKind(retype.toKind);
+  for (const item of [
+    ...artifact.writes.edgeDeletes,
+    ...artifact.writes.edgeUpserts
+  ]) {
+    assertEdgeKind(item.kind);
+  }
+  const plannedNodes = new Set(
+    artifact.writes.nodeUpserts.map(
+      (upsert) => mergeKey(upsert.kind, upsert.id)
+    )
+  );
+  const deletedNodes = new Set(
+    artifact.writes.nodeDeletes.map(
+      (deletion) => mergeKey(deletion.kind, deletion.id)
+    )
+  );
+  const endpointRows = /* @__PURE__ */ new Map();
+  const readEndpoint = async (endpoint) => {
+    const key = mergeKey(endpoint.kind, endpoint.id);
+    if (endpointRows.has(key)) return endpointRows.get(key);
+    const row = (await nodeCollection(nodesApi, endpoint.kind).getByIds(
+      [endpoint.id],
+      INCLUDE_TOMBSTONES
+    ))[0];
+    endpointRows.set(key, row);
+    return row;
+  };
+  const nodeUpsertsByKind = /* @__PURE__ */ new Map();
+  for (const upsert of artifact.writes.nodeUpserts) {
+    const upserts = nodeUpsertsByKind.get(upsert.kind) ?? [];
+    upserts.push(upsert);
+    nodeUpsertsByKind.set(upsert.kind, upserts);
+  }
+  const currentNodesByIdentity = /* @__PURE__ */ new Map();
+  for (const [kind, upserts] of nodeUpsertsByKind) {
+    const rows = await nodeCollection(nodesApi, kind).getByIds(
+      upserts.map((upsert) => upsert.id),
+      INCLUDE_TOMBSTONES
+    );
+    for (const [index, upsert] of upserts.entries()) {
+      const row = rows[index];
+      const identity = mergeKey(kind, upsert.id);
+      currentNodesByIdentity.set(identity, row);
+      endpointRows.set(identity, row);
+    }
+  }
+  for (const upsert of artifact.writes.nodeUpserts) {
+    const current = currentNodesByIdentity.get(
+      mergeKey(upsert.kind, upsert.id)
+    );
+    if (artifact.guards.incremental !== void 0 && current?.meta.deletedAt !== void 0) {
+      throw invalidPlanForTarget(
+        `The incremental merge plan would resurrect soft-deleted committed node "${upsert.id}".`,
+        { kind: upsert.kind, id: upsert.id, role: "node" }
+      );
+    }
+    const props = resolvedWireProps(
+      current === void 0 ? {} : nodeProps2(current),
+      upsert.setProps,
+      upsert.unsetProps
+    );
+    const schema = nodeSchemaFor(target, upsert.kind);
+    if (schema !== void 0 && !schema.safeParse(props).success) {
+      throw invalidPlanForTarget(
+        `The merge plan's node write for "${upsert.id}" does not validate against the active schema.`,
+        { kind: upsert.kind, id: upsert.id, role: "node" }
+      );
+    }
+    if (artifact.guards.incremental !== void 0 && current !== void 0) {
+      const analysis = analyzeRevalidatingWrite(
+        schema,
+        nodeProps2(current),
+        wireWriteProps(upsert.setProps, upsert.unsetProps)
+      );
+      assertValidRevalidatingWrite(
+        analysis,
+        `The incremental merge plan found committed node "${upsert.id}" with props that do not validate against the active schema.`,
+        { kind: upsert.kind, id: upsert.id, role: "node" }
+      );
+      if (analysis.stripsCurrentProps && analysis.schemaWouldChange) {
+        throw invalidPlanForTarget(
+          `The incremental merge plan would strip existing props while updating committed node "${upsert.id}".`,
+          { kind: upsert.kind, id: upsert.id, role: "node" }
+        );
+      }
+    }
+  }
+  const currentEdgeIds = /* @__PURE__ */ new Set();
+  const edgeUpsertsByKind = /* @__PURE__ */ new Map();
+  for (const upsert of artifact.writes.edgeUpserts) {
+    const upserts = edgeUpsertsByKind.get(upsert.kind) ?? [];
+    upserts.push(upsert);
+    edgeUpsertsByKind.set(upsert.kind, upserts);
+  }
+  const currentEdgesByIdentity = /* @__PURE__ */ new Map();
+  for (const [kind, upserts] of edgeUpsertsByKind) {
+    const rows = await edgeCollection(edgesApi, kind).getByIds(
+      upserts.map((upsert) => upsert.id),
+      INCLUDE_TOMBSTONES
+    );
+    for (const [index, upsert] of upserts.entries()) {
+      const row = rows[index];
+      currentEdgesByIdentity.set(mergeKey(kind, upsert.id), row);
+      if (row !== void 0) currentEdgeIds.add(upsert.id);
+    }
+  }
+  for (const upsert of artifact.writes.edgeUpserts) {
+    const registration = requireDefined(graphEdges[upsert.kind]);
+    const endpointError = validateEdgeEndpoints(
+      upsert.kind,
+      upsert.from.kind,
+      upsert.to.kind,
+      registration,
+      target.registry
+    );
+    if (endpointError !== void 0) {
+      throw invalidPlanForTarget(endpointError.message, {
+        kind: upsert.kind,
+        id: upsert.id,
+        role: "edge"
+      });
+    }
+    for (const endpoint of [upsert.from, upsert.to]) {
+      assertNodeKind(endpoint.kind);
+      const key = mergeKey(endpoint.kind, endpoint.id);
+      if (deletedNodes.has(key)) {
+        throw invalidPlanForTarget(
+          `The merge plan deletes an endpoint required by edge "${upsert.id}".`,
+          { edgeKind: upsert.kind, edgeId: upsert.id, endpoint }
+        );
+      }
+      if (plannedNodes.has(key)) continue;
+      const row = await readEndpoint(endpoint);
+      if (row === void 0 || row.meta.deletedAt !== void 0) {
+        throw invalidPlanForTarget(
+          `The merge plan references a missing edge endpoint "${endpoint.id}".`,
+          { edgeKind: upsert.kind, edgeId: upsert.id, endpoint }
+        );
+      }
+    }
+    const current = currentEdgesByIdentity.get(
+      mergeKey(upsert.kind, upsert.id)
+    );
+    if (artifact.guards.incremental !== void 0 && current?.meta.deletedAt !== void 0) {
+      throw invalidPlanForTarget(
+        `The incremental merge plan would resurrect soft-deleted committed edge "${upsert.id}".`,
+        { kind: upsert.kind, id: upsert.id, role: "edge" }
+      );
+    }
+    const props = resolvedWireProps(
+      current === void 0 ? {} : edgeProps(current),
+      upsert.setProps,
+      upsert.unsetProps
+    );
+    const schema = edgeSchemaFor(target, upsert.kind);
+    if (schema !== void 0 && !schema.safeParse(props).success) {
+      throw invalidPlanForTarget(
+        `The merge plan's edge write for "${upsert.id}" does not validate against the active schema.`,
+        { kind: upsert.kind, id: upsert.id, role: "edge" }
+      );
+    }
+    if (artifact.guards.incremental !== void 0 && current !== void 0) {
+      const analysis = analyzeRevalidatingWrite(
+        schema,
+        edgeProps(current),
+        wireWriteProps(upsert.setProps, upsert.unsetProps)
+      );
+      assertValidRevalidatingWrite(
+        analysis,
+        `The incremental merge plan found committed edge "${upsert.id}" with props that do not validate against the active schema.`,
+        { kind: upsert.kind, id: upsert.id, role: "edge" }
+      );
+      if (analysis.stripsCurrentProps && analysis.schemaWouldChange) {
+        throw invalidPlanForTarget(
+          `The incremental merge plan would strip existing props while updating committed edge "${upsert.id}".`,
+          { kind: upsert.kind, id: upsert.id, role: "edge" }
+        );
+      }
+    }
+    if (current !== void 0 && (current.fromKind !== upsert.from.kind || current.fromId !== upsert.from.id || current.toKind !== upsert.to.kind || current.toId !== upsert.to.id)) {
+      throw invalidPlanForTarget(
+        `The merge plan would change the immutable endpoints of edge "${upsert.id}".`,
+        { kind: upsert.kind, id: upsert.id, role: "edge" }
+      );
+    }
+  }
+  const missingEdgeIds = artifact.writes.edgeUpserts.map((upsert) => upsert.id).filter((id) => !currentEdgeIds.has(id));
+  if (missingEdgeIds.length > 0) {
+    const plannedEdgeById = new Map(
+      artifact.writes.edgeUpserts.map((upsert) => [upsert.id, upsert])
+    );
+    for (const kind of Object.keys(target.graph.edges)) {
+      const rows = await edgeCollection(edgesApi, kind).getByIds(
+        missingEdgeIds,
+        INCLUDE_TOMBSTONES
+      );
+      for (const [index, row] of rows.entries()) {
+        if (row === void 0) continue;
+        const id = requireDefined(missingEdgeIds[index]);
+        const planned = plannedEdgeById.get(id);
+        if (planned !== void 0 && planned.kind !== row.kind) {
+          throw invalidPlanForTarget(
+            `The merge plan reuses edge id "${id}" across kinds.`,
+            { id, committedKind: row.kind, plannedKind: planned.kind }
+          );
+        }
+      }
+    }
+  }
+}
+async function assertMergePlanFenceInsideTransaction(target, txBackend, artifact) {
+  await lockRecordedGraphWrite(txBackend, target.graphId);
+  const activeSchema = await txBackend.getActiveSchema(target.graphId);
+  const liveSchema = {
+    managed: activeSchema !== void 0,
+    version: activeSchema?.version ?? 1,
+    hash: activeSchema?.schema_hash ?? await computeSchemaComponent(target)
+  };
+  if (liveSchema.managed !== artifact.target.schema.managed || liveSchema.version !== artifact.target.schema.version || liveSchema.hash !== artifact.target.schema.hash) {
+    throw new MergePlanSchemaMismatchError(
+      "The target's active schema no longer matches the merge plan.",
+      { details: { expected: artifact.target.schema, live: liveSchema } }
+    );
+  }
+  const liveOrigin = await readRevisionOrigin(
+    txBackend,
+    target.revisionSchema,
+    target.graphId
+  );
+  if (liveOrigin !== artifact.target.revision.origin) {
+    throw new MergePlanOriginMismatchError(
+      "The merge plan belongs to a different target revision origin.",
+      {
+        details: {
+          expectedOrigin: artifact.target.revision.origin,
+          liveOrigin
+        }
+      }
+    );
+  }
+  const liveRevision = await readRecordedClock(
+    txBackend,
+    target.revisionSchema,
+    target.graphId
+  ) ?? null;
+  if (liveRevision !== artifact.target.revision.revision) {
+    throw new StaleMergePlanError(
+      "The target revision changed after this merge plan was created; the plan was not applied.",
+      {
+        details: {
+          expectedRevision: artifact.target.revision.revision,
+          liveRevision
+        }
+      }
+    );
+  }
+}
+function identityConsistencySeeds(artifact, profile) {
+  const deleted = new Set(
+    artifact.writes.nodeDeletes.map(
+      (entity) => mergeKey(entity.kind, entity.id)
+    )
+  );
+  const byIdentity = /* @__PURE__ */ new Map();
+  const add = (entity) => {
+    const identity = mergeKey(entity.kind, entity.id);
+    if (!deleted.has(identity)) byIdentity.set(identity, entity);
+  };
+  for (const assertion of [
+    ...artifact.writes.identityAssertions,
+    ...artifact.writes.identityRetractions
+  ]) {
+    add(assertion.a);
+    add(assertion.b);
+  }
+  if (profile === "fold") {
+    for (const upsert of artifact.writes.nodeUpserts) add(upsert);
+  }
+  return [...byIdentity].sort(([left], [right]) => compareMergeKeys(left, right)).map(([, entity]) => entity);
+}
+async function applyWireMergeWrites(target, nodesApi, edgesApi, txBackend, artifact) {
+  const committedNodes = await applyNodeRows(
+    target,
+    txBackend,
+    nodesApi,
+    artifact.writes.nodeDeletes,
+    artifact.writes.nodeUpserts.map((upsert) => ({
+      kind: upsert.kind,
+      id: upsert.id,
+      props: wireWriteProps(upsert.setProps, upsert.unsetProps),
+      ...upsert.validFrom === void 0 ? {} : { validFrom: upsert.validFrom },
+      ...upsert.validTo === void 0 ? {} : { validTo: upsert.validTo }
+    }))
+  );
+  const committedEdges = await applyEdgeRows(
+    edgesApi,
+    artifact.writes.edgeDeletes,
+    artifact.writes.edgeUpserts.map((upsert) => ({
+      kind: upsert.kind,
+      item: {
+        id: upsert.id,
+        from: upsert.from,
+        to: upsert.to,
+        props: wireWriteProps(upsert.setProps, upsert.unsetProps),
+        ...upsert.validFrom === void 0 ? {} : { validFrom: upsert.validFrom },
+        ...upsert.validTo === void 0 ? {} : { validTo: upsert.validTo }
+      }
+    }))
+  );
+  const identityAssertions = artifact.writes.identityAssertions;
+  const identityRetractions = artifact.writes.identityRetractions;
+  const appliedIdentity = await applyIdentityRows(
+    target,
+    txBackend,
+    identityAssertions,
+    identityRetractions,
+    () => storeRuntime(target).assertIdentityClassesConsistentAtTarget(
+      txBackend,
+      identityConsistencySeeds(
+        artifact,
+        target.graph.identity?.sameIdAcrossKinds
+      )
+    )
+  );
+  if (!forceRecordedGraphRevision(txBackend, target.graphId) && !forceWriteTransactionRevision(txBackend)) {
+    await advanceRevisionClock(
+      txBackend,
+      target.revisionSchema,
+      target.graphId,
+      true
+    );
+  }
+  return {
+    nodes: committedNodes,
+    edges: committedEdges,
+    identity: {
+      asserted: appliedIdentity.asserted,
+      retracted: appliedIdentity.retracted
+    }
+  };
+}
+function reportFromArtifact(artifact, merged, warnings, provenancePersisted) {
+  const provenanceRecords = artifact.review.provenanceRecords;
+  return {
+    merged,
+    resolutions: artifact.review.resolutions,
+    conflicts: artifact.review.conflicts,
+    deleteModifyConflicts: artifact.review.deleteModifyConflicts,
+    typeReconciliations: artifact.review.typeReconciliations,
+    dropped: artifact.review.dropped,
+    validityEnds: artifact.review.validityEnds,
+    baseAmbiguities: artifact.review.baseAmbiguities,
+    provenance: artifact.provenance.includeInReport ? buildProvenanceIndex(provenanceRecords) : { byBranch: () => ({ nodeIds: [], edgeIds: [] }) },
+    warnings,
+    ...artifact.review.diagnostics === void 0 ? {} : {
+      candidateDiagnostics: artifact.review.diagnostics
+    },
+    ...provenancePersisted === void 0 ? {} : { provenancePersisted }
+  };
+}
+async function applyMergePlan(target, input) {
+  let validation;
+  try {
+    validation = await validateMergePlanArtifact(input);
+  } catch (error) {
+    return err(
+      new InvalidMergePlanError(
+        `Merge plan validation failed: ${describeCause(error)}`,
+        { cause: error }
+      )
+    );
+  }
+  if (!validation.success)
+    return err(mergePlanValidationError(validation.error));
+  const artifact = validation.artifact;
+  if (artifact.target.graphId !== target.graphId) {
+    return err(
+      new MergePlanTargetMismatchError(
+        "The merge plan names a different target graph.",
+        {
+          details: {
+            expectedGraphId: artifact.target.graphId,
+            receivedGraphId: target.graphId
+          }
+        }
+      )
+    );
+  }
+  try {
+    assertPublicPlanCapability(target);
+    const provenanceStore = artifact.provenance.persist ? await tryOpenProvenanceStore(target) : void 0;
+    if (provenanceStore !== void 0 && isErr(provenanceStore)) {
+      return err(provenanceStore.error);
+    }
+    const merged = await withTxConflictRetry(
+      () => target.transaction(async (tx) => {
+        const txBackend = transactionBackend(tx);
+        await assertMergePlanFenceInsideTransaction(
+          target,
+          txBackend,
+          artifact
+        );
+        await preflightWireMergeWrites(
+          target,
+          tx.nodes,
+          tx.edges,
+          artifact
+        );
+        await assertPlannedIdentityIdsFresh(target, txBackend, {
+          identityAssertions: artifact.writes.identityAssertions,
+          identityRetractions: artifact.writes.identityRetractions
+        });
+        return applyWireMergeWrites(
+          target,
+          tx.nodes,
+          tx.edges,
+          txBackend,
+          artifact
+        );
+      }, mergeCommitTransactionOptions(target))
+    );
+    const warnings = [...artifact.review.warnings];
     let provenancePersisted;
     if (provenanceStore !== void 0 && !isErr(provenanceStore)) {
       try {
+        const records = artifact.review.provenanceRecords;
         const count = await persistProvenanceRecords(
           provenanceStore.data,
           target.graphId,
-          plan.provenanceRecords
+          records
         );
         provenancePersisted = {
           graphId: provenanceGraphId(target.graphId),
@@ -5464,37 +8171,27 @@ async function resolveMerge(store, target, branches, options, useBaseSources, in
         };
       } catch (error) {
         warnings.push(
-          "provenance persistence failed (graph committed; provenance not persisted): " + (error instanceof Error ? error.message : String(error))
+          "provenance persistence failed (graph committed; provenance not persisted): " + describeCause(error)
         );
       }
     }
-    const report = {
-      merged,
-      resolutions: plan.resolutions,
-      conflicts: plan.propertyConflicts,
-      deleteModifyConflicts: plan.deleteModifyConflicts,
-      typeReconciliations: plan.typeReconciliations,
-      dropped: plan.dropped,
-      validityEnds: plan.validityEnds,
-      baseAmbiguities: plan.baseAmbiguities,
-      provenance,
-      warnings,
-      ...provenancePersisted === void 0 ? {} : { provenancePersisted }
-    };
-    return ok(report);
+    return ok(
+      reportFromArtifact(artifact, merged, warnings, provenancePersisted)
+    );
   } catch (error) {
-    if (error instanceof MergeError) {
-      return err(error);
-    }
+    const translated = translateMergeCommitError(error);
     return err(
-      new MergeError(
-        `Merge failed while staging or committing: ${describeCause(error)}`,
-        { cause: error }
+      translated instanceof MergeError ? translated : new MergeError(
+        `Merge plan apply failed: ${describeCause(translated)}`,
+        {
+          cause: translated
+        }
       )
     );
   }
 }
-async function merge(store, branches, optionsInput = {}) {
+async function merge(store, branchInputs, optionsInput = {}) {
+  const branches = unwrapMergeBranches(branchInputs);
   const normalized = tryNormalize(optionsInput);
   if (isErr(normalized)) {
     return err(normalized.error);
@@ -5512,7 +8209,8 @@ async function merge(store, branches, optionsInput = {}) {
     options,
     false,
     void 0,
-    precondition.data
+    precondition.data,
+    commitResolvedMerge
   );
 }
 async function validateForkPointVersions(forkPoint, branches) {
@@ -5931,55 +8629,54 @@ async function commitIncrementalPlan(target, plan, guard) {
       { details: { capability: "transactions" } }
     );
   }
-  return withTxConflictRetry(
-    () => target.transaction(async (tx) => {
-      if (target.revisionTrackingEnabled) {
-        await lockRecordedGraphWrite(transactionBackend(tx), target.graphId);
-      }
-      await assertForkPointUnchanged(guard.forkPoint);
-      const nodesApi = tx.nodes;
-      const edgesApi = tx.edges;
-      await assertBaseResolutionStable(tx, guard);
-      await assertPlannedIdentityIdsFresh(target, transactionBackend(tx), plan);
-      await assertIdentityPeersStable(
-        target,
-        transactionBackend(tx),
-        guard.identityPeerProbe,
-        plan
-      );
-      await assertInheritedTargetUnchanged(nodesApi, edgesApi, guard, plan);
-      await validateIncrementalNodeWrites(target, nodesApi, plan);
-      await validateIncrementalEdgeWrites(target, edgesApi, plan);
-      return applyMergePlan(
-        plan,
-        nodesApi,
-        edgesApi,
-        target,
-        transactionBackend(tx)
-      );
-    }, mergeCommitTransactionOptions(target))
+  return runMergeCommit(
+    () => withTxConflictRetry(
+      () => target.transaction(async (tx) => {
+        if (target.revisionTrackingEnabled) {
+          await lockRecordedGraphWrite(transactionBackend(tx), target.graphId);
+        }
+        await assertForkPointUnchanged(guard.forkPoint);
+        const nodesApi = tx.nodes;
+        const edgesApi = tx.edges;
+        await assertBaseResolutionStable(
+          tx,
+          guard
+        );
+        await assertPlannedIdentityIdsFresh(
+          target,
+          transactionBackend(tx),
+          plan
+        );
+        await assertIdentityPeersStable(
+          target,
+          transactionBackend(tx),
+          guard.identityPeerProbe,
+          plan
+        );
+        await assertInheritedTargetUnchanged(nodesApi, edgesApi, guard, plan);
+        await validateIncrementalNodeWrites(target, nodesApi, plan);
+        await validateIncrementalEdgeWrites(target, edgesApi, plan);
+        return applyInternalMergePlan(
+          plan,
+          nodesApi,
+          edgesApi,
+          target,
+          transactionBackend(tx)
+        );
+      }, mergeCommitTransactionOptions(target))
+    )
   );
 }
 async function mergeIncremental(args) {
-  const { forkPoint, target, branches } = args;
+  const { forkPoint, target } = args;
+  const branches = unwrapMergeBranches(args.branches);
   const normalized = tryNormalize(args.options ?? {}, ["target"]);
   if (isErr(normalized)) {
     return err(normalized.error);
   }
   const options = normalized.data;
   if (options.onBasePropertyConflict !== "flag") {
-    return err(
-      new InvalidMergeOptionsError(
-        'mergeIncremental() requires onBasePropertyConflict: "flag" (keep-base); a non-keep-base policy could overwrite a newer committed base value with a stale branch value.',
-        {
-          details: {
-            option: "onBasePropertyConflict",
-            accepted: "flag",
-            received: options.onBasePropertyConflict
-          }
-        }
-      )
-    );
+    return err(incrementalBaseConflictPolicyError(options));
   }
   const forkPrecondition = await validateForkPointVersions(forkPoint, branches);
   if (isErr(forkPrecondition)) {
@@ -5991,12 +8688,7 @@ async function mergeIncremental(args) {
     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: {} }
-      )
-    );
+    return err(incrementalSchemaError());
   }
   const targetBranch = {
     id: COMMITTED_TARGET_BRANCH,
@@ -6015,10 +8707,12 @@ async function mergeIncremental(args) {
       // it is re-established there rather than assumed to have held for the
       // whole of planning (see `assertForkPointUnchanged`).
       forkPoint: { store: forkPoint, version: forkVersion }
-    }
+    },
+    void 0,
+    commitResolvedMerge
   );
 }
 
-export { BaseVersionMismatchError, BranchError, IdentityMergeConflictError, InvalidMergeOptionsError, MERGE_ERROR_CODES, MERGE_OPTION_DEFAULTS, MergeConflictError, MergeError, SimilarityUnavailableError, VALIDITY_END_TARGET_PRECEDENCE, asBaseVersion, asBranchId, branch, cloneWorkingCopyStrategy, computeBaseVersion, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, provenanceGraphId, readProvenance };
+export { BaseVersionMismatchError, BranchError, CandidateSourceError, IdentityMergeConflictError, InvalidMergeOptionsError, InvalidMergePlanError, MERGE_ERROR_CODES, MERGE_OPTION_DEFAULTS, MERGE_PLAN_DIGEST_ALGORITHM, MERGE_PLAN_FORMAT_VERSION, MatchEvidenceError, MergeConflictError, MergeConstraintConflictError, MergeError, MergePlanCapabilityError, MergePlanDigestMismatchError, MergePlanOriginMismatchError, MergePlanSchemaMismatchError, MergePlanTargetMismatchError, MergePlanningStaleError, SimilarityUnavailableError, StaleMergePlanError, UnsupportedMergePlanVersionError, VALIDITY_END_TARGET_PRECEDENCE, applyMergePlan, asBaseVersion, asBranchId, branch, cloneWorkingCopyStrategy, computeBaseVersion, ingestionBranch, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, planMerge, planMergeIncremental, provenanceGraphId, readProvenance };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map