eve 0.82.0 → 0.83.0

package/dist/src/compiled/@workflow/core/seeded-nanoid.d.ts

@@ -0,0 +1,2 @@
+export declare function createSeededNanoid(random: () => number): () => string;
+//# sourceMappingURL=seeded-nanoid.d.ts.map

package/dist/src/compiled/@workflow/core/serialization/compression.d.ts

@@ -45,6 +45,15 @@ export declare const COMPRESSION_MIN_BYTES = 1024;
  * data paying a permanent decompression tax for a negligible win.
  */
 export declare const COMPRESSION_MIN_SAVINGS_RATIO = 0.05;
+/**
+ * Payloads below this size are compressed synchronously even when the
+ * caller asks for the threadpool (`preferAsync`). Handing a buffer to the
+ * threadpool and back costs ~0.5 ms of wall time regardless of size,
+ * while sync zstd at level 3 blocks the loop for ~0.1 ms at 2 KiB and
+ * ~0.4 ms at 64 KiB; the trade only pays off once the sync call would
+ * block for longer than the round trip.
+ */
+export declare const COMPRESSION_ASYNC_MIN_BYTES: number;
 /** Which codec compressed a payload (or `none` when stored uncompressed). */
 export type CompressionCodec = 'zstd' | 'gzip' | 'none';
 /**
@@ -108,9 +117,11 @@ export declare function compress(data: Uint8Array | unknown, mode: CompressionMo
     /**
      * Compress off the event loop where the codec supports it (zstd via
      * the libuv threadpool; gzip is stream-based and already async).
-     * For multi-MB payloads compressed while a response is flushing —
-     * the sync zstd path would block the loop for the whole compression.
-     * Output bytes are identical either way.
+     * For payloads compressed on a latency-sensitive path, where the
+     * sync zstd call would block the loop for the whole compression.
+     * Only applied from {@link COMPRESSION_ASYNC_MIN_BYTES} up: below
+     * that the threadpool round trip costs more wall time than the sync
+     * call blocks. The result decodes identically either way.
      */
     preferAsync?: boolean;
 }): Promise<Uint8Array | unknown>;

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

@@ -320,7 +320,7 @@ export declare function getCommonRevivers(global?: Record<string, any>): {
 };
 /**
  * Resolves the owner's encryption key, preferring its public key, then its
- * deployment, and finally its run record.
+ * deployment, and finally the deployment on its run record.
  * @internal
  */
 export declare function getForwardedWritableEncryptionKey(runId: string, deploymentId: string | undefined, encryptionPublicKey: string | undefined): Promise<PayloadKey | undefined>;

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

