@tangle-network/agent-provider-tangle 1.0.0 → 1.0.2

package/README.md

@@ -1,8 +1,8 @@
 # @tangle-network/agent-provider-tangle
 
 Wraps `@tangle-network/sandbox` as an `AgentEnvironmentProvider`.
-The peer range is `>=0.34.4 <1.0.0`, and this package is developed and tested against 0.34.4.
-The floor is 0.34.4 because exact interactive attachment needs the host receiver, and workspace branching needs keyed snapshot, fork, lookup, and cleanup operations.
+The peer range is `>=0.34.6 <1.0.0`, and this package is developed and tested against 0.34.6.
+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.
 
@@ -112,7 +112,7 @@ and recovering a checkpoint, forking one managed child, and cleaning both
 resources in dependency order.
 The adapter advertises `branching.checkpoint`, `branching.fork`, `retrySafe`,
 `lookup`, and `cleanup` only when the linked SDK exposes the complete managed
-surface: keyed `snapshot` and `fork`, operation lookup, inventory recovery, and
+surface: keyed `snapshot`, durable snapshot restore, inventory recovery, and
 explicit deletion outcomes.
 An incomplete SDK surface clears every branching flag and omits
 `environment.workspaceBranching`.
@@ -122,9 +122,10 @@ calling Sandbox.
 Retries with the same key replay the original resource, while changed material
 returns a conflict containing the original interface digest.
 The provider stores a bounded request marker in snapshot tags and child
-metadata so a fresh process can recover the exact interface digest, but the
-marker only names a candidate: the Sandbox operation ledger still has to report
-a settled success before the adapter returns the resource.
+metadata so a fresh process can recover the exact interface digest.
+Snapshot-created children are validated through the marker and complete
+account inventory, while legacy fork markers also require the Sandbox fork
+ledger to report a settled success.
 Checkpoint deletion reports `in_use` with every verified child that still
 references it; delete the child first, then retry checkpoint deletion.
 The adapter never treats an SDK response without an explicit idempotency or

package/dist/tangle-workspace-branching.js

@@ -303,47 +303,64 @@ export function createTangleWorkspaceBranching(options) {
                 : "Sandbox checkpoint inventory is unavailable", true);
         }
         const metadata = forkMarkerMetadata(request);
-        let result;
+        let returnedChild;
+        let outcome;
         try {
-            result = await awaitWithSignal(box.fork?.(1, {
-                metadata,
+            // Sandbox fork copies live VM memory, not the durable workspace view.
+            // Restore the checkpoint so files written before the checkpoint survive.
+            returnedChild = await awaitWithSignal(client.create({
+                fromSnapshot: request.checkpoint.checkpointId,
+                fromSandboxId: box.id,
                 idempotencyKey: request.idempotencyKey,
-            }), operation?.signal);
+                metadata,
+                ...(request.name === undefined ? {} : { name: request.name }),
+            }, operation?.signal === undefined
+                ? undefined
+                : { signal: operation.signal }), operation?.signal);
+            const receipt = returnedChild.createReceipt?.();
+            if (!receipt ||
+                receipt.idempotencyKeyApplied !== true ||
+                (receipt.outcome !== "created" &&
+                    receipt.outcome !== "idempotent_replay")) {
+                const compensation = await compensateCreatedForkChild(returnedChild, receipt?.outcome === "created" ? "created" : "replayed", operation?.signal);
+                const removed = compensation === "destroyed" || compensation === "already_absent";
+                return forkUnknown(request, removed
+                    ? "Sandbox snapshot restore returned no complete create receipt; the newly created child was removed"
+                    : "Sandbox snapshot restore returned no complete create receipt; child cleanup was not confirmed", !removed);
+            }
+            outcome =
+                receipt.outcome === "idempotent_replay" ? "replayed" : "created";
         }
         catch (error) {
             operation?.signal?.throwIfAborted();
             const conflict = await forkConflictFromRemote(client, box, provider, request, options.confidentialAttestationVerifier, operation?.signal);
             return (conflict ??
-                forkUnknown(request, `Sandbox fork outcome is unresolved: ${safeError(error)}`, true));
-        }
-        if (!result ||
-            !validForkResult(result) ||
-            result.idempotency === undefined ||
-            (result.idempotency.outcome !== "created" &&
-                result.idempotency.outcome !== "replayed") ||
-            safeString(result.idempotency.requestDigest) === undefined) {
-            return forkUnknown(request, "Sandbox fork returned no complete idempotent acknowledgement", true);
-        }
-        if (result.children.length !== 1 || result.complete !== true) {
-            return forkUnknown(request, "Sandbox fork did not materialize exactly one complete child", true);
+                forkUnknown(request, `Sandbox snapshot restore outcome is unresolved: ${safeError(error)}`, true));
+        }
+        if (!returnedChild ||
+            typeof returnedChild !== "object" ||
+            safeIdentifier(returnedChild.id) === undefined ||
+            returnedChild.id === box.id) {
+            const compensation = returnedChild
+                ? await compensateCreatedForkChild(returnedChild, outcome, operation?.signal)
+                : "not_attempted";
+            const removed = compensation === "destroyed" || compensation === "already_absent";
+            return forkUnknown(request, removed
+                ? "Sandbox snapshot restore returned an invalid child; the newly created child was removed"
+                : "Sandbox snapshot restore returned an invalid child; child cleanup was not confirmed", !removed);
         }
