@workflow/core 5.0.0-beta.4 → 5.0.0-beta.41

package/dist/serialization.d.ts

@@ -1,211 +1,297 @@
-import { type CryptoKey } from './encryption.js';
-/**
- * Encryption key parameter type. Accepts a resolved key, undefined (no encryption),
- * or a promise that resolves to either. This allows synchronous function signatures
- * (e.g., getReadable()) to thread the key through without awaiting it — the promise
- * is resolved lazily inside the first async transform() call.
- */
-export type EncryptionKeyParam = CryptoKey | undefined | Promise<CryptoKey | undefined>;
-/**
- * Known serialization format identifiers.
- * Each format ID is exactly 4 ASCII characters, matching the convention
- * used for other workflow IDs (wrun, step, wait, etc.)
- */
-export declare const SerializationFormat: {
-    /** devalue stringify/parse with TextEncoder/TextDecoder */
-    readonly DEVALUE_V1: "devl";
-    /** Encrypted payload (inner payload has its own format prefix) */
-    readonly ENCRYPTED: "encr";
-};
+import { compress, decompress } from './serialization/compression.js';
+import { aesKeyOf, decrypt, deriveRunPayloadKeys, type EncryptionKeyParam, encrypt, isRunPayloadKeys, isSealTarget, type PayloadKey, type RunPayloadKeys, runPayloadKeys, type SealTarget, sealTo } from './serialization/encryption.js';
+import { decodeFormatPrefix, encodeWithFormatPrefix, isEncrypted, peekFormatPrefix } from './serialization/format.js';
+import { type GuestCodeStats } from './serialization/hardened.js';
+import { type FormatPrefix, isFormatPrefix, SerializationFormat } from './serialization/types.js';
+export { SerializationFormat, type FormatPrefix, isFormatPrefix, encodeWithFormatPrefix, decodeFormatPrefix, peekFormatPrefix, isEncrypted, encrypt, decrypt, compress, decompress, type EncryptionKeyParam, type PayloadKey, type RunPayloadKeys, type SealTarget, sealTo, runPayloadKeys, deriveRunPayloadKeys, isSealTarget, isRunPayloadKeys, aesKeyOf, };
 export type SerializationFormatType = (typeof SerializationFormat)[keyof typeof SerializationFormat];
 /**
- * Encode a payload with a format prefix.
+ * Detect if a readable stream is a byte stream.
  *
- * @param format - The format identifier (must be exactly 4 ASCII characters)
- * @param payload - The serialized payload bytes
- * @returns A new Uint8Array with format prefix prepended
+ * @param stream
+ * @returns `"bytes"` if the stream is a byte stream, `undefined` otherwise
  */
-export declare function encodeWithFormatPrefix(format: SerializationFormatType, payload: Uint8Array | unknown): Uint8Array | unknown;
+export declare function getStreamType(stream: ReadableStream): 'bytes' | undefined;
+export declare function getSerializeStream(reducers: Partial<Reducers>, cryptoKey: EncryptionKeyParam): TransformStream<any, Uint8Array>;
+export declare function getDeserializeStream(revivers: Partial<Revivers>, cryptoKey: EncryptionKeyParam): TransformStream<Uint8Array, any>;
 /**
- * Peek at the format prefix without consuming it.
- * Useful for checking if data is encrypted before deciding how to process it.
+ * Wraps each chunk of a byte stream in a 4-byte big-endian length
+ * prefix. Used by the producer side of a framed byte-stream pipe.
  *
- * @param data - The format-prefixed data
- * @returns The format identifier, or null if data is legacy/non-binary
- */
-export declare function peekFormatPrefix(data: Uint8Array | unknown): SerializationFormatType | null;
-/**
- * Check if data is encrypted (has 'encr' format prefix).
+ * Empty chunks (length 0) are dropped — the resulting `[0x00 0x00 0x00 0x00]`
+ * frame would be ambiguous with the legacy "looks framed" detection in
+ * `getDeserializeStream`, and it carries no information.
  *
- * @param data - The format-prefixed data
- * @returns true if data has the encrypted format prefix
+ * Load-bearing invariant: each user chunk becomes exactly one frame, and
+ * each frame is enqueued as exactly one transport chunk (the downstream
+ * writable performs one wire write per chunk, preserving boundaries). The
+ * server therefore stores one frame per chunk index, which is what allows
+ * a future reconnecting reader to resume a framed byte stream at
+ * `startIndex + consumedFrames` — the same arithmetic
+ * `createReconnectingFramedStream` relies on for object streams. Do not
+ * coalesce or split frames here without revisiting that resume logic.
  */
