eve 0.48.0 → 0.49.1

package/dist/src/compiled/@workflow/world/interfaces.d.ts

@@ -3,7 +3,7 @@ import type { AttributeChange, ExperimentalSetAttributesResult } from './attribu
 import type { BatchEventRequest, CreateEventBatchParams, CreateEventParams, CreateEventRequest, Event, EventBatchResult, EventResult, GetEventParams, ListEventsByCorrelationIdParams, ListEventsParams, RunCreatedEventRequest } from './events.js';
 import type { GetHookParams, Hook, ListHooksParams } from './hooks.js';
 import type { Queue } from './queue.js';
-import type { BulkCancelWorkflowRunsRequest, BulkCancelWorkflowRunsResult, GetWorkflowRunParams, ListWorkflowRunsParams, WorkflowRun, WorkflowRunWithoutData } from './runs.js';
+import type { BulkCancelWorkflowRunsRequest, BulkCancelWorkflowRunsResult, GetWorkflowRunParams, ListWorkflowRunsParams, WaitForTerminalRunStatusParams, WorkflowRun, WorkflowRunWithoutData } from './runs.js';
 import type { GetChunksOptions, PaginatedResponse, StreamChunksResponse, StreamInfoResponse } from './shared.js';
 import type { GetStepParams, ListWorkflowRunStepsParams, Step, StepWithoutData } from './steps.js';
 export interface Streamer {
@@ -94,6 +94,57 @@ export interface Storage {
             resolveData?: 'all';
         }): Promise<WorkflowRun>;
         get(id: string, params?: GetWorkflowRunParams): Promise<WorkflowRun | WorkflowRunWithoutData>;
