@bastani/atomic 0.9.11-alpha.5 → 0.9.11-alpha.7

package/dist/builtin/workflows/src/durable/tool-primitive.ts

@@ -16,42 +16,33 @@
  */
 
 import { runCallback } from "@bastani/atomic";
-import type { WorkflowSerializableValue } from "../shared/types.js";
+import { field, hasProcessFailureEvidence, normalizeCode } from "../shared/workflow-failures-signals.js";
+import type { ToolNodeSnapshot } from "../shared/store-types.js";
+import type {
+  WorkflowSerializableValue,
+  WorkflowToolOptions,
+  WorkflowToolOutcome,
+  WorkflowToolPrimitive,
+} from "../shared/types.js";
 import type { DurableWorkflowBackend } from "./backend.js";
 import { durableHash } from "./backend.js";
-import type { DurableCheckpoint, DurableToolCheckpoint } from "./types.js";
+import {
+  replayedWorkflowToolOutcome,
+  workflowToolFailure,
+  workflowToolOutcomeFromValue,
+  workflowToolSuccess,
+} from "./tool-outcome.js";
+import { recordThrowingToolFailure } from "./tool-failure-checkpoint.js";
+import { DURABLE_TOOL_TOPOLOGY_VERSION, type DurableCheckpoint, type DurableStageRunTopology, type DurableToolCheckpoint } from "./types.js";
+export type { WorkflowToolOptions, WorkflowToolPrimitive } from "../shared/types.js";
 
-/**
- * Options for `ctx.tool(name, args, fn)`.
- */
-export interface WorkflowToolOptions {
-  /**
-   * When true, the tool function is retried on failure with exponential
-   * backoff. Defaults to false (matching DBOS step default).
-   */
-  readonly retriesAllowed?: boolean;
-  /** Max retry attempts when retriesAllowed is true. Default 3. */
-  readonly maxAttempts?: number;
-  /** Initial retry interval in ms. Default 1000. */
-  readonly intervalMs?: number;
-  /** Backoff multiplier. Default 2. */
-  readonly backoffRate?: number;
-}
+type WorkflowToolInvocationResult<TValue extends WorkflowSerializableValue> =
+  | TValue
+  | WorkflowToolOutcome<TValue>;
 
