eve 0.48.0 → 0.49.0

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

@@ -1,11 +1,11 @@
 /**
- * QuickJS WASM workflow VM.
+ * QuickJS WebAssembly (WASM) workflow VM.
  *
  * An alternative engine for the event-replay execution model: the workflow
  * code runs inside a QuickJS WASM VM (via quickjs-wasi) instead of a
  * `node:vm` context. Every invocation creates a fresh VM, re-executes the
  * workflow function from the top, and replays the recorded event log to
- * resolve awaited primitives — the same replay semantics as the `node:vm`
+ * resolve awaited primitives: the same replay semantics as the `node:vm`
  * engine.
  *
  * The workflow primitives (useStep, sleep, createHook) are implemented as
@@ -14,11 +14,11 @@
  * resolve/reject promises.
  *
  * The VM bootstrap is deliberately split into two phases:
- *   1. Static initialization (`initWorkflowVM`) — run-independent setup:
+ *   1. Static initialization (`initWorkflowVM`): run-independent setup:
  *      VM creation and the workflow primitives. (Serialization lives on
- *      the host — see quickjs-serde.ts — so no serde code is evaluated
+ *      the host (see quickjs-serde.ts) so no serde code is evaluated
  *      in the VM.)
- *   2. Per-run initialization (inline in `runQuickJSWorkflow`) — seeded
+ *   2. Per-run initialization (inline in `runQuickJSWorkflow`): seeded
  *      PRNG/ULID host functions, workflow bundle evaluation, run metadata,
  *      workflow input, and start.
  * Keeping the phases separate is groundwork for VM-memory snapshotting:
@@ -28,17 +28,33 @@
  * module-scope user code observes the seeded `Math.random`, matching the
  * `node:vm` engine's replay determinism.
  */
