@lostgradient/weft 0.2.1 → 0.3.0

package/dist/core/engine/termination/cleanup.js

@@ -8,7 +8,11 @@ export const TERMINAL_WORKFLOW_STATUSES = new Set([
   "failed",
   "cancelled",
   "timed-out"
-]);
+]), FORCIBLY_TERMINABLE_STATUSES = [
+  "running",
+  "pending",
+  "suspended"
+];
 function selectTrackedWaiterMaps(internals, kind) {
   return {
     signal: () => ({
@@ -48,6 +52,14 @@ function cleanupSleepResolvers(internals, workflowId) {
   }
   internals.sleepResolversByWorkflow.delete(workflowId);
 }
+function evictSleepResolversWithoutResolving(internals, workflowId) {
+  const sleepOps = internals.sleepResolversByWorkflow.get(workflowId);
+  if (!sleepOps)
+    return;
+  for (const operationId of sleepOps)
+    internals.sleepResolvers.delete(`${workflowId}:${operationId}`);
+  internals.sleepResolversByWorkflow.delete(workflowId);
+}
 function cleanupReviewEscalations(internals, workflowId, callbacks) {
   const reviewIds = internals.workflowReviewIds.get(workflowId);
   if (!reviewIds)
@@ -74,6 +86,12 @@ export function cleanupWaiters(internals, workflowId, callbacks) {
   internals.workflowServices.delete(workflowId);
   internals.workflowTypeByWorkflowId.delete(workflowId);
 }
+export function evictSuspendedWorkflowWaiters(internals, workflowId, callbacks) {
+  for (const kind of TRACKED_WAITER_KINDS)
+    cleanupTrackedWaiter(internals, workflowId, kind);
+  evictSleepResolversWithoutResolving(internals, workflowId);
+  cleanupReviewEscalations(internals, workflowId, callbacks);
+}
 export async function cleanupWorkflowStorage(internals, workflowId, includeOutputArtifacts) {
   const encodedWorkflowId = encodeStorageKeyComponent(workflowId), prefixes = [
     KEYS.activityReconciliationPrefix(workflowId),

package/dist/core/engine/termination/complete.js

@@ -26,7 +26,8 @@ import { buildWorkflowVisibilityIndexTransition } from "../workflow-indexes.js";
 import {
   cleanupTerminalWorkflowImmediately,
   cleanupTerminalWorkflowSynchronously,
-  finalizeScheduledWorkflowTerminal
+  finalizeScheduledWorkflowTerminal,
+  FORCIBLY_TERMINABLE_STATUSES
 } from "./cleanup.js";
 async function runCancelHandlers(handlers, callbacks, workflowId) {
   for (const handler of handlers)
@@ -54,7 +55,7 @@ export async function terminateWorkflow(internals, workflowId, status, callbacks
   internals.strategy.cancelWorkflow(workflowId);
   try {
     const attributeBytes = await internals.storage.get(KEYS.attribute(workflowId)), attributes = attributeBytes ? decode(attributeBytes) : {}, retainedAttributes = buildRetainedTerminalSearchAttributes(attributes), terminationMessage = status === "timed-out" ? "Workflow timed out" : "Workflow cancelled", terminationResult = await updateWorkflowState(internals, workflowId, { status, ...reason !== void 0 ? { terminationReason: reason } : {} }, {
-      allowedStatuses: ["running", "pending"],
+      allowedStatuses: FORCIBLY_TERMINABLE_STATUSES,
       buildAdditionalOperations: (_previousState, updatedAt) => {
         finalizePendingTimelineEntry(internals, workflowId, status, terminationMessage, updatedAt);
         const pendingTimelineOperation = buildPendingTimelineOperation(internals, workflowId);
@@ -182,7 +183,7 @@ export async function failWorkflow(internals, workflowId, error, callbacks, fail
   if (error.stack !== void 0)
     stateUpdate.errorStack = error.stack;
   if (!await updateWorkflowState(internals, workflowId, stateUpdate, {
-    allowedStatuses: ["running", "pending"],
+    allowedStatuses: FORCIBLY_TERMINABLE_STATUSES,
     buildAdditionalOperations: (_previousState, updatedAt) => {
       finalizePendingTimelineEntry(internals, workflowId, "failed", error.message, updatedAt);
       const pendingTimelineOperation = buildPendingTimelineOperation(internals, workflowId);

package/dist/core/engine/termination/suspend.d.ts

@@ -0,0 +1,68 @@
+import type { EngineInternals } from '../internals.ts';
+import { type TerminationCallbacks } from './cleanup.ts';
+/**
+ * Suspend a running workflow without terminating it: a non-terminal cousin of
+ * {@link terminateWorkflow}. The workflow's status transitions `running →
+ * suspended`, its durable checkpoint is preserved, and it becomes resumable via
+ * `engine.resume(id)` / `handle.resume()`. Suspension is client-driven
+ * preemption, so — unlike a fault — a suspended workflow is NOT auto-recovered
+ * by `engine.recoverAll()`.
+ *
+ * Contrast with cancel/timeout, which this deliberately does NOT do:
+ * - does NOT abort the workflow's `AbortController` — suspend is a pause, not a
+ *   cancellation, so user code observing `ctx.signal.aborted` or registered
+ *   abort listeners must not fire. The live inline run is *parked*
+ *   (`parkWorkflow`: evict execution state without aborting), the same primitive
+ *   the engine uses for signal-parking,
+ * - does NOT run cancel handlers,
+ * - does NOT settle the result promise (`handle.result()` stays pending until a
+ *   later `resume()` drives the run to completion, or a `cancel()` terminates it),
+ * - does NOT clean up durable output artifacts or in-memory services (the
+ *   `services` value is preserved so an in-process `resume()` can reuse it),
+ * - does NOT schedule terminal cleanup.
+ *
+ * The CAS status flip and the in-memory teardown both run inside one serialized
+ * per-workflow write section with `allowedStatuses: ['running']`. If the
+ * workflow already left `running` (it completed, failed, or a concurrent cancel
+ * won the race), the flip is skipped and suspend is a no-op — and because the
+ * teardown is gated on the flip succeeding, a workflow that lost the race keeps
+ * its execution state intact.
+ *
+ * The teardown evicts every piece of in-memory execution state that could let a
+ * post-suspend operation drive the parked run: the inline context/generator (via
+ * `parkWorkflow`), the in-memory checkpoint, the parked-inline marker, and the
+ * in-flight operation waiters (signal/update/sleep/review — deleted, NOT
+ * resolved, so a signal arriving after suspend buffers durably and is replayed
+ * on resume instead of waking a dormant operation loop against the gone
+ * generator). The durable checkpoint, durable buffered signals, durable sleep
+ * timers, and `workflowServices` are all left intact for resume.
+ *
+ * A signal that races the in-lock teardown is benign: `continueWorkflow` no-ops
+ * for an evicted generator, and `persistCheckpoint` no-ops when the context and
+ * in-memory checkpoint are gone — so no step can commit past the suspend point.
+ *
+ * `'suspended'` is neither `'running'` nor `'pending'`, and both local-ownership
+ * predicates (`isInlineWorkflowLocallyOwned`, `hasLocalCheckpointOwnership`) are
+ * gated on those two statuses. So once the status flips, the workflow stops
+ * registering as locally owned — which is exactly what makes `recoverAll()` skip
+ * it AND what lets `engine.resume()` re-drive it from storage instead of taking
+ * its local-ownership early return.
+ *
+ * The execution deadline is absolute wall-clock time: suspension does NOT extend
+ * it. The pending `deadline:` timer is deleted durably IN THE SAME COMMIT BATCH
+ * as the status flip, and re-armed at the same absolute fire time on resume (or
+ * fires immediately if already past). It is a durable delete rather than a
+ * `scheduler.cancel()` call because the scheduler is durable-scan-based and
+ * resume's re-arm is likewise durable-only (`buildTimerBatchOperations`); folding
+ * the delete into the commit makes it atomic with the flip and ordered before any
+ * concurrent resume, so an immediate resume cannot have its freshly re-armed
+ * deadline deleted by a late fire-and-forget cancel.
+ *
+ * Worker execution mode is not supported: a worker run cannot be parked without
+ * sending it a cancellation. To keep the contract state-dependent (suspend on a
+ * non-running workflow is always a no-op), the mode check runs only AFTER the
+ * status load confirms the workflow is `running`; a `running` worker workflow
+ * throws {@link WorkflowSuspendNotSupportedError}, while a completed or unknown
+ * one is a no-op regardless of execution mode.
+ */
+export declare function suspendWorkflow(internals: EngineInternals, workflowId: string, callbacks: TerminationCallbacks): Promise<void>;

package/dist/core/engine/termination/suspend.js

@@ -0,0 +1,41 @@
+import { KEYS } from "../../../storage/interface.js";
+import { encode } from "../../codec.js";
+import { WorkflowSuspendedEvent } from "../../events.js";
+import { WorkflowSuspendNotSupportedError } from "../errors.js";
+import { dropQueuedInlineWorkflowStart } from "../inline-launch-queue.js";
+import { buildWorkflowVisibilityIndexTransition } from "../workflow-indexes.js";
+import { evictSuspendedWorkflowWaiters } from "./cleanup.js";
+export async function suspendWorkflow(internals, workflowId, callbacks) {
+  if (!await callbacks.runSerializedWorkflowStateWrite(workflowId, async () => {
+    const state = await callbacks.loadWorkflowState(workflowId);
+    if (!state || state.status !== "running")
+      return !1;
+    if (internals.inlineStrategy === null)
+      throw new WorkflowSuspendNotSupportedError("suspend is only supported in inline execution mode; a worker run cannot be paused without cancelling it.");
+    internals.inlineStrategy.parkWorkflow(workflowId);
+    dropQueuedInlineWorkflowStart(internals, workflowId);
+    internals.checkpoints.delete(workflowId);
+    internals.parkedInlineWorkflows.delete(workflowId);
+    evictSuspendedWorkflowWaiters(internals, workflowId, callbacks);
+    const updatedAt = internals.options.getNow(), updatedState = { ...state, status: "suspended", updatedAt };
+    await callbacks.commitWorkflowStateOperations(state, [
+      { type: "put", key: KEYS.workflow(workflowId), value: encode(updatedState) },
+      ...buildWorkflowVisibilityIndexTransition(workflowId, state, updatedState).batchOps,
+      ...buildDeadlineTimerDeleteOperations(workflowId, state.executionDeadline)
+    ]);
+    return !0;
+  }))
+    return;
+  const event = new WorkflowSuspendedEvent(workflowId);
+  callbacks.dispatchEvent(event);
+  callbacks.forwardEventToHandle(workflowId, event);
+}
+function buildDeadlineTimerDeleteOperations(workflowId, executionDeadline) {
+  if (executionDeadline === void 0)
+    return [];
+  const timerId = `deadline:${workflowId}`;
+  return [
+    { type: "delete", key: KEYS.deadline(executionDeadline, timerId) },
+    { type: "delete", key: `timer-idx:${timerId}` }
+  ];
+}

package/dist/core/engine/termination.d.ts

@@ -1,7 +1,9 @@
 /**
  * Thin barrel over the split termination modules. Keeps existing import paths
  * (`./termination.ts`) working while the implementation lives in
- * `./termination/cleanup.ts` and `./termination/complete.ts`.
+ * `./termination/cleanup.ts`, `./termination/complete.ts`, and
+ * `./termination/suspend.ts`.
  */
-export { TERMINAL_WORKFLOW_STATUSES, cleanupTerminalWorkflowDurableState, cleanupTerminalWorkflowImmediately, cleanupTerminalWorkflowMemory, cleanupTerminalWorkflowSynchronously, cleanupWaiters, cleanupWorkflowStorage, finalizeScheduledWorkflowTerminal, handleCleanupError, runDeferredTerminalCleanup, type TerminationCallbacks, } from './termination/cleanup.ts';
+export { TERMINAL_WORKFLOW_STATUSES, cleanupTerminalWorkflowDurableState, cleanupTerminalWorkflowImmediately, cleanupTerminalWorkflowMemory, cleanupTerminalWorkflowSynchronously, cleanupWaiters, cleanupWorkflowStorage, evictSuspendedWorkflowWaiters, finalizeScheduledWorkflowTerminal, handleCleanupError, runDeferredTerminalCleanup, type TerminationCallbacks, } from './termination/cleanup.ts';
 export { buildPendingTimelineOperation, buildTerminalCleanupTimerOperations, cancelWorkflow, completeWorkflow, ensureTerminalCleanupTracked, failWorkflow, finalizePendingTimelineEntry, terminateWorkflow, timeoutWorkflow, } from './termination/complete.ts';
+export { suspendWorkflow } from './termination/suspend.ts';

package/dist/core/engine/termination.js

@@ -6,6 +6,7 @@ export {
   cleanupTerminalWorkflowSynchronously,
   cleanupWaiters,
   cleanupWorkflowStorage,
+  evictSuspendedWorkflowWaiters,
   finalizeScheduledWorkflowTerminal,
   handleCleanupError,
   runDeferredTerminalCleanup
@@ -21,3 +22,4 @@ export {
   terminateWorkflow,
   timeoutWorkflow
 } from "./termination/complete.js";
+export { suspendWorkflow } from "./termination/suspend.js";

package/dist/core/engine/validation.js

@@ -2,6 +2,7 @@ import { decode } from "../codec.js";
 import { isRecord } from "../debug-output.js";
 import { normalizeFailureCategory } from "../failure-categories.js";
 import { coerceStartWorkflowId, parseStartWorkflowDuration } from "../start-workflow-validation.js";
+import { DEFAULT_WORKFLOW_VERSION } from "../versioning.js";
 import { isWorkflowTagArray } from "../workflow-tags.js";
 const WORKFLOW_TIMELINE_STATUSES = new Set([
   "running",
@@ -55,7 +56,10 @@ export function isValidDecodedTags(value) {
   return value === void 0 || isWorkflowTagArray(value);
 }
 export function decodeWorkflowState(bytes) {
-  const state = decode(bytes);
+  const decoded = decode(bytes);
+  if (isRecord(decoded))
+    liftFlatVersionTuple(decoded);
+  const state = decoded;
   if ("tenant" in state)
     delete state.tenant;
   if (!isValidDecodedTags(state.tags)) {
@@ -78,6 +82,26 @@ export function decodeWorkflowState(bytes) {
     }
   return state;
 }
+function liftFlatVersionTuple(record) {
+  const flatVersion = record.version, hasFlatVersion = typeof flatVersion === "string";
+  if (isWorkflowVersionTuple(record.versionTuple)) {
+    delete record.version;
+    delete record.agentVersion;
+    delete record.toolVersions;
+    return;
+  }
+  const { agentVersion: flatAgentVersion, toolVersions: flatToolVersions } = record, versionTuple = {
+    workflowVersion: hasFlatVersion ? flatVersion : DEFAULT_WORKFLOW_VERSION,
+    ...typeof flatAgentVersion === "string" && { agentVersion: flatAgentVersion },
+    ...Array.isArray(flatToolVersions) && flatToolVersions.every((entry) => typeof entry === "string") && {
+      toolVersions: flatToolVersions
+    }
+  };
+  record.versionTuple = versionTuple;
+  delete record.version;
+  delete record.agentVersion;
+  delete record.toolVersions;
+}
 export function normalizeRetentionDuration(value, fieldName) {
   if (value === void 0)
     return;

package/dist/core/engine/workflow-feed.d.ts

@@ -7,9 +7,11 @@ import type { EngineInternals } from './internals.ts';
  */
 export type WorkflowFeedSelector = 'events' | 'tokens';
 /**
- * Hard-coded stream key for the `tokens` selector. Matches the
- * legacy REST SSE endpoint's key so resumption cursors round-trip
- * across transports.
+ * Hard-coded stream key for the `tokens` selector. Every transport that
+ * exposes the token feed — `engine.getStreamChunks(id, 'tokens')` and the REST
+ * SSE / WebSocket stream-chunk routes layered on it — keys its stored chunks
+ * under this single value, so a resumption cursor issued by one transport
+ * round-trips through another.
  */
 export declare const TOKENS_STREAM_KEY = "tokens";
 /** Record `kind` for every token stream chunk emitted by the feed. */

package/dist/core/events/event-map.d.ts

@@ -4,7 +4,7 @@ import type { AttributesChangedEvent } from './attribute-events.ts';
 import type { SignalDeliveredEvent, SignalReceivedEvent } from './signal-events.ts';
 import type { AlertFiredEvent, AlertResolvedEvent, CheckpointSizeWarningEvent, CleanupWarningEvent, ConstraintViolatedEvent, DevelopmentWarningEvent, StorageSizeReportedEvent } from './system-events.ts';
 import type { UpdateCompletedEvent, UpdateReceivedEvent } from './update-events.ts';
-import type { WorkflowCancelledEvent, WorkflowCompletedEvent, WorkflowFailedEvent, WorkflowRecoverySkippedEvent, WorkflowResumedEvent, WorkflowStartedEvent, WorkflowTimedOutEvent } from './workflow-events.ts';
+import type { WorkflowCancelledEvent, WorkflowCompletedEvent, WorkflowFailedEvent, WorkflowRecoverySkippedEvent, WorkflowResumedEvent, WorkflowStartedEvent, WorkflowSuspendedEvent, WorkflowTimedOutEvent } from './workflow-events.ts';
 /**
  * Record mapping each event-name string the {@link Engine} dispatches to its
  * corresponding typed `Event` subclass. Use this as the type parameter for
@@ -31,6 +31,7 @@ export type WeftEventMap = {
     'workflow:cancelled': WorkflowCancelledEvent;
     'workflow:timed-out': WorkflowTimedOutEvent;
     'workflow:resumed': WorkflowResumedEvent;
+    'workflow:suspended': WorkflowSuspendedEvent;
     'workflow:recovery-skipped': WorkflowRecoverySkippedEvent;
     'activity:started': ActivityStartedEvent;
     'activity:completed': ActivityCompletedEvent;

package/dist/core/events/workflow-events.d.ts

@@ -160,6 +160,29 @@ export declare class WorkflowResumedEvent extends Event {
     readonly fromStep: number;
     constructor(workflowId: string, fromStep: number);
 }
+/**
+ * Fired when a running workflow is explicitly suspended via
+ * `handle.suspend()` / `engine.suspend(id)`. Suspension is a non-terminal pause:
+ * the workflow keeps its checkpoint and is later resumable. This event is
+ * intentionally NOT in {@link WORKFLOW_TERMINAL_EVENT_TYPES} — a suspended
+ * workflow has not ended, and `handle.result()` stays pending.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowSuspendedEvent } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener('workflow:suspended', (e: Event) => {
+ *   const ev = e as WorkflowSuspendedEvent;
+ *   console.log('suspended', ev.workflowId);
+ * });
+ * ```
+ */
+export declare class WorkflowSuspendedEvent extends Event {
+    static readonly type: "workflow:suspended";
+    readonly workflowId: string;
+    constructor(workflowId: string);
+}
 /**
  * Reason carried by {@link WorkflowRecoverySkippedEvent}.
  *

package/dist/core/events/workflow-events.js

@@ -77,6 +77,15 @@ export class WorkflowResumedEvent extends Event {
   }
 }
 
+export class WorkflowSuspendedEvent extends Event {
+  static type = "workflow:suspended";
+  workflowId;
+  constructor(workflowId) {
+    super(WorkflowSuspendedEvent.type);
+    this.workflowId = workflowId;
+  }
+}
+
 export class WorkflowRecoverySkippedEvent extends Event {
   static type = "workflow:recovery-skipped";
   workflowId;

package/dist/core/list-filter-validation.js

@@ -7,7 +7,8 @@ const WORKFLOW_STATUSES = [
   "completed",
   "failed",
   "cancelled",
-  "timed-out"
+  "timed-out",
+  "suspended"
 ], ID_PREFIX_PATTERN = /^[A-Za-z0-9_-]+$/, workflowStatusSchema = z.enum(WORKFLOW_STATUSES), failureCategorySchema = z.enum(FAILURE_CATEGORIES), timeRangeSchema = z.object({
   gte: z.number().optional(),
   lte: z.number().optional(),

package/dist/core/start-workflow-validation.d.ts

@@ -2,11 +2,33 @@ import type { Duration } from './types.ts';
 import { WeftError } from './weft-error.ts';
 export declare const MAX_WORKFLOW_TAGS = 32;
 export declare const MAX_WORKFLOW_TAG_BYTES = 128;
+/**
+ * Upper bound on a start `idempotencyKey`, in UTF-8 bytes. `startOrSignal`
+ * derives a signal id of `start-idem:${key}` (an 11-byte prefix) from the key,
+ * and `validateSignalId` caps a signal id at 128 bytes — so the raw key must fit
+ * in `128 - 11 = 117` bytes for the derived id to stay within that ceiling.
+ */
+export declare const MAX_IDEMPOTENCY_KEY_BYTES = 117;
 export declare class StartWorkflowValidationError extends WeftError<'StartWorkflowValidationError'> {
     constructor(message: string);
 }
 export declare const assertExclusiveStartWorkflowOptions: (startAt: unknown, startAfter: unknown) => void;
 export declare const coerceStartWorkflowId: (value: unknown, fieldName: string) => string;
+/**
+ * Coerce a transport-supplied idempotency key to a non-empty string. The key is
+ * a caller-chosen dedup token (it becomes part of a `start-idem:` storage key),
+ * so an empty string — which would collide across unrelated starts — is rejected.
+ */
+export declare const coerceStartWorkflowIdempotencyKey: (value: unknown, fieldName: string) => string;
+/**
+ * Validate an already-string `idempotencyKey`: non-empty (an empty key would
+ * collide across unrelated starts under the shared `start-idem:` mapping) and at
+ * most {@link MAX_IDEMPOTENCY_KEY_BYTES} UTF-8 bytes (so the derived
+ * `start-idem:${key}` signal id stays within the signal-id ceiling). Shared by
+ * the transport coercion and the engine boundary so a direct `engine.start`
+ * caller gets the same guarantees as an HTTP caller.
+ */
+export declare const assertValidIdempotencyKey: (value: string, fieldName: string) => string;
 export declare function coerceStartWorkflowTimestamp(value: unknown, fieldName: string): number;
 export declare function parseStartWorkflowDuration(duration: Duration, fieldName: string): number;
 export declare function coerceStartWorkflowDuration(value: unknown, fieldName: string): Duration;

package/dist/core/start-workflow-validation.js

@@ -1,7 +1,7 @@
 import { parseDuration } from "./scheduler.js";
 import { WeftError } from "./weft-error.js";
 import { assertValidWorkflowId } from "./workflow-identifiers.js";
-export const MAX_WORKFLOW_TAGS = 32, MAX_WORKFLOW_TAG_BYTES = 128;
+export const MAX_WORKFLOW_TAGS = 32, MAX_WORKFLOW_TAG_BYTES = 128, MAX_IDEMPOTENCY_KEY_BYTES = 117;
 const textEncoder = new TextEncoder, EXCLUSIVE_START_WORKFLOW_OPTIONS_ERROR = "Provide only one of startAt or startAfter";
 
 export class StartWorkflowValidationError extends WeftError {
@@ -22,6 +22,16 @@ export const assertExclusiveStartWorkflowOptions = (startAt, startAfter) => {
     const message = error instanceof Error ? error.message : String(error);
     throw new StartWorkflowValidationError(message);
   }
+}, coerceStartWorkflowIdempotencyKey = (value, fieldName) => {
+  if (typeof value !== "string")
+    throw new StartWorkflowValidationError(`${fieldName} must be a string`);
+  return assertValidIdempotencyKey(value, fieldName);
+}, assertValidIdempotencyKey = (value, fieldName) => {
+  if (value.length === 0)
+    throw new StartWorkflowValidationError(`${fieldName} must not be empty`);
+  if (textEncoder.encode(value).byteLength > MAX_IDEMPOTENCY_KEY_BYTES)
+    throw new StartWorkflowValidationError(`${fieldName} must be at most ${MAX_IDEMPOTENCY_KEY_BYTES} UTF-8 bytes`);
+  return value;
 };
 export function coerceStartWorkflowTimestamp(value, fieldName) {
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)

package/dist/core/step-context.d.ts

@@ -7,19 +7,23 @@
  *
  * @module core/step-context
  */
-import type { ContextOperationRequest } from './context.ts';
 import type { StepWorkflowContext, WorkflowFunction } from './types.ts';
 interface QueuedOperation {
-    request: ContextOperationRequest;
+    /** Explicit, user-supplied step name. Used as the durable activity label. */
+    name: string;
+    /** The zero-argument step body. Executed by the engine as an inline activity. */
+    fn: () => unknown;
     resolve: (value: unknown) => void;
     reject: (reason: unknown) => void;
 }
 /**
  * Internal implementation of {@link StepWorkflowContext} for step-based
- * ("progressive disclosure") workflows. Wraps the generator protocol in a
- * queue so that plain `async function` workflows can be registered on the
- * engine without writing explicit generators. Build via
- * {@link compileStepWorkflow} rather than constructing directly.
+ * ("progressive disclosure") workflows. Each `step()` call is a thin async
+ * enqueue; the compiled generator (see {@link compileStepWorkflow}) drains the
+ * queue and runs each step through the engine's durable activity machinery, so
+ * a completed step is replayed from the checkpoint rather than re-executed
+ * after a crash. Build via {@link compileStepWorkflow} rather than constructing
+ * directly.
  *
  * @example
  * ```ts

package/dist/core/step-context.js

@@ -1,3 +1,5 @@
+import { asConcreteContext, runActivityWithRetry } from "./context/run-operation.js";
+
 export class StepContext {
   workflowId;
   signal;
@@ -9,18 +11,8 @@ export class StepContext {
     this.signal = signal;
   }
   async step(name, fn) {
-    const operationId = crypto.randomUUID(), { promise, resolve, reject } = Promise.withResolvers();
-    this.#queue.push({
-      request: {
-        type: "activity",
-        operationId,
-        activityName: name,
-        fn,
-        input: void 0
-      },
-      resolve,
-      reject
-    });
+    const { promise, resolve, reject } = Promise.withResolvers();
+    this.#queue.push({ name, fn, resolve, reject });
     this.#notifyQueue?.();
     return promise;
   }
@@ -43,8 +35,8 @@ export class StepContext {
   }
 }
 export function compileStepWorkflow(stepFunction) {
-  return async function* (_rawContext, input) {
-    const rawContext = _rawContext, stepContext = new StepContext(rawContext.workflowId, rawContext.signal);
+  return async function* (publicContext, input) {
+    const rawContext = asConcreteContext(publicContext), stepContext = new StepContext(rawContext.workflowId, rawContext.signal);
     let workflowResult, workflowError;
     const userPromise = stepFunction(stepContext, input).then((result) => {
       workflowResult = result;
@@ -59,7 +51,7 @@ export function compileStepWorkflow(stepFunction) {
       if (queued === null)
         break;
       try {
-        const result = yield queued.request;
+        const result = yield* runActivityWithRetry(rawContext, queued.fn, [], queued.name);
         queued.resolve(result);
       } catch (error) {
         queued.reject(error);

package/dist/core/types/activity.d.ts

@@ -218,12 +218,15 @@ export interface ActivityDefinition<TInput = unknown, TOutput = unknown, TName e
     /** Activity implementation called by the engine or worker. */
     execute: ActivityFunction<TInput, TOutput>;
     /**
-     * Optional post-execution verifier.
+     * Optional verifier, invoked in two phases (see
+     * `ActivityVerificationContext.phase`).
      *
      * During normal post-execution validation, return `true` to confirm the
      * activity result or `false` to reject it. During pre-dispatch crash recovery
-     * for keyed activities, return an explicit reconciliation state; legacy boolean
-     * answers are not treated as proof of external completion.
+     * for keyed activities, return an explicit reconciliation state. A boolean is
+     * the post-execution result shape, not a Tier-0 reconciliation state, so a
+     * boolean returned during pre-dispatch reconciliation fails closed rather than
+     * being treated as proof of external completion.
      */
     verify?: ActivityVerifier<TInput, TOutput>;
     retry?: RetryPolicy;

package/dist/core/types/identity.d.ts

@@ -51,5 +51,12 @@ export type FailureCategory = 'application' | 'timeout' | 'cancellation' | 'reso
  * Read this off `(await handle.state()).status` to learn whether a workflow
  * is still running, finished cleanly, or failed. Pass it to `engine.list()`
  * filters to scope queries by status.
+ *
+ * `'suspended'` is a non-terminal, non-running pause: a workflow that was
+ * explicitly suspended via {@link WorkflowHandle.suspend} (or
+ * `engine.suspend(id)`) keeps its checkpoint and is resumable via
+ * {@link WorkflowHandle.resume} (or `engine.resume(id)`), but is NOT
+ * auto-recovered by `engine.recoverAll()` — suspension is client-driven
+ * preemption, not a fault condition.
  */
-export type WorkflowStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'timed-out';
+export type WorkflowStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'timed-out' | 'suspended';

package/dist/core/types/launch-metadata.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Launch context for a workflow, reconstructed from its persisted state by
+ * {@link WorkflowHandle.getLaunchMetadata}. Lets a caller — typically after
+ * `engine.recoverAll()` — recover the original input and the launch options that
+ * survive in durable state, without keeping a side table that correlates a
+ * recovered workflow back to how it was started.
+ *
+ * `launchOptions` carries only the options recoverable *faithfully* from
+ * persisted state: `id` (always) and `tags`. Note `tags` is the run's *current*
+ * tag set (tags are mutable via `addTags`/`removeTags`), not necessarily the
+ * tags passed at launch. Deliberately excluded: `executionTimeout` (state
+ * stores the absolute deadline, not the original duration, so it cannot be
+ * reproduced exactly); `idempotencyKey` (no durable trace); `searchAttributes`
+ * (live in their own durable index — read them via
+ * {@link WorkflowHandle.getAttributes}); and `services` (non-serializable,
+ * re-provided on recovery by {@link EngineOptions.resolveWorkflowServices}).
+ *
+ * @example
+ * ```ts
+ * import { type LaunchMetadata } from '@lostgradient/weft';
+ *
+ * function describe(metadata: LaunchMetadata): string {
+ *   return `input=${JSON.stringify(metadata.input)} id=${metadata.launchOptions.id}`;
+ * }
+ * ```
+ */
+export interface LaunchMetadata {
+    input: unknown;
+    launchOptions: {
+        id: string;
+        tags?: string[];
+    };
+}

package/dist/core/types/message-handles.d.ts

@@ -111,6 +111,31 @@ export interface SignalOptions<TInput = void> {
 export interface SignalDeliveryOptions {
     readonly signalId?: string;
 }
+/**
+ * The signal half of `startOrSignal` (signal-with-start): a signal `name`, an
+ * optional `payload`, and an optional `signalId`. When `signalId` is omitted it
+ * is derived from `options.idempotencyKey`. The id is load-bearing for
+ * convergence — concurrent callers deliver one signal only when they share it,
+ * and independent webhook retries share only the idempotency key — so a
+ * caller-supplied `signalId` covers the single-caller case while idempotent
+ * convergence relies on the derived-from-key value.
+ *
+ * @example
+ * ```ts
+ * import type { StartOrSignalSignal } from '@lostgradient/weft';
+ *
+ * const signal: StartOrSignalSignal = {
+ *   name: 'webhook',
+ *   payload: { event: 'payment.succeeded' },
+ * };
+ * void signal;
+ * ```
+ */
+export interface StartOrSignalSignal {
+    readonly name: string;
+    readonly payload?: unknown;
+    readonly signalId?: string;
+}
 /**
  * Create a typed workflow signal handle. When an `inputSchema` is supplied
  * via options, the payload type is inferred from the schema's