@nicia-ai/typegraph 0.67.1 → 0.68.1

package/dist/graph-merge/index.cjs

@@ -1,11 +1,11 @@
 'use strict';
 
-var chunkFS2GVO2T_cjs = require('../chunk-FS2GVO2T.cjs');
+var chunkOBEYH22Q_cjs = require('../chunk-OBEYH22Q.cjs');
 require('../chunk-76OB5RSH.cjs');
 var chunk3HMEGR7U_cjs = require('../chunk-3HMEGR7U.cjs');
 require('../chunk-2XQYRCPM.cjs');
-var chunkT3VU3YRQ_cjs = require('../chunk-T3VU3YRQ.cjs');
-require('../chunk-WY3IFEKV.cjs');
+var chunk6GUBF5TF_cjs = require('../chunk-6GUBF5TF.cjs');
+require('../chunk-IFTYHOEE.cjs');
 require('../chunk-VNJMM2QQ.cjs');
 require('../chunk-I7SBZJI2.cjs');
 require('../chunk-G7OKJDMG.cjs');
@@ -40,7 +40,7 @@ var chunkXPSPDFKO_cjs = require('../chunk-XPSPDFKO.cjs');
 require('../chunk-HAHNRASW.cjs');
 var chunkHQU2SE74_cjs = require('../chunk-HQU2SE74.cjs');
 var chunkXUO3KQFO_cjs = require('../chunk-XUO3KQFO.cjs');
-require('../chunk-JLSXOBLQ.cjs');
+var chunkJLSXOBLQ_cjs = require('../chunk-JLSXOBLQ.cjs');
 var chunkNYWU6CBZ_cjs = require('../chunk-NYWU6CBZ.cjs');
 require('../chunk-OZ3ZU7Q2.cjs');
 var chunkBXHAPCQG_cjs = require('../chunk-BXHAPCQG.cjs');
@@ -135,7 +135,13 @@ var MERGE_ERROR_CODES = {
   candidateSource: "GRAPH_MERGE_CANDIDATE_SOURCE",
   evidence: "GRAPH_MERGE_EVIDENCE",
   candidateWriteSet: "GRAPH_MERGE_CANDIDATE_WRITE_SET",
-  review: "GRAPH_MERGE_REVIEW"
+  review: "GRAPH_MERGE_REVIEW",
+  operation: "GRAPH_MERGE_OPERATION",
+  operationRequest: "GRAPH_MERGE_OPERATION_REQUEST",
+  operationConflict: "GRAPH_MERGE_OPERATION_CONFLICT",
+  operationUnsupported: "GRAPH_MERGE_OPERATION_UNSUPPORTED",
+  operationEvidence: "GRAPH_MERGE_OPERATION_EVIDENCE",
+  operationUndelivered: "GRAPH_MERGE_OPERATION_UNDELIVERED"
 };
 function toTypeGraphErrorOptions(category, options) {
   return {
@@ -342,6 +348,51 @@ var MatchEvidenceError = class extends MergeError {
     this.name = "MatchEvidenceError";
   }
 };
+var DurableOperationError = class extends MergeError {
+  code = MERGE_ERROR_CODES.operation;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "DurableOperationError";
+  }
+};
+var DurableOperationRequestError = class extends DurableOperationError {
+  static errorCategory = "user";
+  code = MERGE_ERROR_CODES.operationRequest;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "DurableOperationRequestError";
+  }
+};
+var DurableOperationConflictError = class extends DurableOperationError {
+  static errorCategory = "constraint";
+  code = MERGE_ERROR_CODES.operationConflict;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "DurableOperationConflictError";
+  }
+};
+var DurableOperationUnsupportedError = class extends DurableOperationError {
+  static errorCategory = "user";
+  code = MERGE_ERROR_CODES.operationUnsupported;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "DurableOperationUnsupportedError";
+  }
+};
+var DurableOperationEvidenceError = class extends DurableOperationError {
+  code = MERGE_ERROR_CODES.operationEvidence;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "DurableOperationEvidenceError";
+  }
+};
+var DurableEvidenceUndeliveredError = class extends BranchError {
+  code = MERGE_ERROR_CODES.operationUndelivered;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "DurableEvidenceUndeliveredError";
+  }
+};
 function describeCause(cause) {
   return cause instanceof Error ? cause.message : String(cause);
 }
