@nicia-ai/typegraph 0.66.1 → 0.67.1

package/dist/graph-merge/index.js

@@ -1,4 +1,4 @@
-import { NODE_TEMPORAL_READ_NAMES, CURRENT_ONLY_READ_NAMES, createStoreWithSchema, createStore, IDENTITY_READ_NAMES, EDGE_TEMPORAL_READ_NAMES } from '../chunk-TR7QTODF.js';
+import { NODE_TEMPORAL_READ_NAMES, CURRENT_ONLY_READ_NAMES, createStoreWithSchema, createStore, IDENTITY_READ_NAMES, EDGE_TEMPORAL_READ_NAMES } from '../chunk-55DGFZYC.js';
 import '../chunk-OF63ZHSD.js';
 import { requireLineage } from '../chunk-NSOGBYYS.js';
 import '../chunk-XELE7ZOX.js';
@@ -9,7 +9,7 @@ import '../chunk-6ECNYQDW.js';
 import '../chunk-CDKNGCE7.js';
 import '../chunk-N535PWMA.js';
 import '../chunk-UFKYMQJ5.js';
-import { computeSchemaHash, serializeSchema } from '../chunk-WB55URNM.js';
+import { computeSchemaHash, serializeSchema, getGraphDefinitionHash } from '../chunk-6CKSTY2D.js';
 import '../chunk-RFMSZ7CF.js';
 import { defineNode } from '../chunk-Q2SPDS3B.js';
 import { normalizeIdentityPair, identityReferenceKey, identityValidityWindowsOverlap, identityAssertionSemanticKey } from '../chunk-SYXTWPX6.js';
