@nicia-ai/typegraph 0.31.0 → 0.32.0

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

@@ -1,10 +1,10 @@
-import { G as GraphDef, t as NodeKinds, u as GetNodeType } from '../manager-Np7VVSlE.cjs';
-import { S as Store, N as Node, U as UniqueIntrospection } from '../store-DuCbdqsh.cjs';
+import { G as GraphDef, t as NodeKinds, u as GetNodeType } from '../manager-aVgxbGt-.cjs';
+import { S as Store, N as Node, U as UniqueIntrospection } from '../store-view-lTcb_cnp.cjs';
 import { d as NodeId, N as NodeType, e as EdgeId, J as JsonValue, f as KindAnnotations, g as EdgeType, D as DeleteBehavior, T as TemporalMode, h as GraphExtensionVersion, i as ExtensionNodeDef, j as ExtensionEdgeDef, k as ExtensionOntologyRelation, l as ExtensionIndex } from '../extension-types-D1k0inWU.cjs';
 import { T as TypeGraphError } from '../index-C8sSTErx.cjs';
 import { R as Result } from '../result-DWo6mUVz.cjs';
 export { i as isErr, a as isOk, u as unwrap } from '../result-DWo6mUVz.cjs';
-import { G as GraphBackend, M as MetaEdge, I as IndexDeclaration } from '../types-C1CYxWrL.cjs';
+import { G as GraphBackend, M as MetaEdge, I as IndexDeclaration } from '../types-Dvmn-eal.cjs';
 import { z } from 'zod';
 import 'drizzle-orm';
 import '../materialize-indexes-DEYkU-wr.cjs';

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

@@ -1,10 +1,10 @@
-import { G as GraphDef, t as NodeKinds, u as GetNodeType } from '../manager-By-WEd8M.js';
-import { S as Store, N as Node, U as UniqueIntrospection } from '../store-MloRPwb9.js';
+import { G as GraphDef, t as NodeKinds, u as GetNodeType } from '../manager-8htmuGr-.js';
+import { S as Store, N as Node, U as UniqueIntrospection } from '../store-view-pBOUrQte.js';
 import { d as NodeId, N as NodeType, e as EdgeId, J as JsonValue, f as KindAnnotations, g as EdgeType, D as DeleteBehavior, T as TemporalMode, h as GraphExtensionVersion, i as ExtensionNodeDef, j as ExtensionEdgeDef, k as ExtensionOntologyRelation, l as ExtensionIndex } from '../extension-types-D1k0inWU.js';
 import { T as TypeGraphError } from '../index-BEK0VtNB.js';
 import { R as Result } from '../result-DWo6mUVz.js';
 export { i as isErr, a as isOk, u as unwrap } from '../result-DWo6mUVz.js';
-import { G as GraphBackend, M as MetaEdge, I as IndexDeclaration } from '../types-BKQljXom.js';
+import { G as GraphBackend, M as MetaEdge, I as IndexDeclaration } from '../types-Dk8r09KY.js';
 import { z } from 'zod';
 import 'drizzle-orm';
 import '../materialize-indexes-CAGhqPHQ.js';

package/dist/graph-merge/index.js

@@ -1,9 +1,9 @@
-import { createStoreWithSchema, generateId, computeUniqueKey } from '../chunk-UIFEEPME.js';
+import { createStoreWithSchema, generateId, computeUniqueKey } from '../chunk-WNORITK6.js';
 import '../chunk-3EUKJEQ3.js';
-import { exportGraph, importGraph } from '../chunk-THX25XW6.js';
-import { defineNode, computeSchemaHash, serializeSchema } from '../chunk-XKJQQQVR.js';
-import { getNodeKinds, getEdgeKinds, defineGraph } from '../chunk-MAQJYNJR.js';
-import '../chunk-2ZY4K43M.js';
+import { exportGraph, importGraph } from '../chunk-HFBRAOF7.js';
+import { defineNode, computeSchemaHash, serializeSchema } from '../chunk-2BVHPOIG.js';
+import { getNodeKinds, getEdgeKinds, defineGraph } from '../chunk-W4ZX2GCP.js';
+import '../chunk-PIHXFF73.js';
 import '../chunk-IJORSAC3.js';
 import '../chunk-MXE2U3EX.js';
 import '../chunk-454I6GDF.js';
@@ -11,7 +11,7 @@ import { ok, err, isErr, computeTransitiveClosure, isReachable } from '../chunk-
 export { isErr, isOk, unwrap } from '../chunk-YCV72E6L.js';
 import '../chunk-SAJSMR2B.js';
 import { sortedReplacer } from '../chunk-M6OC455F.js';
-import '../chunk-2HZGWCB4.js';
+import '../chunk-C4C4Q7A6.js';
 import { sha256Hex } from '../chunk-2YMGNYXY.js';
 import { TypeGraphError } from '../chunk-TQOYM4LN.js';
 import '../chunk-K5P5OZXS.js';
@@ -317,10 +317,7 @@ function byDigestEntry(left, right) {
   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;
+async function computeContentComponent(backend, graphId, graph) {
   const nodeKinds = getNodeKinds(graph);
   const edgeKinds = getEdgeKinds(graph);
   const nodeDigest = [];
@@ -368,12 +365,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 = {
@@ -2506,6 +2507,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) {
@@ -3225,20 +3268,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];
@@ -3276,7 +3347,7 @@ async function validateBaseVersions(target, branches) {
       );
     }
   }
-  return ok();
+  return ok(targetVersion);
 }
 function tryNormalize(optionsInput) {
   try {
@@ -3285,7 +3356,7 @@ function tryNormalize(optionsInput) {
     return 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) {
@@ -3356,7 +3427,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;
@@ -3417,7 +3497,15 @@ async function merge(store, branches, optionsInput = {}) {
   if (isErr(precondition)) {
     return 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);
@@ -3650,13 +3738,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)) {
@@ -3724,20 +3811,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;