-export declare function isEncrypted(data: Uint8Array | unknown): boolean;
+export declare function getByteFramingStream(): TransformStream<Uint8Array, Uint8Array>;
 /**
- * Decode a format-prefixed payload.
+ * Unwraps length-prefixed byte-stream frames back into the original user
+ * chunks. Used by the consumer side of a framed byte-stream pipe.
  *
- * @param data - The format-prefixed data
- * @returns An object with the format identifier and payload
- * @throws Error if the data is too short or has an unknown format
- */
-export declare function decodeFormatPrefix(data: Uint8Array | unknown): {
-    format: SerializationFormatType;
-    payload: Uint8Array;
-};
-/**
- * Detect if a readable stream is a byte stream.
+ * Buffers across read boundaries — the transport may split a single
+ * frame across multiple reads (header in one chunk, payload in another)
+ * or coalesce multiple frames into a single read. The transform emits
+ * whole user chunks regardless of transport chunking.
  *
- * @param stream
- * @returns `"bytes"` if the stream is a byte stream, `undefined` otherwise
+ * Errors the stream if the length header advertises a frame larger than
+ * `MAX_FRAME_SIZE` bytes, since that almost certainly indicates a
+ * misframed wire (e.g. a raw byte stream being fed through this transform
+ * by mistake) and we don't want to allocate an enormous buffer.
  */
-export declare function getStreamType(stream: ReadableStream): 'bytes' | undefined;
-export declare function getSerializeStream(reducers: Reducers, cryptoKey: EncryptionKeyParam): TransformStream<any, Uint8Array>;
-export declare function getDeserializeStream(revivers: Revivers, cryptoKey: EncryptionKeyParam): TransformStream<Uint8Array, any>;
+export declare function getByteUnframingStream(): TransformStream<Uint8Array, Uint8Array>;
 export declare class WorkflowServerReadableStream extends ReadableStream<Uint8Array> {
     #private;
     constructor(runId: string, name: string, startIndex?: number);
 }
+/**
+ * Maximum consecutive reconnect attempts for a single framed stream session.
+ * The counter resets to zero whenever a reconnect makes forward progress (a
+ * frame is delivered), so this bounds *consecutive* failures, not the lifetime
+ * total — a long-lived serverless stream may legitimately reconnect far more
+ * than this many times as long as each reconnect keeps delivering data. We only
+ * give up after this many reconnects in a row produce nothing.
+ */
+export declare const FRAMED_STREAM_MAX_RECONNECTS = 50;
+/**
+ * Absolute backstop on total reconnects for a single session, independent of
+ * progress. The consecutive cap above resets on forward progress, which is
+ * correct for a well-behaved backend that honors `startIndex`. But if a World's
+ * `streams.get` ever ignored `startIndex` and re-delivered earlier chunks,
+ * "progress" would be reported every reconnect and the consecutive cap would
+ * never trip — turning a bounded failure into an unbounded reconnect loop. This
+ * hard ceiling guarantees the loop always terminates. It is set high enough
+ * (hours of streaming at realistic per-session timeouts) to never interfere
+ * with legitimate long-lived streams.
+ */
+export declare const FRAMED_STREAM_MAX_TOTAL_RECONNECTS = 1000;
+/**
+ * Wraps the length-prefix-framed byte stream from `world.streams.get` with
+ * transparent auto-reconnect.
+ *
+ * Every fully-decoded outer frame corresponds to exactly one server-side
+ * chunk (the serialize transform enqueues one frame per workflow write, and
+ * the writable buffers one frame per chunk when multi-writing). The wrapper
+ * counts completed frames and, on upstream error, reopens the connection
+ * with `startIndex = resolvedStartIndex + consumedFrames`. Partial-frame
+ * bytes buffered before the cut are discarded — the server will resend the
+ * in-flight chunk in full from the new startIndex.
+ *
+ * A clean upstream close (EOF with no error) signals the stream is truly
+ * done; we close the wrapper and do not reconnect.
+ *
+ * Negative `startIndex` values (last-N semantics) skip the reconnect
+ * machinery because we cannot compute an absolute resume position without
+ * a tail-index lookup — the returned stream behaves as a single-shot read.
+ */
+export declare function createReconnectingFramedStream(runId: string, name: string, startIndex?: number): ReadableStream<Uint8Array>;
 export declare class WorkflowServerWritableStream extends WritableStream<Uint8Array> {
-    constructor(runId: string, name: string);
+    /**
+     * @param runReadyBarrier Turbo mode only: a promise that resolves once the
+     * backgrounded `run_started` has landed. When the step body runs
+     * optimistically (before `run_started` is durable), the first chunk write to
+     * a brand-new stream would otherwise reach the World before the run exists
+     * and be rejected as run-not-found. Awaiting this once before the first
+     * flush/close orders the write after the run's creation. `undefined` outside
+     * turbo and on the await path, where the run was already durable.
+     */
+    constructor(runId: string, name: string, runReadyBarrier?: Promise<unknown>);
 }