-/**
- * The `ctx.tool` primitive type exposed on {@link WorkflowRunContext}.
- *
- * @param name Tool name (for display and checkpoint identity).
- * @param args Tool arguments (JSON-serializable; included in the content hash).
- * @param fn The async function to execute. Its return must be JSON-serializable.
- * @param options Retry configuration.
- */
-export type WorkflowToolPrimitive = <T extends WorkflowSerializableValue>(
-  name: string,
-  args: Readonly<Record<string, WorkflowSerializableValue>>,
-  fn: () => Promise<T>,
-  options?: WorkflowToolOptions,
-) => Promise<T>;
+export type WorkflowToolExecutionAdmission =
+  | { readonly accepted?: true; bindNode(nodeId: string): void }
+  | { readonly accepted: false; readonly error: Error; bindNode(nodeId: string): void };
 
 export interface CreateToolPrimitiveInput {
   readonly workflowId: string;
@@ -62,6 +53,16 @@ export interface CreateToolPrimitiveInput {
   readonly throwIfCancelled: () => void;
   /** Optional signal for aborting retry backoff sleeps. */
   readonly signal?: AbortSignal;
+  /** Track the final logical execution promise and bind it to its graph node. */
+  readonly trackExecution?: <T>(execution: Promise<T>) => WorkflowToolExecutionAdmission | void;
+  /** Observe a logical throwing-mode failure before graph publication or promise rejection. */
+  readonly onFailureObserved?: (error: unknown, nodeId: string) => void;
+  /** Admit/update a first-class graph node around the durable call. */
+  readonly onNodeStart?: (node: ToolNodeSnapshot) => void;
+  readonly onNodeRunning?: (nodeId: string, startedAt: number) => void;
+  readonly onNodeEnd?: (nodeId: string, update: Pick<ToolNodeSnapshot, "status"> & Partial<Pick<ToolNodeSnapshot, "endedAt" | "resultSummary" | "error">>) => void;
+  readonly onNodeSettle?: (nodeId: string) => void;
+  readonly runTopology?: DurableStageRunTopology;
 }
 
 /**
@@ -69,53 +70,360 @@ export interface CreateToolPrimitiveInput {
  */
 export function createToolPrimitive(input: CreateToolPrimitiveInput): WorkflowToolPrimitive {
   const ordinals = new Map<string, number>();
-  return async <T extends WorkflowSerializableValue>(
+  return (<T extends WorkflowSerializableValue>(
     name: string,
     args: Readonly<Record<string, WorkflowSerializableValue>>,
     fn: () => Promise<T>,
     options?: WorkflowToolOptions,
-  ): Promise<T> => {
-    input.throwIfCancelled();
-    const callKey = durableHash({ name, args });
-    const ordinal = (ordinals.get(callKey) ?? 0) + 1;
-    ordinals.set(callKey, ordinal);
-    const argsHash = durableHash({ name, args, ordinal });
+  ): Promise<WorkflowToolInvocationResult<T>> => {
+    let resolveExecution!: (value: WorkflowToolInvocationResult<T> | PromiseLike<WorkflowToolInvocationResult<T>>) => void;
+    let rejectExecution!: (reason?: unknown) => void;
+    const execution = new Promise<WorkflowToolInvocationResult<T>>((resolve, reject) => {
+      resolveExecution = resolve;
+      rejectExecution = reject;
+    });
+    const admission = input.trackExecution?.(execution);
+    if (admission?.accepted === false) {
+      void execution.catch(() => undefined);
+      rejectExecution(admission.error);
+      return execution;
+    }
+    void executeToolInvocation(input, ordinals, name, args, fn, options, (nodeId) => admission?.bindNode(nodeId))
+      .then(resolveExecution, rejectExecution);
+    return execution;
+  }) as WorkflowToolPrimitive;
+}
 
-    // Check for cached result — completed side effects are not repeated.
-    const cached = input.backend.getToolOutput(input.workflowId, argsHash);
-    if (cached !== undefined) return cached as T;
+async function executeToolInvocation<T extends WorkflowSerializableValue>(
+  input: CreateToolPrimitiveInput,
+  ordinals: Map<string, number>,
+  name: string,
+  args: Readonly<Record<string, WorkflowSerializableValue>>,
+  fn: () => Promise<T>,
+  options: WorkflowToolOptions | undefined,
+  bindNode: (nodeId: string) => void,
+): Promise<WorkflowToolInvocationResult<T>> {
+  input.throwIfCancelled();
+  if (options?.retriesAllowed === true && options.maxAttempts !== undefined
+    && (!Number.isInteger(options.maxAttempts) || options.maxAttempts < 1)) {
+    throw new RangeError("atomic-workflows: ctx.tool maxAttempts must be a positive integer");
+  }
+  const returnFailure = options?.failureMode === "return";
+  const identityMode = returnFailure ? { failureMode: "return" as const } : {};
+  const callKey = durableHash({ name, args, ...identityMode });
+  const ordinal = (ordinals.get(callKey) ?? 0) + 1;
+  ordinals.set(callKey, ordinal);
+  const argsHash = durableHash({ name, args, ordinal, ...identityMode });
 
-    // Execute (with optional retries).
+  const cached = input.backend.getToolCheckpoint(input.workflowId, argsHash);
+  const node: ToolNodeSnapshot = {
+    kind: "tool",
+    id: cached?.topology?.nodeId ?? `tool:${argsHash}`,
+    name,
+    argsHash,
+    ordinal: cached?.topology?.ordinal ?? ordinal,
+    parentIds: Object.freeze(cached?.topology?.parentIds ?? []),
+    status: "pending",
+    ...(cached !== undefined && cached.topology === undefined ? { topologyState: "unavailable" as const } : {}),
+    ...(cached !== undefined ? { replayed: true } : {}),
+    ...(cached?.topology?.order !== undefined ? { executionOrder: cached.topology.order } : {}),
+    ...(cached?.topology?.startedAt !== undefined ? { startedAt: cached.topology.startedAt } : {}),
+    attachable: false,
+  };
+  bindNode(node.id);
+  input.onNodeStart?.(node);
+  if (cached !== undefined) {
+    const endedAt = cached.topology?.endedAt ?? cached.completedAt;
+    try {
+      await recordReplayedToolTopology(input, node, cached, argsHash, endedAt);
+      const returnedOutcome = cached.outcomeKind === undefined
+        ? undefined
+        : workflowToolOutcomeFromValue<T>(cached.output);
+      if (cached.outcomeKind !== undefined && returnedOutcome === undefined) {
+        throw new Error(`atomic-workflows: invalid durable return outcome for ctx.tool ${name}`);
+      }
+      const output = returnedOutcome === undefined
+        ? cached.output as T
+        : replayedWorkflowToolOutcome(returnedOutcome);
+      const failed = cached.outcomeKind === "return_failure";
+      input.onNodeEnd?.(node.id, {
+        status: failed ? "failed" : "cached",
+        endedAt,
+        ...(failed && returnedOutcome?.ok === false
+          ? { error: returnedOutcome.error.message }
+          : { resultSummary: summarizeToolResult(output) }),
+      });
+      input.onNodeSettle?.(node.id);
+      return output;
+    } catch (error) {
+      const status = input.signal?.aborted === true ? "cancelled" : "failed";
+      if (status === "failed") input.onFailureObserved?.(error, node.id);
+      input.onNodeEnd?.(node.id, { status, endedAt: Date.now(), error: error instanceof Error ? error.message : String(error) });
+      input.onNodeSettle?.(node.id);
+      throw error;
+    }
+  }
+  let callbackError: unknown;
+
+  const startedAt = Date.now();
+  let attempts = 0;
+  let callbackCompleted = false;
+  input.onNodeRunning?.(node.id, startedAt);
+  try {
     const result = await executeWithRetries(
-      () => runCallback(
-        { kind: "workflow.ctx_tool", name, runId: input.workflowId },
-        fn,
-      ),
+      () => {
+        attempts += 1;
+        return runCallback(
+          { kind: "workflow.ctx_tool", name, runId: input.workflowId },
+          fn,
+        ).catch((error: unknown) => {
+          callbackError = error;
+          throw error;
+        });
+      },
       options,
       input.throwIfCancelled,
       input.signal,
     );
+    callbackCompleted = true;
+    const output = returnFailure ? workflowToolSuccess(result, attempts, false) : result;
 
-    // Re-check cancellation after the tool function resolves but BEFORE the
-    // side-effect result is durably checkpointed/returned. A side effect that
-    // completes concurrently with a cancellation must not be recorded as a
-    // durable checkpoint that a resume would silently replay.
-    // cross-ref: issue #1498.
+    // Linearization policy: cancellation observed before persistence prevents
+    // a checkpoint. Once the durable write begins, a successful commit wins
+    // for this node; the root still observes its aborted signal and is killed.
     input.throwIfCancelled();
-
-    // Record the checkpoint durably.
+    const completedAt = Date.now();
     const checkpoint: DurableToolCheckpoint = {
       kind: "tool",
       workflowId: input.workflowId,
       checkpointId: `tool:${argsHash}`,
       name,
       argsHash,
-      output: result,
-      completedAt: Date.now(),
+      output,
+      ...(returnFailure ? { outcomeKind: "return_success" as const } : {}),
+      completedAt,
+      topology: {
+        version: DURABLE_TOOL_TOPOLOGY_VERSION,
+        nodeId: node.id,
+        ordinal,
+        order: node.executionOrder ?? 0,
+        parentIds: [...node.parentIds],
+        startedAt,
+        endedAt: completedAt,
+        ...(input.runTopology !== undefined ? { run: { ...input.runTopology } } : {}),
+      },
     };
     await recordCheckpointDurably(input.backend, checkpoint);
-    return result;
-  };
+    input.onNodeEnd?.(node.id, { status: "completed", endedAt: completedAt, resultSummary: summarizeToolResult(output) });
+    input.onNodeSettle?.(node.id);
+    return output;
+  } catch (error) {
+    try {
+      throwIfInvocationCancelled(input);
+    } catch (cancelledError) {
+      input.onNodeEnd?.(node.id, {
+        status: "cancelled",
+        endedAt: Date.now(),
+        error: cancelledError instanceof Error ? cancelledError.message : String(cancelledError),
+      });
+      input.onNodeSettle?.(node.id);
+      throw cancelledError;
+    }
+    const callbackFailure = callbackError ?? error;
+    if (returnFailure && !callbackCompleted && isExplicitCallbackCancellation(callbackFailure)) {
+      input.onFailureObserved?.(callbackFailure, node.id);
+      const failure = await recordThrowingToolFailure(
+        input,
+        node,
+        { name, argsHash, ordinal, startedAt },
+        callbackFailure,
+        attempts,
+      );
+      input.onNodeEnd?.(node.id, { status: "failed", endedAt: failure.failedAt, error: failure.message });
+      input.onNodeSettle?.(node.id);
+      throw callbackFailure;
+    }
+    if (returnFailure && !callbackCompleted) {
+      const outcome = workflowToolFailure(callbackFailure, attempts, false);
+      const completedAt = Date.now();
+      const checkpoint: DurableToolCheckpoint = {
+        kind: "tool",
+        workflowId: input.workflowId,
+        checkpointId: `tool:${argsHash}`,
+        name,
+        argsHash,
+        output: outcome,
+        outcomeKind: "return_failure",
+        completedAt,
+        topology: {
+          version: DURABLE_TOOL_TOPOLOGY_VERSION,
+          nodeId: node.id,
+          ordinal,
+          order: node.executionOrder ?? 0,
+          parentIds: [...node.parentIds],
+          startedAt,
+          endedAt: completedAt,
+          ...(input.runTopology !== undefined ? { run: { ...input.runTopology } } : {}),
+        },
+      };
+      try {
+        await recordCheckpointDurably(input.backend, checkpoint);
+      } catch (persistenceError) {
+        input.onFailureObserved?.(persistenceError, node.id);
+        input.onNodeEnd?.(node.id, {
+          status: "failed",
+          endedAt: Date.now(),
+          error: persistenceError instanceof Error ? persistenceError.message : String(persistenceError),
+        });
+        input.onNodeSettle?.(node.id);
+        throw persistenceError;
+      }
+      input.onNodeEnd?.(node.id, { status: "failed", endedAt: completedAt, error: outcome.error.message });
+      input.onNodeSettle?.(node.id);
+      throwIfInvocationCancelled(input);
+      return outcome;
+    }
+    input.onFailureObserved?.(error, node.id);
+    const failure = await recordThrowingToolFailure(
+      input,
+      node,
+      { name, argsHash, ordinal, startedAt },
+      error,
+      attempts,
+    );
+    input.onNodeEnd?.(node.id, { status: "failed", endedAt: failure.failedAt, error: failure.message });
+    input.onNodeSettle?.(node.id);
+    throw error;
+  }
+}
+
+function throwIfInvocationCancelled(input: CreateToolPrimitiveInput): void {
+  input.throwIfCancelled();
+  if (!input.signal?.aborted) return;
+  throw input.signal.reason instanceof Error
+    ? input.signal.reason
+    : new Error("atomic-workflows: workflow cancelled");
+}
+
+const CALLBACK_CANCELLATION_NAMES = new Set([
+  "aborterror",
+  "aborted",
+  "cancelederror",
+  "cancellederror",
+  "canceled",
+  "cancelled",
+]);
+const CALLBACK_CANCELLATION_CODES = new Set([
+  "aborterror",
+  "abort_err",
+  "aborted",
+  "canceled",
+  "cancelled",
+  "ecanceled",
+  "ecancelled",
+  "err_canceled",
+  "err_cancelled",
+]);
+const CALLBACK_CANCELLATION_STOP_REASONS = new Set(["aborted", "canceled", "cancelled"]);
+
+function safeCancellationField(error: unknown, key: string): unknown {
+  try {
+    return field(error, key);
+  } catch {
+    return undefined;
+  }
+}
+
+function hasCancellationMarker(markers: ReadonlySet<string>, value: unknown): boolean {
+  return (typeof value === "string" || typeof value === "number")
+    && markers.has(normalizeCode(value) ?? "");
+}
+
+function isExplicitCallbackCancellation(error: unknown): boolean {
+  const seen = new Set<object>();
+  const pending: Array<{ readonly value: unknown; readonly depth: number }> = [{ value: error, depth: 0 }];
+  while (pending.length > 0) {
+    const current = pending.pop()!;
+    if (current.value === undefined || current.value === null || current.depth >= 8) continue;
+    if (typeof current.value === "object") {
+      if (seen.has(current.value)) continue;
+      seen.add(current.value);
+    }
+    const hasProcessFailure = hasProcessFailureEvidence(current.value);
+    if (!hasProcessFailure
+      && hasCancellationMarker(CALLBACK_CANCELLATION_NAMES, safeCancellationField(current.value, "name"))) return true;
+    if (!hasProcessFailure
+      && hasCancellationMarker(CALLBACK_CANCELLATION_STOP_REASONS, safeCancellationField(current.value, "stopReason"))) return true;
+    if (!hasProcessFailure
+      && hasCancellationMarker(CALLBACK_CANCELLATION_CODES, safeCancellationField(current.value, "code"))) return true;
+
+    for (const key of ["cause", "error", "response", "body"] as const) {
+      pending.push({ value: safeCancellationField(current.value, key), depth: current.depth + 1 });
+    }
+    for (const key of ["diagnostics", "errors"] as const) {
+      const entries = safeCancellationField(current.value, key);
+      if (!Array.isArray(entries)) continue;
+      for (const entry of entries) {
+        pending.push({
+          value: key === "diagnostics" ? safeCancellationField(entry, "error") ?? entry : entry,
+          depth: current.depth + 1,
+        });
+      }
+    }
+  }
+  return false;
+}
+
+async function recordReplayedToolTopology(
+  input: CreateToolPrimitiveInput,
+  node: ToolNodeSnapshot,
+  cached: DurableToolCheckpoint,
+  argsHash: string,
+  endedAt: number,
+): Promise<void> {
+  const runTopology = input.runTopology;
+  if (runTopology === undefined) return;
+  if (cached.topology === undefined && runTopology.parentRunId === undefined) return;
+  if (cached.topology?.run?.runId === runTopology.runId) return;
+  const topology = cached.topology === undefined
+    ? {
+        version: DURABLE_TOOL_TOPOLOGY_VERSION,
+        nodeId: node.id,
+        ordinal: node.ordinal,
+        order: node.executionOrder ?? 0,
+        parentIds: [...node.parentIds],
+        endedAt,
+        run: { ...runTopology },
+      }
+    : {
+        ...cached.topology,
+        parentIds: [...node.parentIds],
+        order: node.executionOrder ?? cached.topology.order,
+        endedAt,
+        run: { ...runTopology },
+      };
+  const unchanged = cached.topology !== undefined
+    && JSON.stringify(cached.topology.parentIds) === JSON.stringify(topology.parentIds)
+    && JSON.stringify(cached.topology.run) === JSON.stringify(topology.run)
+    && cached.topology.endedAt === topology.endedAt;
+  if (unchanged) return;
+  await input.backend.recordAdditiveCheckpointBestEffort({
+    kind: "tool",
+    workflowId: input.workflowId,
+    checkpointId: `tool-replay-meta:${durableHash({ argsHash, topology })}`,
+    name: node.name,
+    argsHash,
+    output: cached.output,
+    ...(cached.outcomeKind !== undefined ? { outcomeKind: cached.outcomeKind } : {}),
+    completedAt: Date.now(),
+    topology,
+  });
+  input.throwIfCancelled();
+}
+function summarizeToolResult(value: WorkflowSerializableValue): string {
+  const serialized = JSON.stringify(value);
+  if (serialized === undefined) return String(value).slice(0, 240);
+  return serialized.length <= 240 ? serialized : `${serialized.slice(0, 237)}...`;
 }
 
 export async function recordCheckpointDurably(backend: DurableWorkflowBackend, checkpoint: DurableCheckpoint): Promise<void> {
@@ -140,6 +448,7 @@ async function executeWithRetries<T>(
     try {
       return await fn();
     } catch (err) {
+      if (isExplicitCallbackCancellation(err)) throw err;
       lastError = err instanceof Error ? err : new Error(String(err));
       if (attempt < maxAttempts) {
         await sleepOrAbort(delay, signal);

package/dist/builtin/workflows/src/durable/types.ts

@@ -9,6 +9,7 @@
  * cross-ref: issue #1498
  */
 
+import type { WorkflowFailureCode, WorkflowFailureDisposition, WorkflowFailureKind, WorkflowFailureRecoverability } from "../shared/store-types.js";
 import type { WorkflowModelAttempt, WorkflowSerializableValue } from "../shared/types.js";
 
 // ---------------------------------------------------------------------------
@@ -52,6 +53,12 @@ export interface DurableWorkflowHandle {
   readonly rootWorkflowId?: string;
   /** Explicit resumability flag for failed/blocked runs. */
   readonly resumable?: boolean;
+  readonly error?: string;
+  readonly failureKind?: WorkflowFailureKind;
+  readonly failureCode?: WorkflowFailureCode;
+  readonly failureRecoverability?: WorkflowFailureRecoverability;
+  readonly failureDisposition?: WorkflowFailureDisposition;
+  readonly failedToolNodeId?: string;
   /** Executor id of the Atomic process that last wrote this workflow's metadata. */
   readonly ownerExecutorId?: string;
 }
@@ -77,6 +84,20 @@ export type DurableCheckpoint = DurableToolCheckpoint | DurableUiCheckpoint | Du
 
 export type DurableCheckpointKind = "tool" | "ui" | "stage";
 
+export const DURABLE_TOOL_TOPOLOGY_VERSION = 1 as const;
+
+export interface DurableToolTopology {
+  readonly version: typeof DURABLE_TOOL_TOPOLOGY_VERSION;
+  readonly nodeId: string;
+  readonly ordinal: number;
+  readonly order: number;
+  readonly parentIds: readonly string[];
+  readonly startedAt?: number;
+  /** Original terminal timestamp; replay metadata may be written later. */
+  readonly endedAt?: number;
+  readonly run?: DurableStageRunTopology;
+}
+
 /** A `ctx.tool(...)` result cached durably. */
 export interface DurableToolCheckpoint {
   readonly kind: "tool";
@@ -89,7 +110,13 @@ export interface DurableToolCheckpoint {
   readonly argsHash: string;
   /** Cached tool output (JSON-serializable). */
   readonly output: WorkflowSerializableValue;
+  /** Explicit return-mode result kind; absent for legacy/default successful tools. */
+  readonly outcomeKind?: "return_success" | "return_failure";
+  /** Inspection-only error for a throwing-mode failure; never used as a replay cache hit. */
+  readonly throwingFailureError?: string;
   readonly completedAt: number;
+  /** Additive graph topology; omitted by pre-#1991 checkpoints. */
+  readonly topology?: DurableToolTopology;
 }
 
 /** A `ctx.ui.*` user response cached durably. */
@@ -110,6 +137,45 @@ export interface DurableUiCheckpoint {
 
 export const DURABLE_STAGE_TOPOLOGY_VERSION = 1 as const;
 
+export const DURABLE_BOUNDARY_TOPOLOGY_VERSION = 1 as const;
+
+export type DurableStageLifecycleStatus =
+  | "pending"
+  | "running"
+  | "awaiting_input"
+  | "paused"
+  | "blocked"
+  | "completed"
+  | "failed"
+  | "skipped";
+
+export interface DurableBoundaryChildTopology {
+  readonly runId: string;
+  readonly runName: string;
+  readonly parentRunId: string;
+  readonly parentStageId: string;
+  readonly rootRunId: string;
+}
+
+interface DurableWorkflowBoundaryIdentity {
+  readonly version: typeof DURABLE_BOUNDARY_TOPOLOGY_VERSION;
+  readonly replayScope: string;
+  readonly alias: string;
+  readonly workflow: string;
+  /** Definition + exact validated inputs; absent only on compatible completed legacy records. */
+  readonly invocationFingerprint?: string;
+  readonly child: DurableBoundaryChildTopology;
+}
+
+/** Additive identity record written before a nested workflow can execute. */
+export type DurableWorkflowBoundaryTopology = DurableWorkflowBoundaryIdentity & (
+  | { readonly event: "start"; readonly status: "running" }
+  | {
+      readonly event: "terminal";
+      readonly status: Extract<DurableStageLifecycleStatus, "completed" | "failed" | "skipped">;
+    }
+);
+
 /** Durable ownership metadata needed to rebuild nested workflow runs. */
 export interface DurableStageRunTopology {
   readonly runId: string;
@@ -124,8 +190,18 @@ export interface DurableStageTopology {
   readonly version: typeof DURABLE_STAGE_TOPOLOGY_VERSION;
   readonly stageId: string;
   readonly parentIds: readonly string[];
+  /** Zero-based source/spawn order within the owning run. */
+  readonly sourceOrder?: number;
+  /** Distinguishes one durable prompt-node occurrence from its logical continuation replay key. */
+  readonly occurrenceKey?: string;
+  /** Actual stage lifecycle state represented by this checkpoint. */
+  readonly status?: DurableStageLifecycleStatus;
+  /** Shared admission order with durable tool nodes. */
+  readonly order?: number;
   /** Owning run and boundary linkage for nested workflow graph reconstruction. */
   readonly run?: DurableStageRunTopology;
+  /** Present only for durable nested-workflow boundary records. */
+  readonly boundary?: DurableWorkflowBoundaryTopology;
 }
 
 /** A `ctx.stage(...)` / `ctx.task(...)` durable checkpoint or resumable session marker. */
@@ -188,6 +264,12 @@ export interface DurableWorkflowMetadata {
   readonly transitionClaimId?: string;
   readonly sessionFile?: string;
   readonly label?: string;
+  readonly error?: string;
+  readonly failureKind?: WorkflowFailureKind;
+  readonly failureCode?: WorkflowFailureCode;
+  readonly failureRecoverability?: WorkflowFailureRecoverability;
+  readonly failureDisposition?: WorkflowFailureDisposition;
+  readonly failedToolNodeId?: string;
   readonly rootWorkflowId?: string;
   readonly resumable?: boolean;
   readonly invocationCwd?: string;
@@ -207,6 +289,12 @@ export interface ResumableWorkflowEntry {
   readonly pendingPrompts: number;
   readonly sessionFile?: string;
   readonly label?: string;
+  readonly error?: string;
+  readonly failureKind?: WorkflowFailureKind;
+  readonly failureCode?: WorkflowFailureCode;
+  readonly failureRecoverability?: WorkflowFailureRecoverability;
+  readonly failureDisposition?: WorkflowFailureDisposition;
+  readonly failedToolNodeId?: string;
   readonly rootWorkflowId?: string;
   readonly resumable?: boolean;
   readonly invocationCwd?: string;
@@ -216,3 +304,12 @@ export interface ResumableWorkflowEntry {
   readonly createdAt: number;
   readonly updatedAt: number;
 }
+
+export interface DurableWorkflowFailureMetadata {
+  readonly error: string;
+  readonly failureKind?: WorkflowFailureKind;
+  readonly failureCode?: WorkflowFailureCode;
+  readonly failureRecoverability?: WorkflowFailureRecoverability;
+  readonly failureDisposition?: WorkflowFailureDisposition;
+  readonly failedToolNodeId?: string;
+}