@@ -2083,6 +2083,14 @@ async function lineageDeltaSinceAnchor(baseStore, base) {
 
 // src/graph-merge/working-copy.ts
 var CLONE_IMPORT_BATCH_SIZE = 1e3;
+async function assertWorkingCopyMatchesBase(workingCopy, base) {
+  const workingCopyVersion = await computeBaseVersion(workingCopy);
+  if (workingCopyVersion === base) return;
+  throw new BranchError(
+    "Working copy does not match its base: computeBaseVersion disagrees between the host-created store and the base store it was forked from. The host may have forked a different revision or the source may have advanced while the fork was being allocated.",
+    { details: { workingCopyVersion, baseVersion: base } }
+  );
+}
 function cloneWorkingCopyStrategy(makeBackend) {
   return cloneWorkingCopyWithGraphStrategy(
     makeBackend,
@@ -2235,13 +2243,7 @@ function forkedWorkingCopyStrategy(options) {
           );
         }
         const forkStore = createStore(baseStore.graph, backend, forkOptions);
-        const forkVersion = await computeBaseVersion(forkStore);
-        if (forkVersion !== base) {
-          throw new BranchError(
-            "Fork does not match its base: computeBaseVersion disagrees between the forked store and the base store it was forked from. This fence proves base-token equality (schema plus a revision anchor, or a live-content fingerprint) at the instant the fork was taken, not byte-for-byte physical identity \u2014 a working-copy fork is trusted to provide that.",
-            { details: { forkVersion, baseVersion: base } }
-          );
-        }
+        await assertWorkingCopyMatchesBase(forkStore, base);
         return forkStore;
       } catch (error) {
         try {
@@ -2304,11 +2306,7 @@ async function branch(baseStore, makeBackend, options, strategy) {
 }
 async function captureBranchForkState(store) {
   try {
-    const schemaRow = await storeBackend(store).getActiveSchema(store.graphId);
-    const schemaAnchor = schemaRow === void 0 ? void 0 : { version: schemaRow.version, hash: schemaRow.schema_hash };
-    const lineage = resolveLineage(store);
-    const forkRevision = lineage === void 0 ? void 0 : await lineage.revision(storeBackend(store));
-    return { schemaAnchor, forkRevision };
+    return await readBranchForkState(store);
   } catch (error) {
     try {
       await storeBackend(store).close();
@@ -2317,6 +2315,13 @@ async function captureBranchForkState(store) {
     throw error;
   }
 }
+async function readBranchForkState(store) {
+  const schemaRow = await storeBackend(store).getActiveSchema(store.graphId);
+  const schemaAnchor = schemaRow === void 0 ? void 0 : { version: schemaRow.version, hash: schemaRow.schema_hash };
+  const lineage = resolveLineage(store);
+  const forkRevision = lineage === void 0 ? void 0 : await lineage.revision(storeBackend(store));
+  return { schemaAnchor, forkRevision };
+}
 
 // src/graph-merge/evolution-target.ts
 function evolutionPlanningTarget(store, plan) {
@@ -10262,6 +10267,471 @@ function asReviewError(error) {
   );
 }
 
+// src/graph-merge/durable-branch.ts
+async function branchDurable(baseStore, strategy, options) {
+  let base;
+  let id;
+  try {
+    base = await computeBaseVersion(baseStore);
+    id = options?.id ?? asBranchId(generateId());
+  } catch (error) {
+    return err(
+      new BranchError(
+        "Failed to stamp the durable branch base version for the base store.",
+        { cause: error }
+      )
+    );
+  }
+  let created;
+  try {
+    created = await strategy.create(baseStore, base, id);
+  } catch (error) {
+    return err(
+      new BranchError(
+        "Failed to create durable working-copy branch of base store",
+        { cause: error }
+      )
+    );
+  }
+  let forkState;
+  let definitionHash;
+  try {
+    await assertDurableWorkingCopyMatchesBase(baseStore, created.store, base);
+    forkState = await readBranchForkState(created.store);
+    definitionHash = await getGraphDefinitionHash(created.store.graph);
+  } catch (error) {
+    return err(await abandonAllocation(strategy, created, id, error));
+  }
+  const origin = {
+    graphId: created.store.graphId,
+    definitionHash,
+    branchId: id,
+    base,
+    schemaAnchor: forkState.schemaAnchor,
+    forkRevision: forkState.forkRevision
+  };
+  try {
+    await strategy.seal(created.descriptor, origin);
+  } catch (error) {
+    return err(await abandonAllocation(strategy, created, id, error));
+  }
+  const branch2 = {
+    id,
+    base,
+    store: created.store,
+    close: coalescedDurableClose(created.store, created.access),
+    ...forkState.schemaAnchor === void 0 ? { schemaAnchor: void 0 } : { schemaAnchor: forkState.schemaAnchor },
+    ...forkState.forkRevision === void 0 ? {} : { forkRevision: forkState.forkRevision }
+  };
+  const descriptor = {
+    kind: strategy.type,
+    version: strategy.version,
+    graphId: created.store.graphId,
+    definitionHash,
+    branchId: id,
+    base,
+    store: created.descriptor,
+    ...forkState.schemaAnchor === void 0 ? { schemaAnchor: void 0 } : { schemaAnchor: forkState.schemaAnchor },
+    ...forkState.forkRevision === void 0 ? {} : { forkRevision: forkState.forkRevision }
+  };
+  return ok({ branch: branch2, descriptor });
+}
+async function assertDurableWorkingCopyMatchesBase(baseStore, workingCopy, base) {
+  const sourceVersionBeforeDiff = await computeBaseVersion(baseStore);
+  if (sourceVersionBeforeDiff !== base) {
+    throw new BranchError(
+      "Base store changed while the durable working copy was being allocated.",
+      {
+        details: {
+          baseVersion: base,
+          liveBaseVersion: sourceVersionBeforeDiff
+        }
+      }
+    );
+  }
+  if (workingCopy.graphId !== baseStore.graphId) {
+    throw new BranchError(
+      "Durable working copy belongs to a different graph than its base store.",
+      {
+        details: {
+          expectedGraphId: baseStore.graphId,
+          receivedGraphId: workingCopy.graphId
+        }
+      }
+    );
+  }
+  const workingCopyVersion = await computeBaseVersion(workingCopy);
+  if (workingCopyVersion === base) return;
+  if (schemaComponentOf(workingCopyVersion) !== schemaComponentOf(base)) {
+    throw new BranchError(
+      "Durable working copy schema does not match its stamped base schema.",
+      {
+        details: {
+          baseSchema: schemaComponentOf(base),
+          workingCopySchema: schemaComponentOf(workingCopyVersion)
+        }
+      }
+    );
+  }
+  const diff = await diffAgainstBase(baseStore, workingCopy, false);
+  const sourceVersionAfterDiff = await computeBaseVersion(baseStore);
+  if (sourceVersionAfterDiff !== base) {
+    throw new BranchError(
+      "Base store changed while the durable working copy was being verified.",
+      {
+        details: {
+          baseVersion: base,
+          liveBaseVersion: sourceVersionAfterDiff
+        }
+      }
+    );
+  }
+  const changed = diff.nodes.new.length > 0 || diff.nodes.modified.length > 0 || diff.nodes.deleted.length > 0 || diff.nodes.windowed.length > 0 || diff.edges.new.length > 0 || diff.edges.modified.length > 0 || diff.edges.deleted.length > 0 || diff.edges.windowed.length > 0 || diff.identity.new.length > 0 || diff.identity.retracted.length > 0;
+  if (!changed) return;
+  throw new BranchError(
+    "Durable working copy does not match its base: the stamped graph state differs.",
+    {
+      details: {
+        baseVersion: base,
+        workingCopyVersion,
+        changedNodes: diff.nodes.new.length + diff.nodes.modified.length + diff.nodes.deleted.length + diff.nodes.windowed.length,
+        changedEdges: diff.edges.new.length + diff.edges.modified.length + diff.edges.deleted.length + diff.edges.windowed.length,
+        changedIdentityAssertions: diff.identity.new.length + diff.identity.retracted.length
+      }
+    }
+  );
+}
+async function reopenDurableBranch(graph, descriptor, strategy) {
+  const refusal = durableDescriptorRefusal(descriptor, strategy);
+  if (refusal !== void 0) return err(refusal);
+  if (descriptor.graphId !== graph.id) {
+    return err(
+      new BranchError(
+        `Durable branch descriptor belongs to graph "${descriptor.graphId}", not "${graph.id}".`,
+        {
+          details: { descriptorGraphId: descriptor.graphId, graphId: graph.id }
+        }
+      )
+    );
+  }
+  let reopened;
+  try {
+    reopened = await strategy.reopen(graph, descriptor.store);
+  } catch (error) {
+    return err(
+      new BranchError(
+        `Failed to reopen durable working copy for branch "${descriptor.branchId}": ${describeCause(error)}`,
+        {
+          cause: error,
+          details: { branchId: descriptor.branchId, graphId: graph.id },
+          suggestion: "Confirm the persistent working copy still exists and is reachable by the strategy, then retry."
+        }
+      )
+    );
+  }
+  const { access, store, origin } = reopened;
+  try {
+    if (store.graphId !== graph.id) {
+      throw new BranchError(
+        `Reopened working copy belongs to graph "${store.graphId}", not "${graph.id}".`,
+        {
+          details: {
+            branchId: descriptor.branchId,
+            reopenedGraphId: store.graphId,
+            graphId: graph.id
+          }
+        }
+      );
+    }
+    const descriptorOrigin = durableOriginOfDescriptor(descriptor);
+    if (!durableOriginsEqual(descriptorOrigin, origin)) {
+      throw new BranchError(
+        `Durable branch descriptor does not match the working copy the host attested for its store locator: the descriptor's TypeGraph fences disagree with the origin recorded at fork. This is a tampered, relabeled, or wrong-branch descriptor.`,
+        {
+          details: {
+            branchId: descriptor.branchId,
+            descriptorOrigin,
+            attestedOrigin: origin
+          }
+        }
+      );
+    }
+    await assertGraphMatchesAttestedOrigin(graph, origin);
+    return ok(rebuildBranch(store, access, descriptor));
+  } catch (error) {
+    await closeDurableQuietly(store, access);
+    return err(
+      error instanceof BranchError ? error : new BranchError(
+        `Failed to reattach durable working copy for branch "${descriptor.branchId}": ${describeCause(error)}`,
+        { cause: error, details: { branchId: descriptor.branchId } }
+      )
+    );
+  }
+}
+async function destroyDurableBranch(descriptor, strategy) {
+  const refusal = durableDescriptorRefusal(descriptor, strategy);
+  if (refusal !== void 0) return err(refusal);
+  try {
+    await strategy.destroy(
+      descriptor.store,
+      durableOriginOfDescriptor(descriptor)
+    );
+    return ok(void 0);
+  } catch (error) {
+    return err(
+      new BranchError(
+        `Failed to destroy durable working copy for branch "${descriptor.branchId}": ${describeCause(error)}`,
+        { cause: error, details: { branchId: descriptor.branchId } }
+      )
+    );
+  }
+}
+async function abandonAllocation(strategy, created, branchId, cause) {
+  await closeDurableQuietly(created.store, created.access);
+  let aborted = false;
+  try {
+    await strategy.abort(created.descriptor);
+    aborted = true;
+  } catch {
+  }
+  return new BranchError(
+    aborted ? `Failed to finish durable working-copy branch "${branchId}" after the host allocated it; the opened store was closed and the persistent allocation was aborted.` : `Failed to finish durable working-copy branch "${branchId}" after the host allocated it; the opened store was closed, but the host could NOT abort the persistent allocation, which may survive as an orphan.`,
+    {
+      cause,
+      details: {
+        branchId,
+        strategyType: strategy.type,
+        allocationAborted: aborted
+      },
+      ...aborted ? {} : {
+        suggestion: "The strategy's abort failed, so the persistent allocation for `details.branchId` may still exist. Inspect or remove it through the strategy's operator tooling."
+      }
+    }
+  );
+}
+function durableDescriptorRefusal(descriptor, strategy) {
+  if (typeof descriptor !== "object" || descriptor === null || Array.isArray(descriptor)) {
+    return new BranchError("Durable branch descriptor must be a JSON object.", {
+      details: { strategyType: strategy.type }
+    });
+  }
+  const record = descriptor;
+  if (record["kind"] !== strategy.type) {
+    return new BranchError(
+      `Durable branch descriptor belongs to strategy "${String(record["kind"])}", not "${strategy.type}".`,
+      {
+        details: {
+          descriptorKind: record["kind"],
+          strategyType: strategy.type
+        }
+      }
+    );
+  }
+  if (record["version"] !== strategy.version) {
+    return new BranchError(
+      `Durable branch descriptor version ${String(record["version"])} is not supported by strategy "${strategy.type}" (expected ${strategy.version}).`,
+      {
+        details: {
+          descriptorVersion: record["version"],
+          strategyVersion: strategy.version
+        }
+      }
+    );
+  }
+  for (const key of [
+    "graphId",
+    "definitionHash",
+    "branchId",
+    "base"
+  ]) {
+    const value = record[key];
+    if (typeof value !== "string" || value.length === 0) {
+      return new BranchError(
+        `Durable branch descriptor is malformed: "${key}" must be a non-empty string.`,
+        { details: { key, strategyType: strategy.type } }
+      );
+    }
+  }
+  if (!("store" in record)) {
+    return new BranchError(
+      "Durable branch descriptor is malformed: no strategy store locator.",
+      { details: { strategyType: strategy.type } }
+    );
+  }
+  if (record["schemaAnchor"] !== void 0) {
+    const anchor = record["schemaAnchor"];
+    if (typeof anchor !== "object" || anchor === null || typeof anchor["version"] !== "number" || typeof anchor["hash"] !== "string") {
+      return new BranchError(
+        "Durable branch descriptor is malformed: schemaAnchor must be { version: number; hash: string }.",
+        { details: { strategyType: strategy.type } }
+      );
+    }
+  }
+  if (record["forkRevision"] !== void 0 && typeof record["forkRevision"] !== "string") {
+    return new BranchError(
+      "Durable branch descriptor is malformed: forkRevision must be a string.",
+      { details: { strategyType: strategy.type } }
+    );
+  }
+  return void 0;
+}
+function durableOriginOfDescriptor(descriptor) {
+  return {
+    graphId: descriptor.graphId,
+    definitionHash: descriptor.definitionHash,
+    branchId: descriptor.branchId,
+    base: descriptor.base,
+    schemaAnchor: descriptor.schemaAnchor,
+    forkRevision: descriptor.forkRevision
+  };
+}
+function durableOriginsEqual(descriptor, attested) {
+  return descriptor.graphId === attested.graphId && descriptor.definitionHash === attested.definitionHash && descriptor.branchId === attested.branchId && descriptor.base === attested.base && schemaAnchorsEqual(descriptor.schemaAnchor, attested.schemaAnchor) && descriptor.forkRevision === attested.forkRevision;
+}
+function schemaAnchorsEqual(left, right) {
+  if (left === void 0 || right === void 0) return left === right;
+  return left.version === right.version && left.hash === right.hash;
+}
+async function assertGraphMatchesAttestedOrigin(graph, origin) {
+  if (graph.id !== origin.graphId) {
+    throw new BranchError(
+      `The supplied graph "${graph.id}" is not the graph the durable working copy was forked from ("${origin.graphId}").`,
+      {
+        details: {
+          graphId: graph.id,
+          attestedGraphId: origin.graphId
+        }
+      }
+    );
+  }
+  const graphHash = await getGraphDefinitionHash(graph);
+  if (graphHash !== origin.definitionHash) {
+    throw new BranchError(
+      `The supplied graph definition is incompatible with the durable working copy's host-attested fork-time definition: it hashes differently, so it is a different graph definition even though it reuses graph id "${graph.id}". This identity check is attested independently of any committed schema anchor, so it also protects an unmanaged working copy.`,
+      {
+        details: {
+          graphId: graph.id,
+          attestedDefinitionHash: origin.definitionHash,
+          graphHash
+        }
+      }
+    );
+  }
+}
+function rebuildBranch(store, access, descriptor) {
+  return {
+    id: descriptor.branchId,
+    base: descriptor.base,
+    store,
+    close: coalescedDurableClose(store, access),
+    schemaAnchor: descriptor.schemaAnchor,
+    ...descriptor.forkRevision === void 0 ? {} : { forkRevision: descriptor.forkRevision }
+  };
+}
+function coalescedDurableClose(store, access) {
+  const closeBackend = coalescedWorkingCopyClose(store);
+  let complete = false;
+  let accessReleased = false;
+  let inFlight;
+  return async () => {
+    if (complete) return;
+    inFlight ??= (async () => {
+      await closeBackend();
+      if (access.kind === "exclusive" && !accessReleased) {
+        await access.release();
+        accessReleased = true;
+      }
+      complete = true;
+    })().finally(() => {
+      inFlight = void 0;
+    });
+    await inFlight;
+  };
+}
+async function closeDurableQuietly(store, access) {
+  try {
+    await coalescedDurableClose(store, access)();
+  } catch {
+  }
+}
+
+// src/graph-merge/durable-merge.ts
+async function applyDurableMergePlan(args) {
+  const { branch: branch2, descriptor, plan, strategy, target } = args;
+  const options = args.options ?? {};
+  const refusal = durableDescriptorRefusal(descriptor, strategy);
+  if (refusal !== void 0) {
+    return err(
+      new MergeError("Durable merge descriptor validation failed.", {
+        cause: refusal
+      })
+    );
+  }
+  let artifact;
+  const descriptorOrigin = durableOriginOfDescriptor(descriptor);
+  try {
+    artifact = await validateMergePlanForTarget(target, plan);
+    const branchOrigin = {
+      graphId: branch2.store.graphId,
+      definitionHash: await getGraphDefinitionHash(branch2.store.graph),
+      branchId: branch2.id,
+      base: branch2.base,
+      schemaAnchor: branch2.schemaAnchor,
+      forkRevision: branch2.forkRevision
+    };
+    if (!durableOriginsEqual(branchOrigin, descriptorOrigin)) {
+      throw new MergeError(
+        "The durable branch handle does not match the descriptor supplied for native merge.",
+        {
+          details: {
+            branchOrigin,
+            descriptorOrigin
+          }
+        }
+      );
+    }
+  } catch (error) {
+    return err(
+      error instanceof MergeError ? error : new MergeError(
+        `Durable merge validation failed: ${describeCause(error)}`,
+        { cause: error }
+      )
+    );
+  }
+  const usePortableApply = () => applyMergePlan(target, artifact, options);
+  const hasCallbacks = options.beforeApply !== void 0 || options.afterApply !== void 0;
+  if (strategy.merge === void 0 || hasCallbacks || artifact.provenance.persist) {
+    return usePortableApply();
+  }
+  let nativeResult;
+  try {
+    nativeResult = await strategy.merge({
+      target,
+      branch: branch2,
+      descriptor: descriptor.store,
+      expectedOrigin: descriptorOrigin,
+      plan: artifact
+    });
+  } catch (error) {
+    return err(
+      new MergeError(
+        `Host-native durable merge failed: ${describeCause(error)}`,
+        {
+          cause: error,
+          suggestion: "Inspect the host-native merge state before retrying. TypeGraph does not run the portable fallback after an uncertain or failed native attempt because the host may have applied a partial change."
+        }
+      )
+    );
+  }
+  if (nativeResult.outcome === "unsupported") return usePortableApply();
+  return ok(
+    reportFromArtifact(artifact, nativeResult.merged, [
+      ...artifact.review.warnings,
+      ...nativeResult.warnings ?? []
+    ])
+  );
+}
+
 // src/graph-merge/evolution-branch.ts
 async function branchForEvolution(store, plan, makeBackend, options) {
   try {
@@ -10279,6 +10749,6 @@ async function branchForEvolution(store, plan, makeBackend, options) {
   }
 }
 
-export { BaseVersionMismatchError, BranchError, CANDIDATE_WRITE_SET_FORMAT_VERSION, CandidateSourceError, CandidateWriteSetError, CandidateWriteSetSchema, CandidateWriteSetTargetSchema, IdentityMergeConflictError, InvalidMergeOptionsError, InvalidMergePlanError, MERGE_ERROR_CODES, MERGE_OPTION_DEFAULTS, MERGE_PLAN_DIGEST_ALGORITHM, MERGE_PLAN_FORMAT_VERSION, MERGE_REVIEW_FORMAT_VERSION, MatchEvidenceError, MergeConflictError, MergeConstraintConflictError, MergeError, MergePlanCapabilityError, MergePlanDigestMismatchError, MergePlanOriginMismatchError, MergePlanSchemaMismatchError, MergePlanTargetMismatchError, MergePlanningStaleError, MergeReviewError, SimilarityUnavailableError, StaleMergePlanError, UnsupportedMergePlanVersionError, VALIDITY_END_TARGET_PRECEDENCE, applyMergePlan, applyMergePlanInTransaction, asBaseVersion, asBranchId, branch, branchForEvolution, captureCandidateWriteSetTarget, captureCandidateWriteSetTargetForEvolution, cloneWorkingCopyStrategy, computeBaseVersion, forkedWorkingCopyStrategy, ingestionBranch, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, planCandidateWriteSet, planCandidateWriteSetForEvolution, planCandidateWriteSetReview, planMerge, planMergeForEvolution, planMergeIncremental, provenanceGraphId, readProvenance, revalidateCandidateWriteSetReview };
+export { BaseVersionMismatchError, BranchError, CANDIDATE_WRITE_SET_FORMAT_VERSION, CandidateSourceError, CandidateWriteSetError, CandidateWriteSetSchema, CandidateWriteSetTargetSchema, IdentityMergeConflictError, InvalidMergeOptionsError, InvalidMergePlanError, MERGE_ERROR_CODES, MERGE_OPTION_DEFAULTS, MERGE_PLAN_DIGEST_ALGORITHM, MERGE_PLAN_FORMAT_VERSION, MERGE_REVIEW_FORMAT_VERSION, MatchEvidenceError, MergeConflictError, MergeConstraintConflictError, MergeError, MergePlanCapabilityError, MergePlanDigestMismatchError, MergePlanOriginMismatchError, MergePlanSchemaMismatchError, MergePlanTargetMismatchError, MergePlanningStaleError, MergeReviewError, SimilarityUnavailableError, StaleMergePlanError, UnsupportedMergePlanVersionError, VALIDITY_END_TARGET_PRECEDENCE, applyDurableMergePlan, applyMergePlan, applyMergePlanInTransaction, asBaseVersion, asBranchId, branch, branchDurable, branchForEvolution, captureCandidateWriteSetTarget, captureCandidateWriteSetTargetForEvolution, cloneWorkingCopyStrategy, computeBaseVersion, destroyDurableBranch, forkedWorkingCopyStrategy, ingestionBranch, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, planCandidateWriteSet, planCandidateWriteSetForEvolution, planCandidateWriteSetReview, planMerge, planMergeForEvolution, planMergeIncremental, provenanceGraphId, readProvenance, reopenDurableBranch, revalidateCandidateWriteSetReview };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map