-export interface SerializableSpecial {
-    ArrayBuffer: string;
-    BigInt: string;
-    BigInt64Array: string;
-    BigUint64Array: string;
-    Date: string;
-    DOMException: {
+export type { ByteStreamFraming, Reducers, Revivers, SerializableSpecial, } from './serialization/types.js';
+import type { ByteStreamFraming, Reducers, Revivers } from './serialization/types.js';
+/**
+ * Reducers for serialization boundary from the client side, passing arguments
+ * to the workflow handler.
+ *
+ * @param global
+ * @param ops
+ * @param runId
+ * @param cryptoKey
+ * @param framedByteStreams - When `true`, byte streams (`type: 'bytes'`)
+ *   are wrapped in length-prefixed frames on the wire so the consumer
+ *   can reconnect on transient errors. Should match the target run's
+ *   capability — see `getRunCapabilities` in `capabilities.ts`. Defaults
+ *   to `false` for backwards compatibility with older runs.
+ * @returns
+ */
+export declare function getExternalReducers(global: Record<string, any> | undefined, ops: Promise<void>[], runId: string, cryptoKey: EncryptionKeyParam, framedByteStreams?: boolean, runReadyBarrier?: Promise<unknown>): Partial<Reducers>;
+export declare function getWorkflowReducers(global?: Record<string, any>): Partial<Reducers>;
+/**
+ * Cancel dangling abort-stream readers on any AbortController instances found
+ * in the hydrated step arguments. Called after the step function returns
+ * (success or failure) to prevent reader promises from keeping the serverless
+ * function alive indefinitely.
+ */
+export declare function cancelAbortReaders(...values: unknown[]): void;
+/**
+ * Base revivers shared across all serialization boundaries.
+ * Composes: class + common revivers from the modular modules.
+ *
+ * This is exported because serialization-format.ts and other files reference it.
+ */
+export declare function getCommonRevivers(global?: Record<string, any>): {
+    ArrayBuffer?: ((value: string) => any) | undefined;
+    BigInt?: ((value: string) => any) | undefined;
+    BigInt64Array?: ((value: string) => any) | undefined;
+    BigUint64Array?: ((value: string) => any) | undefined;
+    Date?: ((value: string) => any) | undefined;
+    DOMException?: ((value: {
         message: string;
         name: string;
         stack?: string;
         cause?: unknown;
-    };
-    Float32Array: string;
-    Float64Array: string;
-    Error: Record<string, any>;
-    Headers: [string, string][];
-    Int8Array: string;
-    Int16Array: string;
-    Int32Array: string;
-    Map: [any, any][];
-    ReadableStream: {
+    }) => any) | undefined;
+    FatalError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    Float32Array?: ((value: string) => any) | undefined;
+    Float64Array?: ((value: string) => any) | undefined;
+    Error?: ((value: {
         name: string;
-        type?: 'bytes';
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    EvalError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    Headers?: ((value: [string, string][]) => any) | undefined;
+    HookConflictError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+        token: string;
+        conflictingRunId?: string;
+    }) => any) | undefined;
+    Int8Array?: ((value: string) => any) | undefined;
+    Int16Array?: ((value: string) => any) | undefined;
+    Int32Array?: ((value: string) => any) | undefined;
+    Map?: ((value: [any, any][]) => any) | undefined;
+    RangeError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    ReadableStream?: ((value: {
+        name: string;
+        type?: "bytes";
         startIndex?: number;
+        framing?: ByteStreamFraming;
     } | {
         bodyInit: any;
-    };
-    RegExp: {
+    }) => any) | undefined;
+    ReferenceError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    RegExp?: ((value: {
         source: string;
         flags: string;
-    };
-    Request: {
+    }) => any) | undefined;
+    RetryableError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+        retryAfter: number;
+    }) => any) | undefined;
+    RuntimeDecryptionError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+        context?: import("@workflow/errors").RuntimeDecryptionErrorContext;
+    }) => any) | undefined;
+    Request?: ((value: {
         method: string;
         url: string;
         headers: Headers;
-        body: Request['body'];
-        duplex: Request['duplex'];
+        body: Request["body"];
+        duplex: Request["duplex"];
         responseWritable?: WritableStream<Response>;
-    };
-    Response: {
-        type: Response['type'];
+        signal?: AbortSignal;
+    }) => any) | undefined;
+    Response?: ((value: {
+        type: Response["type"];
         url: string;
         status: number;
         statusText: string;
         headers: Headers;
-        body: Response['body'];
+        body: Response["body"];
         redirected: boolean;
-    };
-    Class: {
+    }) => any) | undefined;
+    Class?: ((value: {
         classId: string;
-    };
-    /**
-     * Custom serialized class instance.
-     * The class must have a `classId` property and be registered for deserialization.
-     */
-    Instance: {
+    }) => any) | undefined;
+    Instance?: ((value: {
         classId: string;
         data: unknown;
-    };
-    Set: any[];
-    StepFunction: {
+    }) => any) | undefined;
+    Set?: ((value: any[]) => any) | undefined;
+    SyntaxError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    StepFunction?: ((value: {
         stepId: string;
         closureVars?: Record<string, any>;
-    };
-    URL: string;
-    WorkflowFunction: {
+        boundThis?: unknown;
+        boundArgs?: unknown[];
+    }) => any) | undefined;
+    TypeError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    URIError?: ((value: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => any) | undefined;
+    URL?: ((value: string) => any) | undefined;
+    WorkflowFunction?: ((value: {
         workflowId: string;
-    };
-    URLSearchParams: string;
-    Uint8Array: string;
-    Uint8ClampedArray: string;
-    Uint16Array: string;
-    Uint32Array: string;
-    WritableStream: {
-        name: string;
-    };
-}
-type Reducers = {
-    [K in keyof SerializableSpecial]: (value: any) => SerializableSpecial[K] | false;
-};
-type Revivers = {
-    [K in keyof SerializableSpecial]: (value: SerializableSpecial[K]) => any;
-};
-/**
- * Reducers for serialization boundary from the client side, passing arguments
- * to the workflow handler.
- *
- * @param global
- * @param ops
- * @returns
- */
-export declare function getExternalReducers(global: Record<string, any> | undefined, ops: Promise<void>[], runId: string, cryptoKey: EncryptionKeyParam): Reducers;
-/**
- * Reducers for serialization boundary from within the workflow execution
- * environment, passing return value to the client side and into step arguments.
- *
- * @param global
- * @returns
- */
-export declare function getWorkflowReducers(global?: Record<string, any>): Reducers;
-export declare function getCommonRevivers(global?: Record<string, any>): {
-    readonly ArrayBuffer: (value: string) => any;
-    readonly BigInt: (value: string) => any;
-    readonly BigInt64Array: (value: string) => any;
-    readonly BigUint64Array: (value: string) => any;
-    readonly Date: (value: string) => any;
-    readonly DOMException: (value: {
+    }) => any) | undefined;
+    URLSearchParams?: ((value: string) => any) | undefined;
+    Uint8Array?: ((value: string) => any) | undefined;
+    Uint8ClampedArray?: ((value: string) => any) | undefined;
+    Uint16Array?: ((value: string) => any) | undefined;
+    Uint32Array?: ((value: string) => any) | undefined;
+    AggregateError?: ((value: {
         message: string;
-        name: string;
         stack?: string;
         cause?: unknown;
-    }) => any;
-    readonly Error: (value: Record<string, any>) => any;
-    readonly Float32Array: (value: string) => any;
-    readonly Float64Array: (value: string) => any;
-    readonly Headers: (value: [string, string][]) => any;
-    readonly Int8Array: (value: string) => any;
-    readonly Int16Array: (value: string) => any;
-    readonly Int32Array: (value: string) => any;
-    readonly Map: (value: [any, any][]) => any;
-    readonly RegExp: (value: {
-        source: string;
-        flags: string;
-    }) => any;
-    readonly Class: (value: {
-        classId: string;
-    }) => Function;
-    readonly Instance: (value: {
-        classId: string;
-        data: unknown;
-    }) => any;
-    readonly Set: (value: any[]) => any;
-    readonly URL: (value: string) => any;
-    readonly URLSearchParams: (value: string) => any;
-    readonly Uint8Array: (value: string) => any;
-    readonly Uint8ClampedArray: (value: string) => any;
-    readonly Uint16Array: (value: string) => any;
-    readonly Uint32Array: (value: string) => any;
+        errors: unknown[];
+    }) => any) | undefined;
+    WritableStream?: ((value: {
+        name: string;
+        runId?: string;
+        deploymentId?: string;
+        encryptionPublicKey?: string;
+    }) => any) | undefined;
+    AbortController?: ((value: {
+        streamName: string;
+        hookToken: string;
+        aborted: boolean;
+        reason?: unknown;
+    }) => any) | undefined;
+    AbortSignal?: ((value: {
+        streamName: string;
+        hookToken: string;
+        aborted: boolean;
+        reason?: unknown;
+    }) => any) | undefined;
 };
 /**
  * Revivers for deserialization boundary from the client side,
@@ -215,7 +301,7 @@ export declare function getCommonRevivers(global?: Record<string, any>): {
  * @param ops
  * @param runId
  */