@@ -1 +1 @@
-import{A as e,Ar as t,C as n,Cr as r,D as i,Dr as a,E as o,Er as s,F as c,I as l,L as u,M as d,Mr as f,N as p,Nr as m,O as h,Or as g,P as _,R as v,S as y,Sr as b,T as x,Tr as S,_ as C,a as w,b as T,br as E,c as D,d as O,f as k,g as A,h as j,i as M,j as N,jr as P,k as F,kr as I,l as L,m as R,n as z,o as B,p as V,r as H,s as U,t as W,u as G,v as K,vr as q,w as J,wr as Y,x as X,xr as Z,y as Q,yr as $,z as ee}from"../../_chunks/workflow/serialization-DPdYS_w2.js";export{W as FRAMED_STREAM_MAX_RECONNECTS,z as FRAMED_STREAM_MAX_TOTAL_RECONNECTS,f as SerializationFormat,H as WorkflowServerReadableStream,M as WorkflowServerWritableStream,q as aesKeyOf,w as cancelAbortReaders,s as compress,B as createForwardedWritable,U as createReconnectingFramedStream,g as decodeFormatPrefix,a as decompress,$ as decrypt,D as dehydrateDynamicWorkflowCode,L as dehydrateRunError,G as dehydrateStepArguments,O as dehydrateStepError,k as dehydrateStepReturnValue,V as dehydrateWorkflowArguments,R as dehydrateWorkflowReturnValue,E as deriveRunPayloadKeys,j as deserializePreparedReplayPayload,A as deserializePreparedStepError,I as encodeWithFormatPrefix,Z as encrypt,C as getByteFramingStream,K as getByteUnframingStream,Q as getCommonRevivers,T as getDeserializeStream,X as getExternalReducers,y as getExternalRevivers,n as getForwardedWritableEncryptionKey,J as getRunReadableStream,x as getSerializeStream,o as getStreamType,i as getWorkflowReducers,h as getWorkflowRevivers,F as hydrateDynamicWorkflowCode,e as hydrateRunError,N as hydrateStepArguments,d as hydrateStepError,p as hydrateStepReturnValue,_ as hydrateWorkflowArguments,c as hydrateWorkflowReturnValue,t as isEncrypted,m as isFormatPrefix,b as isRunPayloadKeys,r as isSealTarget,l as maybeDecrypt,u as maybeEncrypt,P as peekFormatPrefix,v as prepareReplayPayload,Y as runPayloadKeys,S as sealTo,ee as tagForwardedWritableTarget};
+import{A as e,Ar as t,C as n,Cr as r,D as i,Dr as a,E as o,Er as s,F as c,I as l,L as u,M as d,N as f,O as p,Or as m,P as h,R as g,S as _,Sr as v,T as y,Tr as b,_ as x,_r as S,a as C,b as w,br as T,c as E,d as D,f as O,g as k,gr as A,h as j,i as M,j as N,jr as P,k as F,kr as I,l as L,m as R,n as z,o as B,p as V,r as H,s as U,t as W,u as G,v as K,vr as q,w as J,wr as Y,x as X,xr as Z,y as Q,yr as $,z as ee}from"../../_chunks/workflow/serialization-B9gneT9Z.js";export{W as FRAMED_STREAM_MAX_RECONNECTS,z as FRAMED_STREAM_MAX_TOTAL_RECONNECTS,t as SerializationFormat,H as WorkflowServerReadableStream,M as WorkflowServerWritableStream,A as aesKeyOf,C as cancelAbortReaders,Y as compress,B as createForwardedWritable,U as createReconnectingFramedStream,s as decodeFormatPrefix,b as decompress,S as decrypt,E as dehydrateDynamicWorkflowCode,L as dehydrateRunError,G as dehydrateStepArguments,D as dehydrateStepError,O as dehydrateStepReturnValue,V as dehydrateWorkflowArguments,R as dehydrateWorkflowReturnValue,q as deriveRunPayloadKeys,j as deserializePreparedReplayPayload,k as deserializePreparedStepError,a as encodeWithFormatPrefix,$ as encrypt,x as getByteFramingStream,K as getByteUnframingStream,Q as getCommonRevivers,w as getDeserializeStream,X as getExternalReducers,_ as getExternalRevivers,n as getForwardedWritableEncryptionKey,J as getRunReadableStream,y as getSerializeStream,o as getStreamType,i as getWorkflowReducers,p as getWorkflowRevivers,F as hydrateDynamicWorkflowCode,e as hydrateRunError,N as hydrateStepArguments,d as hydrateStepError,f as hydrateStepReturnValue,h as hydrateWorkflowArguments,c as hydrateWorkflowReturnValue,m as isEncrypted,P as isFormatPrefix,T as isRunPayloadKeys,Z as isSealTarget,l as maybeDecrypt,u as maybeEncrypt,I as peekFormatPrefix,g as prepareReplayPayload,v as runPayloadKeys,r as sealTo,ee as tagForwardedWritableTarget};

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

