experimental-ash 0.22.2 → 0.24.0

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

@@ -0,0 +1,15 @@
+/**
+ * A serializable value:
+ * Any valid JSON object is serializable
+ *
+ * @example
+ *
+ * ```ts
+ * // any valid JSON object is serializable
+ * const anyJson: Serializable = { foo: "bar" };
+ * ```
+ */
+export type Serializable = string | number | boolean | null | undefined | Serializable[] | {
+    [key: string]: Serializable;
+} | ArrayBuffer | bigint | BigInt64Array | BigUint64Array | Date | DOMException | Error | Float32Array | Float64Array | Headers | Int8Array | Int16Array | Int32Array | Map<Serializable, Serializable> | ReadableStream<Uint8Array> | RegExp | Response | Set<Serializable> | URL | URLSearchParams | Uint8Array | Uint8ClampedArray | Uint16Array | Uint32Array | WritableStream<Uint8Array> | AbortController | AbortSignal | ((...args: Serializable[]) => Promise<Serializable>);
+//# sourceMappingURL=schemas.d.ts.map

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

@@ -0,0 +1,17 @@
+/**
+ * Client (external) mode serialization.
+ *
+ * Used when starting workflows from the client side (serializing workflow
+ * arguments) and when receiving workflow return values. Supports encryption.
+ */
+import type { CodecOptions } from './codec.js';
+import { type CryptoKey } from './encryption.js';
+/**
+ * Serialize a value from the client environment (e.g. workflow arguments).
+ */
+export declare function serialize(value: unknown, encryptionKey?: CryptoKey, options?: CodecOptions): Promise<Uint8Array | unknown>;
+/**
+ * Deserialize a value for the client environment (e.g. workflow return value).
+ */
+export declare function deserialize(data: Uint8Array | unknown, encryptionKey?: CryptoKey, options?: CodecOptions): Promise<unknown>;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1,14 @@
+/**
+ * Devalue codec implementation.
+ *
+ * Uses the `devalue` library for serialization. Handles custom types via
+ * reducers (serialize) and revivers (deserialize) which are composed
+ * internally based on the serialization mode.
+ *
+ * The reducer/reviver pattern is specific to devalue — other codecs
+ * (CBOR, JSON) would handle types differently (e.g. CBOR supports Date,
+ * typed arrays, Map, Set natively).
+ */
+import type { Codec } from './codec.js';
+export declare const devalueCodec: Codec;
+//# sourceMappingURL=codec-devalue.d.ts.map

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

@@ -0,0 +1,90 @@
+/**
+ * Codec interface for serialization formats.
+ *
+ * A codec handles the core serialize/deserialize logic for a specific
+ * wire format (devalue, CBOR, JSON, etc.). Each codec is responsible
+ * for handling all supported data types internally — the caller only
+ * specifies which serialization mode to use.
+ *
+ * - **devalue**: Uses custom reducers/revivers for Date, Error, Map, Set,
+ *   typed arrays, class instances, etc.
+ * - **cbor**: Would handle Date, typed arrays, Map, Set natively via the
+ *   CBOR type system. Class instances would still need custom handling.
+ * - **json**: Would only support standard JSON types (primitives, arrays,
+ *   plain objects). No Date, Map, Set, typed arrays, etc.
+ */
+import type { FormatPrefix } from './types.js';
+/**
+ * The serialization mode determines which types are supported and how
+ * they're handled. Different modes compose different sets of type handlers.
+ *
+ * - `workflow`: Runs inside the workflow VM. Includes class serialization,
+ *   step function serialization. No stream handling.
+ * - `step`: Runs in the step handler (Node.js). Includes class serialization.
+ *   No step function serialization. Stream handling at call sites.
+ * - `client`: Runs on the client side. Includes class serialization.
+ *   No step function serialization. Stream handling at call sites.
+ */
+export type SerializationMode = 'workflow' | 'step' | 'client';
+/**
+ * Options passed to codec serialize/deserialize to support VM-context
+ * serialization and mode-specific type handling.
+ */
+export interface CodecOptions {
+    /**
+     * The global object to use for `instanceof` checks and constructors.
+     * Defaults to `globalThis`. Must be set to the VM's global when
+     * serializing/deserializing data that crosses VM boundaries.
+     */
+    global?: Record<string, any>;
+    /**
+     * Additional reducers to merge into the mode's default reducers.
+     * Used by dehydrate/hydrate functions that need stream handling
+     * or other mode-specific type reducers.
+     */
+    extraReducers?: Record<string, (value: any) => any>;
+    /**
+     * Additional revivers to merge into the mode's default revivers.
+     * Used by dehydrate/hydrate functions that need stream handling
+     * or other mode-specific type revivers.
+     */
+    extraRevivers?: Record<string, (value: any) => any>;
+}
+export interface Codec {
+    /** The 4-character format prefix identifier (e.g. "devl", "cbor", "json") */
+    readonly formatPrefix: FormatPrefix;
+    /**
+     * Serialize a value to bytes.
+     *
+     * The codec handles all supported types internally based on the mode.
+     *
+     * @param value - The value to serialize
+     * @param mode - The serialization mode
+     * @param options - Optional global, extra reducers/revivers
+     * @returns The serialized payload (without format prefix)
+     */
+    serialize(value: unknown, mode: SerializationMode, options?: CodecOptions): Uint8Array;
+    /**
+     * Deserialize bytes back to a value.
+     *
+     * The codec handles all supported types internally based on the mode.
+     *
+     * @param data - The serialized payload (without format prefix)
+     * @param mode - The serialization mode
+     * @param options - Optional global, extra revivers
+     * @returns The deserialized value
+     */
+    deserialize(data: Uint8Array, mode: SerializationMode, options?: CodecOptions): unknown;
+    /**
+     * Deserialize legacy (pre-format-prefix) data.
+     * Used for backwards compatibility with specVersion 1 runs that stored
+     * data as plain JSON arrays instead of binary.
+     *
+     * @param data - The legacy data
+     * @param mode - The serialization mode
+     * @param options - Optional global, extra revivers
+     * @returns The deserialized value
+     */
+    deserializeLegacy?(data: unknown, mode: SerializationMode, options?: CodecOptions): unknown;
+}
+//# sourceMappingURL=codec.d.ts.map

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

