@tangle-network/agent-provider-tangle 1.1.2 → 1.1.3

package/README.md

@@ -1,7 +1,7 @@
 # @tangle-network/agent-provider-tangle
 
 Wraps `@tangle-network/sandbox` as an `AgentEnvironmentProvider`.
-The peer range is `>=0.34.6 <1.0.0`, and this package is developed and tested against 0.34.6.
+The peer range is `>=0.34.6 <1.0.0`, and this package is developed and tested against 0.36.4.
 The floor is 0.34.6 because exact interactive attachment needs the host receiver, and workspace branching needs keyed snapshots, durable restores, inventory recovery, and cleanup.
 The provider fails closed when the configured backend or its catalog entry cannot be read.
 Newer SDKs may also provide `getBackend()` as a lookup over the same catalog.
@@ -205,6 +205,11 @@ cannot prove the complete operation surface.
 Recovery reads the account inventory through Sandbox offset pages of at most
 1,000 sandboxes and continues until a short page proves the inventory is
 complete.
+If a live snapshot loses its marker tags, recovery reads the owner-scoped
+operation record by key and binds its stored result to that live snapshot id.
+The operation record alone never revives a deleted snapshot.
+An older Sandbox deployment that cannot answer the owner-scoped lookup returns
+`unknown` and does not create or mutate a checkpoint.
 The adapter also reads checkpoints from the previous marker format while writing only the current bounded format.
 Malformed, repeated, failed, or over-bound pages return `unknown` and do not
 mutate a resource.

package/dist/tangle-workspace-branching.js