@@ -566,24 +566,6 @@ 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, which completes the
- * recovery path {@link StepResilientDispatchRecovered} began.
- */
-export declare const StepResilientDispatchMaterialized: (value: boolean) => {
-    [k: string]: boolean;
-};
 /**
  * How the queued-step consumer resolved the run identity for this execution:
  * `run_context` — carried on the dispatch message, no `runs.get` before the

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

@@ -1,2 +1,2 @@
-export declare const version = "5.2.0";
+export declare const version = "5.2.3";
 //# sourceMappingURL=version.d.ts.map

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

@@ -1 +1 @@
-import{Fr as e,Pr as t,Zr as n,ii as r,ni as i,ri as a}from"../../_chunks/workflow/serialization-DPdYS_w2.js";import{d as o,i as s}from"../../_chunks/workflow/dist-T5NnW-0k.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-BW-kbMMn.js";import{t as m}from"../../_chunks/workflow/sleep-BY6leHh8.js";import{t as h}from"../../_chunks/workflow/run-DzdAqdb1.js";e(t,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 generated for you. 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 s("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{s as FatalError,o 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{Mr as e,Nr as t,Yr as n,ei as r,ni as i,ti as a}from"../../_chunks/workflow/serialization-B9gneT9Z.js";import{i as o,m as s}from"../../_chunks/workflow/dist-S9cZRway.js";import{a as c}from"../../_chunks/workflow/workflow-routes-BaljomCk.js";import{c as l,i as u,o as d,r as f,t as p}from"../../_chunks/workflow/attribute-changes-7se_SE2q.js";import{t as m}from"../../_chunks/workflow/sleep-BL0oQs3R.js";import{t as h}from"../../_chunks/workflow/run-BJSLCXR4.js";t(e,h);function g(e){let t=globalThis[r];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 generated for you. 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,a=globalThis[i];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,r?{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};

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

@@ -1,4 +1,21 @@
 import type { StringValue } from './_ms.js';
+/**
+ * @internal
+ * Format an error message with framed `hint:` / `docs:` details, for errors
+ * raised as plain classes (e.g. `FatalError`) that can't take a slug.
+ */
+export declare function formatErrorMessageWithDetails(title: string, details: {
+    hint?: string;
+    slug?: ErrorSlug;
+}): string;
+/**
+ * @internal
+ * Shared remediation text for runs that outgrow the default event-count
+ * ceiling or replay budget. QuickJS runs with snapshotting are exempt from
+ * the default ceiling, and resume from a snapshot instead of replaying the
+ * full event log.
+ */
+export declare const QUICKJS_SNAPSHOT_REMEDIATION: string;
 /**
  * @internal
  * All the slugs of the errors used for documentation links.
@@ -19,6 +36,8 @@ export declare const ERROR_SLUGS: {
     readonly WORKFLOW_NOT_REGISTERED: "workflow-not-registered";
     readonly RUNTIME_DECRYPTION_FAILED: "runtime-decryption-failed";
     readonly DEPLOYMENT_MISMATCH: "deployment-mismatch";
+    readonly MAX_EVENTS_EXCEEDED: "max-events-exceeded";
+    readonly REPLAY_TIMEOUT: "replay-timeout";
 };
 type ErrorSlug = (typeof ERROR_SLUGS)[keyof typeof ERROR_SLUGS];
 interface WorkflowErrorOptions extends ErrorOptions {
@@ -599,6 +618,35 @@ export declare class PreconditionFailedError extends WorkflowWorldError {
     });
     static is(value: unknown): value is PreconditionFailedError;
 }
+/** Error code a World uses for an {@link InBandSupersededError} refusal. */
+export declare const IN_BAND_SUPERSEDED_CODE = "in-band-superseded";
+/**
+ * Thrown when a World refuses an in-band write (a write made by the run's
+ * orchestrator) because another orchestrator invocation of the same run has
+ * written in-band since this one loaded the log (HTTP 412,
+ * `in-band-superseded`).
+ *
+ * The in-band fence keeps a run to one orchestrator writer: the World counts
+ * the positions it allocated to in-band writes, and accepts an in-band write
+ * only when the writer's expected count matches. Nothing is written or
+ * allocated for a refused write.
+ *
+ * @property seq - The run's allocated position count at the time of the
+ *   refusal, when the World reports it. Diagnostic only.
+ * @property seqInBand - The run's in-band position count at the time of the
+ *   refusal, when the World reports it. Diagnostic only: a client must never
+ *   adopt it as its own count, since that would make it a writer without
+ *   having seen the events the count stands for.
+ */
+export declare class InBandSupersededError extends WorkflowWorldError {
+    readonly seq?: number;
+    readonly seqInBand?: number;
+    constructor(message: string, options?: {
+        seq?: number;
+        seqInBand?: number;
+    });
+    static is(value: unknown): value is InBandSupersededError;
+}
 /**
  * Thrown when awaiting `run.returnValue` on a workflow run that was cancelled.
  *

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

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

package/dist/src/compiled/@workflow/world/env-config.d.ts

@@ -40,6 +40,30 @@ export declare function envNumber(name: string, fallback: number, options?: EnvN
  */
 export declare function envFlag(name: string, fallback: boolean, env?: Record<string, string | undefined>): boolean;
 export declare function getMaxEventsPerRun(): number;