-        const returnedChild = result.children[0];
         const child = await completeForkChild(client, returnedChild, operation?.signal);
         if (!child) {
-            const compensation = forkMarkerFromMetadata(returnedChild.metadata) === undefined
-                ? await compensateUnmarkedForkChild(result, returnedChild, operation?.signal)
-                : "not_attempted";
+            const compensation = await compensateCreatedForkChild(returnedChild, outcome, operation?.signal);
             const removed = compensation === "destroyed" || compensation === "already_absent";
             return forkUnknown(request, removed
-                ? "Sandbox fork returned a child without a complete identity; the newly created child was removed"
-                : compensation === "unconfirmed"
-                    ? "Sandbox fork returned a child without a complete identity; child cleanup was not confirmed"
-                    : "Sandbox fork returned a child without a complete identity", !removed);
+                ? "Sandbox snapshot restore returned a child without a complete identity; the newly created child was removed"
+                : "Sandbox snapshot restore returned a child without a complete identity; child cleanup was not confirmed", !removed);
         }
         const childMarker = forkMarkerFromMetadata(child.metadata);
         if (childMarker) {
             if (!markerBelongsToSource(childMarker, provider, box.id)) {
-                return forkUnknown(request, "Sandbox fork returned a child marked for another source", true);
+                return forkUnknown(request, "Sandbox snapshot restore returned a child marked for another source", true);
             }
             if (childMarker.idempotencyKey !== request.idempotencyKey ||
                 childMarker.requestDigest !== request.requestDigest) {
@@ -351,21 +368,19 @@ export function createTangleWorkspaceBranching(options) {
             }
         }
         if (!childMarker) {
-            const compensation = await compensateUnmarkedForkChild(result, child, operation?.signal);
+            const compensation = await compensateCreatedForkChild(returnedChild, outcome, operation?.signal);
             const removed = compensation === "destroyed" || compensation === "already_absent";
             return forkUnknown(request, removed
-                ? "Sandbox fork acknowledgement omitted its provider recovery marker; the newly created child was removed"
-                : compensation === "unconfirmed"
-                    ? "Sandbox fork acknowledgement omitted its provider recovery marker; child cleanup was not confirmed"
-                    : "Sandbox fork acknowledgement omitted its provider recovery marker", !removed);
+                ? "Sandbox snapshot restore acknowledgement omitted its provider recovery marker; the newly created child was removed"
+                : "Sandbox snapshot restore acknowledgement omitted its provider recovery marker; child cleanup was not confirmed", !removed);
         }
         const environment = await environmentFromChild(request, child, provider, child.createdAt, options.confidentialAttestationVerifier, operation?.signal);
         if (!environment) {
-            return forkUnknown(request, "Sandbox fork returned a child without a valid identity", true);
+            return forkUnknown(request, "Sandbox snapshot restore returned a child without a valid identity", true);
         }
         const record = { request, environment, child };
         forks.set(request.idempotencyKey, record);
