@nicia-ai/typegraph 0.31.0 → 0.33.0

package/dist/graph-merge/index.cjs

@@ -1,29 +1,30 @@
 'use strict';
 
-var chunkRZ4DH4E7_cjs = require('../chunk-RZ4DH4E7.cjs');
+var chunkD3EWZ67S_cjs = require('../chunk-D3EWZ67S.cjs');
 require('../chunk-HTGDWIDE.cjs');
-var chunk3JBJEYWE_cjs = require('../chunk-3JBJEYWE.cjs');
-var chunk5DTPBFX5_cjs = require('../chunk-5DTPBFX5.cjs');
-var chunk7JGLPAFV_cjs = require('../chunk-7JGLPAFV.cjs');
-require('../chunk-6SA7UIQJ.cjs');
-require('../chunk-6RMLO5O4.cjs');
-require('../chunk-YQGLVWB2.cjs');
+var chunkSST7XDY6_cjs = require('../chunk-SST7XDY6.cjs');
+var chunkNG5N7R45_cjs = require('../chunk-NG5N7R45.cjs');
+var chunkMBLXCV2Y_cjs = require('../chunk-MBLXCV2Y.cjs');
+require('../chunk-3QRBXYT5.cjs');
+require('../chunk-3IR2GEMJ.cjs');
+require('../chunk-EF3Z645U.cjs');
 require('../chunk-ZFWNO3GE.cjs');
 var chunkKTIEB7VH_cjs = require('../chunk-KTIEB7VH.cjs');
-require('../chunk-6G35I3VW.cjs');
-var chunkRP7YITHX_cjs = require('../chunk-RP7YITHX.cjs');
-require('../chunk-V4IQYOQ4.cjs');
+require('../chunk-I4W7MKVG.cjs');
+var chunkOIE2UPVG_cjs = require('../chunk-OIE2UPVG.cjs');
+require('../chunk-CFNT3ITG.cjs');
 var chunk73KASJGO_cjs = require('../chunk-73KASJGO.cjs');