@@ -57,8 +57,8 @@ export function createTangleWorkspaceBranching(options) {
      *
      * The in-process record answers first; otherwise the Sandbox inventory and
      * operation ledger rebuild it after a restart. `absent` means the key has no
-     * resource this provider created, which is the only state where a caller may
-     * go on to create one.
+     * record, which is the only state where a caller may go on to create one.
+     * `retired` means the durable operation settled but its snapshot is gone.
      */
     const resolveCheckpoint = async (request, signal) => {
         const local = checkpoints.get(request.idempotencyKey);
@@ -70,30 +70,20 @@ export function createTangleWorkspaceBranching(options) {
                     existingRequestDigest: local.request.requestDigest,
                 };
         }
-        const recovered = await findCheckpointByKey(box, request.idempotencyKey, signal);
-        if (recovered === undefined) {
+        const recovered = await reconcileCheckpoint(box, provider, request, signal);
+        if (recovered.state === "undecided") {
             return {
                 state: "undecided",
-                message: "Sandbox checkpoint inventory is unavailable",
+                message: recovered.reason === "inventory_unavailable"
+                    ? "Sandbox checkpoint inventory is unavailable"
+                    : "Sandbox checkpoint metadata is invalid",
             };
         }
-        if (!recovered)
-            return { state: "absent" };
-        if (recovered.marker.requestDigest !== request.requestDigest) {
-            return {
-                state: "conflict",
-                existingRequestDigest: recovered.marker.requestDigest,
-            };
+        if (recovered.state === "found") {
+            checkpoints.set(request.idempotencyKey, recovered.record);
+            return { state: "known", record: recovered.record };
         }
-        const record = checkpointRecordFromSnapshot(recovered.marker.request, recovered.snapshot);
-        if (!record) {
-            return {
-                state: "undecided",
-                message: "Sandbox checkpoint metadata is invalid",
-            };
-        }
-        checkpoints.set(request.idempotencyKey, record);
-        return { state: "known", record };
+        return recovered;
     };
     /** The fork equivalent of {@link resolveCheckpoint}. */
     const resolveFork = async (request, signal) => {
@@ -153,17 +143,21 @@ export function createTangleWorkspaceBranching(options) {
         if (known.state === "undecided") {
             return checkpointUnknown(request, `${known.message}; retry after reconciliation`, true);
         }
+        if (known.state === "retired") {
+            return checkpointUnknown(request, "Sandbox checkpoint operation is settled but its snapshot is no longer present; the idempotency key cannot be reused", false);
+        }
         if (known.state === "known") {
             return checkpointSuccess(request, known.record.checkpoint, "replayed");
         }
         const tags = checkpointMarkerTags(request);
         let result;
         try {
+            operation?.signal?.throwIfAborted();
             result = await awaitWithSignal(box.snapshot?.({ tags, idempotencyKey: request.idempotencyKey }), operation?.signal);
         }
         catch (error) {
             operation?.signal?.throwIfAborted();
-            const conflict = await checkpointConflictFromRemote(box, request, operation?.signal);
+            const conflict = await checkpointConflictFromRemote(box, provider, request, operation?.signal);
             return (conflict ??
                 checkpointUnknown(request, `Sandbox checkpoint outcome is unresolved: ${safeError(error)}`, true));
         }
@@ -180,6 +174,26 @@ export function createTangleWorkspaceBranching(options) {
         if (resultMarker && resultMarker.requestDigest !== request.requestDigest) {
             return checkpointConflict(request, resultMarker.requestDigest);
         }
+        if (resultMarker &&
+            !checkpointMarkerBelongsToSource(resultMarker, provider, box.id)) {
+            return checkpointUnknown(request, "Sandbox checkpoint acknowledgement belongs to another source", false);
+        }
+        if (result.idempotency.outcome === "replayed") {
+            const recovered = await reconcileCheckpoint(box, provider, request, operation?.signal);
+            if (recovered.state === "retired" || recovered.state === "absent") {
+                return checkpointUnknown(request, "Sandbox replay acknowledged a checkpoint that is no longer present", false);
+            }
+            if (recovered.state === "undecided") {
+                return checkpointUnknown(request, recovered.reason === "metadata_invalid"
+                    ? "Sandbox replay returned invalid checkpoint metadata"
+                    : "Sandbox replay could not be reconciled with live checkpoint inventory", true);
+            }
+            if (recovered.state === "conflict") {
+                return checkpointConflict(request, recovered.existingRequestDigest);
+            }
+            checkpoints.set(request.idempotencyKey, recovered.record);
+            return checkpointSuccess(request, recovered.record.checkpoint, "replayed");
+        }
         if (!resultMarker) {
             return checkpointUnknown(request, "Sandbox checkpoint acknowledgement omitted its provider recovery marker", true);
         }
@@ -199,20 +213,13 @@ export function createTangleWorkspaceBranching(options) {
         if (known.state === "undecided") {
             return checkpointLookupUnknown(request, known.message, true);
         }
+        if (known.state === "retired") {
+            return checkpointNotFound(request);
+        }
         if (known.state === "known") {
             return checkpointFound(request, known.record.checkpoint);
         }
-        try {
-            const lookup = await awaitWithSignal(box.getSnapshotOperation?.(request.idempotencyKey, { tags: [] }), operation?.signal);
-            const settled = lookupOutcomeFromSandbox(lookup, "checkpoint");
-            return settled.absent
-                ? checkpointNotFound(request)
-                : checkpointLookupUnknown(request, settled.message, settled.retryable);
-        }
-        catch (error) {
-            operation?.signal?.throwIfAborted();
-            return checkpointLookupUnknown(request, `Sandbox checkpoint lookup failed: ${safeError(error)}`, true);
-        }
+        return checkpointNotFound(request);
     };
     const deleteCheckpoint = async (input, operation) => {
         const request = WorkspaceCleanupRequestSchema.parse(input);
@@ -731,6 +738,11 @@ function validSnapshotOperationResult(value) {
         safeIdentifier(value.snapshotId) !== undefined &&
         validOperationDate(value.createdAt));
 }
+function validTaggedSnapshotOperationResult(value) {
+    return (validSnapshotOperationResult(value) &&
+        Array.isArray(value.tags) &&
+        value.tags.every((tag) => safeString(tag) !== undefined));
+}
 function validForkOperationChildResult(value) {
     return (validOperationRecord(value) &&
         safeIdentifier(value.sandboxId ?? value.id) !== undefined &&
@@ -796,6 +808,7 @@ function forkMarkerMetadata(request, materialization = "snapshot") {
  * until the ledger reports the operation succeeded.
  */
 async function checkpointOperationLookup(box, marker, signal) {
+    signal?.throwIfAborted();
     const lookup = await awaitWithSignal(box.getSnapshotOperation?.(marker.idempotencyKey, {
         tags: marker.legacy
             ? legacyCheckpointMarkerTags(marker.request)
@@ -803,6 +816,11 @@ async function checkpointOperationLookup(box, marker, signal) {
     }), signal);
     return lookup;
 }
+/** Read the durable record by its owner-scoped key when no request body remains. */
+async function checkpointOperationLookupByKey(box, idempotencyKey, signal) {
+    signal?.throwIfAborted();
+    return await awaitWithSignal(box.getSnapshotOperation?.(idempotencyKey), signal);
+}
 async function checkpointOperationSucceeded(box, marker, signal) {
     const lookup = await checkpointOperationLookup(box, marker, signal);
     return (lookup?.outcome === "found" &&
@@ -850,9 +868,10 @@ function markerTags(kind, idempotencyKey, requestDigest, marker) {
         return tag;
     });
 }
-async function findCheckpointByKey(box, key, signal) {
+async function findCheckpointByKey(box, provider, key, signal) {
     let snapshots;
     try {
+        signal?.throwIfAborted();
         const listed = await awaitWithSignal(box.listSnapshots?.(), signal);
         if (!Array.isArray(listed))
             return undefined;
@@ -865,13 +884,21 @@ async function findCheckpointByKey(box, key, signal) {
     if (!Array.isArray(snapshots) || snapshots.length > MAX_LIST_RESULTS) {
         return undefined;
     }
+    const snapshotIds = new Set();
+    let found;
     let unresolved = false;
     for (const snapshot of snapshots) {
         if (!validSnapshotInfo(snapshot, box.id))
             return undefined;
+        if (snapshotIds.has(snapshot.snapshotId))
+            return undefined;
+        snapshotIds.add(snapshot.snapshotId);
         const marker = checkpointMarkerFromTags(snapshot.tags, key);
         if (!marker)
             continue;
+        if (!checkpointMarkerBelongsToSource(marker, provider, box.id)) {
+            return undefined;
+        }
         try {
             const lookup = await checkpointOperationLookup(box, marker, signal);
             if (lookup?.outcome === "found" &&
@@ -880,7 +907,10 @@ async function findCheckpointByKey(box, key, signal) {
                 const authoritative = snapshotFromOperationResult(snapshot, lookup);
                 if (authoritative === undefined)
                     return undefined;
-                return { snapshot: authoritative, marker };
+                if (found !== undefined)
+                    return undefined;
+                found = { state: "found", snapshot: authoritative, marker };
+                continue;
             }
             unresolved = true;
         }
@@ -889,7 +919,69 @@ async function findCheckpointByKey(box, key, signal) {
             return undefined;
         }
     }
-    return unresolved ? undefined : null;
+    if (found !== undefined)
+        return found;
+    if (unresolved)
+        return undefined;
+    // Some storage backends retain the snapshot but omit caller tags from a
+    // later inventory read. The owner-scoped operation record retains the exact
+    // acknowledgement, including those tags. Bind that record to a currently
+    // live snapshot id before recovering it; neither record is sufficient alone.
+    let lookup;
+    try {
+        lookup = await checkpointOperationLookupByKey(box, key, signal);
+    }
+    catch {
+        signal?.throwIfAborted();
+        return undefined;
+    }
+    if (lookup?.outcome === "not_found" && lookup.kind === "checkpoint") {
+        return null;
+    }
+    if (lookup?.outcome !== "found" ||
+        lookup.kind !== "checkpoint" ||
+        lookup.state !== "succeeded") {
+        return undefined;
+    }
+    if (snapshots.length === 0)
+        return { state: "retired" };
+    if (!validTaggedSnapshotOperationResult(lookup.result))
+        return undefined;
+    const live = snapshots.filter((snapshot) => snapshot.snapshotId === lookup.result?.snapshotId);
+    if (live.length === 0)
+        return { state: "retired" };
+    if (live.length !== 1)
+        return undefined;
+    const marker = checkpointMarkerFromTags(lookup.result.tags, key);
+    if (!marker ||
+        !checkpointMarkerBelongsToSource(marker, provider, box.id)) {
+        return undefined;
+    }
+    const authoritative = snapshotFromOperationResult(live[0], lookup);
+    return authoritative === undefined
+        ? undefined
+        : { state: "found", snapshot: authoritative, marker };
+}
+/** Normalize one remote checkpoint recovery attempt for every caller. */
+async function reconcileCheckpoint(box, provider, request, signal) {
+    const recovered = await findCheckpointByKey(box, provider, request.idempotencyKey, signal);
+    if (recovered === undefined) {
+        return { state: "undecided", reason: "inventory_unavailable" };
+    }
+    if (recovered === null)
+        return { state: "absent" };
+    if (recovered.state === "retired")
+        return recovered;
+    if (recovered.marker.requestDigest !== request.requestDigest) {
+        return {
+            state: "conflict",
+            existingRequestDigest: recovered.marker.requestDigest,
+        };
+    }
+    const record = checkpointRecordFromSnapshot(recovered.marker.request, recovered.snapshot);
+    return record === undefined
+        ? { state: "undecided", reason: "metadata_invalid" }
+        : { state: "found", record };
 }
 /**
  * Prefer the durable operation result over inventory metadata.
@@ -1177,6 +1269,10 @@ function markerBelongsToSource(marker, provider, sourceEnvironmentId) {
     return (marker.request.checkpoint.provider === provider &&
         marker.request.checkpoint.source.environmentId === sourceEnvironmentId);
 }
+function checkpointMarkerBelongsToSource(marker, provider, sourceEnvironmentId) {
+    return (marker.request.source.provider === provider &&
+        marker.request.source.environmentId === sourceEnvironmentId);
+}
 function checkpointMarkerFromTags(tags, key) {
     if (!Array.isArray(tags) ||
         tags.length > MAX_MARKER_CHUNKS + 3 ||
@@ -1324,19 +1420,19 @@ function forkMarkerFromMetadata(metadata, key) {
  * digest covers the Sandbox request body, not this interface's identity, so it
  * is never presented as an interface digest.
  */
-async function checkpointConflictFromRemote(box, request, signal) {
+async function checkpointConflictFromRemote(box, provider, request, signal) {
     signal?.throwIfAborted();
-    const recovered = await findCheckpointByKey(box, request.idempotencyKey, signal);
+    const recovered = await reconcileCheckpoint(box, provider, request, signal);
     signal?.throwIfAborted();
-    if (!recovered)
-        return undefined;
-    if (recovered.marker.requestDigest !== request.requestDigest) {
-        return checkpointConflict(request, recovered.marker.requestDigest);
+    if (recovered.state === "retired") {
+        return checkpointUnknown(request, "Sandbox checkpoint operation is settled but its snapshot is no longer present; the idempotency key cannot be reused", false);
     }
-    const record = checkpointRecordFromSnapshot(recovered.marker.request, recovered.snapshot);
-    return record === undefined
+    if (recovered.state === "conflict") {
+        return checkpointConflict(request, recovered.existingRequestDigest);
+    }
+    return recovered.state !== "found"
         ? undefined
-        : checkpointSuccess(request, record.checkpoint, "replayed");
+        : checkpointSuccess(request, recovered.record.checkpoint, "replayed");
 }
 /** The fork equivalent of {@link checkpointConflictFromRemote}. */
 async function forkConflictFromRemote(client, box, provider, request, verifier, signal) {
@@ -1355,10 +1451,10 @@ async function forkConflictFromRemote(client, box, provider, request, verifier,
         : forkSuccess(request, environment, "replayed");
 }
 /**
- * Read a ledger answer for a key that left no marked resource behind.
+ * Read a fork ledger answer for a key that left no marked resource behind.
  *
  * `absent` is the settled answer: a decided operation with no inventory marker
- * means the resource was cleaned after creation, and the provider must not
+ * means the child was cleaned after creation, and the provider must not
  * resurrect it from the ledger. Every other state is undecided for the caller.
  */
 function lookupOutcomeFromSandbox(lookup, kind) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
@@ -102,13 +102,13 @@
     }
   },
   "devDependencies": {
-    "@tangle-network/agent-eval": "0.170.0",
-    "@tangle-network/agent-runtime": "0.184.0",
-    "@tangle-network/sandbox": "0.34.6",
+    "@tangle-network/agent-eval": "0.173.0",
+    "@tangle-network/agent-runtime": "0.190.0",
+    "@tangle-network/sandbox": "0.36.4",
     "@types/node": "26.4.0",
     "typescript": "7.0.2",
     "vitest": "4.1.11",
-    "@tangle-network/agent-provider-testkit": "0.9.0"
+    "@tangle-network/agent-provider-testkit": "0.9.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",