eve 0.48.0 → 0.49.0

package/dist/src/compiled/@workflow/core/describe-error.d.ts

@@ -4,7 +4,7 @@ import { type RunErrorCode } from '#compiled/@workflow/errors/index.js';
  *
  * - `user`: the error came from customer code (a step or workflow function
  *   threw, or a value they passed across a boundary wasn't serializable).
- * - `sdk`: the SDK produced the error itself — an internal invariant broke,
+ * - `sdk`: the SDK produced the error itself: an internal invariant broke,
  *   or a runtime guard rejected the call. These should be rare; when they
  *   happen we want to frame the terminal output as "this is us, not you."
  */
@@ -26,7 +26,7 @@ export interface ErrorDescription {
  *
  * - `errorCode` is typed as `string` rather than `RunErrorCode` because
  *   the value comes from stored JSON/CBOR and may predate the current
- *   enum — callers should not narrow on it blindly. Values that don't
+ *   enum, so callers should not narrow on it blindly. Values that don't
  *   match a known `RUN_ERROR_CODES` entry fall through to USER_ERROR.
  * - `errorName` is the thrown `Error#name`. It is not universally
  *   persisted today; callers that have access to it (either via an
@@ -40,13 +40,13 @@ export interface PersistedErrorSignal {
 }
 /**
  * Data-driven variant of {@link describeError} that works from persisted
- * event fields instead of a live `Error` instance. Intended for CLI/web
- * renderers that read failure events and no longer have the original
- * thrown object.
+ * event fields instead of a live `Error` instance. Intended for command-line
+ * interface (CLI) and web renderers that read failure events and no longer
+ * have the original thrown object.
  */
 export declare function describeRunError(signal: PersistedErrorSignal): ErrorDescription;
 /**
- * Describe an error for user-facing presentation. Purely informational —
+ * Describe an error for user-facing presentation. Purely informational: it
  * does not change any persisted event data or error classification used by
  * the runtime.
  *
@@ -58,7 +58,7 @@ export declare function describeRunError(signal: PersistedErrorSignal): ErrorDes
  * - Context-violation errors (`NotInWorkflowContextError`, etc.) likewise
  *   describe a user mistake.
  * - `WorkflowRuntimeError` (and subclasses like `StepNotRegisteredError`)
- *   indicates an internal SDK invariant broke — surface that as `sdk`.
+ *   indicates an internal SDK invariant broke, so surface that as `sdk`.
  *
  * @param err The error value thrown by the workflow / step.
  * @param errorCode Optional precomputed error code. Callers that already

package/dist/src/compiled/@workflow/core/encryption.d.ts

@@ -12,7 +12,7 @@
  * calls on every encrypt/decrypt invocation.
  *
  * Wire format: `[nonce (12 bytes)][ciphertext + auth tag]`
- * The `encr` format prefix is NOT part of this module — it's added/stripped
+ * The `encr` format prefix is NOT part of this module: it's added/stripped
  * by the serialization layer in `maybeEncrypt`/`maybeDecrypt`.
  */
 export type CryptoKey = import('node:crypto').webcrypto.CryptoKey;
@@ -30,7 +30,7 @@ export declare const TAG_BYTES: number;
  *
  * Pass `usages: ['encrypt']` (or `['decrypt']`) for cross-run scenarios
  * where the caller should not be able to perform the inverse operation
- * with the key — for example a child workflow writing into a parent
+ * with the key. For example, a child workflow writing into a parent
  * run's forwarded WritableStream only needs to encrypt, never decrypt.
  *
  * @param raw - Raw 32-byte AES-256 key (from World.getEncryptionKeyForRun)
@@ -53,17 +53,17 @@ export declare function encrypt(key: CryptoKey, data: Uint8Array, aad?: Uint8Arr
 /**
  * Decrypt data using AES-256-GCM.
  *
- * Any failure inside the Web Crypto layer — most commonly an
+ * Any failure inside the Web Crypto layer (most commonly an
  * `OperationError: The operation failed for an operation-specific reason`
  * raised by `AESCipherJob.onDone` when the GCM authentication tag does
- * not verify — is rewrapped as {@link RuntimeDecryptionError}. The
+ * not verify) is rewrapped as {@link RuntimeDecryptionError}. The
  * wrapped error carries the original DOMException as `cause`, plus a
  * small diagnostic context (`operation`, input `byteLength`) to help
  * disambiguate ciphertext corruption from key mismatch from truncated
  * transport reads.
  *
  * Note: `data` is the raw AES payload (`[nonce][ciphertext + tag]`), not a
- * format-prefixed envelope — callers strip the `encr` marker via
+ * format-prefixed envelope: callers strip the `encr` marker via
  * `decodeFormatPrefix()` before reaching this function. The outer
  * envelope's format prefix is therefore attached by the serialization
  * layer (`serialization/encryption.ts`), which is the layer that has it.

package/dist/src/compiled/@workflow/core/events-consumer.d.ts

@@ -1,4 +1,4 @@
-import { type Event } from '#compiled/@workflow/world/index.js';
+import type { Event } from '#compiled/@workflow/world/index.js';
 /**
  * Delay before firing the deferred unconsumed-event check after the promise
  * queue has drained. Must be long enough for cross-VM microtask chains to
@@ -49,7 +49,7 @@ export interface EventsConsumerOptions {
      * Callback invoked when an event is skipped because it repeats an event
      * class the walk already consumed for the same entity. `firstEventType` is
      * the type that recorded the class, which is the one the workflow observed.
-     * Diagnostics only: skipping is a normal outcome, not an error — though a
+     * Diagnostics only: skipping is a normal outcome, not an error, though a
      * `firstEventType` differing from `event.eventType` says the two writers
      * decided the entity's outcome differently, which is worth more than an
      * info log.
@@ -69,7 +69,7 @@ export interface EventsConsumerOptions {
      * claimed yet is an event it has not reached yet.
      *
      * Required rather than defaulting to always-idle: always-idle is exactly the
-     * pre-gate behaviour, so a defaulted option would let a construction site opt
+     * pre-gate behavior, so a defaulted option would let a construction site opt
      * a whole replay path back out without saying so. Tests that drive a consumer
      * with no orchestrator context pass `() => true` to keep the pre-existing
      * timing, and say so at the call site.
@@ -117,8 +117,8 @@ export declare class EventsConsumer {
     /**
      * The oldest event the walk stepped over that no consumer has claimed yet,
      * if any. Parking is a bet that a consumer will be registered later, so at
-     * any point where no consumer ever will be again — the replay finishing is
-     * the definitive one — this answers which event the bet lost on.
+     * any point where no consumer ever will be again (the replay finishing is
+     * the definitive one), this answers which event the bet lost on.
      */
     get strandedEvent(): Event | undefined;
     /**
@@ -165,6 +165,27 @@ export declare class EventsConsumer {
      * afterwards is what keeps the two pointers from interfering.
      */
     private drainParked;
+    /**
+     * Release anything parked whose class a consumption has since recorded for
+     * the same entity, on the same terms as {@link skipDuplicateEvent}.
+     *
+     * The ordered walk decides a straggler at the event, but only for one of the
+     * two orders the copies can arrive in. When neither copy has a consumer yet,
+     * both park — the walk steps over the first and re-enters immediately, so
+     * the second is offered in the same tick, with no class recorded because
+     * nothing has been *consumed*. The drain then claims the first and the
+     * second is left held by a consumer list that will never grow the callback
+     * it needs, which the workflow function returning reports through
+     * {@link strandedEvent} as a replay divergence.
+     *
+     * Run before each offer pass rather than once, because the consumption that
+     * records the class happens inside the drain itself.
+     *
+     * Not specific to `attr_set`: `wait_completed` reaches the same state, and
+     * {@link ONE_SHOT_EVENT_TYPES} only covers it in the order where the
+     * consumption came first.
+     */
+    private dropParkedDuplicates;
     /**
      * Step the ordered walk over an event nobody claimed, holding on to it for a
      * later consumer. Returns false when the event's type makes its position a
@@ -173,12 +194,13 @@ export declare class EventsConsumer {
      */
     private park;
     /**
-     * The key `event`'s class is tracked under, or `undefined` for the event
-     * types that belong to no class (`hook_received`, `hook_conflict`,
-     * `attr_set`, `run_created`) and are therefore never skipped.
+     * The key `event`'s class is tracked under, or `undefined` for the events
+     * that belong to no class and are therefore never skipped: the types with no
+     * entry at all (`hook_received`, `hook_conflict`, `run_created`), and a
+     * classed type carrying no entity to track it under.
      *
-     * Run events carry no correlation id. They are classes of the run itself, so
-     * they all key off the same bucket.
+     * {@link classifyEntityEvent} owns that rule, because the observability UI
+     * decides the same question about the same log and the two must not drift.
      */
     private eventClassKey;
     /**
@@ -220,7 +242,7 @@ export declare class EventsConsumer {
      * ids are minted from a monotonic ULID per body position, so nothing later in
      * the body registers a second consumer under this id. Waiting would cost
      * `getDeferredCheckDelayMs()` per straggler per replay for information that
-     * cannot arrive — 0.75% of production runs carry at least one straggler, and
+     * cannot arrive: 0.75% of production runs carry at least one straggler, and
      * the p99 among those carries 155.
      *
      * The invariant to preserve if hook identity ever becomes caller-supplied
@@ -231,6 +253,18 @@ export declare class EventsConsumer {
      * class map lives next to the event types rather than being inferred.
      */
     private firstEventTypeOfClass;
+    /**
+     * Steps the walk over a sealed-log `noop` (specVersion >= 7): the World's
+     * backend wrote it to occupy a slot whose writer allocated the position and
+     * died, so the log's density arithmetic holds. It is invisible to the
+     * workflow: no consumer is offered it, no event class is recorded, and the
+     * deterministic clock does not advance, exactly as with
+     * {@link skipDuplicateEvent}, so a log that happens to contain one produces the same
+     * timestamps as a log that does not. (Its `createdAt` is the seal time,
+     * which can even postdate later slots' events; letting it touch the clock
+     * would leak the sealer's wall clock into replay.)
+     */
+    private skipSealedNoop;
     /** Steps the walk over a repeat of an already-consumed class. */
     private skipDuplicateEvent;
     private handleEndOfLog;
@@ -248,8 +282,9 @@ export declare class EventsConsumer {
      * pass that offered it, before this check is ever scheduled, and a class
      * recorded while the check was in flight can only have been recorded by a
      * consumption inside {@link consume}, whose next pass re-offers this event
-     * and steps over it there — leaving the identity guard above to drop the
-     * in-flight check.
+     * and steps over it there, leaving the identity guard above to drop the
+     * in-flight check. One that parks before any consumption records its class
+     * is released later by {@link dropParkedDuplicates} instead.
      */
     private resolveUnconsumedEvent;
     /**
@@ -273,7 +308,7 @@ export declare class EventsConsumer {
      * loses it, and no measurement of a delivery outrunning 100ms exists either
      * way. So read this as retiring the bet rather than as repairing an observed
      * failure of that number: the delay is a user-settable env override, which
-     * leaves the old behaviour one configuration away from losing on any backend.
+     * leaves the old behavior one configuration away from losing on any backend.
      *
      * Termination is `hasParkedCommittedDelivery`'s: it counts only deliveries
      * that resolve on their own, so nothing here can gate its own retirement. A

package/dist/src/compiled/@workflow/core/flushable-stream.d.ts

@@ -15,7 +15,7 @@ type DrainBarrier = () => Promise<void>;
  * This is deliberately distinct from the per-request batch caps below: this
  * bounds how much is *buffered*, those bound how much goes out in one
  * `writeMulti`. Raising this must never let a single request exceed a wire
- * limit — batch sizing enforces that independently.
+ * limit, since batch sizing enforces that independently.
  */
 export declare const MAX_INFLIGHT_CHUNKS = 1000;
 export declare const getMaxInflightChunks: () => number;
@@ -29,7 +29,7 @@ export declare const MAX_CHUNKS_PER_BATCH = 1000;
 export declare const getMaxChunksPerBatch: () => number;
 /**
  * Wire limit: maximum cumulative bytes in a single coalesced `writeMulti`.
- * Chunk *count* alone is not enough — 1,000 small chunks are ~100KB but 1,000
+ * Chunk *count* alone is not enough: 1,000 small chunks are ~100KB but 1,000
  * file-sized chunks can be hundreds of MB, which platform request-body limits
  * reject long before the count cap matters. A batch is split once adding the
  * next chunk would exceed this (a single chunk larger than the cap still goes
@@ -38,7 +38,7 @@ export declare const getMaxChunksPerBatch: () => number;
 export declare const MAX_BYTES_PER_BATCH: number;
 export declare const getMaxBytesPerBatch: () => number;
 /**
- * Buffer bound (bytes) for the server writable's group-commit buffer — the
+ * Buffer bound (bytes) for the server writable's group-commit buffer, the
  * byte-denominated counterpart of {@link MAX_INFLIGHT_CHUNKS}. `write()`
  * blocks once this much data is buffered-but-not-durable, so a fast producer
  * of large chunks can't grow client memory without bound. Default 8 MiB
@@ -59,7 +59,7 @@ export declare const getMaxBufferedBytes: () => number;
  * after each step body returns, so a coarser interval (the previous 100ms)
  * adds visible per-step latency to streaming workflows. With a uniformly
  * distributed offset between step return and the next tick, the expected
- * wait is half the interval — so 10ms means ~5ms average wait per step
+ * wait is half the interval, so 10ms means ~5ms average wait per step
  * instead of ~50ms. The per-tick work is `writable.locked` plus a
  * `getWriter()`/`releaseLock()` probe, both microsecond-scale; 10× more
  * ticks during a stream's lifetime is not measurable in practice.

package/dist/src/compiled/@workflow/core/global.d.ts

@@ -13,7 +13,7 @@ export interface StepInvocationQueueItem {
      * during replay: the queue message ID stamped by the invocation running
      * the step inline, or undefined when the latest start was unstamped (a
      * retry attempt driven by a queued step message, or an older runtime).
-     * Latest start wins — an unstamped bare start clears a previous stamp; an
+     * Latest start wins: an unstamped bare start clears a previous stamp; an
      * owner-recovery re-stamped start restores it.
      */
     ownerMessageId?: string;
@@ -65,6 +65,8 @@ export type QueueItem = StepInvocationQueueItem | HookInvocationQueueItem | Wait
  * onto the queue.
  */
 export declare class WorkflowSuspension extends Error {
+    items: QueueItem[];
+    /** @deprecated Use `items` instead. */
     steps: QueueItem[];
     globalThis: typeof globalThis;
     stepCount: number;
@@ -73,7 +75,7 @@ export declare class WorkflowSuspension extends Error {
     attributeCount: number;
     hookDisposedCount: number;
     abortCount: number;
-    constructor(stepsInput: Map<string, QueueItem>, global: typeof globalThis);
+    constructor(itemsInput: Map<string, QueueItem>, global: typeof globalThis);
     static is(value: unknown): value is WorkflowSuspension;
 }
 export declare function ENOTSUP(): never;

package/dist/src/compiled/@workflow/core/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Just the core utilities that are meant to be imported by user
+ * Core utilities intended for import by user
  * steps/workflows. This allows the bundler to tree-shake and limit what goes
  * into the final user bundles. Logic for running/handling steps/workflows
  * should live in runtime. Eventually these might be separate packages

package/dist/src/compiled/@workflow/core/index.js

@@ -1,2 +1,2 @@
-import{E as e,I as t,Jn as n,P as r,X as i,Z as a,cr as o,gr as s,hr as c,lr as l,mr as u,or as d,pr as f,rr as p,ur as m}from"../../_chunks/workflow/wait-until-BZHmJCAW.js";import{i as h,u as g}from"../../_chunks/workflow/dist-CqvWKNQv.js";import{a as _,i as v,r as y,t as b}from"../../_chunks/workflow/attribute-changes-DXbpwBdw.js";import"../../_chunks/workflow/dist-Dk0aQqFO.js";import{n as x}from"../../_chunks/workflow/resume-hook-E-Nkx8q_.js";import{t as S}from"../../_chunks/workflow/sleep-CxFsdxB_.js";function C(e){v(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,C)}function w(e){v(`createWebhook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-webhook`,w)}function T({schema:e}={}){function t(e){v(`defineHook().create()`,`https://workflow-sdk.dev/docs/api-reference/workflow/define-hook`,t)}return{create:t,async resume(t,n){if(!e?.[`~standard`])return await x(t,n);let r=e[`~standard`].validate(n);if(r instanceof Promise&&(r=await r),r.issues){let e=r.issues.map(e=>{let t=e.path?.map(e=>String(typeof e==`object`&&e?e.key:e)).join(`.`);return t?`  at "${t}": ${e.message}`:`  ${e.message}`});throw Error(`Hook payload did not match the defined schema:\n${e.join(`
-`)}`)}return await x(t,r.value)}}}async function E(e,t={}){let n=a.getStore(),r=n?.workflowMetadata?.workflowRunId;if(!r)throw new h(`setAttributes() must be called from a 'use workflow' or 'use step' function. Calling it from plain host code is not supported.`);let i=b(e,t);if(i.length!==0){if(n.runReadyBarrier)try{await n.runReadyBarrier}catch{}await(await d()).events.create(r,{eventType:`attr_set`,specVersion:6,eventData:{changes:i,writer:{type:`step`,stepId:n.stepMetadata.stepId,attempt:n.stepMetadata.attempt},...t.allowReservedAttributes===!0?{allowReservedAttributes:!0}:{}}})}}function D(){let e=a.getStore();return e||y(`getStepMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-step-metadata`,D),e.stepMetadata}function O(){let e=a.getStore();return e||_(`getWorkflowMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-workflow-metadata`,O),e.workflowMetadata}function k(d={}){let h=a.getStore();h||_(`getWritable()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-writable`,k);let{namespace:g}=d,v=h.workflowMetadata.workflowRunId,y=i(v,g);h.writables??=new Map;let b=h.writables,x=b.get(y);if(x)return x.writable;let S=t(r(globalThis,h.ops,v,h.encryptionKey,!0,h.runReadyBarrier),h.encryptionKey),C=new e(v,y,h.runReadyBarrier),w=o();return h.ops.push(w.promise),l(S.readable,C,w).catch(()=>{}),m(S.writable,w),Object.defineProperty(S.writable,f,{value:y,writable:!1}),Object.defineProperty(S.writable,s,{value:v,writable:!1}),h.workflowDeploymentId&&Object.defineProperty(S.writable,u,{value:h.workflowDeploymentId,writable:!1}),n(h.encryptionKey)&&Object.defineProperty(S.writable,c,{value:p(h.encryptionKey.keyPair.publicKey),writable:!1}),b.set(y,{writable:S.writable,state:w}),S.writable}export{h as FatalError,g as RetryableError,C as createHook,w as createWebhook,T as defineHook,D as getStepMetadata,O as getWorkflowMetadata,k as getWritable,E as setAttributes,S as sleep};
+import{J as e,M as t,P as n,Qn as r,Y as i,_r as a,br as o,fr as s,mr as c,pr as l,sr as u,ur as d,vr as f,w as p,yr as m}from"../../_chunks/workflow/wait-until-BtySPYD0.js";import{i as h,u as g}from"../../_chunks/workflow/dist-DjojkP5e.js";import{a as _,i as v,r as y,t as b}from"../../_chunks/workflow/attribute-changes-BwAadFfB.js";import"../../_chunks/workflow/dist-CgbVZs5l.js";import{n as x}from"../../_chunks/workflow/resume-hook-BToMtPbH.js";import{t as S}from"../../_chunks/workflow/sleep-3_A5uOp-.js";function C(e){v(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,C)}function w(e){v(`createWebhook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-webhook`,w)}function T({schema:e}={}){function t(e){v(`defineHook().create()`,`https://workflow-sdk.dev/docs/api-reference/workflow/define-hook`,t)}return{create:t,async resume(t,n){if(!e?.[`~standard`])return await x(t,n);let r=e[`~standard`].validate(n);if(r instanceof Promise&&(r=await r),r.issues){let e=r.issues.map(e=>{let t=e.path?.map(e=>String(typeof e==`object`&&e?e.key:e)).join(`.`);return t?`  at "${t}": ${e.message}`:`  ${e.message}`});throw Error(`Hook payload did not match the defined schema:\n${e.join(`
+`)}`)}return await x(t,r.value)}}}async function E(e,t={}){let n=i.getStore(),r=n?.workflowMetadata?.workflowRunId;if(!r)throw new h(`setAttributes() must be called from a 'use workflow' or 'use step' function. Calling it from plain host code is not supported.`);let a=b(e,t);if(a.length!==0){if(n.runReadyBarrier)try{await n.runReadyBarrier}catch{}await(await d()).events.create(r,{eventType:`attr_set`,specVersion:7,eventData:{changes:a,writer:{type:`step`,stepId:n.stepMetadata.stepId,attempt:n.stepMetadata.attempt},...t.allowReservedAttributes===!0?{allowReservedAttributes:!0}:{}}})}}function D(){let e=i.getStore();return e||y(`getStepMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-step-metadata`,D),e.stepMetadata}function O(){let e=i.getStore();return e||_(`getWorkflowMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-workflow-metadata`,O),e.workflowMetadata}function k(d={}){let h=i.getStore();h||_(`getWritable()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-writable`,k);let{namespace:g}=d,v=h.workflowMetadata.workflowRunId,y=e(v,g);h.writables??=new Map;let b=h.writables,x=b.get(y);if(x)return x.writable;let S=n(t(globalThis,h.ops,v,h.encryptionKey,!0,h.runReadyBarrier),h.encryptionKey),C=new p(v,y,h.runReadyBarrier),w=s();return h.ops.push(w.promise),l(S.readable,C,w).catch(()=>{}),c(S.writable,w),Object.defineProperty(S.writable,a,{value:y,writable:!1}),Object.defineProperty(S.writable,o,{value:v,writable:!1}),h.workflowDeploymentId&&Object.defineProperty(S.writable,f,{value:h.workflowDeploymentId,writable:!1}),r(h.encryptionKey)&&Object.defineProperty(S.writable,m,{value:u(h.encryptionKey.keyPair.publicKey),writable:!1}),b.set(y,{writable:S.writable,state:w}),S.writable}export{h as FatalError,g as RetryableError,C as createHook,w as createWebhook,T as defineHook,D as getStepMetadata,O as getWorkflowMetadata,k as getWritable,E as setAttributes,S as sleep};

package/dist/src/compiled/@workflow/core/log-format.d.ts

@@ -9,7 +9,7 @@
  *       step   step_… · add (./workflows/x)
  *       hint:  Move the call to a step function.
  *     FatalError: …
- *         at … (trimmed stack — internals collapsed)
+ *         at … (trimmed stack, internals collapsed)
  *
  * Without this composition, callers passing `${framing}\n${stack}` as the
  * message and structured fields as the metadata object got `util.inspect`'s
@@ -18,7 +18,7 @@
  *
  * The same metadata is also emitted as structured OTel span events from
  * the logger itself, so backends that want JSON-shaped data still get it.
- * web/web-shared do not consume stderr at all — they read CBOR/JSON event
+ * web/web-shared do not consume stderr at all: they read CBOR/JSON event
  * payloads from the World event log.
  */
 export declare function composeLogLine(prefix: string, message: string, metadata: Record<string, unknown> | undefined): string;

package/dist/src/compiled/@workflow/core/private.d.ts

@@ -3,7 +3,7 @@
  */
 import type { WorldCapabilities } from '#compiled/@workflow/world/index.js';
 import type { EventsConsumer } from './events-consumer.js';
-import type { QueueItem } from './global.js';
+import { type QueueItem } from './global.js';
 import type { ReplayPayloadCache } from './replay-payload-cache.js';
 import type { Serializable } from './schemas.js';
 import type { PayloadKey } from './serialization/encryption.js';
@@ -32,12 +32,12 @@ export interface WorkflowOrchestratorContext {
     globalThis: typeof globalThis;
     /**
      * Increments when a suspension is accepted and on every retained-session
-     * resume. STEP suspension signals capture it when scheduled and no-op if
-     * it moved (see step.ts) — this drops same-boundary sibling signals and
-     * timers queued at boundary N that would fire after the session resumed
-     * into boundary N+1. Sleep/hook/attribute signals are intentionally
-     * unguarded: their presence makes the boundary unretainable, so a late
-     * signal correctly demotes the session (workflow.ts `onWorkflowError`).
+     * resume. Step, hook, and attribute suspension signals capture it when
+     * scheduled and no-op if it moved, which drops same-boundary sibling signals
+     * and timers queued at boundary N that would fire after the session resumed
+     * into boundary N+1. Sleep signals are intentionally unguarded: their
+     * presence makes the boundary unretainable, so a late signal correctly
+     * demotes the session (workflow.ts `onWorkflowError`).
      */
     suspensionGeneration: number;
     eventsConsumer: EventsConsumer;
@@ -53,6 +53,14 @@ export interface WorkflowOrchestratorContext {
      * whole run and both replays of a run must draw in the same order.
      */
     generateUlid: () => string;
+    /**
+     * Monotone count of correlation-id draws this replay has made. Progress
+     * metric for {@link quiesceEarlierCascades}: a macrotask turn in which it
+     * does not move (and no hydration is in flight) means every woken branch has
+     * run as far as it can without another delivery. Optional so lightweight
+     * test contexts degrade to the single-yield behavior.
+     */
+    readonly mintCount?: number;
     generateNanoid: () => string;
     /**
      * Sequential promise queue that ensures all event-driven promise resolutions
@@ -66,12 +74,12 @@ export interface WorkflowOrchestratorContext {
      * Counter of in-flight async data delivery operations (step result
      * hydration, hook payload hydration, abort signal hydration). Suspensions
      * must wait for this to reach 0 before firing, to avoid preempting data
-     * delivery — e.g. dehydrating a step's arguments while an abort that should
+     * delivery, e.g. dehydrating a step's arguments while an abort that should
      * be reflected in those arguments is still hydrating its reason.
      */
     pendingDeliveries: number;
     /**
-     * Ordered registry of in-flight "branch-deciding" deliveries — the
+     * Ordered registry of in-flight "branch-deciding" deliveries: the
      * resolutions a workflow typically `Promise.race`s on, or awaits from
      * independent concurrent branches: hook payloads (`hook_received`), wait
      * completions (`wait_completed`), and step results (`step_completed` /
@@ -84,7 +92,7 @@ export interface WorkflowOrchestratorContext {
      * costing extra hops; a `wait_completed` resolves with fewer, and a reused
      * sleep can resolve in an entirely earlier loop iteration; a step result is
      * gated on hydration whose cost varies between replays of the SAME
-     * invocation — the first replay pays the full decrypt/decompress/revive,
+     * invocation: the first replay pays the full decrypt/decompress/revive,
      * while later replays sharing the invocation's `ReplayPayloadCache`
      * memo-hit small primitive results and resolve in one or two hops. Either
      * way, the resolution that the committed event log ordered first can lose a
@@ -118,8 +126,8 @@ export interface WorkflowOrchestratorContext {
 export type DeliveryKind = 'hook' | 'wait' | 'step';
 interface DeliveryBarrierEntry {
     kind: DeliveryKind;
-    /** Resolves once this delivery has resolved to the workflow. */
-    delivered: Promise<void>;
+    /** Resolves once this delivery is handed to the workflow or retired. */
+    released: Promise<void>;
     /**
      * Whether this delivery is committed to reaching the workflow without any
      * further action by workflow code. True for wait completions and step
@@ -127,77 +135,29 @@ interface DeliveryBarrierEntry {
      * that already had a waiting consumer when it was consumed.
      *
      * False for a BUFFERED hook payload no consumer has claimed yet: it is
-     * delivered by `claim()`, i.e. whenever the workflow next reads the hook —
+     * delivered by `claim()`, i.e. whenever the workflow next reads the hook,
      * which may be causally *after* a later-in-log delivery. `arm()` flips it
      * once a consumer takes the payload.
      */
     armed: boolean;
+    /** Whether this entry has been removed and its `released` promise settled. */
+    retired: boolean;
     /**
-     * Retire this entry: resolve `delivered` and remove it from the registry,
-     * exactly as `markDelivered` would. Called only by the context's safety-net
-     * dispenser ({@link ensureBarrierSafetyNet}), and only on the lowest-index
-     * entry at delivery idle. Idempotent.
+     * Retire this entry: resolve `released` and remove it from the registry,
+     * without marking the handle delivered to the workflow. A safety-retired
+     * buffered payload may therefore install a fresh entry if it is claimed by
+     * a retained VM later. Called only by the context's safety-net dispenser
+     * ({@link ensureBarrierSafetyNet}), and only on the lowest-index entry at
+     * delivery idle. Idempotent.
      */
     retire: () => void;
 }
-/**
- * Awaits, in strict event-log order, every still-registered delivery that is
- * earlier in the log than `eventIndex` and that a delivery of `kind` defers
- * behind (see {@link DEFER_BEHIND}), so that this resolution is handed to the
- * workflow only after all relevant earlier-in-log deliveries have been. This
- * is what keeps a `Promise.race` — or the ULID a follow-up `useStep` draws on
- * a concurrent branch — deterministic and aligned with the committed event
- * log, independent of microtask-hop counts, hydration time, or race-argument
- * order. When this delivery does have to wait, it also yields a macrotask
- * afterwards so the earlier delivery's consumer can run to its own next
- * suspension point first; see the comment at that `await` for why ordering the
- * `resolve()` calls alone is not enough.
- *
- * What counts as "defers behind" is {@link gatesOn}, shared with
- * {@link computeResolvesOnItsOwn} so the two cannot drift.
- *
- * One asymmetry: a STEP result skips any earlier delivery that is UNARMED,
- * i.e. a buffered hook payload no consumer has claimed. Such a payload is
- * delivered only when the workflow next reads the hook, and reaching that read
- * very commonly requires the step result itself (`await stepX()` before the
- * read). Gating the step on it would stall the workflow until the barrier's
- * idle safety net fires, which then releases every delivery queued behind that
- * payload at once — losing exactly the race this ordering exists to protect.
- * Waits and hooks keep gating on unclaimed payloads: for them, waiting for the
- * claim IS the ordering guarantee (a `wait_completed` must not preempt a
- * payload the log ordered first).
- *
- * The skip is direct, never transitive. A step still gates on an earlier ARMED
- * wait or hook, including one that is itself parked behind an unclaimed
- * payload. Skipping those too would invert log order for the commonest shape
- * there is: a workflow that creates a hook it does not read on this branch,
- * races `step` against `sleep`, and has the log say the sleep won. The step
- * would then overtake the wait, both branches would swap the correlation ids
- * they draw next, and replay would diverge — see
- * `step-delivery-ordering.test.ts`. Waiting instead is safe because the
- * payload's own idle safety net retires it and the whole chain then delivers
- * in log order; {@link hasParkedCommittedDelivery} deliberately reports such a
- * step as not self-resolving so that idle stays reachable.
- *
- * "The whole chain then delivers in log order" rests on the PAYLOAD's barrier
- * being retired before that of anything parked behind it. That order is
- * structural: safety-net retirements go through one per-context dispenser that
- * only ever retires the lowest-index entry at delivery idle, and every
- * retirement that wakes a chain flips {@link hasParkedCommittedDelivery} back
- * to true, re-blocking the dispenser until the chain has drained — see
- * {@link ensureBarrierSafetyNet}. (This used to rest on the FIFO of one idle
- * poll per barrier, which held for a single parked segment but decayed to
- * timing noise with several — the release order, and therefore the ULIDs
- * drawn by the woken branches, then depended on how much log the replay had
- * loaded. storm-log-replay.test.ts replays a production log corrupted exactly
- * that way.)
- */
 export declare function awaitEarlierDeliveries(ctx: WorkflowOrchestratorContext, eventIndex: number | undefined, kind: DeliveryKind): Promise<void>;
 /** Handle for a registered branch-deciding delivery barrier. */
 export interface DeliveryBarrier {
     /**
      * Mark this delivery as delivered to the workflow. Resolves its
-     * `delivered` promise so any later-in-log delivery gated on it (via
+     * `released` promise so any later-in-log delivery gated on it (via
      * {@link awaitEarlierDeliveries}) may proceed, and removes it from the
      * registry. Idempotent.
      */
@@ -222,12 +182,12 @@ export interface DeliveryBarrier {
  * suspending and never observes it), the barrier auto-resolves at idle.
  *
  * INVARIANT required of every call site: a barrier that is ever `armed` must
- * be paired with a delivery chain that runs unconditionally — attached when
+ * be paired with a delivery chain that runs unconditionally, attached when
  * the event is consumed (waits, step results, waiting-consumer hook payloads,
  * aborts), or by the `claim()` whose invocation is what arms it (buffered
  * hook payloads). The idle check ({@link scheduleWhenIdle}) refuses to
  * observe idle while an armed, self-resolving barrier is undelivered, and the
- * safety net below is itself idle-gated — so an armed barrier with no
+ * safety net below is itself idle-gated, so an armed barrier with no
  * unconditional chain would livelock every idle check in the run, including
  * its own retirement.
  */
@@ -237,19 +197,19 @@ export declare function registerDeliveryBarrier(ctx: WorkflowOrchestratorContext
 /**
  * Whether some registered branch-deciding delivery is going to reach the
  * workflow without any further help (it is armed and not transitively parked
- * behind an unclaimed buffered payload — see {@link resolvesOnItsOwn}) but
+ * behind an unclaimed buffered payload, see {@link resolvesOnItsOwn}) but
  * has not been handed over yet.
  *
  * This is the delivery state `pendingDeliveries` cannot see. That counter
  * covers the hydration window inside a serial `promiseQueue` slot and is
  * released there, while the delivery's `resolve()` runs later, from a
- * detached continuation behind {@link awaitEarlierDeliveries} — including its
+ * detached continuation behind {@link awaitEarlierDeliveries}, including its
  * macrotask yield whenever the delivery had to defer. Replaying a batch of N
  * parallel step results consumed in one drain window leaves N-1 of them
  * parked on that yield with `pendingDeliveries` already at 0. An idle check
  * armed during the same window (a pending `sleep()` arms one on every replay)
  * could then observe "idle" mid-deferral and raise a `WorkflowSuspension`
- * BEFORE the workflow's own continuations ran — a suspension carrying none of
+ * BEFORE the workflow's own continuations ran: a suspension carrying none of
  * the follow-up work the batch was about to create, which the runtime
  * dutifully schedules as nothing, leaving the run dormant until an unrelated
  * timer fires (vercel/workflow#3183).
@@ -258,7 +218,7 @@ export declare function registerDeliveryBarrier(ctx: WorkflowOrchestratorContext
  * accuracy but for termination: an unclaimed buffered hook payload is retired
  * BY the idle safety net in {@link registerDeliveryBarrier}, so counting it
  * here would gate its own retirement. That reasoning extends to whatever is
- * parked behind such a payload — a wait, and a step gating on that wait — for
+ * parked behind such a payload (a wait, and a step gating on that wait) for
  * the same reason: the whole chain moves only once the net fires, and it
  * cannot fire while the chain is counted. Self-resolving deliveries always
  * deliver from their own chains (see the INVARIANT on
@@ -272,7 +232,7 @@ export declare function hasParkedCommittedDelivery(ctx: WorkflowOrchestratorCont
  * "In flight" is two distinct windows, each with its own guard:
  * `pendingDeliveries > 0` covers hydration inside the serial queue slots, and
  * {@link hasParkedCommittedDelivery} covers the detached gap between a slot
- * releasing that counter and the delivery's `resolve()` actually running —
+ * releasing that counter and the delivery's `resolve()` actually running,
  * deliberately outside `pendingDeliveries` (see step.ts), and invisible to it.
  *
  * Anything that decides a replay is over, or that a replay went wrong, has to
@@ -285,7 +245,7 @@ export declare function hasParkedCommittedDelivery(ctx: WorkflowOrchestratorCont
  * entry is parked behind an unclaimed buffered payload. Those entries only
  * move when the safety-net dispenser retires them (lowest-first, see
  * {@link ensureBarrierSafetyNet}), and the deliveries they release are real
- * workflow reactions — a suspension raised before they run would be computed
+ * workflow reactions: a suspension raised before they run would be computed
  * from a VM that has not seen them, scheduling none of their follow-up work
  * and leaving the run dormant (the vercel/workflow#3183 shape). The dispenser
  * itself is gated on {@link canRetireAbandonedBarriers}, the weaker predicate
@@ -316,5 +276,7 @@ export declare function isDeliveryIdle(ctx: WorkflowOrchestratorContext): boolea
  * breaks hook/sleep `Promise.race` ordering (CorruptedEventLogError).
  */
 export declare function scheduleWhenIdle(ctx: WorkflowOrchestratorContext, fn: () => void): void;
+/** Schedule a generation-guarded suspension after deliveries settle. */
+export declare function scheduleWorkflowSuspension(ctx: WorkflowOrchestratorContext): void;
 export {};
 //# sourceMappingURL=private.d.ts.map

package/dist/src/compiled/@workflow/core/private.js

@@ -1 +1 @@
-import{a as e,i as t,n,o as r,r as i,s as a,t as o}from"../../_chunks/workflow/private-CuQ4HTFC.js";export{o as awaitEarlierDeliveries,n as getStepFunction,i as hasParkedCommittedDelivery,t as isDeliveryIdle,e as registerDeliveryBarrier,r as registerStepFunction,a as scheduleWhenIdle};
+import{a as e,c as t,i as n,n as r,o as i,r as a,s as o,t as s}from"../../_chunks/workflow/private-CZFMABEf.js";export{s as awaitEarlierDeliveries,r as getStepFunction,a as hasParkedCommittedDelivery,n as isDeliveryIdle,e as registerDeliveryBarrier,i as registerStepFunction,o as scheduleWhenIdle,t as scheduleWorkflowSuspension};

package/dist/src/compiled/@workflow/core/replay-payload-cache.d.ts

@@ -10,33 +10,26 @@ type ReplayPayloadField = 'result' | 'error' | 'payload';
  * those replays. Deserialization still runs against each VM's globals so every
  * replay receives fresh object graphs and correctly revived Workflow objects.
  *
- * Successful prepared plaintext remains resident for the invocation lifetime.
- * Its memory cost is the sum of decrypted and decompressed payload sizes, but
- * it never crosses workflow runs or queue deliveries.
+ * Successful prepared plaintext and memoized primitive step results remain
+ * resident for the invocation lifetime. Their memory never crosses workflow
+ * runs or queue deliveries.
  */
 export declare class ReplayPayloadCache {
-    private readonly encryptionKey;
     private readonly preparer;
     private readonly preparedPayloads;
     private readonly primitiveStepResults;
+    private readonly encryptionKey;
     private nextUnscannedEventIndex;
-    constructor(encryptionKey: PayloadKey | undefined, preparer?: ReplayPayloadPreparer);
+    constructor(encryptionKey: PayloadKey | undefined | Promise<PayloadKey | undefined>, preparer?: ReplayPayloadPreparer);
+    /** Start preparing an event payload as soon as its frame is decoded. */
+    prepareEvent(event: Event): void;
     /**
      * Start every missing binary preparation before workflow execution. Failures
      * are intentionally retained: the ordered event consumer must observe the
      * original rejection before that entry becomes retryable.
      */
     prewarm(workflowRun: WorkflowRun, events: Event[]): Promise<void>;
-    /**
-     * Forget how much of the event log has been scanned, so the next
-     * {@link prewarm} walks it from the start again.
-     *
-     * Required before a replay whose event log was reloaded rather than extended:
-     * a corrected log inserts the events the previous load was missing, which
-     * shifts every later position, so a positional resume would skip exactly the
-     * events the reload was for. Already-prepared payloads are kept — they are
-     * keyed by event id, so re-scanning re-observes them for free.
-     */
+    /** Rescan the next event log after an authoritative replacement. */
     resetScan(): void;
     /** Return the workflow input after shared host-side preparation. */
     prepareWorkflowInput(workflowRun: WorkflowRun): Promise<PreparedReplayPayload>;
@@ -48,8 +41,8 @@ export declare class ReplayPayloadCache {
     prepareEventPayload(eventId: string, field: ReplayPayloadField, value: unknown): Promise<PreparedReplayPayload>;
     /**
      * Reuse final step values only when sharing them across VMs is unobservable.
-     * Objects and large strings/bigints always run `hydrate` again, producing a
-     * fresh VM-specific value from the separately cached prepared payload.
+     * Objects always run `hydrate` again to produce a fresh VM-specific value;
+     * every primitive is safe to reuse directly.
      */
     getStepResult(eventId: string, hydrate: () => Promise<unknown>): Promise<unknown>;
     /**
@@ -61,6 +54,9 @@ export declare class ReplayPayloadCache {
     private ensurePreparation;
     /** Normalize synchronous and asynchronous preparers to one promise contract. */
     private runPreparation;
+    /** Start one event's binary payload unless another path already did. */
+    private prepareEventIfMissing;
+    private startPreparation;
     private workflowInputKey;
     private eventPayloadKey;
 }