+require('../chunk-3E7SNSIA.cjs');
 var chunkJIEJCTDS_cjs = require('../chunk-JIEJCTDS.cjs');
 require('../chunk-FLRCVI2G.cjs');
 var zod = require('zod');
 
 // src/graph-merge/canonical-props.ts
 function canonicalizeProps(props) {
-  return JSON.stringify(props, chunkRP7YITHX_cjs.sortedReplacer);
+  return JSON.stringify(props, chunkOIE2UPVG_cjs.sortedReplacer);
 }
 function canonicalValueKey(value) {
-  return JSON.stringify(value, chunkRP7YITHX_cjs.sortedReplacer);
+  return JSON.stringify(value, chunkOIE2UPVG_cjs.sortedReplacer);
 }
 function parseRowProps(props) {
   let parsed;
@@ -228,8 +229,8 @@ function byId(left, right) {
 }
 async function diffAgainstBase(baseStore, forkStore) {
   const graph = baseStore.graph;
-  const nodeKinds = chunk7JGLPAFV_cjs.getNodeKinds(graph);
-  const edgeKinds = chunk7JGLPAFV_cjs.getEdgeKinds(graph);
+  const nodeKinds = chunkMBLXCV2Y_cjs.getNodeKinds(graph);
+  const edgeKinds = chunkMBLXCV2Y_cjs.getEdgeKinds(graph);
   const newNodes = [];
   const modifiedNodes = [];
   const deletedNodes = [];
@@ -311,19 +312,16 @@ async function readActiveSchemaVersion(backend, graphId) {
 }
 async function computeSchemaComponent(store) {
   const version = await readActiveSchemaVersion(store.backend, store.graphId);
-  return chunk5DTPBFX5_cjs.computeSchemaHash(chunk5DTPBFX5_cjs.serializeSchema(store.graph, version));
+  return chunkNG5N7R45_cjs.computeSchemaHash(chunkNG5N7R45_cjs.serializeSchema(store.graph, version));
 }
 function byDigestEntry(left, right) {
   const byKind = compareStrings(left.kind, right.kind);
   return byKind === 0 ? compareStrings(left.id, right.id) : byKind;
 }
 var CONTENT_FINGERPRINT_BYTES = 16;
-async function computeContentFingerprint(store) {
-  const backend = store.backend;
-  const graphId = store.graphId;
-  const graph = store.graph;
-  const nodeKinds = chunk7JGLPAFV_cjs.getNodeKinds(graph);
-  const edgeKinds = chunk7JGLPAFV_cjs.getEdgeKinds(graph);
+async function computeContentComponent(backend, graphId, graph) {
+  const nodeKinds = chunkMBLXCV2Y_cjs.getNodeKinds(graph);
+  const edgeKinds = chunkMBLXCV2Y_cjs.getEdgeKinds(graph);
   const nodeDigest = [];
   for (const kind of nodeKinds) {
     const rows = await enumerateAllNodes(backend, graphId, kind);
@@ -369,12 +367,16 @@ async function computeContentFingerprint(store) {
 async function computeBaseVersion(store) {
   const [schemaComponent, contentComponent] = await Promise.all([
     computeSchemaComponent(store),
-    computeContentFingerprint(store)
+    computeContentComponent(store.backend, store.graphId, store.graph)
   ]);
   return asBaseVersion(
     `${schemaComponent}${TOKEN_SEPARATOR}${contentComponent}`
   );
 }
+function contentComponentOf(version) {
+  const separatorIndex = version.indexOf(TOKEN_SEPARATOR);
+  return separatorIndex === -1 ? version : version.slice(separatorIndex + 1);
+}
 
 // src/graph-merge/errors.ts
 var MERGE_ERROR_CODES = {
@@ -445,17 +447,17 @@ var CLONE_IMPORT_BATCH_SIZE = 1e3;
 function cloneWorkingCopyStrategy(makeBackend) {
   return {
     create: async (baseStore) => {
-      const data = await chunk3JBJEYWE_cjs.exportGraph(baseStore, {
+      const data = await chunkSST7XDY6_cjs.exportGraph(baseStore, {
         includeMeta: true,
         includeDeleted: false
       });
       const backend = await makeBackend();
       try {
-        const [freshStore] = await chunkRZ4DH4E7_cjs.createStoreWithSchema(
+        const [freshStore] = await chunkD3EWZ67S_cjs.createStoreWithSchema(
           baseStore.graph,
           backend
         );
-        const result = await chunk3JBJEYWE_cjs.importGraph(freshStore, data, {
+        const result = await chunkSST7XDY6_cjs.importGraph(freshStore, data, {
           onConflict: "error",
           onUnknownProperty: "error",
           validateReferences: true,
@@ -483,7 +485,7 @@ function cloneWorkingCopyStrategy(makeBackend) {
 async function branch(baseStore, makeBackend, options, strategy) {
   try {
     const base = await computeBaseVersion(baseStore);
-    const id = options?.id ?? asBranchId(chunkRZ4DH4E7_cjs.generateId());
+    const id = options?.id ?? asBranchId(chunkD3EWZ67S_cjs.generateId());
     const workingCopyStrategy = strategy ?? cloneWorkingCopyStrategy(makeBackend);
     const store = await workingCopyStrategy.create(baseStore);
     return chunkKTIEB7VH_cjs.ok({ id, base, store });
@@ -512,7 +514,7 @@ function constraintSignature(node, constraint) {
       return void 0;
     }
   }
-  return `${constraint.name}${KEY_PART_SEPARATOR}${chunkRZ4DH4E7_cjs.computeUniqueKey(
+  return `${constraint.name}${KEY_PART_SEPARATOR}${chunkD3EWZ67S_cjs.computeUniqueKey(
     props,
     constraint.fields,
     constraint.collation
@@ -2055,7 +2057,7 @@ function normalizeMergeOptions(options = {}) {
     ...provenanceWeights === void 0 ? {} : { provenanceWeights }
   };
 }
-var Provenance = chunk5DTPBFX5_cjs.defineNode("Provenance", {
+var Provenance = chunkNG5N7R45_cjs.defineNode("Provenance", {
   schema: zod.z.object({
     targetGraphId: zod.z.string(),
     role: zod.z.enum(["node", "edge"]),
@@ -2069,14 +2071,14 @@ function provenanceGraphId(targetGraphId) {
   return `${targetGraphId}::merge-provenance`;
 }
 function buildProvenanceGraph(targetGraphId) {
-  return chunk7JGLPAFV_cjs.defineGraph({
+  return chunkMBLXCV2Y_cjs.defineGraph({
     id: provenanceGraphId(targetGraphId),
     nodes: { Provenance: { type: Provenance } },
     edges: {}
   });
 }
 async function openProvenanceStore(backend, targetGraphId) {
-  const [store] = await chunkRZ4DH4E7_cjs.createStoreWithSchema(
+  const [store] = await chunkD3EWZ67S_cjs.createStoreWithSchema(
     buildProvenanceGraph(targetGraphId),
     backend
   );
@@ -2507,6 +2509,48 @@ async function stageBranches(baseStore, branches) {
   };
 }
 
+// src/graph-merge/tx-retry.ts
+var RETRYABLE_SQLSTATES = /* @__PURE__ */ new Set(["40001", "40P01"]);
+var RETRYABLE_MESSAGE_PATTERN = /could not serialize access|deadlock detected/i;
+var MAX_COMMIT_ATTEMPTS = 3;
+function isRetryableTxConflict(error) {
+  const seen = /* @__PURE__ */ new Set();
+  let current = error;
+  while (current !== void 0 && current !== null && typeof current === "object" && !seen.has(current)) {
+    seen.add(current);
+    const candidate = current;
+    if (typeof candidate.code === "string" && RETRYABLE_SQLSTATES.has(candidate.code)) {
+      return true;
+    }
+    if (typeof candidate.message === "string" && RETRYABLE_MESSAGE_PATTERN.test(candidate.message)) {
+      return true;
+    }
+    current = candidate.cause;
+  }
+  return false;
+}
+async function withTxConflictRetry(commit) {
+  let lastConflict;
+  for (let attempt = 1; attempt <= MAX_COMMIT_ATTEMPTS; attempt += 1) {
+    try {
+      return await commit();
+    } catch (error) {
+      if (!isRetryableTxConflict(error)) {
+        throw error;
+      }
+      lastConflict = error;
+    }
+  }
+  throw new MergeError(
+    `Merge commit aborted by transaction conflicts (serialization failure or deadlock) on ${MAX_COMMIT_ATTEMPTS} consecutive attempts; giving up.`,
+    {
+      cause: lastConflict,
+      details: { attempts: MAX_COMMIT_ATTEMPTS },
+      suggestion: "Reduce concurrent writes to the merge target, or serialize merges against it."
+    }
+  );
+}
+
 // src/graph-merge/type-reconcile.ts
 var INCOMPATIBLE_TYPES_FLAG_REASON = "type-reconcile:incompatible-kinds";
 function distinctKinds(kinds) {
@@ -3226,20 +3270,48 @@ async function applyMergePlan(plan, nodesApi, edgesApi) {
   }
   return { nodes: committedNodeIds.size, edges: committedEdges };
 }
-async function commitPlan(target, plan) {
+async function commitPlan(target, plan, expectedBaseVersion) {
   if (!target.backend.capabilities.transactions) {
     throw new MergeError(
       "merge() requires a transaction-capable target backend. The merged plan (canonical upserts, soft-deletes, edge upserts) must commit atomically; a non-transactional fallback would leave a partially-merged graph on a mid-commit failure. (mergeIncremental() enforces the same requirement.)",
       { details: { capability: "transactions" } }
     );
   }
-  return target.transaction(
-    (tx) => applyMergePlan(
-      plan,
-      tx.nodes,
-      tx.edges
-    )
+  return withTxConflictRetry(
+    () => target.transaction(async (tx) => {
+      if (expectedBaseVersion !== void 0) {
+        await assertTargetUnchanged(tx.backend, target, expectedBaseVersion);
+      }
+      return applyMergePlan(
+        plan,
+        tx.nodes,
+        tx.edges
+      );
+    }, MERGE_COMMIT_TX_OPTIONS)
+  );
+}
+var MERGE_COMMIT_TX_OPTIONS = {
+  isolationLevel: "serializable"
+};
+async function assertTargetUnchanged(txBackend, target, expectedBaseVersion) {
+  const liveContent = await computeContentComponent(
+    txBackend,
+    target.graphId,
+    target.graph
   );
+  const expectedContent = contentComponentOf(expectedBaseVersion);
+  if (liveContent !== expectedContent) {
+    throw new BaseVersionMismatchError(
+      "The merge target was modified between the base@V check and the commit transaction; the resolved plan no longer describes the live target and was not applied.",
+      {
+        details: {
+          expectedContentFingerprint: expectedContent,
+          liveContentFingerprint: liveContent
+        },
+        suggestion: "Re-run the merge (and re-branch if the divergence is real), or serialize writers against merges on this target."
+      }
+    );
+  }
 }
 function nodeCollection(nodes, kind) {
   const collection = nodes[kind];
@@ -3277,7 +3349,7 @@ async function validateBaseVersions(target, branches) {
       );
     }
   }
-  return chunkKTIEB7VH_cjs.ok();
+  return chunkKTIEB7VH_cjs.ok(targetVersion);
 }
 function tryNormalize(optionsInput) {
   try {
@@ -3286,7 +3358,7 @@ function tryNormalize(optionsInput) {
     return chunkKTIEB7VH_cjs.err(new MergeError("Invalid merge options.", { cause: error }));
   }
 }
-async function resolveMerge(store, target, branches, options, useBaseSources, incremental) {
+async function resolveMerge(store, target, branches, options, useBaseSources, incremental, expectedBaseVersion) {
   let targetBranchSeen = false;
   for (const branch2 of branches) {
     if (branch2.id === BASE_PROVENANCE_BRANCH) {
@@ -3357,7 +3429,16 @@ async function resolveMerge(store, target, branches, options, useBaseSources, in
       subClassClosure,
       preferredBranchId
     );
-    const merged = incremental === void 0 ? await commitPlan(target, plan) : await commitIncrementalPlan(target, plan);
+    const merged = incremental === void 0 ? await commitPlan(target, plan, expectedBaseVersion) : await commitIncrementalPlan(target, plan, {
+      stagedNewByKind: newNodesByKind(staging),
+      options,
+      introspectionKinds,
+      // The committed (kind, id) keys the base sources matched at PLAN time;
+      // anything NEW the in-tx re-probe surfaces is a window write.
+      plannedBaseMatchKeys: new Set(
+        candidates.data.baseMembers.map((member) => mergeKeyOf(member))
+      )
+    });
     const provenance = options.provenance ? buildProvenanceIndex(plan.provenanceRecords) : { byBranch: () => ({ nodeIds: [], edgeIds: [] }) };
     const warnings = [...plan.warnings];
     let provenancePersisted;
@@ -3418,7 +3499,15 @@ async function merge(store, branches, optionsInput = {}) {
   if (chunkKTIEB7VH_cjs.isErr(precondition)) {
     return chunkKTIEB7VH_cjs.err(precondition.error);
   }
-  return resolveMerge(store, target, branches, options, false);
+  return resolveMerge(
+    store,
+    target,
+    branches,
+    options,
+    false,
+    void 0,
+    precondition.data
+  );
 }
 async function validateForkPointVersions(forkPoint, branches) {
   const forkVersion = await computeBaseVersion(forkPoint);
@@ -3651,13 +3740,12 @@ async function validateIncrementalEdgeWrites(target, edgesApi, plan) {
   }
   const notFound = [...plannedKindById.keys()].filter((id) => !existingById.has(id)).sort((left, right) => compareStrings(left, right));
   if (notFound.length > 0) {
-    const perKind = await Promise.all(
-      Object.keys(target.graph.edges).map(
-        (kind) => edgeCollection(edgesApi, kind).getByIds(notFound, INCLUDE_TOMBSTONES)
-      )
-    );
     const crossKindById = /* @__PURE__ */ new Map();
-    for (const rows of perKind) {
+    for (const kind of Object.keys(target.graph.edges)) {
+      const rows = await edgeCollection(edgesApi, kind).getByIds(
+        notFound,
+        INCLUDE_TOMBSTONES
+      );
       for (const [index, id] of notFound.entries()) {
         const row = rows[index];
         if (row !== void 0 && !crossKindById.has(id)) {
@@ -3725,20 +3813,77 @@ async function validateIncrementalEdgeWrites(target, edgesApi, plan) {
     }
   }
 }
-async function commitIncrementalPlan(target, plan) {
+async function collectBaseMatchKeys(lookupStore, guard) {
+  const matched = /* @__PURE__ */ new Set();
+  for (const [kind, stagedNodes] of guard.stagedNewByKind) {
+    const resolveConfig = guard.options.resolve[kind];
+    if (resolveConfig === void 0) {
+      continue;
+    }
+    const collection = lookupStore.nodes[kind];
+    if (collection === void 0 || stagedNodes.length === 0) {
+      continue;
+    }
+    const items = stagedNodes.map((staged) => ({ props: staged.node.props }));
+    for (const constraint of uniqueConstraintsFor(
+      guard.introspectionKinds,
+      kind
+    )) {
+      const matches = await collection.bulkFindByConstraint(
+        constraint.name,
+        items
+      );
+      for (const base of matches) {
+        if (base !== void 0) {
+          matched.add(mergeKeyOf(base));
+        }
+      }
+    }
+    if (resolveConfig.blockIndex !== void 0) {
+      const matchesByItem = await collection.bulkFindByIndex(
+        resolveConfig.blockIndex,
+        items
+      );
+      for (const perItem of matchesByItem) {
+        for (const base of perItem) {
+          matched.add(mergeKeyOf(base));
+        }
+      }
+    }
+  }
+  return matched;
+}
+async function assertBaseResolutionStable(lookupStore, guard) {
+  const liveKeys = await collectBaseMatchKeys(lookupStore, guard);
+  const appeared = [...liveKeys].filter((key) => !guard.plannedBaseMatchKeys.has(key)).sort((left, right) => compareMergeKeys(left, right));
+  if (appeared.length === 0) {
+    return;
+  }
+  throw new BaseVersionMismatchError(
+    `mergeIncremental() resolved its branch additions against the target as of planning, but ${appeared.length} committed row(s) matching a branch addition's identity key (a unique constraint or block index) were inserted before the commit transaction. Committing the plan would create duplicate entities the base-source resolution would otherwise have collapsed.`,
+    {
+      details: { appeared },
+      suggestion: "Re-run mergeIncremental(); the re-planned merge resolves the branch additions against the now-committed rows."
+    }
+  );
+}
+async function commitIncrementalPlan(target, plan, guard) {
   if (!target.backend.capabilities.transactions) {
     throw new MergeError(
       "mergeIncremental() requires a transaction-capable target backend. Incremental writes must preflight existing rows and commit atomically; non-transactional fallback would allow partial graph writes.",
       { details: { capability: "transactions" } }
     );
   }
-  return target.transaction(async (tx) => {
-    const nodesApi = tx.nodes;
-    const edgesApi = tx.edges;
-    await validateIncrementalNodeWrites(target, nodesApi, plan);
-    await validateIncrementalEdgeWrites(target, edgesApi, plan);
-    return applyMergePlan(plan, nodesApi, edgesApi);
-  });
+  return withTxConflictRetry(
+    () => target.transaction(async (tx) => {
+      const nodesApi = tx.nodes;
+      const edgesApi = tx.edges;
+      await assertBaseResolutionStable(tx, guard);
+      await validateIncrementalNodeWrites(target, nodesApi, plan);
+      await validateIncrementalEdgeWrites(target, edgesApi, plan);
+      return applyMergePlan(plan, nodesApi, edgesApi);
+    }, MERGE_COMMIT_TX_OPTIONS)
+  );
 }
 async function mergeIncremental(args) {
   const { forkPoint, target, branches } = args;