+/**
+ * Whether a run is exempt from the default per-run event ceiling: its
+ * persisted `executionContext` selects the QuickJS VM with a positive
+ * safe-integer `snapshotThreshold`. Snapshotting keeps resume cost bounded
+ * regardless of log length, so these runs don't need the ceiling.
+ *
+ * Mirrors the Vercel World's server-side policy so runs behave the same
+ * locally and in production.
+ */
+export declare function isEventLimitExemptRun(run?: {
+    executionContext?: unknown;
+}): boolean;
+/**
+ * The event ceiling a World advertises (as `maxEvents`) for a specific
+ * run. Exempt runs (see {@link isEventLimitExemptRun}) get
+ * `Number.MAX_SAFE_INTEGER`, which is effectively unlimited while staying a
+ * positive integer for SDKs that validate one. Other runs get
+ * {@link getMaxEventsPerRun}.
+ *
+ * Use {@link getMaxEventsPerRun} (not this) for page sizes and scan bounds.
+ */
+export declare function getMaxEventsForRun(run?: {
+    executionContext?: unknown;
+}): number;
 /**
  * Reset the warn-once cache. Test-only, exported so unit tests can exercise
  * the warning path repeatedly without sharing state across cases.

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

@@ -1,7 +1,7 @@
 import { z } from '#compiled/zod/index.js';
 import type { Hook } from './hooks.js';
 import type { StartedWorkflowRun, WorkflowRun } from './runs.js';
-import type { EventsResolveData, PaginationOptions, ResolveData } from './shared.js';
+import type { EventsResolveData, PaginatedResponse, PaginationOptions, ResolveData } from './shared.js';
 import type { StartedStep, Step } from './steps.js';
 import type { Wait } from './waits.js';
 export * from './event-metadata.js';
@@ -617,6 +617,56 @@ export type RunCreatedEventRequest = z.infer<typeof RunCreatedEventSchema>;
 export type CreateEventRequest = Exclude<AnyEventRequest, RunCreatedEventRequest>;
 export interface CreateEventParams {
     v1Compat?: boolean;
+    /**
+     * Whether the run's orchestrator is making this write, for the in-band
+     * writer fence. Optional World support: a World that implements the fence
+     * counts the positions it allocates to in-band writes, and accepts an
+     * in-band write only when {@link expectedSeqInBand} equals that count,
+     * refusing it otherwise with `InBandSupersededError` (HTTP 412,
+     * `in-band-superseded`) before anything is written or allocated.
+     * Out-of-band writes (`false` or absent) are never refused by the fence and
+     * never move the in-band count.
+     *
+     * Only the orchestrator's own writes may set it. Writes made from outside
+     * the run's orchestrator (cancellation, hook resumption, step execution,
+     * dispatch re-ensures) stay out-of-band, since they can come from a newer
+     * SDK than the run's own and must never be refused on its behalf. A
+     * fenced `step_created` must not be published to the step queue in parallel
+     * with its write (resilient step dispatch): the dispatch's out-of-band
+     * re-ensure would materialize a step the fence refused. A World may revoke
+     * such a dispatch on refusal, but only as a best-effort backstop.
+     *
+     * A World may refuse an in-band write on a run whose stamped spec version
+     * predates the sealed log (`SPEC_VERSION_SUPPORTS_SEALED_LOG`), rather than
+     * accept it unfenced. A caller must therefore decide from the run's stamped
+     * spec version, never from its own SDK version: the same SDK still executes
+     * runs stamped below it (the `WORKFLOW_SEALED_LOG` opt-out, and
+     * cross-deployment starts, which are stamped with the lower of the caller's
+     * and the target's version).
+     *
+     * The runtime does not set it yet.
+     */
+    inBand?: boolean;
+    /**
+     * The writer's count of in-band positions, required with `inBand: true`
+     * and only allowed with it. `run_created` counts as the run's first in-band
+     * position, so the lowest valid value is 1.
+     *
+     * The count is the World's, not the client's: a writer starts from a count
+     * the World reports (a snapshot read with the log it loaded) and advances
+     * it by the in-band positions the World reports a write allocated. It must
+     * never be derived by counting events or writes, because the two diverge:
+     *
+     * - a single create can allocate more than one position, when one of its
+     *   own positions is sealed and it allocates again;
+     * - a write the World rejects after allocating (for example a 409 on a
+     *   duplicate entity) may still have advanced the count;
+     * - a World may reset the count when it loses its counter, and only a
+     *   World-provided snapshot reflects that.
+     *
+     * A writer that holds no World-provided count must not send the fence.
+     */
+    expectedSeqInBand?: number;
     /**
      * `'skip-step-inputs'` applies only to the event-log page this create
      * returns (the `sinceCursor` delta or a replay preload), never to the
@@ -651,11 +701,11 @@ export interface CreateEventParams {
      * 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
+     * Advisory, and not set by the current `@workflow/core` runtime, which
+     * publishes a step's queue message only after its create. A producer that
+     * parallelizes the two accepts that a create can come back refused while
+     * the message carrying its payload is already out, and a backend MAY use
+     * this flag to narrow that window: 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
@@ -690,7 +740,11 @@ export interface CreateEventParams {
      * the replay loop and the suspension handler, which merge the report below
      * back into their loaded log. Omitted by callers with no loaded log to be
      * stale against, the step executor included: for those the report would be
-     * a read the World does for no one.
+     * a read the World does for no one. Independent concurrent hook registrations
+     * in a hooks-only suspension also omit it deliberately: the runtime verifies
+     * their committed events together after every write settles, and reloads if
+     * they do not form a complete suffix. Absence does not imply no loaded log;
+     * without a count there is no evidence for count-based stale rejection.
      *
      * 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
@@ -849,6 +903,18 @@ export interface CreateEventParams {
 export type EventResult<T extends EventType = EventType> = {
     /** The created event (optional for legacy compatibility) */
     event?: Event;