-        return forkSuccess(request, environment, result.idempotency.outcome);
+        return forkSuccess(request, environment, outcome);
     };
     const lookupFork = async (input, operation) => {
         const request = WorkspaceOperationLookupRequestSchema.parse(input);
@@ -461,14 +476,13 @@ export function createTangleWorkspaceBranching(options) {
 }
 /** Capability support requires every operation used by recovery and cleanup. */
 export function supportsWorkspaceBranching(box, client) {
-    return (typeof client.list === "function" &&
+    return (typeof client.create === "function" &&
+        typeof client.list === "function" &&
         typeof client.get === "function" &&
         typeof box.snapshot === "function" &&
         typeof box.listSnapshots === "function" &&
         typeof box.deleteSnapshot === "function" &&
-        typeof box.getSnapshotOperation === "function" &&
-        typeof box.fork === "function" &&
-        typeof box.getForkOperation === "function");
+        typeof box.getSnapshotOperation === "function");
 }
 /** Drop every in-process record for a resource the platform no longer holds. */
 function forgetRecords(records, matches) {
@@ -689,16 +703,6 @@ function validSnapshotInfo(snapshot, sandboxId) {
         safeIdentifier(snapshot.sandboxId) !== undefined &&
         (sandboxId === undefined || snapshot.sandboxId === sandboxId));
 }
-function validForkResult(result) {
-    return (!!result &&
-        Array.isArray(result.children) &&
-        result.children.every((child) => child !== null &&
-            typeof child === "object" &&
-            safeIdentifier(child.id) !== undefined) &&
-        result.requestedCount === 1 &&
-        result.materializedCount === result.children.length &&
-        typeof result.complete === "boolean");
-}
 function validOperationRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -713,7 +717,9 @@ function validSnapshotOperationResult(value) {
 function validForkOperationChildResult(value) {
     return (validOperationRecord(value) &&
         safeIdentifier(value.sandboxId ?? value.id) !== undefined &&
-        validOperationDate(value.createdAt));
+        (value.createdAt === undefined ||
+            value.createdAt === null ||
+            validOperationDate(value.createdAt)));
 }
 function checkpointMarkerTags(request) {
     const marker = {
@@ -748,7 +754,7 @@ function legacyCheckpointMarkerTags(request) {
         ...chunks.map((chunk, index) => `${base}:material:${index}:${chunks.length}:${chunk}`),
     ];
 }
-function forkMarkerMetadata(request) {
+function forkMarkerMetadata(request, materialization = "snapshot") {
     if (request.metadata && Object.hasOwn(request.metadata, FORK_METADATA_KEY)) {
         throw new Error(`fork metadata reserves ${FORK_METADATA_KEY}`);
     }
@@ -758,6 +764,7 @@ function forkMarkerMetadata(request) {
         idempotencyKey: request.idempotencyKey,
         requestDigest: request.requestDigest,
         request,
+        ...(materialization === "snapshot" ? { materialization } : {}),
     };
     assertBoundedJson(marker);
     return {
@@ -785,11 +792,18 @@ async function checkpointOperationSucceeded(box, marker, signal) {
         lookup.kind === "checkpoint" &&
         lookup.state === "succeeded");
 }
-/** The fork equivalent of {@link checkpointOperationSucceeded}. */
+/** Confirm a fork child through its marker or the legacy fork ledger. */
 async function forkOperationLookup(box, marker, signal) {
+    if (marker.materialization === "snapshot") {
+        return {
+            outcome: "found",
+            kind: "fork",
+            state: "succeeded",
+        };
+    }
     const lookup = await awaitWithSignal(box.getForkOperation?.(marker.idempotencyKey, {
         count: 1,
-        metadata: forkMarkerMetadata(marker.request),
+        metadata: forkMarkerMetadata(marker.request, marker.materialization),
     }), signal);
     return lookup;
 }
@@ -948,6 +962,8 @@ async function findForkByKey(client, box, provider, key, signal) {
  * Fork inventory can report a child timestamp from a later registry read. The
  * operation ledger stores the original child acknowledgement, which is the
  * stable value required to replay one exact fork reference after a restart.
+ * Some Sandbox responses omit that timestamp, so the validated inventory
+ * record supplies it only when the operation result does not.
  */
 function childFromOperationResult(child, lookup) {
     if (lookup.result === undefined) {
@@ -963,7 +979,10 @@ function childFromOperationResult(child, lookup) {
         (candidate.sandboxId ?? candidate.id) === child.id);
     if (!operationChild)
         return undefined;
-    return { child, createdAt: operationChild.createdAt };
+    const createdAt = operationChild.createdAt ?? child.createdAt;
+    if (!validOperationDate(createdAt))
+        return undefined;
+    return { child, createdAt };
 }
 async function findForkChildById(client, box, provider, id, signal) {
     try {
@@ -1016,9 +1035,9 @@ async function completeForkChild(client, child, signal) {
         return undefined;
     }
 }
-/** Remove only a child this exact call confirmed it created. */
-async function compensateUnmarkedForkChild(result, child, signal) {
-    if (result.idempotency?.outcome !== "created")
+/** Remove only a child this exact create call confirmed it created. */
+async function compensateCreatedForkChild(child, outcome, signal) {
+    if (outcome !== "created")
         return "not_attempted";
     if (typeof child.delete !== "function")
         return "unconfirmed";
@@ -1259,6 +1278,10 @@ function forkMarkerFromMetadata(metadata, key) {
         typeof parsed.idempotencyKey !== "string" ||
         typeof parsed.requestDigest !== "string")
         return undefined;
+    if (parsed.materialization !== undefined &&
+        parsed.materialization !== "snapshot") {
+        return undefined;
+    }
     if (key !== undefined && parsed.idempotencyKey !== key)
         return undefined;
     const request = WorkspaceForkRequestSchema.safeParse(parsed.request);
@@ -1272,6 +1295,9 @@ function forkMarkerFromMetadata(metadata, key) {
         idempotencyKey: parsed.idempotencyKey,
         requestDigest: parsed.requestDigest,
         request: request.data,
+        ...(parsed.materialization === "snapshot"
+            ? { materialization: "snapshot" }
+            : {}),
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",