experimental-ash 0.22.2 → 0.23.0

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

@@ -0,0 +1,201 @@
+/**
+ * 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][];
+    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;
+    };
+    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

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

@@ -0,0 +1,171 @@
+/**
+ * Browser-safe serialization format utilities.
+ *
+ * This module contains the format prefix handling, generic hydrate/dehydrate
+ * dispatch, and shared types/classes used by all environments (runtime, web
+ * o11y, CLI o11y). It has NO Node.js dependencies.
+ */
+export declare const SerializationFormat: {
+    /** devalue stringify/parse with TextEncoder/TextDecoder */
+    readonly DEVALUE_V1: "devl";
+    /** Encrypted payload (inner payload has its own format prefix after decryption) */
+    readonly ENCRYPTED: "encr";
+};
+export type SerializationFormatType = (typeof SerializationFormat)[keyof typeof SerializationFormat];
+/**
+ * Encode a payload with a format prefix.
+ */
+export declare function encodeWithFormatPrefix(format: SerializationFormatType, payload: Uint8Array | unknown): Uint8Array | unknown;
+/**
+ * Decode a format-prefixed payload.
+ */
+export declare function decodeFormatPrefix(data: Uint8Array | unknown): {
+    format: SerializationFormatType;
+    payload: Uint8Array;
+};
+/**
+ * Placeholder string displayed when data is encrypted and decryption
+ * has not been requested. Used by both CLI and web o11y.
+ */
+export declare const ENCRYPTED_PLACEHOLDER = "\uD83D\uDD12 Encrypted";
+/**
+ * Check if a hydrated value is an expired data stub from the server.
+ *
+ * The server replaces expired ref fields with a devalue-encoded stub
+ * (`makeExpiredStub`) that deserializes to `[{ expiredAt: "<ISO date>" }]`
+ * after `unflatten` (array-wrapped due to backwards-compatible encoding).
+ * Also matches the unwrapped `{ expiredAt: "..." }` form for robustness.
+ */
+export declare function isExpiredStub(data: unknown): boolean;
+/**
+ * Check if a binary value has the 'encr' format prefix indicating encryption.
+ * Browser-safe — does not depend on the full serialization module.
+ */
+export declare function isEncryptedData(data: unknown): boolean;
+/**
+ * A map of type name → reviver function, used by devalue's `parse`/`unflatten`.
+ * Each environment (runtime, web, CLI) provides its own set.
+ */
+export type Revivers = Record<string, (value: any) => any>;
+/**
+ * Hydrate (deserialize) a value that was stored in the database.
+ *
+ * Handles four data shapes:
+ * 1. `Uint8Array` with 'encr' prefix → returned as-is (encrypted, not yet decrypted)
+ * 2. `Uint8Array` with a format prefix (specVersion 2+) → decode prefix, parse
+ * 3. `Array` (legacy specVersion 1, "revived devalue") → unflatten
+ * 4. Other (already a plain JS value) → return as-is
+ *
+ * Encrypted data is intentionally left as a `Uint8Array` so that consumers
+ * (CLI, web UI) can detect it with `isEncryptedData()` and decide how to
+ * handle it — the CLI replaces it with a styled placeholder, the web UI
+ * renders an "Encrypted" card with a Decrypt button that triggers
+ * client-side decryption on demand.
+ */
+export declare function hydrateData(value: unknown, revivers: Revivers): unknown;
+/**
+ * Hydrate a value, decrypting it first if an encryption key is provided.
+ *
+ * This is the async version of `hydrateData` that supports transparent
+ * decryption. Used by o11y tooling (web UI, CLI) when the user requests
+ * decryption.
+ *
+ * @param value - The value to hydrate (may be encrypted)
+ * @param revivers - Devalue revivers for deserialization
+ * @param key - AES-256 encryption key (if provided, encrypted data will be decrypted)
+ */
+export declare function hydrateDataWithKey(value: unknown, revivers: Revivers, key: import('./encryption.js').CryptoKey | undefined): Promise<unknown>;
+/** Marker for stream reference objects rendered as links in the UI */
+export declare const STREAM_REF_TYPE = "__workflow_stream_ref__";
+/** A stream reference for UI display */
+export interface StreamRef {
+    __type: typeof STREAM_REF_TYPE;
+    streamId: string;
+}
+/** Marker for Run reference objects rendered as links in the UI */
+export declare const RUN_REF_TYPE = "__workflow_run_ref__";
+/** A Run reference for UI display */
+export interface RunRef {
+    __type: typeof RUN_REF_TYPE;
+    runId: string;
+}
+/** Check if a value is a RunRef object */
+export declare const isRunRef: (value: unknown) => value is RunRef;
+/** Convert a serialized Run value to a RunRef for display */
+export declare const serializedRunToRunRef: (value: {
+    runId: string;
+}) => RunRef;
+/** Marker for custom class instance references */
+export declare const CLASS_INSTANCE_REF_TYPE = "__workflow_class_instance_ref__";
+/**
+ * A class instance reference for o11y display.
+ *
+ * Browser-safe base class — no `util.inspect.custom`. Environment-specific
+ * rendering (CLI inspect, web component) is handled by each consumer.
+ */
+export declare class ClassInstanceRef {
+    readonly className: string;
+    readonly classId: string;
+    readonly data: unknown;
+    readonly __type = "__workflow_class_instance_ref__";
+    constructor(className: string, classId: string, data: unknown);
+    toJSON(): {
+        __type: string;
+        className: string;
+        classId: string;
+        data: unknown;
+    };
+}
+/** Check if a value is a ClassInstanceRef object */
+export declare const isClassInstanceRef: (value: unknown) => value is ClassInstanceRef;
+/** Check if a value is a stream ID string */
+export declare const isStreamId: (value: unknown) => boolean;
+/** Check if a value is a StreamRef object */
+export declare const isStreamRef: (value: unknown) => value is StreamRef;
+/**
+ * Convert a serialized stream value to a StreamRef for display.
+ */
+export declare const streamToStreamRef: (value: any) => StreamRef;
+/** Convert a serialized step function to a display string */
+export declare const serializedStepFunctionToString: (value: unknown) => string;
+/** Extract the class name from a classId */
+export declare const extractClassName: (classId: string) => string;
+/** Convert a serialized class instance to a ClassInstanceRef for display.
+ *  Run instances are special-cased to a RunRef for clickable rendering. */
+export declare const serializedInstanceToRef: (value: {
+    classId: string;
+    data: unknown;
+}) => ClassInstanceRef | RunRef;
+/** Convert a serialized class reference to a display string */
+export declare const serializedClassToString: (value: {
+    classId: string;
+}) => string;
+/**
+ * Standard o11y revivers that override runtime-specific types with
+ * display-friendly values. Used by both web and CLI hydration.
+ */
+export declare const observabilityRevivers: Revivers;
+/**
+ * Hydrate the serialized data fields of any resource for o11y display.
+ *
+ * Dispatches by resource type (step, hook, event, workflow) and calls
+ * `hydrateData` with the provided revivers for each data field.
+ *
+ * Each environment (web, CLI) provides its own revivers — this function
+ * only handles the dispatch logic and field mapping.
+ */
+export declare function hydrateResourceIO<T extends {
+    stepId?: string;
+    hookId?: string;
+    eventId?: string;
+    input?: any;
+    output?: any;
+    metadata?: any;
+    eventData?: any;
+    executionContext?: any;
+}>(resource: T, revivers: Revivers): T;
+/** Extract all stream IDs from a value (recursively traverses objects/arrays) */
+export declare function extractStreamIds(obj: unknown): string[];
+/** Truncate a string to a maximum length, adding ellipsis if needed */
+export declare function truncateId(id: string, maxLength?: number): string;
+//# sourceMappingURL=serialization-format.d.ts.map