@nicia-ai/typegraph 0.55.0 → 0.56.0

package/dist/graph-merge/index.cjs

@@ -1,22 +1,22 @@
 'use strict';
 
-var chunkOJ47LMOB_cjs = require('../chunk-OJ47LMOB.cjs');
-require('../chunk-WTW7RWAG.cjs');
-var chunk7I2PYI4U_cjs = require('../chunk-7I2PYI4U.cjs');
-require('../chunk-KZG7HQSN.cjs');
-var chunkORPT5EQW_cjs = require('../chunk-ORPT5EQW.cjs');
-require('../chunk-PGZV3E3I.cjs');
-require('../chunk-MTE255N3.cjs');
-require('../chunk-D5TCKAQT.cjs');
-var chunkHZCOCNIX_cjs = require('../chunk-HZCOCNIX.cjs');
+var chunkWIUHN6SZ_cjs = require('../chunk-WIUHN6SZ.cjs');
+require('../chunk-BYUIOM4L.cjs');
+var chunkKR3N6Y7O_cjs = require('../chunk-KR3N6Y7O.cjs');
+require('../chunk-UVMSWO6X.cjs');
+var chunkUZ6CJUC5_cjs = require('../chunk-UZ6CJUC5.cjs');
+require('../chunk-VXEHEPC4.cjs');
+require('../chunk-36XLQHZA.cjs');
+require('../chunk-DGIA64DM.cjs');
+var chunkL2REUAJB_cjs = require('../chunk-L2REUAJB.cjs');
 require('../chunk-6YKISECL.cjs');
 var chunkOGZA7IS4_cjs = require('../chunk-OGZA7IS4.cjs');
-var chunkT7LSSV7J_cjs = require('../chunk-T7LSSV7J.cjs');
-var chunkTKFQLKH2_cjs = require('../chunk-TKFQLKH2.cjs');
+var chunkXXEFDJHY_cjs = require('../chunk-XXEFDJHY.cjs');
+var chunkCYKHSH5O_cjs = require('../chunk-CYKHSH5O.cjs');
 require('../chunk-6OWTUEUL.cjs');
 var chunk5X46XWNH_cjs = require('../chunk-5X46XWNH.cjs');
-require('../chunk-FYMYLZGX.cjs');
-var chunkECYEWFEH_cjs = require('../chunk-ECYEWFEH.cjs');
+require('../chunk-ZXXGMQC3.cjs');
+var chunkJ34FSPSC_cjs = require('../chunk-J34FSPSC.cjs');
 var chunkV32ES2Q2_cjs = require('../chunk-V32ES2Q2.cjs');
 var chunkOJHFXL7Y_cjs = require('../chunk-OJHFXL7Y.cjs');
 require('../chunk-F2HGOZJR.cjs');