+        /**
+         * Long poll for a run to reach a terminal status (`completed`, `failed`,
+         * or `cancelled`), returning the same entity `get` returns.
+         *
+         * This is how a caller awaiting a run's outcome (`await run.returnValue`)
+         * avoids paying interval-poll quantization for it: instead of asking
+         * "is it done yet?" every second, it asks once and the World answers the
+         * moment the run finishes.
+         *
+         * The contract:
+         *
+         * - **Resolve as soon as the run is terminal**, with the run entity in
+         *   the shape `params.resolveData` asks for.
+         * - **Resolve no later than roughly `params.timeoutMs`** with the latest
+         *   snapshot, whatever its status. A timeout is a normal return, never an
+         *   error: a run that is still running is a legitimate answer.
+         * - **`timeoutMs` is an upper bound, not a lower one.** An
+         *   implementation MAY resolve earlier with a non-terminal snapshot. For
+         *   example, `@workflow/world-vercel` does when the backend it is talking
+         *   to has no long-poll route and it degrades to a plain read. Callers
+         *   must therefore pace their own retries rather than assume one call per
+         *   `timeoutMs` (the runtime's `Run#pollReturnValue` keeps consecutive
+         *   non-terminal observations at least one poll interval apart).
+         * - **Fail exactly like `get`.** A missing run throws
+         *   `WorkflowRunNotFoundError`; transport failures surface as they would
+         *   on any other read.
+         *
+         * OPTIONAL. Omit it entirely when the World has no way to wait (a
+         * deterministic simulator, a store with no change notification) and the
+         * runtime keeps interval-polling `get` on
+         * `WORKFLOW_RETURN_VALUE_POLL_INTERVAL_MS`. There is nothing to declare
+         * beyond the method's presence, and no behavior degrades when it is
+         * absent: the fast path is strictly additive.
+         *
+         * Implementations are free to satisfy this however their backend allows,
+         * such as a server-side long poll (`world-vercel` holds
+         * `GET /v2/runs/:runId/status` open), a change notification
+         * (`world-postgres` uses `LISTEN`/`NOTIFY`, `world-local` an in-process
+         * emitter), or a tight internal poll, as long as a lost or missing
+         * notification degrades to returning a snapshot rather than hanging past
+         * the budget.
+         */
+        waitForTerminalStatus?: {
+            (id: string, params: WaitForTerminalRunStatusParams & {
+                resolveData: 'none';
+            }): Promise<WorkflowRunWithoutData>;
+            (id: string, params?: WaitForTerminalRunStatusParams & {
+                resolveData?: 'all';
+            }): Promise<WorkflowRun>;
+            (id: string, params?: WaitForTerminalRunStatusParams): Promise<WorkflowRun | WorkflowRunWithoutData>;
+        };
         /**
          * Retrieves several runs as one snapshot. The result preserves the input
          * order and contains `null` for run IDs that do not exist.
@@ -179,7 +230,7 @@ export interface Storage {
     /**
      * The event log, and the one part of this interface with a requirement the
      * types cannot express: **the World allocates every event id, and every id
-     * is a slot** — `evnt_` followed by the event's dense, 1-based position in
+     * is a slot**: `evnt_` followed by the event's dense, 1-based position in
      * its run's log, zero-padded to 26 characters. Use `slotToEventId()` to
      * format one.
      *
@@ -197,7 +248,7 @@ export interface Storage {
      *   taken. The World advances to the next free slot, commits there, and
      *   returns the events occupying the slots it skipped over on the success
      *   response (see {@link EventResult.events}). The writer learns its
-     *   snapshot was stale without the write being rejected — which is why no
+     *   snapshot was stale without the write being rejected, which is why no
      *   World needs a precondition guard.
      *
      * Allocating at the commit is what makes a reader's log a *prefix* of the
@@ -227,7 +278,7 @@ export interface Storage {
          */
         create<T extends CreateEventRequest>(runId: string, data: T, params?: CreateEventParams): Promise<EventResult<T['eventType']>>;
         /**
-         * OPTIONAL batch write — append an ordered list of events to the run's
+         * OPTIONAL batch write: append an ordered list of events to the run's
          * log in one durable, atomic-per-attempt write, with a per-event outcome
          * for each (see {@link BatchEventItemResult}). The events land in request
          * order at consecutive slots. A concurrent writer may push the whole
@@ -235,14 +286,14 @@ export interface Storage {
          * report accompanies the result, so a position-tracking caller compares
          * the committed slots against its expectation and reloads the log to
          * observe what landed in between. Its local view stays a strict PREFIX
-         * of the log — never a hole — so replaying it stays correct and the
+         * of the log (never a hole), so replaying it stays correct and the
          * next reload self-corrects.
          *
          * Presence of the method IS the capability declaration: the core runtime
          * batches only when the World implements it (and the run's spec version
          * supports slot identity); absent, every write takes the single-event
          * `create` path unchanged. A World must implement it with real
-         * atomicity per attempt — a lost race must leave nothing behind — or not
+         * atomicity per attempt (a lost race must leave nothing behind) or not
          * implement it at all.
          *
          * Size limits are the caller's problem: Worlds enforce their own caps
@@ -255,11 +306,11 @@ export interface Storage {
          * `hook_created`, `hook_disposed`, `attr_set`, and more events targeting
          * one entity than a single write can express (the one legal combination
          * is `step_created` followed by `step_started` for the same step, which
-         * creates the step born-running — the step's input MUST ride the
+         * creates the step born-running: the step's input MUST ride the
          * `step_created`; a `step_started` carrying a payload rejects the whole
          * batch). Events outside this list keep their own ordering requirements:
          * a caller mixing a batch with single writes (hook or attribute events)
-         * owns those barriers itself — the core runtime simply never batches a
+         * owns those barriers itself: the core runtime never batches a
          * suspension that carries hook or attribute writes.
          */
         createBatch?(runId: string, events: BatchEventRequest[], params?: CreateEventBatchParams): Promise<EventBatchResult>;