-import type { Event, RunInput, WorkflowRun, WorldCapabilities } from '#compiled/@workflow/world/index.js';
+import { SerializationError } from '#compiled/@workflow/errors/index.js';
+import { type Event, type RunInput, type WorkflowRun, type WorldCapabilities } from '#compiled/@workflow/world/index.js';
 import { type Snapshot } from '../_quickjs-wasi.js';
 import type { DecryptionKey } from '../serialization/encryption.js';
 export interface PendingStep {
     type: 'step';
     correlationId: string;
     stepId: string;
-    /** Format-prefixed devalue-serialized step input (args + closureVars) */
-    input: Uint8Array;
+    /**
+     * Format-prefixed devalue-serialized step input (args + closureVars).
+     * Absent when {@link serializationError} is set: the input is precisely
+     * what refused to serialize.
+     */
+    input?: Uint8Array;
     /** Whether a step_created event already exists for this step */
     hasCreatedEvent: boolean;
+    /**
+     * Set when host-side serialization of the step's raw input failed while
+     * dumping the VM's pending ops (see `dumpPendingOps`). The failure is
+     * deterministic (replaying re-derives the same unserializable value), so
+     * instead of failing the whole collection the op is surfaced with the
+     * reframed error and no `input`; the entrypoint finalizes the step as
+     * `step_created` (placeholder input) + `step_failed`, mirroring the
+     * node:vm engine's `finalizeUnserializableStep`, so a try/catch around
+     * the step call observes the SerializationError.
+     */
+    serializationError?: SerializationError;
 }
 export interface PendingWait {
     type: 'wait';
@@ -100,7 +116,7 @@ export interface PendingHookDispose {
 }
 export type PendingOperation = PendingStep | PendingWait | PendingHook | PendingAttribute | PendingHookDispose;
 export interface QuickJSRuntimeResult {
-    /** The workflow completed — result is format-prefixed devalue bytes */
+    /** The workflow completed: result is format-prefixed devalue bytes */
     completed?: {
         result: Uint8Array;
         /**
@@ -121,7 +137,7 @@ export interface QuickJSRuntimeResult {
         message: string;
         stack?: string;
         name?: string;
-        /** See completed.drainOperations — same semantics on failure. */
+        /** See completed.drainOperations: same semantics on failure. */
         drainOperations?: PendingOperation[];
         /**
          * Format-prefixed devalue bytes of the original thrown value
@@ -155,8 +171,8 @@ export interface QuickJSRuntimeOptions {
     /**
      * The local port the workflow server is listening on, used to populate
      * `workflowMetadata.url`. Resolved at call time on the host side so the
-     * VM doesn't have to probe the filesystem. Ignored on Vercel — VERCEL_URL
-     * takes precedence there.
+     * VM doesn't have to probe the filesystem. Ignored on Vercel, where
+     * VERCEL_URL takes precedence.
      */
     port?: number;
     /**
@@ -170,7 +186,7 @@ export interface QuickJSRuntimeOptions {
  * Eval filename used when hydrating the baseline VM. The baseline is
  * shared by EVERY workflow in the bundle, so the filename baked into
  * its compiled code (and therefore into snapshot-path stack frames)
- * must be workflow-independent — hydrating under the first caller's
+ * must be workflow-independent: hydrating under the first caller's
  * workflowId would break `remapErrorStack`'s filename matching for
  * every other workflow in the bundle. Remap call sites match this
  * constant IN ADDITION to the run's module specifier (which covers
@@ -185,7 +201,7 @@ type BaselineEntry = {
      * bundle evaluated (see captureSerdeRoot). The box lives in the
      * snapshot's memory image at this offset; every restored VM
      * re-adopts it so serde initialization executes no guest code
-     * after user code has run — capture-before-user-code semantics,
+     * after user code has run: capture-before-user-code semantics,
      * identical to the fresh path.
      */
     serdeRootPtr: number;
@@ -201,7 +217,7 @@ export declare function __peekBaselineEntryForTests(workflowCode: string): Promi
  * A live QuickJS workflow invocation. When the initial `result` is
  * `suspended`, the VM is kept alive so the caller can feed newly recorded
  * events (e.g. terminal events of inline-executed steps) into the SAME VM
- * via `continueWithEvents` — resuming execution exactly where it left off
+ * via `continueWithEvents`, resuming execution exactly where it left off
  * without a fresh-VM re-replay. Terminal results dispose the VM
  * automatically; `dispose()` must be called when abandoning a suspended
  * session (idempotent).

package/dist/src/compiled/@workflow/core/runtime/quickjs-serde.d.ts

@@ -6,8 +6,8 @@
  * host code operating on `JSValueHandle`s, using devalue 5.9's pluggable
  * operations (quickjs-wasi's host-side introspection primitives underneath).
  * The serde bundle previously evaluated inside the VM is gone: guest values
- * are read and built through handles, so no serializer code lives in — or
- * can be tampered with from — the guest realm.
+ * are read and built through handles, so no serializer code lives in (or
+ * can be tampered with from) the guest realm.
  *
  * Side-effect discipline mirrors the node:vm engine's hardened codec
  * (serialization/hardened.ts):
@@ -17,7 +17,7 @@
  *   `Symbol.toStringTag`;
  * - extraction goes through intrinsics captured at boot (before any user
  *   code runs) invoked with explicit receivers, or through own-property
- *   descriptor reads — patched prototypes and inherited accessors never
+ *   descriptor reads, so patched prototypes and inherited accessors never
  *   run;
  * - the only guest code serialization can execute is the same code the
  *   previous in-VM codec executed by contract: a class's static
@@ -30,7 +30,7 @@
  * versa).
  *
  * Hybrid value space: reducers return host shapes (plain objects, strings,
- * numbers) whose leaves may be guest handles — exactly how the node:vm
+ * numbers) whose leaves may be guest handles, exactly how the node:vm
  * codec mixes host shapes with sandbox-realm leaves. Every stringify
  * operation therefore dispatches on `JSValueHandle` and falls back to
  * devalue's default host operations for host values. Parse operations
@@ -42,7 +42,7 @@ import { JSValueHandle, type QuickJS } from '../_quickjs-wasi.js';
  * bootstrap and BEFORE any user code. The returned handle owns the
  * container; on the baseline-snapshot path its raw box pointer
  * (`handle.ptr`) is recorded next to the snapshot and re-adopted per
- * restored VM via {@link adoptSerdeRoot} — do NOT dispose the handle
+ * restored VM via {@link adoptSerdeRoot}. Do NOT dispose the handle
  * before the snapshot is taken (the box must stay live in the memory
  * image).
  */
@@ -51,14 +51,14 @@ export declare function captureSerdeRoot(vm: QuickJS): JSValueHandle;
  * Re-create the capture-root handle in a VM restored from a snapshot
  * taken while the exported root was alive, via quickjs-wasi's
  * snapshot-portable handle tokens (`importHandle` duplicates the
- * underlying value — the returned handle is independently owned and the
+ * underlying value: the returned handle is independently owned and the
  * serde disposes it per restored VM). No guest code executes.
  */
 export declare function adoptSerdeRoot(vm: QuickJS, token: number): JSValueHandle;
 /**
  * Export the capture root as a snapshot-portable token to record next to
  * the baseline snapshot. The root handle must stay undisposed until the
- * snapshot is taken (its box — and the reference it holds — must be part
+ * snapshot is taken (its box, and the reference it holds, must be part
  * of the memory image).
  */
 export declare function exportSerdeRoot(vm: QuickJS, root: JSValueHandle): number;
@@ -70,7 +70,7 @@ export interface QuickJSSerde {
     /**
      * The reducer names this codec applies, in registration order. Exposed
      * so tests can assert exhaustiveness against the shared value-space
-     * codec (codec-devalue-vm) — a reducer added there but not here would
+     * codec (codec-devalue-vm): a reducer added there but not here would
      * otherwise silently round-trip values as plain objects.
      */
     reducerKeys: readonly string[];
@@ -78,7 +78,7 @@ export interface QuickJSSerde {
     reviverKeys: readonly string[];
     /**
      * Install `globalThis.process = { env: Object.freeze({...}) }` in the
-     * VM through handles and boot-captured intrinsics only — no guest
+     * VM through handles and boot-captured intrinsics only: no guest
      * source is evaluated, so a module-scope wrapper around JSON.parse /
      * Object.freeze cannot observe the injection. This matters on the
      * baseline-snapshot path, where env injection happens after user code
@@ -98,7 +98,7 @@ export declare function createQuickJSSerde(vm: QuickJS,
  * Pre-captured serde root (baseline-snapshot path): the container
  * `captureSerdeRoot` created BEFORE user code, re-adopted from the
  * restored memory image via `adoptSerdeRoot`. When omitted, the root
- * is captured now — callers must guarantee no user code has run yet.
+ * is captured now; callers must guarantee no user code has run yet.
  * Either way, initialization below performs only plain-data property
  * reads and C-level classId reads on the container: NO guest code
  * executes here, so nothing user-patchable can observe or perturb it.

package/dist/src/compiled/@workflow/core/runtime/replay-budget.d.ts

@@ -4,7 +4,7 @@ import { type SlotSnapshotParams } from './helpers.js';
  * handler run: deterministic event-log replay, workflow-VM execution
  * between step boundaries, suspension handling, queue round-trips, etc.
  * Inline step bodies (`"use step"` functions invoked via `executeStep`)
- * are intentionally excluded — they are bounded by the platform's
+ * are intentionally excluded since they are bounded by the platform's
  * function `maxDuration` and the `NO_INLINE_REPLAY_AFTER_MS` early-return
  * guard.
  *
@@ -30,7 +30,7 @@ import { type SlotSnapshotParams } from './helpers.js';
  *   This protects against double-counting in future refactors that nest
  *   step execution or take an early-return path between a `pause()` and
  *   the matching `resume()`.
- * - `isExhausted()` is checked at loop boundaries by the caller — the
+ * - `isExhausted()` is checked at loop boundaries by the caller; the
  *   budget itself does not arm any timers. This means an in-flight
  *   pathological `runWorkflow` call (e.g. a huge event-log replay) can
  *   overshoot the budget by up to one iteration's worth of work before
@@ -54,13 +54,13 @@ export declare class ReplayBudget {
      */
     elapsed(): number;
     /**
-     * Stop counting elapsed time toward the budget. Idempotent — safe to
+     * Stop counting elapsed time toward the budget. Idempotent: safe to
      * call multiple times in a row; subsequent calls are no-ops until
      * `resume()` reopens an interval.
      */
     pause(): void;
     /**
-     * Resume counting elapsed time toward the budget. Idempotent — safe to
+     * Resume counting elapsed time toward the budget. Idempotent: safe to
      * call multiple times in a row; subsequent calls re-anchor the
      * interval start to `now()`, which is fine because no time accrues
      * between back-to-back `resume()` calls.

package/dist/src/compiled/@workflow/core/runtime/replay-recovery-reporter.d.ts

@@ -17,7 +17,7 @@ export declare class ReplayRecoveryReporter {
      * it, so `withEventCreate` always passes writes through untouched. Lets every
      * call site hold a non-optional reporter instead of branching on one.
      *
-     * Structurally inert rather than a zero-count reporter on purpose — the
+     * Structurally inert rather than a zero-count reporter on purpose: the
      * server rejects a count below 1 as out-of-range and emits a
      * `telemetry_rejected` metric, so a reporter that *can* report zero is a
      * live footgun.

package/dist/src/compiled/@workflow/core/runtime/resume-hook.d.ts

@@ -15,18 +15,10 @@ export declare function getHookByToken(token: string): Promise<Hook>;
  * The result of {@link resumeHook}: a {@link Hook} augmented with an optional
  * resilience signal.
  *
- * On the parallel fast path, `resumeHook()` writes the `hook_received` event and
- * dispatches the workflow queue message concurrently. When the direct event
- * write fails *transiently* — a 429/5xx, a transport error, or an expected
- * `(runId, resumeId)` conflict with its own re-ensuring consumer — but the queue
- * dispatch succeeds, the resume is still guaranteed: the queue consumer
- * idempotently materializes the `hook_received` event from the payload carried
- * on the message before replay. In that recovered case the returned hook carries
- * `resilientResume: true`.
- *
- * On the happy path (the direct write landed) and on the sequential fallback
- * path, the flag is absent (`undefined`). Callers that don't care about the
- * distinction can treat the result as a plain {@link Hook}.
+ * `resilientResume` is retained for source compatibility and is never set.
+ * `resumeHook()` now requires the durable `hook_received` write and workflow
+ * wake to both succeed before it resolves. Treat the result as a plain
+ * {@link Hook}.
  */
 export type ResumedHook = Hook & {
     resilientResume?: boolean;
@@ -37,6 +29,22 @@ export type ResumedHook = Hook & {
  * This function is called externally (e.g., from an API route or server action)
  * to send data to a hook and resume the associated workflow run.
  *
+ * Resolving means BOTH that the `hook_received` event is durably recorded in
+ * the run's event log and that the workflow wake was accepted by the queue, in
+ * that order. A {@link HookNotFoundError} means this invocation committed no
+ * event. Any other error after the write is ambiguous only in dispatch, never
+ * in durability: the event may already be committed, and a later wake of the
+ * run (from any source) will deliver it.
+ *
+ * Prefer passing the token string over a cached {@link Hook} object. A token
+ * is looked up fresh, so the live backend can attest its atomic resume claim
+ * and the durable write becomes idempotent-on-retry (transport retries of the
+ * same write converge on one event). A supplied Hook object may carry a stale
+ * attestation, so it is deliberately ignored and the write is claim-less —
+ * meaning a lost response cannot be retried safely: retrying at the
+ * application level mints a fresh claim and can commit a second
+ * `hook_received`.
+ *
  * @param tokenOrHook - The unique token identifying the hook, or the hook object itself
  * @param payload - The data payload to send to the hook
  * @returns Promise resolving to the {@link ResumedHook}

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

@@ -6,46 +6,53 @@ import type { HookResumeTiming } from '#compiled/@workflow/world/index.js';
  *
  * ```text
  * T0 resumeHook() entered
- *      producer_prep   — hook lookup, serialization, encryption
+ *      producer_prep   : hook lookup, serialization, encryption
  * T1 queue publish requested
- *      queue_delivery  — network + VQS delivery (incl. any affinity re-route)
+ *      queue_delivery  : network + VQS delivery (incl. any affinity re-route)
  * T2 final consumer's queue handler entered
- *      resume_setup    — affinity check, hook_received re-ensure, replay preload
+ *      resume_setup    : affinity check, hook_received re-ensure, replay preload
  * T3 replay begins
- *      replay          — VM/session creation and workflow replay
+ *      replay          : VM/session creation and workflow replay
  * T4 next durable step encountered
- *      step_dispatch   — suspension handling, inline batch or queue dispatch
+ *      step_dispatch   : suspension handling, inline batch or queue dispatch
  * T5 step_started request begins
- *      step_claim      — the claim round trip
+ *      step_claim      : the claim round trip
  * T6 step_started response returned
- *      step_prepare    — key resolution, argument hydration, context setup
+ *      step_prepare    : key resolution, argument hydration, context setup
  * T7 immediately before stepFn.apply()
  * ```
  *
- * The producer's direct `hook_received` POST races the queue publish on the
- * parallel fast path, so it deliberately has no phase of its own — the two
- * overlap, and representing both as additive phases would double-count. It
- * remains visible as a contextual span (`hook.resume`).
+ * The producer's `hook_received` write is awaited inside `producer_prep`
+ * (the wake is only published after it commits). Older producers may report
+ * `lazy`, where the consumer materializes the event from `hookInput`, or
+ * `parallel`, where the write raced the publish. The write has no phase of
+ * its own; it remains visible as a contextual span (`hook.resume`).
  *
  * T0/T1 are stamped on the producer's machine and T2..T7 on the consumer's, so
  * the measurement is subject to cross-machine clock skew. Rather than clamp
  * (which would break the sum-equals-total property this decomposition exists
- * for), a non-monotonic boundary set drops the whole sample — see
+ * for), a non-monotonic boundary set drops the whole sample; see
  * {@link computeResumeTtrAttributes}.
  */
 /** What caused the resumption being measured. Only hooks are measured today. */
 export type ResumeTrigger = 'hook';
-/** Which `resumeHook()` dispatch path produced this resume. */
-export type ResumeStrategy = 'parallel' | 'sequential';
+/**
+ * Which `resumeHook()` dispatch path produced this resume.
+ *
+ * Current producers always send `sequential` (durable write, then wake).
+ * Older producers may send `lazy` (the consumer materializes the event from
+ * `hookInput`) or `parallel` (the write raced the publish).
+ */
+export type ResumeStrategy = 'lazy' | 'parallel' | 'sequential';
 /**
  * How the consuming invocation initialized its replay state:
  *
- * - `hook_preload` — the hoisted `hook_received` write returned a usable
+ * - `hook_preload`: the hoisted `hook_received` write returned a usable
  *   replay preload, so neither `run_started` nor the initial `events.list` ran.
- * - `run_started` — the generic `run_started` setup ran (including the fast
+ * - `run_started`: the generic `run_started` setup ran (including the fast
  *   path's fallback, where the hoisted write succeeded but returned no usable
  *   preload).
- * - `event_load` — neither setup ran because the run arrived already loaded,
+ * - `event_load`: neither setup ran because the run arrived already loaded,
  *   so setup was a plain event load. No current path produces it (the one
  *   preloaded-run path, the background-step fall-through, consumes the
  *   tracking on its own step first); it is the honest default rather than a
@@ -62,7 +69,7 @@ export type ResumeStepExecution = 'inline' | 'dispatched';
  *
  * The runtime holds at most one of these per invocation and CONSUMES it when
  * it hands it to the execution that will attempt the next durable step, so a
- * later step in the same invocation — or a retry of the same step — never
+ * later step in the same invocation (or a retry of the same step) never
  * re-reports the same resumption. Within one inline batch the object is
  * shared by every step and the {@link ResumeTtrTracking.reported} latch picks
  * the single reporter.
@@ -71,19 +78,19 @@ export interface ResumeTtrTracking {
     trigger: ResumeTrigger;
     /** Absent only if an older producer omitted it from the queue message. */
     strategy?: ResumeStrategy;
-    /** T0 — entry into `resumeHook()`. */
+    /** T0: entry into `resumeHook()`. */
     resumeRequestedAtMs: number;
-    /** T1 — immediately before the queue publish was requested. */
+    /** T1: immediately before the queue publish was requested. */
     queuePublishRequestedAtMs: number;
     /**
-     * T2 — entry into the FINAL consumer's queue handler. A delivery that
+     * T2: entry into the FINAL consumer's queue handler. A delivery that
      * re-routes for deployment affinity never stamps this, so the re-routed hop
      * stays inside `queue_delivery` where it belongs.
      */
     consumerStartedAtMs: number;
-    /** T3 — this invocation's first replay pass. */
+    /** T3: this invocation's first replay pass. */
     replayStartedAtMs?: number;
-    /** T4 — replay first encountered a durable step after the resume. */
+    /** T4: replay first encountered a durable step after the resume. */
     nextStepEncounteredAtMs?: number;
     setupSource?: ResumeSetupSource;
     stepExecution: ResumeStepExecution;
@@ -91,7 +98,7 @@ export interface ResumeTtrTracking {
      * One-shot latch, set by the step executor once this resumption has been
      * reported. Every step of an inline batch is handed the SAME tracking
      * object, so the first one to reach user code takes the measurement and the
-     * rest see this and skip — one resumption, one sample, without pinning the
+     * rest see this and skip: one resumption, one sample, without pinning the
      * sample to a step that may lose its create-claim and never run.
      *
      * Deliberately not part of {@link HookResumeTiming}: it is invocation-local
@@ -101,8 +108,8 @@ export interface ResumeTtrTracking {
 }
 /**
  * Rebuild tracking from a queue message's timing object. Returns undefined for
- * a message that carries none (an older producer, or any non-hook delivery) —
- * the caller then simply reports no TTR.
+ * a message that carries none (an older producer, or any non-hook delivery);
+ * the caller then reports no TTR.
  */
 export declare function resumeTrackingFromMessage(timing: HookResumeTiming | undefined, stepExecution: ResumeStepExecution): ResumeTtrTracking | undefined;
 /**
@@ -114,7 +121,7 @@ export declare function resumeTrackingFromMessage(timing: HookResumeTiming | und
 export declare function resumeTimingForMessage(tracking: ResumeTtrTracking | undefined): HookResumeTiming | undefined;
 /**
  * Compute the TTR span attributes for a step that is the first durable step
- * following a hook resume. Returns undefined — emitting nothing at all — when
+ * following a hook resume. Returns undefined (emitting nothing at all) when
  * any of these hold:
  *
  * - the invocation carries no resume tracking (not a hook resume, or an older
@@ -133,11 +140,11 @@ export declare function computeResumeTtrAttributes(params: {
     tracking: ResumeTtrTracking | undefined;
     /** The attempt number of the execution about to run. */
     attempt: number;
-    /** T5 — `Date.now()` immediately before the `step_started` request. */
+    /** T5: `Date.now()` immediately before the `step_started` request. */
     stepClaimStartedAtMs: number | undefined;
-    /** T6 — `Date.now()` once the `step_started` response returned. */
+    /** T6: `Date.now()` once the `step_started` response returned. */
     stepClaimCompletedAtMs: number | undefined;
-    /** T7 — `Date.now()` immediately before `stepFn.apply()`. */
+    /** T7: `Date.now()` immediately before `stepFn.apply()`. */
     stepCodeStartedAtMs: number;
 }): Record<string, string | number> | undefined;
 //# sourceMappingURL=resume-latency.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/run-id-time.d.ts

@@ -5,8 +5,8 @@
  * `@workflow/world-vercel`'s region-tagged run IDs mark an ID as carrying
  * metadata by setting the most-significant bit of the ULID's 48-bit
  * timestamp, which would otherwise skew the decoded time past the year 6400.
- * The tag-bit handling is delegated to the scheme's own codec —
- * `decode()` returns the ULID with the tag bit cleared — so if the tagged
+ * The tag-bit handling is delegated to the scheme's own codec
+ * (`decode()` returns the ULID with the tag bit cleared), so if the tagged
  * layout ever evolves (the scheme carries a 5-bit version field for exactly
  * that), this anchor keeps tracking the codec instead of silently diverging.
  * For untagged input `decode()` is a passthrough.

package/dist/src/compiled/@workflow/core/runtime/run.d.ts

@@ -1,8 +1,25 @@
 import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from '../_workflow-serde.js';
-import { type WorkflowRunStatus } from '#compiled/@workflow/world/index.js';
+import type { WorkflowRunStatus } from '#compiled/@workflow/world/index.js';
 import { type CancelRunOptions, type StopSleepOptions, type StopSleepResult } from './runs.js';
 /** @internal */
 export declare function getReturnValuePollIntervalMs(): number;
+/** @internal */
+export declare function getReturnValueWaitTimeoutMs(): number;
+/** @internal */
+export declare function getReturnValueMaxLongPolls(): number;
+/**
+ * Whether `await run.returnValue` may use the World's long poll
+ * (`runs.waitForTerminalStatus`) instead of interval-polling `runs.get`.
+ *
+ * Default **ON** wherever the World implements the method; a World that does
+ * not is already on the interval path with nothing to switch off. Reads
+ * `process.env.WORKFLOW_RETURN_VALUE_LONG_POLL` lazily; an explicit `'0'` /
+ * `'false'` is the kill switch, restoring the fixed-interval poll exactly as
+ * it behaved before the fast path existed.
+ *
+ * @internal
+ */
+export declare function isReturnValueLongPollEnabled(): boolean;
 /**
  * A `ReadableStream` extended with workflow-specific helpers.
  */
@@ -10,7 +27,7 @@ export type WorkflowReadableStream<R = any> = ReadableStream<R> & {
     /**
      * Returns the tail index (index of the last known chunk, 0-based) of the
      * underlying workflow stream. Useful for resolving a negative `startIndex`
-     * into an absolute position — for example, when building reconnection
+     * into an absolute position, for example, when building reconnection
      * endpoints that need to inform the client where the stream starts.
      *
      * Returns `-1` when no chunks have been written yet.
@@ -32,8 +49,8 @@ export interface WorkflowReadableStreamOptions {
      */
     startIndex?: number;
     /**
-     * Any asynchronous operations that need to be performed before the execution
-     * environment is paused / terminated
+     * Any asynchronous operations to complete before pausing or terminating the
+     * execution environment
      * (i.e. using [`waitUntil()`](https://developer.mozilla.org/docs/Web/API/ExtendableEvent/waitUntil) or similar).
      */
     ops?: Promise<any>[];
@@ -90,7 +107,7 @@ export declare class Run<TResult> {
     get status(): Promise<WorkflowRunStatus>;
     /**
      * The return value of the workflow run.
-     * Polls the workflow return value until it is completed.
+     * Polls the workflow return value until the workflow run completes.
      */
     get returnValue(): Promise<TResult>;
     /**

package/dist/src/compiled/@workflow/core/runtime/runs.d.ts

@@ -6,9 +6,9 @@ export interface RecreateRunOptions {
      * Queue namespace of the target deployment (e.g. `'eve'` for topics like
      * `__eve_wkf_workflow_*`). Falls back to `WORKFLOW_QUEUE_NAMESPACE` in
      * the calling process. Cross-context callers (e.g. the observability
-     * dashboard) must pass the target deployment's namespace explicitly —
-     * a run enqueued to a topic the target deployment has no consumer for
-     * is never picked up.
+     * dashboard) must pass the target deployment's namespace explicitly,
+     * since a run enqueued to a topic the target deployment has no consumer
+     * for is never picked up.
      */
     namespace?: string;
 }
@@ -75,7 +75,7 @@ export declare function cancelRun(world: World, runId: string, options?: CancelR
  * `cancelRun()` calls with at most {@link CANCEL_RUNS_FALLBACK_CONCURRENCY}
  * in flight at a time. Fallback successes are reported as `cancelled`;
  * failures are reported as `failed` with `code: 'internal_error'` and
- * `retryable: true` — deliberately without per-world error classification.
+ * `retryable: true`, deliberately without per-world error classification.
  *
  * @throws if `runIds` is empty, contains duplicates, or exceeds
  *   {@link BULK_CANCEL_MAX_RUN_IDS}.

package/dist/src/compiled/@workflow/core/runtime/start.d.ts

@@ -1,7 +1,7 @@
 import type { World } from '#compiled/@workflow/world/index.js';
 import { Run } from './run.js';
 /**
- * Reset the `deploymentId: 'latest'` no-op warn-once guard. Test-only —
+ * Reset the `deploymentId: 'latest'` no-op warn-once guard. Test-only,
  * exported so unit tests can exercise the warn path across `start()` calls.
  *
  * @internal
@@ -23,7 +23,7 @@ export interface StartOptionsBase {
      * run ID and routes the initial workflow message to the matching
      * regional queue. When omitted, the world falls back to its own
      * default (for `world-vercel`: the `VERCEL_REGION` environment
-     * variable, then the server-side default region `iad1` — a concrete,
+     * variable, then the server-side default region `iad1`; a concrete,
      * routable region is always chosen).
      *
      * Worlds without a regional dimension ignore this field.
@@ -89,7 +89,7 @@ export interface StartOptionsWithDeploymentId extends StartOptionsBase {
      * This is only meaningful in worlds with atomic, immutable deployments
      * (currently Vercel). In other worlds (local dev, Postgres) there is no
      * notion of multiple deployments to resolve between, so `'latest'` has no
-     * effect — a warning is logged and the run targets the current deployment.
+     * effect: a warning is logged and the run targets the current deployment.
      *
      * **Note:** When `deploymentId` is provided, the argument and return types become `unknown`
      * since there is no guarantee the types will be consistent across deployments.