@workflow/world-testing 5.0.0-beta.47 → 5.0.0-beta.48

package/dist/.well-known/workflow/v1/flow.mjs

@@ -16010,7 +16010,7 @@ var init_runs2 = __esm({
       // Completed state - output can be v1 or v2 format
       WorkflowRunBaseSchema2.extend({
         status: external_exports2.literal("completed"),
-        output: SerializedDataSchema2,
+        output: SerializedDataSchema2.optional(),
         error: external_exports2.undefined().optional(),
         completedAt: external_exports2.coerce.date()
       }),
@@ -16018,7 +16018,7 @@ var init_runs2 = __esm({
       WorkflowRunBaseSchema2.extend({
         status: external_exports2.literal("failed"),
         output: external_exports2.undefined().optional(),
-        error: SerializedDataSchema2,
+        error: SerializedDataSchema2.optional(),
         completedAt: external_exports2.coerce.date()
       })
     ]);
@@ -16158,7 +16158,7 @@ var init_waits2 = __esm({
 });
 
 // ../world/dist/analytics.js
-var NAIVE_DATETIME2, UTCDateSchema2, NullableDateSchema2, NullableStringSchema2, NullableBooleanSchema2, AnalyticsRunSchema2, AnalyticsStepSchema2, AnalyticsEventSchema2, AnalyticsHookSchema2, AnalyticsWaitSchema2, AnalyticsAttributeKeySchema2, ANALYTICS_EVENTS_GET_MANY_LIMIT;
+var NAIVE_DATETIME2, UTCDateSchema2, NullableDateSchema2, NullableStringSchema2, NullableBooleanSchema2, AnalyticsRunSchema2, AnalyticsStepSchema2, AnalyticsEventSchema2, AnalyticsHookSchema2, AnalyticsWaitSchema2, AnalyticsAttributeKeySchema2, ANALYTICS_EVENTS_GET_MANY_LIMIT, ANALYTICS_RUN_SCOPED_PAGE_LIMIT, ANALYTICS_PAGE_LIMIT, ANALYTICS_MAX_ATTRIBUTE_FILTERS;
 var init_analytics2 = __esm({
   "../world/dist/analytics.js"() {
     "use strict";
@@ -16261,10 +16261,13 @@ var init_analytics2 = __esm({
     AnalyticsAttributeKeySchema2 = external_exports2.object({
       key: external_exports2.string(),
       runCount: external_exports2.coerce.number(),
-      firstSeenAt: external_exports2.coerce.date(),
-      lastSeenAt: external_exports2.coerce.date()
+      firstSeenAt: UTCDateSchema2,
+      lastSeenAt: UTCDateSchema2
     });
     ANALYTICS_EVENTS_GET_MANY_LIMIT = 100;
+    ANALYTICS_RUN_SCOPED_PAGE_LIMIT = 1e3;
+    ANALYTICS_PAGE_LIMIT = 100;
+    ANALYTICS_MAX_ATTRIBUTE_FILTERS = 8;
   }
 });
 
@@ -17080,6 +17083,9 @@ var init_ulid2 = __esm({
 var dist_exports = {};
 __export(dist_exports, {
   ANALYTICS_EVENTS_GET_MANY_LIMIT: () => ANALYTICS_EVENTS_GET_MANY_LIMIT,
+  ANALYTICS_MAX_ATTRIBUTE_FILTERS: () => ANALYTICS_MAX_ATTRIBUTE_FILTERS,
+  ANALYTICS_PAGE_LIMIT: () => ANALYTICS_PAGE_LIMIT,
+  ANALYTICS_RUN_SCOPED_PAGE_LIMIT: () => ANALYTICS_RUN_SCOPED_PAGE_LIMIT,
   ATTRIBUTE_KEY_MAX_LENGTH: () => ATTRIBUTE_KEY_MAX_LENGTH2,
   ATTRIBUTE_MAX_PER_RUN: () => ATTRIBUTE_MAX_PER_RUN2,
   ATTRIBUTE_VALUE_MAX_BYTES: () => ATTRIBUTE_VALUE_MAX_BYTES2,
@@ -17244,6 +17250,8 @@ var init_error_codes2 = __esm({
       MAX_EVENTS_EXCEEDED: "MAX_EVENTS_EXCEEDED",
       /** Workflow replay exceeded the maximum allowed duration */
       REPLAY_TIMEOUT: "REPLAY_TIMEOUT",
+      /** Workflow stream infrastructure failed while reading or writing data */
+      STREAM_ERROR: "STREAM_ERROR",
       /** World response violated the SDK contract and cannot be retried safely */
       WORLD_CONTRACT_ERROR: "WORLD_CONTRACT_ERROR",
       /** Run was delivered to a deployment other than the one it is pinned to */
@@ -17279,12 +17287,13 @@ function buildFramedDetails2(hint3, slug) {
     out.push({ label: "docs", value: `${BASE_URL2}/${slug}` });
   return out;
 }
-var BASE_URL2, ERROR_SLUGS2, WorkflowError2, WorkflowWorldError2, WorkflowRunFailedError2, WorkflowRunNotCompletedError2, WorkflowRuntimeError2, CorruptedEventLogError, ReplayDivergenceError, MaxEventsExceededError, RuntimeDecryptionError2, SerializationError2, StepNotRegisteredError2, WorkflowNotRegisteredError2, WorkflowDeploymentMismatchError, WorkflowRunNotFoundError2, HookConflictError2, HookNotFoundError2, EntityConflictError2, RunExpiredError2, StreamExpiredError2, TooEarlyError, ThrottleError2, PreconditionFailedError, WorkflowRunCancelledError2, RunNotSupportedError, FatalError2, RetryableError2, FATAL_ERROR_KEY2, RETRYABLE_ERROR_KEY2, HOOK_CONFLICT_ERROR_KEY2, RUNTIME_DECRYPTION_ERROR_KEY2;
+var BASE_URL2, ERROR_SLUGS2, WorkflowError2, WorkflowWorldError2, WorkflowRunFailedError2, WorkflowRunNotCompletedError2, WorkflowRuntimeError2, CorruptedEventLogError, ReplayDivergenceError, MaxEventsExceededError, RuntimeDecryptionError2, SerializationError2, StepNotRegisteredError2, WorkflowNotRegisteredError2, WorkflowDeploymentMismatchError, WorkflowRunNotFoundError2, HookConflictError2, HookNotFoundError2, EntityConflictError2, RunExpiredError2, StreamError2, StreamExpiredError2, TooEarlyError, ThrottleError2, PreconditionFailedError, WorkflowRunCancelledError2, RunNotSupportedError, FatalError2, RetryableError2, FATAL_ERROR_KEY2, RETRYABLE_ERROR_KEY2, HOOK_CONFLICT_ERROR_KEY2, RUNTIME_DECRYPTION_ERROR_KEY2, STREAM_ERROR_KEY2;
 var init_dist7 = __esm({
   "../errors/dist/index.js"() {
     "use strict";
     init_dist5();
     init_error_codes2();
+    init_error_codes2();
     BASE_URL2 = "https://workflow-sdk.dev/err";
     __name(isError2, "isError");
     __name(appendFramedDetails2, "appendFramedDetails");
@@ -17334,6 +17343,12 @@ Caused by: ${options.cause.stack}`;
       url;
       /** Retry-After value in seconds, present on 429 and 425 responses */
       retryAfter;
+      /**
+       * The offending argument, present on client-side validation failures
+       * (`code: 'INVALID_ARGUMENT'`). Lets a caller correct the specific
+       * parameter without parsing the message.
+       */
+      field;
       constructor(message, options) {
         super(message, {
           cause: options?.cause
@@ -17343,6 +17358,7 @@ Caused by: ${options.cause.stack}`;
         this.code = options?.code;
         this.url = options?.url;
         this.retryAfter = options?.retryAfter;
+        this.field = options?.field;
       }
       static is(value) {
         return isError2(value) && value.name === "WorkflowWorldError";
@@ -17622,6 +17638,23 @@ Caused by: ${options.cause.stack}`;
         return isError2(value) && value.name === "RunExpiredError";
       }
     };
+    StreamError2 = class extends WorkflowWorldError2 {
+      static {
+        __name(this, "StreamError");
+      }
+      constructor(message, options) {
+        super(message, {
+          code: RUN_ERROR_CODES2.STREAM_ERROR,
+          cause: options?.cause,
+          url: options?.url,
+          status: options?.status
+        });
+        this.name = "StreamError";
+      }
+      static is(value) {
+        return isError2(value) && value.name === "StreamError";
+      }
+    };
     StreamExpiredError2 = class extends WorkflowWorldError2 {
       static {
         __name(this, "StreamExpiredError");
@@ -17752,6 +17785,7 @@ Caused by: ${options.cause.stack}`;
     RETRYABLE_ERROR_KEY2 = /* @__PURE__ */ Symbol.for("@workflow/errors//RetryableError");
     HOOK_CONFLICT_ERROR_KEY2 = /* @__PURE__ */ Symbol.for("@workflow/errors//HookConflictError");
     RUNTIME_DECRYPTION_ERROR_KEY2 = /* @__PURE__ */ Symbol.for("@workflow/errors//RuntimeDecryptionError");
+    STREAM_ERROR_KEY2 = /* @__PURE__ */ Symbol.for("@workflow/errors//StreamError");
     if (typeof globalThis !== "undefined") {
       if (!Object.hasOwn(globalThis, FATAL_ERROR_KEY2)) {
         Object.defineProperty(globalThis, FATAL_ERROR_KEY2, {
@@ -17785,6 +17819,14 @@ Caused by: ${options.cause.stack}`;
           configurable: false
         });
       }
+      if (!Object.hasOwn(globalThis, STREAM_ERROR_KEY2)) {
+        Object.defineProperty(globalThis, STREAM_ERROR_KEY2, {
+          value: StreamError2,
+          writable: false,
+          enumerable: false,
+          configurable: false
+        });
+      }
     }
   }
 });
@@ -51455,12 +51497,24 @@ function createEventsStorage(basedir, tag) {
             };
             const storedConflict = await storeEvent(conflictEvent);
             const resolveData2 = params?.resolveData ?? DEFAULT_RESOLVE_DATA_OPTION;
-            return {
+            const conflictDelta = typeof params?.sinceCursor === "string" ? await queryRunEvents(effectiveRunId, {
+              sortOrder: "asc",
+              cursor: params.sinceCursor
+            }) : void 0;
+            const conflictResult = {
               event: stripEventDataRefs(storedConflict, resolveData2),
               run: run3,
               step,
               hook: void 0
             };
+            if (!conflictDelta)
+              return conflictResult;
+            return {
+              ...conflictResult,
+              events: resolveData2 === "none" ? conflictDelta.data.map((delta) => stripEventDataRefs(delta, resolveData2)) : conflictDelta.data,
+              cursor: conflictDelta.cursor,
+              hasMore: conflictDelta.hasMore
+            };
           }
           const persistedHookData = event.eventData;
           hook = {
@@ -56155,7 +56209,7 @@ var version4;
 var init_version3 = __esm({
   "../world-vercel/dist/version.js"() {
     "use strict";
-    version4 = "5.0.0-beta.43";
+    version4 = "5.0.0-beta.44";
   }
 });
 
@@ -56576,6 +56630,17 @@ var init_telemetry3 = __esm({
 });
 
 // ../world-vercel/dist/http-core.js
+function getTransientTransportCode(error95) {
+  let current = error95;
+  for (let depth = 0; current && depth < 8; depth++) {
+    const code3 = current.code;
+    if (typeof code3 === "string" && TRANSIENT_TRANSPORT_ERROR_CODES.has(code3)) {
+      return code3;
+    }
+    current = current.cause;
+  }
+  return void 0;
+}
 function getVercelDiagnostics(headers) {
   return DIAGNOSTIC_HEADERS.flatMap((header) => {
     const value = headers.get(header);
@@ -56698,7 +56763,7 @@ function recordClientSpanStatus(span, status) {
   }
 }
 async function instrumentedFetch(opts) {
-  const { method, url: url3, headers, body, dispatcher, peerService, timeoutMs = getRequestTimeoutMs(), signal: callerSignal, injectTraceContext: injectTraceContext2 = true, cacheBust = true, logLabel, buildError, spanName, attributes, durationAttribute, onTransportOutcome } = opts;
+  const { method, url: url3, headers, body, dispatcher, peerService, timeoutMs = getRequestTimeoutMs(), signal: callerSignal, injectTraceContext: injectTraceContext2 = true, cacheBust = true, logLabel, buildError, spanName, attributes, durationAttribute, onTransportOutcome, deferTransportSuccessUntilBody = false, transportErrorCode = "TRANSPORT" } = opts;
   const label = logLabel ?? url3;
   return withHttpClientSpan({ method, url: url3, peerService, spanName, attributes }, async (span) => {
     if (injectTraceContext2)
@@ -56738,15 +56803,36 @@ async function instrumentedFetch(opts) {
       const elapsed = Date.now() - start3;
       onTransportOutcome?.(error95);
       if (error95 instanceof Error && (error95.name === "TimeoutError" || error95.name === "AbortError")) {
-        const timeoutError = new WorkflowWorldError2(`${method} ${label} timed out after ${elapsed}ms`, { url: url3, cause: error95 });
-        span?.setAttributes({ ...ErrorType2("TIMEOUT") });
+        const message = `${method} ${label} timed out after ${elapsed}ms`;
+        const errorCode = transportErrorCode === "STREAM_ERROR" ? "STREAM_ERROR" : "TIMEOUT";
+        const timeoutError = errorCode === "STREAM_ERROR" ? new StreamError2(message, { url: url3, cause: error95 }) : new WorkflowWorldError2(message, {
+          url: url3,
+          code: errorCode,
+          cause: error95
+        });
+        span?.setAttributes({ ...ErrorType2(errorCode) });
         span?.recordException?.(timeoutError);
         throw timeoutError;
       }
+      const transportCode = getTransientTransportCode(error95);
+      if (transportCode) {
+        const message = `${method} ${label} transport failure after ${elapsed}ms (${transportCode})`;
+        const errorCode = transportErrorCode === "STREAM_ERROR" ? "STREAM_ERROR" : "TRANSPORT";
+        const transportError2 = errorCode === "STREAM_ERROR" ? new StreamError2(message, { url: url3, cause: error95 }) : new WorkflowWorldError2(message, {
+          url: url3,
+          code: errorCode,
+          cause: error95
+        });
+        span?.setAttributes({ ...ErrorType2(errorCode) });
+        span?.recordException?.(transportError2);
+        throw transportError2;
+      }
       throw error95;
     }
     const ms3 = Date.now() - start3;
-    onTransportOutcome?.();
+    if (response.ok && !deferTransportSuccessUntilBody) {
+      onTransportOutcome?.(void 0, response);
+    }
     httpLog(method, label, response, ms3);
     recordClientSpanStatus(span, response.status);
     if (durationAttribute)
@@ -56754,11 +56840,37 @@ async function instrumentedFetch(opts) {
     if (!response.ok) {
       logCurlRepro(method, url3, headers);
       if (buildError) {
-        const error96 = await buildError(response);
+        let error96;
+        try {
+          error96 = await buildError(response);
+        } catch (cause) {
+          const transportCode = getTransientTransportCode(cause);
+          if (transportCode) {
+            onTransportOutcome?.(cause, response);
+            const message = `${method} ${label} response body transport failure (${transportCode})`;
+            const mappedError = transportErrorCode === "STREAM_ERROR" ? new StreamError2(message, { url: url3, cause }) : new WorkflowWorldError2(message, {
+              url: url3,
+              code: "TRANSPORT",
+              cause
+            });
+            span?.setAttributes({ ...ErrorType2(transportErrorCode) });
+            span?.recordException?.(mappedError);
+            throw mappedError;
+          }
+          onTransportOutcome?.(void 0, response);
+          throw cause;
+        }
+        onTransportOutcome?.(void 0, response);
         span?.recordException?.(error96);
         throw error96;
       }
-      const text = await response.text().catch(() => "");
+      let text = "";
+      try {
+        text = await response.text();
+        onTransportOutcome?.(void 0, response);
+      } catch (cause) {
+        onTransportOutcome?.(cause, response);
+      }
       const error95 = errorForResponse(response.status, `${method} ${label} -> HTTP ${response.status}: ${response.statusText}${text ? ` ${text}` : ""}${formatVercelDiagnostics(response.headers)}`, {
         url: url3,
         retryAfter: parseRetryAfter(response.headers.get("Retry-After"))
@@ -56769,7 +56881,7 @@ async function instrumentedFetch(opts) {
     return response;
   });
 }
-var import_oidc, REQUEST_TIMEOUT_MS, getRequestTimeoutMs, HTTP_DEBUG_ENABLED, DIAGNOSTIC_HEADERS;
+var import_oidc, REQUEST_TIMEOUT_MS, TRANSIENT_TRANSPORT_ERROR_CODES, getRequestTimeoutMs, HTTP_DEBUG_ENABLED, DIAGNOSTIC_HEADERS;
 var init_http_core = __esm({
   "../world-vercel/dist/http-core.js"() {
     "use strict";
@@ -56780,6 +56892,23 @@ var init_http_core = __esm({
     init_http_client();
     init_telemetry3();
     REQUEST_TIMEOUT_MS = 6e4;
+    TRANSIENT_TRANSPORT_ERROR_CODES = /* @__PURE__ */ new Set([
+      "UND_ERR_INFO",
+      "UND_ERR_REQ_RETRY",
+      "UND_ERR_SOCKET",
+      "UND_ERR_CONNECT",
+      "UND_ERR_CONNECT_TIMEOUT",
+      "UND_ERR_HEADERS_TIMEOUT",
+      "UND_ERR_BODY_TIMEOUT",
+      "UND_ERR_CLOSED",
+      "ECONNRESET",
+      "ECONNREFUSED",
+      "ENOTFOUND",
+      "EAI_AGAIN",
+      "EPIPE",
+      "ETIMEDOUT"
+    ]);
+    __name(getTransientTransportCode, "getTransientTransportCode");
     getRequestTimeoutMs = /* @__PURE__ */ __name(() => envNumber2("WORKFLOW_REQUEST_TIMEOUT_MS", REQUEST_TIMEOUT_MS, {
       integer: true,
       min: 1e4,
@@ -56811,19 +56940,6 @@ var init_http_core = __esm({
 // ../world-vercel/dist/utils.js
 import os from "node:os";
 import { inspect } from "node:util";
-function getTransientTransportCode(error95) {
-  let current = error95;
-  for (let depth = 0; current != null && depth < 5; depth++) {
-    if (typeof current === "object" && "code" in current) {
-      const code3 = current.code;
-      if (typeof code3 === "string" && TRANSIENT_TRANSPORT_ERROR_CODES.has(code3)) {
-        return code3;
-      }
-    }
-    current = current?.cause;
-  }
-  return void 0;
-}
 function deserializeError(obj) {
   return obj;
 }
@@ -57009,7 +57125,7 @@ async function parseResponseBody(response) {
     getDebugContext: /* @__PURE__ */ __name(() => `Content-Type: ${contentType}, ${text.length} bytes, preview: ${createPreview(data)}`, "getDebugContext")
   };
 }
-var import_oidc2, WORKFLOW_SERVER_URL_OVERRIDE, IDEMPOTENT_METHODS, MAX_BODY_PARSE_RETRIES, BODY_PARSE_RETRY_BASE_MS, TRANSIENT_TRANSPORT_ERROR_CODES, getWorkflowServerUrlOverride, TEST_LIMIT_OVERRIDES_HEADER, getTestLimitOverridesHeader, DEFAULT_RESOLVE_DATA_OPTION2, joinUserAgentProducts, getUserAgent, getHttpUrl, resolveClientEnvironment, getHeaders, MAX_PREVIEW_LENGTH;
+var import_oidc2, WORKFLOW_SERVER_URL_OVERRIDE, IDEMPOTENT_METHODS, MAX_BODY_PARSE_RETRIES, BODY_PARSE_RETRY_BASE_MS, getWorkflowServerUrlOverride, TEST_LIMIT_OVERRIDES_HEADER, getTestLimitOverridesHeader, DEFAULT_RESOLVE_DATA_OPTION2, joinUserAgentProducts, getUserAgent, getHttpUrl, resolveClientEnvironment, getHeaders, MAX_PREVIEW_LENGTH;
 var init_utils4 = __esm({
   "../world-vercel/dist/utils.js"() {
     "use strict";
@@ -57025,22 +57141,6 @@ var init_utils4 = __esm({
     IDEMPOTENT_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD"]);
     MAX_BODY_PARSE_RETRIES = 2;
     BODY_PARSE_RETRY_BASE_MS = 100;
-    TRANSIENT_TRANSPORT_ERROR_CODES = /* @__PURE__ */ new Set([
-      "UND_ERR_REQ_RETRY",
-      "UND_ERR_SOCKET",
-      "UND_ERR_CONNECT",
-      "UND_ERR_CONNECT_TIMEOUT",
-      "UND_ERR_HEADERS_TIMEOUT",
-      "UND_ERR_BODY_TIMEOUT",
-      "UND_ERR_CLOSED",
-      "ECONNRESET",
-      "ECONNREFUSED",
-      "ENOTFOUND",
-      "EAI_AGAIN",
-      "EPIPE",
-      "ETIMEDOUT"
-    ]);
-    __name(getTransientTransportCode, "getTransientTransportCode");
     getWorkflowServerUrlOverride = /* @__PURE__ */ __name(() => WORKFLOW_SERVER_URL_OVERRIDE || process.env.VERCEL_WORKFLOW_SERVER_URL || "", "getWorkflowServerUrlOverride");
     TEST_LIMIT_OVERRIDES_HEADER = "x-workflow-test-limit-overrides";
     getTestLimitOverridesHeader = /* @__PURE__ */ __name(() => process.env.WORKFLOW_TEST_LIMIT_OVERRIDES?.trim() || "", "getTestLimitOverridesHeader");
@@ -57106,9 +57206,86 @@ var init_utils4 = __esm({
 });
 
 // ../world-vercel/dist/analytics.js
-function appendPagination(params, pagination) {
-  if (pagination?.limit)
+function invalidArgument(method, field, detail) {
+  return new WorkflowWorldError2(`${method}: ${field} ${detail}`, {
+    code: INVALID_ARGUMENT,
+    field
+  });
+}
+function assertPageLimit(method, limit, maxLimit) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > maxLimit) {
+    throw invalidArgument(method, "pagination.limit", `must be an integer between 1 and ${maxLimit} (received ${limit})`);
+  }
+}
+function assertRunId(method, runId) {
+  if (!RUN_ID_PATTERN.test(runId)) {
+    throw invalidArgument(method, "runId", `must be a workflow run id ('wrun_' followed by a ULID), received ${JSON.stringify(runId)}`);
+  }
+}
+function assertCorrelationId(method, correlationId) {
+  if (!CORRELATION_ID_PATTERN.test(correlationId)) {
+    throw invalidArgument(method, "correlationId", `must be a step, hook, wait, or attribute id, received ${JSON.stringify(correlationId)}`);
+  }
+}
+function assertEventId(method, eventId) {
+  if (!EVENT_ID_PATTERN.test(eventId)) {
+    throw invalidArgument(method, "eventId", `must be an event id ('evnt_' followed by a ULID), received ${JSON.stringify(eventId)}`);
+  }
+}
+function assertStepId(method, stepId) {
+  if (!STEP_ID_PATTERN.test(stepId)) {
+    throw invalidArgument(method, "stepId", `must be a step id ('step_' followed by a ULID), received ${JSON.stringify(stepId)}`);
+  }
+}
+function assertHookId(method, hookId) {
+  if (!HOOK_ID_PATTERN.test(hookId)) {
+    throw invalidArgument(method, "hookId", `must be a hook id ('hook_' followed by a ULID), received ${JSON.stringify(hookId)}`);
+  }
+}
+function assertWaitId(method, waitId) {
+  if (!WAIT_ID_PATTERN.test(waitId)) {
+    throw invalidArgument(method, "waitId", `must be a wait id ('wait_' followed by a ULID), received ${JSON.stringify(waitId)}`);
+  }
+}
+function assertAttributeFilters(method, attributes) {
+  const entries = Object.entries(attributes);
+  if (entries.length > ANALYTICS_MAX_ATTRIBUTE_FILTERS) {
+    throw invalidArgument(method, "attributes", `may filter by at most ${ANALYTICS_MAX_ATTRIBUTE_FILTERS} pairs (received ${entries.length})`);
+  }
+  for (const [key, value] of entries) {
+    if (!AttributeKeySchema2.safeParse(key).success) {
+      throw invalidArgument(method, "attributes", `key must be 1 to ${ATTRIBUTE_KEY_MAX_LENGTH2} characters, received ${key.length} in ${JSON.stringify(key)}`);
+    }
+    if (!AttributeValueSchema2.safeParse(value).success) {
+      throw invalidArgument(method, "attributes", `value for ${JSON.stringify(key)} must be at most ${ATTRIBUTE_VALUE_MAX_BYTES2} UTF-8 bytes (received ${new TextEncoder().encode(value).length})`);
+    }
+  }
+}
+function assertDateWindow(method, startTime, endTime) {
+  if (startTime === void 0 && endTime === void 0)
+    return;
+  if (startTime === void 0 || endTime === void 0) {
+    const given = startTime === void 0 ? "endTime" : "startTime";
+    const missing = startTime === void 0 ? "startTime" : "endTime";
+    throw invalidArgument(method, missing, `is required when ${given} is provided; supply both or neither`);
+  }
+  const start3 = new Date(startTime).getTime();
+  const end = new Date(endTime).getTime();
+  if (!Number.isFinite(start3)) {
+    throw invalidArgument(method, "startTime", `must be a parseable datetime, received ${JSON.stringify(startTime)}`);
+  }
+  if (!Number.isFinite(end)) {
+    throw invalidArgument(method, "endTime", `must be a parseable datetime, received ${JSON.stringify(endTime)}`);
+  }
+  if (start3 > end) {
+    throw invalidArgument(method, "startTime", `must be before or equal to endTime (received startTime=${JSON.stringify(startTime)}, endTime=${JSON.stringify(endTime)})`);
+  }
+}
+function appendPagination(method, params, pagination, maxLimit) {
+  if (pagination?.limit !== void 0) {
+    assertPageLimit(method, pagination.limit, maxLimit);
     params.set("limit", pagination.limit.toString());
+  }
   if (pagination?.cursor)
     params.set("cursor", pagination.cursor);
   if (pagination?.sortOrder)
@@ -57118,30 +57295,34 @@ function createQueryString(params) {
   const query = params.toString();
   return query ? `?${query}` : "";
 }
-function normalizeEventIds(eventIds) {
+function normalizeEventIds(method, eventIds) {
   const uniqueEventIds = [...new Set(eventIds)];
   if (uniqueEventIds.length === 0) {
-    throw new RangeError("eventIds must contain at least one event ID");
+    throw invalidArgument(method, "eventIds", "must contain at least one id");
   }
   if (uniqueEventIds.length > ANALYTICS_EVENTS_GET_MANY_LIMIT) {
-    throw new RangeError(`eventIds must contain at most ${ANALYTICS_EVENTS_GET_MANY_LIMIT} unique event IDs`);
+    throw invalidArgument(method, "eventIds", `must contain at most ${ANALYTICS_EVENTS_GET_MANY_LIMIT} unique ids (received ${uniqueEventIds.length})`);
   }
+  for (const eventId of uniqueEventIds)
+    assertEventId(method, eventId);
   return uniqueEventIds;
 }
-function appendAttributeListParams(searchParams, params) {
-  if (params.workflowName) {
+function appendAttributeListParams(method, searchParams, params) {
+  assertDateWindow(method, params.startTime, params.endTime);
+  if (params.workflowName !== void 0) {
     searchParams.set("workflowName", params.workflowName);
   }
-  if (params.startTime && params.endTime) {
+  if (params.startTime !== void 0 && params.endTime !== void 0) {
     searchParams.set("startTime", params.startTime);
     searchParams.set("endTime", params.endTime);
   }
-  appendPagination(searchParams, params.pagination);
+  appendPagination(method, searchParams, params.pagination, ANALYTICS_PAGE_LIMIT);
 }
 function createAnalytics(config4) {
   return {
     runs: {
       get(runId) {
+        assertRunId("analytics.runs.get", runId);
         return makeRequest({
           endpoint: `/v2/analytics/runs/${encodeURIComponent(runId)}`,
           config: config4,
@@ -57149,21 +57330,23 @@ function createAnalytics(config4) {
         });
       },
       list(params = {}) {
+        assertDateWindow("analytics.runs.list", params.startTime, params.endTime);
         const searchParams = new URLSearchParams();
-        if (params.workflowName) {
+        if (params.workflowName !== void 0) {
           searchParams.set("workflowName", params.workflowName);
         }
         if (params.status) {
           searchParams.set("status", params.status);
         }
-        if (params.startTime && params.endTime) {
+        if (params.startTime !== void 0 && params.endTime !== void 0) {
           searchParams.set("startTime", params.startTime);
           searchParams.set("endTime", params.endTime);
         }
         if (params.attributes && Object.keys(params.attributes).length > 0) {
+          assertAttributeFilters("analytics.runs.list", params.attributes);
           searchParams.set("attributes", JSON.stringify(params.attributes));
         }
-        appendPagination(searchParams, params.pagination);
+        appendPagination("analytics.runs.list", searchParams, params.pagination, ANALYTICS_PAGE_LIMIT);
         return makeRequest({
           endpoint: `/v2/analytics/runs${createQueryString(searchParams)}`,
           config: config4,
@@ -57174,7 +57357,7 @@ function createAnalytics(config4) {
     attributes: {
       list(params = {}) {
         const searchParams = new URLSearchParams();
-        appendAttributeListParams(searchParams, params);
+        appendAttributeListParams("analytics.attributes.list", searchParams, params);
         return makeRequest({
           endpoint: `/v2/analytics/attributes${createQueryString(searchParams)}`,
           config: config4,
@@ -57184,6 +57367,8 @@ function createAnalytics(config4) {
     },
     steps: {
       get(runId, stepId) {
+        assertRunId("analytics.steps.get", runId);
+        assertStepId("analytics.steps.get", stepId);
         return makeRequest({
           endpoint: `/v2/analytics/runs/${encodeURIComponent(runId)}/steps/${encodeURIComponent(stepId)}`,
           config: config4,
@@ -57191,8 +57376,9 @@ function createAnalytics(config4) {
         });
       },
       list(params) {
+        assertRunId("analytics.steps.list", params.runId);
         const searchParams = new URLSearchParams();
-        appendPagination(searchParams, params.pagination);
+        appendPagination("analytics.steps.list", searchParams, params.pagination, ANALYTICS_RUN_SCOPED_PAGE_LIMIT);
         return makeRequest({
           endpoint: `/v2/analytics/runs/${encodeURIComponent(params.runId)}/steps${createQueryString(searchParams)}`,
           config: config4,
@@ -57202,6 +57388,8 @@ function createAnalytics(config4) {
     },
     events: {
       get(runId, eventId) {
+        assertRunId("analytics.events.get", runId);
+        assertEventId("analytics.events.get", eventId);
         return makeRequest({
           endpoint: `/v2/analytics/runs/${encodeURIComponent(runId)}/events/${encodeURIComponent(eventId)}`,
           config: config4,
@@ -57209,33 +57397,47 @@ function createAnalytics(config4) {
         });
       },
       getMany(runId, eventIds) {
+        assertRunId("analytics.events.getMany", runId);
         return makeRequest({
           endpoint: `/v2/analytics/runs/${encodeURIComponent(runId)}/events/get-many`,
           options: { method: "POST" },
-          data: { eventIds: normalizeEventIds(eventIds) },
+          data: {
+            eventIds: normalizeEventIds("analytics.events.getMany", eventIds)
+          },
           config: config4,
           schema: AnalyticsEventSchema2.array()
         });
       },
       list(params) {
+        assertRunId("analytics.events.list", params.runId);
         const searchParams = new URLSearchParams();
         if (params.eventType) {
           searchParams.set("eventType", params.eventType);
         }
-        if (params.correlationId) {
+        if (params.correlationId !== void 0) {
+          assertCorrelationId("analytics.events.list", params.correlationId);
           searchParams.set("correlationId", params.correlationId);
         }
-        appendPagination(searchParams, params.pagination);
+        appendPagination("analytics.events.list", searchParams, params.pagination, ANALYTICS_RUN_SCOPED_PAGE_LIMIT);
         return makeRequest({
           endpoint: `/v2/analytics/runs/${encodeURIComponent(params.runId)}/events${createQueryString(searchParams)}`,
           config: config4,
           schema: PaginatedResponseSchema(AnalyticsEventSchema2)
         });
       },
+      /**
+       * @deprecated Use `list({ runId, correlationId })`. Kept as its own
+       * implementation rather than delegating: `list` treats
+       * `correlationId` as optional and skips an empty one, where this
+       * method requires it, so a delegation would turn an empty id into an
+       * unfiltered listing of the run.
+       */
       listByCorrelationId(params) {
+        assertRunId("analytics.events.listByCorrelationId", params.runId);
+        assertCorrelationId("analytics.events.listByCorrelationId", params.correlationId);
         const searchParams = new URLSearchParams();
         searchParams.set("correlationId", params.correlationId);
-        appendPagination(searchParams, params.pagination);
+        appendPagination("analytics.events.listByCorrelationId", searchParams, params.pagination, ANALYTICS_RUN_SCOPED_PAGE_LIMIT);
         return makeRequest({
           endpoint: `/v2/analytics/runs/${encodeURIComponent(params.runId)}/events${createQueryString(searchParams)}`,
           config: config4,
@@ -57245,8 +57447,10 @@ function createAnalytics(config4) {
     },
     hooks: {
       get(hookId, params) {
+        assertHookId("analytics.hooks.get", hookId);
         const searchParams = new URLSearchParams();
-        if (params?.runId) {
+        if (params?.runId !== void 0) {
+          assertRunId("analytics.hooks.get", params.runId);
           searchParams.set("runId", params.runId);
         }
         return makeRequest({
@@ -57256,9 +57460,10 @@ function createAnalytics(config4) {
         });
       },
       list(params) {
+        assertRunId("analytics.hooks.list", params.runId);
         const searchParams = new URLSearchParams();
         searchParams.set("runId", params.runId);
-        appendPagination(searchParams, params.pagination);
+        appendPagination("analytics.hooks.list", searchParams, params.pagination, ANALYTICS_PAGE_LIMIT);
         return makeRequest({
           endpoint: `/v2/analytics/hooks${createQueryString(searchParams)}`,
           config: config4,
@@ -57268,6 +57473,8 @@ function createAnalytics(config4) {
     },
     waits: {
       get(runId, waitId) {
+        assertRunId("analytics.waits.get", runId);
+        assertWaitId("analytics.waits.get", waitId);
         return makeRequest({
           endpoint: `/v2/analytics/runs/${encodeURIComponent(runId)}/waits/${encodeURIComponent(waitId)}`,
           config: config4,
@@ -57275,11 +57482,12 @@ function createAnalytics(config4) {
         });
       },
       list(params) {
+        assertRunId("analytics.waits.list", params.runId);
         const searchParams = new URLSearchParams();
         if (params.status) {
           searchParams.set("status", params.status);
         }
-        appendPagination(searchParams, params.pagination);
+        appendPagination("analytics.waits.list", searchParams, params.pagination, ANALYTICS_RUN_SCOPED_PAGE_LIMIT);
         return makeRequest({
           endpoint: `/v2/analytics/runs/${encodeURIComponent(params.runId)}/waits${createQueryString(searchParams)}`,
           config: config4,
@@ -57289,11 +57497,31 @@ function createAnalytics(config4) {
     }
   };
 }
+var INVALID_ARGUMENT, ULID_BODY, RUN_ID_PATTERN, CORRELATION_ID_PATTERN, EVENT_ID_PATTERN, STEP_ID_PATTERN, HOOK_ID_PATTERN, WAIT_ID_PATTERN;
 var init_analytics3 = __esm({
   "../world-vercel/dist/analytics.js"() {
     "use strict";
+    init_dist7();
     init_dist6();
     init_utils4();
+    INVALID_ARGUMENT = "INVALID_ARGUMENT";
+    __name(invalidArgument, "invalidArgument");
+    ULID_BODY = "[01234567][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{25}";
+    RUN_ID_PATTERN = new RegExp(`^wrun_${ULID_BODY}$`);
+    CORRELATION_ID_PATTERN = new RegExp(`^(?:step|hook|wait|attr)_${ULID_BODY}$`);
+    EVENT_ID_PATTERN = new RegExp(`^evnt_${ULID_BODY}$`);
+    STEP_ID_PATTERN = new RegExp(`^step_${ULID_BODY}$`);
+    HOOK_ID_PATTERN = new RegExp(`^hook_${ULID_BODY}$`);
+    WAIT_ID_PATTERN = new RegExp(`^wait_${ULID_BODY}$`);
+    __name(assertPageLimit, "assertPageLimit");
+    __name(assertRunId, "assertRunId");
+    __name(assertCorrelationId, "assertCorrelationId");
+    __name(assertEventId, "assertEventId");
+    __name(assertStepId, "assertStepId");
+    __name(assertHookId, "assertHookId");
+    __name(assertWaitId, "assertWaitId");
+    __name(assertAttributeFilters, "assertAttributeFilters");
+    __name(assertDateWindow, "assertDateWindow");
     __name(appendPagination, "appendPagination");
     __name(createQueryString, "createQueryString");
     __name(normalizeEventIds, "normalizeEventIds");
@@ -69227,7 +69455,7 @@ var init_steps3 = __esm({
 import assert4 from "node:assert/strict";
 async function fetchV4(url3, init, config4, opName, attributes) {
   const dispatcher = getEventsDispatcher(config4);
-  return instrumentedFetch({
+  const response = await instrumentedFetch({
     method: init.method,
     url: url3,
     headers: init.headers,
@@ -69239,11 +69467,44 @@ async function fetchV4(url3, init, config4, opName, attributes) {
     // service indefinitely, so without this every request routed onto it fails
     // until the compute instance is recycled. See noteEventsTransportOutcome.
     onTransportOutcome: /* @__PURE__ */ __name((error95) => noteEventsTransportOutcome(dispatcher, error95), "onTransportOutcome"),
+    deferTransportSuccessUntilBody: true,
     timeoutMs: null,
+    transportErrorCode: "STREAM_ERROR",
     logLabel: opName,
     // Read the body as bytes, not text: a CBOR error body (the fence 412
     // carries event payloads back) does not survive a UTF-8 decode.
-    buildError: /* @__PURE__ */ __name(async (response) => errorFromV4Response(response.status, headersToRecord(response.headers), new Uint8Array(await response.arrayBuffer()), opName, url3), "buildError")
+    buildError: /* @__PURE__ */ __name(async (response2) => errorFromV4Response(response2.status, headersToRecord(response2.headers), new Uint8Array(await response2.arrayBuffer()), opName, url3), "buildError")
+  });
+  if (!response.body) {
+    noteEventsTransportOutcome(dispatcher);
+    return response;
+  }
+  const reader = response.body.getReader();
+  const body = new ReadableStream({
+    async pull(controller) {
+      try {
+        const chunk = await reader.read();
+        if (chunk.done) {
+          noteEventsTransportOutcome(dispatcher);
+          controller.close();
+        } else {
+          controller.enqueue(chunk.value);
+        }
+      } catch (cause) {
+        noteEventsTransportOutcome(dispatcher, cause);
+        const transportCode = getTransientTransportCode(cause);
+        controller.error(transportCode ? new StreamError2(`v4 ${opName}: response stream transport failure (${transportCode})`, { cause, url: url3 }) : cause);
+      }
+    },
+    cancel(reason) {
+      noteEventsTransportOutcome(dispatcher);
+      return reader.cancel(reason);
+    }
+  });
+  return new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers
   });
 }
 function eventsV4Url(baseUrl, runId, eventType) {
@@ -69495,6 +69756,8 @@ async function decodeCreateEventResponse(response, eventType) {
   try {
     bodyBytes = new Uint8Array(await response.arrayBuffer());
   } catch (cause) {
+    if (StreamError2.is(cause))
+      throw cause;
     throw new WorkflowWorldError2("v4 createEvent: failed to read response body", { code: "TRANSPORT", cause });
   }
   if (bodyBytes.byteLength === 0) {
@@ -69687,14 +69950,21 @@ async function getEventV4(runId, eventId, remoteRefBehavior, config4) {
     throw new Error(`v4 getEvent: expected ${V4_FRAME_CONTENT_TYPE}, got ${contentType ?? "(none)"}`);
   }
   const chunks = response.body;
-  for await (const frame3 of decodeFrames(chunks)) {
-    if (frame3.meta._error === 1) {
-      throw streamErrorFrameToError(frame3.meta, "getEvent");
+  try {
+    for await (const frame3 of decodeFrames(chunks)) {
+      if (frame3.meta._error === 1) {
+        throw streamErrorFrameToError(frame3.meta, "getEvent");
+      }
+      if (Object.keys(frame3.meta).some((key) => key.startsWith("_"))) {
+        throw new Error("v4 getEvent: unexpected control frame");
+      }
+      return decodeEventFrame(frame3);
     }
-    if (Object.keys(frame3.meta).some((key) => key.startsWith("_"))) {
-      throw new Error("v4 getEvent: unexpected control frame");
+  } catch (cause) {
+    if (cause instanceof IncompleteFrameError && StreamError2.is(cause.cause)) {
+      throw cause.cause;
     }
-    return decodeEventFrame(frame3);
+    throw cause;
   }
   throw new Error(`v4 getEvent: empty frame stream for ${eventId}`);
 }
@@ -69762,6 +70032,9 @@ async function consumeEventFrameStream(response, opName, replayEventObserver) {
     if (cause instanceof ReplayEventObserverError || CorruptedEventLogError.is(cause) || WorkflowWorldError2.is(cause)) {
       throw cause;
     }
+    if (cause instanceof IncompleteFrameError && StreamError2.is(cause.cause)) {
+      return partialEventFrameStream(events, cause.cause);
+    }
     if (!(cause instanceof IncompleteFrameError)) {
       throw new WorkflowWorldError2(`v4 ${opName}: invalid event frame stream`, {
         code: "SCHEMA_VALIDATION",
@@ -70752,21 +71025,28 @@ function streamSpanAttributes(args) {
 }
 async function createStreamReadError(response) {
   const fallback = `Failed to fetch stream: ${response.status}`;
-  if (response.status !== 410)
-    return new Error(fallback);
+  if (response.status !== 410) {
+    return new StreamError2(fallback, { status: response.status });
+  }
   try {
     const body = await response.json();
     return errorForResponse(response.status, typeof body.message === "string" ? body.message : fallback, { code: body.error, details: body.details });
   } catch {
-    return new Error(fallback);
+    return new StreamError2(fallback, { status: response.status });
+  }
+}
+function toStreamError(message, cause) {
+  if (WorkflowWorldError2.is(cause) || EntityConflictError2.is(cause) || RunExpiredError2.is(cause) || StreamError2.is(cause) || StreamExpiredError2.is(cause) || TooEarlyError.is(cause) || ThrottleError2.is(cause) || PreconditionFailedError.is(cause)) {
+    return cause;
   }
+  return new StreamError2(message, { cause });
 }
 function createStreamRequestError(operation, url3, response, text) {
   const context2 = [
     `PUT ${url3.origin}${url3.pathname}`,
     ...getVercelDiagnostics(response.headers)
   ];
-  return new Error(`Stream ${operation} failed: HTTP ${response.status} (${context2.join("; ")}): ${text}`);
+  return new StreamError2(`Stream ${operation} failed: HTTP ${response.status} (${context2.join("; ")}): ${text}`, { url: url3.toString(), status: response.status });
 }
 function encodeMultiChunks(chunks) {
   const encoder4 = new TextEncoder();
@@ -70802,6 +71082,7 @@ function createStreamer2(config4) {
           headers: httpConfig.headers,
           dispatcher: getStreamDispatcher(config4),
           timeoutMs: null,
+          transportErrorCode: "STREAM_ERROR",
           logLabel: url3.pathname,
           spanName: "workflow.stream.write",
           durationAttribute: "workflow.stream.write.chunk_rtt",
@@ -70832,6 +71113,7 @@ function createStreamer2(config4) {
             headers: httpConfig.headers,
             dispatcher: getStreamDispatcher(config4),
             timeoutMs: null,
+            transportErrorCode: "STREAM_ERROR",
             logLabel: url3.pathname,
             spanName: "workflow.stream.write",
             durationAttribute: "workflow.stream.write.chunk_rtt",
@@ -70860,6 +71142,7 @@ function createStreamer2(config4) {
           // 503s with the stream left durably closing.
           dispatcher: getStreamCloseDispatcher(config4),
           timeoutMs: null,
+          transportErrorCode: "STREAM_ERROR",
           logLabel: url3.pathname,
           spanName: "workflow.stream.write",
           durationAttribute: "workflow.stream.write.chunk_rtt",
@@ -70885,6 +71168,7 @@ function createStreamer2(config4) {
           headers: httpConfig.headers,
           dispatcher: void 0,
           timeoutMs: null,
+          transportErrorCode: "STREAM_ERROR",
           logLabel: url3.pathname,
           spanName: "workflow.stream.read.connect",
           attributes: streamSpanAttributes({
@@ -70896,7 +71180,9 @@ function createStreamer2(config4) {
           buildError: createStreamReadError
         });
         if (!response.body) {
-          throw new Error("No response body for stream");
+          throw new StreamError2("No response body for stream", {
+            url: url3.toString()
+          });
         }
         return response.body;
       },
@@ -70910,19 +71196,27 @@ function createStreamer2(config4) {
         }
         const qs = params.toString();
         const endpoint = `/v2/runs/${encodeURIComponent(runId)}/streams/${encodeURIComponent(name)}/chunks${qs ? `?${qs}` : ""}`;
-        return makeRequest({
-          endpoint,
-          config: config4,
-          schema: StreamChunksResponseSchema
-        });
+        try {
+          return await makeRequest({
+            endpoint,
+            config: config4,
+            schema: StreamChunksResponseSchema
+          });
+        } catch (cause) {
+          throw toStreamError(`Failed to read stream chunks for ${name}`, cause);
+        }
       },
       async getInfo(runId, name) {
         const endpoint = `/v2/runs/${encodeURIComponent(runId)}/streams/${encodeURIComponent(name)}/info`;
-        return makeRequest({
-          endpoint,
-          config: config4,
-          schema: StreamInfoResponseSchema
-        });
+        try {
+          return await makeRequest({
+            endpoint,
+            config: config4,
+            schema: StreamInfoResponseSchema
+          });
+        } catch (cause) {
+          throw toStreamError(`Failed to read stream info for ${name}`, cause);
+        }
       },
       async list(runId) {
         const httpConfig = await getHttpConfig(config4);
@@ -70933,10 +71227,18 @@ function createStreamer2(config4) {
           headers: httpConfig.headers,
           dispatcher: void 0,
           timeoutMs: null,
+          transportErrorCode: "STREAM_ERROR",
           logLabel: url3.pathname,
-          buildError: /* @__PURE__ */ __name((res) => new Error(`Failed to list streams: ${res.status}`), "buildError")
+          buildError: /* @__PURE__ */ __name((res) => new StreamError2(`Failed to list streams: ${res.status}`, {
+            url: url3.toString(),
+            status: res.status
+          }), "buildError")
         });
-        return await response.json();
+        try {
+          return await response.json();
+        } catch (cause) {
+          throw toStreamError("Failed to parse stream list response", cause);
+        }
       }
     }
   };
@@ -70945,6 +71247,7 @@ var MAX_CHUNKS_PER_REQUEST, getMaxChunksPerRequest, StreamInfoResponseSchema, St
 var init_streamer2 = __esm({
   "../world-vercel/dist/streamer.js"() {
     "use strict";
+    init_dist7();
     init_dist6();
     init_zod2();
     init_http_client();
@@ -70960,6 +71263,7 @@ var init_streamer2 = __esm({
     __name(getStreamReadUrl, "getStreamReadUrl");
     __name(streamSpanAttributes, "streamSpanAttributes");
     __name(createStreamReadError, "createStreamReadError");
+    __name(toStreamError, "toStreamError");
     __name(createStreamRequestError, "createStreamRequestError");
     __name(encodeMultiChunks, "encodeMultiChunks");
     StreamInfoResponseSchema = external_exports2.object({
@@ -71222,6 +71526,9 @@ function isRetryableWorldError2(err) {
   if (ThrottleError2.is(err)) {
     return true;
   }
+  if (StreamError2.is(err)) {
+    return err.status === void 0 || err.status >= 500;
+  }
   if (!WorkflowWorldError2.is(err)) {
     return false;
   }
@@ -71243,6 +71550,9 @@ function classifyRunError(err) {
   if (WorkflowDeploymentMismatchError.is(err)) {
     return RUN_ERROR_CODES2.DEPLOYMENT_MISMATCH;
   }
+  if (StreamError2.is(err)) {
+    return RUN_ERROR_CODES2.STREAM_ERROR;
+  }
   if (isWorldContractError(err) || isRetryableWorldError2(err)) {
     return RUN_ERROR_CODES2.WORLD_CONTRACT_ERROR;
   }
@@ -71263,7 +71573,11 @@ var init_classify_error = __esm({
       "SCHEMA_VALIDATION",
       RUN_ERROR_CODES2.WORLD_CONTRACT_ERROR
     ]);
-    RETRYABLE_WORLD_ERROR_CODES2 = /* @__PURE__ */ new Set(["TRANSPORT", "TIMEOUT"]);
+    RETRYABLE_WORLD_ERROR_CODES2 = /* @__PURE__ */ new Set([
+      "TRANSPORT",
+      "TIMEOUT",
+      RUN_ERROR_CODES2.STREAM_ERROR
+    ]);
     RUNTIME_ERROR_CHECKS2 = [
       WorkflowRuntimeError2.is,
       StepNotRegisteredError2.is,
@@ -71646,6 +71960,13 @@ function describeError2(err, errorCode) {
       hint: CORRUPTED_EVENT_LOG_HINT
     };
   }
+  if (effectiveCode === RUN_ERROR_CODES2.STREAM_ERROR) {
+    return {
+      attribution: "sdk",
+      errorCode: effectiveCode,
+      hint: STREAM_ERROR_HINT
+    };
+  }
   if (effectiveCode === RUN_ERROR_CODES2.WORLD_CONTRACT_ERROR) {
     return {
       attribution: "sdk",
@@ -71655,7 +71976,7 @@ function describeError2(err, errorCode) {
   }
   return { attribution: "user", errorCode: effectiveCode };
 }
-var SERIALIZATION_ERROR_HINT, CONTEXT_ERROR_HINT, RUNTIME_ERROR_HINT, CORRUPTED_EVENT_LOG_HINT, REPLAY_TIMEOUT_HINT, MAX_DELIVERIES_HINT, MAX_EVENTS_HINT, WORLD_CONTRACT_HINT, DEPLOYMENT_MISMATCH_HINT;
+var SERIALIZATION_ERROR_HINT, CONTEXT_ERROR_HINT, RUNTIME_ERROR_HINT, CORRUPTED_EVENT_LOG_HINT, REPLAY_TIMEOUT_HINT, MAX_DELIVERIES_HINT, MAX_EVENTS_HINT, STREAM_ERROR_HINT, WORLD_CONTRACT_HINT, DEPLOYMENT_MISMATCH_HINT;
 var init_describe_error = __esm({
   "../core/dist/describe-error.js"() {
     "use strict";
@@ -71670,6 +71991,7 @@ var init_describe_error = __esm({
     REPLAY_TIMEOUT_HINT = 'The workflow replay between step boundaries took too long. This bounds workflow-VM and event-log replay time only \u2014 step bodies (`"use step"` functions) are excluded. This usually means the event log is unusually large or the workflow function is doing heavy synchronous work in workflow code outside of step bodies. Override the default budget via the WORKFLOW_REPLAY_TIMEOUT_MS env var if needed.';
     MAX_DELIVERIES_HINT = "The workflow queue exceeded its max-delivery budget. This usually indicates a persistent runtime failure \u2014 check the most recent stack traces for the underlying cause.";
     MAX_EVENTS_HINT = "The workflow exceeded the maximum number of events per run. This usually means unbounded work in the workflow function \u2014 e.g. a loop that keeps creating steps without terminating. Break long-running workflows into child workflows to stay under the limit.";
+    STREAM_ERROR_HINT = "Workflow stream infrastructure failed while reading or writing data. This is an SDK or backend failure, not an error in your workflow code; please retry the run and report persistent failures with the runId.";
     WORLD_CONTRACT_HINT = "The workflow backend returned data that violated the SDK contract. This is not retryable; please report it with the stack trace and runId.";
     DEPLOYMENT_MISMATCH_HINT = "The run was delivered to a deployment other than the deployment it is pinned to, and was stopped to protect against code-skew errors after the runtime failed to re-route it there. Verify that the run's deployment is still available and that queue callbacks route to it.";
     __name(describeError2, "describeError");
@@ -74828,6 +75150,19 @@ function getCommonReducers2(_global2 = globalThis) {
       }
       return reduced;
     }, "RuntimeDecryptionError"),
+    StreamError: /* @__PURE__ */ __name((value) => {
+      const base = reduceNamedErrorSubclassBase2("StreamError", value);
+      if (!base)
+        return false;
+      const reduced = { ...base };
+      const status = readProperty2(value, "status");
+      const url3 = readProperty2(value, "url");
+      if (typeof status === "number")
+        reduced.status = status;
+      if (typeof url3 === "string")
+        reduced.url = url3;
+      return reduced;
+    }, "StreamError"),
     SyntaxError: makeErrorSubclassReducer2("SyntaxError"),
     TypeError: makeErrorSubclassReducer2("TypeError"),
     URIError: makeErrorSubclassReducer2("URIError"),
@@ -74973,6 +75308,17 @@ function getCommonRevivers3(global2 = globalThis) {
         error95.stack = value.stack;
       return error95;
     }, "RuntimeDecryptionError"),
+    StreamError: /* @__PURE__ */ __name((value) => {
+      const Ctor = global2[/* @__PURE__ */ Symbol.for("@workflow/errors//StreamError")] ?? StreamError2;
+      const error95 = new Ctor(value.message, {
+        ..."cause" in value ? { cause: value.cause } : {},
+        status: value.status,
+        url: value.url
+      });
+      if (value.stack !== void 0)
+        error95.stack = value.stack;
+      return error95;
+    }, "StreamError"),
     SyntaxError: makeErrorSubclassReviver2(global2, "SyntaxError"),
     TypeError: makeErrorSubclassReviver2(global2, "TypeError"),
     URIError: makeErrorSubclassReviver2(global2, "URIError"),
@@ -78545,7 +78891,7 @@ var version5;
 var init_version4 = __esm({
   "../core/dist/version.js"() {
     "use strict";
-    version5 = "5.0.0-beta.47";
+    version5 = "5.0.0-beta.48";
   }
 });
 
@@ -78726,6 +79072,10 @@ async function loadWorkflowRunEvents(runId, afterCursor) {
     return { events: loadedEvents, cursor };
   });
 }
+function appendEventLog(log, appended) {
+  appendUniqueEvents(log.events, appended.events);
+  log.cursor = appended.cursor ?? log.cursor;
+}
 function isSlotGapCheckEnabled() {
   return process.env.WORKFLOW_SLOT_GAP_CHECK !== "0";
 }
@@ -78938,6 +79288,7 @@ var init_helpers3 = __esm({
     __name(assertEventPaginationProgress, "assertEventPaginationProgress");
     __name(shouldRetryWithoutEventCursor, "shouldRetryWithoutEventCursor");
     __name(loadWorkflowRunEvents, "loadWorkflowRunEvents");
+    __name(appendEventLog, "appendEventLog");
     __name(isSlotGapCheckEnabled, "isSlotGapCheckEnabled");
     __name(mergeReportedEvents, "mergeReportedEvents");
     __name(absorbSkippedSlotReport, "absorbSkippedSlotReport");
@@ -79550,6 +79901,18 @@ function recordReadTimeToFirstChunk2(startEpochMs, runId, name, startIndex, conn
     });
   })();
 }
+function recordStreamReadKeyResolution2(startEpochMs, runId, name, succeeded) {
+  void (async () => {
+    await recordElapsedSpan2("workflow.stream.read.resolve_key", startEpochMs, {
+      kind: await getSpanKind4("CLIENT"),
+      attributes: {
+        "workflow.run.id": runId,
+        "workflow.stream.name": name,
+        "workflow.stream.read.key_succeeded": succeeded
+      }
+    });
+  })();
+}
 function recordStreamReadComplete2(startEpochMs, runId, name, chunkCount, byteCount, reconnects) {
   void (async () => {
     await recordElapsedSpan2("workflow.stream.read.complete", startEpochMs, {
@@ -79566,27 +79929,51 @@ function recordStreamReadComplete2(startEpochMs, runId, name, chunkCount, byteCo
     });
   })();
 }
-function createReconnectingFramedStream2(runId, name, startIndex) {
+function createReconnectingFramedStream2(runId, name, startIndex, prefetchEncryptionKey = async () => void 0) {
   const reconnectSupported = startIndex === void 0 || startIndex >= 0;
   let currentStartIndex = startIndex ?? 0;
   let consumedFrames = 0;
   let reconnectCount = 0;
   let totalReconnectCount = 0;
   let reader;
+  let canceled = false;
+  let cancelReason;
   let buffer3 = new Uint8Array(0);
   let readStart;
   let connectMs;
   let firstChunkReported = false;
   let chunksDelivered = 0;
   let bytesDelivered = 0;
+  let keyPrefetched = false;
+  function prefetchKey() {
+    if (keyPrefetched)
+      return;
+    keyPrefetched = true;
+    const keyStart = Date.now();
+    void prefetchEncryptionKey().then((key) => {
+      if (key)
+        recordStreamReadKeyResolution2(keyStart, runId, name, true);
+    }, () => recordStreamReadKeyResolution2(keyStart, runId, name, false));
+  }
+  __name(prefetchKey, "prefetchKey");
   async function connect2() {
+    if (canceled)
+      return false;
     const world = await getWorldLazy2();
+    if (canceled)
+      return false;
     const effectiveStartIndex = reconnectSupported ? currentStartIndex + consumedFrames : startIndex;
     const connectStart = Date.now();
     const stream = await world.streams.get(runId, name, effectiveStartIndex);
+    if (canceled) {
+      await stream.cancel(cancelReason).catch(() => {
+      });
+      return false;
+    }
     if (connectMs === void 0)
       connectMs = Date.now() - connectStart;
     reader = stream.getReader();
+    return true;
   }
   __name(connect2, "connect");
   async function isVerifiedComplete() {
@@ -79600,11 +79987,15 @@ function createReconnectingFramedStream2(runId, name, startIndex) {
   }
   __name(isVerifiedComplete, "isVerifiedComplete");
   async function reconnect() {
+    if (canceled)
+      return false;
     if (reader) {
       await reader.cancel().catch(() => {
       });
       reader = void 0;
     }
+    if (canceled)
+      return false;
     currentStartIndex += consumedFrames;
     consumedFrames = 0;
     buffer3 = new Uint8Array(0);
@@ -79614,15 +80005,18 @@ function createReconnectingFramedStream2(runId, name, startIndex) {
       reconnectCount++;
       totalReconnectCount++;
       if (reconnectCount > maxReconnects) {
-        throw new Error(`Stream "${name}" exceeded maximum reconnection attempts (${maxReconnects})`);
+        throw new StreamError2(`Stream "${name}" exceeded maximum reconnection attempts (${maxReconnects})`);
       }
       if (totalReconnectCount > maxTotalReconnects) {
-        throw new Error(`Stream "${name}" exceeded maximum total reconnection attempts (${maxTotalReconnects})`);
+        throw new StreamError2(`Stream "${name}" exceeded maximum total reconnection attempts (${maxTotalReconnects})`);
       }
       try {
-        await connect2();
-        return;
+        if (!await connect2())
+          return false;
+        return true;
       } catch (error95) {
+        if (canceled)
+          return false;
         if (StreamExpiredError2.is(error95))
           throw error95;
       }
@@ -79631,13 +80025,19 @@ function createReconnectingFramedStream2(runId, name, startIndex) {
   __name(reconnect, "reconnect");
   return new ReadableStream({
     pull: /* @__PURE__ */ __name(async (controller) => {
+      if (canceled)
+        return;
       if (readStart === void 0)
         readStart = Date.now();
+      prefetchKey();
       for (; ; ) {
         if (!reader) {
           try {
-            await connect2();
+            if (!await connect2())
+              return;
           } catch (err) {
+            if (canceled)
+              return;
             controller.error(err);
             return;
           }
@@ -79646,23 +80046,32 @@ function createReconnectingFramedStream2(runId, name, startIndex) {
         try {
           result2 = await reader.read();
         } catch (err) {
+          if (canceled)
+            return;
           if (!reconnectSupported) {
             controller.error(err);
             return;
           }
           try {
-            await reconnect();
+            if (!await reconnect())
+              return;
           } catch (reconnectErr) {
             controller.error(reconnectErr);
             return;
           }
           continue;
         }
+        if (canceled)
+          return;
         if (result2.done || !result2.value) {
           reader = void 0;
-          if (reconnectSupported && !await isVerifiedComplete()) {
+          const verifiedComplete = !reconnectSupported || await isVerifiedComplete();
+          if (canceled)
+            return;
+          if (!verifiedComplete) {
             try {
-              await reconnect();
+              if (!await reconnect())
+                return;
             } catch (reconnectErr) {
               controller.error(reconnectErr);
               return;
@@ -79705,12 +80114,15 @@ function createReconnectingFramedStream2(runId, name, startIndex) {
         }
       }
     }, "pull"),
-    cancel: /* @__PURE__ */ __name(async () => {
-      if (reader) {
-        await reader.cancel().catch((err) => {
+    cancel: /* @__PURE__ */ __name(async (reason) => {
+      canceled = true;
+      cancelReason = reason;
+      const currentReader = reader;
+      reader = void 0;
+      if (currentReader) {
+        await currentReader.cancel(reason).catch((err) => {
           console.warn("Error closing ReadableStream reader:", err);
         });
-        reader = void 0;
       }
     }, "cancel")
   });
@@ -80261,7 +80673,48 @@ async function getForwardedWritableEncryptionKey2(runId, deploymentId, encryptio
   const rawKey = deploymentId ? await world.getEncryptionKeyForRun(runId, { deploymentId }) : await world.getEncryptionKeyForRun(await world.runs.get(runId));
   return rawKey ? await importKey2(rawKey, ["encrypt"]) : void 0;
 }
-function getExternalRevivers2(global2 = globalThis, ops, runId, cryptoKey) {
+function getRunReadableStream2(global2, ops, runId, name, startIndex, cryptoKey) {
+  let reader;
+  let lockState;
+  let lockPollingStarted = false;
+  let userReadable;
+  userReadable = new ReadableStream(
+    {
+      async pull(controller) {
+        try {
+          if (!reader) {
+            const stream = getExternalRevivers2(global2, ops, runId, cryptoKey, {
+              onReadableState: /* @__PURE__ */ __name((state) => {
+                lockState = state;
+              }, "onReadableState")
+            }).ReadableStream({ name, startIndex });
+            reader = stream.getReader();
+            if (lockState && !lockPollingStarted) {
+              lockPollingStarted = true;
+              pollReadableLock2(userReadable, lockState);
+            }
+          }
+          const result2 = await reader.read();
+          if (result2.done)
+            controller.close();
+          else
+            controller.enqueue(result2.value);
+        } catch (error95) {
+          controller.error(error95);
+        }
+      },
+      async cancel(reason) {
+        await reader?.cancel(reason).catch(() => {
+        });
+      }
+    },
+    // A positive default high-water mark would run pull at construction to
+    // fill the queue, turning an unread Run.getReadable() into I/O.
+    { highWaterMark: 0 }
+  );
+  return userReadable;
+}
+function getExternalRevivers2(global2 = globalThis, ops, runId, cryptoKey, options) {
   return {
     ...getCommonRevivers4(global2),
     // StepFunction should not be returned from workflows to clients
@@ -80309,16 +80762,27 @@ function getExternalRevivers2(global2 = globalThis, ops, runId, cryptoKey) {
         const { readable: userReadable, writable } = value.framing === "framed-v1" ? getByteUnframingStream2() : new global2.TransformStream();
         flushablePipe2(readable, writable, state).catch(() => {
         });
-        pollReadableLock2(userReadable, state);
+        if (options?.onReadableState)
+          options.onReadableState(state);
+        else
+          pollReadableLock2(userReadable, state);
         return userReadable;
       } else {
-        const readable = createReconnectingFramedStream2(runId, value.name, value.startIndex);
-        const transform3 = getDeserializeStream2(getExternalRevivers2(global2, ops, runId, cryptoKey), cryptoKey);
+        let keyPromise;
+        const resolveKey = /* @__PURE__ */ __name(() => {
+          keyPromise ??= resolveEncryptionKey2(cryptoKey);
+          return keyPromise;
+        }, "resolveKey");
+        const readable = createReconnectingFramedStream2(runId, value.name, value.startIndex, resolveKey);
+        const transform3 = getDeserializeStream2(getExternalRevivers2(global2, ops, runId, resolveKey), resolveKey);
         const state = createFlushableState2();
         ops.push(state.promise);
         flushablePipe2(readable, transform3.writable, state).catch(() => {
         });
-        pollReadableLock2(transform3.readable, state);
+        if (options?.onReadableState)
+          options.onReadableState(state);
+        else
+          pollReadableLock2(transform3.readable, state);
         return transform3.readable;
       }
     }, "ReadableStream"),
@@ -80892,6 +81356,7 @@ var init_serialization4 = __esm({
     __name(getByteFramingStream2, "getByteFramingStream");
     __name(getByteUnframingStream2, "getByteUnframingStream");
     __name(recordReadTimeToFirstChunk2, "recordReadTimeToFirstChunk");
+    __name(recordStreamReadKeyResolution2, "recordStreamReadKeyResolution");
     __name(recordStreamReadComplete2, "recordStreamReadComplete");
     WorkflowServerReadableStream2 = class extends ReadableStream {
       static {
@@ -81206,6 +81671,7 @@ var init_serialization4 = __esm({
     __name(reviveAbortSignal2, "reviveAbortSignal");
     __name(getCommonRevivers4, "getCommonRevivers");
     __name(getForwardedWritableEncryptionKey2, "getForwardedWritableEncryptionKey");
+    __name(getRunReadableStream2, "getRunReadableStream");
     __name(getExternalRevivers2, "getExternalRevivers");
     __name(getWorkflowRevivers, "getWorkflowRevivers");
     __name(getStepRevivers2, "getStepRevivers");
@@ -87866,6 +88332,30 @@ function createQuickJSSerde(vm, capturedRoot) {
         reduced.cause = shape.cause;
       return reduced;
     }, "RuntimeDecryptionError"),
+    StreamError: /* @__PURE__ */ __name((value) => {
+      if (!isHandle(value) || !value.isError)
+        return false;
+      if (chainedString(value, "name") !== "StreamError")
+        return false;
+      const shape = reduceErrorShape(value);
+      const reduced = {
+        message: shape.message,
+        stack: shape.stack
+      };
+      if (Object.hasOwn(shape, "cause"))
+        reduced.cause = shape.cause;
+      const status = own(value, "status");
+      if (status && !status.isUndefined)
+        reduced.status = status;
+      else
+        status?.dispose();
+      const url3 = own(value, "url");
+      if (url3 && !url3.isUndefined)
+        reduced.url = url3;
+      else
+        url3?.dispose();
+      return reduced;
+    }, "StreamError"),
     SyntaxError: namedErrorSubclassReducer("SyntaxError"),
     TypeError: namedErrorSubclassReducer("TypeError"),
     URIError: namedErrorSubclassReducer("URIError"),
@@ -88449,6 +88939,41 @@ function createQuickJSSerde(vm, capturedRoot) {
       }
       return error95;
     }, "RuntimeDecryptionError"),
+    StreamError: /* @__PURE__ */ __name((value) => {
+      const cls = registeredErrorClass("@workflow/errors//StreamError");
+      let error95;
+      if (cls) {
+        const options = vm.newObject();
+        for (const property of ["cause", "status", "url"]) {
+          if (!guestHasOwn(value, property))
+            continue;
+          const propertyValue = own(value, property) ?? vm.undefined;
+          options.setProp(property, propertyValue);
+          if (propertyValue !== vm.undefined)
+            propertyValue.dispose();
+        }
+        const message = own(value, "message") ?? vm.undefined;
+        error95 = vm.construct(cls, message, options);
+        if (message !== vm.undefined)
+          message.dispose();
+        options.dispose();
+        const stack = own(value, "stack");
+        if (stack && !stack.isUndefined)
+          define2(error95, "stack", stack);
+        stack?.dispose();
+        cls.dispose();
+      } else {
+        error95 = buildError(i.Error, value, { name: "StreamError" });
+        for (const property of ["status", "url"]) {
+          const propertyValue = own(value, property);
+          if (propertyValue && !propertyValue.isUndefined) {
+            define2(error95, property, propertyValue);
+          }
+          propertyValue?.dispose();
+        }
+      }
+      return error95;
+    }, "StreamError"),
     SyntaxError: namedErrorSubclassReviver("SyntaxError"),
     TypeError: namedErrorSubclassReviver("TypeError"),
     URIError: namedErrorSubclassReviver("URIError"),
@@ -88941,7 +89466,8 @@ var init_quickjs_serde = __esm({
       "@workflow/errors//FatalError",
       "@workflow/errors//HookConflictError",
       "@workflow/errors//RetryableError",
-      "@workflow/errors//RuntimeDecryptionError"
+      "@workflow/errors//RuntimeDecryptionError",
+      "@workflow/errors//StreamError"
     ];
     CAPTURE_ROOT = `(() => ({
   intrinsics: ${CAPTURE_INTRINSICS},
@@ -92268,6 +92794,8 @@ var init_error_codes = __esm2({
       MAX_EVENTS_EXCEEDED: "MAX_EVENTS_EXCEEDED",
       /** Workflow replay exceeded the maximum allowed duration */
       REPLAY_TIMEOUT: "REPLAY_TIMEOUT",
+      /** Workflow stream infrastructure failed while reading or writing data */
+      STREAM_ERROR: "STREAM_ERROR",
       /** World response violated the SDK contract and cannot be retried safely */
       WORLD_CONTRACT_ERROR: "WORLD_CONTRACT_ERROR",
       /** Run was delivered to a deployment other than the one it is pinned to */
@@ -92325,6 +92853,7 @@ var HookConflictError;
 var HookNotFoundError;
 var EntityConflictError;
 var RunExpiredError;
+var StreamError;
 var StreamExpiredError;
 var ThrottleError;
 var WorkflowRunCancelledError;
@@ -92334,11 +92863,13 @@ var FATAL_ERROR_KEY;
 var RETRYABLE_ERROR_KEY;
 var HOOK_CONFLICT_ERROR_KEY;
 var RUNTIME_DECRYPTION_ERROR_KEY;
+var STREAM_ERROR_KEY;
 var init_dist2 = __esm2({
   "../errors/dist/index.js"() {
     "use strict";
     init_dist();
     init_error_codes();
+    init_error_codes();
     BASE_URL = "https://workflow-sdk.dev/err";
     __name2(isError, "isError");
     __name2(appendFramedDetails, "appendFramedDetails");
@@ -92396,6 +92927,12 @@ Caused by: ${options.cause.stack}`;
       url;
       /** Retry-After value in seconds, present on 429 and 425 responses */
       retryAfter;
+      /**
+       * The offending argument, present on client-side validation failures
+       * (`code: 'INVALID_ARGUMENT'`). Lets a caller correct the specific
+       * parameter without parsing the message.
+       */
+      field;
       constructor(message, options) {
         super(message, {
           cause: options?.cause
@@ -92405,6 +92942,7 @@ Caused by: ${options.cause.stack}`;
         this.code = options?.code;
         this.url = options?.url;
         this.retryAfter = options?.retryAfter;
+        this.field = options?.field;
       }
       static is(value) {
         return isError(value) && value.name === "WorkflowWorldError";
@@ -92651,6 +93189,26 @@ Caused by: ${options.cause.stack}`;
         return isError(value) && value.name === "RunExpiredError";
       }
     };
+    StreamError = class extends WorkflowWorldError {
+      static {
+        __name(this, "StreamError");
+      }
+      static {
+        __name2(this, "StreamError");
+      }
+      constructor(message, options) {
+        super(message, {
+          code: RUN_ERROR_CODES.STREAM_ERROR,
+          cause: options?.cause,
+          url: options?.url,
+          status: options?.status
+        });
+        this.name = "StreamError";
+      }
+      static is(value) {
+        return isError(value) && value.name === "StreamError";
+      }
+    };
     StreamExpiredError = class extends WorkflowWorldError {
       static {
         __name(this, "StreamExpiredError");
@@ -92755,6 +93313,7 @@ Caused by: ${options.cause.stack}`;
     RETRYABLE_ERROR_KEY = /* @__PURE__ */ Symbol.for("@workflow/errors//RetryableError");
     HOOK_CONFLICT_ERROR_KEY = /* @__PURE__ */ Symbol.for("@workflow/errors//HookConflictError");
     RUNTIME_DECRYPTION_ERROR_KEY = /* @__PURE__ */ Symbol.for("@workflow/errors//RuntimeDecryptionError");
+    STREAM_ERROR_KEY = /* @__PURE__ */ Symbol.for("@workflow/errors//StreamError");
     if (typeof globalThis !== "undefined") {
       if (!Object.hasOwn(globalThis, FATAL_ERROR_KEY)) {
         Object.defineProperty(globalThis, FATAL_ERROR_KEY, {
@@ -92788,6 +93347,14 @@ Caused by: ${options.cause.stack}`;
           configurable: false
         });
       }
+      if (!Object.hasOwn(globalThis, STREAM_ERROR_KEY)) {
+        Object.defineProperty(globalThis, STREAM_ERROR_KEY, {
+          value: StreamError,
+          writable: false,
+          enumerable: false,
+          configurable: false
+        });
+      }
     }
   }
 });
@@ -111882,7 +112449,7 @@ var init_runs = __esm2({
       // Completed state - output can be v1 or v2 format
       WorkflowRunBaseSchema.extend({
         status: external_exports.literal("completed"),
-        output: SerializedDataSchema,
+        output: SerializedDataSchema.optional(),
         error: external_exports.undefined().optional(),
         completedAt: external_exports.coerce.date()
       }),
@@ -111890,7 +112457,7 @@ var init_runs = __esm2({
       WorkflowRunBaseSchema.extend({
         status: external_exports.literal("failed"),
         output: external_exports.undefined().optional(),
-        error: SerializedDataSchema,
+        error: SerializedDataSchema.optional(),
         completedAt: external_exports.coerce.date()
       })
     ]);
@@ -112154,8 +112721,8 @@ var init_analytics = __esm2({
     AnalyticsAttributeKeySchema = external_exports.object({
       key: external_exports.string(),
       runCount: external_exports.coerce.number(),
-      firstSeenAt: external_exports.coerce.date(),
-      lastSeenAt: external_exports.coerce.date()
+      firstSeenAt: UTCDateSchema,
+      lastSeenAt: UTCDateSchema
     });
   }
 });
@@ -113279,6 +113846,18 @@ function getCommonReducers(_global2 = globalThis) {
       }
       return reduced;
     }, "RuntimeDecryptionError"),
+    StreamError: /* @__PURE__ */ __name2((value) => {
+      const base = reduceNamedErrorSubclassBase("StreamError", value);
+      if (!base) return false;
+      const reduced = {
+        ...base
+      };
+      const status = readProperty(value, "status");
+      const url22 = readProperty(value, "url");
+      if (typeof status === "number") reduced.status = status;
+      if (typeof url22 === "string") reduced.url = url22;
+      return reduced;
+    }, "StreamError"),
     SyntaxError: makeErrorSubclassReducer("SyntaxError"),
     TypeError: makeErrorSubclassReducer("TypeError"),
     URIError: makeErrorSubclassReducer("URIError"),
@@ -113413,6 +113992,18 @@ function getCommonRevivers(global2 = globalThis) {
       if (value.stack !== void 0) error482.stack = value.stack;
       return error482;
     }, "RuntimeDecryptionError"),
+    StreamError: /* @__PURE__ */ __name2((value) => {
+      const Ctor = global2[/* @__PURE__ */ Symbol.for("@workflow/errors//StreamError")] ?? StreamError;
+      const error482 = new Ctor(value.message, {
+        ..."cause" in value ? {
+          cause: value.cause
+        } : {},
+        status: value.status,
+        url: value.url
+      });
+      if (value.stack !== void 0) error482.stack = value.stack;
+      return error482;
+    }, "StreamError"),
     SyntaxError: makeErrorSubclassReviver(global2, "SyntaxError"),
     TypeError: makeErrorSubclassReviver(global2, "TypeError"),
     URIError: makeErrorSubclassReviver(global2, "URIError"),
@@ -118938,7 +119529,7 @@ var version2;
 var init_version = __esm2({
   "../core/dist/version.js"() {
     "use strict";
-    version2 = "5.0.0-beta.47";
+    version2 = "5.0.0-beta.48";
   }
 });
 function getWorkflowQueueName(workflowName, namespace) {
@@ -124730,6 +125321,19 @@ function recordReadTimeToFirstChunk(startEpochMs, runId, name, startIndex, conne
   })();
 }
 __name(recordReadTimeToFirstChunk, "recordReadTimeToFirstChunk");
+function recordStreamReadKeyResolution(startEpochMs, runId, name, succeeded) {
+  void (async () => {
+    await recordElapsedSpan("workflow.stream.read.resolve_key", startEpochMs, {
+      kind: await getSpanKind("CLIENT"),
+      attributes: {
+        "workflow.run.id": runId,
+        "workflow.stream.name": name,
+        "workflow.stream.read.key_succeeded": succeeded
+      }
+    });
+  })();
+}
+__name(recordStreamReadKeyResolution, "recordStreamReadKeyResolution");
 function recordStreamReadComplete(startEpochMs, runId, name, chunkCount, byteCount, reconnects) {
   void (async () => {
     await recordElapsedSpan("workflow.stream.read.complete", startEpochMs, {
@@ -124749,26 +125353,47 @@ function recordStreamReadComplete(startEpochMs, runId, name, chunkCount, byteCou
   })();
 }
 __name(recordStreamReadComplete, "recordStreamReadComplete");
-function createReconnectingFramedStream(runId, name, startIndex) {
+function createReconnectingFramedStream(runId, name, startIndex, prefetchEncryptionKey = async () => void 0) {
   const reconnectSupported = startIndex === void 0 || startIndex >= 0;
   let currentStartIndex = startIndex ?? 0;
   let consumedFrames = 0;
   let reconnectCount = 0;
   let totalReconnectCount = 0;
   let reader;
+  let canceled = false;
+  let cancelReason;
   let buffer22 = new Uint8Array(0);
   let readStart;
   let connectMs;
   let firstChunkReported = false;
   let chunksDelivered = 0;
   let bytesDelivered = 0;
+  let keyPrefetched = false;
+  function prefetchKey() {
+    if (keyPrefetched) return;
+    keyPrefetched = true;
+    const keyStart = Date.now();
+    void prefetchEncryptionKey().then((key) => {
+      if (key) recordStreamReadKeyResolution(keyStart, runId, name, true);
+    }, () => recordStreamReadKeyResolution(keyStart, runId, name, false));
+  }
+  __name(prefetchKey, "prefetchKey");
+  __name2(prefetchKey, "prefetchKey");
   async function connect2() {
+    if (canceled) return false;
     const world = await getWorldLazy();
+    if (canceled) return false;
     const effectiveStartIndex = reconnectSupported ? currentStartIndex + consumedFrames : startIndex;
     const connectStart = Date.now();
     const stream = await world.streams.get(runId, name, effectiveStartIndex);
+    if (canceled) {
+      await stream.cancel(cancelReason).catch(() => {
+      });
+      return false;
+    }
     if (connectMs === void 0) connectMs = Date.now() - connectStart;
     reader = stream.getReader();
+    return true;
   }
   __name(connect2, "connect");
   __name2(connect2, "connect");
@@ -124784,11 +125409,13 @@ function createReconnectingFramedStream(runId, name, startIndex) {
   __name(isVerifiedComplete, "isVerifiedComplete");
   __name2(isVerifiedComplete, "isVerifiedComplete");
   async function reconnect() {
+    if (canceled) return false;
     if (reader) {
       await reader.cancel().catch(() => {
       });
       reader = void 0;
     }
+    if (canceled) return false;
     currentStartIndex += consumedFrames;
     consumedFrames = 0;
     buffer22 = new Uint8Array(0);
@@ -124798,15 +125425,16 @@ function createReconnectingFramedStream(runId, name, startIndex) {
       reconnectCount++;
       totalReconnectCount++;
       if (reconnectCount > maxReconnects) {
-        throw new Error(`Stream "${name}" exceeded maximum reconnection attempts (${maxReconnects})`);
+        throw new StreamError(`Stream "${name}" exceeded maximum reconnection attempts (${maxReconnects})`);
       }
       if (totalReconnectCount > maxTotalReconnects) {
-        throw new Error(`Stream "${name}" exceeded maximum total reconnection attempts (${maxTotalReconnects})`);
+        throw new StreamError(`Stream "${name}" exceeded maximum total reconnection attempts (${maxTotalReconnects})`);
       }
       try {
-        await connect2();
-        return;
+        if (!await connect2()) return false;
+        return true;
       } catch (error482) {
+        if (canceled) return false;
         if (StreamExpiredError.is(error482)) throw error482;
       }
     }
@@ -124815,12 +125443,15 @@ function createReconnectingFramedStream(runId, name, startIndex) {
   __name2(reconnect, "reconnect");
   return new ReadableStream({
     pull: /* @__PURE__ */ __name2(async (controller) => {
+      if (canceled) return;
       if (readStart === void 0) readStart = Date.now();
+      prefetchKey();
       for (; ; ) {
         if (!reader) {
           try {
-            await connect2();
+            if (!await connect2()) return;
           } catch (err) {
+            if (canceled) return;
             controller.error(err);
             return;
           }
@@ -124829,23 +125460,27 @@ function createReconnectingFramedStream(runId, name, startIndex) {
         try {
           result2 = await reader.read();
         } catch (err) {
+          if (canceled) return;
           if (!reconnectSupported) {
             controller.error(err);
             return;
           }
           try {
-            await reconnect();
+            if (!await reconnect()) return;
           } catch (reconnectErr) {
             controller.error(reconnectErr);
             return;
           }
           continue;
         }
+        if (canceled) return;
         if (result2.done || !result2.value) {
           reader = void 0;
-          if (reconnectSupported && !await isVerifiedComplete()) {
+          const verifiedComplete = !reconnectSupported || await isVerifiedComplete();
+          if (canceled) return;
+          if (!verifiedComplete) {
             try {
-              await reconnect();
+              if (!await reconnect()) return;
             } catch (reconnectErr) {
               controller.error(reconnectErr);
               return;
@@ -124887,12 +125522,15 @@ function createReconnectingFramedStream(runId, name, startIndex) {
         }
       }
     }, "pull"),
-    cancel: /* @__PURE__ */ __name2(async () => {
-      if (reader) {
-        await reader.cancel().catch((err) => {
+    cancel: /* @__PURE__ */ __name2(async (reason) => {
+      canceled = true;
+      cancelReason = reason;
+      const currentReader = reader;
+      reader = void 0;
+      if (currentReader) {
+        await currentReader.cancel(reason).catch((err) => {
           console.warn("Error closing ReadableStream reader:", err);
         });
-        reader = void 0;
       }
     }, "cancel")
   });
@@ -125415,7 +126053,52 @@ async function getForwardedWritableEncryptionKey(runId, deploymentId, encryption
   ]) : void 0;
 }
 __name(getForwardedWritableEncryptionKey, "getForwardedWritableEncryptionKey");
-function getExternalRevivers(global2 = globalThis, ops, runId, cryptoKey) {
+function getRunReadableStream(global2, ops, runId, name, startIndex, cryptoKey) {
+  let reader;
+  let lockState;
+  let lockPollingStarted = false;
+  let userReadable;
+  userReadable = new ReadableStream(
+    {
+      async pull(controller) {
+        try {
+          if (!reader) {
+            const stream = getExternalRevivers(global2, ops, runId, cryptoKey, {
+              onReadableState: /* @__PURE__ */ __name2((state) => {
+                lockState = state;
+              }, "onReadableState")
+            }).ReadableStream({
+              name,
+              startIndex
+            });
+            reader = stream.getReader();
+            if (lockState && !lockPollingStarted) {
+              lockPollingStarted = true;
+              pollReadableLock(userReadable, lockState);
+            }
+          }
+          const result2 = await reader.read();
+          if (result2.done) controller.close();
+          else controller.enqueue(result2.value);
+        } catch (error482) {
+          controller.error(error482);
+        }
+      },
+      async cancel(reason) {
+        await reader?.cancel(reason).catch(() => {
+        });
+      }
+    },
+    // A positive default high-water mark would run pull at construction to
+    // fill the queue, turning an unread Run.getReadable() into I/O.
+    {
+      highWaterMark: 0
+    }
+  );
+  return userReadable;
+}
+__name(getRunReadableStream, "getRunReadableStream");
+function getExternalRevivers(global2 = globalThis, ops, runId, cryptoKey, options) {
   return {
     ...getCommonRevivers2(global2),
     // StepFunction should not be returned from workflows to clients
@@ -125463,16 +126146,23 @@ function getExternalRevivers(global2 = globalThis, ops, runId, cryptoKey) {
         const { readable: userReadable, writable } = value.framing === "framed-v1" ? getByteUnframingStream() : new global2.TransformStream();
         flushablePipe(readable, writable, state).catch(() => {
         });
-        pollReadableLock(userReadable, state);
+        if (options?.onReadableState) options.onReadableState(state);
+        else pollReadableLock(userReadable, state);
         return userReadable;
       } else {
-        const readable = createReconnectingFramedStream(runId, value.name, value.startIndex);
-        const transform22 = getDeserializeStream(getExternalRevivers(global2, ops, runId, cryptoKey), cryptoKey);
+        let keyPromise;
+        const resolveKey = /* @__PURE__ */ __name2(() => {
+          keyPromise ??= resolveEncryptionKey(cryptoKey);
+          return keyPromise;
+        }, "resolveKey");
+        const readable = createReconnectingFramedStream(runId, value.name, value.startIndex, resolveKey);
+        const transform22 = getDeserializeStream(getExternalRevivers(global2, ops, runId, resolveKey), resolveKey);
         const state = createFlushableState();
         ops.push(state.promise);
         flushablePipe(readable, transform22.writable, state).catch(() => {
         });
-        pollReadableLock(transform22.readable, state);
+        if (options?.onReadableState) options.onReadableState(state);
+        else pollReadableLock(transform22.readable, state);
         return transform22.readable;
       }
     }, "ReadableStream"),
@@ -125889,6 +126579,7 @@ var init_serialization2 = __esm2({
     __name2(getByteFramingStream, "getByteFramingStream");
     __name2(getByteUnframingStream, "getByteUnframingStream");
     __name2(recordReadTimeToFirstChunk, "recordReadTimeToFirstChunk");
+    __name2(recordStreamReadKeyResolution, "recordStreamReadKeyResolution");
     __name2(recordStreamReadComplete, "recordStreamReadComplete");
     WorkflowServerReadableStream = class extends ReadableStream {
       static {
@@ -126209,6 +126900,7 @@ var init_serialization2 = __esm2({
     __name2(reviveAbortSignal, "reviveAbortSignal");
     __name2(getCommonRevivers2, "getCommonRevivers");
     __name2(getForwardedWritableEncryptionKey, "getForwardedWritableEncryptionKey");
+    __name2(getRunReadableStream, "getRunReadableStream");
     __name2(getExternalRevivers, "getExternalRevivers");
     __name2(getStepRevivers, "getStepRevivers");
     __name2(dehydrateWorkflowArguments, "dehydrateWorkflowArguments");
@@ -126379,7 +127071,8 @@ var WORLD_CONTRACT_ERROR_CODES = /* @__PURE__ */ new Set([
 ]);
 var RETRYABLE_WORLD_ERROR_CODES = /* @__PURE__ */ new Set([
   "TRANSPORT",
-  "TIMEOUT"
+  "TIMEOUT",
+  RUN_ERROR_CODES.STREAM_ERROR
 ]);
 var RUNTIME_ERROR_CHECKS = [
   WorkflowRuntimeError.is,
@@ -126395,6 +127088,9 @@ function isRetryableWorldError(err) {
   if (ThrottleError.is(err)) {
     return true;
   }
+  if (StreamError.is(err)) {
+    return err.status === void 0 || err.status >= 500;
+  }
   if (!WorkflowWorldError.is(err)) {
     return false;
   }
@@ -126692,7 +127388,7 @@ __name2(start, "start");
     value: "start",
     configurable: true
   });
-})(start, "step//@workflow/core/runtime/start@5.0.0-beta.47//start");
+})(start, "step//@workflow/core/runtime/start@5.0.0-beta.48//start");
 async function wakeUpRun(world, runId, options) {
   try {
     const run22 = await world.runs.get(runId, {
@@ -126880,9 +127576,9 @@ var Run = class _Run {
     return this.#encryptionKeyPromise;
   }
   /**
-   * Defer fetching the run and its encryption key until serialized stream data
-   * is actually read. An empty or metadata-only stream must not start an
-   * unobserved run lookup.
+   * Defers fetching the run and its encryption key until a readable is first
+   * consumed. The first pull prefetches it so an encrypted first frame can join
+   * the lookup; this also applies to an empty consumed stream.
    * @internal
    */
   #getEncryptionKeyLazily() {
@@ -126993,10 +127689,7 @@ var Run = class _Run {
     const { ops = [], global: global2 = globalThis, startIndex, namespace } = options;
     const name = getWorkflowRunStreamId(this.runId, namespace);
     const encryptionKey = this.#getEncryptionKeyLazily();
-    const stream = getExternalRevivers(global2, ops, this.runId, encryptionKey).ReadableStream({
-      name,
-      startIndex
-    });
+    const stream = getRunReadableStream(global2, ops, this.runId, name, startIndex, encryptionKey);
     const worldPromise = this.#lazyWorldPromise;
     const runId = this.runId;
     return Object.assign(stream, {
@@ -127095,7 +127788,7 @@ var Run = class _Run {
     value: "wakeUp",
     configurable: true
   });
-})(Run.prototype["wakeUp"], "step//@workflow/core/runtime/run@5.0.0-beta.47//Run#wakeUp");
+})(Run.prototype["wakeUp"], "step//@workflow/core/runtime/run@5.0.0-beta.48//Run#wakeUp");
 (function(__wf_fn, __wf_id) {
   var __wf_sym = /* @__PURE__ */ Symbol.for("@workflow/core//registeredSteps"), __wf_reg = globalThis[__wf_sym] || (globalThis[__wf_sym] = /* @__PURE__ */ new Map());
   __wf_reg.set(__wf_id, __wf_fn);
@@ -127104,7 +127797,7 @@ var Run = class _Run {
     value: "cancel",
     configurable: true
   });
-})(Run.prototype["cancel"], "step//@workflow/core/runtime/run@5.0.0-beta.47//Run#cancel");
+})(Run.prototype["cancel"], "step//@workflow/core/runtime/run@5.0.0-beta.48//Run#cancel");
 (function(__wf_fn, __wf_id) {
   var __wf_sym = /* @__PURE__ */ Symbol.for("@workflow/core//registeredSteps"), __wf_reg = globalThis[__wf_sym] || (globalThis[__wf_sym] = /* @__PURE__ */ new Map());
   __wf_reg.set(__wf_id, __wf_fn);
@@ -127113,7 +127806,7 @@ var Run = class _Run {
     value: "getReadable",
     configurable: true
   });
-})(Run.prototype["getReadable"], "step//@workflow/core/runtime/run@5.0.0-beta.47//Run#getReadable");
+})(Run.prototype["getReadable"], "step//@workflow/core/runtime/run@5.0.0-beta.48//Run#getReadable");
 (function(__wf_fn, __wf_id) {
   var __wf_sym = /* @__PURE__ */ Symbol.for("@workflow/core//registeredSteps"), __wf_reg = globalThis[__wf_sym] || (globalThis[__wf_sym] = /* @__PURE__ */ new Map());
   __wf_reg.set(__wf_id, __wf_fn);
@@ -127122,7 +127815,7 @@ var Run = class _Run {
     value: "exists",
     configurable: true
   });
-})(Object.getOwnPropertyDescriptor(Run.prototype, "exists").get, "step//@workflow/core/runtime/run@5.0.0-beta.47//Run#exists");
+})(Object.getOwnPropertyDescriptor(Run.prototype, "exists").get, "step//@workflow/core/runtime/run@5.0.0-beta.48//Run#exists");
 (function(__wf_fn, __wf_id) {
   var __wf_sym = /* @__PURE__ */ Symbol.for("@workflow/core//registeredSteps"), __wf_reg = globalThis[__wf_sym] || (globalThis[__wf_sym] = /* @__PURE__ */ new Map());
   __wf_reg.set(__wf_id, __wf_fn);
@@ -127131,7 +127824,7 @@ var Run = class _Run {
     value: "status",
     configurable: true
   });
-})(Object.getOwnPropertyDescriptor(Run.prototype, "status").get, "step//@workflow/core/runtime/run@5.0.0-beta.47//Run#status");
+})(Object.getOwnPropertyDescriptor(Run.prototype, "status").get, "step//@workflow/core/runtime/run@5.0.0-beta.48//Run#status");
 (function(__wf_fn, __wf_id) {
   var __wf_sym = /* @__PURE__ */ Symbol.for("@workflow/core//registeredSteps"), __wf_reg = globalThis[__wf_sym] || (globalThis[__wf_sym] = /* @__PURE__ */ new Map());
   __wf_reg.set(__wf_id, __wf_fn);
@@ -127140,7 +127833,7 @@ var Run = class _Run {
     value: "returnValue",
     configurable: true
   });
-})(Object.getOwnPropertyDescriptor(Run.prototype, "returnValue").get, "step//@workflow/core/runtime/run@5.0.0-beta.47//Run#returnValue");
+})(Object.getOwnPropertyDescriptor(Run.prototype, "returnValue").get, "step//@workflow/core/runtime/run@5.0.0-beta.48//Run#returnValue");
 (function(__wf_fn, __wf_id) {
   var __wf_sym = /* @__PURE__ */ Symbol.for("@workflow/core//registeredSteps"), __wf_reg = globalThis[__wf_sym] || (globalThis[__wf_sym] = /* @__PURE__ */ new Map());
   __wf_reg.set(__wf_id, __wf_fn);
@@ -127149,7 +127842,7 @@ var Run = class _Run {
     value: "workflowName",
     configurable: true
   });
-})(Object.getOwnPropertyDescriptor(Run.prototype, "workflowName").get, "step//@workflow/core/runtime/run@5.0.0-beta.47//Run#workflowName");
+})(Object.getOwnPropertyDescriptor(Run.prototype, "workflowName").get, "step//@workflow/core/runtime/run@5.0.0-beta.48//Run#workflowName");
 (function(__wf_fn, __wf_id) {
   var __wf_sym = /* @__PURE__ */ Symbol.for("@workflow/core//registeredSteps"), __wf_reg = globalThis[__wf_sym] || (globalThis[__wf_sym] = /* @__PURE__ */ new Map());
   __wf_reg.set(__wf_id, __wf_fn);
@@ -127158,7 +127851,7 @@ var Run = class _Run {
     value: "createdAt",
     configurable: true
   });
-})(Object.getOwnPropertyDescriptor(Run.prototype, "createdAt").get, "step//@workflow/core/runtime/run@5.0.0-beta.47//Run#createdAt");
+})(Object.getOwnPropertyDescriptor(Run.prototype, "createdAt").get, "step//@workflow/core/runtime/run@5.0.0-beta.48//Run#createdAt");
 (function(__wf_fn, __wf_id) {
   var __wf_sym = /* @__PURE__ */ Symbol.for("@workflow/core//registeredSteps"), __wf_reg = globalThis[__wf_sym] || (globalThis[__wf_sym] = /* @__PURE__ */ new Map());
   __wf_reg.set(__wf_id, __wf_fn);
@@ -127167,7 +127860,7 @@ var Run = class _Run {
     value: "startedAt",
     configurable: true
   });
-})(Object.getOwnPropertyDescriptor(Run.prototype, "startedAt").get, "step//@workflow/core/runtime/run@5.0.0-beta.47//Run#startedAt");
+})(Object.getOwnPropertyDescriptor(Run.prototype, "startedAt").get, "step//@workflow/core/runtime/run@5.0.0-beta.48//Run#startedAt");
 (function(__wf_fn, __wf_id) {
   var __wf_sym = /* @__PURE__ */ Symbol.for("@workflow/core//registeredSteps"), __wf_reg = globalThis[__wf_sym] || (globalThis[__wf_sym] = /* @__PURE__ */ new Map());
   __wf_reg.set(__wf_id, __wf_fn);
@@ -127176,7 +127869,7 @@ var Run = class _Run {
     value: "completedAt",
     configurable: true
   });
-})(Object.getOwnPropertyDescriptor(Run.prototype, "completedAt").get, "step//@workflow/core/runtime/run@5.0.0-beta.47//Run#completedAt");
+})(Object.getOwnPropertyDescriptor(Run.prototype, "completedAt").get, "step//@workflow/core/runtime/run@5.0.0-beta.48//Run#completedAt");
 (function(__wf_cls, __wf_id) {
   var __wf_sym = /* @__PURE__ */ Symbol.for("workflow-class-registry"), __wf_reg = globalThis[__wf_sym] || (globalThis[__wf_sym] = /* @__PURE__ */ new Map());
   __wf_reg.set(__wf_id, __wf_cls);
@@ -127186,7 +127879,7 @@ var Run = class _Run {
     enumerable: false,
     configurable: false
   });
-})(Run, "class//@workflow/core/runtime/run@5.0.0-beta.47//Run");
+})(Run, "class//@workflow/core/runtime/run@5.0.0-beta.48//Run");
 async function fetch2(...args) {
   return globalThis.fetch(...args);
 }
@@ -128089,10 +128782,11 @@ init_constants3();
 init_helpers3();
 init_replay_recovery_reporter();
 init_unserializable_step();
-async function createHookEvent({ runId, hookEvent, queueItem, requestId, createEvent }) {
+async function createHookEvent({ runId, hookEvent, queueItem, requestId, sinceCursor, createEvent }) {
   try {
     const result2 = await createEvent(hookEvent, {
-      requestId
+      requestId,
+      ...sinceCursor === void 0 ? {} : { sinceCursor }
     });
     if (result2.event?.eventType === "hook_conflict") {
       return {
@@ -128153,7 +128847,10 @@ async function handleSuspension({ suspension, world, run: run3, span, requestId,
   const reporter = replayRecoveryReporter ?? ReplayRecoveryReporter.inert();
   const createEvent = /* @__PURE__ */ __name((data, params) => reporter.withEventCreate(params, (p) => world.events.create(runId, data, p)), "createEvent");
   let reportedEvents = 0;
+  let guardedWrites = 0;
+  let deltaAbsorbed = false;
   const createGuarded = /* @__PURE__ */ __name(async (data, params) => {
+    guardedWrites++;
     if (!eventLog) {
       return createEvent(data, params);
     }
@@ -128162,6 +128859,13 @@ async function handleSuspension({ suspension, world, run: run3, span, requestId,
       ...params,
       ...slotSnapshotParams(log.events)
     });
+    if (typeof params?.sinceCursor === "string") {
+      if (log.cursor === params.sinceCursor && result2.events !== void 0 && result2.hasMore !== true) {
+        appendEventLog(log, { events: result2.events, cursor: result2.cursor });
+        deltaAbsorbed = true;
+      }
+      return result2;
+    }
     const report = absorbSkippedSlotReport(log.events, result2);
     reportedEvents += report.added;
     if (report.truncated) {
@@ -128249,9 +128953,10 @@ async function handleSuspension({ suspension, world, run: run3, span, requestId,
     }
   }
   __name(disposeHook, "disposeHook");
-  let hasHookConflict = false;
-  let hasAwaitedHookCreation = false;
+  const hookConflictCorrelationIds = [];
+  const awaitedHookCorrelationIds = [];
   let hookCreationMs = 0;
+  const hookDeltaCursor = hooksNeedingCreation.length === 1 && typeof eventLog?.cursor === "string" ? eventLog.cursor : void 0;
   if (hookItemsByToken.size > 0) {
     const hookPhaseStart = Date.now();
     await ensureRunReady();
@@ -128280,10 +128985,15 @@ async function handleSuspension({ suspension, world, run: run3, span, requestId,
             hookEvent,
             queueItem,
             requestId,
+            sinceCursor: hookDeltaCursor,
             createEvent: createGuarded
           });
-          hasHookConflict ||= result2.hasHookConflict;
-          hasAwaitedHookCreation ||= result2.hasAwaitedHookCreation;
+          if (result2.hasHookConflict) {
+            hookConflictCorrelationIds.push(queueItem.correlationId);
+          }
+          if (result2.hasAwaitedHookCreation) {
+            awaitedHookCorrelationIds.push(queueItem.correlationId);
+          }
           creationConflicted = result2.hasHookConflict;
         }
         if (queueItem.disposed && !creationConflicted) {
@@ -128406,7 +129116,7 @@ async function handleSuspension({ suspension, world, run: run3, span, requestId,
     failedStepCorrelationIds.add(queueItem.correlationId);
     lazyInlineCorrelationIds.delete(queueItem.correlationId);
   }, "finalizeUnserializableStep");
-  const lazyInlineCorrelationIds = new Set(hasAwaitedHookCreation === false ? stepItems.filter((item) => stepsNeedingCreation.has(item.correlationId)).slice(0, getMaxInlineSteps()).map((item) => item.correlationId) : []);
+  const lazyInlineCorrelationIds = new Set(awaitedHookCorrelationIds.length === 0 ? stepItems.filter((item) => stepsNeedingCreation.has(item.correlationId)).slice(0, getMaxInlineSteps()).map((item) => item.correlationId) : []);
   const lazyInlineByCorrelationId = /* @__PURE__ */ new Map();
   const ops = [];
   const queuedStepCorrelationIds = /* @__PURE__ */ new Set();
@@ -128903,11 +129613,18 @@ async function handleSuspension({ suspension, world, run: run3, span, requestId,
     inlineClaims,
     batchCommittedSlotCeiling,
     deferredBatchWork,
-    // On hook conflict the caller re-invokes immediately and never reads
-    // the wait timeout, so don't report one.
-    waitTimeout: hasHookConflict ? void 0 : soonestWait,
-    hasHookConflict,
-    hasAwaitedHookCreation,
+    // On hook conflict the caller advances the workflow over the conflict
+    // before scheduling anything and never reads the wait timeout, so don't
+    // report one. The next pass, which sees the conflict settled, reports it.
+    waitTimeout: hookConflictCorrelationIds.length > 0 ? void 0 : soonestWait,
+    hasHookConflict: hookConflictCorrelationIds.length > 0,
+    hookConflictCorrelationIds,
+    hasAwaitedHookCreation: awaitedHookCorrelationIds.length > 0,
+    awaitedHookCorrelationIds,
+    // The delta accounts for the whole log only if the write that returned it
+    // was this suspension's only one — anything written after it landed above
+    // the delta and is missing from the caller's log.
+    eventLogCarriedForward: deltaAbsorbed && guardedWrites === 1,
     hasAttributeEvents: attributeItems.length > 0,
     hasHookEvents: hooksNeedingCreation.length > 0,
     hookCreationMs,
@@ -130092,7 +130809,6 @@ __name(createCreateHook, "createCreateHook");
 init_dist7();
 init_dist5();
 init_events_consumer2();
-init_global2();
 init_private2();
 function createSleep(ctx) {
   return /* @__PURE__ */ __name(async function sleepImpl(param) {
@@ -130107,9 +130823,7 @@ function createSleep(ctx) {
     ctx.invocationsQueue.set(correlationId, waitItem);
     ctx.eventsConsumer.subscribe((event) => {
       if (!event) {
-        scheduleWhenIdle(ctx, () => {
-          ctx.onWorkflowError(new WorkflowSuspension2(ctx.invocationsQueue, ctx.globalThis));
-        });
+        scheduleWorkflowSuspension(ctx);
         return EventConsumerResult2.NotConsumed;
       }
       if (event.correlationId !== correlationId) {
@@ -131108,9 +131822,9 @@ var Run2 = class _Run2 {
     return this.#encryptionKeyPromise;
   }
   /**
-   * Defer fetching the run and its encryption key until serialized stream data
-   * is actually read. An empty or metadata-only stream must not start an
-   * unobserved run lookup.
+   * Defers fetching the run and its encryption key until a readable is first
+   * consumed. The first pull prefetches it so an encrypted first frame can join
+   * the lookup; this also applies to an empty consumed stream.
    * @internal
    */
   #getEncryptionKeyLazily() {
@@ -131223,10 +131937,7 @@ var Run2 = class _Run2 {
     const { ops = [], global: global2 = globalThis, startIndex, namespace } = options;
     const name = getWorkflowRunStreamId2(this.runId, namespace);
     const encryptionKey = this.#getEncryptionKeyLazily();
-    const stream = getExternalRevivers2(global2, ops, this.runId, encryptionKey).ReadableStream({
-      name,
-      startIndex
-    });
+    const stream = getRunReadableStream2(global2, ops, this.runId, name, startIndex, encryptionKey);
     const worldPromise = this.#lazyWorldPromise;
     const runId = this.runId;
     return Object.assign(stream, {
@@ -131463,7 +132174,7 @@ function openHookAndWaitState(events) {
   return { openHook: hooks.size > 0, openWait: waits.size > 0 };
 }
 __name(openHookAndWaitState, "openHookAndWaitState");
-function getRetentionDecision({ suspension, serializationBlockerCount, hasOpenWait }) {
+function getRetentionDecision({ suspension, serializationBlockerCount, hookContinuation = false }) {
   if (!isVmRetentionEnabled()) {
     return { retain: false, reason: "disabled" };
   }
@@ -131473,27 +132184,12 @@ function getRetentionDecision({ suspension, serializationBlockerCount, hasOpenWa
       reason: "serialization_executed_workflow_code"
     };
   }
+  if (hookContinuation) {
+    return { retain: true };
+  }
   if (suspension.stepCount === 0 && suspension.attributeCount === 0) {
     return { retain: false, reason: "no_replay_driver" };
   }
-  if (!suspension.items.every((item) => {
-    switch (item.type) {
-      case "step":
-      case "hook":
-      case "attribute":
-        return true;
-      case "wait":
-        return false;
-      default:
-        item;
-        throw new Error("Unknown workflow suspension item");
-    }
-  })) {
-    return { retain: false, reason: "unsupported_suspension_item" };
-  }
-  if (hasOpenWait()) {
-    return { retain: false, reason: "open_wait" };
-  }
   return { retain: true };
 }
 __name(getRetentionDecision, "getRetentionDecision");
@@ -131522,11 +132218,6 @@ function nextEventLogLoad(log) {
   };
 }
 __name(nextEventLogLoad, "nextEventLogLoad");
-function appendEventLog(log, appended) {
-  appendUniqueEvents(log.events, appended.events);
-  log.cursor = appended.cursor ?? log.cursor;
-}
-__name(appendEventLog, "appendEventLog");
 async function getMaxInlineDurationMs(world, invocationStartTime) {
   const rawEnvOverride = process.env.WORKFLOW_V2_TIMEOUT_MS;
   if (rawEnvOverride !== void 0 && rawEnvOverride !== "") {
@@ -132398,6 +133089,7 @@ function workflowEntrypoint(workflowCode2, options) {
             }
           }
           let retainedSession = null;
+          const continuedHookIds = /* @__PURE__ */ new Set();
           while (true) {
             loopIteration++;
             if (replayBudget.isExhausted()) {
@@ -132740,7 +133432,10 @@ function workflowEntrypoint(workflowCode2, options) {
                 const retentionDecision = retainedSession ? getRetentionDecision({
                   suspension: err,
                   serializationBlockerCount: suspensionResult.serializationBlockerCount,
-                  hasOpenWait: /* @__PURE__ */ __name(() => openHookWait.value.openWait, "hasOpenWait")
+                  // This suspension committed the event a hook's
+                  // own awaiter is parked on; the continuation
+                  // below drives the next iteration in-process.
+                  hookContinuation: suspensionResult.hasAwaitedHookCreation || suspensionResult.hasHookConflict
                 }) : void 0;
                 if (retentionDecision?.retain === false) {
                   retainedSession = null;
@@ -132765,7 +133460,37 @@ function workflowEntrypoint(workflowCode2, options) {
                   } : {},
                   ...suspensionResult.serializationBlockerCount > 0 ? serializationBlockerLogMetadata(suspensionResult.serializationBlockers, suspensionResult.serializationBlockerCount) : {}
                 });
+                const continueOverHookWrite = /* @__PURE__ */ __name((hookIds, settles) => {
+                  if (!retainedSession)
+                    return false;
+                  const fresh = hookIds.filter((id) => !continuedHookIds.has(id));
+                  if (fresh.length === 0)
+                    return false;
+                  for (const id of fresh) {
+                    continuedHookIds.add(id);
+                  }
+                  const resumeWithoutRead = suspensionResult.eventLogCarriedForward && !openHookWait.value.openWait;
+                  if (!resumeWithoutRead) {
+                    assert6(eventLog.type === "ready");
+                    eventLog = nextEventLogLoad(eventLog);
+                  }
+                  runtimeLogger2.debug("Continuing over a hook write in-process", {
+                    workflowRunId: runId,
+                    loopIteration,
+                    settles,
+                    hookIds: fresh,
+                    carriedForward: suspensionResult.eventLogCarriedForward,
+                    readBeforeResume: !resumeWithoutRead
+                  });
+                  span?.setAttributes({
+                    "workflow.hook_write_continuations": continuedHookIds.size
+                  });
+                  return true;
+                }, "continueOverHookWrite");
                 if (suspensionResult.hasHookConflict) {
+                  if (continueOverHookWrite(suspensionResult.hookConflictCorrelationIds, "hook_conflict")) {
+                    continue;
+                  }
                   return await reinvoke(0);
                 }
                 if (suspensionResult.hasAttributeEvents) {
@@ -132893,6 +133618,9 @@ function workflowEntrypoint(workflowCode2, options) {
                     suspensionResult.deferredBatchWork
                   ]);
                   if (suspensionResult.hasAwaitedHookCreation) {
+                    if (continueOverHookWrite(suspensionResult.awaitedHookCorrelationIds, "hook_created")) {
+                      continue;
+                    }
                     return await reinvoke(0);
                   }
                   return;
@@ -133753,6 +134481,30 @@ function parseDurationToDate(param) {
 }
 __name(parseDurationToDate, "parseDurationToDate");
 
+// ../errors/dist/error-codes.js
+var RUN_ERROR_CODES = {
+  /** Error thrown in user workflow or step code */
+  USER_ERROR: "USER_ERROR",
+  /** Internal runtime error (missing timestamps, runtime invariant failures) */
+  RUNTIME_ERROR: "RUNTIME_ERROR",
+  /** Event log contains orphaned or mismatched events and cannot be replayed */
+  CORRUPTED_EVENT_LOG: "CORRUPTED_EVENT_LOG",
+  /** One replay could not consume the event log deterministically; retryable */
+  REPLAY_DIVERGENCE: "REPLAY_DIVERGENCE",
+  /** Run exceeded the maximum number of queue deliveries */
+  MAX_DELIVERIES_EXCEEDED: "MAX_DELIVERIES_EXCEEDED",
+  /** Run exceeded the maximum number of events per run */
+  MAX_EVENTS_EXCEEDED: "MAX_EVENTS_EXCEEDED",
+  /** Workflow replay exceeded the maximum allowed duration */
+  REPLAY_TIMEOUT: "REPLAY_TIMEOUT",
+  /** Workflow stream infrastructure failed while reading or writing data */
+  STREAM_ERROR: "STREAM_ERROR",
+  /** World response violated the SDK contract and cannot be retried safely */
+  WORLD_CONTRACT_ERROR: "WORLD_CONTRACT_ERROR",
+  /** Run was delivered to a deployment other than the one it is pinned to */
+  DEPLOYMENT_MISMATCH: "DEPLOYMENT_MISMATCH"
+};
+
 // ../errors/dist/index.js
 var BASE_URL = "https://workflow-sdk.dev/err";
 function isError(value) {
@@ -133827,6 +134579,36 @@ Caused by: \${options.cause.stack}\`;
     return isError(value) && value.name === "WorkflowError";
   }
 };
+var WorkflowWorldError = class extends WorkflowError {
+  static {
+    __name(this, "WorkflowWorldError");
+  }
+  status;
+  code;
+  url;
+  /** Retry-After value in seconds, present on 429 and 425 responses */
+  retryAfter;
+  /**
+   * The offending argument, present on client-side validation failures
+   * (\`code: 'INVALID_ARGUMENT'\`). Lets a caller correct the specific
+   * parameter without parsing the message.
+   */
+  field;
+  constructor(message, options) {
+    super(message, {
+      cause: options?.cause
+    });
+    this.name = "WorkflowWorldError";
+    this.status = options?.status;
+    this.code = options?.code;
+    this.url = options?.url;
+    this.retryAfter = options?.retryAfter;
+    this.field = options?.field;
+  }
+  static is(value) {
+    return isError(value) && value.name === "WorkflowWorldError";
+  }
+};
 var WorkflowRuntimeError = class extends WorkflowError {
   static {
     __name(this, "WorkflowRuntimeError");
@@ -133881,6 +134663,23 @@ var HookConflictError = class extends WorkflowError {
     return isError(value) && value.name === "HookConflictError";
   }
 };
+var StreamError = class extends WorkflowWorldError {
+  static {
+    __name(this, "StreamError");
+  }
+  constructor(message, options) {
+    super(message, {
+      code: RUN_ERROR_CODES.STREAM_ERROR,
+      cause: options?.cause,
+      url: options?.url,
+      status: options?.status
+    });
+    this.name = "StreamError";
+  }
+  static is(value) {
+    return isError(value) && value.name === "StreamError";
+  }
+};
 var FatalError = class extends Error {
   static {
     __name(this, "FatalError");
@@ -133921,6 +134720,7 @@ var FATAL_ERROR_KEY = /* @__PURE__ */ Symbol.for("@workflow/errors//FatalError")
 var RETRYABLE_ERROR_KEY = /* @__PURE__ */ Symbol.for("@workflow/errors//RetryableError");
 var HOOK_CONFLICT_ERROR_KEY = /* @__PURE__ */ Symbol.for("@workflow/errors//HookConflictError");
 var RUNTIME_DECRYPTION_ERROR_KEY = /* @__PURE__ */ Symbol.for("@workflow/errors//RuntimeDecryptionError");
+var STREAM_ERROR_KEY = /* @__PURE__ */ Symbol.for("@workflow/errors//StreamError");
 if (typeof globalThis !== "undefined") {
   if (!Object.hasOwn(globalThis, FATAL_ERROR_KEY)) {
     Object.defineProperty(globalThis, FATAL_ERROR_KEY, {
@@ -133954,6 +134754,14 @@ if (typeof globalThis !== "undefined") {
       configurable: false
     });
   }
+  if (!Object.hasOwn(globalThis, STREAM_ERROR_KEY)) {
+    Object.defineProperty(globalThis, STREAM_ERROR_KEY, {
+      value: StreamError,
+      writable: false,
+      enumerable: false,
+      configurable: false
+    });
+  }
 }
 
 // ../core/dist/symbols.js
@@ -134038,10 +134846,10 @@ var Run = class _Run {
     return this.getReadable();
   }
 };
-Run.prototype["wakeUp"] = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.47//Run#wakeUp");
-Run.prototype["cancel"] = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.47//Run#cancel");
-Run.prototype["getReadable"] = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.47//Run#getReadable");
-var __step_Run$exists = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.47//Run#exists");
+Run.prototype["wakeUp"] = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.48//Run#wakeUp");
+Run.prototype["cancel"] = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.48//Run#cancel");
+Run.prototype["getReadable"] = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.48//Run#getReadable");
+var __step_Run$exists = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.48//Run#exists");
 Object.defineProperty(Run.prototype, "exists", {
   get() {
     return __step_Run$exists.call(this);
@@ -134049,7 +134857,7 @@ Object.defineProperty(Run.prototype, "exists", {
   configurable: true,
   enumerable: false
 });
-var __step_Run$status = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.47//Run#status");
+var __step_Run$status = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.48//Run#status");
 Object.defineProperty(Run.prototype, "status", {
   get() {
     return __step_Run$status.call(this);
@@ -134057,7 +134865,7 @@ Object.defineProperty(Run.prototype, "status", {
   configurable: true,
   enumerable: false
 });
-var __step_Run$returnValue = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.47//Run#returnValue");
+var __step_Run$returnValue = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.48//Run#returnValue");
 Object.defineProperty(Run.prototype, "returnValue", {
   get() {
     return __step_Run$returnValue.call(this);
@@ -134065,7 +134873,7 @@ Object.defineProperty(Run.prototype, "returnValue", {
   configurable: true,
   enumerable: false
 });
-var __step_Run$workflowName = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.47//Run#workflowName");
+var __step_Run$workflowName = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.48//Run#workflowName");
 Object.defineProperty(Run.prototype, "workflowName", {
   get() {
     return __step_Run$workflowName.call(this);
@@ -134073,7 +134881,7 @@ Object.defineProperty(Run.prototype, "workflowName", {
   configurable: true,
   enumerable: false
 });
-var __step_Run$createdAt = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.47//Run#createdAt");
+var __step_Run$createdAt = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.48//Run#createdAt");
 Object.defineProperty(Run.prototype, "createdAt", {
   get() {
     return __step_Run$createdAt.call(this);
@@ -134081,7 +134889,7 @@ Object.defineProperty(Run.prototype, "createdAt", {
   configurable: true,
   enumerable: false
 });
-var __step_Run$startedAt = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.47//Run#startedAt");
+var __step_Run$startedAt = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.48//Run#startedAt");
 Object.defineProperty(Run.prototype, "startedAt", {
   get() {
     return __step_Run$startedAt.call(this);
@@ -134089,7 +134897,7 @@ Object.defineProperty(Run.prototype, "startedAt", {
   configurable: true,
   enumerable: false
 });
-var __step_Run$completedAt = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.47//Run#completedAt");
+var __step_Run$completedAt = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/run@5.0.0-beta.48//Run#completedAt");
 Object.defineProperty(Run.prototype, "completedAt", {
   get() {
     return __step_Run$completedAt.call(this);
@@ -134106,7 +134914,7 @@ Object.defineProperty(Run.prototype, "completedAt", {
     enumerable: false,
     configurable: false
   });
-})(Run, "class//@workflow/core/runtime/run@5.0.0-beta.47//Run");
+})(Run, "class//@workflow/core/runtime/run@5.0.0-beta.48//Run");
 
 // ../core/dist/workflow/create-hook.js
 aliasSerializationClass(RUN_CLASS_ID, Run);
@@ -138736,7 +139544,7 @@ globalThis.__private_workflows.set("workflow//./workflows/inline-execution//hook
 var latestNoOpWarning = globalSingleton("@workflow/core//latestNoOpWarning", 1, () => ({
   warned: false
 }));
-var start = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/start@5.0.0-beta.47//start");
+var start = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//@workflow/core/runtime/start@5.0.0-beta.48//start");
 
 // workflows/lineage.ts
 var noop = globalThis[/* @__PURE__ */ Symbol.for("WORKFLOW_USE_STEP")]("step//./workflows/lineage//noop");