@@ -289,7 +340,7 @@ export interface Storage {
  * Optional feature capabilities a World implementation declares so the core
  * runtime can enable optimizations that depend on backend behavior, instead
  * of inferring support from environment variables alone. Every capability
- * defaults to "unsupported" when absent — runtime fast paths that rely on
+ * defaults to "unsupported" when absent: runtime fast paths that rely on
  * one must fail closed (keep their conservative behavior) unless the World
  * explicitly declares it.
  */
@@ -302,7 +353,7 @@ export interface WorldCapabilities {
         active: boolean;
     };
     /**
-     * The World's queue supports `maxConcurrency`-limited consumption — in
+     * The World's queue supports `maxConcurrency`-limited consumption, in
      * particular the per-run flow topics consumed with `maxConcurrency: 1`
      * that `WORKFLOW_SEQUENTIAL_REPLAYS=1` uses to serialize a run's
      * orchestrator invocations. Worlds whose queue has no concurrency-limit
@@ -312,25 +363,29 @@ export interface WorldCapabilities {
      * serialization also requires the build-time half (a flow trigger emitted
      * with `maxConcurrency: 1`), which a runtime process cannot verify today.
      * The core runtime therefore does not yet take any fast path from this
-     * capability alone — it exists so a future build-verified signal can be
+     * capability alone: it exists so a future build-verified signal can be
      * combined with it (and so Worlds document the contract explicitly).
      */
     maxConcurrency?: boolean;
     /**
      * The World's `events.create` deduplicates concurrent `hook_received` writes
-     * that carry the same `(runId, resumeId)` — collapsing them onto a single
-     * committed event and returning the canonical one to every caller. This is
-     * the backend half of `resumeHook()`'s parallel fast path: the producer's
-     * direct write and the queue consumer's re-ensure both write the same
-     * `resumeId`, and exactly one event must survive or the run replays a
-     * duplicated `hook_received`.
+     * that carry the same `(runId, resumeId)`, collapsing them onto a single
+     * committed event and returning the canonical one to every caller. Two
+     * writers rely on it: `resumeHook()`'s durable write attaches a `resumeId` +
+     * payload digest so transport-level retries of one write converge on exactly
+     * one event, and legacy `hookInput` queue redeliveries (from older
+     * producers) converge through the same constraint.
+     *
+     * The core runtime fails closed on this: a `resumeId` is attached ONLY when
+     * the World declares `hookResumeDedup === true` (or the live backend attests
+     * it per-lookup, below). A World that accepts a `resumeId` but does not
+     * enforce the `(runId, resumeId)` constraint must leave this unset so the
+     * runtime keeps the plain single-shot write.
      *
-     * The core runtime fails closed on this: the parallel path is taken ONLY
-     * when the World declares `hookResumeDedup === true` AND the target run's
-     * deployment can re-ensure from `hookInput` (see the execution-context
-     * marker `hookResumeInputVersion`). A World that accepts a `resumeId` but
-     * does not enforce the `(runId, resumeId)` constraint must leave this unset
-     * so the runtime keeps the sequential single-writer path.
+     * Declaring this also commits the World to ROUND-TRIPPING the key:
+     * `events.list` must return `resumeId` on `hook_received` events it
+     * persisted with one, because the legacy `hookInput` consumer path detects
+     * an already-materialized resume by matching `resumeId` in the loaded log.
      *
      * Enabled statically for `world-local` (filesystem sidecar claim keyed on
      * `(runId, resumeId)`; the adapter and its backend ship together, so a static
@@ -338,8 +393,8 @@ export interface WorldCapabilities {
      * leaves this UNSET and instead attests support per-lookup via the
      * server-computed, response-only `Hook.resumeCapabilities.hookResumeDedupVersion`
      * (see `HookResumeCapabilitiesSchema`), so a server rollback or kill switch
-     * degrades new resumes to the sequential path immediately without redeploying
-     * the adapter. `world-postgres` leaves it unset for now and stays sequential.
+     * degrades new resumes to plain writes immediately without redeploying
+     * the adapter. `world-postgres` leaves it unset for now.
      *
      * The resume gate treats EITHER signal as backend support (see
      * `resume-hook.ts`): this static capability OR a current
@@ -387,7 +442,7 @@ export interface World extends Queue, Streamer, Storage {
      */
     specVersion: number;
     /**
-     * Feature capabilities this World implementation supports — see
+     * Feature capabilities this World implementation supports. See
      * {@link WorldCapabilities}. Absent (or absent members) means
      * "unsupported": runtime optimizations gated on a capability fail closed.
      */
@@ -418,7 +473,7 @@ export interface World extends Queue, Streamer, Storage {
      * "production" target or same git branch for "preview" deployments) as the
      * current deployment.
      *
-     * Not all World implementations support this — it is only implemented by
+     * Not all World implementations support this: it is only implemented by
      * world-vercel where deployment routing is meaningful.
      */
     resolveLatestDeploymentId?(): Promise<string>;
@@ -432,18 +487,18 @@ export interface World extends Queue, Streamer, Storage {
      *
      * Two overloads:
      *
-     * - `getEncryptionKeyForRun(run)` — Preferred. Pass a `WorkflowRun` when
+     * - `getEncryptionKeyForRun(run)`: Preferred. Pass a `WorkflowRun` when
      *   the run entity already exists. The World reads any context it needs
      *   (e.g., `deploymentId`) directly from the run.
      *
-     * - `getEncryptionKeyForRun(runId, context?)` — Used when the run entity
+     * - `getEncryptionKeyForRun(runId, context?)`: Used when the run entity
      *   is not locally available, such as `start()` before run creation or a
      *   forwarded writable stream carrying its owning deployment context. The
      *   `context` parameter carries opaque world-specific data (e.g.,
      *   `{ deploymentId }` for world-vercel) needed to resolve the correct key.
      *   When `context` is omitted, the World assumes the current deployment.
      *
-     * When not implemented, encryption is disabled — data is stored unencrypted.
+     * When not implemented, encryption is disabled: data is stored unencrypted.
      */
     getEncryptionKeyForRun?(run: WorkflowRun): Promise<Uint8Array | undefined>;
     getEncryptionKeyForRun?(runId: string, context?: Record<string, unknown>): Promise<Uint8Array | undefined>;
@@ -462,8 +517,8 @@ export interface World extends Queue, Streamer, Storage {
      * @param options - The full options bag passed to `start()` (typed as
      *   `Record<string, unknown>` here to avoid a circular dependency with
      *   `@workflow/core`). Worlds should read only the fields they
-     *   recognise — for example, `@workflow/world-vercel` reads
-     *   `options.region` to embed a region identifier. Unrecognised keys
+     *   recognize. For example, `@workflow/world-vercel` reads
+     *   `options.region` to embed a region identifier. Unrecognized keys
      *   must be ignored. `start()` always passes an object (an empty one
      *   when it was called with no options), but implementations should
      *   tolerate `undefined` for direct callers.
@@ -478,7 +533,7 @@ export interface World extends Queue, Streamer, Storage {
      * network call. Return `undefined` when the environment can't be determined.
      *
      * The value MUST match the attribution the backend will actually apply to
-     * this client's writes — for `world-vercel` that means keeping it in lockstep
+     * this client's writes: for `world-vercel` that means keeping it in lockstep
      * with the `x-vercel-environment` header (proxy path) and the OIDC token's
      * `environment` claim (in-deployment path). A value that merely looks
      * plausible is worse than `undefined`, because callers use it to detect
@@ -487,14 +542,14 @@ export interface World extends Queue, Streamer, Storage {
      * `start()` stamps this into the queue message's `runInput` so the consuming
      * deployment can tell that a message it was handed was created against a
      * different environment than its own. Not all Worlds have an environment
-     * dimension — local dev and Postgres have exactly one tenant, so they omit
+     * dimension: local dev and Postgres have exactly one tenant, so they omit
      * this and the check is skipped.
      */
     getEnvironment?(): string | undefined;
     /**
      * World-specific display fields for a run.
      *
-     * Tooling — e.g. the `workflow inspect` CLI — calls this to enrich a
+     * Tooling (e.g. the `workflow inspect` CLI) calls this to enrich a
      * run's listing row / detail output with fields only the world can
      * derive: a region decoded from the run ID, placement read off the
      * run's `executionContext`, a shard, a billing tier, etc. Consumers
@@ -502,11 +557,11 @@ export interface World extends Queue, Streamer, Storage {
      * hook is absent, no extra fields appear at all.
      *
      * The contract:
-     * - **Cheap and pure.** Called once per displayed run, so avoid I/O —
-     *   prefer deriving fields from the entity you are given.
-     * - **Read only what you recognise.** The argument is the run entity
+     * - **Cheap and pure.** Called once per displayed run, so avoid I/O.
+     *   Prefer deriving fields from the entity you are given.
+     * - **Read only what you recognize.** The argument is the run entity
      *   as the caller has it (a full storage run, or a leaner analytics
-     *   row) — typed loosely for the same reason as {@link createRunId}.
+     *   row), typed loosely for the same reason as {@link createRunId}.
      *   Tolerate missing fields.
      * - **Must not throw.**
      * - A `null` field value means "applicable but undeterminable" and is

package/dist/src/compiled/@workflow/world/queue.d.ts

@@ -39,7 +39,7 @@ export declare const TraceCarrierSchema: z.ZodRecord<z.ZodString, z.ZodString>;
 export type TraceCarrier = z.infer<typeof TraceCarrierSchema>;
 /**
  * Run creation data carried through the queue for resilient start.
- * Only present on the first queue delivery — re-enqueues omit this.
+ * Only present on the first queue delivery: re-enqueues omit this.
  * When the runtime processes the message, it passes this data to the
  * run_started event so the server can create the run if it doesn't exist yet.
  */
@@ -55,35 +55,34 @@ export declare const RunInputSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type RunInput = z.infer<typeof RunInputSchema>;
 /**
- * Lazy hook resume data carried through the queue alongside a workflow
- * invocation. Present only when `resumeHook()` takes the parallel fast path:
- * the producer persists the `hook_received` event and publishes this invocation
- * concurrently. On receipt, a consumer that understands `hookInput` idempotently
- * ensures the `hook_received` event exists — keyed by `resumeId` — before
- * replaying, so the two concurrent writes converge on exactly one event.
+ * Legacy lazy hook resume data carried through the queue alongside a workflow
+ * invocation. Older producers publish this invocation and write no event of
+ * their own. On receipt, a consumer that understands `hookInput` idempotently
+ * ensures the `hook_received` event exists (keyed by `resumeId`) before
+ * replaying, so repeated deliveries converge on exactly one event.
  *
  * The `payload` is the already-serialized (and possibly encrypted) resume
- * payload — the identical bytes the producer also sent on the direct
- * `events.create`, so both server receipts hash to the same digest under the
+ * payload, and on this path the queue message is its only carrier. Every write
+ * derived from this message therefore hashes to the same digest under the
  * `(runId, resumeId)` constraint.
  */
 /**
  * Resilient step dispatch data carried through the queue alongside a
  * step-execution message ({@link WorkflowInvokePayload.stepId}). Present when
  * the producer (the suspension handler dispatching a newly created step)
- * parallelized the `step_created` event write with the queue publish — the
+ * parallelized the `step_created` event write with the queue publish: the
  * same shape as resilient start (`runInput`) and the resilient hook resume
  * (`hookInput`).
  *
  * When the producer's `step_created` write fails transiently (429 / 5xx /
  * transport), the step entity may not exist when this message is consumed. A
  * consumer that understands `stepInput` idempotently re-ensures the
- * `step_created` event — keyed by the message's `stepId` (the step's
- * correlation id, unique per `(runId, correlationId)`) — before executing, so
+ * `step_created` event, keyed by the message's `stepId` (the step's
+ * correlation id, unique per `(runId, correlationId)`), before executing, so
  * the producer's write and the consumer's re-ensure converge on exactly one
  * event.
  *
- * The `input` is the already-serialized (and possibly encrypted) step input —
+ * The `input` is the already-serialized (and possibly encrypted) step input:
  * the identical bytes the producer also sent on the direct `events.create`.
  */
 export declare const StepDispatchInputSchema: z.ZodObject<{
@@ -101,8 +100,8 @@ export declare const HookResumeInputSchema: z.ZodObject<{
 export type HookResumeInput = z.infer<typeof HookResumeInputSchema>;
 /**
  * Wall-clock boundaries of a hook-triggered resume, carried on the queue
- * message so the SDK can report end-to-end time-to-resume (TTR) — entry into
- * `resumeHook()` through to the first line of the next durable step — and its
+ * message so the SDK can report end-to-end time-to-resume (TTR, entry into
+ * `resumeHook()` through to the first line of the next durable step) and its
  * non-overlapping phase breakdown, as span attributes on that step's
  * `step.execute` span. See `runtime/resume-latency.ts` in `@workflow/core`.
  *
@@ -120,13 +119,13 @@ export type HookResumeInput = z.infer<typeof HookResumeInputSchema>;
  *
  * Every field is advisory and the whole object is optional, in all three
  * directions that matter for a rolling deploy: a new producer's timing is
- * ignored by an old consumer, a new consumer simply reports no TTR for an old
+ * ignored by an old consumer, a new consumer reports no TTR for an old
  * message, and workflow-server never reads it at all.
  *
  * `strategy` and `setupSource` are deliberately typed as plain strings rather
  * than enums: an unrecognized value from a newer producer must not fail the
- * parse of the whole invocation payload (which would wedge the run) — it is
- * only ever forwarded to a span attribute.
+ * parse of the whole invocation payload (which would wedge the run), since it
+ * is only ever forwarded to a span attribute.
  */
 export declare const HookResumeTimingSchema: z.ZodObject<{
     resumeRequestedAtMs: z.ZodNumber;
@@ -149,6 +148,10 @@ export declare const WorkflowInvokePayloadSchema: z.ZodObject<{
     preconditionReinvocations: z.ZodOptional<z.ZodNumber>;
     serverErrorRetryCount: z.ZodOptional<z.ZodNumber>;
     deploymentMismatchRetryCount: z.ZodOptional<z.ZodNumber>;
+    waitContinuation: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        correlationId: z.ZodString;
+        attempt: z.ZodNumber;
+    }, z.core.$strip>>>;
     stepId: z.ZodOptional<z.ZodString>;
     stepName: z.ZodOptional<z.ZodString>;
     runInput: z.ZodOptional<z.ZodObject<{
@@ -201,8 +204,8 @@ export declare const HealthCheckPayloadSchema: z.ZodObject<{
  * an optional `runId`, so a probe payload also satisfies
  * `WorkflowInvokePayloadSchema` (whose only required field is `runId`). With
  * the invoke member first, parsing a runId-bearing probe silently dropped
- * `__healthCheck` and `correlationId`, and the runtime — which dispatches on
- * `__healthCheck` before falling through to the invoke schema — reinterpreted
+ * `__healthCheck` and `correlationId`, and the runtime (which dispatches on
+ * `__healthCheck` before falling through to the invoke schema) reinterpreted
  * the probe as "replay this run". That made the queue handler POST
  * `run_started` for a run that doesn't exist yet (404), fail, and retry
  * forever, so the probe never answered and `start()` timed out.
@@ -225,6 +228,10 @@ export declare const QueuePayloadSchema: z.ZodUnion<readonly [z.ZodObject<{
     preconditionReinvocations: z.ZodOptional<z.ZodNumber>;
     serverErrorRetryCount: z.ZodOptional<z.ZodNumber>;
     deploymentMismatchRetryCount: z.ZodOptional<z.ZodNumber>;
+    waitContinuation: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        correlationId: z.ZodString;
+        attempt: z.ZodNumber;
+    }, z.core.$strip>>>;
     stepId: z.ZodOptional<z.ZodString>;
     stepName: z.ZodOptional<z.ZodString>;
     runInput: z.ZodOptional<z.ZodObject<{
@@ -276,7 +283,7 @@ export interface QueueOptions {
      * `@vercel/queue` client uses to route the message; when omitted, the
      * region is resolved from the payload's tagged run ID, then from the
      * `VERCEL_REGION` environment variable, and finally defaults to `'iad1'`
-     * (the pre-regional-routing behaviour).
+     * (the pre-regional-routing behavior).
      */
     region?: string;
 }
@@ -308,7 +315,7 @@ export interface Queue {
      * `step_started` records the handling invocation's messageId, and only a
      * delivery of that same message may re-execute the step before the
      * ownership lease expires (crash recovery via queue redelivery). A World
-     * whose queue mints a fresh ID per delivery degrades gracefully — owner
+     * whose queue mints a fresh ID per delivery degrades gracefully: owner
      * redeliveries fall back to the delayed-backstop path instead of executing
      * immediately, adding recovery latency but never wedging or duplicating.
      */

package/dist/src/compiled/@workflow/world/runs.d.ts

@@ -151,6 +151,26 @@ export interface CreateWorkflowRunRequest {
 export interface GetWorkflowRunParams {
     resolveData?: ResolveData;
 }
+/**
+ * Params for the optional `runs.waitForTerminalStatus` long poll.
+ */
+export interface WaitForTerminalRunStatusParams extends GetWorkflowRunParams {
+    /**
+     * How long the caller is willing to wait, in milliseconds. Treat it as an
+     * upper bound on the wait, not a promise about the duration: the call
+     * resolves as soon as the run is terminal, and a World may also resolve
+     * early with a non-terminal snapshot (see
+     * {@link Storage.runs.waitForTerminalStatus}).
+     *
+     * Implementations clamp this to whatever their backend can hold open.
+     */
+    timeoutMs?: number;
+    /**
+     * Abandon the wait when this signal aborts. Implementations that cannot
+     * observe it may ignore it; callers must not rely on it to bound the call.
+     */
+    signal?: AbortSignal;
+}
 export interface ListWorkflowRunsParams {
     workflowName?: string;
     status?: WorkflowRunStatus;

package/dist/src/compiled/@workflow/world/slot-identity.d.ts

@@ -14,7 +14,7 @@
  *
  * The one thing that does *not* survive: a slot id's leading characters are
  * zeros, so decoding it as a ULID timestamp yields the Unix epoch. Nothing may
- * derive a time from an event id without first ruling out a slot id — see
+ * derive a time from an event id without first ruling out a slot id. See
  * {@link isSlotBody} and the guard in `ulidToDate`.
  */
 /** Characters in an event id body, ULID or slot alike. */
@@ -41,7 +41,7 @@ export declare function isSlotEventId(eventId: string): boolean;
 /**
  * Formats a slot as a prefixed event id.
  *
- * @throws if the slot is outside the representable range — a caller that
+ * @throws if the slot is outside the representable range: a caller that
  * overflows must fail loudly rather than mint an id that sorts wrong.
  */
 export declare function slotToEventId(slot: number): string;
@@ -57,7 +57,7 @@ export declare function eventIdToSlot(eventId: string): number | null;
  * Separate from {@link eventIdToSlot} because the two failures are different
  * problems. A caller that can act on either scheme asks the question and takes
  * `null` as an answer; a caller whose whole computation is positional (a
- * precondition snapshot, a density audit) has no correct behaviour to fall back
+ * precondition snapshot, a density audit) has no correct behavior to fall back
  * on, and silently skipping the id would make it report a position it never
  * verified. Throwing names the id instead.
  *

package/dist/src/compiled/@workflow/world/spec-version.d.ts

@@ -1,5 +1,5 @@
 /**
- * Spec version utilities for backwards compatibility.
+ * Spec version utilities for backward compatibility.
  *
  * Uses a branded type to ensure packages import the version constants
  * from @workflow/world rather than using arbitrary numbers.
@@ -14,7 +14,7 @@ export type SpecVersion = number & {
 };
 /**
  * Legacy spec version (pre-event-sourcing). Also used for runs without specVersion.
- * This is the only true legacy version — specVersion 2+ all use the event-sourced model.
+ * This is the only true legacy version: specVersion 2+ all use the event-sourced model.
  */
 export declare const SPEC_VERSION_LEGACY: SpecVersion;
 export declare const SPEC_VERSION_SUPPORTS_EVENT_SOURCING: SpecVersion;
@@ -44,17 +44,41 @@ export declare const SPEC_VERSION_SUPPORTS_COMPRESSION: SpecVersion;
  * all. See `SPEC_VERSION_CURRENT`.
  */
 export declare const SPEC_VERSION_SUPPORTS_SLOT_IDENTITY: SpecVersion;
+/**
+ * Runs at this spec version or later live in a "sealed log": their slot
+ * positions are pre-assigned by a per-run sequencer on the World's backend,
+ * so concurrent writers never race each other for a position. A position
+ * whose writer died is filled ("sealed") by the backend with a `noop` event.
+ * What the version gates is the READER contract that makes that safe: a
+ * reader at this version knows a `noop` occupies its slot and carries no
+ * workflow meaning, and skips it during replay without advancing the
+ * deterministic clock (see `EventsConsumer`). A reader below this version
+ * would fail to parse the unknown event type, which is exactly what
+ * `requiresNewerWorld` exists to catch.
+ *
+ * Note this is the READER contract only, so a World is spec-7 compliant by
+ * construction if it allocates each position at the commit that occupies it:
+ * no write can then leave a position empty, so it has no holes to seal and
+ * will never emit a `noop`. Pre-assigning positions ahead of the commit is
+ * what creates the obligation (see `building-a-world.mdx`), and only a World
+ * that does so needs the sealing half.
+ */
+export declare const SPEC_VERSION_SUPPORTS_SEALED_LOG: SpecVersion;
 /**
  * Current spec version: event-sourced architecture with native attributes,
- * compressed payloads and slot-numbered event ids.
+ * compressed payloads, slot-numbered event ids, and sealed-log sequencing.
  *
  * This is both the version a World stamps on the runs it creates and the
  * *lowest* one this runtime accepts from a World (see
- * `assertWorldSupportsRuntimeProtocol`). The two coincide because slot
- * numbering is a requirement of the World contract rather than a capability to
- * opt into: a World declaring anything below this allocates event ids the
- * runtime cannot read positions out of, so admitting it would only move the
- * failure from startup to the middle of a run.
+ * `assertWorldSupportsRuntimeProtocol`). Slot numbering is a requirement of
+ * the World contract rather than a capability to opt into: a World declaring
+ * anything below this allocates event ids the runtime cannot read positions
+ * out of, so admitting it would only move the failure from startup to the
+ * middle of a run.
+ *
+ * This is the FLOOR, not necessarily what gets stamped. Sealed-log runs sit
+ * one version above it and are opt-in, so what a World actually stamps comes
+ * from {@link mintedSpecVersion}; this is what that falls back to.
  *
  * A World therefore declares this constant rather than a literal, so a bump
  * moves the declaration and the floor together. Pinning a literal would leave
@@ -66,16 +90,59 @@ export declare const SPEC_VERSION_SUPPORTS_SLOT_IDENTITY: SpecVersion;
  * run's identity scheme from what is stored rather than from this constant.
  */
 export declare const SPEC_VERSION_CURRENT: SpecVersion;
+/**
+ * Environment variable that opts new runs OUT of the sealed log.
+ *
+ * Read per `createWorld()` call rather than at module load, so a test or a
+ * single process can create worlds in both modes.
+ */
+export declare const SEALED_LOG_ENV_VAR = "WORKFLOW_SEALED_LOG";
+/**
+ * The spec version a World should stamp on the runs it creates: the sealed log
+ * unless {@link SEALED_LOG_ENV_VAR} switches it off, in which case the
+ * slot-identity version it supersedes.
+ *
+ * Same shape, and the same reasoning, as the flag slot identity itself shipped
+ * behind before going unconditional: default on, with one env var to put a
+ * deployment back on the previous scheme without a release.
+ *
+ * What default-on rests on is the density requirement in
+ * `Storage['events']`: a reader's log must be a PREFIX of the run's log, so
+ * that the number of events it holds tells it whether it has the whole thing.
+ * A sealed log satisfies that by repair rather than by construction — a
+ * position is handed out before its write commits, so a read can land while
+ * one is still empty — and it is only equivalent if a read that cannot see
+ * past such a position waits for it to be filled or sealed instead of
+ * reporting a log that ends there. It has to be the READ that waits, because
+ * a shorter prefix is a legal log state and nothing downstream can tell the
+ * two apart. The first rollout of this default shipped without that: the
+ * backend's in-request poll budget was shorter than the age a position must
+ * reach before it can be sealed, so the read always gave up and truncated,
+ * and a replay took a step whose completion sat above the gap to be still
+ * running — then sat on it for a full inline-ownership lease.
+ *
+ * The fallback is a real fallback, not a formality. Turning this off has to
+ * leave a World the runtime still admits, which is why
+ * `assertWorldSupportsRuntimeProtocol` floors at the slot-identity version
+ * rather than at {@link SPEC_VERSION_CURRENT} because a kill switch that made
+ * the runtime reject its own World would be no kill switch at all.
+ *
+ * Every World reads runs up to {@link SPEC_VERSION_MAX_SUPPORTED} whatever
+ * this returns, so switching it off here does not make runs another process
+ * created unreadable.
+ */
+export declare function mintedSpecVersion(env?: Record<string, string | undefined>): SpecVersion;
 /**
  * The highest spec version this SDK can read.
  *
- * Kept distinct from `SPEC_VERSION_CURRENT` even though the two are equal
- * today. They answer different questions, "what do we write?" versus "what can
- * we still read?", and they come apart in the release order a spec bump
- * follows: a reader that can already handle the next version raises this
- * ceiling first, and `SPEC_VERSION_CURRENT` follows only once the version is
- * safe to stamp. Collapsing them into one constant would make that staging
- * impossible to express.
+ * Kept distinct from `SPEC_VERSION_CURRENT`, and right now they genuinely
+ * differ. They answer different questions, "what do we write?" versus "what
+ * can we still read?", and they come apart in exactly the release order a spec
+ * bump follows: a reader that can already handle the next version raises this
+ * ceiling first, and stamping follows only once the version is safe to mint
+ * everywhere. Sealed-log support is at that first stage. Every build reads
+ * spec 7 and skips `noop`, while {@link mintedSpecVersion} still has to be
+ * turned on before anything creates a spec-7 run.
  */
 export declare const SPEC_VERSION_MAX_SUPPORTED: SpecVersion;
 /**

package/dist/src/compiled/@workflow/world/ulid.d.ts

@@ -1,8 +1,8 @@
 import { z } from '#compiled/zod/index.js';
 /**
  * A workflow run ID: the `wrun_` prefix followed by a 26-char ULID (minted
- * client-side in core's `start()`). Validates the exact shape — prefix plus a
- * well-formed ULID — rather than a loose length bound, so callers can't smuggle
+ * client-side in core's `start()`). Validates the exact shape (prefix plus a
+ * well-formed ULID) rather than a loose length bound, so callers can't smuggle
  * arbitrary strings through APIs that persist a run ID verbatim.
  */
 export declare const workflowRunIdSchema: z.ZodTemplateLiteral<`wrun_${string}`>;