-export declare function getExternalRevivers(global: Record<string, any> | undefined, ops: Promise<void>[], runId: string, cryptoKey: EncryptionKeyParam): Revivers;
+export declare function getExternalRevivers(global: Record<string, any> | undefined, ops: Promise<void>[], runId: string, cryptoKey: EncryptionKeyParam): Partial<Revivers>;
 /**
  * Revivers for deserialization boundary from within the workflow execution
  * environment, receiving arguments from the client side, and return values
@@ -224,29 +310,57 @@ export declare function getExternalRevivers(global: Record<string, any> | undefi
  * @param global
  * @returns
  */
-export declare function getWorkflowRevivers(global?: Record<string, any>): Revivers;
+export declare function getWorkflowRevivers(global?: Record<string, any>): Partial<Revivers>;
 /**
  * Encrypt data if the world supports encryption.
  * Returns original data if encryption is not available.
  *
- * @param data - Serialized data to encrypt
- * @param key - Encryption key (undefined to skip encryption)
- * @param context - Encryption context with runId
- * @returns Encrypted data if encryption available, original data otherwise
+ * @deprecated Use `encrypt` from `./serialization/encryption.js` instead.
  */
-export declare function maybeEncrypt(data: Uint8Array, key: CryptoKey | undefined): Promise<Uint8Array>;
+export declare function maybeEncrypt(data: Uint8Array, key: PayloadKey | undefined): Promise<Uint8Array>;
 /**
  * Decrypt data if it has the 'encr' prefix.
  *
- * @param data - Data that may be encrypted
- * @param key - Encryption key (undefined if no key available)
- * @returns Decrypted data if encrypted, original data otherwise
- * @throws {WorkflowRuntimeError} If the data is encrypted but no key is
- *   available. Callers (e.g., `Run.pollReturnValue()`, `hydrateStepReturnValue`)
- *   should be aware this can surface as a rejected promise during key rotation
- *   or misconfiguration scenarios.
+ * @deprecated Use `decrypt` from `./serialization/encryption.js` instead.
+ */
+export declare function maybeDecrypt(data: Uint8Array | unknown, key: PayloadKey | undefined): Promise<Uint8Array | unknown>;
+/**
+ * Replay hydration has two stages:
+ *
+ * 1. Host-side preparation decrypts and decompresses persisted data. That work
+ *    is independent of a workflow VM and can be cached across replay VMs.
+ * 2. Deserialization revives the prepared representation against the current
+ *    VM's globals. It must run again for every VM to produce fresh object graphs
+ *    and correctly scoped Workflow objects.
+ *
+ * `data` is the boundary between those stages. For current-format payloads it
+ * is still format-prefixed serialized bytes, not a live JavaScript value.
  */
