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

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

@@ -370,6 +370,8 @@ var init_error_codes = __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 */
@@ -410,12 +412,13 @@ function buildFramedDetails(hint2, slug) {
   });
   return out;
 }
-var BASE_URL, ERROR_SLUGS, WorkflowError, WorkflowWorldError, WorkflowRunFailedError, WorkflowRunNotCompletedError, WorkflowRuntimeError, RuntimeDecryptionError, SerializationError, StepNotRegisteredError, WorkflowNotRegisteredError, WorkflowRunNotFoundError, HookConflictError, HookNotFoundError, EntityConflictError, RunExpiredError, StreamExpiredError, ThrottleError, WorkflowRunCancelledError, FatalError, RetryableError, FATAL_ERROR_KEY, RETRYABLE_ERROR_KEY, HOOK_CONFLICT_ERROR_KEY, RUNTIME_DECRYPTION_ERROR_KEY;
+var BASE_URL, ERROR_SLUGS, WorkflowError, WorkflowWorldError, WorkflowRunFailedError, WorkflowRunNotCompletedError, WorkflowRuntimeError, RuntimeDecryptionError, SerializationError, StepNotRegisteredError, WorkflowNotRegisteredError, WorkflowRunNotFoundError, HookConflictError, HookNotFoundError, EntityConflictError, RunExpiredError, StreamError, StreamExpiredError, ThrottleError, WorkflowRunCancelledError, FatalError, RetryableError, FATAL_ERROR_KEY, RETRYABLE_ERROR_KEY, HOOK_CONFLICT_ERROR_KEY, RUNTIME_DECRYPTION_ERROR_KEY, STREAM_ERROR_KEY;
 var init_dist2 = __esm({
   "../errors/dist/index.js"() {
     "use strict";
     init_dist();
     init_error_codes();
+    init_error_codes();
     BASE_URL = "https://workflow-sdk.dev/err";
     __name(isError, "isError");
     __name(appendFramedDetails, "appendFramedDetails");
@@ -467,6 +470,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
@@ -476,6 +485,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";
@@ -678,14 +688,40 @@ Caused by: ${options.cause.stack}`;
       static {
         __name(this, "RunExpiredError");
       }
-      constructor(message) {
-        super(message);
+      runId;
+      runStatus;
+      expiredAt;
+      constructor(message, runId, runStatus, expiredAt) {
+        super(message, {
+          status: 410,
+          code: "run-expired"
+        });
+        this.runId = runId;
+        this.runStatus = runStatus;
+        this.expiredAt = expiredAt;
         this.name = "RunExpiredError";
       }
       static is(value) {
         return isError(value) && value.name === "RunExpiredError";
       }
     };
+    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";
+      }
+    };
     StreamExpiredError = class extends WorkflowWorldError {
       static {
         __name(this, "StreamExpiredError");
@@ -775,6 +811,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, {
@@ -808,6 +845,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
+        });
+      }
     }
   }
 });
@@ -18493,13 +18538,14 @@ function validateAttributeChanges(changes, context = {}) {
   }
   validateAttributeBatchConstraints(changes, context);
 }
-var RESERVED_ATTRIBUTE_KEY_PREFIX, ROOT_RUN_ID_ATTRIBUTE, PARENT_RUN_ID_ATTRIBUTE, ATTRIBUTE_KEY_MAX_LENGTH, ATTRIBUTE_VALUE_MAX_BYTES, ATTRIBUTE_MAX_PER_RUN, textEncoder, AttributeValidationError;
+var RESERVED_ATTRIBUTE_KEY_PREFIX, ROOT_RUN_ID_ATTRIBUTE, PARENT_RUN_ID_ATTRIBUTE, RETENTION_ATTRIBUTE, ATTRIBUTE_KEY_MAX_LENGTH, ATTRIBUTE_VALUE_MAX_BYTES, ATTRIBUTE_MAX_PER_RUN, textEncoder, AttributeValidationError;
 var init_attributes_validation = __esm({
   "../world/dist/attributes-validation.js"() {
     "use strict";
     RESERVED_ATTRIBUTE_KEY_PREFIX = "$";
     ROOT_RUN_ID_ATTRIBUTE = `${RESERVED_ATTRIBUTE_KEY_PREFIX}rootRunId`;
     PARENT_RUN_ID_ATTRIBUTE = `${RESERVED_ATTRIBUTE_KEY_PREFIX}parentRunId`;
+    RETENTION_ATTRIBUTE = `${RESERVED_ATTRIBUTE_KEY_PREFIX}retention`;
     ATTRIBUTE_KEY_MAX_LENGTH = 256;
     ATTRIBUTE_VALUE_MAX_BYTES = 256;
     ATTRIBUTE_MAX_PER_RUN = 64;
@@ -19109,7 +19155,7 @@ var init_runs = __esm({
       // 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()
       }),
@@ -19117,7 +19163,7 @@ var init_runs = __esm({
       WorkflowRunBaseSchema.extend({
         status: external_exports.literal("failed"),
         output: external_exports.undefined().optional(),
-        error: SerializedDataSchema,
+        error: SerializedDataSchema.optional(),
         completedAt: external_exports.coerce.date()
       })
     ]);
@@ -19373,8 +19419,8 @@ var init_analytics = __esm({
     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
     });
   }
 });
@@ -20442,6 +20488,18 @@ function getCommonReducers(_global = globalThis) {
       }
       return reduced;
     }, "RuntimeDecryptionError"),
+    StreamError: /* @__PURE__ */ __name((value) => {
+      const base = reduceNamedErrorSubclassBase("StreamError", value);
+      if (!base) return false;
+      const reduced = {
+        ...base
+      };
+      const status = readProperty(value, "status");
+      const url2 = readProperty(value, "url");
+      if (typeof status === "number") reduced.status = status;
+      if (typeof url2 === "string") reduced.url = url2;
+      return reduced;
+    }, "StreamError"),
     SyntaxError: makeErrorSubclassReducer("SyntaxError"),
     TypeError: makeErrorSubclassReducer("TypeError"),
     URIError: makeErrorSubclassReducer("URIError"),
@@ -20575,6 +20633,18 @@ function getCommonRevivers(global2 = globalThis) {
       if (value.stack !== void 0) error48.stack = value.stack;
       return error48;
     }, "RuntimeDecryptionError"),
+    StreamError: /* @__PURE__ */ __name((value) => {
+      const Ctor = global2[/* @__PURE__ */ Symbol.for("@workflow/errors//StreamError")] ?? StreamError;
+      const error48 = new Ctor(value.message, {
+        ..."cause" in value ? {
+          cause: value.cause
+        } : {},
+        status: value.status,
+        url: value.url
+      });
+      if (value.stack !== void 0) error48.stack = value.stack;
+      return error48;
+    }, "StreamError"),
     SyntaxError: makeErrorSubclassReviver(global2, "SyntaxError"),
     TypeError: makeErrorSubclassReviver(global2, "TypeError"),
     URIError: makeErrorSubclassReviver(global2, "URIError"),
@@ -25982,7 +26052,7 @@ var version2;
 var init_version = __esm({
   "../core/dist/version.js"() {
     "use strict";
-    version2 = "5.0.0-beta.47";
+    version2 = "5.0.0-beta.49";
   }
 });
 
@@ -31690,6 +31760,18 @@ function recordReadTimeToFirstChunk(startEpochMs, runId, name, startIndex, conne
     });
   })();
 }
+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
+      }
+    });
+  })();
+}
 function recordStreamReadComplete(startEpochMs, runId, name, chunkCount, byteCount, reconnects) {
   void (async () => {
     await recordElapsedSpan("workflow.stream.read.complete", startEpochMs, {
@@ -31708,26 +31790,46 @@ function recordStreamReadComplete(startEpochMs, runId, name, chunkCount, byteCou
     });
   })();
 }
-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 buffer2 = 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");
   async function connect() {
+    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(connect, "connect");
   async function isVerifiedComplete() {
@@ -31741,11 +31843,13 @@ function createReconnectingFramedStream(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;
     buffer2 = new Uint8Array(0);
@@ -31755,15 +31859,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 connect();
-        return;
+        if (!await connect()) return false;
+        return true;
       } catch (error48) {
+        if (canceled) return false;
         if (StreamExpiredError.is(error48)) throw error48;
       }
     }
@@ -31771,12 +31876,15 @@ function createReconnectingFramedStream(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 connect();
+            if (!await connect()) return;
           } catch (err) {
+            if (canceled) return;
             controller.error(err);
             return;
           }
@@ -31785,23 +31893,27 @@ function createReconnectingFramedStream(runId, name, startIndex) {
         try {
           result = 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 (result.done || !result.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;
@@ -31843,12 +31955,15 @@ function createReconnectingFramedStream(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")
   });
@@ -32353,7 +32468,87 @@ async function getForwardedWritableEncryptionKey(runId, deploymentId, encryption
     "encrypt"
   ]) : void 0;
 }
-function getExternalRevivers(global2 = globalThis, ops, runId, cryptoKey) {
+function tagForwardedWritableTarget(writable, { deploymentId, encryptionPublicKey }) {
+  if (typeof deploymentId === "string") {
+    Object.defineProperty(writable, STREAM_SERVER_DEPLOYMENT_ID_SYMBOL, {
+      value: deploymentId,
+      writable: false
+    });
+  }
+  if (typeof encryptionPublicKey === "string") {
+    Object.defineProperty(writable, STREAM_SERVER_PUBLIC_KEY_SYMBOL, {
+      value: encryptionPublicKey,
+      writable: false
+    });
+  }
+}
+function createForwardedWritable({ global: global2, ops, runId, name, key, deploymentId, encryptionPublicKey, runReadyBarrier }) {
+  const serialize3 = getSerializeStream(getExternalReducers(global2, ops, runId, key), key);
+  const serverWritable = new WorkflowServerWritableStream(runId, name, runReadyBarrier);
+  const state = createFlushableState();
+  ops.push(state.promise);
+  flushablePipe(serialize3.readable, serverWritable, state).catch(() => {
+  });
+  pollWritableLock(serialize3.writable, state);
+  Object.defineProperty(serialize3.writable, STREAM_NAME_SYMBOL, {
+    value: name,
+    writable: false
+  });
+  Object.defineProperty(serialize3.writable, STREAM_SERVER_RUN_ID_SYMBOL, {
+    value: runId,
+    writable: false
+  });
+  tagForwardedWritableTarget(serialize3.writable, {
+    deploymentId,
+    encryptionPublicKey
+  });
+  return serialize3.writable;
+}
+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__ */ __name((state) => {
+                lockState = state;
+              }, "onReadableState")
+            }).ReadableStream({
+              name,
+              startIndex
+            });
+            reader = stream.getReader();
+            if (lockState && !lockPollingStarted) {
+              lockPollingStarted = true;
+              pollReadableLock(userReadable, lockState);
+            }
+          }
+          const result = await reader.read();
+          if (result.done) controller.close();
+          else controller.enqueue(result.value);
+        } catch (error48) {
+          controller.error(error48);
+        }
+      },
+      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 getExternalRevivers(global2 = globalThis, ops, runId, cryptoKey, options) {
   return {
     ...getCommonRevivers2(global2),
     // StepFunction should not be returned from workflows to clients
@@ -32401,50 +32596,38 @@ 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 transform2 = getDeserializeStream(getExternalRevivers(global2, ops, runId, cryptoKey), cryptoKey);
+        let keyPromise;
+        const resolveKey = /* @__PURE__ */ __name(() => {
+          keyPromise ??= resolveEncryptionKey(cryptoKey);
+          return keyPromise;
+        }, "resolveKey");
+        const readable = createReconnectingFramedStream(runId, value.name, value.startIndex, resolveKey);
+        const transform2 = getDeserializeStream(getExternalRevivers(global2, ops, runId, resolveKey), resolveKey);
         const state = createFlushableState();
         ops.push(state.promise);
         flushablePipe(readable, transform2.writable, state).catch(() => {
         });
-        pollReadableLock(transform2.readable, state);
+        if (options?.onReadableState) options.onReadableState(state);
+        else pollReadableLock(transform2.readable, state);
         return transform2.readable;
       }
     }, "ReadableStream"),
     WritableStream: /* @__PURE__ */ __name((value) => {
       const targetRunId = typeof value.runId === "string" ? value.runId : runId;
       const targetKey = targetRunId === runId ? cryptoKey : getForwardedWritableEncryptionKey(targetRunId, value.deploymentId, value.encryptionPublicKey);
-      const serialize3 = getSerializeStream(getExternalReducers(global2, ops, targetRunId, targetKey), targetKey);
-      const serverWritable = new WorkflowServerWritableStream(targetRunId, value.name);
-      const state = createFlushableState();
-      ops.push(state.promise);
-      flushablePipe(serialize3.readable, serverWritable, state).catch(() => {
-      });
-      pollWritableLock(serialize3.writable, state);
-      Object.defineProperty(serialize3.writable, STREAM_NAME_SYMBOL, {
-        value: value.name,
-        writable: false
-      });
-      Object.defineProperty(serialize3.writable, STREAM_SERVER_RUN_ID_SYMBOL, {
-        value: targetRunId,
-        writable: false
+      return createForwardedWritable({
+        global: global2,
+        ops,
+        runId: targetRunId,
+        name: value.name,
+        key: targetKey,
+        deploymentId: value.deploymentId,
+        encryptionPublicKey: value.encryptionPublicKey
       });
-      if (typeof value.deploymentId === "string") {
-        Object.defineProperty(serialize3.writable, STREAM_SERVER_DEPLOYMENT_ID_SYMBOL, {
-          value: value.deploymentId,
-          writable: false
-        });
-      }
-      if (typeof value.encryptionPublicKey === "string") {
-        Object.defineProperty(serialize3.writable, STREAM_SERVER_PUBLIC_KEY_SYMBOL, {
-          value: value.encryptionPublicKey,
-          writable: false
-        });
-      }
-      return serialize3.writable;
     }, "WritableStream"),
     AbortController: /* @__PURE__ */ __name((value) => reviveAbortController(value, ops, runId), "AbortController"),
     AbortSignal: /* @__PURE__ */ __name((value) => reviveAbortSignal(value, ops, runId), "AbortSignal")
@@ -32806,6 +32989,7 @@ var init_serialization2 = __esm({
     __name(getByteFramingStream, "getByteFramingStream");
     __name(getByteUnframingStream, "getByteUnframingStream");
     __name(recordReadTimeToFirstChunk, "recordReadTimeToFirstChunk");
+    __name(recordStreamReadKeyResolution, "recordStreamReadKeyResolution");
     __name(recordStreamReadComplete, "recordStreamReadComplete");
     WorkflowServerReadableStream = class extends ReadableStream {
       static {
@@ -32916,6 +33100,14 @@ var init_serialization2 = __esm({
             pendingRunReady = void 0;
           }
         }, "ensureRunReady");
+        const writerId = `wrtr_${defaultUlid()}`;
+        const writeSessionPromise = ensureRunReady().then(async () => {
+          const world = await worldPromise;
+          return world.streams.createWriteSession?.(runId, name, {
+            writerId
+          });
+        });
+        let nextChunkSeq = 0;
         let buffer2 = [];
         let bufferBytes = 0;
         let inFlightChunks = 0;
@@ -32961,14 +33153,18 @@ var init_serialization2 = __esm({
         const sendGroup = /* @__PURE__ */ __name(async (group, bytes, groupT0) => {
           await ensureRunReady();
           const world = await worldPromise;
+          const session = await writeSessionPromise;
           const dispatchAt = Date.now();
-          if (typeof world.streams.writeMulti === "function" && group.length > 1) {
+          if (session) {
+            await session.write(nextChunkSeq, group);
+          } else if (typeof world.streams.writeMulti === "function" && group.length > 1) {
             await world.streams.writeMulti(runId, name, group);
           } else {
             for (const chunk of group) {
               await world.streams.write(runId, name, chunk);
             }
           }
+          nextChunkSeq += group.length;
           if (groupT0 !== void 0) {
             recordStreamWriteFlush(groupT0, dispatchAt, runId, name, group.length, bytes, Date.now() - dispatchAt);
           }
@@ -33079,8 +33275,13 @@ var init_serialization2 = __esm({
             await drain();
             await ensureRunReady();
             const world = await worldPromise;
+            const session = await writeSessionPromise;
             const closeStart = Date.now();
-            await world.streams.close(runId, name);
+            if (session) {
+              await session.close();
+            } else {
+              await world.streams.close(runId, name);
+            }
             recordStreamClose(closeStart, runId, name);
           },
           async abort(reason) {
@@ -33096,6 +33297,8 @@ var init_serialization2 = __esm({
             bufferBytes = 0;
             sinkError ??= reason ?? new Error("Stream aborted");
             rejectWaiters(sinkError);
+            const session = await writeSessionPromise.catch(() => void 0);
+            await session?.dispose?.();
           }
         });
         Object.defineProperty(this, STREAM_DRAIN_SYMBOL, {
@@ -33120,6 +33323,9 @@ var init_serialization2 = __esm({
     __name(reviveAbortSignal, "reviveAbortSignal");
     __name(getCommonRevivers2, "getCommonRevivers");
     __name(getForwardedWritableEncryptionKey, "getForwardedWritableEncryptionKey");
+    __name(tagForwardedWritableTarget, "tagForwardedWritableTarget");
+    __name(createForwardedWritable, "createForwardedWritable");
+    __name(getRunReadableStream, "getRunReadableStream");
     __name(getExternalRevivers, "getExternalRevivers");
     __name(getStepRevivers, "getStepRevivers");
     __name(dehydrateWorkflowArguments, "dehydrateWorkflowArguments");
@@ -33298,7 +33504,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,
@@ -33314,6 +33521,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;
   }
@@ -33356,6 +33566,7 @@ __name(getWorkflowVmFromEnv, "getWorkflowVmFromEnv");
 init_wait_until();
 init_world_compatibility();
 var CROSS_DEPLOYMENT_CAPABILITY_PROBE_TIMEOUT_MS = 2e3;
+var RETENTION_ZERO_ATTRIBUTE_VALUE = "0";
 var ulid3 = monotonicFactory();
 function resolveLineageAttributes() {
   const store = contextStorage.getStore();
@@ -33460,14 +33671,27 @@ async function start(workflow, argsOrOptions, options) {
           value
         ]));
       }
+      let retentionAttribute;
+      if (opts.experimental_retention !== void 0 && opts.experimental_retention !== "default") {
+        if (opts.experimental_retention !== 0) {
+          throw new WorkflowRuntimeError(`start({ experimental_retention }) must be 0 or 'default'; received ${JSON.stringify(opts.experimental_retention)}.`);
+        }
+        if (specVersion < SPEC_VERSION_SUPPORTS_ATTRIBUTES) {
+          throw new WorkflowRuntimeError("start({ experimental_retention }) requires a World that supports spec version 4 or later.");
+        }
+        retentionAttribute = {
+          [RETENTION_ATTRIBUTE]: RETENTION_ZERO_ATTRIBUTE_VALUE
+        };
+      }
       const lineage = specVersion >= SPEC_VERSION_SUPPORTS_ATTRIBUTES ? resolveLineageAttributes() : void 0;
-      const runAttributes = lineage ? {
+      const runAttributes = lineage || retentionAttribute ? {
         ...lineage,
-        ...attributes
+        ...attributes,
+        ...retentionAttribute
       } : attributes;
       const attributeSeed = runAttributes ? {
         attributes: runAttributes,
-        ...allowReservedAttributes || lineage != null ? {
+        ...allowReservedAttributes || lineage != null || retentionAttribute != null ? {
           allowReservedAttributes: true
         } : {}
       } : {};
@@ -33613,7 +33837,7 @@ __name(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.49//start");
 
 // ../core/dist/runtime/runs.js
 async function wakeUpRun(world, runId, options) {
@@ -33704,6 +33928,11 @@ var PAYLOAD_TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set([
   "completed",
   "failed"
 ]);
+var NOT_FOUND_RETRY_DELAYS = [
+  1e3,
+  3e3,
+  6e3
+];
 function getReturnValuePollIntervalMs() {
   return envNumber("WORKFLOW_RETURN_VALUE_POLL_INTERVAL_MS", RETURN_VALUE_POLL_INTERVAL_MS, {
     integer: true,
@@ -33797,9 +34026,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() {
@@ -33910,10 +34139,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, {
@@ -33924,8 +34150,75 @@ var Run = class _Run {
       }, "getTailIndex")
     });
   }
+  /** The writable stream of the workflow run. */
+  get writable() {
+    return this.getWritable();
+  }
+  /**
+   * Returns a writable that appends to this run's stream.
+   *
+   * Initialization is deferred until the first write. The run must already
+   * exist. The writable may be forwarded through `start()` and into steps, but
+   * grants no read access or additional authorization.
+   *
+   * @remarks
+   * `writer.close()` closes the shared stream. Contributors should call
+   * `releaseLock()`, which also drains pending writes.
+   *
+   * @param options - The writable stream options.
+   */
+  getWritable(options = {}) {
+    const { ops = [], global: global2 = globalThis, namespace } = options;
+    const name = getWorkflowRunStreamId(this.runId, namespace);
+    let targetPromise;
+    let writable;
+    const resolveTarget = /* @__PURE__ */ __name(() => {
+      targetPromise ??= this.#getMetadata().then(async (run2) => {
+        const target = {
+          key: await getForwardedWritableEncryptionKey(this.runId, run2.deploymentId, run2.encryptionPublicKey),
+          deploymentId: run2.deploymentId,
+          encryptionPublicKey: run2.encryptionPublicKey
+        };
+        tagForwardedWritableTarget(writable, target);
+        return target;
+      });
+      return targetPromise;
+    }, "resolveTarget");
+    writable = createForwardedWritable({
+      global: global2,
+      ops,
+      runId: this.runId,
+      name,
+      key: /* @__PURE__ */ __name(() => resolveTarget().then(({ key }) => key), "key")
+    });
+    return writable;
+  }
+  /** Reads metadata, briefly retrying resilient starts. @internal */
+  async #getMetadata() {
+    const world = await this.#lazyWorldPromise;
+    const maxRetries = this.#resilientStart ? NOT_FOUND_RETRY_DELAYS.length : 0;
+    let attempt = 0;
+    while (true) {
+      try {
+        return await world.runs.get(this.runId, {
+          resolveData: "none"
+        });
+      } catch (error48) {
+        if (!WorkflowRunNotFoundError.is(error48) || attempt >= maxRetries) {
+          throw error48;
+        }
+        const delay = NOT_FOUND_RETRY_DELAYS[attempt];
+        attempt++;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  }
   /** @internal */
   async #resolveTerminalReturnValue(run2) {
+    const expiredAt = run2.expiredAt;
+    if (expiredAt != null && expiredAt <= /* @__PURE__ */ new Date()) {
+      throw new RunExpiredError(`Run "${this.runId}" ${run2.status === "completed" ? "completed" : `is ${run2.status}`}, but its data expired at ${expiredAt.toISOString()} and is no longer readable.`, this.runId, run2.status, expiredAt);
+    }
     if (run2.status === "completed") {
       const encryptionKey = await this.#getEncryptionKey(run2);
       return await hydrateWorkflowReturnValue(run2.output, this.runId, encryptionKey);
@@ -33955,12 +34248,7 @@ var Run = class _Run {
   async #pollReturnValue() {
     const world = await this.#lazyWorldPromise;
     let notFoundRetries = 0;
-    const NOT_FOUND_MAX_RETRIES = this.#resilientStart ? 3 : 0;
-    const NOT_FOUND_DELAYS = [
-      1e3,
-      3e3,
-      6e3
-    ];
+    const NOT_FOUND_MAX_RETRIES = this.#resilientStart ? NOT_FOUND_RETRY_DELAYS.length : 0;
     const waitForTerminalStatus = isReturnValueLongPollEnabled() ? world.runs.waitForTerminalStatus?.bind(world.runs) : void 0;
     let longPolls = 0;
     const maxLongPolls = getReturnValueMaxLongPolls();
@@ -33994,7 +34282,7 @@ var Run = class _Run {
           continue;
         }
         if (WorkflowRunNotFoundError.is(error48) && notFoundRetries < NOT_FOUND_MAX_RETRIES) {
-          const delay = NOT_FOUND_DELAYS[notFoundRetries];
+          const delay = NOT_FOUND_RETRY_DELAYS[notFoundRetries];
           notFoundRetries++;
           await new Promise((resolve) => setTimeout(resolve, delay));
           continue;
@@ -34012,7 +34300,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.49//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);
@@ -34021,7 +34309,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.49//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);
@@ -34030,7 +34318,16 @@ 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.49//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);
+  __wf_fn.stepId = __wf_id;
+  Object.defineProperty(__wf_fn, "name", {
+    value: "getWritable",
+    configurable: true
+  });
+})(Run.prototype["getWritable"], "step//@workflow/core/runtime/run@5.0.0-beta.49//Run#getWritable");
 (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);
@@ -34039,7 +34336,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.49//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);
@@ -34048,7 +34345,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.49//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);
@@ -34057,7 +34354,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.49//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);
@@ -34066,7 +34363,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.49//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);
@@ -34075,7 +34372,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.49//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);
@@ -34084,7 +34381,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.49//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);
@@ -34093,7 +34390,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.49//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);
@@ -34103,7 +34400,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.49//Run");
 
 // ../workflow/dist/stdlib.js
 async function fetch2(...args) {