+    /**
+     * Optional ascending events.list cursor immediately after `event`, minted
+     * by the World that owns the cursor format. This does not attest that the
+     * caller holds any earlier events. The runtime may advance to it only after
+     * proving that its loaded prefix plus committed responses covers every slot
+     * through this event. Worlds that omit it retain the normal reload path.
+     * When supplied, `event` MUST match what ascending events.list returns for
+     * that slot with the same resolveData option, including stored timestamps,
+     * normalized retention, metadata bytes, and hook-conflict details. The
+     * runtime uses this stored event as replay input, not an echo of the request.
+     */
+    eventCursor?: string;
     /** The workflow run entity (for run_* events) */
     run?: WorkflowRun;
     /** The step entity (for step_* events) */
@@ -871,6 +937,14 @@ export type EventResult<T extends EventType = EventType> = {
     stepCreated?: true;
     /** Server-owned max event count for the run (run-lifecycle responses); the runtime enforces it. */
     maxEvents?: number;
+    /**
+     * How many positions this write allocated to the run's log, when the World
+     * reports it: 1 for a create that appended its event, 0 for one that
+     * converged on an event the log already held. A World implementing the
+     * in-band fence advances the run's in-band count by this number for an
+     * accepted in-band write. Absent from a World that does not report it.
+     */
+    allocated?: number;
 } & ({
     /**
      * Events with data resolved. Five producers populate this:
@@ -947,6 +1021,18 @@ export interface CreateEventBatchParams {
      * attribution its single-path twin would.
      */
     requestId?: string;
+    /**
+     * The in-band fence for the whole batch, as {@link CreateEventParams.inBand}.
+     * Every event of a batch shares it.
+     */
+    inBand?: boolean;
+    /**
+     * The writer's in-band count for the whole block, as
+     * {@link CreateEventParams.expectedSeqInBand}. The block's positions are
+     * allocated in one fenced allocation, and the count the World reports for
+     * it covers the whole block even when some of its events are rejected.
+     */
+    expectedSeqInBand?: number;
 }
 /**
  * One event's outcome in a batch response, index-aligned with the submitted
@@ -1011,6 +1097,39 @@ export interface EventBatchResult {
     /** One entry per submitted event, in request order. */
     results: BatchEventItemResult[];
 }