@@ -2109,7 +2160,7 @@ function cloneWorkingCopyWithGraphStrategy(makeBackend, graphForClone) {
     create: async (baseStore) => {
       const backend = await makeBackend();
       try {
-        const [freshStore] = await chunkFS2GVO2T_cjs.createStoreWithSchema(
+        const [freshStore] = await chunkOBEYH22Q_cjs.createStoreWithSchema(
           graphForClone(baseStore),
           backend,
           {
@@ -2140,25 +2191,25 @@ function cloneWorkingCopyWithGraphStrategy(makeBackend, graphForClone) {
         };
         const importOptions = {
           onConflict: "error",
-          onUnknownProperty: "error",
+          onUnknownProperty: "allow",
           validateReferences: true,
           batchSize: CLONE_IMPORT_BATCH_SIZE
         };
         const result = chunk6JRVV2SS_cjs.snapshotExportContention(
           chunk6B3LQUYG_cjs.storeBackend(baseStore),
           chunk6B3LQUYG_cjs.storeBackend(freshStore)
-        ) === void 0 ? await chunkT3VU3YRQ_cjs.importGraphStream(
+        ) === void 0 ? await chunk6GUBF5TF_cjs.importGraphStream(
           freshStore,
-          chunkT3VU3YRQ_cjs.exportGraphStream(baseStore, exportOptions),
+          chunk6GUBF5TF_cjs.exportGraphStream(baseStore, exportOptions),
           importOptions
-        ) : await chunkT3VU3YRQ_cjs.importGraph(
+        ) : await chunk6GUBF5TF_cjs.importGraph(
           freshStore,
-          await chunkT3VU3YRQ_cjs.exportGraph(baseStore, exportOptions),
+          await chunk6GUBF5TF_cjs.exportGraph(baseStore, exportOptions),
           importOptions
         );
         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.",
+            `Clone import failed: the working copy could not be seeded from the base store. ${chunk6GUBF5TF_cjs.summarizeImportErrors(result.errors)}`,
             { details: { errors: result.errors } }
           );
         }
@@ -2243,7 +2294,7 @@ function forkedWorkingCopyStrategy(options) {
             { details: { inheritedTables, connectedTables } }
           );
         }
-        const forkStore = chunkFS2GVO2T_cjs.createStore(baseStore.graph, backend, forkOptions);
+        const forkStore = chunkOBEYH22Q_cjs.createStore(baseStore.graph, backend, forkOptions);
         await assertWorkingCopyMatchesBase(forkStore, base);
         return forkStore;
       } catch (error) {
@@ -2385,7 +2436,7 @@ async function ingestionBranch(baseStore, makeBackend, options) {
       close: coalescedWorkingCopyClose(store)
     });
     PRIVATE_BRANCHES.set(handle, privateBranch);
-    chunkT3VU3YRQ_cjs.registerIngestionImportTarget(handle, store);
+    chunk6GUBF5TF_cjs.registerIngestionImportTarget(handle, store);
     return chunkHQU2SE74_cjs.ok(handle);
   } catch (error) {
     return chunkHQU2SE74_cjs.err(
@@ -2431,8 +2482,8 @@ async function assertMergeTransactionPristine(target, txBackend) {
 
 // src/graph-merge/apply-callbacks.ts
 var NODE_READ_NAMES = [
-  ...chunkFS2GVO2T_cjs.NODE_TEMPORAL_READ_NAMES,
-  ...chunkFS2GVO2T_cjs.CURRENT_ONLY_READ_NAMES
+  ...chunkOBEYH22Q_cjs.NODE_TEMPORAL_READ_NAMES,
+  ...chunkOBEYH22Q_cjs.CURRENT_ONLY_READ_NAMES
 ];
 function pickReadMethods(source, names) {
   return Object.fromEntries(names.map((name) => [name, source[name]]));
@@ -2450,12 +2501,12 @@ function mergePlanReadContext(tx, graph) {
         kind,
         pickReadMethods(
           chunkBXHAPCQG_cjs.requireDefined(tx.edges[kind]),
-          chunkFS2GVO2T_cjs.EDGE_TEMPORAL_READ_NAMES
+          chunkOBEYH22Q_cjs.EDGE_TEMPORAL_READ_NAMES
         )
       ])
     ),
     ..."identity" in tx ? {
-      identity: pickReadMethods(tx.identity, chunkFS2GVO2T_cjs.IDENTITY_READ_NAMES)
+      identity: pickReadMethods(tx.identity, chunkOBEYH22Q_cjs.IDENTITY_READ_NAMES)
     } : {}
   };
 }
@@ -5285,7 +5336,7 @@ async function openProvenanceStore(...args) {
       throw provenanceGraphIdCollision(graph.id, targetGraphId, claim.reason);
     }
   }
