@tangle-network/agent-provider-tangle 1.1.6 → 1.1.8

package/dist/tangle-workspace-markers.d.ts

@@ -0,0 +1,27 @@
+import type { WorkspaceCheckpointRequest, WorkspaceForkRequest } from "@tangle-network/agent-interface";
+export interface CheckpointMarker {
+    version: 1;
+    kind: "checkpoint";
+    idempotencyKey: string;
+    requestDigest: `sha256:${string}`;
+    request: WorkspaceCheckpointRequest;
+    /** True only for markers written by the pre-128-byte-tag release. */
+    legacy?: boolean;
+}
+export interface ForkMarker {
+    version: 1;
+    kind: "fork";
+    idempotencyKey: string;
+    requestDigest: `sha256:${string}`;
+    request: WorkspaceForkRequest;
+    /** New markers identify children created from the durable checkpoint. */
+    materialization?: "snapshot";
+}
+export declare function checkpointMarkerTags(request: WorkspaceCheckpointRequest): string[];
+/** Rebuild the exact tags used by the release before the current safe format. */
+export declare function legacyCheckpointMarkerTags(request: WorkspaceCheckpointRequest): string[];
+export declare function forkMarkerMetadata(request: WorkspaceForkRequest, materialization?: "snapshot" | undefined): Record<string, unknown>;
+export declare function markerBelongsToSource(marker: ForkMarker, provider: string, sourceEnvironmentId: string): boolean;
+export declare function checkpointMarkerBelongsToSource(marker: CheckpointMarker, provider: string, sourceEnvironmentId: string): boolean;
+export declare function checkpointMarkerFromTags(tags: string[] | undefined, key?: string): CheckpointMarker | undefined;
+export declare function forkMarkerFromMetadata(metadata: Record<string, unknown> | undefined, key?: string): ForkMarker | undefined;

package/dist/tangle-workspace-markers.js