+/**
+ * The sequencer state a World read before it listed a run's log, for the
+ * in-band writer fence ({@link CreateEventParams.inBand}). Positions are
+ * slots.
+ */
+export interface EventLogSnapshot {
+    /** Highest position allocated to any write when the list began. */
+    seq: number;
+    /** Number of positions allocated to in-band writes when the list began. */
+    seqInBand: number;
+}
+/**
+ * A run's in-band count right after its creation, before any other write:
+ * `run_created` counts as the run's first in-band position, so the run's
+ * first fenced orchestrator write expects this value.
+ */
+export declare const IN_BAND_SEQ_AT_RUN_CREATION = 1;
+/**
+ * Result of {@link Storage.events.list}.
+ *
+ * `snapshot` is set by a World that implements the in-band writer fence
+ * (`WorldCapabilities.inBandFence`), on every page of a slot-numbered run's
+ * log where the World reads one. It is read before the listing, so a full
+ * load (following `cursor` until `hasMore` is false) covers every position
+ * up to the FIRST page's `snapshot.seq`. A fenced writer takes its
+ * {@link CreateEventParams.expectedSeqInBand} from the first page's
+ * `snapshot.seqInBand`, never from counting events: a count cannot tell
+ * which positions were in-band. A fencing World that lists no snapshot
+ * reports the counters on a refusal (`InBandSupersededError`) instead.
+ */
+export type EventListResponse = PaginatedResponse<Event> & {
+    snapshot?: EventLogSnapshot;
+};
 export interface GetEventParams {
     resolveData?: ResolveData;
 }

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

@@ -2,16 +2,16 @@ export type * from './analytics.js';
 export { ANALYTICS_EVENTS_GET_MANY_LIMIT, ANALYTICS_MAX_ATTRIBUTE_FILTERS, ANALYTICS_PAGE_LIMIT, ANALYTICS_RUN_SCOPED_PAGE_LIMIT, AnalyticsAttributeKeySchema, AnalyticsEventSchema, AnalyticsHookSchema, AnalyticsRunSchema, AnalyticsStepSchema, AnalyticsWaitSchema, } from './analytics.js';
 export type * from './attributes.js';
 export { ATTRIBUTE_EVENT_DATA_MAX_BYTES, ATTRIBUTE_KEY_MAX_LENGTH, ATTRIBUTE_MAX_PER_RUN, ATTRIBUTE_VALUE_MAX_BYTES, AttributeChangeSchema, AttributeChangesSchema, AttributeKeySchema, AttributeValidationError, AttributeValueSchema, applyAttributeChanges, PARENT_RUN_ID_ATTRIBUTE, purgesUserDataOnFinish, RESERVED_ATTRIBUTE_KEY_PREFIX, RETENTION_ATTRIBUTE, RETENTION_DEFAULT, RETENTION_ZERO, type ResolvedRunRetention, ROOT_RUN_ID_ATTRIBUTE, type RunRetention, readRunRetention, validateAttributeChanges, validateAttributeEventDataSize, } from './attributes.js';
-export { _resetEnvWarnCacheForTests, type EnvNumberOptions, envFlag, envNumber, getMaxEventsPerRun, } from './env-config.js';
+export { _resetEnvWarnCacheForTests, type EnvNumberOptions, envFlag, envNumber, getMaxEventsForRun, getMaxEventsPerRun, isEventLimitExemptRun, } from './env-config.js';
 export type * from './events.js';