-  const [store] = await chunkFS2GVO2T_cjs.createStoreWithSchema(graph, backend);
+  const [store] = await chunkOBEYH22Q_cjs.createStoreWithSchema(graph, backend);
   return store;
 }
 async function claimSidecarOwnership(backend, graph, targetGraphId) {
@@ -9640,7 +9691,7 @@ var CandidateWriteSetSchema = zod.z.object({
   target: CandidateWriteSetTargetSchema,
   nodes: zod.z.array(candidateNodeSchema),
   edges: zod.z.array(candidateEdgeSchema),
-  identity: chunkT3VU3YRQ_cjs.InterchangeIdentitySchema.optional()
+  identity: chunk6GUBF5TF_cjs.InterchangeIdentitySchema.optional()
 });
 async function captureCandidateWriteSetTarget(target) {
   const activeSchema = await chunk6B3LQUYG_cjs.storeBackend(target).getActiveSchema(
@@ -9733,7 +9784,7 @@ async function planCandidateWriteSet(args) {
   }
   const candidate = created.data;
   try {
-    const imported = await chunkT3VU3YRQ_cjs.importGraph(
+    const imported = await chunk6GUBF5TF_cjs.importGraph(
       candidate,
       interchangeDocument(writeSet),
       {
@@ -9833,7 +9884,7 @@ async function planCandidateWriteSetForEvolution(args) {
   }
   const candidate = created.data;
   try {
-    const imported = await chunkT3VU3YRQ_cjs.importGraph(
+    const imported = await chunk6GUBF5TF_cjs.importGraph(
       candidate,
       interchangeDocument(writeSet),
       {
@@ -10479,6 +10530,7 @@ async function destroyDurableBranch(descriptor, strategy) {
     );
     return chunkHQU2SE74_cjs.ok(void 0);
   } catch (error) {
+    if (error instanceof DurableEvidenceUndeliveredError) return chunkHQU2SE74_cjs.err(error);
     return chunkHQU2SE74_cjs.err(
       new BranchError(
         `Failed to destroy durable working copy for branch "${descriptor.branchId}": ${describeCause(error)}`,
@@ -10733,6 +10785,458 @@ async function applyDurableMergePlan(args) {
   );
 }
 
+// src/graph-merge/durable-operation.ts
+var DURABLE_OPERATION_SCAN_DEFAULT_LIMIT = 100;
+var DURABLE_OPERATION_SCAN_MAX_LIMIT = 1e3;
+var OPERATION_DIGEST_BYTE_LENGTH = 16;
+async function computeDurableOperationDigest(request) {
+  const canonical = canonicalValueKey({
+    metadata: request.metadata,
+    mutation: request.mutation
+  });
+  return chunkZY4GXIVN_cjs.sha256Hex(canonical, OPERATION_DIGEST_BYTE_LENGTH);
+}
+function requireDescriptorOwner(descriptor, strategy) {
+  const refusal = durableDescriptorRefusal(descriptor, strategy);
+  if (refusal !== void 0) {
+    return {
+      ok: false,
+      error: new DurableOperationRequestError(
+        "Durable operation descriptor validation failed.",
+        { cause: refusal }
+      )
+    };
+  }
+  return { ok: true, origin: durableOriginOfDescriptor(descriptor) };
+}
+async function normalizeOperationRequest(request) {
+  const rawRequest = request;
+  if (typeof rawRequest !== "object" || rawRequest === null || Array.isArray(rawRequest)) {
+    return chunkHQU2SE74_cjs.err(
+      new DurableOperationRequestError(
+        "Durable operation request must be a JSON object."
+      )
+    );
+  }
+  if (typeof request.idempotencyKey !== "string" || request.idempotencyKey.length === 0) {
+    return chunkHQU2SE74_cjs.err(
+      new DurableOperationRequestError(
+        "Durable operation request is malformed: idempotencyKey must be a non-empty string.",
+        { details: { idempotencyKey: request.idempotencyKey } }
+      )
+    );
+  }
+  try {
+    chunkJLSXOBLQ_cjs.assertJsonValue(request.metadata, "metadata", "Durable operation");
+    chunkJLSXOBLQ_cjs.assertJsonValue(request.mutation, "mutation", "Durable operation");
+  } catch (error) {
+    return chunkHQU2SE74_cjs.err(
+      new DurableOperationRequestError(
+        `Durable operation request is not JSON-safe: ${describeCause(error)}`,
+        { cause: error, details: { idempotencyKey: request.idempotencyKey } }
+      )
+    );
+  }
+  return chunkHQU2SE74_cjs.ok({
+    idempotencyKey: request.idempotencyKey,
+    metadata: request.metadata,
+    mutation: request.mutation,
+    operationDigest: await computeDurableOperationDigest(request)
+  });
+}
+async function normalizeStoredEvidence(evidence, expectedIdempotencyKey) {
+  if (typeof evidence !== "object" || evidence === null || Array.isArray(evidence)) {
+    return chunkHQU2SE74_cjs.err(
+      new DurableOperationEvidenceError(
+        "Durable operation evidence must be a JSON object.",
+        { details: { idempotencyKey: expectedIdempotencyKey } }
+      )
+    );
+  }
+  const record = evidence;
+  if (typeof record["idempotencyKey"] !== "string" || record["idempotencyKey"].length === 0) {
+    return chunkHQU2SE74_cjs.err(
+      new DurableOperationEvidenceError(
+        "Durable operation evidence needs a non-empty idempotency key.",
+        { details: { expectedKey: expectedIdempotencyKey } }
+      )
+    );
+  }
+  if (expectedIdempotencyKey !== void 0 && record["idempotencyKey"] !== expectedIdempotencyKey) {
+    return chunkHQU2SE74_cjs.err(
+      new DurableOperationEvidenceError(
+        "Durable operation evidence does not carry the requested idempotency key.",
+        {
+          details: {
+            expectedKey: expectedIdempotencyKey,
+            receivedKey: record["idempotencyKey"]
+          }
+        }
+      )
+    );
+  }
+  if (typeof record["operationDigest"] !== "string" || record["operationDigest"].length === 0) {
+    return chunkHQU2SE74_cjs.err(
+      new DurableOperationEvidenceError(
+        "Durable operation evidence needs a non-empty operation digest.",
+        { details: { idempotencyKey: record["idempotencyKey"] } }
+      )
+    );
+  }
+  try {
+    chunkJLSXOBLQ_cjs.assertJsonValue(
+      record["metadata"],
+      "metadata",
+      "Durable operation evidence"
+    );
+    chunkJLSXOBLQ_cjs.assertJsonValue(
+      record["mutation"],
+      "mutation",
+      "Durable operation evidence"
+    );
+  } catch (error) {
+    return chunkHQU2SE74_cjs.err(
+      new DurableOperationEvidenceError(
+        `Durable operation evidence content is not JSON-safe: ${describeCause(error)}`,
+        { cause: error, details: { idempotencyKey: record["idempotencyKey"] } }
+      )
+    );
+  }
+  const refusal = validateCoordinates(record["before"], record, "before") ?? validateCoordinates(record["after"], record, "after") ?? (typeof record["delivered"] === "boolean" ? void 0 : new DurableOperationEvidenceError(
+    "Durable operation evidence is missing its delivered flag.",
+    { details: { idempotencyKey: record["idempotencyKey"] } }
+  ));
+  if (refusal !== void 0) return chunkHQU2SE74_cjs.err(refusal);
+  const normalized = evidence;
+  const canonicalDigest = await computeDurableOperationDigest(normalized);
+  if (normalized.operationDigest !== canonicalDigest) {
+    return chunkHQU2SE74_cjs.err(
+      new DurableOperationEvidenceError(
+        "Durable operation evidence digest disagrees with its canonical content.",
+        {
+          details: {
+            idempotencyKey: normalized.idempotencyKey,
+            expectedDigest: canonicalDigest,
+            receivedDigest: normalized.operationDigest
+          }
+        }
+      )
+    );
+  }
+  return chunkHQU2SE74_cjs.ok(normalized);
+}
+async function validateEvidenceForOperation(evidence, expected) {
+  const normalized = await normalizeStoredEvidence(
+    evidence,
+    expected.idempotencyKey
+  );
+  if (chunkHQU2SE74_cjs.isErr(normalized)) return normalized;
+  if (normalized.data.operationDigest !== expected.operationDigest) {
+    return chunkHQU2SE74_cjs.err(
+      new DurableOperationEvidenceError(
+        "Durable operation evidence digest disagrees with the canonical request digest.",
+        {
+          details: {
+            idempotencyKey: expected.idempotencyKey,
+            expectedDigest: expected.operationDigest,
+            receivedDigest: normalized.data.operationDigest
+          }
+        }
+      )
+    );
+  }
+  if (canonicalValueKey(normalized.data.metadata) !== canonicalValueKey(expected.metadata) || canonicalValueKey(normalized.data.mutation) !== canonicalValueKey(expected.mutation)) {
+    return chunkHQU2SE74_cjs.err(
+      new DurableOperationEvidenceError(
+        "Durable operation evidence does not echo the canonical request content.",
+        { details: { idempotencyKey: expected.idempotencyKey } }
+      )
+    );
+  }
+  return normalized;
+}
+var DURABLE_OPERATION_UNSUPPORTED_DIMENSIONS = /* @__PURE__ */ new Set([
+  "atomicMutation",
+  "evidenceStore",
+  "host"
+]);
+function isDurableOperationUnsupportedDimension(value) {
+  return typeof value === "string" && DURABLE_OPERATION_UNSUPPORTED_DIMENSIONS.has(
+    value
+  );
+}
+async function normalizeOperationOutcome(outcome, expected) {
+  if (typeof outcome !== "object" || outcome === null || Array.isArray(outcome)) {
+    return chunkHQU2SE74_cjs.err(
+      new DurableOperationEvidenceError(
+        "Durable operation host returned a malformed outcome envelope.",
+        { details: { idempotencyKey: expected.idempotencyKey } }
+      )
+    );
+  }
+  const record = outcome;
+  const outcomeKind = record["outcome"];
+  if (outcomeKind === "unsupported") {
+    const dimensions = record["dimensions"];
+    const normalizedDimensions = Array.isArray(dimensions) ? dimensions.filter(
+      (dimension) => isDurableOperationUnsupportedDimension(dimension)
+    ) : [];
+    const [firstDimension, ...remainingDimensions] = normalizedDimensions;
+    if (!Array.isArray(dimensions) || firstDimension === void 0 || normalizedDimensions.length !== dimensions.length || new Set(normalizedDimensions).size !== normalizedDimensions.length) {
+      return chunkHQU2SE74_cjs.err(
+        new DurableOperationEvidenceError(
+          "Durable operation host returned malformed unsupported dimensions.",
+          { details: { idempotencyKey: expected.idempotencyKey } }
+        )
+      );
+    }
+    return chunkHQU2SE74_cjs.ok({
+      outcome: "unsupported",
+      dimensions: [firstDimension, ...remainingDimensions]
+    });
+  }
+  if (outcomeKind !== "applied" && outcomeKind !== "replayed") {
+    return chunkHQU2SE74_cjs.err(
+      new DurableOperationEvidenceError(
+        "Durable operation host returned an unknown outcome.",
+        {
+          details: {
+            idempotencyKey: expected.idempotencyKey,
+            outcome: outcomeKind
+          }
+        }
+      )
+    );
+  }
+  const evidence = await validateEvidenceForOperation(
+    record["evidence"],
+    expected
+  );
+  if (chunkHQU2SE74_cjs.isErr(evidence)) return evidence;
+  if (outcomeKind === "applied" && evidence.data.delivered) {
+    return chunkHQU2SE74_cjs.err(
+      new DurableOperationEvidenceError(
+        "Newly applied durable operation evidence must be undelivered.",
+        { details: { idempotencyKey: expected.idempotencyKey } }
+      )
+    );
+  }
+  return chunkHQU2SE74_cjs.ok({ outcome: outcomeKind, evidence: evidence.data });
+}
+function validateCoordinates(coordinates, evidence, side) {
+  const idempotencyKey = evidence["idempotencyKey"];
+  if (typeof coordinates !== "object" || coordinates === null || Array.isArray(coordinates)) {
+    return new DurableOperationEvidenceError(
+      `Durable operation evidence ${side} coordinates are malformed.`,
+      { details: { idempotencyKey, side } }
+    );
+  }
+  const record = coordinates;
+  if (typeof record["base"] !== "string" || record["base"].length === 0) {
+    return new DurableOperationEvidenceError(
+      `Durable operation evidence ${side} coordinates need a non-empty base.`,
+      { details: { idempotencyKey, side } }
+    );
+  }
+  if (record["revision"] !== void 0 && (typeof record["revision"] !== "string" || record["revision"].length === 0)) {
+    return new DurableOperationEvidenceError(
+      `Durable operation evidence ${side} coordinates revision must be a non-empty string.`,
+      { details: { idempotencyKey, side } }
+    );
+  }
+  return void 0;
+}
+function unsupportedError(member, strategyType) {
+  return new DurableOperationUnsupportedError(
+    `Durable strategy "${strategyType}" does not provide the "${member}" operation capability.`,
+    {
+      details: { strategyType, member },
+      suggestion: "Use a strategy whose `operations` capability provides atomic mutation-plus-evidence and evidence access; TypeGraph never emulates the atomic guarantee."
+    }
+  );
+}
+async function operateDurableBranch(descriptor, strategy, request) {
+  const owner = requireDescriptorOwner(descriptor, strategy);
+  if (!owner.ok) return chunkHQU2SE74_cjs.err(owner.error);
+  const normalized = await normalizeOperationRequest(request);
+  if (chunkHQU2SE74_cjs.isErr(normalized)) return normalized;
+  if (strategy.operations === void 0) {
+    return chunkHQU2SE74_cjs.ok({
+      outcome: "unsupported",
+      dimensions: ["atomicMutation"]
+    });
+  }
+  try {
+    const outcome = await strategy.operations.operate({
+      descriptor: descriptor.store,
+      expectedOrigin: owner.origin,
+      request: normalized.data
+    });
+    return await normalizeOperationOutcome(outcome, normalized.data);
+  } catch (error) {
+    return chunkHQU2SE74_cjs.err(
+      error instanceof DurableOperationError ? error : new DurableOperationError(
+        `Durable operation failed: ${describeCause(error)}`,
+        {
+          cause: error,
+          details: { idempotencyKey: request.idempotencyKey }
+        }
+      )
+    );
+  }
+}
+async function getDurableOperation(descriptor, strategy, idempotencyKey) {
+  const owner = requireDescriptorOwner(descriptor, strategy);
+  if (!owner.ok) return chunkHQU2SE74_cjs.err(owner.error);
+  if (strategy.operations === void 0) {
+    return chunkHQU2SE74_cjs.err(unsupportedError("get", strategy.type));
+  }
+  try {
+    const evidence = await strategy.operations.get({
+      descriptor: descriptor.store,
+      expectedOrigin: owner.origin,
+      idempotencyKey
+    });
+    if (evidence === void 0) return chunkHQU2SE74_cjs.ok(void 0);
+    return await normalizeStoredEvidence(evidence, idempotencyKey);
+  } catch (error) {
+    return chunkHQU2SE74_cjs.err(
+      error instanceof DurableOperationError ? error : new DurableOperationError(
+        `Failed to read durable operation "${idempotencyKey}": ${describeCause(error)}`,
+        { cause: error, details: { idempotencyKey } }
+      )
+    );
+  }
+}
+async function scanDurableOperations(descriptor, strategy, options = {}) {
+  const owner = requireDescriptorOwner(descriptor, strategy);
+  if (!owner.ok) return chunkHQU2SE74_cjs.err(owner.error);
+  const limit = options.limit ?? DURABLE_OPERATION_SCAN_DEFAULT_LIMIT;
+  if (!Number.isInteger(limit) || limit < 1) {
+    return chunkHQU2SE74_cjs.err(
+      new DurableOperationRequestError(
+        "Durable operation scan limit must be a positive integer.",
+        { details: { limit } }
+      )
+    );
+  }
+  if (limit > DURABLE_OPERATION_SCAN_MAX_LIMIT) {
+    return chunkHQU2SE74_cjs.err(
+      new DurableOperationRequestError(
+        `Durable operation scan limit ${limit} exceeds the maximum of ${DURABLE_OPERATION_SCAN_MAX_LIMIT}.`,
+        {
+          details: { limit, max: DURABLE_OPERATION_SCAN_MAX_LIMIT },
+          suggestion: `Request at most ${DURABLE_OPERATION_SCAN_MAX_LIMIT} operations per page and page with the returned cursor.`
+        }
+      )
+    );
+  }
+  if (strategy.operations === void 0) {
+    return chunkHQU2SE74_cjs.err(unsupportedError("scan", strategy.type));
+  }
+  try {
+    const rawPage = await strategy.operations.scan({
+      descriptor: descriptor.store,
+      expectedOrigin: owner.origin,
+      after: options.after,
+      limit
+    });
+    if (typeof rawPage !== "object" || rawPage === null || Array.isArray(rawPage)) {
+      return chunkHQU2SE74_cjs.err(
+        new DurableOperationEvidenceError(
+          "Durable operation scan returned a malformed page.",
+          { details: { limit } }
+        )
+      );
+    }
+    const page = rawPage;
+    const rawOperations = page["operations"];
+    const cursor = page["cursor"];
+    if (!Array.isArray(rawOperations) || rawOperations.length > limit || cursor !== void 0 && (typeof cursor !== "string" || cursor.length === 0)) {
+      return chunkHQU2SE74_cjs.err(
+        new DurableOperationEvidenceError(
+          "Durable operation scan returned a malformed page.",
+          { details: { limit } }
+        )
+      );
+    }
+    const operations = [];
+    for (const evidence of rawOperations) {
+      const normalized = await normalizeStoredEvidence(evidence);
+      if (chunkHQU2SE74_cjs.isErr(normalized)) return normalized;
+      operations.push(normalized.data);
+    }
+    return chunkHQU2SE74_cjs.ok(
+      cursor === void 0 ? { operations } : { operations, cursor }
+    );
+  } catch (error) {
+    return chunkHQU2SE74_cjs.err(
+      error instanceof DurableOperationError ? error : new DurableOperationError(
+        `Failed to scan durable operations: ${describeCause(error)}`,
+        { cause: error, details: { limit } }
+      )
+    );
+  }
+}
+async function markDurableOperationDelivered(descriptor, strategy, idempotencyKey) {
+  const owner = requireDescriptorOwner(descriptor, strategy);
+  if (!owner.ok) return chunkHQU2SE74_cjs.err(owner.error);
+  if (strategy.operations === void 0) {
+    return chunkHQU2SE74_cjs.err(unsupportedError("markDelivered", strategy.type));
+  }
+  try {
+    const evidence = await strategy.operations.markDelivered({
+      descriptor: descriptor.store,
+      expectedOrigin: owner.origin,
+      idempotencyKey
+    });
+    if (evidence === void 0) return chunkHQU2SE74_cjs.ok(void 0);
+    const normalized = await normalizeStoredEvidence(evidence, idempotencyKey);
+    if (chunkHQU2SE74_cjs.isErr(normalized)) return normalized;
+    if (!normalized.data.delivered) {
+      return chunkHQU2SE74_cjs.err(
+        new DurableOperationEvidenceError(
+          "Durable operation delivery marking returned undelivered evidence.",
+          { details: { idempotencyKey } }
+        )
+      );
+    }
+    return normalized;
+  } catch (error) {
+    return chunkHQU2SE74_cjs.err(
+      error instanceof DurableOperationError ? error : new DurableOperationError(
+        `Failed to mark durable operation "${idempotencyKey}" delivered: ${describeCause(error)}`,
+        { cause: error, details: { idempotencyKey } }
+      )
+    );
+  }
+}
+async function durableBranchHasUndeliveredEvidence(descriptor, strategy) {
+  const owner = requireDescriptorOwner(descriptor, strategy);
+  if (!owner.ok) return chunkHQU2SE74_cjs.err(owner.error);
+  if (strategy.operations === void 0) {
+    return chunkHQU2SE74_cjs.err(unsupportedError("hasUndelivered", strategy.type));
+  }
+  try {
+    const hasUndelivered = await strategy.operations.hasUndelivered({
+      descriptor: descriptor.store,
+      expectedOrigin: owner.origin
+    });
+    return typeof hasUndelivered === "boolean" ? chunkHQU2SE74_cjs.ok(hasUndelivered) : chunkHQU2SE74_cjs.err(
+      new DurableOperationEvidenceError(
+        "Durable operation undelivered query returned a non-boolean value."
+      )
+    );
+  } catch (error) {
+    return chunkHQU2SE74_cjs.err(
+      error instanceof DurableOperationError ? error : new DurableOperationError(
+        `Failed to query undelivered durable evidence: ${describeCause(error)}`,
+        { cause: error }
+      )
+    );
+  }
+}
+
 // src/graph-merge/evolution-branch.ts
 async function branchForEvolution(store, plan, makeBackend, options) {
   try {
@@ -10769,6 +11273,14 @@ exports.CandidateSourceError = CandidateSourceError;
 exports.CandidateWriteSetError = CandidateWriteSetError;
 exports.CandidateWriteSetSchema = CandidateWriteSetSchema;
 exports.CandidateWriteSetTargetSchema = CandidateWriteSetTargetSchema;
+exports.DURABLE_OPERATION_SCAN_DEFAULT_LIMIT = DURABLE_OPERATION_SCAN_DEFAULT_LIMIT;
+exports.DURABLE_OPERATION_SCAN_MAX_LIMIT = DURABLE_OPERATION_SCAN_MAX_LIMIT;
+exports.DurableEvidenceUndeliveredError = DurableEvidenceUndeliveredError;
+exports.DurableOperationConflictError = DurableOperationConflictError;
+exports.DurableOperationError = DurableOperationError;
+exports.DurableOperationEvidenceError = DurableOperationEvidenceError;
+exports.DurableOperationRequestError = DurableOperationRequestError;
+exports.DurableOperationUnsupportedError = DurableOperationUnsupportedError;
 exports.IdentityMergeConflictError = IdentityMergeConflictError;
 exports.InvalidMergeOptionsError = InvalidMergeOptionsError;
 exports.InvalidMergePlanError = InvalidMergePlanError;
@@ -10804,13 +11316,18 @@ exports.captureCandidateWriteSetTarget = captureCandidateWriteSetTarget;
 exports.captureCandidateWriteSetTargetForEvolution = captureCandidateWriteSetTargetForEvolution;
 exports.cloneWorkingCopyStrategy = cloneWorkingCopyStrategy;
 exports.computeBaseVersion = computeBaseVersion;
+exports.computeDurableOperationDigest = computeDurableOperationDigest;
 exports.destroyDurableBranch = destroyDurableBranch;
+exports.durableBranchHasUndeliveredEvidence = durableBranchHasUndeliveredEvidence;
 exports.forkedWorkingCopyStrategy = forkedWorkingCopyStrategy;
+exports.getDurableOperation = getDurableOperation;
 exports.ingestionBranch = ingestionBranch;
+exports.markDurableOperationDelivered = markDurableOperationDelivered;
 exports.merge = merge;
 exports.mergeIncremental = mergeIncremental;
 exports.normalizeMergeOptions = normalizeMergeOptions;
 exports.openProvenanceStore = openProvenanceStore;
+exports.operateDurableBranch = operateDurableBranch;
 exports.persistProvenanceRecords = persistProvenanceRecords;
 exports.planCandidateWriteSet = planCandidateWriteSet;
 exports.planCandidateWriteSetForEvolution = planCandidateWriteSetForEvolution;
@@ -10822,5 +11339,6 @@ exports.provenanceGraphId = provenanceGraphId;
 exports.readProvenance = readProvenance;
 exports.reopenDurableBranch = reopenDurableBranch;
 exports.revalidateCandidateWriteSetReview = revalidateCandidateWriteSetReview;
+exports.scanDurableOperations = scanDurableOperations;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map