eve 0.48.0 → 0.49.0

package/dist/src/compiled/@workflow/core/runtime/step-executor.d.ts

@@ -41,7 +41,7 @@ export interface StepExecutorParams {
      * Pre-claimed inline start: the suspension handler committed (or lost) this
      * step's `step_created` + `step_started` pair inside its batched fan-out
      * write, so the start this executor would otherwise send has already been
-     * decided. `owned: false` returns `{ type: 'skipped' }` before any write —
+     * decided. `owned: false` returns `{ type: 'skipped' }` before any write,
      * the same outcome as losing the lazy claim's atomic create. `owned: true`
      * skips both start paths (no start write at all) and runs the body against
      * the claimed step. Mutually exclusive with `lazyStepInput`: the input
@@ -51,11 +51,11 @@ export interface StepExecutorParams {
     /**
      * Inline step ownership: the queue message ID of the invocation this
      * executeStep call runs in (from the queue handler's meta). When set, the
-     * `step_started` this call sends is stamped with it — on the lazy paths
+     * `step_started` this call sends is stamped with it: on the lazy paths
      * (where `lazyStepInput` is present) and on the owned-recovery
      * payload-less start (where it is not; the re-stamp keeps a recovered
      * step readable as owned by this message, since ownership derives from
-     * the LATEST start — so a recovery start is never bare). Wake
+     * the LATEST start, so a recovery start is never bare). Wake
      * replays that observe an actively-owned step suppress the immediate
      * requeue and enqueue a delayed backstop instead. Omitted on the
      * background-step path, whose bare start intentionally clears ownership
@@ -82,7 +82,7 @@ export interface StepExecutorParams {
      * It matters most on the lazy inline path, where the `step_started` claim is
      * the step's FIRST durable write (its `step_created` is deferred): without a
      * seed the claim would name no position at all, and a replay working from a
-     * stale view could claim — and then commit — a step scheduled without
+     * stale view could claim (and then commit) a step scheduled without
      * observing an event it never loaded.
      *
      * A World that fences rejects a stale claim with `PreconditionFailedError`
@@ -100,7 +100,7 @@ export interface StepExecutorParams {
      * stale-sensitive (an open hook means an out-of-band event can make the
      * scheduling view stale): the guard's 412 fence can reject a stale claim's
      * durable writes, but it cannot un-run a body that optimistic start began
-     * before the claim settled — awaiting the claim extends the fence to user
+     * before the claim settled; awaiting the claim extends the fence to user
      * code. Wins over `forceOptimisticStart` and the env flag.
      */
     suppressOptimisticStart?: boolean;
@@ -116,8 +116,8 @@ export interface StepExecutorParams {
      * Turbo mode only: a promise that resolves once the backgrounded
      * `run_started` has landed. When set, the lazy/optimistic `step_started` is
      * chained on it so the step is never created before its run exists. The body
-     * still runs immediately against locally-synthesized state — only the network
-     * write waits — so the `run_started` round-trip overlaps the body. `undefined`
+     * still runs immediately against locally-synthesized state (only the network
+     * write waits), so the `run_started` round-trip overlaps the body. `undefined`
      * outside turbo, where `run_started` was already awaited up front.
      */
     runReadyBarrier?: Promise<unknown>;
@@ -126,7 +126,7 @@ export interface StepExecutorParams {
      * by the orchestrator. When set, this executor computes the final values
      * against the wall clock taken immediately before user code runs and
      * attaches them to the step's terminal event. Set only for the first step of
-     * an inline batch, and only on first-attempt executions that qualify — see
+     * an inline batch, and only on first-attempt executions that qualify; see
      * runtime/step-latency.ts.
      */
     latencyTracking?: StepLatencyTracking;
@@ -136,12 +136,12 @@ export interface StepExecutorParams {
      * executor closes the measurement against the `step_started` claim and the
      * wall clock taken immediately before user code, and attaches the total plus
      * its phase breakdown to this step's `step.execute` span. Set by the runtime
-     * for exactly one step per resumption — see runtime/resume-latency.ts.
+     * for exactly one step per resumption; see runtime/resume-latency.ts.
      */
     resumeTracking?: ResumeTtrTracking;
     /**
      * Authoritative attempt number for this execution, used to bound retries
-     * against `maxRetries` BEFORE the body runs. In order to also catch
+     * against `maxRetries` BEFORE the body runs. To also catch
      * step timeouts (which we can't have catch handlers for), we determine
      * the attempt count based as follows:
      * - Inline (combined handler): the number of `step_started` events already
@@ -171,13 +171,13 @@ export type PreclaimedInlineStart = {
      */
     step: StartedStep;
     /**
-     * `Date.now()` taken right before the batch POST that carried the pair
-     * — the claim's "start POST sent" instant, anchoring RSFS exactly like
+     * `Date.now()` taken right before the batch POST that carried the pair:
+     * the claim's "start POST sent" instant, anchoring RSFS exactly like
      * the lazy claim's own POST would.
      */
     batchPostSentAtMs?: number;
     /**
-     * `Date.now()` taken right after that batch POST returned — the
+     * `Date.now()` taken right after that batch POST returned: the
      * claim's completion instant (T6 of the hook-resume TTR window).
      */
     claimCompletedAtMs?: number;
@@ -233,7 +233,7 @@ export type StepExecutionResult = {
  * Executes a single step: creates step_started event, hydrates input,
  * runs the step function, creates step_completed/step_failed/step_retrying events.
  *
- * Does NOT queue workflow continuation messages — the caller decides what to do next.
+ * Does NOT queue workflow continuation messages; the caller decides what to do next.
  * Used by the combined workflow handler for step execution.
  */
 export declare function executeStep(params: StepExecutorParams): Promise<StepExecutionResult>;

package/dist/src/compiled/@workflow/core/runtime/step-latency.d.ts

@@ -7,11 +7,11 @@ import type { Event } from '#compiled/@workflow/world/index.js';
  * beginning to execute. STSO (step-to-step overhead) measures the previous
  * step's terminal event → the next step's body beginning to execute. RSFS
  * (run-started-to-first-step) measures the `run_started` response landing →
- * the first step's start POST being issued — a sub-window of TTFS that
+ * the first step's start POST being issued, a sub-window of TTFS that
  * isolates replay overhead from the run-creation queue hop; `finalSchedulingReplay`
  * is the synchronous workflow-function-execution duration of only the FINAL
  * replay pass within that window (the pass that reached and scheduled the
- * first step) — it is NOT accumulated across earlier pre-first-step passes
+ * first step); it is NOT accumulated across earlier pre-first-step passes
  * (see {@link StepLatencyTracking.replayMs}), so it must not be read as "the
  * replay portion of RSFS". All are attached to the step's terminal
  * event so a backend can emit latency metrics from the event write alone,
@@ -42,7 +42,7 @@ export interface StepLatencyTracking {
      * workflow-body `setAttributes` before the first step
      * resolves through an extra replay (see the `hasAttributeEvents` branch in
      * runtime.ts), so everything from this write until the step body runs is
-     * the duration of the setAttributes call — which is subtracted by ending
+     * the duration of the setAttributes call, which is subtracted by ending
      * the measurement at the point where the step would otherwise have been
      * scheduled.
      */
@@ -59,7 +59,7 @@ export interface StepLatencyTracking {
     eventCount?: number;
     /**
      * Epoch ms the `run_started` response was received/parsed by the SDK.
-     * Present only when the step qualifies for RSFS — the same eligibility as
+     * Present only when the step qualifies for RSFS: the same eligibility as
      * TTFS (see {@link computeStepLatencyTracking}), plus a recoverable
      * anchor. In turbo mode, `run_started` is backgrounded rather than
      * awaited, so this is stamped at the point the runtime synthesizes the
@@ -74,21 +74,30 @@ export interface StepLatencyTracking {
      * Wall-clock ms this invocation's synchronous workflow-function replay
      * took: from calling `runWorkflow` to it throwing the suspension that
      * scheduled this batch. Excludes awaited network I/O (the suspension's
-     * event commits, the step's own start POST). Present only alongside
-     * `rsfsAnchorMs`.
+     * event commits, the step's own start POST). Reported for every batch that
+     * qualifies for TTFS or STSO, not just the first step.
      *
-     * This is the FINAL replay pass only — the invocation that reached and
-     * scheduled the first step. Valid RSFS paths can replay more than once
-     * before the first step (e.g. a workflow-body `setAttributes()` detour
-     * replays twice), and a redelivery omits earlier invocations' replay work
-     * entirely; this value is not accumulated across those earlier passes.
-     * Do not read it as "the replay portion of RSFS" — RSFS
-     * ({@link rsfsAnchorMs}) covers the whole run_started-to-first-step
-     * window, this covers only the last pass.
+     * This is the FINAL pass only: the one that reached and scheduled this
+     * batch. Valid RSFS paths can replay more than once before the first step
+     * (e.g. a workflow-body `setAttributes()` detour replays twice), and a
+     * redelivery omits earlier invocations' replay work entirely; this value is
+     * not accumulated across those earlier passes. Do not read it as "the
+     * replay portion of RSFS": RSFS ({@link rsfsAnchorMs}) covers the whole
+     * run_started-to-first-step window, this covers only the last pass.
+     *
+     * On a retained resume this measures the resume, not a replay, which is
+     * why the distribution is bimodal and why {@link retained} is reported
+     * alongside it as the dimension that separates the two modes.
      */
     replayMs?: number;
     /** Whether turbo mode is active for this invocation. */
     turbo: boolean;
+    /**
+     * Whether a retained VM session served this batch, as opposed to a full
+     * replay from the event log. Reported as a `retained` entry in
+     * {@link StepLatencyEventData.optimizations}, alongside `turbo`.
+     */
+    retained: boolean;
 }
 /** Latency telemetry attached to a step's terminal event's `eventData`. */
 export interface StepLatencyEventData {
@@ -99,12 +108,18 @@ export interface StepLatencyEventData {
     /** Client-measured run_started → first step's start POST, ms. */
     rsfs?: number;
     /**
-     * Client-measured wall-clock ms of the FINAL replay pass that scheduled
-     * the first step (see {@link StepLatencyTracking.replayMs}) — not
-     * accumulated across earlier pre-first-step passes, so it must not be
-     * read as "the replay portion of `rsfs`".
+     * Client-measured wall-clock ms of the FINAL pass that scheduled this
+     * batch (see {@link StepLatencyTracking.replayMs}); not accumulated
+     * across earlier passes, so it must not be read as "the replay portion of
+     * `rsfs`". Present whenever `ttfs` or `stso` is.
      */
     finalSchedulingReplay?: number;
+    /**
+     * Active runtime modes for this measurement: `turbo`, `lazyStepStart`,
+     * `optimisticStart`, and `retained` (a retained VM served the batch; its
+     * absence means a full replay). The server turns each known entry into a
+     * bounded boolean tag on every latency metric.
+     */
     optimizations?: string[];
 }
 /**
@@ -131,13 +146,13 @@ export declare function computeStepLatencyTracking(params: {
     runCreatedAtMs: number | undefined;
     /**
      * Epoch ms the `run_started` response was received/parsed by the SDK (or,
-     * under turbo, the instant the run was synthesized locally — see
+     * under turbo, the instant the run was synthesized locally; see
      * {@link StepLatencyTracking.rsfsAnchorMs}). Absent disqualifies RSFS.
      */
     runStartedReceivedAtMs: number | undefined;
     /**
      * Wall-clock ms this suspension's `runWorkflow` call spent executing
-     * synchronously before throwing — the FINAL replay pass only, not
+     * synchronously before throwing: the FINAL replay pass only, not
      * accumulated across earlier passes. See
      * {@link StepLatencyTracking.replayMs}.
      */
@@ -148,7 +163,7 @@ export declare function computeStepLatencyTracking(params: {
      * The accumulator's value as of the suspension that wrote the run's first
      * attr_set (its hook phase runs before its attr writes). When the
      * measurement ends at the attr write, only hook time from before that
-     * point may be subtracted — later hook writes fall outside the measured
+     * point may be subtracted; later hook writes fall outside the measured
      * window. Undefined when no attr suspension happened in this invocation
      * (e.g. the attr_set was loaded from a redelivery's snapshot, where no
      * same-invocation hook time precedes it).
@@ -157,25 +172,27 @@ export declare function computeStepLatencyTracking(params: {
     /**
      * Whether the suspension that scheduled this batch also created waits.
      * Those `wait_created` writes are not in `events` yet (they were committed
-     * by this very suspension pass), so they must be reported separately. A
+     * by this suspension pass), so they must be reported separately. A
      * wait disqualifies both measurements.
      */
     suspensionHasWaits: boolean;
     /**
      * Whether the suspension that scheduled this batch also created hooks
-     * (also not in `events` yet). Hooks keep TTFS eligible — their measured
-     * write time is subtracted via `preStepBlockingMs` — but disqualify STSO,
+     * (also not in `events` yet). Hooks keep TTFS eligible (their measured
+     * write time is subtracted via `preStepBlockingMs`) but disqualify STSO,
      * which is only meaningful for a pure back-to-back step gap.
      */
     suspensionCreatedHooks: boolean;
     /** Whether turbo mode is active for this invocation. */
     turbo: boolean;
+    /** See {@link StepLatencyTracking.retained}. */
+    retained: boolean;
 }): StepLatencyTracking | undefined;
 /**
  * Compute the latency telemetry to attach to the step's terminal event.
  * Called by `executeStep` with the wall-clock timestamp taken immediately
  * before user step code runs. Returns undefined when there is nothing to
- * report (no tracking, or a retry attempt — retries measure neither TTFS nor
+ * report (no tracking, or a retry attempt; retries measure neither TTFS nor
  * STSO).
  */
 export declare function computeStepLatencyEventData(params: {

package/dist/src/compiled/@workflow/core/runtime/step-ownership.d.ts

@@ -18,13 +18,13 @@ export declare function isStepOwnershipActive(step: StepInvocationQueueItem): bo
 /**
  * Seconds left on an owned step's liveness lease, anchored at its latest
  * `step_started`. 0 means the lease has expired (or the start timestamp is
- * missing — the degraded mode for worlds whose events lack usable
+ * missing, the degraded mode for worlds whose events lack usable
  * timestamps), in which case dispatch falls back to the immediate enqueue.
  *
  * The result is clamped to the configured lease: `lastStartedAt` is the
  * server-stamped event `createdAt` while `nowMs` is the local clock, so a
  * client running behind the server would otherwise compute a remainder
- * LONGER than the lease itself — and with the lease tuned to the 900s cap,
+ * LONGER than the lease itself, and with the lease tuned to the 900s cap,
  * a `delaySeconds` above the queue's per-message maximum, which SQS-backed
  * worlds reject outright (the wake replay's enqueue would throw and ride
  * the redelivery loop). The clamp makes skew strictly harmless; remaining
@@ -34,14 +34,14 @@ export declare function stepLeaseRemainingSeconds(step: StepInvocationQueueItem,
 /**
  * Idempotency key for the delayed backstop wake of an inline-owned step.
  *
- * The key is scoped to the current OWNERSHIP EPOCH — the timestamp of the
- * latest `step_started` — not just the correlation ID. Within one epoch,
+ * The key is scoped to the current OWNERSHIP EPOCH (the timestamp of the
+ * latest `step_started`), not just the correlation ID. Within one epoch,
  * every wake replay derives the same key, so fan-out stays capped at one
  * pending backstop per step. But when owner recovery re-stamps the step
  * (queue redelivery of the owning message → new `step_started` → new
  * `lastStartedAt`), the key CHANGES. This is load-bearing for liveness:
  * queues dedupe an idempotency key for the lifetime of the original
- * message — including while a delivery of it is in flight — so a backstop
+ * message (including while a delivery of it is in flight), so a backstop
  * that fires during a refreshed lease and tries to re-arm under a fixed key
  * would dedupe against ITSELF and be dropped, leaving no escape hatch if
  * the recovered owner later dies without further redeliveries. The epoch
@@ -56,7 +56,7 @@ export declare function stepLeaseRemainingSeconds(step: StepInvocationQueueItem,
  * The key must also never be the step message's own `idempotencyKey`
  * (the bare correlation ID): the owner's retry handoff enqueues the step
  * under that key with a short backoff, and a pending backstop sharing it
- * would absorb the retry — turning a 1s backoff into a full-lease stall.
+ * would absorb the retry, turning a 1s backoff into a full-lease stall.
  */
 export declare function backstopIdempotencyKey(step: StepInvocationQueueItem): string;
 /**

package/dist/src/compiled/@workflow/core/runtime/step-single-flight.d.ts

@@ -4,7 +4,7 @@ import type { StepExecutionResult } from './step-executor.js';
  * already in flight in this process. The winner's result is returned to the
  * winner; a loser awaits the winner's settlement (success OR failure) and
  * then returns `{ type: 'skipped' }` so its caller acks without running the
- * body. A winner failure is not propagated to the loser — the winner's own
+ * body. A winner failure is not propagated to the loser: the winner's own
  * queue message redelivers and drives the retry, so exactly one message
  * keeps owning the outcome.
  */

package/dist/src/compiled/@workflow/core/runtime/suspension-handler.d.ts

@@ -1,6 +1,7 @@
 import type { Span } from '#compiled/@opentelemetry/api/index.js';
 import { type SerializedData, type TraceCarrier, type ValidQueueName, type WorkflowRun, type World } from '#compiled/@workflow/world/index.js';
 import type { StepInvocationQueueItem, WorkflowSuspension } from '../global.js';
+import { type GuestCodeExecution } from '../serialization/hardened.js';
 import { type LoadedEventLog } from './helpers.js';
 import { ReplayRecoveryReporter } from './replay-recovery-reporter.js';
 import type { PreclaimedInlineStart } from './step-executor.js';
@@ -13,7 +14,7 @@ export interface SuspensionHandlerParams {
     /**
      * The runtime's loaded event log. Every event creation this suspension makes
      * names the position it was derived from, so a backend that has recorded
-     * events the replay did not see can report them back on the write — or, if
+     * events the replay did not see can report them back on the write, or, if
      * it would rather refuse than report, reject it with a 412. A rejection is
      * not retried here: the event's correlation id was minted by *this* replay's
      * seeded sequence, so re-committing it against a corrected log would persist
@@ -35,14 +36,14 @@ export interface SuspensionHandlerParams {
     replayRecoveryReporter?: ReplayRecoveryReporter;
     /**
      * Resilient step dispatch: when provided (and the per-step eligibility gates
-     * pass — see the step ops below), each newly created non-inline step's
+     * pass, see the step ops below), each newly created non-inline step's
      * `step_created` write is parallelized with its step-execution queue
      * publish, and the queue message carries the serialized step input
      * (`stepInput`) so the consumer can idempotently re-ensure the event if the
      * direct write failed transiently. Steps queued this way are reported in
      * {@link SuspensionHandlerResult.queuedStepCorrelationIds} so the caller
      * skips them in its own dispatch pass. Omitted by callers that must not
-     * queue (terminal drain, tests) — creates then behave exactly as before.
+     * queue (terminal drain, tests); creates then behave exactly as before.
      */
     stepDispatch?: {
         /** The unified workflow queue this run's step messages are published to. */
@@ -57,9 +58,9 @@ export interface SuspensionHandlerParams {
      * Inline step ownership: the queue message ID of the invocation this
      * suspension runs in (the queue handler's meta). When present AND the
      * batched fan-out engages, the lazy-inline steps' deferred writes are
-     * folded into the batch as `step_created` + `step_started` pairs — the
+     * folded into the batch as `step_created` + `step_started` pairs (the
      * started row stamped with this ID, exactly like the lazy claim it
-     * replaces — pre-claiming the steps the caller is about to run inline. See
+     * replaces), pre-claiming the steps the caller is about to run inline. See
      * {@link SuspensionHandlerResult.inlineClaims}. Callers that never
      * inline-execute (terminal drain) omit it, keeping their lazy steps on the
      * plain deferred path.
@@ -69,8 +70,8 @@ export interface SuspensionHandlerParams {
      * Lets the batched fan-out return before every chunk has committed: only
      * the chunk carrying the pre-claimed inline pairs gates the handler's
      * return (its claims are what the caller starts bodies from), while the
-     * trailing chunks' commits — and every chunk's in-flush step-message
-     * publishes — ride {@link SuspensionHandlerResult.deferredBatchWork}. A
+     * trailing chunks' commits (and every chunk's in-flush step-message
+     * publishes) ride {@link SuspensionHandlerResult.deferredBatchWork}. A
      * caller that opts in MUST await that promise before acking its delivery:
      * the durability contract ("every create durable before ack") moves from
      * the handler's return to that join, and nothing else re-drives a lost
@@ -90,16 +91,28 @@ export interface SuspensionHandlerResult {
      * Correlation IDs for which this suspension call actually wrote the
      * step_created event (as opposed to catching EntityConflictError because
      * a concurrent handler wrote it first). Only the handler that wrote the
-     * step_created event should queue / inline-execute the step — this
+     * step_created event should queue / inline-execute the step; this
      * guarantees a single owner per step, even when multiple handlers race
      * into the same batch boundary.
      */
     createdStepCorrelationIds: Set<string>;
+    /**
+     * Correlation IDs of steps whose arguments failed to serialize. Each was
+     * finalized here as `step_created` (with a placeholder input; the real
+     * input is precisely what refused to serialize) followed by `step_failed`
+     * carrying the SerializationError, so the next replay rejects the step's
+     * promise and a try/catch around the step call observes the error,
+     * exactly like a step-body failure. No step-execution message is
+     * dispatched for these, so the caller MUST force an in-process replay:
+     * when the failed step was the only pending work, nothing else will ever
+     * re-invoke the run to observe the terminal event.
+     */
+    failedStepCorrelationIds: Set<string>;
     /**
      * Correlation IDs of steps this suspension call already published
      * step-execution queue messages for, via resilient step dispatch (the
      * `step_created` write parallelized with a `stepInput`-carrying queue
-     * publish). The caller MUST NOT dispatch these again — the message is
+     * publish). The caller MUST NOT dispatch these again: the message is
      * already out (a duplicate would be deduped by its idempotency key, but
      * costs a wasted round-trip). Empty when {@link SuspensionHandlerParams.stepDispatch}
      * was not provided or no step was eligible.
@@ -134,12 +147,12 @@ export interface SuspensionHandlerResult {
      * Pre-claimed inline starts, by correlation id: the per-step verdicts of
      * the `step_created` + `step_started` pairs the batched fan-out committed
      * for the lazy-inline steps. A step with an entry here is passed to
-     * `executeStep` as `preclaimedStart` INSTEAD of `lazyStepInput` — its
+     * `executeStep` as `preclaimedStart` INSTEAD of `lazyStepInput`: its
      * input already rode the pair, and the claim is settled: `owned: true`
      * carries the started attempt-1 entity (input re-attached) so the body
      * runs straight off the batch commit with no start write of its own;
      * `owned: false` lost the pair's atomic create-claim to a concurrent
-     * writer, and executeStep returns `skipped` without running the body —
+     * writer, and executeStep returns `skipped` without running the body,
      * the same outcome as losing the lazy claim. Empty whenever the fold did
      * not engage (batching off, no `ownerMessageId`, or the lone-inline case,
      * which keeps the optimistic lazy path and its claim/body overlap).
@@ -147,20 +160,20 @@ export interface SuspensionHandlerResult {
      * Crash window: the pair commits before the caller runs the body, so a
      * crash between them leaves a started step stamped with this message's
      * ID. Redelivery of the same message re-executes it via the owned-recovery
-     * path — the exact machinery the lazy claim's crash window already uses.
+     * path, the exact machinery the lazy claim's crash window already uses.
      */
     inlineClaims: Map<string, PreclaimedInlineStart>;
     /**
      * The highest slot the batched fan-out committed, when it ran. The batch's
      * own events are not in the caller's loaded log (the next reload picks
      * them up), so the caller folds this ceiling into the slot snapshot it
-     * hands the inline executions — otherwise every inline terminal write
+     * hands the inline executions; otherwise every inline terminal write
      * would name a pre-batch position and be answered with a skipped-slot
      * report echoing the events this suspension just wrote. Under
      * {@link SuspensionHandlerParams.allowDeferredBatchWork} this covers the
      * chunks that had committed by the handler's return (always the pair
      * chunk); a trailing chunk that commits later is echoed back on the
-     * terminal writes like any foreign event — reports the executor reads for
+     * terminal writes like any foreign event: reports the executor reads for
      * position and discards.
      *
      * So the echo is only fully suppressed for a SINGLE-chunk fold. On a
@@ -168,7 +181,7 @@ export interface SuspensionHandlerResult {
      * chunks are still in flight, and an inline terminal write issued in that
      * window still names a position below them and still draws a report for
      * their events. Bounded (trailing chunks only, large fan-outs only) and
-     * self-correcting on the next reload — recorded so a report seen there
+     * self-correcting on the next reload, and recorded so a report seen there
      * reads as expected rather than as a bug.
      */
     batchCommittedSlotCeiling?: number;
@@ -178,7 +191,7 @@ export interface SuspensionHandlerResult {
      * trailing work exists: the commits of every chunk except the pair chunk,
      * plus every chunk's step-message publishes (each chained on ITS OWN
      * chunk's commit, so publish-after-create holds per step). The caller
-     * MUST await it before acking — a rejection here is a failed suspension
+     * MUST await it before acking: a rejection here is a failed suspension
      * write and fails the delivery exactly as it would have at the handler's
      * return. Steps whose messages this work publishes are already in
      * {@link queuedStepCorrelationIds} at return time.
@@ -216,17 +229,18 @@ export interface SuspensionHandlerResult {
      * durably creating the user's hooks doesn't count as runtime overhead.
      */
     hookCreationMs: number;
-    /**
-     * Whether serializing this suspension's new step inputs was passive (did
-     * not execute workflow-owned code such as getters, proxy traps, or custom
-     * serializers). `false` means the retained VM may have diverged from what
-     * a cold replay would compute, so the caller must demote to replay.
-     */
-    retainedStepInputsSafe: boolean;
+    /** Exact number of workflow-code executions observed during serialization. */
+    serializationBlockerCount: number;
+    /** Bounded sample used only for retention diagnostics. */
+    serializationBlockers: SuspensionSerializationBlocker[];
+}
+export interface SuspensionSerializationBlocker extends GuestCodeExecution {
+    source: 'step_input' | 'hook_metadata' | 'hook_abort';
+    correlationId: string;
 }
 /**
  * Handles a workflow suspension by processing all pending operations (hooks, steps, waits).
- * Creates events for all operations but does NOT queue step messages — returns the pending
+ * Creates events for all operations but does NOT queue step messages; returns the pending
  * steps so the caller can decide which to execute inline vs queue to background.
  *
  * Processing order:

package/dist/src/compiled/@workflow/core/runtime/unserializable-step.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared shape for finalizing a step whose arguments failed to serialize
+ * (used by both the node:vm suspension handler and the QuickJS entrypoint).
+ *
+ * The world requires a `step_created` before any terminal step event, and
+ * the step's real input is precisely what refused to serialize, so the
+ * finalization writes a placeholder input. The marker string makes the
+ * placeholder distinguishable from a genuine zero-argument step in
+ * `workflow inspect steps` and the observability UI: a reader sees
+ * "input unavailable" instead of "no arguments".
+ */
+export declare const UNSERIALIZABLE_STEP_INPUT_MARKER = "[input unavailable: step argument serialization failed]";
+/**
+ * The placeholder value serialized into the failed step's `step_created`
+ * input. Matches the `{ args, closureVars, thisVal }` triple
+ * `dehydrateStepArguments` / the QuickJS bootstrap produce for real steps,
+ * so every consumer hydrates it uniformly, plus the structural flag the
+ * step executor checks before running user code (see
+ * {@link isUnserializableStepInputPlaceholder}).
+ */
+export declare function unserializableStepInputPlaceholder(): Record<string, unknown>;
+/**
+ * Whether a hydrated step input is the finalization placeholder.
+ *
+ * Finalization writes `step_created` (placeholder) and `step_failed` as two
+ * separate durable writes; a crash or transient failure between them leaves
+ * a pending step whose stored input is the placeholder. Redelivery then
+ * dispatches that step through normal crash recovery: the executor calls
+ * this before running user code and completes the intended failure (a fatal
+ * SerializationError → `step_failed`) instead of silently invoking the step
+ * body with placeholder arguments.
+ */
+export declare function isUnserializableStepInputPlaceholder(hydratedInput: unknown): boolean;
+//# sourceMappingURL=unserializable-step.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/vm-mode.d.ts

@@ -24,7 +24,7 @@ export type WorkflowVmMode = (typeof WORKFLOW_VMS)[number];
  *
  * Returns the configured engine, or `undefined` if unset/empty.
  * Throws {@link WorkflowRuntimeError} if the value is set but not one of
- * the known engines — catching misconfiguration early is better than
+ * the known engines, since catching misconfiguration early is better than
  * silently falling back to the default.
  */
 export declare function getWorkflowVmFromEnv(env?: NodeJS.ProcessEnv): WorkflowVmMode | undefined;
@@ -40,5 +40,5 @@ export declare function getWorkflowVmFromEnv(env?: NodeJS.ProcessEnv): WorkflowV
  * Throws if `WORKFLOW_VM` or `executionContext.workflowVm` is set to an
  * unknown value.
  */
-export declare function useQuickJSVm(workflowRun: WorkflowRun): boolean;
+export declare function useQuickJSVm(workflowRun: Pick<WorkflowRun, 'executionContext'>): boolean;
 //# sourceMappingURL=vm-mode.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/wait-continuation.d.ts

@@ -10,7 +10,7 @@
  * The continuation is keyed on the wait's correlationId: while a wait is
  * pending, every replay pass over the run re-observes it (e.g., once per
  * step completion in `Promise.all([steps..., sleep()])`), and without
- * dedupe each pass would enqueue another delayed continuation — each one
+ * dedupe each pass would enqueue another delayed continuation: each one
  * a spurious full replay when the wait elapses, and each a fresh message
  * that resets the delivery-attempt runaway guard. A key is attached in
  * all cases: some worlds (e.g. world-postgres) serialize key-less
@@ -29,7 +29,7 @@
  * situations exist, each with its own key variation:
  *
  * - Waits longer than the maximum queue delay are chained: the delay is
- *   clamped to `WAIT_CONTINUATION_MAX_DELAY_SECONDS` (23h — VQS messages
+ *   clamped to `WAIT_CONTINUATION_MAX_DELAY_SECONDS` (23h: VQS messages
  *   have a 24h retention limit, and one hour of buffer matches
  *   world-vercel's own clamp for delayed re-enqueues), so the
  *   continuation intentionally fires early, re-observes the wait, and
@@ -37,7 +37,7 @@
  *   (`ceil(timeoutSeconds / maxDelay)`): stable for every re-observation
  *   within the same hop window (so passes dedupe), decremented at each
  *   hop delivery (so the chain always advances). Worlds without a delay
- *   limit (world-postgres, world-local) simply take the same ≤23h hops.
+ *   limit (world-postgres, world-local) take the same ≤23h hops.
  *
  * - Near-elapsed waits (≤2s remaining) get a second-bucketed suffix. A
  *   continuation delivered marginally early (clock skew between the
@@ -50,11 +50,25 @@
  * Mid-range waits (more than the near-elapsed threshold, at most one
  * hop) use the bare correlationId: every re-observation targets the same
  * deadline, so deduping to the first message is semantically lossless.
- * Host clock skew beyond the near-elapsed threshold could in principle
- * deliver such a continuation early enough to re-observe its wait and
- * lose the re-enqueue to the burnt key; the threshold is the skew
- * tolerance we accept for the benefit of exactly-one continuation per
- * wait.
+ *
+ * That last case used to be the one hole in the scheme, and it was not
+ * theoretical. Any delivery early enough to re-observe its own wait as
+ * pending burns the bare key on the way in: the re-enqueue is dropped by
+ * the dedupe window, nothing else is scheduled to wake the run, and no
+ * backstop exists for a wait the way inline step ownership provides one
+ * for a step. The run sleeps forever. Waits over the threshold have zero
+ * tolerance for it, which is why an infrastructure change in delivery
+ * timing was able to strand runs across every published SDK version at
+ * once, all of them keyed this way.
+ *
+ * So the key is no longer derived from the wait alone. A continuation
+ * carries the wait it was armed for and its attempt number
+ * ({@link WorkflowInvokePayload.waitContinuation}), and an invocation
+ * that recognizes itself as the continuation for a wait that is still
+ * pending arms the next one at `attempt + 1`. Attempts advance ONLY when
+ * an early delivery actually happens, so the normal path is untouched:
+ * attempt 0 keys exactly as before, and every re-observation within one
+ * attempt still collapses to a single message.
  */
 /**
  * Maximum `delaySeconds` for a single wait-continuation message. Waits
@@ -79,6 +93,14 @@ export interface WaitContinuationDispatch {
  * message. `timeoutSeconds` is the time until the wait's `resumeAt`
  * (floored at 1s by the suspension handler); `waitCorrelationId`
  * identifies the wait so repeated suspension passes dedupe.
+ *
+ * `attempt` is the number of continuations already spent on this wait, taken
+ * from the incoming message when this invocation IS one of them (see
+ * {@link WorkflowInvokePayload.waitContinuation}). It only ever moves when a
+ * continuation arrived before its wait elapsed, which is exactly when the
+ * previous key is spent and re-using it would drop the message. Attempt 0
+ * keys identically to the scheme before attempts existed, so the ordinary
+ * path — arm once, deliver once, complete — is byte-for-byte unchanged.
  */
-export declare function getWaitContinuationDispatch(timeoutSeconds: number, waitCorrelationId: string, now?: number): WaitContinuationDispatch;
+export declare function getWaitContinuationDispatch(timeoutSeconds: number, waitCorrelationId: string, now?: number, attempt?: number): WaitContinuationDispatch;
 //# sourceMappingURL=wait-continuation.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/wait-until.d.ts

@@ -3,7 +3,7 @@ export declare function waitUntil(promise: Promise<unknown>): void;
  * Schedule a background promise via `waitUntil`, guaranteeing that the
  * promise handed to `waitUntil` can never reject. Nothing consumes a
  * `waitUntil` promise, so a rejection surfaces as an `unhandledRejection`
- * and can crash the process — even when the same underlying error is
+ * and can crash the process, even when the same underlying error is
  * correctly handled by an awaited copy elsewhere.
  *
  * Expected client-disconnect errors (`AbortError` / `ResponseAborted`)