@@ -129,7 +129,8 @@ var MERGE_ERROR_CODES = {
   planningStale: "GRAPH_MERGE_PLANNING_STALE",
   candidateSource: "GRAPH_MERGE_CANDIDATE_SOURCE",
   evidence: "GRAPH_MERGE_EVIDENCE",
-  candidateWriteSet: "GRAPH_MERGE_CANDIDATE_WRITE_SET"
+  candidateWriteSet: "GRAPH_MERGE_CANDIDATE_WRITE_SET",
+  review: "GRAPH_MERGE_REVIEW"
 };
 function toTypeGraphErrorOptions(category, options) {
   return {
@@ -159,6 +160,14 @@ var InvalidMergeOptionsError = class extends MergeError {
     this.name = "InvalidMergeOptionsError";
   }
 };
+var MergeReviewError = class extends MergeError {
+  static errorCategory = "user";
+  code = MERGE_ERROR_CODES.review;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "MergeReviewError";
+  }
+};
 var BranchError = class extends chunkASKXTVK5_cjs.TypeGraphError {
   constructor(message, options = {}) {
     super(
@@ -735,7 +744,7 @@ function identityEndpointKey(assertion) {
   return chunkOJHFXL7Y_cjs.encodeTupleKey(endpointTuple(assertion));
 }
 function identitySemanticKey(assertion) {
-  return chunkT7LSSV7J_cjs.identityAssertionSemanticKey(
+  return chunkXXEFDJHY_cjs.identityAssertionSemanticKey(
     assertion.relation,
     assertion.a,
     assertion.b
@@ -799,7 +808,7 @@ function assertNoOpposingIdentityRelations(assertions) {
     );
     for (const sameAssertion of same) {
       for (const differentAssertion of different) {
-        if (!chunkT7LSSV7J_cjs.identityValidityWindowsOverlap(sameAssertion, differentAssertion)) {
+        if (!chunkXXEFDJHY_cjs.identityValidityWindowsOverlap(sameAssertion, differentAssertion)) {
           continue;
         }
         throw new IdentityMergeConflictError(
@@ -959,7 +968,7 @@ function remapIdentityAssertionEndpoints(assertions, canonicalOf, retypeMap, sto
       );
       continue;
     }
-    const [a, b] = chunkT7LSSV7J_cjs.normalizeIdentityPair(remappedA, remappedB);
+    const [a, b] = chunkXXEFDJHY_cjs.normalizeIdentityPair(remappedA, remappedB);
     const endpointWindowA = endpointWindows.get(mergeKeyOf(a));
     const endpointWindowB = endpointWindows.get(mergeKeyOf(b));
     const validFrom = [
@@ -1114,7 +1123,7 @@ async function buildIdentityPeerProbe(target, probedIds, targetPeers, plan, prof
       (group) => group.map((member) => mergeKey(member.kind, member.id))
     )
   ]);
-  const ledger = (await relevantLedgerAssertions(target, memberKeys, chunkORPT5EQW_cjs.storeBackend(target))).filter(
+  const ledger = (await relevantLedgerAssertions(target, memberKeys, chunkUZ6CJUC5_cjs.storeBackend(target))).filter(
     (assertion) => !plannedDeletions.has(mergeKey(assertion.a.kind, assertion.a.id)) && !plannedDeletions.has(mergeKey(assertion.b.kind, assertion.b.id))
   );
   return {
@@ -1135,7 +1144,7 @@ async function buildIdentityPeerProbe(target, probedIds, targetPeers, plan, prof
   };
 }
 async function snapshotIdentityClasses(target, seeds, liveKeys, plannedDeletions, txBackend) {
-  const classes = await chunkORPT5EQW_cjs.storeRuntime(target).structuralIdentityClasses(
+  const classes = await chunkUZ6CJUC5_cjs.storeRuntime(target).structuralIdentityClasses(
     seeds,
     txBackend
   );
@@ -1143,7 +1152,7 @@ async function snapshotIdentityClasses(target, seeds, liveKeys, plannedDeletions
   const groups = [];
   for (const seed of seeds) {
     const key = mergeKey(seed.kind, seed.id);
-    const members = (classes.get(chunkT7LSSV7J_cjs.identityReferenceKey(seed)) ?? [seed]).filter(
+    const members = (classes.get(chunkXXEFDJHY_cjs.identityReferenceKey(seed)) ?? [seed]).filter(
       (member) => !plannedDeletions.has(mergeKey(member.kind, member.id))
     );
     groups.push(members);
@@ -1152,7 +1161,7 @@ async function snapshotIdentityClasses(target, seeds, liveKeys, plannedDeletions
   return { fingerprints, groups };
 }
 async function relevantLedgerAssertions(target, memberKeys, backend) {
-  const current = await chunkORPT5EQW_cjs.storeRuntime(target).identityAssertionsAtTarget(
+  const current = await chunkUZ6CJUC5_cjs.storeRuntime(target).identityAssertionsAtTarget(
     backend,
     "state"
   );
@@ -1225,7 +1234,7 @@ async function assertPlannedIdentityIdsFresh(target, txBackend, plan) {
     ...plan.identityRetractions.map((retraction) => retraction.id)
   ];
   if (plannedIds.length === 0) return;
-  const storedById = await chunkORPT5EQW_cjs.storeRuntime(target).identityAssertionRowsByIds(
+  const storedById = await chunkUZ6CJUC5_cjs.storeRuntime(target).identityAssertionRowsByIds(
     plannedIds,
     txBackend
   );
@@ -1278,7 +1287,7 @@ function affectedIdentityClassSeeds(plan, profile) {
   return [...seedsByKey.values()];
 }
 async function assertMergedIdentityClassesConsistent(target, txBackend, plan) {
-  await chunkORPT5EQW_cjs.storeRuntime(target).assertIdentityClassesConsistentAtTarget(
+  await chunkUZ6CJUC5_cjs.storeRuntime(target).assertIdentityClassesConsistentAtTarget(
     txBackend,
     affectedIdentityClassSeeds(plan, target.graph.identity?.sameIdAcrossKinds)
   );
@@ -1332,7 +1341,7 @@ function translateIdentityCommitError(error) {
 }
 async function assertIdentityPeersStable(target, txBackend, probe, plan) {
   if (probe === void 0) return;
-  const live = (await chunkORPT5EQW_cjs.storeRuntime(target).liveNodesSharingIds(probe.ids, txBackend)).filter((peer) => !probe.plannedDeletions.has(mergeKey(peer.kind, peer.id)));
+  const live = (await chunkUZ6CJUC5_cjs.storeRuntime(target).liveNodesSharingIds(probe.ids, txBackend)).filter((peer) => !probe.plannedDeletions.has(mergeKey(peer.kind, peer.id)));
   const seedKindsById = /* @__PURE__ */ new Map();
   for (const seed of probe.seeds) {
     const kinds = seedKindsById.get(seed.id) ?? /* @__PURE__ */ new Set();
@@ -1632,8 +1641,8 @@ async function diffAgainstBase(baseStore, forkStore, captureForkState = true) {
   const nodeKinds = chunkV32ES2Q2_cjs.getNodeKinds(graph);
   const edgeKinds = chunkV32ES2Q2_cjs.getEdgeKinds(graph);
   const [baseIdentity, forkIdentity] = await Promise.all([
-    chunkORPT5EQW_cjs.storeRuntime(baseStore).readCurrentIdentityAssertions("archival"),
-    chunkORPT5EQW_cjs.storeRuntime(forkStore).readCurrentIdentityAssertions("archival")
+    chunkUZ6CJUC5_cjs.storeRuntime(baseStore).readCurrentIdentityAssertions("archival"),
+    chunkUZ6CJUC5_cjs.storeRuntime(forkStore).readCurrentIdentityAssertions("archival")
   ]);
   const baseIdentityById = new Map(
     baseIdentity.map((assertion) => [assertion.id, assertion])
@@ -1648,12 +1657,12 @@ async function diffAgainstBase(baseStore, forkStore, captureForkState = true) {
   const forkNodeVersions = /* @__PURE__ */ new Map();
   for (const kind of nodeKinds) {
     const baseRows = await enumerateAllNodes(
-      chunkORPT5EQW_cjs.storeBackend(baseStore),
+      chunkUZ6CJUC5_cjs.storeBackend(baseStore),
       baseStore.graphId,
       kind
     );
     const forkRows = await enumerateAllNodes(
-      chunkORPT5EQW_cjs.storeBackend(forkStore),
+      chunkUZ6CJUC5_cjs.storeBackend(forkStore),
       forkStore.graphId,
       kind
     );
@@ -1683,12 +1692,12 @@ async function diffAgainstBase(baseStore, forkStore, captureForkState = true) {
   const forkEdgeSignatures = /* @__PURE__ */ new Map();
   for (const kind of edgeKinds) {
     const baseRows = await enumerateAllEdges(
-      chunkORPT5EQW_cjs.storeBackend(baseStore),
+      chunkUZ6CJUC5_cjs.storeBackend(baseStore),
       baseStore.graphId,
       kind
     );
     const forkRows = await enumerateAllEdges(
-      chunkORPT5EQW_cjs.storeBackend(forkStore),
+      chunkUZ6CJUC5_cjs.storeBackend(forkStore),
       forkStore.graphId,
       kind
     );
@@ -1785,10 +1794,10 @@ async function readActiveSchemaVersion(backend, graphId) {
 }
 async function computeSchemaComponent(store) {
   const version = await readActiveSchemaVersion(
-    chunkORPT5EQW_cjs.storeBackend(store),
+    chunkUZ6CJUC5_cjs.storeBackend(store),
     store.graphId
   );
-  return chunkHZCOCNIX_cjs.computeSchemaHash(chunkHZCOCNIX_cjs.serializeSchema(store.graph, version));
+  return chunkL2REUAJB_cjs.computeSchemaHash(chunkL2REUAJB_cjs.serializeSchema(store.graph, version));
 }
 function byDigestEntry(left, right) {
   const byKind = chunkNYWU6CBZ_cjs.compareStrings(left.kind, right.kind);
@@ -1847,7 +1856,7 @@ async function computeBaseVersion(store) {
       computeSchemaComponent(store),
       store.revisionOriginNow(),
       store.revisionNow(),
-      readActiveSchemaVersion(chunkORPT5EQW_cjs.storeBackend(store), store.graphId)
+      readActiveSchemaVersion(chunkUZ6CJUC5_cjs.storeBackend(store), store.graphId)
     ]);
     return asBaseVersion(
       `${schemaComponent2}${SCHEMA_VERSION_TAG}${activeVersion}${TOKEN_SEPARATOR}${revisionComponent(origin, revision)}`
@@ -1862,9 +1871,9 @@ async function computeBaseVersion(store) {
   );
 }
 async function computeStoreContentComponent(store) {
-  const identityAssertions = await chunkORPT5EQW_cjs.storeRuntime(store).readCurrentIdentityAssertions("state");
+  const identityAssertions = await chunkUZ6CJUC5_cjs.storeRuntime(store).readCurrentIdentityAssertions("state");
   return computeContentComponent(
-    chunkORPT5EQW_cjs.storeBackend(store),
+    chunkUZ6CJUC5_cjs.storeBackend(store),
     store.graphId,
     store.graph,
     identityAssertions
@@ -1918,7 +1927,7 @@ function cloneWorkingCopyWithGraphStrategy(makeBackend, graphForClone) {
     create: async (baseStore) => {
       const backend = await makeBackend();
       try {
-        const [freshStore] = await chunkOJ47LMOB_cjs.createStoreWithSchema(
+        const [freshStore] = await chunkWIUHN6SZ_cjs.createStoreWithSchema(
           graphForClone(baseStore),
           backend,
           {
@@ -1939,16 +1948,16 @@ function cloneWorkingCopyWithGraphStrategy(makeBackend, graphForClone) {
           validateReferences: true,
           batchSize: CLONE_IMPORT_BATCH_SIZE
         };
-        const result = chunkECYEWFEH_cjs.snapshotExportContention(
-          chunkORPT5EQW_cjs.storeBackend(baseStore),
-          chunkORPT5EQW_cjs.storeBackend(freshStore)
-        ) === void 0 ? await chunk7I2PYI4U_cjs.importGraphStream(
+        const result = chunkJ34FSPSC_cjs.snapshotExportContention(
+          chunkUZ6CJUC5_cjs.storeBackend(baseStore),
+          chunkUZ6CJUC5_cjs.storeBackend(freshStore)
+        ) === void 0 ? await chunkKR3N6Y7O_cjs.importGraphStream(
           freshStore,
-          chunk7I2PYI4U_cjs.exportGraphStream(baseStore, exportOptions),
+          chunkKR3N6Y7O_cjs.exportGraphStream(baseStore, exportOptions),
           importOptions
-        ) : await chunk7I2PYI4U_cjs.importGraph(
+        ) : await chunkKR3N6Y7O_cjs.importGraph(
           freshStore,
-          await chunk7I2PYI4U_cjs.exportGraph(baseStore, exportOptions),
+          await chunkKR3N6Y7O_cjs.exportGraph(baseStore, exportOptions),
           importOptions
         );
         if (!result.success) {
@@ -1997,7 +2006,7 @@ function graphWithoutNodeUniqueness(graph) {
 async function branch(baseStore, makeBackend, options, strategy) {
   try {
     const base = await computeBaseVersion(baseStore);
-    const id = options?.id ?? asBranchId(chunkTKFQLKH2_cjs.generateId());
+    const id = options?.id ?? asBranchId(chunkCYKHSH5O_cjs.generateId());
     const workingCopyStrategy = strategy ?? cloneWorkingCopyStrategy(makeBackend);
     const store = await workingCopyStrategy.create(baseStore);
     const schemaAnchor = await captureBranchSchemaAnchor(store);
@@ -2017,11 +2026,11 @@ async function branch(baseStore, makeBackend, options, strategy) {
 }
 async function captureBranchSchemaAnchor(store) {
   try {
-    const schemaRow = await chunkORPT5EQW_cjs.storeBackend(store).getActiveSchema(store.graphId);
+    const schemaRow = await chunkUZ6CJUC5_cjs.storeBackend(store).getActiveSchema(store.graphId);
     return schemaRow === void 0 ? void 0 : { version: schemaRow.version, hash: schemaRow.schema_hash };
   } catch (error) {
     try {
-      await chunkORPT5EQW_cjs.storeBackend(store).close();
+      await chunkUZ6CJUC5_cjs.storeBackend(store).close();
     } catch {
     }
     throw error;
@@ -2074,10 +2083,10 @@ async function ingestionBranch(baseStore, makeBackend, options) {
       nodes: store.nodes,
       edges: store.edges,
       ...identityAccess,
-      close: async () => chunkORPT5EQW_cjs.storeBackend(store).close()
+      close: async () => chunkUZ6CJUC5_cjs.storeBackend(store).close()
     });
     PRIVATE_BRANCHES.set(handle, privateBranch);
-    chunk7I2PYI4U_cjs.registerIngestionImportTarget(handle, store);
+    chunkKR3N6Y7O_cjs.registerIngestionImportTarget(handle, store);
     return chunkNXJRIRWE_cjs.ok(handle);
   } catch (error) {
     return chunkNXJRIRWE_cjs.err(
@@ -2098,6 +2107,45 @@ function unwrapMergeBranches(inputs) {
   return inputs.map((input) => unwrapMergeBranch(input));
 }
 
+// src/graph-merge/apply-callbacks.ts
+var NODE_READ_NAMES = [
+  ...chunkWIUHN6SZ_cjs.NODE_TEMPORAL_READ_NAMES,
+  ...chunkWIUHN6SZ_cjs.CURRENT_ONLY_READ_NAMES
+];
+function pickReadMethods(source, names) {
+  return Object.fromEntries(names.map((name) => [name, source[name]]));
+}
+function mergePlanReadContext(tx, graph) {
+  return {
+    nodes: Object.fromEntries(
+      Object.keys(graph.nodes).map((kind) => [
+        kind,
+        pickReadMethods(chunkBXHAPCQG_cjs.requireDefined(tx.nodes[kind]), NODE_READ_NAMES)
+      ])
+    ),
+    edges: Object.fromEntries(
+      Object.keys(graph.edges).map((kind) => [
+        kind,
+        pickReadMethods(
+          chunkBXHAPCQG_cjs.requireDefined(tx.edges[kind]),
+          chunkWIUHN6SZ_cjs.EDGE_TEMPORAL_READ_NAMES
+        )
+      ])
+    ),
+    ..."identity" in tx ? {
+      identity: pickReadMethods(tx.identity, chunkWIUHN6SZ_cjs.IDENTITY_READ_NAMES)
+    } : {}
+  };
+}
+function assertMergeCallbackResult(result, callback) {
+  if (result !== void 0) {
+    throw new InvalidMergeOptionsError(
+      `${callback} must resolve without a return value; throw or reject to abort merge application.`,
+      { cause: result, details: { callback } }
+    );
+  }
+}
+
 // src/graph-merge/blocking.ts
 var UNBLOCKED_BUCKET_KEY = "unblocked";
 var KEY_PART_SEPARATOR = "\0";
@@ -4903,7 +4951,7 @@ function buildProvenanceGraph(targetGraphId) {
   });
 }
 async function openProvenanceStore(...args) {
-  const [backend, targetGraphId] = args.length === 1 ? [chunkORPT5EQW_cjs.storeBackend(args[0]), args[0].graphId] : args;
+  const [backend, targetGraphId] = args.length === 1 ? [chunkUZ6CJUC5_cjs.storeBackend(args[0]), args[0].graphId] : args;
   const graph = buildOwnedProvenanceGraph(targetGraphId);
   const preflight = await inspectSidecarGraphId(backend, graph, targetGraphId);
   if (preflight.state === "refuse") {
@@ -4915,7 +4963,7 @@ async function openProvenanceStore(...args) {
       throw provenanceGraphIdCollision(graph.id, targetGraphId, claim.reason);
     }
   }
-  const [store] = await chunkOJ47LMOB_cjs.createStoreWithSchema(graph, backend);
+  const [store] = await chunkWIUHN6SZ_cjs.createStoreWithSchema(graph, backend);
   return store;
 }
 async function claimSidecarOwnership(backend, graph, targetGraphId) {
@@ -4941,15 +4989,15 @@ async function claimSidecarOwnership(backend, graph, targetGraphId) {
   });
 }
 async function drainUnfencedRowWriters(tx) {
-  const plan = chunkECYEWFEH_cjs.resolveWriteFencePlan(tx);
-  const fence = chunkECYEWFEH_cjs.requireWriteFence(
+  const plan = chunkJ34FSPSC_cjs.resolveWriteFencePlan(tx);
+  const fence = chunkJ34FSPSC_cjs.requireWriteFence(
     plan,
     "graph-merge provenance fence",
     "table-lock"
   );
   switch (fence.kind) {
     case "lock": {
-      const schema = chunkECYEWFEH_cjs.createSqlSchema(tx.tableNames);
+      const schema = chunkJ34FSPSC_cjs.createSqlSchema(tx.tableNames);
       await tx.executeStatement(
         chunkAYQBEVQY_cjs.asCompiledStatementSql(
           chunkAYQBEVQY_cjs.sql`LOCK TABLE ${schema.nodesTable}, ${schema.edgesTable} IN SHARE ROW EXCLUSIVE MODE`
@@ -4977,14 +5025,14 @@ async function inspectSidecarGraphId(port, graph, targetGraphId) {
   if (activeSchema === void 0) {
     return { state: "refuse", reason: "application-graph" };
   }
-  const ownedHash = await chunkHZCOCNIX_cjs.computeSchemaHash(
-    chunkHZCOCNIX_cjs.serializeSchema(graph, activeSchema.version)
+  const ownedHash = await chunkL2REUAJB_cjs.computeSchemaHash(
+    chunkL2REUAJB_cjs.serializeSchema(graph, activeSchema.version)
   );
   if (activeSchema.schema_hash === ownedHash) {
     return { state: "refuse", reason: "unowned-exact-schema-graph" };
   }
-  const legacyHash = await chunkHZCOCNIX_cjs.computeSchemaHash(
-    chunkHZCOCNIX_cjs.serializeSchema(buildProvenanceGraph(targetGraphId), activeSchema.version)
+  const legacyHash = await chunkL2REUAJB_cjs.computeSchemaHash(
+    chunkL2REUAJB_cjs.serializeSchema(buildProvenanceGraph(targetGraphId), activeSchema.version)
   );
   if (activeSchema.schema_hash !== legacyHash) {
     return { state: "refuse", reason: "application-graph" };
@@ -5088,7 +5136,7 @@ async function* readRowsOfKind(port, graphId, kind) {
   }
 }
 async function hasRowsUnderGraphId(port, graphId, scope) {
-  const schema = chunkECYEWFEH_cjs.createSqlSchema(port.tableNames);
+  const schema = chunkJ34FSPSC_cjs.createSqlSchema(port.tableNames);
   const kindFilter = scope === "any" ? chunkAYQBEVQY_cjs.sql.empty() : chunkAYQBEVQY_cjs.sql` AND kind <> ${PROVENANCE_KIND}`;
   if (await hasRowsInTable(port, schema.tables.nodes, graphId, kindFilter)) {
     return true;
@@ -5685,7 +5733,7 @@ async function stageBranches(baseStore, branches, captureTargetStateFor) {
   const windowedEdges = [];
   const newIdentityAssertions = [];
   const retractedIdentityAssertions = [];
-  const baseIdentityAssertions = await chunkORPT5EQW_cjs.storeRuntime(baseStore).readCurrentIdentityAssertions("state");
+  const baseIdentityAssertions = await chunkUZ6CJUC5_cjs.storeRuntime(baseStore).readCurrentIdentityAssertions("state");
   let targetNodeVersions = /* @__PURE__ */ new Map();
   let targetEdgeSignatures = /* @__PURE__ */ new Map();
   for (const branch2 of branches) {
@@ -5885,7 +5933,7 @@ function reconcileTypes(clusters, closure, mode) {
 // src/graph-merge/write-fence.ts
 async function lockMergeTargetWrite(txBackend, input) {
   try {
-    await chunkTKFQLKH2_cjs.lockSchemaVersionForStoreWrite(
+    await chunkCYKHSH5O_cjs.lockSchemaVersionForStoreWrite(
       { graphId: input.graphId, schemaVersion: input.schemaVersion },
       txBackend
     );
@@ -5896,7 +5944,20 @@ async function lockMergeTargetWrite(txBackend, input) {
     throw input.staleSchemaError(error);
   }
   if (input.graphLock === "required") {
-    await chunkTKFQLKH2_cjs.lockRecordedGraphWrite(txBackend, input.graphId);
+    const lock = await chunkCYKHSH5O_cjs.lockRecordedGraphWrite(txBackend, input.graphId);
+    if (input.requireFreshSnapshot && lock.coordination !== void 0) {
+      const isolation = chunkJ34FSPSC_cjs.graphCommandCoordinationIsolation(
+        txBackend.commands,
+        input.graphId,
+        lock.coordination
+      );
+      if (isolation !== "read_committed") {
+        throw new MergePlanCapabilityError(
+          "Merge callbacks require read-committed isolation so their reads observe the target after acquiring its graph lock.",
+          { details: { capability: "mergeCallbackIsolation", isolation } }
+        );
+      }
+    }
   }
 }
 
@@ -6846,7 +6907,7 @@ async function applyNodeRows(target, txBackend, nodesApi, deletions, upserts) {
       afterImages.set(mergeKey(kind, item.id), props);
     }
   }
-  return chunkORPT5EQW_cjs.storeRuntime(target).applyResolvedNodeUniqueness(
+  return chunkUZ6CJUC5_cjs.storeRuntime(target).applyResolvedNodeUniqueness(
     txBackend,
     {
       upserts: upserts.map((upsert) => ({
@@ -6894,7 +6955,7 @@ async function applyEdgeRows(edgesApi, deletions, upserts) {
 }
 async function applyIdentityRows(target, txBackend, assertions, retractions, assertConsistent) {
   try {
-    const applied = await chunkORPT5EQW_cjs.storeRuntime(target).applyIdentityMergeAtTarget(
+    const applied = await chunkUZ6CJUC5_cjs.storeRuntime(target).applyIdentityMergeAtTarget(
       txBackend,
       retractions,
       assertions
@@ -6992,7 +7053,7 @@ async function applyInternalMergePlan(plan, nodesApi, edgesApi, target, txBacken
   };
 }
 async function commitPlan(target, plan, expectedBaseVersion) {
-  if (!chunkORPT5EQW_cjs.storeBackend(target).capabilities.execution.interactiveTransactions) {
+  if (!chunkUZ6CJUC5_cjs.storeBackend(target).capabilities.execution.interactiveTransactions) {
     throw new MergeError(
       "merge() requires a transaction-capable target backend. The merged plan (canonical upserts, soft-deletes, edge upserts) must commit atomically; a non-transactional fallback would leave a partially-merged graph on a mid-commit failure. (mergeIncremental() enforces the same requirement.)",
       { details: { capability: "execution.interactiveTransactions" } }
@@ -7003,14 +7064,14 @@ async function commitPlan(target, plan, expectedBaseVersion) {
       () => target.transaction(async (tx) => {
         if (expectedBaseVersion !== void 0) {
           await assertTargetUnchanged(
-            chunkORPT5EQW_cjs.transactionBackend(tx),
+            chunkUZ6CJUC5_cjs.transactionBackend(tx),
             target,
             expectedBaseVersion
           );
         }
         await assertPlannedIdentityIdsFresh(
           target,
-          chunkORPT5EQW_cjs.transactionBackend(tx),
+          chunkUZ6CJUC5_cjs.transactionBackend(tx),
           plan
         );
         return applyInternalMergePlan(
@@ -7018,7 +7079,7 @@ async function commitPlan(target, plan, expectedBaseVersion) {
           tx.nodes,
           tx.edges,
           target,
-          chunkORPT5EQW_cjs.transactionBackend(tx)
+          chunkUZ6CJUC5_cjs.transactionBackend(tx)
         );
       }, mergeCommitTransactionOptions(target))
     )
@@ -7049,7 +7110,7 @@ async function assertTargetUnchanged(txBackend, target, expectedBaseVersion) {
       )
     });
     const expectedOrigin = revisionOriginOf(expectedBaseVersion);
-    const liveOrigin = await chunkTKFQLKH2_cjs.readRevisionOrigin(
+    const liveOrigin = await chunkCYKHSH5O_cjs.readRevisionOrigin(
       txBackend,
       target.revisionSchema,
       target.graphId
@@ -7063,7 +7124,7 @@ async function assertTargetUnchanged(txBackend, target, expectedBaseVersion) {
         }
       );
     }
-    const liveRevision = await chunkTKFQLKH2_cjs.readRecordedClock(
+    const liveRevision = await chunkCYKHSH5O_cjs.readRecordedClock(
       txBackend,
       target.revisionSchema,
       target.graphId
@@ -7084,7 +7145,7 @@ async function assertTargetUnchanged(txBackend, target, expectedBaseVersion) {
     txBackend,
     target.graphId,
     target.graph,
-    await chunkORPT5EQW_cjs.storeRuntime(target).identityAssertionsAtTarget(txBackend, "state")
+    await chunkUZ6CJUC5_cjs.storeRuntime(target).identityAssertionsAtTarget(txBackend, "state")
   );
   const expectedContent = contentComponentOf(expectedBaseVersion);
   if (liveContent !== expectedContent) {
@@ -7176,7 +7237,7 @@ async function tryOpenProvenanceStore(target) {
   }
 }
 function assertPublicPlanCapability(target) {
-  if (!chunkORPT5EQW_cjs.storeBackend(target).capabilities.execution.interactiveTransactions) {
+  if (!chunkUZ6CJUC5_cjs.storeBackend(target).capabilities.execution.interactiveTransactions) {
     throw new MergePlanCapabilityError(
       "Public merge plans require a transaction-capable target backend.",
       { details: { capability: "execution.interactiveTransactions" } }
@@ -7195,7 +7256,7 @@ function assertPublicPlanCapability(target) {
 async function captureMergePlanTargetFence(target) {
   assertPublicPlanCapability(target);
   const [activeSchema, schemaHash, origin, revision] = await Promise.all([
-    chunkORPT5EQW_cjs.storeBackend(target).getActiveSchema(target.graphId),
+    chunkUZ6CJUC5_cjs.storeBackend(target).getActiveSchema(target.graphId),
     computeSchemaComponent(target),
     target.revisionOriginNow(),
     target.revisionNow()
@@ -7361,7 +7422,7 @@ async function resolveMerge(store, target, branches, options, useBaseSources, in
     }
   }
   for (const branch2 of branches) {
-    const branchSchemaRow = await chunkORPT5EQW_cjs.storeBackend(branch2.store).getActiveSchema(
+    const branchSchemaRow = await chunkUZ6CJUC5_cjs.storeBackend(branch2.store).getActiveSchema(
       branch2.store.graphId
     );
     let drifted;
@@ -7369,7 +7430,7 @@ async function resolveMerge(store, target, branches, options, useBaseSources, in
       const anchor = branch2.schemaAnchor;
       drifted = anchor === void 0 ? branchSchemaRow !== void 0 : branchSchemaRow?.version !== anchor.version || branchSchemaRow.schema_hash !== anchor.hash;
     } else {
-      const sourceSchemaRow = await chunkORPT5EQW_cjs.storeBackend(store).getActiveSchema(
+      const sourceSchemaRow = await chunkUZ6CJUC5_cjs.storeBackend(store).getActiveSchema(
         store.graphId
       );
       drifted = branchSchemaRow?.schema_hash !== sourceSchemaRow?.schema_hash;
@@ -7414,7 +7475,7 @@ async function resolveMerge(store, target, branches, options, useBaseSources, in
       options.embedder
     );
     const ctx = {
-      backend: chunkORPT5EQW_cjs.storeBackend(store),
+      backend: chunkUZ6CJUC5_cjs.storeBackend(store),
       ...embeddings === void 0 ? {} : { embeddings }
     };
     const candidates = await generateAllCandidates(
@@ -7442,7 +7503,7 @@ async function resolveMerge(store, target, branches, options, useBaseSources, in
         ])
       ])
     ];
-    const targetPeers = identityProbeIds === void 0 ? [] : await chunkORPT5EQW_cjs.storeRuntime(target).liveNodesSharingIds(identityProbeIds);
+    const targetPeers = identityProbeIds === void 0 ? [] : await chunkUZ6CJUC5_cjs.storeRuntime(target).liveNodesSharingIds(identityProbeIds);
     const stagedIdentityIds = [
       .../* @__PURE__ */ new Set([
         ...staging.newIdentityAssertions.map((staged) => staged.assertion.id),
@@ -7451,7 +7512,7 @@ async function resolveMerge(store, target, branches, options, useBaseSources, in
         )
       ])
     ];
-    const storedIdentityRowsById = stagedIdentityIds.length === 0 || target.graph.identity === void 0 ? NO_STORED_ASSERTIONS : await chunkORPT5EQW_cjs.storeRuntime(target).identityAssertionRowsByIds(
+    const storedIdentityRowsById = stagedIdentityIds.length === 0 || target.graph.identity === void 0 ? NO_STORED_ASSERTIONS : await chunkUZ6CJUC5_cjs.storeRuntime(target).identityAssertionRowsByIds(
       stagedIdentityIds
     );
     const identityContext = {
@@ -7476,14 +7537,14 @@ async function resolveMerge(store, target, branches, options, useBaseSources, in
     if (plan.identityAssertions.length > 0) {
       assertOneIdOneTruth(
         plan.identityAssertions,
-        await chunkORPT5EQW_cjs.storeRuntime(target).identityAssertionRowsByIds(
+        await chunkUZ6CJUC5_cjs.storeRuntime(target).identityAssertionRowsByIds(
           plan.identityAssertions.map((assertion) => assertion.id)
         )
       );
     }
     let identityGuard;
     if (identityProbeIds !== void 0 && incremental !== void 0) {
-      const freshPeers = await chunkORPT5EQW_cjs.storeRuntime(target).liveNodesSharingIds(identityProbeIds);
+      const freshPeers = await chunkUZ6CJUC5_cjs.storeRuntime(target).liveNodesSharingIds(identityProbeIds);
       const built = await buildIdentityPeerProbe(
         target,
         identityProbeIds,
@@ -7681,7 +7742,7 @@ async function planMergeIncremental(args) {
     computeSchemaComponent(target)
   ]);
   if (forkSchema !== targetSchema) return chunkNXJRIRWE_cjs.err(incrementalSchemaError());
-  const forkActiveSchema = await chunkORPT5EQW_cjs.storeBackend(forkPoint).getActiveSchema(
+  const forkActiveSchema = await chunkUZ6CJUC5_cjs.storeBackend(forkPoint).getActiveSchema(
     forkPoint.graphId
   );
   const targetBranch = {
@@ -8024,11 +8085,12 @@ async function preflightWireMergeWrites(target, nodesApi, edgesApi, artifact) {
     }
   }
 }
-async function assertMergePlanFenceInsideTransaction(target, txBackend, artifact) {
+async function assertMergePlanFenceInsideTransaction(target, txBackend, artifact, requireFreshSnapshot) {
   await lockMergeTargetWrite(txBackend, {
     graphId: target.graphId,
     schemaVersion: artifact.target.schema.managed ? artifact.target.schema.version : void 0,
     graphLock: "required",
+    requireFreshSnapshot,
     staleSchemaError: (cause) => new MergePlanSchemaMismatchError(
       "The target's active schema no longer matches the merge plan.",
       { cause, details: { expected: artifact.target.schema } }
@@ -8046,7 +8108,7 @@ async function assertMergePlanFenceInsideTransaction(target, txBackend, artifact
       { details: { expected: artifact.target.schema, live: liveSchema } }
     );
   }
-  const liveOrigin = await chunkTKFQLKH2_cjs.readRevisionOrigin(
+  const liveOrigin = await chunkCYKHSH5O_cjs.readRevisionOrigin(
     txBackend,
     target.revisionSchema,
     target.graphId
@@ -8062,7 +8124,7 @@ async function assertMergePlanFenceInsideTransaction(target, txBackend, artifact
       }
     );
   }
-  const liveRevision = await chunkTKFQLKH2_cjs.readRecordedClock(
+  const liveRevision = await chunkCYKHSH5O_cjs.readRecordedClock(
     txBackend,
     target.revisionSchema,
     target.graphId
@@ -8138,7 +8200,7 @@ async function applyWireMergeWrites(target, nodesApi, edgesApi, txBackend, artif
     txBackend,
     identityAssertions,
     identityRetractions,
-    () => chunkORPT5EQW_cjs.storeRuntime(target).assertIdentityClassesConsistentAtTarget(
+    () => chunkUZ6CJUC5_cjs.storeRuntime(target).assertIdentityClassesConsistentAtTarget(
       txBackend,
       identityConsistencySeeds(
         artifact,
@@ -8146,8 +8208,8 @@ async function applyWireMergeWrites(target, nodesApi, edgesApi, txBackend, artif
       )
     )
   );
-  if (!chunkTKFQLKH2_cjs.forceRecordedGraphRevision(txBackend, target.graphId) && !chunkTKFQLKH2_cjs.forceWriteTransactionRevision(txBackend)) {
-    await chunkTKFQLKH2_cjs.advanceRevisionClock(
+  if (!chunkCYKHSH5O_cjs.forceRecordedGraphRevision(txBackend, target.graphId) && !chunkCYKHSH5O_cjs.forceWriteTransactionRevision(txBackend)) {
+    await chunkCYKHSH5O_cjs.advanceRevisionClock(
       txBackend,
       target.revisionSchema,
       target.graphId,
@@ -8182,7 +8244,7 @@ function reportFromArtifact(artifact, merged, warnings, provenancePersisted) {
     ...provenancePersisted === void 0 ? {} : { provenancePersisted }
   };
 }
-async function applyMergePlan(target, input) {
+async function applyMergePlan(target, input, options = {}) {
   let validation;
   try {
     validation = await validateMergePlanArtifact(input);
@@ -8211,6 +8273,9 @@ async function applyMergePlan(target, input) {
     );
   }
   try {
+    const { beforeApply, afterApply } = options;
+    const composed = beforeApply !== void 0 || afterApply !== void 0;
+    const transactionOptions = composed ? { isolationLevel: "read_committed" } : mergeCommitTransactionOptions(target);
     assertPublicPlanCapability(target);
     const provenanceStore = artifact.provenance.persist ? await tryOpenProvenanceStore(target) : void 0;
     if (provenanceStore !== void 0 && chunkNXJRIRWE_cjs.isErr(provenanceStore)) {
@@ -8218,12 +8283,19 @@ async function applyMergePlan(target, input) {
     }
     const merged = await withTxConflictRetry(
       () => target.transaction(async (tx) => {
-        const txBackend = chunkORPT5EQW_cjs.transactionBackend(tx);
+        const txBackend = chunkUZ6CJUC5_cjs.transactionBackend(tx);
         await assertMergePlanFenceInsideTransaction(
           target,
           txBackend,
-          artifact
+          artifact,
+          composed
         );
+        if (beforeApply !== void 0) {
+          assertMergeCallbackResult(
+            await beforeApply(mergePlanReadContext(tx, target.graph)),
+            "beforeApply"
+          );
+        }
         await preflightWireMergeWrites(
           target,
           tx.nodes,
@@ -8234,14 +8306,21 @@ async function applyMergePlan(target, input) {
           identityAssertions: artifact.writes.identityAssertions,
           identityRetractions: artifact.writes.identityRetractions
         });
-        return applyWireMergeWrites(
+        const applied = await applyWireMergeWrites(
           target,
           tx.nodes,
           tx.edges,
           txBackend,
           artifact
         );
-      }, mergeCommitTransactionOptions(target))
+        if (afterApply !== void 0) {
+          assertMergeCallbackResult(
+            await afterApply(tx, { merged: structuredClone(applied) }),
+            "afterApply"
+          );
+        }
+        return applied;
+      }, transactionOptions)
     );
     const warnings = [...artifact.review.warnings];
     let provenancePersisted;
@@ -8711,7 +8790,7 @@ async function assertForkPointUnchanged(precondition) {
   );
 }
 async function commitIncrementalPlan(target, plan, guard) {
-  if (!chunkORPT5EQW_cjs.storeBackend(target).capabilities.execution.interactiveTransactions) {
+  if (!chunkUZ6CJUC5_cjs.storeBackend(target).capabilities.execution.interactiveTransactions) {
     throw new MergeError(
       "mergeIncremental() requires a transaction-capable target backend. Incremental writes must preflight existing rows and commit atomically; non-transactional fallback would allow partial graph writes.",
       { details: { capability: "execution.interactiveTransactions" } }
@@ -8720,7 +8799,7 @@ async function commitIncrementalPlan(target, plan, guard) {
   return runMergeCommit(
     () => withTxConflictRetry(
       () => target.transaction(async (tx) => {
-        await lockMergeTargetWrite(chunkORPT5EQW_cjs.transactionBackend(tx), {
+        await lockMergeTargetWrite(chunkUZ6CJUC5_cjs.transactionBackend(tx), {
           graphId: target.graphId,
           schemaVersion: target.introspect().schemaVersion,
           graphLock: target.revisionTrackingEnabled ? "required" : "not-required",
@@ -8738,12 +8817,12 @@ async function commitIncrementalPlan(target, plan, guard) {
         );
         await assertPlannedIdentityIdsFresh(
           target,
-          chunkORPT5EQW_cjs.transactionBackend(tx),
+          chunkUZ6CJUC5_cjs.transactionBackend(tx),
           plan
         );
         await assertIdentityPeersStable(
           target,
-          chunkORPT5EQW_cjs.transactionBackend(tx),
+          chunkUZ6CJUC5_cjs.transactionBackend(tx),
           guard.identityPeerProbe,
           plan
         );
@@ -8755,7 +8834,7 @@ async function commitIncrementalPlan(target, plan, guard) {
           nodesApi,
           edgesApi,
           target,
-          chunkORPT5EQW_cjs.transactionBackend(tx)
+          chunkUZ6CJUC5_cjs.transactionBackend(tx)
         );
       }, mergeCommitTransactionOptions(target))
     )
@@ -8845,10 +8924,10 @@ var CandidateWriteSetSchema = zod.z.object({
   target: CandidateWriteSetTargetSchema,
   nodes: zod.z.array(candidateNodeSchema),
   edges: zod.z.array(candidateEdgeSchema),
-  identity: chunk7I2PYI4U_cjs.InterchangeIdentitySchema.optional()
+  identity: chunkKR3N6Y7O_cjs.InterchangeIdentitySchema.optional()
 });
 async function captureCandidateWriteSetTarget(target) {
-  const activeSchema = await chunkORPT5EQW_cjs.storeBackend(target).getActiveSchema(
+  const activeSchema = await chunkUZ6CJUC5_cjs.storeBackend(target).getActiveSchema(
     target.graphId
   );
   return {
@@ -8927,7 +9006,7 @@ async function planCandidateWriteSet(args) {
   }
   const candidate = created.data;
   try {
-    const imported = await chunk7I2PYI4U_cjs.importGraph(
+    const imported = await chunkKR3N6Y7O_cjs.importGraph(
       candidate,
       interchangeDocument(writeSet),
       {
@@ -8966,6 +9045,401 @@ async function planCandidateWriteSet(args) {
   }
 }
 
+// src/graph-merge/review-evidence.ts
+function reviewJson(value) {
+  if (value === void 0) return "undefined";
+  return JSON.stringify(value, chunk5X46XWNH_cjs.sortedReplacer);
+}
+async function reviewDigest(value) {
+  return chunkZY4GXIVN_cjs.sha256Hex(reviewJson(value), 32);
+}
+function reviewOptionEvidence(options) {
+  return encodeOption(normalizeMergeOptions(options), /* @__PURE__ */ new Set());
+}
+function encodeOption(value, ancestors) {
+  if (value === void 0) return ["undefined"];
+  if (typeof value === "function") return ["callback"];
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return ["literal", value];
+  }
+  if (typeof value === "number" && Number.isFinite(value))
+    return ["number", value];
+  if (typeof value !== "object" || ancestors.has(value)) {
+    throw new MergeReviewError(
+      "Merge options contain unsupported or cyclic review evidence."
+    );
+  }
+  const nextAncestors = /* @__PURE__ */ new Set([...ancestors, value]);
+  if (Array.isArray(value)) {
+    return [
+      "array",
+      value.map((item) => encodeOption(item, nextAncestors))
+    ];
+  }
+  if (value instanceof Map) {
+    const entries = [...value].map(
+      ([key, entry]) => [
+        encodeOption(key, nextAncestors),
+        encodeOption(entry, nextAncestors)
+      ]
+    );
+    entries.sort(
+      (left, right) => chunkNYWU6CBZ_cjs.compareStrings(reviewJson(left), reviewJson(right))
+    );
+    return ["map", entries];
+  }
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new MergeReviewError(
+      "Merge options contain a non-JSON object without a review representation."
+    );
+  }
+  return [
+    "object",
+    Object.entries(value).sort(([left], [right]) => chunkNYWU6CBZ_cjs.compareStrings(left, right)).map(([key, entry]) => [key, encodeOption(entry, nextAncestors)])
+  ];
+}
+
+// src/graph-merge/review-baseline.ts
+function reviewRowKey(row) {
+  return JSON.stringify([row.role, row.kind, row.id]);
+}
+async function captureReviewBaseline(target) {
+  const backend = chunkUZ6CJUC5_cjs.storeBackend(target);
+  const rows = [];
+  for (const kind of chunkV32ES2Q2_cjs.getNodeKinds(target.graph)) {
+    for (const row of await enumerateAllNodes(backend, target.graphId, kind)) {
+      rows.push({
+        role: "node",
+        kind,
+        id: row.id,
+        digest: await reviewDigest({ ...row, props: parseRowProps(row.props) })
+      });
+    }
+  }
+  for (const kind of chunkV32ES2Q2_cjs.getEdgeKinds(target.graph)) {
+    for (const row of await enumerateAllEdges(backend, target.graphId, kind)) {
+      rows.push({
+        role: "edge",
+        kind,
+        id: row.id,
+        digest: await reviewDigest({ ...row, props: parseRowProps(row.props) })
+      });
+    }
+  }
+  const identity = await chunkUZ6CJUC5_cjs.storeRuntime(target).readCurrentIdentityAssertions(
+    "archival",
+    {
+      includeDeleted: true
+    }
+  );
+  return {
+    rows: rows.sort(
+      (left, right) => chunkNYWU6CBZ_cjs.compareStrings(reviewRowKey(left), reviewRowKey(right))
+    ),
+    identityDigest: await reviewDigest(
+      [...identity].sort((left, right) => chunkNYWU6CBZ_cjs.compareStrings(left.id, right.id))
+    )
+  };
+}
+function withReviewAbsences(baseline, writeSet, plan, graph) {
+  const rows = new Map(baseline.rows.map((row) => [reviewRowKey(row), row]));
+  function addNode(entity) {
+    for (const kind of chunkV32ES2Q2_cjs.getNodeKinds(graph)) {
+      const row = { role: "node", kind, id: entity.id };
+      if (!rows.has(reviewRowKey(row))) rows.set(reviewRowKey(row), row);
+    }
+  }
+  for (const row of baseline.rows) if (row.role === "node") addNode(row);
+  function addEdge(entity) {
+    for (const kind of chunkV32ES2Q2_cjs.getEdgeKinds(graph)) {
+      const row = { role: "edge", kind, id: entity.id };
+      if (!rows.has(reviewRowKey(row))) rows.set(reviewRowKey(row), row);
+    }
+  }
+  for (const node of [
+    ...writeSet.nodes,
+    ...plan.writes.nodeUpserts,
+    ...plan.writes.nodeDeletes,
+    ...plan.guards.deletedNodes
+  ])
+    addNode(node);
+  for (const edge of [...writeSet.edges, ...plan.writes.edgeUpserts]) {
+    addEdge(edge);
+    addNode(edge.from);
+    addNode(edge.to);
+  }
+  for (const edge of plan.writes.edgeDeletes) addEdge(edge);
+  for (const assertion of [
+    ...writeSet.identity?.assertions ?? [],
+    ...plan.writes.identityAssertions,
+    ...plan.writes.identityRetractions
+  ]) {
+    addNode(assertion.a);
+    addNode(assertion.b);
+    if (assertion.endedBy !== void 0) addNode(assertion.endedBy);
+  }
+  for (const mapping of plan.guards.canonicalMappings) {
+    addNode(mapping.member);
+    addNode(mapping.canonical);
+  }
+  for (const retype of plan.guards.retypes) {
+    addNode(retype.entity);
+    addNode({ kind: retype.toKind, id: retype.entity.id });
+  }
+  return {
+    ...baseline,
+    rows: [...rows.values()].sort(
+      (left, right) => chunkNYWU6CBZ_cjs.compareStrings(reviewRowKey(left), reviewRowKey(right))
+    )
+  };
+}
+function compareReviewBaseline(reviewed, current) {
+  const currentRows = new Map(
+    current.rows.map((row) => [reviewRowKey(row), row])
+  );
+  const differences = [];
+  for (const row of reviewed.rows) {
+    if (row.digest !== currentRows.get(reviewRowKey(row))?.digest) {
+      differences.push({
+        category: "baseline",
+        path: "baseline.rows",
+        entity: { role: row.role, kind: row.kind, id: row.id }
+      });
+    }
+  }
+  if (reviewed.identityDigest !== current.identityDigest) {
+    differences.push({ category: "baseline", path: "baseline.identityDigest" });
+  }
+  return differences;
+}
+var MERGE_REVIEW_FORMAT_VERSION = 1;
+var digestSchema = zod.z.string().regex(/^[\da-f]{64}$/u);
+var mergeReviewPolicySchema = zod.z.object({
+  id: zod.z.string().min(1),
+  context: zod.z.json()
+}).strict();
+var mergeReviewArtifactSchema = zod.z.object({
+  formatVersion: zod.z.literal(MERGE_REVIEW_FORMAT_VERSION),
+  kind: zod.z.literal("candidate-write-set"),
+  digest: zod.z.object({ algorithm: zod.z.literal("sha256"), value: digestSchema }).strict(),
+  writeSet: CandidateWriteSetSchema,
+  policy: mergeReviewPolicySchema,
+  options: zod.z.json(),
+  plan: mergePlanArtifactV1Schema,
+  baseline: zod.z.object({
+    rows: zod.z.array(
+      zod.z.object({
+        role: zod.z.enum(["node", "edge"]),
+        kind: zod.z.string().min(1),
+        id: zod.z.string().min(1),
+        digest: digestSchema.optional()
+      }).strict()
+    ),
+    identityDigest: digestSchema
+  }).strict()
+}).strict();
+
+// src/graph-merge/candidate-review.ts
+async function planCandidateWriteSetReview(args) {
+  try {
+    const writeSet = CandidateWriteSetSchema.parse(args.writeSet);
+    const policy = mergeReviewPolicySchema.parse(args.policy);
+    const options = reviewOptionEvidence(args.options);
+    const startingFence = await captureMergePlanTargetFence(args.target);
+    const baseline = await captureReviewBaseline(args.target);
+    const planned = await planCandidateWriteSet({ ...args, writeSet });
+    if (chunkNXJRIRWE_cjs.isErr(planned)) return planned;
+    assertReviewPlanFence(startingFence, planned.data);
+    await assertPlanningFenceUnchanged(args.target, startingFence);
+    assertOptionsUnchanged(options, reviewOptionEvidence(args.options));
+    const input = {
+      formatVersion: MERGE_REVIEW_FORMAT_VERSION,
+      kind: "candidate-write-set",
+      writeSet,
+      policy,
+      options,
+      plan: planned.data,
+      baseline: withReviewAbsences(
+        baseline,
+        writeSet,
+        planned.data,
+        args.target.graph
+      )
+    };
+    const review = {
+      ...input,
+      digest: { algorithm: "sha256", value: await reviewDigest(input) }
+    };
+    mergeReviewArtifactSchema.parse(review);
+    return chunkNXJRIRWE_cjs.ok(review);
+  } catch (error) {
+    return chunkNXJRIRWE_cjs.err(asReviewError(error));
+  }
+}
+async function revalidateCandidateWriteSetReview(args) {
+  try {
+    const review = await validateReview(args.review);
+    const policy = mergeReviewPolicySchema.parse(args.policy);
+    const options = reviewOptionEvidence(args.options);
+    const startingFence = await captureMergePlanTargetFence(args.target);
+    const targetDifferences = compareReviewTarget(
+      review.plan.target,
+      startingFence
+    );
+    if (targetDifferences.length > 0)
+      return chunkNXJRIRWE_cjs.ok({
+        status: "incompatible",
+        reviewDigest: review.digest,
+        differences: targetDifferences
+      });
+    if (withReviewAbsences(
+      review.baseline,
+      review.writeSet,
+      review.plan,
+      args.target.graph
+    ).rows.length !== review.baseline.rows.length) {
+      throw new MergeReviewError(
+        "The merge review is missing required baseline evidence.",
+        { details: { reason: "incomplete-baseline" } }
+      );
+    }
+    const policyDifferences = compareFields(
+      "policy",
+      { policy: review.policy, options: review.options },
+      { policy, options }
+    );
+    if (policyDifferences.length > 0)
+      return chunkNXJRIRWE_cjs.ok({
+        status: "changed",
+        reviewDigest: review.digest,
+        differences: policyDifferences
+      });
+    const baseline = await captureReviewBaseline(args.target);
+    const baselineDifferences = compareReviewBaseline(
+      review.baseline,
+      baseline
+    );
+    if (baselineDifferences.length > 0) {
+      await assertPlanningFenceUnchanged(args.target, startingFence);
+      return chunkNXJRIRWE_cjs.ok({
+        status: "changed",
+        reviewDigest: review.digest,
+        differences: baselineDifferences
+      });
+    }
+    const planned = await planCandidateWriteSet({
+      ...args,
+      writeSet: review.writeSet
+    });
+    if (chunkNXJRIRWE_cjs.isErr(planned)) return planned;
+    assertReviewPlanFence(startingFence, planned.data);
+    await assertPlanningFenceUnchanged(args.target, startingFence);
+    assertOptionsUnchanged(options, reviewOptionEvidence(args.options));
+    const differences = compareFields(
+      "plan",
+      reviewPlanContent(review.plan),
+      reviewPlanContent(planned.data)
+    );
+    return chunkNXJRIRWE_cjs.ok(
+      differences.length === 0 ? {
+        status: "compatible",
+        reviewDigest: review.digest,
+        plan: planned.data
+      } : {
+        status: "changed",
+        reviewDigest: review.digest,
+        differences,
+        plan: planned.data
+      }
+    );
+  } catch (error) {
+    return chunkNXJRIRWE_cjs.err(asReviewError(error));
+  }
+}
+async function validateReview(input) {
+  const review = mergeReviewArtifactSchema.parse(input);
+  if (reviewJson(input) !== reviewJson(review)) {
+    throw new MergeReviewError(
+      "Stored merge review evidence must not require normalization.",
+      {
+        details: { reason: "noncanonical-shape" }
+      }
+    );
+  }
+  const { digest, ...content } = review;
+  if (digest.value !== await reviewDigest(content)) {
+    throw new MergeReviewError(
+      "The merge review digest does not match its content.",
+      { details: { reason: "digest-mismatch" } }
+    );
+  }
+  const plan = await validateMergePlanArtifact(review.plan);
+  if (!plan.success)
+    throw new MergeReviewError("The reviewed execution plan is invalid.", {
+      details: { reason: "invalid-plan", error: plan.error }
+    });
+  const anchors = plan.artifact.anchors;
+  if (plan.artifact.mode !== "incremental" || anchors.kind !== "incremental" || anchors.forkPoint.graphId !== review.writeSet.target.graphId || plan.artifact.target.graphId !== review.writeSet.target.graphId || plan.artifact.target.schema.version !== review.writeSet.target.schemaVersion || plan.artifact.target.schema.hash !== review.writeSet.target.schemaHash || reviewJson(anchors.forkPoint.schema) !== reviewJson(plan.artifact.target.schema) || anchors.branches.length !== 1 || anchors.branches[0]?.branchId !== review.writeSet.sourceId || anchors.branches[0].baseVersion !== anchors.forkPoint.baseVersion) {
+    throw new MergeReviewError(
+      "The reviewed plan does not describe the retained candidate source and target.",
+      { details: { reason: "incompatible-plan" } }
+    );
+  }
+  if (new Set(review.baseline.rows.map((row) => reviewRowKey(row))).size !== review.baseline.rows.length) {
+    throw new MergeReviewError(
+      "The merge review contains duplicate baseline references.",
+      { details: { reason: "duplicate-baseline" } }
+    );
+  }
+  return { ...review, plan: plan.artifact };
+}
+function assertReviewPlanFence(fence, plan) {
+  if (!sameMergePlanTargetFence(fence, plan.target)) {
+    throw new MergePlanningStaleError(
+      "The target changed between review evidence capture and planning."
+    );
+  }
+}
+function assertOptionsUnchanged(before, after) {
+  if (reviewJson(before) !== reviewJson(after))
+    throw new MergeReviewError(
+      "Merge options changed while review evidence was being captured."
+    );
+}
+function compareReviewTarget(reviewed, current) {
+  return compareFields(
+    "target",
+    {
+      graphId: reviewed.graphId,
+      schema: reviewed.schema,
+      origin: reviewed.revision.origin
+    },
+    {
+      graphId: current.graphId,
+      schema: current.schema,
+      origin: current.revision.origin
+    }
+  );
+}
+function reviewPlanContent(plan) {
+  const {
+    digest: _digest,
+    target: _target,
+    anchors: _anchors,
+    ...content
+  } = plan;
+  return content;
+}
+function compareFields(category, reviewed, current) {
+  return [.../* @__PURE__ */ new Set([...Object.keys(reviewed), ...Object.keys(current)])].sort().filter((key) => reviewJson(reviewed[key]) !== reviewJson(current[key])).map((key) => ({ category, path: `${category}.${key}` }));
+}
+function asReviewError(error) {
+  return error instanceof MergeError ? error : new MergeReviewError(
+    "Unable to validate or capture merge review evidence.",
+    { cause: error }
+  );
+}
+
 Object.defineProperty(exports, "isErr", {
   enumerable: true,
   get: function () { return chunkNXJRIRWE_cjs.isErr; }
@@ -8992,6 +9466,7 @@ exports.MERGE_ERROR_CODES = MERGE_ERROR_CODES;
 exports.MERGE_OPTION_DEFAULTS = MERGE_OPTION_DEFAULTS;
 exports.MERGE_PLAN_DIGEST_ALGORITHM = MERGE_PLAN_DIGEST_ALGORITHM;
 exports.MERGE_PLAN_FORMAT_VERSION = MERGE_PLAN_FORMAT_VERSION;
+exports.MERGE_REVIEW_FORMAT_VERSION = MERGE_REVIEW_FORMAT_VERSION;
 exports.MatchEvidenceError = MatchEvidenceError;
 exports.MergeConflictError = MergeConflictError;
 exports.MergeConstraintConflictError = MergeConstraintConflictError;
@@ -9002,6 +9477,7 @@ exports.MergePlanOriginMismatchError = MergePlanOriginMismatchError;
 exports.MergePlanSchemaMismatchError = MergePlanSchemaMismatchError;
 exports.MergePlanTargetMismatchError = MergePlanTargetMismatchError;
 exports.MergePlanningStaleError = MergePlanningStaleError;
+exports.MergeReviewError = MergeReviewError;
 exports.SimilarityUnavailableError = SimilarityUnavailableError;
 exports.StaleMergePlanError = StaleMergePlanError;
 exports.UnsupportedMergePlanVersionError = UnsupportedMergePlanVersionError;
@@ -9020,9 +9496,11 @@ exports.normalizeMergeOptions = normalizeMergeOptions;
 exports.openProvenanceStore = openProvenanceStore;
 exports.persistProvenanceRecords = persistProvenanceRecords;
 exports.planCandidateWriteSet = planCandidateWriteSet;
+exports.planCandidateWriteSetReview = planCandidateWriteSetReview;
 exports.planMerge = planMerge;
 exports.planMergeIncremental = planMergeIncremental;
 exports.provenanceGraphId = provenanceGraphId;
 exports.readProvenance = readProvenance;
+exports.revalidateCandidateWriteSetReview = revalidateCandidateWriteSetReview;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map