-export declare function maybeDecrypt(data: Uint8Array | unknown, key: CryptoKey | undefined): Promise<Uint8Array | unknown>;
+export interface PreparedReplayPayload {
+    readonly data: unknown;
+}
+/**
+ * Swappable implementation of the host-side preparation stage. Supporting
+ * both direct and promised results lets a future synchronous Node decryptor use
+ * the same cache contract as today's asynchronous Web Crypto implementation.
+ */
+export type ReplayPayloadPreparer = (value: unknown, key: PayloadKey | undefined) => PreparedReplayPayload | Promise<PreparedReplayPayload>;
+/**
+ * Decrypt and decompress persisted data without parsing it into JavaScript.
+ * Legacy non-binary values pass through unchanged for their consumer to revive.
+ */
+export declare const prepareReplayPayload: ReplayPayloadPreparer;
+/**
+ * Parse a prepared workflow argument or successful step/hook payload using the
+ * current workflow VM's globals and revivers. Each call intentionally creates
+ * a fresh object graph so mutations cannot leak across replay iterations.
+ */
+export declare function deserializePreparedReplayPayload(prepared: PreparedReplayPayload, global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>): any;
+/**
+ * Parse a prepared step error using the current workflow VM's class revivers.
+ * This preserves thrown-value identity without sharing objects between VMs.
+ */
+export declare function deserializePreparedStepError(prepared: PreparedReplayPayload, global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>): unknown;
 /**
  * Called from the `start()` function to serialize the workflow arguments
  * into a format that can be saved to the database and then hydrated from
@@ -258,61 +372,113 @@ export declare function maybeDecrypt(data: Uint8Array | unknown, key: CryptoKey
  * @param ops - Promise array for stream operations
  * @param global - Global object for serialization context
  * @param v1Compat - Enable legacy v1 compatibility mode
+ * @param framedByteStreams - Whether the target run can decode wire-framed
+ *   byte streams. Should match the target deployment's capability — see
+ *   `getRunCapabilities` in `capabilities.ts`. Defaults to `false` for
+ *   backwards compatibility with older runs.
  * @returns The dehydrated value as binary data (Uint8Array) with format prefix
  */
