eve 0.38.1 → 0.38.2

package/dist/src/compiled/@workflow/core/telemetry/semantic-conventions.d.ts

@@ -417,6 +417,87 @@ export declare const HookResilientResumeMaterialized: (value: boolean) => {
 export declare const HookResumeSetupSource: (value: string) => {
     [k: string]: string;
 };
+/**
+ * Producer-side signal (on the suspension span) counting steps whose direct
+ * `step_created` write failed transiently while their `stepInput`-carrying
+ * queue publish succeeded, so step creation is recovered via the consumer's
+ * re-ensure. Mirrors {@link HookResilientResume}.
+ */
+export declare const StepResilientDispatchRecovered: (value: number) => {
+    [k: string]: number;
+};
+/**
+ * Consumer-side signal (on the workflow execution span) that this delivery
+ * materialized the `step_created` event from the queue message's `stepInput`
+ * because the producer's direct write had not landed — the completion of the
+ * recovery path {@link StepResilientDispatchRecovered} began.
+ */
+export declare const StepResilientDispatchMaterialized: (value: boolean) => {
+    [k: string]: boolean;
+};
+/** Total TTR: entry into `resumeHook()` → immediately before `stepFn.apply()`. */
+export declare const ResumeTotalMs: (value: number) => {
+    [k: string]: number;
+};
+/** Phase: `resumeHook()` entry → the queue publish being requested. */
+export declare const ResumeProducerPrepMs: (value: number) => {
+    [k: string]: number;
+};
+/** Phase: queue publish requested → the final consumer's handler being entered. */
+export declare const ResumeQueueDeliveryMs: (value: number) => {
+    [k: string]: number;
+};
+/** Phase: consumer entry → replay beginning. */
+export declare const ResumeSetupMs: (value: number) => {
+    [k: string]: number;
+};
+/** Phase: replay beginning → the next durable step being encountered. */
+export declare const ResumeReplayMs: (value: number) => {
+    [k: string]: number;
+};
+/** Phase: step encountered → the `step_started` request beginning. */
+export declare const ResumeStepDispatchMs: (value: number) => {
+    [k: string]: number;
+};
+/**
+ * Phase: `step_started` request beginning → its response returning. Omitted
+ * under optimistic inline start, where the claim is not awaited before the
+ * body runs and therefore has no completion instant at that point; the time
+ * is then reported entirely as {@link ResumeStepPrepareMs}.
+ */
+export declare const ResumeStepClaimMs: (value: number) => {
+    [k: string]: number;
+};
+/**
+ * Phase: claim returning → immediately before `stepFn.apply()`. Deliberately
+ * includes encryption-key resolution, argument hydration, and step-context
+ * setup; `workflow.queue.deserialize_time_ms` still isolates hydration.
+ */
+export declare const ResumeStepPrepareMs: (value: number) => {
+    [k: string]: number;
+};
+/** What triggered the measured resumption. */
+export declare const ResumeTrigger: (value: "hook") => {
+    [k: string]: "hook";
+};
+/** Which `resumeHook()` dispatch path produced this resume. */
+export declare const ResumeStrategy: (value: "parallel" | "sequential") => {
+    [k: string]: "parallel" | "sequential";
+};
+/**
+ * How the consuming invocation initialized replay state. Distinct from the
+ * pre-existing {@link HookResumeSetupSource} (`workflow.resume_setup_source`,
+ * on the workflow execution span), which reports the finer-grained
+ * hoisted-write outcome; this one is the TTR dimension and shares the metric's
+ * three-value vocabulary.
+ */
+export declare const ResumeSetupSource: (value: "hook_preload" | "run_started" | "event_load") => {
+    [k: string]: "hook_preload" | "run_started" | "event_load";
+};
+/** Whether the measured step ran in the resuming invocation or a queued one. */
+export declare const ResumeStepExecution: (value: "inline" | "dispatched") => {
+    [k: string]: "inline" | "dispatched";
+};
 /** Number of webhook handlers triggered */
 export declare const WebhookHandlersTriggered: (value: number) => {
     [k: string]: number;

package/dist/src/compiled/@workflow/core/test-support/orchestrator-context.d.ts

@@ -0,0 +1,25 @@
+import type { Event } from '#compiled/@workflow/world/index.js';
+import type { WorkflowOrchestratorContext } from '../private.js';
+/**
+ * Builds an orchestrator context that replays a hand-written event log through
+ * the real workflow primitives (`createUseStep`, `createSleep`,
+ * `createCreateHook`), without a World or a VM entrypoint.
+ */
+export declare function setupWorkflowContext(events: Event[], options?: {
+    onDuplicateEvent?: (event: Event) => void;
+}): WorkflowOrchestratorContext;
+/**
+ * Deterministic correlation IDs from the ULID generator with seed 'test', in
+ * the order {@link setupWorkflowContext}'s generator mints them.
+ */
+export declare const CORR_IDS: string[];
+/**
+ * Runs `workflowFn` against `ctx`, racing it against the context's error
+ * channel so a `WorkflowSuspension` or a detected divergence surfaces as
+ * `error` rather than hanging.
+ */
+export declare function runWithDiscontinuation(ctx: WorkflowOrchestratorContext, workflowFn: () => Promise<any>): Promise<{
+    result?: any;
+    error?: any;
+}>;
+//# sourceMappingURL=orchestrator-context.d.ts.map

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

@@ -1,2 +1,2 @@
-export declare const version = "5.0.0-beta.41";
+export declare const version = "5.0.0-beta.42";
 //# sourceMappingURL=version.d.ts.map

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

@@ -1 +1 @@
-import{Fn as e,In as t,Zn as n,ir as r,nr as i,rr as a}from"../../_chunks/workflow/wait-until-CT1ve8qB.js";import{i as o,u as s}from"../../_chunks/workflow/dist-xQXN70ED.js";import"../../_chunks/workflow/dist-DpYyXbJv.js";import{i as c}from"../../_chunks/workflow/workflow-routes-CwqB063q.js";import{c as l,i as u,o as d,r as f,t as p}from"../../_chunks/workflow/attribute-changes-DZtQkszH.js";import{t as m}from"../../_chunks/workflow/sleep-C1P0OWBm.js";import{t as h}from"../../_chunks/workflow/run-Cjo0A3NO.js";t(e,h);function g(e){let t=globalThis[i];return t||u(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,g),t(e)}function _(e){let{respondWith:t,token:n,...r}=e??{};if(n!==void 0)throw Error("`createWebhook()` does not accept a `token` option. Webhook tokens are always randomly generated. Use `createHook()` with `resumeHook()` for deterministic token patterns.");let i;t!==void 0&&(i={respondWith:t});let a=g({...r,metadata:i,isWebhook:!0}),{url:o}=l();return a.url=c(o,{type:`webhook`,token:a.token}),a}function v(){function e(t,n){d(`defineHook().resume()`,`https://workflow-sdk.dev/docs/api-reference/workflow-api/resume-hook`,e)}return{create(e){return g(e)},resume:e}}async function y(e,t={}){let n=p(e,t);if(n.length===0)return;let i=t.allowReservedAttributes===!0,a=globalThis[r];if(!a)throw new o("setAttributes() called outside a workflow runtime context. It must be called from within a workflow body (`use workflow`).");await a(n,i?{allowReservedAttributes:!0}:{})}function b(e={}){let{namespace:t}=e,r=globalThis[a](t);return Object.create(globalThis.WritableStream.prototype,{[n]:{value:r,writable:!1}})}function x(){f(`getStepMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-step-metadata`,x)}function S(){d(`resumeHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow-api/resume-hook`,S)}export{o as FatalError,s as RetryableError,g as createHook,_ as createWebhook,v as defineHook,x as getStepMetadata,l as getWorkflowMetadata,b as getWritable,S as resumeHook,y as setAttributes,m as sleep};
+import{Xn as e,Zn as t,_r as n,fr as r,vr as i,yr as a}from"../../_chunks/workflow/wait-until-BPSgt1Wg.js";import{i as o,u as s}from"../../_chunks/workflow/dist-CqvWKNQv.js";import"../../_chunks/workflow/dist-DpYyXbJv.js";import{i as c}from"../../_chunks/workflow/workflow-routes-CwqB063q.js";import{c as l,i as u,o as d,r as f,t as p}from"../../_chunks/workflow/attribute-changes-B8K0pwpH.js";import{t as m}from"../../_chunks/workflow/sleep-7TgF3i-e.js";import{t as h}from"../../_chunks/workflow/run-lq7-eG0l.js";t(e,h);function g(e){let t=globalThis[n];return t||u(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,g),t(e)}function _(e){let{respondWith:t,token:n,...r}=e??{};if(n!==void 0)throw Error("`createWebhook()` does not accept a `token` option. Webhook tokens are always randomly generated. Use `createHook()` with `resumeHook()` for deterministic token patterns.");let i;t!==void 0&&(i={respondWith:t});let a=g({...r,metadata:i,isWebhook:!0}),{url:o}=l();return a.url=c(o,{type:`webhook`,token:a.token}),a}function v(){function e(t,n){d(`defineHook().resume()`,`https://workflow-sdk.dev/docs/api-reference/workflow-api/resume-hook`,e)}return{create(e){return g(e)},resume:e}}async function y(e,t={}){let n=p(e,t);if(n.length===0)return;let r=t.allowReservedAttributes===!0,i=globalThis[a];if(!i)throw new o("setAttributes() called outside a workflow runtime context. It must be called from within a workflow body (`use workflow`).");await i(n,r?{allowReservedAttributes:!0}:{})}function b(e={}){let{namespace:t}=e,n=globalThis[i](t);return Object.create(globalThis.WritableStream.prototype,{[r]:{value:n,writable:!1}})}function x(){f(`getStepMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-step-metadata`,x)}function S(){d(`resumeHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow-api/resume-hook`,S)}export{o as FatalError,s as RetryableError,g as createHook,_ as createWebhook,v as defineHook,x as getStepMetadata,l as getWorkflowMetadata,b as getWritable,S as resumeHook,y as setAttributes,m as sleep};

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

@@ -437,6 +437,20 @@ export declare class RunExpiredError extends WorkflowWorldError {
     constructor(message: string);
     static is(value: unknown): value is RunExpiredError;
 }
+/**
+ * Thrown when a stream is no longer readable because its owning run passed its
+ * storage-retention boundary. This is terminal: retrying cannot restore data.
+ *
+ * Unlike {@link RunExpiredError}, this identifies the failed stream read and
+ * exposes the server's authoritative expiry timestamp for user-facing errors.
+ */
+export declare class StreamExpiredError extends WorkflowWorldError {
+    readonly runId?: string | undefined;
+    readonly streamId?: string | undefined;
+    readonly expiredAt?: Date | undefined;
+    constructor(message: string, runId?: string | undefined, streamId?: string | undefined, expiredAt?: Date | undefined);
+    static is(value: unknown): value is StreamExpiredError;
+}
 /**
  * Thrown when an operation cannot proceed because a required timestamp
  * (e.g. retryAfter) has not been reached yet.
@@ -482,8 +496,10 @@ export declare class ThrottleError extends WorkflowWorldError {
  *   does not read this field.
  * @property details - Optional rejection detail supplied by the World. A World
  *   MAY attach the events the client's snapshot was missing so the client can
- *   correct its log without a follow-up fetch; see the `stateCursor` contract
- *   on `CreateEventParams`. Typed `unknown` because this package cannot depend
+ *   correct its log without a follow-up fetch. The attached set must account
+ *   for the whole discrepancy the rejection reported or be omitted entirely; a
+ *   client that receives nothing does the authoritative full reload, which is
+ *   always correct. Typed `unknown` because this package cannot depend
  *   on the event type — consumers narrow it themselves and must treat a
  *   missing or malformed value as "no detail" (a full reload is always
  *   correct).

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

@@ -1 +1 @@
-import{C as e,D as t,E as n,O as r,S as i,T as a,_ as o,a as s,b as c,c as l,d as u,f as d,g as f,h as p,i as m,k as h,l as g,m as _,n as v,o as y,p as b,r as x,s as S,t as C,u as w,v as T,w as E,x as D,y as O}from"../../_chunks/workflow/dist-xQXN70ED.js";export{C as CorruptedEventLogError,v as ERROR_SLUGS,x as EntityConflictError,m as FatalError,s as HookConflictError,y as HookNotFoundError,S as MaxEventsExceededError,l as PreconditionFailedError,h as RUN_ERROR_CODES,g as ReplayDivergenceError,w as RetryableError,u as RunExpiredError,d as RunNotSupportedError,b as RuntimeDecryptionError,_ as SerializationError,p as StepNotRegisteredError,f as ThrottleError,o as TooEarlyError,T as VERCEL_403_ERROR_MESSAGE,O as WorkflowBuildError,c as WorkflowDeploymentMismatchError,D as WorkflowError,i as WorkflowNotRegisteredError,e as WorkflowRunCancelledError,E as WorkflowRunFailedError,a as WorkflowRunNotCompletedError,n as WorkflowRunNotFoundError,t as WorkflowRuntimeError,r as WorkflowWorldError};
+import{A as e,C as t,D as n,E as r,O as i,S as a,T as o,_ as s,a as c,b as l,c as u,d,f,g as p,h as m,i as h,k as g,l as _,m as v,n as y,o as b,p as x,r as S,s as C,t as w,u as T,v as E,w as D,x as O,y as k}from"../../_chunks/workflow/dist-CqvWKNQv.js";export{w as CorruptedEventLogError,y as ERROR_SLUGS,S as EntityConflictError,h as FatalError,c as HookConflictError,b as HookNotFoundError,C as MaxEventsExceededError,u as PreconditionFailedError,e as RUN_ERROR_CODES,_ as ReplayDivergenceError,T as RetryableError,d as RunExpiredError,f as RunNotSupportedError,x as RuntimeDecryptionError,v as SerializationError,m as StepNotRegisteredError,p as StreamExpiredError,s as ThrottleError,E as TooEarlyError,k as VERCEL_403_ERROR_MESSAGE,l as WorkflowBuildError,O as WorkflowDeploymentMismatchError,a as WorkflowError,t as WorkflowNotRegisteredError,D as WorkflowRunCancelledError,o as WorkflowRunFailedError,r as WorkflowRunNotCompletedError,n as WorkflowRunNotFoundError,i as WorkflowRuntimeError,g as WorkflowWorldError};

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

@@ -178,6 +178,8 @@ export interface AnalyticsListEventsByCorrelationIdParams {
     runId: string;
     pagination?: PaginationOptions;
 }
+/** Maximum number of event IDs accepted by one analytics batch lookup. */
+export declare const ANALYTICS_EVENTS_GET_MANY_LIMIT = 100;
 export interface AnalyticsListHooksParams {
     runId: string;
     pagination?: PaginationOptions;
@@ -204,6 +206,13 @@ export interface Analytics {
     };
     events: {
         get(runId: string, eventId: string): Promise<AnalyticsEvent>;
+        /**
+         * Retrieves the analytics rows present for a bounded set of event IDs in
+         * one run. Missing rows are omitted because analytics ingestion may lag
+         * canonical storage. Duplicate IDs are looked up once; result ordering is
+         * not guaranteed.
+         */
+        getMany(runId: string, eventIds: readonly string[]): Promise<AnalyticsEvent[]>;
         list(params: AnalyticsListEventsParams): Promise<PaginatedResponse<AnalyticsEvent>>;
         listByCorrelationId(params: AnalyticsListEventsByCorrelationIdParams): Promise<PaginatedResponse<AnalyticsEvent>>;
     };

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

@@ -59,6 +59,49 @@ declare const TerminalStepEventTypeSchema: z.ZodEnum<{
 export type TerminalStepEventType = z.infer<typeof TerminalStepEventTypeSchema>;
 export declare const TERMINAL_STEP_EVENT_TYPES: ("step_completed" | "step_failed")[];
 export declare function isTerminalStepEventType(eventType: string): eventType is TerminalStepEventType;
+/**
+ * Groups event types into the classes a replay tracks per entity: the entity
+ * named by the event's `correlationId`, or the run itself for run events,
+ * which carry none.
+ *
+ * Types that share a class are the mutually exclusive outcomes of one
+ * decision, so the log records the class once and the first event of it is the
+ * one that counts: a step either completes or fails.
+ *
+ * Classes are independent of each other. A step whose result is in the log has
+ * still recorded exactly one `step_created`, and can still record another
+ * `step_started` if an attempt is running somewhere. What a class bounds is
+ * which events can be *ignored*: a replay may pass over an event whose class
+ * it already recorded for that entity and which no consumer wants (see
+ * `EventsConsumer`), and only then.
+ *
+ * Note the omissions, all of them types a mapping would be dead weight for.
+ * `hook_received` and `hook_conflict` are deliveries whose consumer subscribes
+ * lazily, `attr_set` is written on every attribute write, and `run_created`
+ * precedes every replay. The terminal run types are absent for a different
+ * reason: recording a class requires a consumer to take an event of it, and no
+ * consumer takes `run_completed` / `run_failed` / `run_cancelled` — the runtime
+ * exits before replaying the body once the log holds one, so they never reach a
+ * consumer at all. An entry for them could never match.
+ */
+declare const ENTITY_EVENT_CLASS_BY_TYPE: {
+    readonly step_created: "step_created";
+    readonly step_started: "step_started";
+    readonly step_retrying: "step_retrying";
+    readonly step_completed: "step_terminal";
+    readonly step_failed: "step_terminal";
+    readonly wait_created: "wait_created";
+    readonly wait_completed: "wait_completed";
+    readonly hook_created: "hook_created";
+    readonly hook_disposed: "hook_disposed";
+    readonly run_started: "run_started";
+};
+export type EntityEventClass = (typeof ENTITY_EVENT_CLASS_BY_TYPE)[keyof typeof ENTITY_EVENT_CLASS_BY_TYPE];
+/**
+ * The per-entity class `eventType` belongs to, or `undefined` when it belongs
+ * to none. See {@link ENTITY_EVENT_CLASS_BY_TYPE}.
+ */
+export declare function entityEventClass(eventType: string): EntityEventClass | undefined;
 declare const HookLifecycleEventTypeSchema: z.ZodEnum<{
     hook_created: "hook_created";
     hook_received: "hook_received";
@@ -607,6 +650,26 @@ export interface CreateEventParams {
      * alongside {@link resumeId}.
      */
     resumePayloadDigest?: string;
+    /**
+     * Marks a `step_created` create as the queue consumer's re-ensure of a
+     * resilient step dispatch (a step message carrying `stepInput` — see
+     * `WorkflowInvokePayload.stepInput`): the producer's direct write was
+     * parallelized with the queue publish and may have failed. Only meaningful
+     * for `step_created`.
+     *
+     * Advisory. Parallelizing a create with its publish is opt-in and off by
+     * default (`WORKFLOW_RESILIENT_STEP_DISPATCH`), precisely because a create
+     * can come back refused while the message carrying its payload is already
+     * out. A deployment that opts in accepts that window, and a backend MAY use
+     * this flag to narrow it: refuse the re-ensure (world-vercel surfaces the
+     * backend's 410 as `RunExpiredError`, which the consumer treats as "nothing
+     * left to execute" and acks the message) when it has recorded a refusal for
+     * this correlation id and no step entity exists. Best-effort by nature — a
+     * marker written at refusal time cannot be ordered before the redelivery it
+     * is meant to stop — so it hardens, and does not close, the window. Worlds
+     * may ignore this flag entirely.
+     */
+    viaStepDispatch?: boolean;
     /** Request ID (x-vercel-id when on Vercel) for correlating request logs with workflow events. */
     requestId?: string;
     /**
@@ -616,86 +679,16 @@ export interface CreateEventParams {
      * `AnalyticsEventSchema` / `AnalyticsStepSchema`.
      */
     computeInstanceId?: string;
-    /**
-     * Epoch ms (the ULID time of the latest event the runtime has loaded during
-     * replay). Sent by replay-context creates so the backend can reject the event
-     * when a newer out-of-band event was recorded after this snapshot, enabling
-     * an optimistic-concurrency guard. Omitted by callers without a loaded event
-     * log.
-     *
-     * Backend contract (for World implementers who want to support the guard):
-     * maintain a per-run marker holding the ULID time of the most recent
-     * *externally-originated* event — a `hook_received` or `step_completed`
-     * created **without** a `stateUpdatedAt` (replay-origin events carry one and
-     * must not advance the marker). On a create that carries `stateUpdatedAt`,
-     * reject with 412 when `stateUpdatedAt < marker` (strictly older); an equal
-     * timestamp must pass (anti-livelock, so an up-to-date client is never
-     * rejected). A backend that ignores this field simply disables the guard —
-     * the client falls open and behaves as before.
-     *
-     * A watermark alone cannot see an event *missing at or below* it, which is
-     * the failure that actually corrupts a replay — see {@link stateEventCount}
-     * for the second half of the guard.
-     */
-    stateUpdatedAt?: number;
-    /**
-     * How many loaded events have a ULID time at or below {@link stateUpdatedAt}.
-     * Since `stateUpdatedAt` is the *maximum* ULID time in the loaded log, this
-     * equals the loaded array's length. Sent **only** together with
-     * `stateUpdatedAt`; a World must ignore a count that arrives without one.
-     *
-     * This closes the hole a watermark cannot: the watermark proves only "no
-     * newer event exists", while a replay corrupts its log by missing an event
-     * at or *below* its own frontier — a concurrent writer commits in the same
-     * ULID millisecond as the client's last loaded event, so the two watermarks
-     * compare equal and the write is accepted against a log that is one event
-     * short. Because correlation IDs are positional ordinals of a single seeded
-     * sequence, that one-event difference renames every entity after it.
-     *
-     * Backend contract (for World implementers who want to support this half):
-     *
-     * - Count **every** created event for the run, including replay-origin ones.
-     *   Unlike the watermark, this is not restricted to out-of-band writes: the
-     *   race being fenced is one replay against another.
-     * - Reject with 412 when the count of recorded events at ULID time
-     *   `<= stateUpdatedAt` is strictly **greater** than `stateEventCount`.
-     * - Compare **at or below** `stateUpdatedAt`, never strictly below (the
-     *   missing event routinely shares the client's frontier millisecond) and
-     *   never against a total (all the creates of one suspension share one
-     *   snapshot, so a total would reject every sibling after the first).
-     * - **One-sided safety is mandatory.** Anything that makes the backend's
-     *   count incomplete, uncomputable, or expired must *allow* the write. A
-     *   rejection has to imply a real hole, because the client responds to it by
-     *   discarding and re-deriving its whole replay.
-     *
-     * See also the millisecond-granularity caveat on `stateUpdatedAt`: the count
-     * is what makes an equal-timestamp snapshot safe to accept.
-     */
-    stateEventCount?: number;
-    /**
-     * The client's current event-log cursor (advisory). Sent alongside the other
-     * two snapshot fields so a World that rejects the write MAY return the
-     * events the client is missing on the 412 itself, saving the client a
-     * follow-up `events.list`.
-     *
-     * Distinct from {@link sinceCursor}: a World must **not** compute a delta for
-     * this on the accepted path — it exists purely to make a rejection cheaper.
-     * Returning events on a 412 is OPTIONAL, and the returned set must be
-     * provably complete (it must account for the entire discrepancy the
-     * rejection reported) or omitted entirely: a cursor filters by lexicographic
-     * event id while a hole is defined by ULID time, so a naive
-     * "everything after the cursor" delta can silently exclude the very event
-     * the client is missing. A client that receives nothing does the
-     * authoritative full reload, which is always correct.
-     */
-    stateCursor?: string;
     /**
      * How many events the writer held in its loaded log when it decided to write
-     * this one — equivalently, the slot it expects to land on minus one.
+     * this one — equivalently, the slot it expects to land on minus one. Sent by
+     * every replay-context create; omitted by callers with no loaded log to be
+     * stale against.
      *
-     * Only meaningful against a World that declares
-     * `WorldCapabilities.slotEventIds`, where slots are dense and 1-based so a
-     * count and a position are the same number. Such a World attempts
+     * A World's slots are dense and 1-based (see `Storage.events`), so a count
+     * and a position are the same number. An id that is not a position does not
+     * produce a count here — it throws, since the runtime cannot state a
+     * snapshot for a log it cannot place. Such a World attempts
      * `eventCount + 1`, and on contention **bumps** to the next free slot and
      * commits there anyway — a stale count never rejects a write. What it does
      * instead is report: when the committed slot is higher than the one asked
@@ -703,13 +696,10 @@ export interface CreateEventParams {
      * response in {@link EventResult.events} / `cursor` / `hasMore`, so the
      * writer learns exactly what it had not seen.
      *
-     * This supersedes the {@link stateUpdatedAt} / {@link stateEventCount} /
-     * {@link stateCursor} triple for slot Worlds. That triple approximates a
-     * position with a ULID-time watermark plus a count of events at or below it,
-     * which is why a *complete but stale* prefix passes it: every event the
-     * writer holds is at or below its own watermark, so the count matches and no
-     * fence fires. A dense position has no such blind spot. Worlds without slots
-     * ignore this field and keep using the triple.
+     * Understating is safe and overstating is not. A count below the writer's
+     * true position only widens the reported span, and the client discards what
+     * its log already holds. A count above it makes the World report less than
+     * the writer is missing, which is a hole the writer never learns about.
      *
      * A batch of writes issued from one snapshot starts from the same
      * `eventCount`; they land on consecutive slots in whatever order the World
@@ -863,9 +853,8 @@ export type EventResult<T extends EventType = EventType> = {
      *   log through the canonical `hook_received`, so the lazy hook queue
      *   consumer can skip both the `run_started` write and the initial
      *   `events.list`.
-     * - On any response from a slot-allocating World (see
-     *   `WorldCapabilities.slotEventIds`) whose committed slot came out
-     *   higher than the one {@link CreateEventParams.eventCount} asked for:
+     * - On any response whose committed slot came out higher than the one
+     *   {@link CreateEventParams.eventCount} asked for:
      *   the events occupying the slots that were skipped over, in slot
      *   order. This is the "report" half of bump-and-report — the write
      *   succeeded, and these are the events the writer had not seen when it

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

@@ -1,10 +1,10 @@
 export type * from './analytics.js';
-export { AnalyticsAttributeKeySchema, AnalyticsEventSchema, AnalyticsHookSchema, AnalyticsRunSchema, AnalyticsStepSchema, AnalyticsWaitSchema, } from './analytics.js';
+export { ANALYTICS_EVENTS_GET_MANY_LIMIT, AnalyticsAttributeKeySchema, AnalyticsEventSchema, AnalyticsHookSchema, AnalyticsRunSchema, AnalyticsStepSchema, AnalyticsWaitSchema, } from './analytics.js';
 export type * from './attributes.js';
 export { ATTRIBUTE_KEY_MAX_LENGTH, ATTRIBUTE_MAX_PER_RUN, ATTRIBUTE_VALUE_MAX_BYTES, AttributeChangeSchema, AttributeChangesSchema, AttributeValidationError, applyAttributeChanges, PARENT_RUN_ID_ATTRIBUTE, RESERVED_ATTRIBUTE_KEY_PREFIX, ROOT_RUN_ID_ATTRIBUTE, validateAttributeChanges, validateAttributeKey, validateAttributeValue, } from './attributes.js';
 export { _resetEnvWarnCacheForTests, type EnvNumberOptions, envNumber, getMaxEventsPerRun, } from './env-config.js';
 export type * from './events.js';
-export { BaseEventSchema, CHILD_ENTITY_CREATION_EVENT_TYPES, CreateEventSchema, EVENT_DATA_PAYLOAD_FIELD_BY_EVENT_TYPE, EVENT_DATA_REF_FIELDS, EventSchema, EventTypeSchema, getEventDataPayloadField, getEventDataRefFields, HOOK_EVENTS_REQUIRING_EXISTENCE, HOOK_LIFECYCLE_EVENT_TYPES, HookCreatedEventSchema, isChildEntityCreationEvent, isChildEntityCreationEventType, isHookEventRequiringExistence, isHookLifecycleEventType, isRunEventType, isStepEventType, isTerminalRunEventType, isTerminalStepEventType, isWaitEventType, RUN_EVENT_TYPES, STEP_EVENT_TYPES, stripEventDataRefs, TERMINAL_RUN_EVENT_TYPES, TERMINAL_STEP_EVENT_TYPES, TerminalRunEventTypeSchema, WAIT_EVENT_TYPES, } from './events.js';
+export { BaseEventSchema, CHILD_ENTITY_CREATION_EVENT_TYPES, CreateEventSchema, EVENT_DATA_PAYLOAD_FIELD_BY_EVENT_TYPE, EVENT_DATA_REF_FIELDS, EventSchema, EventTypeSchema, entityEventClass, getEventDataPayloadField, getEventDataRefFields, HOOK_EVENTS_REQUIRING_EXISTENCE, HOOK_LIFECYCLE_EVENT_TYPES, HookCreatedEventSchema, isChildEntityCreationEvent, isChildEntityCreationEventType, isHookEventRequiringExistence, isHookLifecycleEventType, isRunEventType, isStepEventType, isTerminalRunEventType, isTerminalStepEventType, isWaitEventType, RUN_EVENT_TYPES, STEP_EVENT_TYPES, stripEventDataRefs, TERMINAL_RUN_EVENT_TYPES, TERMINAL_STEP_EVENT_TYPES, TerminalRunEventTypeSchema, WAIT_EVENT_TYPES, } from './events.js';
 export type * from './hooks.js';
 export { HOOK_RESUME_DEDUP_VERSION, HOOK_RESUME_INPUT_VERSION, HookResumeCapabilitiesSchema, HookSchema, } from './hooks.js';
 export type * from './interfaces.js';
@@ -18,7 +18,7 @@ export { LegacySerializedDataSchemaV1, SerializedDataSchema, } from './serializa
 export type * from './shared.js';
 export type { GetChunksOptions, StreamChunk, StreamChunksResponse, StreamInfoResponse, } from './shared.js';
 export { PaginatedResponseSchema, StructuredErrorSchema, } from './shared.js';
-export { EVENT_ID_BODY_LENGTH, EVENT_ID_PREFIX, eventIdToSlot, FIRST_EVENT_SLOT, isSlotBody, isSlotEventId, MAX_EVENT_SLOT, slotToEventId, } from './slot-identity.js';
+export { EVENT_ID_BODY_LENGTH, EVENT_ID_PREFIX, eventIdToSlot, FIRST_EVENT_SLOT, isSlotBody, isSlotEventId, MAX_EVENT_SLOT, requireEventSlot, slotToEventId, } from './slot-identity.js';
 export type { SpecVersion } from './spec-version.js';
 export { isLegacySpecVersion, requiresNewerWorld, SPEC_VERSION_CURRENT, SPEC_VERSION_LEGACY, SPEC_VERSION_MAX_SUPPORTED, SPEC_VERSION_SUPPORTS_ATTRIBUTES, SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT, SPEC_VERSION_SUPPORTS_COMPRESSION, SPEC_VERSION_SUPPORTS_EVENT_SOURCING, SPEC_VERSION_SUPPORTS_SLOT_IDENTITY, } from './spec-version.js';
 export type * from './steps.js';

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

@@ -107,6 +107,14 @@ export interface Storage {
             }): Promise<(WorkflowRun | null)[]>;
             (ids: readonly string[], params?: GetWorkflowRunParams): Promise<(WorkflowRun | WorkflowRunWithoutData | null)[]>;
         };
+        /**
+         * Lists canonical workflow storage records.
+         *
+         * @remarks Observability and inspection usage of this method is
+         * deprecated. Use `world.analytics?.runs.list()` for plan-aware
+         * observability queries. This storage API remains available for
+         * operational and payload-bearing callers.
+         */
         list(params: ListWorkflowRunsParams & {
             resolveData: 'none';
         }): Promise<PaginatedResponse<WorkflowRunWithoutData>>;
@@ -168,6 +176,35 @@ export interface Storage {
         }): Promise<PaginatedResponse<Step>>;
         list(params: ListWorkflowRunStepsParams): Promise<PaginatedResponse<Step | StepWithoutData>>;
     };
+    /**
+     * 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
+     * its run's log, zero-padded to 26 characters. Use `slotToEventId()` to
+     * format one.
+     *
+     * Not a capability to opt into. The runtime reads a position out of every id
+     * it loads (`requireEventSlot`) and fails the run if it cannot, so a World
+     * whose ids are not positions cannot replay anything at all. Two properties
+     * are what the runtime actually relies on:
+     *
+     * - **Density.** A run's slots are contiguous from 1, so the number of
+     *   events a reader holds *is* the position of the last one. That is what
+     *   makes {@link CreateEventParams.eventCount} a complete statement of the
+     *   writer's snapshot in a single integer, and what lets a reader tell a
+     *   complete log from a truncated one by its length.
+     * - **Bump and report.** A create never fails because its requested slot is
+     *   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
+     *   World needs a precondition guard.
+     *
+     * Allocating at the commit is what makes a reader's log a *prefix* of the
+     * run's log rather than a prefix with a hole in it. A World that hands a
+     * position out earlier, and can therefore let an event land behind one a
+     * reader has already passed, breaks the property every replay depends on.
+     */
     events: {
         /**
          * Create a run_created event to start a new workflow run.
@@ -227,25 +264,6 @@ export interface WorldCapabilities {
     hookRetention?: {
         active: boolean;
     };
-    /**
-     * The World enforces the optimistic-concurrency precondition guard: an
-     * event creation carrying a `stateUpdatedAt` snapshot is rejected with a
-     * `PreconditionFailedError` (412) when a newer out-of-band event (e.g. a
-     * received hook) was recorded after that snapshot. Worlds that accept but
-     * ignore `stateUpdatedAt` must leave this unset so runtime optimizations
-     * that rely on the 412 fence (see `WORKFLOW_PRECONDITION_GUARD`) are not
-     * enabled without an actual fence behind them.
-     *
-     * A World declaring this should honour the whole snapshot the runtime sends,
-     * not just the watermark: `stateUpdatedAt`, `stateEventCount` (the count
-     * fence, which catches an event missing at or below the watermark — the case
-     * the watermark provably cannot see) and, optionally, `stateCursor` (return
-     * the missing events on the 412 to save the client a reload). See
-     * `CreateEventParams` for each field's contract. The runtime does not branch
-     * on which halves are implemented; a World that ignores the count simply
-     * fences less.
-     */
-    preconditionGuard?: boolean;
     /**
      * The World's queue supports `maxConcurrency`-limited consumption — in
      * particular the per-run flow topics consumed with `maxConcurrency: 1`
@@ -305,29 +323,6 @@ export interface WorldCapabilities {
      * fail ordinary runs after a version bump.
      */
     deploymentAffinity?: boolean;
-    /**
-     * The World allocates **slot-numbered** event ids: `evnt_` plus the event's
-     * dense, 1-based position in its run's log, zero-padded to 26 characters
-     * (see `slot-identity.ts`). Two guarantees come with it, and the runtime
-     * relies on both:
-     *
-     * - **Density.** A run's slots are contiguous from 1, so the number of
-     *   events a reader holds *is* the position of the last one. That is what
-     *   makes {@link CreateEventParams.eventCount} a complete statement of the
-     *   writer's snapshot, where the `stateUpdatedAt` / `stateEventCount`
-     *   watermark pair could only approximate it.
-     * - **Bump and report.** A create never fails because its requested slot is
-     *   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.
-     *
-     * A run's scheme is pinned by the run, not by this flag: it is readable off
-     * the shape of the run's own first event id, so a World that turns slots on
-     * keeps replaying its existing ULID-numbered runs unchanged. The capability
-     * only says what *new* runs get.
-     */
-    slotEventIds?: boolean;
 }
 /**
  * The "World" interface represents how Workflows are able to communicate with the outside world.
@@ -343,10 +338,15 @@ export interface World extends Queue, Streamer, Storage {
      */
     analytics?: Analytics;
     /**
-     * The Workflow protocol spec version this World implements.
+     * The Workflow protocol spec version this World implements, and the version
+     * stamped on every run it creates.
      *
-     * Current runtimes require this to exactly match their
-     * `SPEC_VERSION_CURRENT` before they create or replay runs.
+     * Declare `SPEC_VERSION_CURRENT` rather than a literal. The runtime checks
+     * this against `[SPEC_VERSION_CURRENT, SPEC_VERSION_MAX_SUPPORTED]` before it
+     * creates or replays anything, and refuses a World outside that range: below
+     * the floor the World allocates event ids the runtime cannot read positions
+     * out of (see the event log contract above), above the ceiling it speaks a
+     * spec this runtime has not learned.
      */
     specVersion: number;
     /**