@@ -0,0 +1,32 @@
+/**
+ * Composable encryption layer for serialized data.
+ *
+ * Wraps/unwraps serialized payloads with AES-256-GCM encryption,
+ * using the format prefix system to mark encrypted data.
+ */
+import { type CryptoKey } from '../encryption.js';
+export type { CryptoKey };
+/**
+ * Encryption key parameter type. Accepts a resolved key, undefined (no encryption),
+ * or a promise that resolves to either.
+ */
+export type EncryptionKeyParam = CryptoKey | undefined | Promise<CryptoKey | undefined>;
+/**
+ * Encrypt a format-prefixed payload if a key is provided.
+ * Wraps the data with the 'encr' format prefix.
+ *
+ * @param data - The format-prefixed serialized data
+ * @param key - Encryption key (undefined to skip encryption)
+ * @returns The encrypted data with 'encr' prefix, or the original data if no key
+ */
+export declare function encrypt(data: Uint8Array | unknown, key: CryptoKey | undefined): Promise<Uint8Array | unknown>;
+/**
+ * Decrypt a format-prefixed payload if it's encrypted.
+ * Strips the 'encr' format prefix and decrypts the inner payload.
+ *
+ * @param data - The potentially encrypted data
+ * @param key - Encryption key (undefined to skip decryption)
+ * @returns The decrypted inner payload, or the original data if not encrypted
+ */
+export declare function decrypt(data: Uint8Array | unknown, key: CryptoKey | undefined): Promise<Uint8Array | unknown>;
+//# sourceMappingURL=encryption.d.ts.map

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