@@ -0,0 +1,277 @@
+import { WorkspaceCheckpointRequestSchema, WorkspaceForkRequestSchema, sha256Bytes, } from "@tangle-network/agent-interface";
+import { assertBoundedJson, cloneJson, safeString, } from "./tangle-contract-safety.js";
+/**
+ * Namespace used for provider recovery metadata.
+ *
+ * The values are identity markers, not security evidence. A marker can tell
+ * the provider which request produced a resource, but only the Sandbox
+ * operation ledger and the external verifier can prove an outcome.
+ */
+const MARKER_PREFIX = "tangle-agent-ws-v1";
+/** Marker namespace used by releases before the 128-byte tag limit. */
+const LEGACY_MARKER_PREFIX = "tangle-agent-sdk:workspace:v1";
+const FORK_METADATA_KEY = "__tangle_agent_workspace_v1";
+const MAX_MARKER_TAG_LENGTH = 128;
+const MARKER_CHUNK_SIZE = 80;
+const LEGACY_MARKER_CHUNK_SIZE = 240;
+const MAX_MARKER_CHUNKS = 512;
+export function checkpointMarkerTags(request) {
+    const marker = {
+        version: 1,
+        kind: "checkpoint",
+        idempotencyKey: request.idempotencyKey,
+        requestDigest: request.requestDigest,
+        request,
+    };
+    const encoded = encodeJson(marker);
+    if (encoded === undefined)
+        throw new Error("workspace marker is not JSON serializable");
+    const base = `${MARKER_PREFIX}-checkpoint`;
+    const chunks = splitIntoChunks(encoded, MARKER_CHUNK_SIZE);
+    if (chunks.length > MAX_MARKER_CHUNKS) {
+        throw new Error("workspace marker exceeds the recovery bound");
+    }
+    return [
+        `${base}-key-${markerKeyDigest(request.idempotencyKey).replace(":", "-")}`,
+        `${base}-digest-${request.requestDigest.replace(":", "-")}`,
+        ...chunks.map((chunk, index) => `${base}-material-${index}-${chunks.length}-${chunk}`),
+    ].map((tag) => {
+        if (Buffer.byteLength(tag, "utf8") > MAX_MARKER_TAG_LENGTH) {
+            throw new Error("workspace marker tag exceeds the platform bound");
+        }
+        return tag;
+    });
+}
+/** Rebuild the exact tags used by the release before the current safe format. */
+export function legacyCheckpointMarkerTags(request) {
+    const marker = {
+        version: 1,
+        kind: "checkpoint",
+        idempotencyKey: request.idempotencyKey,
+        requestDigest: request.requestDigest,
+        request,
+    };
+    const encoded = encodeJson(marker);
+    if (encoded === undefined)
+        throw new Error("workspace marker is not JSON serializable");
+    const base = `${LEGACY_MARKER_PREFIX}:checkpoint`;
+    const chunks = splitIntoChunks(encoded, LEGACY_MARKER_CHUNK_SIZE);
+    if (chunks.length > MAX_MARKER_CHUNKS) {
+        throw new Error("workspace marker exceeds the recovery bound");
+    }
+    return [
+        `${base}:key:${encodeText(request.idempotencyKey)}`,
+        `${base}:digest:${request.requestDigest}`,
+        ...chunks.map((chunk, index) => `${base}:material:${index}:${chunks.length}:${chunk}`),
+    ];
+}
+export function forkMarkerMetadata(request, materialization = "snapshot") {
+    if (request.metadata && Object.hasOwn(request.metadata, FORK_METADATA_KEY)) {
+        throw new Error(`fork metadata reserves ${FORK_METADATA_KEY}`);
+    }
+    const marker = {
+        version: 1,
+        kind: "fork",
+        idempotencyKey: request.idempotencyKey,
+        requestDigest: request.requestDigest,
+        request,
+        ...(materialization === "snapshot" ? { materialization } : {}),
+    };
+    assertBoundedJson(marker);
+    return {
+        ...(request.metadata === undefined ? {} : cloneJson(request.metadata)),
+        [FORK_METADATA_KEY]: marker,
+    };
+}
+export function markerBelongsToSource(marker, provider, sourceEnvironmentId) {
+    return (marker.request.checkpoint.provider === provider &&
+        marker.request.checkpoint.source.environmentId === sourceEnvironmentId);
+}
+export function checkpointMarkerBelongsToSource(marker, provider, sourceEnvironmentId) {
+    return (marker.request.source.provider === provider &&
+        marker.request.source.environmentId === sourceEnvironmentId);
+}
+export function checkpointMarkerFromTags(tags, key) {
+    if (!Array.isArray(tags) ||
+        tags.length > MAX_MARKER_CHUNKS + 3 ||
+        !tags.every((tag) => safeString(tag) !== undefined)) {
+        return undefined;
+    }
+    const currentBase = `${MARKER_PREFIX}-checkpoint`;
+    const legacyBase = `${LEGACY_MARKER_PREFIX}:checkpoint`;
+    const hasCurrentTags = tags.some((tag) => tag.startsWith(`${currentBase}-`));
+    const hasLegacyTags = tags.some((tag) => tag.startsWith(`${legacyBase}:`));
+    if (hasCurrentTags === hasLegacyTags)
+        return undefined;
+    if (hasLegacyTags)
+        return legacyCheckpointMarkerFromTags(tags, key, legacyBase);
+    if (tags.some((tag) => Buffer.byteLength(tag, "utf8") > MAX_MARKER_TAG_LENGTH)) {
+        return undefined;
+    }
+    return currentCheckpointMarkerFromTags(tags, key, currentBase);
+}
+function currentCheckpointMarkerFromTags(tags, key, base) {
+    const keyTag = tags.find((tag) => tag.startsWith(`${base}-key-`));
+    if (keyTag &&
+        key !== undefined &&
+        keyTag.slice(`${base}-key-`.length) !==
+            markerKeyDigest(key).replace(":", "-")) {
+        return undefined;
+    }
+    const chunks = tags
+        .map((tag) => {
+        const match = tag.match(new RegExp(`^${escapeRegExp(base)}-material-(\\d+)-(\\d+)-([A-Za-z0-9_-]+)$`));
+        return match
+            ? { index: Number(match[1]), total: Number(match[2]), chunk: match[3] }
+            : undefined;
+    })
+        .filter((value) => value !== undefined)
+        .sort((left, right) => left.index - right.index);
+    if (chunks.length === 0 ||
+        chunks[0].total < 1 ||
+        chunks[0].total > MAX_MARKER_CHUNKS ||
+        chunks[0].total !== chunks.length ||
+        chunks.some((chunk, index) => !Number.isSafeInteger(chunk.index) ||
+            !Number.isSafeInteger(chunk.total) ||
+            chunk.index !== index ||
+            chunk.total !== chunks[0].total)) {
+        return undefined;
+    }
+    const decoded = decodeJson(chunks.map((chunk) => chunk.chunk).join(""));
+    return checkpointMarkerFromUnknown(decoded, key);
+}
+function legacyCheckpointMarkerFromTags(tags, key, base) {
+    const keyTag = tags.find((tag) => tag.startsWith(`${base}:key:`));
+    if (keyTag &&
+        key !== undefined &&
+        decodeText(keyTag.slice(`${base}:key:`.length)) !== key) {
+        return undefined;
+    }
+    const chunks = tags
+        .map((tag) => {
+        const match = tag.match(new RegExp(`^${escapeRegExp(base)}:material:(\\d+):(\\d+):([A-Za-z0-9_-]+)$`));
+        return match
+            ? { index: Number(match[1]), total: Number(match[2]), chunk: match[3] }
+            : undefined;
+    })
+        .filter((value) => value !== undefined)
+        .sort((left, right) => left.index - right.index);
+    if (chunks.length === 0 ||
+        chunks[0].total < 1 ||
+        chunks[0].total > MAX_MARKER_CHUNKS ||
+        chunks[0].total !== chunks.length ||
+        chunks.some((chunk, index) => !Number.isSafeInteger(chunk.index) ||
+            !Number.isSafeInteger(chunk.total) ||
+            chunk.index !== index ||
+            chunk.total !== chunks[0].total)) {
+        return undefined;
+    }
+    const decoded = decodeJson(chunks.map((chunk) => chunk.chunk).join(""));
+    return checkpointMarkerFromUnknown(decoded, key, true);
+}
+function checkpointMarkerFromUnknown(value, key, legacy = false) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const parsed = value;
+    if (parsed.version !== 1 ||
+        parsed.kind !== "checkpoint" ||
+        typeof parsed.idempotencyKey !== "string" ||
+        typeof parsed.requestDigest !== "string")
+        return undefined;
+    if (key !== undefined && parsed.idempotencyKey !== key)
+        return undefined;
+    const request = WorkspaceCheckpointRequestSchema.safeParse(parsed.request);
+    if (!request.success ||
+        request.data.idempotencyKey !== parsed.idempotencyKey ||
+        request.data.requestDigest !== parsed.requestDigest)
+        return undefined;
+    return {
+        version: 1,
+        kind: "checkpoint",
+        idempotencyKey: parsed.idempotencyKey,
+        requestDigest: parsed.requestDigest,
+        request: request.data,
+        ...(legacy ? { legacy: true } : {}),
+    };
+}
+export function forkMarkerFromMetadata(metadata, key) {
+    if (!metadata ||
+        typeof metadata !== "object" ||
+        !Object.hasOwn(metadata, FORK_METADATA_KEY)) {
+        return undefined;
+    }
+    const value = metadata[FORK_METADATA_KEY];
+    if (!value || typeof value !== "object")
+        return undefined;
+    const parsed = value;
+    if (parsed.version !== 1 ||
+        parsed.kind !== "fork" ||
+        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);
+    if (!request.success ||
+        request.data.idempotencyKey !== parsed.idempotencyKey ||
+        request.data.requestDigest !== parsed.requestDigest)
+        return undefined;
+    return {
+        version: 1,
+        kind: "fork",
+        idempotencyKey: parsed.idempotencyKey,
+        requestDigest: parsed.requestDigest,
+        request: request.data,
+        ...(parsed.materialization === "snapshot"
+            ? { materialization: "snapshot" }
+            : {}),
+    };
+}
+function encodeText(value) {
+    return Buffer.from(value, "utf8").toString("base64url");
+}
+function decodeText(value) {
+    try {
+        const decoded = Buffer.from(value, "base64url").toString("utf8");
+        return encodeText(decoded) === value ? decoded : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function markerKeyDigest(value) {
+    return sha256Bytes(Buffer.from(value, "utf8"));
+}
+function encodeJson(value) {
+    try {
+        const serialized = JSON.stringify(value);
+        if (serialized === undefined)
+            return undefined;
+        return encodeText(serialized);
+    }
+    catch {
+        return undefined;
+    }
+}
+function decodeJson(value) {
+    try {
+        return JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function splitIntoChunks(value, chunkSize) {
+    const chunks = [];
+    for (let index = 0; index < value.length; index += chunkSize) {
+        chunks.push(value.slice(index, index + chunkSize));
+    }
+    return chunks;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/tangle-workspace-recovery.d.ts

@@ -0,0 +1,68 @@
+import type { WorkspaceCheckpointRef, WorkspaceCheckpointRequest } from "@tangle-network/agent-interface";
+import type { SandboxClientLike, SandboxInstanceLike, SandboxSnapshotInfoLike, SandboxSnapshotResultLike, SandboxWorkspaceOperationLookupLike } from "./tangle-types.js";
+import type { ForkMarker } from "./tangle-workspace-markers.js";
+export interface CheckpointRecord {
+    request: WorkspaceCheckpointRequest;
+    checkpoint: WorkspaceCheckpointRef;
+    snapshotId: string;
+}
+interface RecoveredForkChild {
+    child: SandboxInstanceLike;
+    createdAt: Date | string | undefined;
+}
+/** Normalize remote checkpoint recovery before each caller chooses its output. */
+type CheckpointReconciliation = {
+    state: "found";
+    record: CheckpointRecord;
+} | {
+    state: "conflict";
+    existingRequestDigest: `sha256:${string}`;
+} | {
+    state: "undecided";
+    reason: "inventory_unavailable" | "metadata_invalid";
+} | {
+    state: "retired";
+} | {
+    state: "absent";
+};
+export declare function checkpointRecordFromSnapshot(request: WorkspaceCheckpointRequest, snapshot: SandboxSnapshotResultLike | SandboxSnapshotInfoLike): CheckpointRecord | undefined;
+export declare function validSnapshotResult(result: SandboxSnapshotResultLike | undefined): result is SandboxSnapshotResultLike;
+/** Normalize one remote checkpoint recovery attempt for every caller. */
+export declare function reconcileCheckpoint(box: SandboxInstanceLike, provider: string, request: Pick<WorkspaceCheckpointRequest, "idempotencyKey" | "requestDigest">, signal?: AbortSignal): Promise<CheckpointReconciliation>;
+/**
+ * Confirm that one snapshot id is a settled checkpoint this provider created.
+ *
+ * `expected` binds the answer to a specific checkpoint reference. A reference
+ * that does not match its marker is absent, not unknown: the caller supplied a
+ * checkpoint this source never produced.
+ */
+export declare function findManagedCheckpoint(box: SandboxInstanceLike, provider: string, id: string, expected?: WorkspaceCheckpointRef, signal?: AbortSignal): Promise<true | false | "unknown">;
+export declare function findForkByKey(client: SandboxClientLike, box: SandboxInstanceLike, provider: string, key: string, signal?: AbortSignal): Promise<(RecoveredForkChild & {
+    marker: ForkMarker;
+}) | null | undefined>;
+export declare function findForkChildById(client: SandboxClientLike, box: SandboxInstanceLike, provider: string, id: string, signal?: AbortSignal): Promise<SandboxInstanceLike | null | undefined>;
+/**
+ * Resolve a complete child identity when an acknowledgement omits durable data.
+ *
+ * A branch response can precede a richer registry read during a rolling
+ * deployment. Recover the exact child when its creation time or provider
+ * marker is absent. Never invent either field from the request.
+ */
+export declare function completeForkChild(client: SandboxClientLike, child: SandboxInstanceLike, signal?: AbortSignal): Promise<SandboxInstanceLike | undefined>;
+export declare function findBlockingForks(box: SandboxInstanceLike, client: SandboxClientLike, provider: string, checkpointId: string, signal?: AbortSignal): Promise<string[] | undefined>;
+/**
+ * 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 child was cleaned after creation, and the provider must not
+ * resurrect it from the ledger. Every other state is undecided for the caller.
+ */
+export declare function lookupOutcomeFromSandbox(lookup: SandboxWorkspaceOperationLookupLike | undefined, kind: "fork"): {
+    absent: true;
+} | {
+    absent: false;
+    message: string;
+    retryable: boolean;
+};
+export declare function isoDate(value: Date | string): string;
+export {};