-export declare function dehydrateWorkflowArguments(value: unknown, runId: string, key: CryptoKey | undefined, ops?: Promise<void>[], global?: Record<string, any>, v1Compat?: boolean): Promise<Uint8Array | unknown>;
+export declare function dehydrateWorkflowArguments(value: unknown, runId: string, key: PayloadKey | undefined, ops?: Promise<void>[], global?: Record<string, any>, v1Compat?: boolean, framedByteStreams?: boolean, compression?: boolean): Promise<Uint8Array | unknown>;
 /**
  * Called from workflow execution environment to hydrate the workflow
- * arguments from the database at the start of workflow execution.
- *
- * @param value - Binary serialized data (Uint8Array) with format prefix
- * @param _runId - Workflow run ID (reserved for future decryption context; decryption is currently driven solely by the provided key)
- * @param key - Encryption key (undefined to skip decryption)
- * @param global - Global object for deserialization context
- * @param extraRevivers - Additional revivers for custom types
- * @returns The hydrated value
+ * arguments from the database at the start of workflow execution. A prepared
+ * payload skips host-side decrypt/decompress but always performs VM revival.
  */
-export declare function hydrateWorkflowArguments(value: Uint8Array | unknown, _runId: string, key: CryptoKey | undefined, global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>): Promise<any>;
+export declare function hydrateWorkflowArguments(value: Uint8Array | unknown, _runId: string, key: PayloadKey | undefined, global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>, prepared?: PreparedReplayPayload): Promise<any>;
 /**
  * Dehydrate workflow return value for storage.
+ */
+export declare function dehydrateWorkflowReturnValue(value: unknown, _runId: string, key: PayloadKey | undefined, global?: Record<string, any>, v1Compat?: boolean, compression?: boolean, 
+/**
+ * Optional sink receiving every workflow-code execution serialization could
+ * not avoid, for callers that need them programmatically (e.g. a
+ * retained-VM gate deciding whether the VM is still reusable). The
+ * executions are emitted as span attributes either way, so omitting this
+ * loses nothing observability-wise. The retained-VM gate in
+ * runtime/suspension-handler.ts passes one for step-input dehydration.
+ */
+guestCodeStatsOut?: GuestCodeStats): Promise<Uint8Array | unknown>;
+/**
+ * Called from the client side to hydrate the workflow return value
+ * of a completed workflow run.
+ */
+export declare function hydrateWorkflowReturnValue(value: Uint8Array | unknown, runId: string, key: PayloadKey | undefined, ops?: Promise<void>[], global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>): Promise<any>;
+/**
+ * Called from the workflow handler when a step is being created.
+ * Dehydrates values from within the workflow execution environment.
+ */
+export declare function dehydrateStepArguments(value: unknown, _runId: string, key: PayloadKey | undefined, global?: Record<string, any>, v1Compat?: boolean, compression?: boolean, 
+/** See `dehydrateWorkflowReturnValue`. */
+guestCodeStatsOut?: GuestCodeStats): Promise<Uint8Array | unknown>;
+/**
+ * Called from the step executor to hydrate the arguments of a step
+ * from the database at the start of the step execution.
+ */
+export declare function hydrateStepArguments(value: Uint8Array | unknown, runId: string, key: PayloadKey | undefined, ops?: Promise<any>[], global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>, deploymentId?: string): Promise<any>;
+/**
+ * Called from the step executor when a step has completed.
+ * Dehydrates values from within the step execution environment
+ * into a format that can be saved to the database.
  *
  * @param value - The value to serialize
  * @param runId - Run ID for encryption context
  * @param key - Encryption key (undefined to skip encryption)
+ * @param ops - Promise array for stream operations
  * @param global - Global object for serialization context
+ * @param v1Compat - Enable legacy v1 compatibility mode
+ * @param framedByteStreams - Whether the target run can decode wire-framed
+ *   byte streams. Should match the target deployment's capability — see
+ *   `getRunCapabilities` in `capabilities.ts`. Defaults to `false` for
+ *   backwards compatibility with older runs.
  * @returns The dehydrated value as binary data (Uint8Array) with format prefix
  */