@@ -0,0 +1,21 @@
+/**
+ * Shared error formatting utility for serialization failures.
+ *
+ * Used by the mode-specific serializers (workflow, step, client) to
+ * produce consistent error messages with devalue path information.
+ *
+ * Returns a `{ message, hint }` pair so callers can throw a
+ * `SerializationError(message, { hint, cause })` and have the hint flow
+ * through the standard friendly-errors framing instead of being baked
+ * into the message string.
+ */
+/**
+ * Format a serialization error with context about what failed.
+ * Extracts path, value, and reason from devalue's DevalueError when available.
+ * Logs the problematic value to the console for better debugging.
+ */
+export declare function formatSerializationError(context: string, error: unknown): {
+    message: string;
+    hint: string;
+};
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1,60 @@
+/**
+ * Format prefix system for serialized payloads.
+ *
+ * All serialized payloads are prefixed with a 4-byte format identifier that
+ * allows the deserializer to determine how to decode the payload. This enables:
+ *
+ * 1. Self-describing payloads — the World layer is agnostic to serialization format
+ * 2. Gradual migration — old runs keep working, new runs can use new formats
+ * 3. Composability — encryption can wrap any format ("encr" wrapping "devl")
+ * 4. Debugging — raw data inspection immediately reveals the format
+ *
+ * Format: [4 bytes: format identifier][payload]
+ *
+ * The format prefix is open-ended — any 4-character [a-z0-9] string is valid.
+ * This allows new codecs to be added without modifying this module.
+ */
+import { type FormatPrefix } from './types.js';
+/**
+ * Encode a payload with a format prefix.
+ *
+ * @param format - The format identifier (4 chars, [a-z0-9])
+ * @param payload - The serialized payload bytes
+ * @returns A new Uint8Array with format prefix prepended
+ */
+export declare function encodeWithFormatPrefix(format: FormatPrefix, payload: Uint8Array | unknown): Uint8Array | unknown;
+/**
+ * Peek at the format prefix without consuming it.
+ *
+ * Returns the prefix if it's a valid format prefix ([a-z0-9]{4}),
+ * or null if the data is legacy/non-binary or doesn't start with a
+ * valid prefix.
+ *
+ * @param data - The format-prefixed data
+ * @returns The format prefix, or null
+ */
+export declare function peekFormatPrefix(data: Uint8Array | unknown): FormatPrefix | null;
+/**
+ * Check if data is encrypted (has 'encr' format prefix).
+ */
+export declare function isEncrypted(data: Uint8Array | unknown): boolean;
+/**
+ * Decode a format-prefixed payload.
+ *
+ * Unlike the legacy implementation which only accepted known formats
+ * (`devl`, `encr`), this function accepts any valid format prefix
+ * (`[a-z0-9]{4}`). This is intentional for forward compatibility —
+ * new codecs (e.g. `cbor`) can be added without modifying this module.
+ * Callers are responsible for checking whether they support the returned
+ * format and throwing an appropriate error if not (e.g. "Unsupported
+ * serialization format").
+ *
+ * @param data - The format-prefixed data
+ * @returns An object with the format prefix and payload
+ * @throws Error if the data is too short or has an invalid prefix
+ */
+export declare function decodeFormatPrefix(data: Uint8Array | unknown): {
+    format: FormatPrefix;
+    payload: Uint8Array;
+};
+//# sourceMappingURL=format.d.ts.map

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

@@ -0,0 +1,18 @@
+/**
+ * Serialization module — public API.
+ *
+ * Re-exports the mode-specific serialize/deserialize functions and
+ * the codec/format/encryption abstractions.
+ */
+export type { FormatPrefix, SerializableSpecial, Reducers, Revivers, } from './types.js';
+export { SerializationFormat, isFormatPrefix } from './types.js';
+export type { Codec, SerializationMode } from './codec.js';
+export { devalueCodec } from './codec-devalue.js';
+export { encodeWithFormatPrefix, decodeFormatPrefix, peekFormatPrefix, isEncrypted, } from './format.js';
+export { encrypt, decrypt, type CryptoKey, type EncryptionKeyParam, } from './encryption.js';
+import * as workflow from './workflow.js';
+import * as step from './step.js';
+import * as client from './client.js';
+export { workflow, step, client };
+export { revive } from './reducers/common.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,11 @@
+/**
+ * Reducers and revivers for custom class serialization.
+ *
+ * Handles:
+ * - Class: class constructors with a `classId` property
+ * - Instance: instances of classes with custom WORKFLOW_SERIALIZE/DESERIALIZE methods
+ */
+import type { Reducers, Revivers } from '../types.js';
+export declare function getClassReducers(): Partial<Reducers>;
+export declare function getClassRevivers(global?: Record<string, any>): Partial<Revivers>;
+//# sourceMappingURL=class.d.ts.map

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

@@ -0,0 +1,16 @@
+/**
+ * Common reducers and revivers for types shared across all serialization modes.
+ *
+ * Handles: ArrayBuffer, BigInt, typed arrays, Date, Error, Headers, Map, Set,
+ * RegExp, Request, Response, URL, URLSearchParams.
+ *
+ * Note: Uses Node.js Buffer for base64 encoding/decoding. For environments
+ * without Buffer (e.g. QuickJS VM), a polyfill or alternative base64
+ * implementation will be needed.
+ */
+import type { Reducers, Revivers } from '../types.js';
+declare function revive(str: string): any;
+export declare function getCommonReducers(global?: Record<string, any>): Partial<Reducers>;
+export declare function getCommonRevivers(global?: Record<string, any>): Partial<Revivers>;
+export { revive };
+//# sourceMappingURL=common.d.ts.map

