@nicia-ai/typegraph 0.33.0 → 0.35.0

package/dist/graph-merge/index.js

@@ -1,21 +1,29 @@
-import { createStoreWithSchema, generateId, computeUniqueKey } from '../chunk-WLP6TKFB.js';
-import '../chunk-3EUKJEQ3.js';
-import { exportGraph, importGraph } from '../chunk-SPT5JMME.js';
-import { defineNode, computeSchemaHash, serializeSchema } from '../chunk-XVUJY72M.js';
-import { getNodeKinds, getEdgeKinds, defineGraph } from '../chunk-QBYTJSAY.js';
-import '../chunk-PIHXFF73.js';
-import '../chunk-6NRFUHMS.js';
-import '../chunk-IZ4PCL47.js';
-import '../chunk-454I6GDF.js';
-import { ok, err, isErr, computeTransitiveClosure, isReachable } from '../chunk-YCV72E6L.js';
-export { isErr, isOk, unwrap } from '../chunk-YCV72E6L.js';
-import '../chunk-PYD3UCDU.js';
-import { sortedReplacer } from '../chunk-GYVBEZAO.js';
-import '../chunk-C4C4Q7A6.js';
-import { sha256Hex } from '../chunk-2YMGNYXY.js';
-import '../chunk-XLUNB2TZ.js';
-import { TypeGraphError } from '../chunk-TQOYM4LN.js';
-import '../chunk-K5P5OZXS.js';
+import { createStoreWithSchema } from '../chunk-UES55P7G.js';
+import '../chunk-55MZDDZV.js';
+import { importGraphStream, exportGraphStream } from '../chunk-KMI7LYAF.js';
+import '../chunk-QNKSQTKQ.js';
+import { defineNode, computeSchemaHash, serializeSchema } from '../chunk-K3PPLHY7.js';
+import { sortedReplacer } from '../chunk-UR7W5YQK.js';
+import { getNodeKinds, getEdgeKinds, defineGraph } from '../chunk-QWEUYILR.js';
+import '../chunk-UZV3AZKF.js';
+import '../chunk-OR5ZA5WP.js';
+import { sha256Hex } from '../chunk-W63OVYY4.js';
+import '../chunk-FPIZFYHE.js';
+import '../chunk-5SEGFTZX.js';
+import { ok, err, isErr, computeTransitiveClosure, isReachable } from '../chunk-QOTI55H7.js';
+export { isErr, isOk, unwrap } from '../chunk-QOTI55H7.js';
+import '../chunk-RGPG7EOJ.js';
+import { compareStrings } from '../chunk-BYPOGQWK.js';
+import { generateId, computeUniqueKey, lockRecordedGraphWrite, readRevisionOrigin, readRecordedClock } from '../chunk-CZQ3FO2Q.js';
+import '../chunk-UT3S4SEN.js';
+import '../chunk-JBTOYDMN.js';
+import '../chunk-I7ZUZKFD.js';
+import '../chunk-OHMP6N2J.js';
+import '../chunk-KBGQIPRQ.js';
+import '../chunk-SNXVDZAJ.js';
+import '../chunk-ITE4IXAK.js';
+import { TypeGraphError } from '../chunk-MP2JQKSG.js';
+import '../chunk-G6Q5UM7U.js';
 import { z } from 'zod';
 
 // src/graph-merge/canonical-props.ts
