eve 0.54.2 → 0.54.4

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

@@ -1,4 +1,4 @@
-import { createFlushableState } from './flushable-stream.js';
+import { createFlushableState, type FlushableStreamState } from './flushable-stream.js';
 import { compress, decompress } from './serialization/compression.js';
 import { aesKeyOf, decrypt, deriveRunPayloadKeys, type EncryptionKeyParam, encrypt, isRunPayloadKeys, isSealTarget, type PayloadKey, type RunPayloadKeys, runPayloadKeys, type SealTarget, sealTo } from './serialization/encryption.js';
 import { decodeFormatPrefix, encodeWithFormatPrefix, isEncrypted, peekFormatPrefix } from './serialization/format.js';
@@ -465,7 +465,7 @@ guestCodeStatsOut?: GuestCodeStats): Promise<Uint8Array | unknown>;
  * Called from the step executor to hydrate the arguments of a step
  * from the database at the start of the step execution.
  */
-export declare function hydrateStepArguments(value: Uint8Array | unknown, runId: string, key: PayloadKey | undefined, ops?: Promise<any>[], global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>, deploymentId?: string): Promise<any>;
+export declare function hydrateStepArguments(value: Uint8Array | unknown, runId: string, key: PayloadKey | undefined, ops?: Promise<any>[], global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>, deploymentId?: string, streamStates?: FlushableStreamState[]): Promise<any>;
 /**
  * Called from the step executor when a step has completed.
  * Dehydrates values from within the step execution environment

package/dist/src/compiled/@workflow/core/step/context-storage.d.ts

@@ -57,6 +57,8 @@ export type StepContext = {
     closureVars?: Record<string, any>;
     encryptionKey?: PayloadKey;
     writables?: Map<string, CachedWritable>;
+    /** Server-bound stream pipes whose current frames must drain at step end. */
+    streamStates?: FlushableStreamState[];
     /**
      * Turbo mode only: a promise that resolves once the backgrounded
      * `run_started` has landed (the run exists). Set when the step body runs

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

@@ -192,6 +192,15 @@ export declare const WorkflowOwnedRecoverySteps: (value: number) => {
 export declare const WorkflowBackstopWakesArmed: (value: number) => {
     [k: string]: number;
 };
+/**
+ * Number of pending steps whose immediate step-execution enqueue this replay
+ * pass skipped because THIS invocation already published that step's message
+ * on an earlier pass (a fan-out that ran inline steps and replayed again).
+ * Invocation-local knowledge only: a fresh delivery never skips.
+ */
+export declare const WorkflowDispatchRepublishSkipped: (value: number) => {
+    [k: string]: number;
+};
 /** The workflow runtime route being handled */
 export declare const WorkflowRouteType: (value: "flow") => {
     [k: string]: "flow";
@@ -294,6 +303,15 @@ export declare const StepFinalSchedulingReplayMs: (value: number) => {
 export declare const StepLatencyOptimizations: (value: string[]) => {
     [k: string]: string[];
 };
+/**
+ * How the step's initial `step_started` claim was made. Only present for
+ * inline create claims; ordinary background starts and owned recovery remain
+ * unlabeled.
+ */
+export type StepStartStrategy = 'awaited' | 'optimistic' | 'batch_preclaimed';
+export declare const StepStartStrategy: (value: StepStartStrategy) => {
+    [k: string]: StepStartStrategy;
+};
 /** Whether the step was skipped during execution */
 export declare const StepSkipped: (value: boolean) => {
     [k: string]: boolean;
@@ -350,6 +368,14 @@ export declare const MessagingMessageId: (value: string & import("zod").$brand<"
 export declare const MessagingOperationType: (value: "publish" | "receive" | "process") => {
     [k: string]: "publish" | "receive" | "process";
 };
+/**
+ * Messages carried by one batched publish (standard OTEL:
+ * messaging.batch.message_count). Set only on the batch send, so a span
+ * without it is a single-message publish.
+ */
+export declare const MessagingBatchMessageCount: (value: number) => {
+    [k: string]: number;
+};
 /** Time taken to enqueue the message in milliseconds (workflow-specific) */
 export declare const QueueOverheadMs: (value: number) => {
     [k: string]: number;
@@ -482,6 +508,16 @@ export declare const StepResilientDispatchRecovered: (value: number) => {
 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
+ * step (the fetch-free prologue); `runs_get` — the legacy blocking fetch
+ * (message from an older producer). Distinguishes the two paths during
+ * version-skew windows and makes the saved round trip directly measurable.
+ */
+export declare const StepDispatchPrologue: (value: "run_context" | "runs_get") => {
+    [k: string]: "run_context" | "runs_get";
+};
 /** Total TTR: entry into `resumeHook()` → immediately before `stepFn.apply()`. */
 export declare const ResumeTotalMs: (value: number) => {
     [k: string]: number;

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

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

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

@@ -1 +1 @@
-import{Dr as e,Er as t,Ir as n,Nr as r,Or as i,Pr as a,Rr as o,ar as s,or as c,t as l,xr as u}from"../../_chunks/workflow/attribute-changes-C6H-fRVP.js";import{i as d,u as f}from"../../_chunks/workflow/dist-xTushGCp.js";import{i as p}from"../../_chunks/workflow/workflow-routes-CwqB063q.js";import{t as m}from"../../_chunks/workflow/sleep-6cG0F99-.js";import{t as h}from"../../_chunks/workflow/run-BM2OFphk.js";c(s,h);function g(e){let n=globalThis[t];return n||a(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,g),n(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:s}=o();return a.url=p(s,{type:`webhook`,token:a.token}),a}function v(){function e(t,r){n(`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=l(e,t);if(n.length===0)return;let r=t.allowReservedAttributes===!0,a=globalThis[i];if(!a)throw new d("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(t={}){let{namespace:n}=t,r=globalThis[e](n);return Object.create(globalThis.WritableStream.prototype,{[u]:{value:r,writable:!1}})}function x(){r(`getStepMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-step-metadata`,x)}function S(){n(`resumeHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow-api/resume-hook`,S)}export{d as FatalError,f as RetryableError,g as createHook,_ as createWebhook,v as defineHook,x as getStepMetadata,o as getWorkflowMetadata,b as getWritable,S as resumeHook,y as setAttributes,m as sleep};
+import{Br as e,Fr as t,Gr as n,Nr as r,Or as i,Pr as a,Ur as o,Vr as s,dr as c,fr as l,t as u}from"../../_chunks/workflow/attribute-changes-BAcgmlXp.js";import{i as d,u as f}from"../../_chunks/workflow/dist-xTushGCp.js";import{i as p}from"../../_chunks/workflow/workflow-routes-CwqB063q.js";import{t as m}from"../../_chunks/workflow/sleep-BB2HuVie.js";import{t as h}from"../../_chunks/workflow/run-ChHLjaCt.js";l(c,h);function g(e){let t=globalThis[r];return t||s(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,g),t(e)}function _(e){let{respondWith:t,token:r,...i}=e??{};if(r!==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 a;t!==void 0&&(a={respondWith:t});let o=g({...i,metadata:a,isWebhook:!0}),{url:s}=n();return o.url=p(s,{type:`webhook`,token:o.token}),o}function v(){function e(t,n){o(`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,n={}){let r=u(e,n);if(r.length===0)return;let i=n.allowReservedAttributes===!0,a=globalThis[t];if(!a)throw new d("setAttributes() called outside a workflow runtime context. It must be called from within a workflow body (`use workflow`).");await a(r,i?{allowReservedAttributes:!0}:{})}function b(e={}){let{namespace:t}=e,n=globalThis[a](t);return Object.create(globalThis.WritableStream.prototype,{[i]:{value:n,writable:!1}})}function x(){e(`getStepMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-step-metadata`,x)}function S(){o(`resumeHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow-api/resume-hook`,S)}export{d as FatalError,f as RetryableError,g as createHook,_ as createWebhook,v as defineHook,x as getStepMetadata,n as getWorkflowMetadata,b as getWritable,S as resumeHook,y as setAttributes,m as sleep};

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

@@ -13,10 +13,10 @@ export declare const AnalyticsRunSchema: z.ZodObject<{
     workflowName: z.ZodString;
     specVersion: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
     attributes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
-    createdAt: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>;
-    updatedAt: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>;
-    startedAt: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>>>;
-    completedAt: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>>>;
+    createdAt: z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>;
+    updatedAt: z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>;
+    startedAt: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>>>;
+    completedAt: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>>>;
     errorCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     workflowCoreVersion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     workflowEncryptionEnabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
@@ -33,11 +33,11 @@ export declare const AnalyticsStepSchema: z.ZodObject<{
         cancelled: "cancelled";
     }>;
     attempt: z.ZodOptional<z.ZodNumber>;
-    createdAt: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>;
-    updatedAt: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>;
-    startedAt: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>>>;
-    completedAt: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>>>;
-    retryAfter: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>>>;
+    createdAt: z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>;
+    updatedAt: z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>;
+    startedAt: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>>>;
+    completedAt: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>>>;
+    retryAfter: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>>>;
     errorCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     workflowCoreVersion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     workflowEncryptionEnabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
@@ -72,14 +72,14 @@ export declare const AnalyticsEventSchema: z.ZodObject<{
     workflowName: z.ZodString;
     deploymentId: z.ZodString;
     specVersion: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
-    runCreatedAt: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>;
-    createdAt: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>;
+    runCreatedAt: z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>;
+    createdAt: z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>;
     region: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     vercelId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     requestId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     computeInstanceId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    resumeAt: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>>>;
-    retryAfter: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>>>;
+    resumeAt: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>>>;
+    retryAfter: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>>>;
     errorCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     workflowCoreVersion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     isWebhook: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
@@ -95,10 +95,10 @@ export declare const AnalyticsHookSchema: z.ZodObject<{
         disposed: "disposed";
         conflict: "conflict";
     }>;
-    createdAt: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>;
-    updatedAt: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>;
-    receivedAt: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>>>;
-    disposedAt: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>>>;
+    createdAt: z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>;
+    updatedAt: z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>;
+    receivedAt: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>>>;
+    disposedAt: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>>>;
     isWebhook: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     isSystem: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     workflowCoreVersion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -111,18 +111,18 @@ export declare const AnalyticsWaitSchema: z.ZodObject<{
         completed: "completed";
         waiting: "waiting";
     }>;
-    resumeAt: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>>>;
-    createdAt: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>;
-    updatedAt: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>;
-    completedAt: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>>>;
+    resumeAt: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>>>;
+    createdAt: z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>;
+    updatedAt: z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>;
+    completedAt: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>>>;
     workflowCoreVersion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     workflowEncryptionEnabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
 }, z.core.$strip>;
 export declare const AnalyticsAttributeKeySchema: z.ZodObject<{
     key: z.ZodString;
     runCount: z.ZodCoercedNumber<unknown>;
-    firstSeenAt: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>;
-    lastSeenAt: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodCoercedDate<unknown>>;
+    firstSeenAt: z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>;
+    lastSeenAt: z.ZodPreprocess<z.ZodCoercedDate<unknown>, unknown>;
 }, z.core.$strip>;
 export type AnalyticsRun = z.infer<typeof AnalyticsRunSchema>;
 export type AnalyticsStep = z.infer<typeof AnalyticsStepSchema>;

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

@@ -622,8 +622,10 @@ export interface CreateEventParams {
     /**
      * 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. Sent by
-     * every replay-context create; omitted by callers with no loaded log to be
-     * stale against.
+     * 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 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

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

@@ -89,6 +89,25 @@ export declare const StepDispatchInputSchema: z.ZodObject<{
     input: z.ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>;
 }, z.core.$strip>;
 export type StepDispatchInput = z.infer<typeof StepDispatchInputSchema>;
+/**
+ * Immutable run identity carried on a step-execution message so the consumer
+ * can start the step without a blocking `runs.get` round trip. Every field is
+ * fixed for the life of a run (runs are pinned to their deployment), and the
+ * producer holds the run row at dispatch time, so the copy can never go
+ * stale. Run *status* is deliberately NOT carried: liveness is enforced by
+ * the `step_started` claim itself, which the World rejects on a terminal run.
+ *
+ * Consumers that need the full run row for inline replay
+ * still fetch it lazily; messages without this field (older producers) take
+ * the legacy `runs.get` prologue.
+ */
+export declare const RunDispatchContextSchema: z.ZodObject<{
+    deploymentId: z.ZodString;
+    specVersion: z.ZodNumber;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    rootRunId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RunDispatchContext = z.infer<typeof RunDispatchContextSchema>;
 export declare const HookResumeInputSchema: z.ZodObject<{
     resumeId: z.ZodString;
     hookId: z.ZodString;
@@ -144,6 +163,7 @@ export declare const WorkflowInvokePayloadSchema: z.ZodObject<{
     replayDivergence: z.ZodOptional<z.ZodObject<{
         eventId: z.ZodString;
         count: z.ZodNumber;
+        eventIds: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodString>>>;
     }, z.core.$strip>>;
     preconditionReinvocations: z.ZodOptional<z.ZodNumber>;
     serverErrorRetryCount: z.ZodOptional<z.ZodNumber>;
@@ -175,6 +195,12 @@ export declare const WorkflowInvokePayloadSchema: z.ZodObject<{
     stepInput: z.ZodOptional<z.ZodObject<{
         input: z.ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>;
     }, z.core.$strip>>;
+    runContext: z.ZodOptional<z.ZodObject<{
+        deploymentId: z.ZodString;
+        specVersion: z.ZodNumber;
+        startedAt: z.ZodOptional<z.ZodNumber>;
+        rootRunId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     hookResumeTiming: z.ZodCatch<z.ZodOptional<z.ZodObject<{
         resumeRequestedAtMs: z.ZodNumber;
         queuePublishRequestedAtMs: z.ZodNumber;
@@ -224,6 +250,7 @@ export declare const QueuePayloadSchema: z.ZodUnion<readonly [z.ZodObject<{
     replayDivergence: z.ZodOptional<z.ZodObject<{
         eventId: z.ZodString;
         count: z.ZodNumber;
+        eventIds: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodString>>>;
     }, z.core.$strip>>;
     preconditionReinvocations: z.ZodOptional<z.ZodNumber>;
     serverErrorRetryCount: z.ZodOptional<z.ZodNumber>;
@@ -255,6 +282,12 @@ export declare const QueuePayloadSchema: z.ZodUnion<readonly [z.ZodObject<{
     stepInput: z.ZodOptional<z.ZodObject<{
         input: z.ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>;
     }, z.core.$strip>>;
+    runContext: z.ZodOptional<z.ZodObject<{
+        deploymentId: z.ZodString;
+        specVersion: z.ZodNumber;
+        startedAt: z.ZodOptional<z.ZodNumber>;
+        rootRunId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     hookResumeTiming: z.ZodCatch<z.ZodOptional<z.ZodObject<{
         resumeRequestedAtMs: z.ZodNumber;
         queuePublishRequestedAtMs: z.ZodNumber;
@@ -287,6 +320,23 @@ export interface QueueOptions {
      */
     region?: string;
 }
+/**
+ * Outcome of one message in a {@link Queue.queueBatch} call, in input order.
+ *
+ * `messageId: null` with no `error` means accepted for deferred processing
+ * (the same "accepted, no ID yet" case {@link Queue.queue} reports), so
+ * `error === undefined` is the success test, not a non-null `messageId`.
+ */
+export type QueueBatchResult = {
+    messageId: MessageId | null;
+    error?: undefined;
+} | {
+    messageId: null;
+    /** Human-readable failure description for this message. */
+    error: string;
+    /** Republishing the batch may succeed. */
+    retryable: boolean;
+};
 export interface Queue {
     getDeploymentId(): Promise<string>;
     /**
@@ -305,6 +355,40 @@ export interface Queue {
     queue(queueName: ValidQueueName, message: QueuePayload, opts?: QueueOptions): Promise<{
         messageId: MessageId | null;
     }>;
+    /**
+     * Enqueues several messages to the SAME logical queue in as few round trips
+     * as the backing transport allows. Optional: callers MUST fall back to
+     * per-message {@link Queue.queue} when a World does not implement it.
+     *
+     * Exists for wide fan-outs. Publishing an N-branch `Promise.all` one message
+     * at a time costs N round trips through a bounded connection pool, and that
+     * cost is paid before the fan-out's first step body runs, so it lands
+     * directly on time-to-first-step.
+     *
+     * Contract:
+     *
+     * - Results are returned in input order, one per input message. Returning
+     *   a different number of results than there were messages is a contract
+     *   violation the runtime rejects the whole batch on: an omitted result is
+     *   indistinguishable from a message that was never published, and reading
+     *   it as success would strand that step with no error anywhere.
+     * - Partial failure is normal. A rejected entry reports `error`; a
+     *   `retryable` entry may succeed if the whole batch is published again.
+     *   Implementations MUST NOT throw for a per-entry failure — reserve
+     *   rejection for request-level failures where no entry outcome is known.
+     * - Callers are expected to pass `opts.idempotencyKey` per message, because
+     *   the recovery for both a request-level failure and a retryable entry is
+     *   to republish the batch: without keys that redelivers the entries that
+     *   already succeeded.
+     * - Every message must target one logical `queueName`. Implementations are
+     *   free to split the batch (by transport cap, or by any per-message routing
+     *   dimension they derive from the payload, such as region or physical
+     *   topic); the split must not be observable in the returned order.
+     */
+    queueBatch?(queueName: ValidQueueName, messages: readonly {
+        message: QueuePayload;
+        opts?: QueueOptions;
+    }[]): Promise<QueueBatchResult[]>;
     /**
      * Creates an HTTP queue handler for processing messages from a specific queue.
      * A rejected handler must retry the same message with an incremented attempt.