-export { BaseEventSchema, CHILD_ENTITY_CREATION_EVENT_TYPES, CreateEventSchema, classifyEntityEvent, EventSchema, EventTypeSchema, entityEventClass, getEventDataPayloadField, getEventDataRefFields, HOOK_EVENTS_REQUIRING_EXISTENCE, HOOK_LIFECYCLE_EVENT_TYPES, HookCreatedEventSchema, isChildEntityCreationEvent, isChildEntityCreationEventType, isHookEventRequiringExistence, isHookLifecycleEventType, isRunEventType, isSealedNoopEvent, isStepEventType, isTerminalRunEventType, isTerminalStepEventType, isWaitEventType, RUN_ENTITY_KEY, RUN_EVENT_TYPES, STEP_EVENT_TYPES, stripEventDataRefs, TERMINAL_EVENT_CLASSES, TERMINAL_RUN_EVENT_TYPES, TERMINAL_STEP_EVENT_TYPES, TerminalRunEventTypeSchema, WAIT_EVENT_TYPES, } from './events.js';
+export { BaseEventSchema, CHILD_ENTITY_CREATION_EVENT_TYPES, CreateEventSchema, classifyEntityEvent, EventSchema, EventTypeSchema, entityEventClass, getEventDataPayloadField, getEventDataRefFields, HOOK_EVENTS_REQUIRING_EXISTENCE, HOOK_LIFECYCLE_EVENT_TYPES, HookCreatedEventSchema, IN_BAND_SEQ_AT_RUN_CREATION, isChildEntityCreationEvent, isChildEntityCreationEventType, isHookEventRequiringExistence, isHookLifecycleEventType, isRunEventType, isSealedNoopEvent, isStepEventType, isTerminalRunEventType, isTerminalStepEventType, isWaitEventType, RUN_ENTITY_KEY, RUN_EVENT_TYPES, STEP_EVENT_TYPES, stripEventDataRefs, TERMINAL_EVENT_CLASSES, 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, HookClaimedFromSchema, HookResumeCapabilitiesSchema, HookSchema, } from './hooks.js';
 export type * from './interfaces.js';
 export type { InvocationOutcome, SerializedWorkflowError, } from './invocation.js';
 export { isNodeHttpEnabled, NODE_HTTP_DEFAULT, NODE_HTTP_ENV_VAR, } from './node-http-flag.js';
 export type * from './queue.js';
-export { getQueueTopicPrefix, HealthCheckPayloadSchema, MessageId, parseQueueName, QueuePayloadSchema, QueuePrefix, RunInputSchema, resolveQueueNamespace, ValidQueueName, WorkflowInvokePayloadSchema, } from './queue.js';
+export { getQueueTopicPrefix, getRunQueueNamespace, HealthCheckPayloadSchema, MessageId, parseQueueName, parseQueueRoute, QueuePayloadSchema, QueuePrefix, RunInputSchema, resolveQueueNamespace, ValidQueueName, WORKFLOW_FLOW_ROUTE, WorkflowInvokePayloadSchema, } from './queue.js';
 export { reenqueueActiveRuns } from './recovery.js';
 export type * from './runs.js';
 export { BULK_CANCEL_MAX_RUN_IDS, BulkCancelWorkflowRunResultSchema, BulkCancelWorkflowRunsRequestSchema, BulkCancelWorkflowRunsResultSchema, isTerminalWorkflowRunStatus, TERMINAL_WORKFLOW_RUN_STATUSES, TerminalWorkflowRunStatusSchema, WorkflowRunBaseSchema, WorkflowRunSchema, WorkflowRunStatusSchema, } from './runs.js';

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

@@ -1,6 +1,6 @@
 import type { Analytics } from './analytics.js';
 import type { AttributeChange, ExperimentalSetAttributesResult } from './attributes.js';