-export declare function dehydrateWorkflowReturnValue(value: unknown, _runId: string, key: CryptoKey | undefined, global?: Record<string, any>, v1Compat?: boolean): Promise<Uint8Array | unknown>;
+export declare function dehydrateStepReturnValue(value: unknown, runId: string, key: PayloadKey | undefined, ops?: Promise<any>[], global?: Record<string, any>, v1Compat?: boolean, framedByteStreams?: boolean, compression?: boolean, runReadyBarrier?: Promise<unknown>): Promise<Uint8Array | unknown>;
 /**
- * Called from the client side (i.e. the execution environment where
- * the workflow run was initiated from) to hydrate the workflow
- * return value of a completed workflow run.
+ * Called from the step executor when a step throws. Dehydrates the thrown
+ * value from within the step execution environment into a format that can
+ * be saved to the database in a `step_failed` or `step_retrying` event.
+ *
+ * Any JavaScript value can be thrown (strings, numbers, objects, Errors,
+ * Error subclasses), so the same serialization pipeline used for step
+ * arguments and return values is applied here.
+ *
+ * @param value - The thrown value to serialize (can be any type)
+ * @param runId - Run ID for encryption context
+ * @param key - Encryption key (undefined to skip encryption)
+ * @param ops - Promise array for stream operations
+ * @param global - Global object for serialization context
+ * @returns The dehydrated value as binary data (Uint8Array) with format prefix
+ */
+export declare function dehydrateStepError(value: unknown, runId: string, key: PayloadKey | undefined, ops?: Promise<any>[], global?: Record<string, any>, compression?: boolean): Promise<Uint8Array>;
+/**
+ * Called from the workflow handler when replaying the event log of a
+ * `step_failed` or `step_retrying` event. Hydrates the thrown value from
+ * the database so the workflow can see the original thrown value.
  *
  * @param value - Binary serialized data (Uint8Array) with format prefix
  * @param runId - Run ID for decryption context
  * @param key - Encryption key (undefined to skip decryption)
- * @param ops - Promise array for stream operations
  * @param global - Global object for deserialization context
  * @param extraRevivers - Additional revivers for custom types
- * @returns The hydrated return value, ready to be consumed by the client
+ * @param prepared - Optional cached decrypt/decompress result
+ * @returns The hydrated thrown value, ready to reject the step promise
  */