package/dist/src/compiled/@workflow/core/serialization/reducers/step-function.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Reducer and reviver for step function references.
+ *
+ * In workflow mode, step functions are replaced by the SWC plugin with
+ * proxies created by `globalThis[Symbol.for("WORKFLOW_USE_STEP")]("stepId")`.
+ * These proxies have a `.stepId` property and optionally a `.__closureVarsFn`
+ * for captured closure variables. They may additionally have `.__boundThis`
+ * (and rarely `.__boundArgs`) when the SWC plugin emitted
+ * `useStep(...).bind(this)` for a nested arrow step that lexically
+ * captured `this` (see `packages/swc-plugin-workflow/spec.md` → "Lexical
+ * `this` Capture in Nested Arrow Steps").
+ *
+ * The reducer serializes them as
+ *   `{ stepId, closureVars?, boundThis?, boundArgs? }`.
+ * The reviver reconstructs them by calling WORKFLOW_USE_STEP and, when
+ * `boundThis` (or `boundArgs`) is present, re-binding the resulting
+ * proxy so the caller's captured `this` (and prefilled args) survive the
+ * round trip.
+ */
+import type { Reducers, Revivers } from '../types.js';
+export declare function getStepFunctionReducer(): Partial<Reducers>;
+/**
+ * Create the StepFunction reviver for workflow context.
+ *
+ * The reviver calls WORKFLOW_USE_STEP to create the step proxy,
+ * restoring the ability to call the step from workflow code. If the
+ * serialized payload includes `boundThis` (and optionally `boundArgs`),
+ * the reviver also re-binds the freshly-created proxy so a step proxy
+ * that was constructed with `.bind(this, …)` in the workflow bundle
+ * continues to carry that receiver and any prefilled arguments after
+ * being deserialized in another bundle (e.g. when passed as a step
+ * argument).
+ */
+export declare function getStepFunctionReviver(global?: Record<string, any>): Partial<Revivers>;
+//# sourceMappingURL=step-function.d.ts.map

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

@@ -0,0 +1,17 @@
+/**
+ * Step mode serialization.
+ *
+ * Used by the step handler for serializing step return values and
+ * deserializing step arguments. Supports encryption as a composable layer.
+ */
+import type { CodecOptions } from './codec.js';
+import { type CryptoKey } from './encryption.js';
+/**
+ * Serialize a value from the step execution environment.
+ */
+export declare function serialize(value: unknown, encryptionKey?: CryptoKey, options?: CodecOptions): Promise<Uint8Array | unknown>;
+/**
+ * Deserialize a value for the step execution environment.
+ */
+export declare function deserialize(data: Uint8Array | unknown, encryptionKey?: CryptoKey, options?: CodecOptions): Promise<unknown>;
+//# sourceMappingURL=step.d.ts.map

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

@@ -0,0 +1,215 @@
+/**
+ * Shared types for the serialization system.
+ */
+/**
+ * A format prefix is exactly 4 lowercase alphanumeric characters [a-z0-9].
+ *
+ * This is a branded string type — use `isFormatPrefix()` to validate
+ * at runtime. The `SerializationFormat` object provides well-known
+ * constants, but codecs may define additional prefixes.
+ */
+export type FormatPrefix = string & {
+    readonly __brand: 'FormatPrefix';
+};
+/**
+ * Runtime type guard for format prefix strings.
+ *
+ * Validates that a string is exactly 4 characters of [a-z0-9].
+ */
+export declare function isFormatPrefix(value: string): value is FormatPrefix;
+/**
+ * Well-known format prefix constants. Codecs may define additional ones.
+ */
+export declare const SerializationFormat: {
+    /** devalue stringify/parse with TextEncoder/TextDecoder */
+    readonly DEVALUE_V1: FormatPrefix;
+    /** Encrypted payload (inner payload has its own format prefix) */
+    readonly ENCRYPTED: FormatPrefix;
+};
+/**
+ * Types that need specialized handling when serialized/deserialized.
+ * If a type is added here, it MUST also be added to the `Serializable`
+ * type in `schemas.ts`.
+ */
+export interface SerializableSpecial {
+    ArrayBuffer: string;
+    BigInt: string;
+    BigInt64Array: string;
+    BigUint64Array: string;
+    Date: string;
+    DOMException: {
+        message: string;
+        name: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    FatalError: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    Float32Array: string;
+    Float64Array: string;
+    Error: {
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    EvalError: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    Headers: [string, string][];
+    HookConflictError: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+        token: string;
+        conflictingRunId?: string;
+    };
+    Int8Array: string;
+    Int16Array: string;
+    Int32Array: string;
+    Map: [any, any][];
+    RangeError: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    ReadableStream: {
+        name: string;
+        type?: 'bytes';
+        startIndex?: number;
+    } | {
+        bodyInit: any;
+    };
+    ReferenceError: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    RegExp: {
+        source: string;
+        flags: string;
+    };
+    /**
+     * `retryAfter` is serialized as a numeric epoch timestamp rather than a
+     * `Date` to be realm-safe. The Date reducer uses `instanceof global.Date`,
+     * which fails for Dates from a different VM realm.
+     */
+    RetryableError: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+        retryAfter: number;
+    };
+    Request: {
+        method: string;
+        url: string;
+        headers: Headers;
+        body: Request['body'];
+        duplex: Request['duplex'];
+        responseWritable?: WritableStream<Response>;
+        signal?: AbortSignal;
+    };
+    Response: {
+        type: Response['type'];
+        url: string;
+        status: number;
+        statusText: string;
+        headers: Headers;
+        body: Response['body'];
+        redirected: boolean;
+    };
+    Class: {
+        classId: string;
+    };
+    Instance: {
+        classId: string;
+        data: unknown;
+    };
+    Set: any[];
+    SyntaxError: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    StepFunction: {
+        stepId: string;
+        closureVars?: Record<string, any>;
+        /**
+         * Captured lexical `this` for step proxies that were created via
+         * `useStep(...).bind(thisArg)` (the SWC plugin emits this for nested
+         * arrow steps that close over their enclosing function's `this`).
+         * The reviver re-binds the freshly-created proxy to this value so the
+         * binding survives serialization round-trips.
+         */
+        boundThis?: unknown;
+        /**
+         * Prefilled arguments captured when the user (rather than the SWC
+         * plugin) called `useStep(...).bind(thisArg, x, y)`. The reviver
+         * re-applies these alongside `boundThis` so partial application
+         * survives serialization. The SWC plugin only ever emits
+         * `.bind(this)` with no extra args today; this slot exists so a
+         * hand-written `.bind(thisArg, x)` doesn't silently lose `x` after
+         * round-tripping through the reducer/reviver.
+         */
+        boundArgs?: unknown[];
+    };
+    TypeError: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    URIError: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    URL: string;
+    WorkflowFunction: {
+        workflowId: string;
+    };
+    URLSearchParams: string;
+    Uint8Array: string;
+    Uint8ClampedArray: string;
+    Uint16Array: string;
+    Uint32Array: string;
+    AggregateError: {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+        errors: unknown[];
+    };
+    WritableStream: {
+        name: string;
+        /**
+         * The runId of the workflow run that owns the underlying server
+         * stream. Present only when the writable was forwarded across a
+         * `start()` boundary (parent → child). When omitted, the writable
+         * belongs to the receiving run (the normal in-run case).
+         */
+        runId?: string;
+    };
+    AbortController: {
+        streamName: string;
+        hookToken: string;
+        aborted: boolean;
+        reason?: unknown;
+    };
+    AbortSignal: {
+        streamName: string;
+        hookToken: string;
+        aborted: boolean;
+        reason?: unknown;
+    };
+}
+export type Reducers = {
+    [K in keyof SerializableSpecial]: (value: any) => SerializableSpecial[K] | false;
+};
+export type Revivers = {
+    [K in keyof SerializableSpecial]: (value: SerializableSpecial[K]) => any;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,29 @@
+/**
+ * Workflow mode serialization.
+ *
+ * Provides serialize/deserialize for use inside the workflow execution
+ * environment (QuickJS VM or Node.js vm). It is:
+ * - Synchronous (no async operations)
+ * - No encryption (encryption is handled outside the VM on the host side)
+ *
+ * Designed to be bundled into the workflow code by esbuild and executed
+ * inside the sandboxed VM.
+ */
+import type { CodecOptions } from './codec.js';
+/**
+ * Serialize a value for storage/transmission from the workflow environment.
+ *
+ * @param value - The value to serialize
+ * @param options - Optional global, extra reducers/revivers for VM-context serialization
+ * @returns Format-prefixed serialized bytes
+ */
+export declare function serialize(value: unknown, options?: CodecOptions): Uint8Array;
+/**
+ * Deserialize a value received in the workflow environment.
+ *
+ * @param data - Format-prefixed serialized bytes, or legacy data
+ * @param options - Optional global, extra revivers for VM-context deserialization
+ * @returns The deserialized value
+ */
+export declare function deserialize(data: Uint8Array | unknown, options?: CodecOptions): unknown;
+//# sourceMappingURL=workflow.d.ts.map