@@ -25,12 +33,26 @@ function canonicalizeProps(props) {
 function canonicalValueKey(value) {
   return JSON.stringify(value, sortedReplacer);
 }
+function edgeStateSignature(edge) {
+  return JSON.stringify([
+    edge.fromKind,
+    edge.fromId,
+    edge.toKind,
+    edge.toId,
+    edge.live,
+    canonicalizeProps(edge.props)
+  ]);
+}
 function parseRowProps(props) {
   let parsed;
-  try {
-    parsed = JSON.parse(props);
-  } catch {
-    return {};
+  if (typeof props === "string") {
+    try {
+      parsed = JSON.parse(props);
+    } catch {
+      return {};
+    }
+  } else {
+    parsed = props;
   }
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
     return {};
@@ -48,9 +70,6 @@ function mergeKey(kind, id) {
   }
   return `${kind}${SEPARATOR}${id}`;
 }
-function compareStrings(left, right) {
-  return left < right ? -1 : left > right ? 1 : 0;
-}
 function mergeKeyOf(node) {
   return mergeKey(node.kind, node.id);
 }
@@ -77,7 +96,7 @@ function compareMergeKeys(left, right) {
 var ENUMERATION_PAGE_SIZE = 1e3;
 async function enumerateAllNodes(backend, graphId, kind) {
   const collected = [];
-  let after = void 0;
+  let after;
   for (; ; ) {
     const page = await backend.findNodesByKind({
       graphId,
@@ -99,7 +118,7 @@ async function enumerateAllNodes(backend, graphId, kind) {
 }
 async function enumerateAllEdges(backend, graphId, kind) {
   const collected = [];
-  let after = void 0;
+  let after;
   for (; ; ) {
     const page = await backend.findEdgesByKind({
       graphId,
@@ -226,13 +245,14 @@ function diffEdgeKind(kind, baseRows, forkRows) {
 function byId(left, right) {
   return compareStrings(left.id, right.id);
 }
-async function diffAgainstBase(baseStore, forkStore) {
+async function diffAgainstBase(baseStore, forkStore, captureForkState = true) {
   const graph = baseStore.graph;
   const nodeKinds = getNodeKinds(graph);
   const edgeKinds = getEdgeKinds(graph);
   const newNodes = [];
   const modifiedNodes = [];
   const deletedNodes = [];
+  const forkNodeVersions = /* @__PURE__ */ new Map();
   for (const kind of nodeKinds) {
     const baseRows = await enumerateAllNodes(
       baseStore.backend,
@@ -244,6 +264,11 @@ async function diffAgainstBase(baseStore, forkStore) {
       forkStore.graphId,
       kind
     );
+    if (captureForkState) {
+      for (const row of forkRows) {
+        forkNodeVersions.set(mergeKey(kind, row.id), row.version);
+      }
+    }
     const delta = diffNodeKind(kind, baseRows, forkRows);
     for (const entry of delta.new) {
       newNodes.push(entry);
@@ -258,6 +283,7 @@ async function diffAgainstBase(baseStore, forkStore) {
   const newEdges = [];
   const modifiedEdges = [];
   const deletedEdges = [];
+  const forkEdgeSignatures = /* @__PURE__ */ new Map();
   for (const kind of edgeKinds) {
     const baseRows = await enumerateAllEdges(
       baseStore.backend,
@@ -269,6 +295,21 @@ async function diffAgainstBase(baseStore, forkStore) {
       forkStore.graphId,
       kind
     );
+    if (captureForkState) {
+      for (const row of forkRows) {
+        forkEdgeSignatures.set(
+          mergeKey(kind, row.id),
+          edgeStateSignature({
+            fromKind: row.from_kind,
+            fromId: row.from_id,
+            toKind: row.to_kind,
+            toId: row.to_id,
+            live: isLive(row),
+            props: parseRowProps(row.props)
+          })
+        );
+      }
+    }
     const delta = diffEdgeKind(kind, baseRows, forkRows);
     for (const entry of delta.new) {
       newEdges.push(entry);
@@ -290,7 +331,9 @@ async function diffAgainstBase(baseStore, forkStore) {
       new: newEdges.sort((left, right) => byId(left, right)),
       modified: modifiedEdges.sort((left, right) => byId(left, right)),
       deleted: deletedEdges.sort((left, right) => byId(left, right))
-    }
+    },
+    forkNodeVersions,
+    forkEdgeSignatures
   };
 }
 
@@ -304,6 +347,9 @@ function asBaseVersion(value) {
 
 // src/graph-merge/base-version.ts
 var TOKEN_SEPARATOR = "\0";
+var REVISION_COMPONENT_PREFIX = "revision:";
+var REVISION_COMPONENT_SEPARATOR = ":";
+var INITIAL_REVISION = "initial";
 var FALLBACK_SCHEMA_VERSION = 1;
 async function readActiveSchemaVersion(backend, graphId) {
   const active = await backend.getActiveSchema(graphId);
@@ -364,6 +410,16 @@ async function computeContentComponent(backend, graphId, graph) {
   );
 }
 async function computeBaseVersion(store) {
+  if (store.revisionTrackingEnabled) {
+    const [schemaComponent2, origin, revision] = await Promise.all([
+      computeSchemaComponent(store),
+      store.revisionOriginNow(),
+      store.revisionNow()
+    ]);
+    return asBaseVersion(
+      `${schemaComponent2}${TOKEN_SEPARATOR}${revisionComponent(origin, revision)}`
+    );
+  }
   const [schemaComponent, contentComponent] = await Promise.all([
     computeSchemaComponent(store),
     computeContentComponent(store.backend, store.graphId, store.graph)
@@ -372,6 +428,30 @@ async function computeBaseVersion(store) {
     `${schemaComponent}${TOKEN_SEPARATOR}${contentComponent}`
   );
 }
+function revisionComponent(origin, revision) {
+  return `${REVISION_COMPONENT_PREFIX}${origin}${REVISION_COMPONENT_SEPARATOR}${revision ?? INITIAL_REVISION}`;
+}
+function hasRevisionAnchor(version) {
+  return contentComponentOf(version).startsWith(REVISION_COMPONENT_PREFIX);
+}
+function revisionAnchorOf(version) {
+  const revision = revisionPartsOf(version)?.revision;
+  return revision === void 0 || revision === INITIAL_REVISION ? void 0 : revision;
+}
+function revisionOriginOf(version) {
+  return revisionPartsOf(version)?.origin;
+}
+function revisionPartsOf(version) {
+  const component = contentComponentOf(version);
+  if (!component.startsWith(REVISION_COMPONENT_PREFIX)) return void 0;
+  const encoded = component.slice(REVISION_COMPONENT_PREFIX.length);
+  const separator = encoded.indexOf(REVISION_COMPONENT_SEPARATOR);
+  if (separator <= 0 || separator === encoded.length - 1) return void 0;
+  return {
+    origin: encoded.slice(0, separator),
+    revision: encoded.slice(separator + 1)
+  };
+}
 function contentComponentOf(version) {
   const separatorIndex = version.indexOf(TOKEN_SEPARATOR);
   return separatorIndex === -1 ? version : version.slice(separatorIndex + 1);
@@ -446,22 +526,32 @@ var CLONE_IMPORT_BATCH_SIZE = 1e3;
 function cloneWorkingCopyStrategy(makeBackend) {
   return {
     create: async (baseStore) => {
-      const data = await exportGraph(baseStore, {
-        includeMeta: true,
-        includeDeleted: false
-      });
       const backend = await makeBackend();
       try {
         const [freshStore] = await createStoreWithSchema(
           baseStore.graph,
-          backend
+          backend,
+          {
+            // Keep descendants branchable with the same O(1) anchor contract,
+            // but do not copy recorded-time history into the disposable fork.
+            revisionTracking: baseStore.revisionTrackingEnabled
+          }
+        );
+        const result = await importGraphStream(
+          freshStore,
+          exportGraphStream(baseStore, {
+            includeMeta: true,
+            includeTemporal: true,
+            includeDeleted: false,
+            batchSize: CLONE_IMPORT_BATCH_SIZE
+          }),
+          {
+            onConflict: "error",
+            onUnknownProperty: "error",
+            validateReferences: true,
+            batchSize: CLONE_IMPORT_BATCH_SIZE
+          }
         );
-        const result = await importGraph(freshStore, data, {
-          onConflict: "error",
-          onUnknownProperty: "error",
-          validateReferences: true,
-          batchSize: CLONE_IMPORT_BATCH_SIZE
-        });
         if (!result.success) {
           throw new BranchError(
             "Clone import failed: the working copy could not be seeded from the base store. The backend returned by makeBackend() must be empty.",
@@ -859,6 +949,7 @@ 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) {
@@ -2461,16 +2552,26 @@ function groupByKind(items) {
   }
   return ordered;
 }
-async function stageBranches(baseStore, branches) {
+async function stageBranches(baseStore, branches, captureTargetStateFor) {
   const newNodes = [];
   const modifiedNodes = [];
   const deletedNodes = [];
   const newEdges = [];
   const modifiedEdges = [];
   const deletedEdges = [];
+  let targetNodeVersions = /* @__PURE__ */ new Map();
+  let targetEdgeSignatures = /* @__PURE__ */ new Map();
   for (const branch2 of branches) {
-    const diff = await diffAgainstBase(baseStore, branch2.store);
     const branchId = branch2.id;
+    const diff = await diffAgainstBase(
+      baseStore,
+      branch2.store,
+      branchId === captureTargetStateFor
+    );
+    if (branchId === captureTargetStateFor) {
+      targetNodeVersions = diff.forkNodeVersions;
+      targetEdgeSignatures = diff.forkEdgeSignatures;
+    }
     for (const node of diff.nodes.new) {
       newNodes.push({ branchId, node, kind: node.kind, id: node.id });
     }
@@ -2504,7 +2605,9 @@ async function stageBranches(baseStore, branches) {
     ),
     deletedEdges: [...deletedEdges].sort(
       (left, right) => compareByKindIdBranch(left, right)
-    )
+    ),
+    targetNodeVersions,
+    targetEdgeSignatures
   };
 }
 
@@ -3286,13 +3389,50 @@ async function commitPlan(target, plan, expectedBaseVersion) {
         tx.nodes,
         tx.edges
       );
-    }, MERGE_COMMIT_TX_OPTIONS)
+    }, mergeCommitTransactionOptions(target))
   );
 }
 var MERGE_COMMIT_TX_OPTIONS = {
   isolationLevel: "serializable"
 };
+function mergeCommitTransactionOptions(target) {
+  return target.historyEnabled ? void 0 : MERGE_COMMIT_TX_OPTIONS;
+}
 async function assertTargetUnchanged(txBackend, target, expectedBaseVersion) {
+  if (hasRevisionAnchor(expectedBaseVersion)) {
+    await lockRecordedGraphWrite(txBackend, target.graphId);
+    const expectedOrigin = revisionOriginOf(expectedBaseVersion);
+    const liveOrigin = await readRevisionOrigin(
+      txBackend,
+      target.revisionSchema,
+      target.graphId
+    );
+    if (liveOrigin !== expectedOrigin) {
+      throw new BaseVersionMismatchError(
+        "The merge branch was forked from a different revision-tracked store; the resolved plan was not applied.",
+        {
+          details: { expectedOrigin, liveOrigin },
+          suggestion: "Merge the branch back into its original base store, or fork a new branch from this target."
+        }
+      );
+    }
+    const liveRevision = await readRecordedClock(
+      txBackend,
+      target.revisionSchema,
+      target.graphId
+    );
+    const expectedRevision = revisionAnchorOf(expectedBaseVersion);
+    if (liveRevision !== expectedRevision) {
+      throw new BaseVersionMismatchError(
+        "The merge target was modified between the revision-anchor check and the commit transaction; the resolved plan was not applied.",
+        {
+          details: { expectedRevision, liveRevision },
+          suggestion: "Re-run the merge (and re-branch if the divergence is real), or route all graph writes through the revision-tracked Store."
+        }
+      );
+    }
+    return;
+  }
   const liveContent = await computeContentComponent(
     txBackend,
     target.graphId,
@@ -3381,8 +3521,8 @@ async function resolveMerge(store, target, branches, options, useBaseSources, in
     }
   }
   try {
-    const staging = await stageBranches(store, branches);
     const preferredBranchId = incremental?.targetBranchId;
+    const staging = await stageBranches(store, branches, preferredBranchId);
     const branchIds = branches.map((branch2) => branch2.id);
     const branchOrder = preferredBranchId === void 0 ? options.branchOrder ?? [] : [
       preferredBranchId,
@@ -3436,7 +3576,9 @@ async function resolveMerge(store, target, branches, options, useBaseSources, in
       // 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];
@@ -3866,6 +4008,99 @@ async function assertBaseResolutionStable(lookupStore, guard) {
     }
   );
 }
+function bucketInheritedRefsByKind(refs, identities) {
+  const seen = /* @__PURE__ */ new Set();
+  const idsByKind = /* @__PURE__ */ new Map();
+  for (const ref of refs) {
+    const identity = mergeKey(ref.kind, ref.id);
+    if (!identities.has(identity) || seen.has(identity)) {
+      continue;
+    }
+    seen.add(identity);
+    const bucket = idsByKind.get(ref.kind) ?? [];
+    bucket.push(ref.id);
+    idsByKind.set(ref.kind, bucket);
+  }
+  return idsByKind;
+}
+async function assertInheritedUnchanged(args) {
+  if (args.expected.size === 0) {
+    return;
+  }
+  const idsByKind = bucketInheritedRefsByKind(args.refs, args.expected);
+  for (const [kind, ids] of idsByKind) {
+    const rows = await args.fetchRows(kind, ids);
+    for (const [index, id] of ids.entries()) {
+      const expected = args.expected.get(mergeKey(kind, id));
+      const current = args.deriveValue(rows[index]);
+      if (current === expected) {
+        continue;
+      }
+      throw args.buildError(id, kind, expected, current);
+    }
+  }
+}
+async function assertInheritedTargetUnchanged(nodesApi, edgesApi, guard, plan) {
+  await Promise.all([
+    assertInheritedNodesUnchanged(nodesApi, guard, plan),
+    assertInheritedEdgesUnchanged(edgesApi, guard, plan)
+  ]);
+}
+async function assertInheritedNodesUnchanged(nodesApi, guard, plan) {
+  const nodeRefs = plannedNodeWrites(plan).map(
+    (write) => ({ kind: write.kind, id: write.id })
+  );
+  for (const [identity, kind] of plan.nodeDeletions) {
+    nodeRefs.push({ kind, id: idOf(identity) });
+  }
+  await assertInheritedUnchanged({
+    refs: nodeRefs,
+    expected: guard.targetNodeVersions,
+    fetchRows: (kind, ids) => nodeCollection(nodesApi, kind).getByIds(ids, INCLUDE_TOMBSTONES),
+    deriveValue: (row) => row?.meta.version,
+    buildError: (id, kind, expected, current) => new BaseVersionMismatchError(
+      `mergeIncremental() observed committed node "${id}" (kind "${kind}") at version ${expected} while planning, but it changed before the commit transaction; the resolved plan no longer describes the live target and was not applied.`,
+      {
+        details: {
+          id,
+          kind,
+          expectedVersion: expected,
+          currentVersion: current
+        },
+        suggestion: "Re-run mergeIncremental(); the re-planned merge resolves the inherited modifications against the now-committed rows."
+      }
+    )
+  });
+}
+async function assertInheritedEdgesUnchanged(edgesApi, guard, plan) {
+  const edgeRefs = plan.mergedEdges.map((edge) => ({
+    kind: edge.kind,
+    id: edge.id
+  }));
+  for (const [identity, kind] of plan.edgeDeletions) {
+    edgeRefs.push({ kind, id: idOf(identity) });
+  }
+  await assertInheritedUnchanged({
+    refs: edgeRefs,
+    expected: guard.targetEdgeSignatures,
+    fetchRows: (kind, ids) => edgeCollection(edgesApi, kind).getByIds(ids, INCLUDE_TOMBSTONES),
+    deriveValue: (row) => row === void 0 ? void 0 : edgeStateSignature({
+      fromKind: row.fromKind,
+      fromId: row.fromId,
+      toKind: row.toKind,
+      toId: row.toId,
+      live: row.meta.deletedAt === void 0,
+      props: edgeProps(row)
+    }),
+    buildError: (id, kind) => new BaseVersionMismatchError(
+      `mergeIncremental() observed committed edge "${id}" (kind "${kind}") while planning, but its endpoints, liveness, or props changed before the commit transaction; the resolved plan no longer describes the live target and was not applied.`,
+      {
+        details: { id, kind },
+        suggestion: "Re-run mergeIncremental(); the re-planned merge resolves the inherited modifications against the now-committed rows."
+      }
+    )
+  });
+}
 async function commitIncrementalPlan(target, plan, guard) {
   if (!target.backend.capabilities.transactions) {
     throw new MergeError(
@@ -3875,13 +4110,17 @@ async function commitIncrementalPlan(target, plan, guard) {
   }
   return withTxConflictRetry(
     () => target.transaction(async (tx) => {
+      if (target.revisionTrackingEnabled) {
+        await lockRecordedGraphWrite(tx.backend, target.graphId);
+      }
       const nodesApi = tx.nodes;
       const edgesApi = tx.edges;
       await assertBaseResolutionStable(tx, guard);
+      await assertInheritedTargetUnchanged(nodesApi, edgesApi, guard, plan);
       await validateIncrementalNodeWrites(target, nodesApi, plan);
       await validateIncrementalEdgeWrites(target, edgesApi, plan);
       return applyMergePlan(plan, nodesApi, edgesApi);
-    }, MERGE_COMMIT_TX_OPTIONS)
+    }, mergeCommitTransactionOptions(target))
   );
 }
 async function mergeIncremental(args) {