-export declare function hydrateWorkflowReturnValue(value: Uint8Array | unknown, runId: string, key: CryptoKey | undefined, ops?: Promise<void>[], global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>): Promise<any>;
+export declare function hydrateStepError(value: Uint8Array | unknown, _runId: string, key: PayloadKey | undefined, global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>, prepared?: PreparedReplayPayload): Promise<unknown>;
 /**
- * Called from the workflow handler when a step is being created.
- * Dehydrates values from within the workflow execution environment
- * into a format that can be saved to the database.
+ * Called from the workflow handler when the workflow itself throws.
+ * Dehydrates the thrown value from within the workflow execution environment
+ * into a format that can be saved to the database in a `run_failed` event.
  *
- * @param value - The value to serialize
+ * @param value - The thrown value to serialize (can be any type)
  * @param runId - Run ID for encryption context
  * @param key - Encryption key (undefined to skip encryption)
  * @param global - Global object for serialization context
- * @param v1Compat - Enable legacy v1 compatibility mode
  * @returns The dehydrated value as binary data (Uint8Array) with format prefix
  */
-export declare function dehydrateStepArguments(value: unknown, _runId: string, key: CryptoKey | undefined, global?: Record<string, any>, v1Compat?: boolean): Promise<Uint8Array | unknown>;
+export declare function dehydrateRunError(value: unknown, _runId: string, key: PayloadKey | undefined, global?: Record<string, any>, compression?: boolean): Promise<Uint8Array>;
 /**
- * Called from the step handler to hydrate the arguments of a step
- * from the database at the start of the step execution.
+ * Called from the client side (or observability tools) to hydrate the run
+ * error value of a failed workflow run.
  *
  * @param value - Binary serialized data (Uint8Array) with format prefix
  * @param runId - Run ID for decryption context
@@ -320,23 +486,9 @@ export declare function dehydrateStepArguments(value: unknown, _runId: string, k
  * @param ops - Promise array for stream operations
  * @param global - Global object for deserialization context
  * @param extraRevivers - Additional revivers for custom types
- * @returns The hydrated value, ready to be consumed by the step user-code function
- */
-export declare function hydrateStepArguments(value: Uint8Array | unknown, runId: string, key: CryptoKey | undefined, ops?: Promise<any>[], global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>): Promise<any>;
-/**
- * Called from the step handler when a step has completed.
- * Dehydrates values from within the step execution environment
- * into a format that can be saved to the database.
- *
- * @param value - The value to serialize
- * @param runId - Run ID for encryption context
- * @param key - Encryption key (undefined to skip encryption)
- * @param ops - Promise array for stream operations
- * @param global - Global object for serialization context
- * @param v1Compat - Enable legacy v1 compatibility mode
- * @returns The dehydrated value as binary data (Uint8Array) with format prefix
+ * @returns The hydrated thrown value, ready to be consumed by the client
  */
-export declare function dehydrateStepReturnValue(value: unknown, runId: string, key: CryptoKey | undefined, ops?: Promise<any>[], global?: Record<string, any>, v1Compat?: boolean): Promise<Uint8Array | unknown>;
+export declare function hydrateRunError(value: Uint8Array | unknown, runId: string, key: PayloadKey | undefined, ops?: Promise<void>[], global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>): Promise<unknown>;
 /**
  * Called from the workflow handler when replaying the event log of a `step_completed` event.
  * Hydrates the return value of a step from the database.
@@ -346,8 +498,9 @@ export declare function dehydrateStepReturnValue(value: unknown, runId: string,
  * @param key - Encryption key (undefined to skip decryption)
  * @param global - Global object for deserialization context
  * @param extraRevivers - Additional revivers for custom types
- * @returns The hydrated return value of a step, ready to be consumed by the workflow handler
+ * @param prepared - Optional cached decrypt/decompress result
+ * Called from the workflow handler when replaying the event log
+ * of a `step_completed` event.
  */
-export declare function hydrateStepReturnValue(value: Uint8Array | unknown, _runId: string, key: CryptoKey | undefined, global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>): Promise<any>;
-export {};
+export declare function hydrateStepReturnValue(value: Uint8Array | unknown, _runId: string, key: PayloadKey | undefined, global?: Record<string, any>, extraRevivers?: Record<string, (value: any) => any>, prepared?: PreparedReplayPayload): Promise<any>;
 //# sourceMappingURL=serialization.d.ts.map