-import type { BatchEventRequest, CreateEventBatchParams, CreateEventParams, CreateEventRequest, Event, EventBatchResult, EventResult, GetEventParams, ListEventsByCorrelationIdParams, ListEventsParams, RunCreatedEventRequest } from './events.js';
+import type { BatchEventRequest, CreateEventBatchParams, CreateEventParams, CreateEventRequest, Event, EventBatchResult, EventListResponse, 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, WaitForTerminalRunStatusParams, WorkflowRun, WorkflowRunWithoutData } from './runs.js';
@@ -344,7 +344,7 @@ export interface Storage {
          */
         createBatch?(runId: string, events: BatchEventRequest[], params?: CreateEventBatchParams): Promise<EventBatchResult>;
         get(runId: string, eventId: string, params?: GetEventParams): Promise<Event>;
-        list(params: ListEventsParams): Promise<PaginatedResponse<Event>>;
+        list(params: ListEventsParams): Promise<EventListResponse>;
         listByCorrelationId(params: ListEventsByCorrelationIdParams): Promise<PaginatedResponse<Event>>;
     };
     hooks: {
@@ -465,6 +465,42 @@ export interface WorldCapabilities {
      * combined with it (and so Worlds document the contract explicitly).
      */
     maxConcurrency?: boolean;
+    /**
+     * The World implements the in-band writer fence
+     * ({@link CreateEventParams.inBand}). Optional: the runtime does not send
+     * the fence yet, and a World without it stays fully supported.
+     *
+     * Declaring it commits the World to all of:
+     *
+     * - **A per-run in-band count.** Next to the position counter its sequencer
+     *   allocates from (`seq`), the World counts the positions allocated to
+     *   in-band writes (`seqInBand`). A new run's `run_created` counts as
+     *   in-band and is never fenced itself, so a fresh run holds
+     *   `seq = 1, seqInBand = IN_BAND_SEQ_AT_RUN_CREATION`.
+     * - **The counters, from a list or a refusal.** `events.list` on a
+     *   slot-numbered run returns `snapshot: { seq, seqInBand }`
+     *   ({@link EventListResponse.snapshot}), read before the listing, on
+     *   every page where the World reads one. A World may list none
+     *   (world-vercel lists one only where its backend reports it); its
+     *   refusals then carry both counters, read together
+     *   (`InBandSupersededError.seq` and `.seqInBand`), and a writer takes its
+     *   count from a refusal instead. Building a World's in-band fence section
+     *   says how.
+     * - **Fenced in-band creates.** A create with `inBand: true` carries
+     *   {@link CreateEventParams.expectedSeqInBand}. The World checks it
+     *   against `seqInBand` and advances both counters by the positions it
+     *   allocates in one atomic step. On a mismatch it throws
+     *   `InBandSupersededError` (HTTP 412, `in-band-superseded`) and writes and
+     *   allocates nothing. An in-band write without an expected count is a 400.
+     *   A batch is one fenced allocation for the whole block.
+     * - **Unfenced out-of-band creates.** Writes with `inBand: false` (or
+     *   absent) move `seq` and never `seqInBand`, and are never refused by the
+     *   fence.
+     *
+     * `@workflow/world`'s `test-support/in-band-fence-conformance.ts` checks
+     * each of these against a World's `events` storage.
+     */
+    inBandFence?: boolean;
     /**
      * The World's `events.create` deduplicates concurrent `hook_received` writes
      * that carry the same `(runId, resumeId)`, collapsing them onto a single
@@ -630,17 +666,20 @@ export interface World extends Queue, Streamer, Storage {
      *
      * Two overloads:
      *
-     * - `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(run)`: Used when the runtime already holds
+     *   the `WorkflowRun` entity. The World reads any context it needs (e.g.,
+     *   `deploymentId`) directly from the run.
      *
-     * - `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
+     * - `getEncryptionKeyForRun(runId, context?)`: Used everywhere else: when
+     *   the run does not exist yet (`start()` before run creation), and when
+     *   the runtime has a run id but no reason to load the run's payloads
+     *   (stream reads, forwarded writable streams, hook resumption). 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.
      *
+     * Implementations must resolve the same key from either form.
+     *
      * When not implemented, encryption is disabled: data is stored unencrypted.
      */
     getEncryptionKeyForRun?(run: WorkflowRun): Promise<Uint8Array | undefined>;
@@ -667,6 +706,18 @@ export interface World extends Queue, Streamer, Storage {
      *   tolerate `undefined` for direct callers.
      */
     createRunId?(options?: Readonly<Record<string, unknown>>): string;
+    /**
+     * The region an existing run's data lives in, derived from its run ID
+     * alone (no I/O, never throws).
+     *
+     * The counterpart of {@link createRunId} for worlds that embed a region in
+     * the IDs they mint. Callers that create a run on behalf of an existing one
+     * (e.g. `recreateRunFromExisting()`) pass the result to `start({ region })`
+     * so the new run is placed where the original was, rather than wherever the
+     * calling process happens to execute. Return `null` when the ID is not one
+     * this world recognizes. Worlds without a regional dimension omit this.
+     */
+    regionForRunId?(runId: string): string | null;
     /**
      * Upload a dynamic run's serialized workflow VM code to the World's blob
      * storage ahead of `run_created`, returning the ref key to attach to the