experimental-ash 0.45.0 → 0.46.0

package/dist/src/compiled/@workflow/world/interfaces.d.ts

@@ -0,0 +1,264 @@
+import type { AttributeChange, ExperimentalSetAttributesResult } from './attributes.js';
+import type { CreateEventParams, CreateEventRequest, Event, EventResult, GetEventParams, ListEventsByCorrelationIdParams, ListEventsParams, RunCreatedEventRequest } from './events.js';
+import type { GetHookParams, Hook, ListHooksParams } from './hooks.js';
+import type { Queue } from './queue.js';
+import type { GetWorkflowRunParams, ListWorkflowRunsParams, WorkflowRun, WorkflowRunWithoutData } from './runs.js';
+import type { GetChunksOptions, PaginatedResponse, StreamChunksResponse, StreamInfoResponse } from './shared.js';
+import type { GetStepParams, ListWorkflowRunStepsParams, Step, StepWithoutData } from './steps.js';
+export interface Streamer {
+    /**
+     * Override the default flush interval (in milliseconds) for buffered stream writes.
+     * Chunks are accumulated in a buffer and flushed together on this interval.
+     *
+     * The default is 10ms, which is appropriate for HTTP-based backends where
+     * each flush is a network round-trip. For backends with sub-millisecond writes
+     * (e.g., Redis, local filesystem), a lower value (or 0 for immediate flushing) reduces
+     * end-to-end stream latency.
+     *
+     * Not supported by all worlds.
+     */
+    streamFlushIntervalMs?: number;
+    streams: {
+        write(runId: string, name: string, chunk: string | Uint8Array): Promise<void>;
+        /**
+         * Write multiple chunks to a stream in a single operation.
+         * This is an optional optimization for world implementations that can
+         * batch multiple writes efficiently (e.g., single HTTP request for world-vercel).
+         *
+         * If not implemented, the caller should fall back to sequential write() calls.
+         *
+         * @param runId - The run ID
+         * @param name - The stream name
+         * @param chunks - Array of chunks to write, in order
+         */
+        writeMulti?(runId: string, name: string, chunks: (string | Uint8Array)[]): Promise<void>;
+        close(runId: string, name: string): Promise<void>;
+        /**
+         * Read from a stream starting at the given chunk index.
+         * Positive values skip that many chunks from the start (0-based).
+         * Negative values start that many chunks before the current end
+         * (e.g. -3 on a 10-chunk stream starts at chunk 7). Clamped to 0.
+         */
+        get(runId: string, name: string, startIndex?: number): Promise<ReadableStream<Uint8Array>>;
+        list(runId: string): Promise<string[]>;
+        /**
+         * Fetch stream chunks with cursor-based pagination.
+         *
+         * Unlike `get` (which returns a live `ReadableStream` that waits
+         * for new chunks in real-time), `getChunks` returns a snapshot of currently
+         * available chunks in a standard paginated response.
+         *
+         * @param runId - The workflow run ID that owns the stream
+         * @param name - The stream name/ID
+         * @param options - Pagination options (limit defaults to 100, max 1000)
+         * @returns Paginated chunks with a `done` flag indicating stream completion
+         */
+        getChunks(runId: string, name: string, options?: GetChunksOptions): Promise<StreamChunksResponse>;
+        /**
+         * Retrieve lightweight metadata about a stream.
+         *
+         * Returns the tail index (index of the last known chunk, 0-based) and
+         * whether the stream is complete. This is useful for resolving a negative
+         * `startIndex` into an absolute position before connecting to a stream.
+         *
+         * @param runId - The workflow run ID that owns the stream
+         * @param name - The stream name/ID
+         */
+        getInfo(runId: string, name: string): Promise<StreamInfoResponse>;
+    };
+}
+/**
+ * Storage interface for workflow data.
+ *
+ * Workflow storage models an append-only event log, so all state changes are handled through `events.create()`.
+ * Run/Step/Hook entities provide materialized views into the current state, but entities can't be modified directly.
+ *
+ * User-originated state changes are also handled via events:
+ * - run_cancelled event for run cancellation
+ * - hook_disposed event for explicit hook disposal (optional)
+ *
+ * Note: Hooks are automatically disposed by the World implementation when a workflow
+ * reaches a terminal state (run_completed, run_failed, run_cancelled). This releases
+ * hook tokens for reuse by future workflows. The hook_disposed event is only needed
+ * for explicit disposal before workflow completion.
+ */
+export interface Storage {
+    runs: {
+        get(id: string, params: GetWorkflowRunParams & {
+            resolveData: 'none';
+        }): Promise<WorkflowRunWithoutData>;
+        get(id: string, params?: GetWorkflowRunParams & {
+            resolveData?: 'all';
+        }): Promise<WorkflowRun>;
+        get(id: string, params?: GetWorkflowRunParams): Promise<WorkflowRun | WorkflowRunWithoutData>;
+        list(params: ListWorkflowRunsParams & {
+            resolveData: 'none';
+        }): Promise<PaginatedResponse<WorkflowRunWithoutData>>;
+        list(params?: ListWorkflowRunsParams & {
+            resolveData?: 'all';
+        }): Promise<PaginatedResponse<WorkflowRun>>;
+        list(params?: ListWorkflowRunsParams): Promise<PaginatedResponse<WorkflowRun | WorkflowRunWithoutData>>;
+        /**
+         * Apply a batch of attribute changes to a run. Merge semantics:
+         * - `value: string` upserts the key
+         * - `value: null` removes the key
+         * - keys not listed in `changes` are untouched
+         *
+         * Returns the post-merge attribute snapshot on the run.
+         *
+         * Pass `options.allowReservedAttributes: true` to permit keys
+         * starting with the reserved `$` prefix. Default behavior rejects
+         * those keys so user code can't accidentally collide with
+         * framework / tooling namespaces; framework callers that own a
+         * sub-namespace flip this on.
+         *
+         * OPTIONAL. World implementations may omit this method; the SDK
+         * helper (`setAttributes` in `@workflow/core`) feature-detects its
+         * absence and no-ops with a one-time warning so third-party /
+         * community worlds keep working without adopting the experimental
+         * API.
+         *
+         * EXPERIMENTAL: this method exists as a stopgap until the
+         * `attr_set` event type lands in a future spec version. When that
+         * happens, `setAttributes` will dispatch through `events.create`
+         * instead, and this method is expected to be removed. See the
+         * `attributes-mvp` changelog entry for the migration shape.
+         */
+        experimentalSetAttributes?(runId: string, changes: AttributeChange[], options?: {
+            allowReservedAttributes?: boolean;
+        }): Promise<ExperimentalSetAttributesResult>;
+    };
+    steps: {
+        get(runId: string, stepId: string, params: GetStepParams & {
+            resolveData: 'none';
+        }): Promise<StepWithoutData>;
+        get(runId: string, stepId: string, params?: GetStepParams & {
+            resolveData?: 'all';
+        }): Promise<Step>;
+        get(runId: string, stepId: string, params?: GetStepParams): Promise<Step | StepWithoutData>;
+        list(params: ListWorkflowRunStepsParams & {
+            resolveData: 'none';
+        }): Promise<PaginatedResponse<StepWithoutData>>;
+        list(params: ListWorkflowRunStepsParams & {
+            resolveData?: 'all';
+        }): Promise<PaginatedResponse<Step>>;
+        list(params: ListWorkflowRunStepsParams): Promise<PaginatedResponse<Step | StepWithoutData>>;
+    };
+    events: {
+        /**
+         * Create a run_created event to start a new workflow run.
+         * The runId may be provided by the client or left as null for the server to generate.
+         *
+         * @param runId - Client-generated runId, or null for server-generated
+         * @param data - The run_created event data
+         * @param params - Optional parameters for event creation
+         * @returns Promise resolving to the created event and run entity
+         */
+        create(runId: string | null, data: RunCreatedEventRequest, params?: CreateEventParams): Promise<EventResult>;
+        /**
+         * Create an event for an existing workflow run and atomically update the entity.
+         * Returns both the event and the affected entity (run/step/hook).
+         *
+         * @param runId - The workflow run ID (required for all events except run_created)
+         * @param data - The event to create
+         * @param params - Optional parameters for event creation
+         * @returns Promise resolving to the created event and affected entity
+         */
+        create(runId: string, data: CreateEventRequest, params?: CreateEventParams): Promise<EventResult>;
+        get(runId: string, eventId: string, params?: GetEventParams): Promise<Event>;
+        list(params: ListEventsParams): Promise<PaginatedResponse<Event>>;
+        listByCorrelationId(params: ListEventsByCorrelationIdParams): Promise<PaginatedResponse<Event>>;
+    };
+    hooks: {
+        get(hookId: string, params?: GetHookParams): Promise<Hook>;
+        getByToken(token: string, params?: GetHookParams): Promise<Hook>;
+        list(params: ListHooksParams): Promise<PaginatedResponse<Hook>>;
+    };
+}
+/**
+ * The "World" interface represents how Workflows are able to communicate with the outside world.
+ */
+export interface World extends Queue, Streamer, Storage {
+    /**
+     * The highest spec version this World supports.
+     *
+     * When set, `start()` creates runs at this version so world-specific
+     * features (e.g., CBOR queue transport) are enabled automatically.
+     * When omitted, runs default to `SPEC_VERSION_SUPPORTS_EVENT_SOURCING` (2),
+     * the safe baseline that all worlds — including community worlds on
+     * older @workflow/world versions — are expected to handle.
+     */
+    specVersion?: number;
+    /**
+     * Whether calling `process.exit(1)` from a queue handler is observed by
+     * the World as a delivery failure that will be retried.
+     *
+     * Set to `true` for worlds running inside a managed serverless platform
+     * (e.g. `world-vercel`) where the platform fails the invocation when the
+     * function process exits non-zero, and the queue redelivers the message
+     * via a separate fresh invocation.
+     *
+     * Set to `false` (the default) for in-process worlds (e.g. `world-local`,
+     * dev servers) where calling `process.exit()` would terminate the host
+     * process — including the user's `pnpm dev` — without producing a
+     * redelivery. Such worlds should instead surface failures via the event
+     * log and return normally.
+     *
+     * The core runtime reads this when deciding how to handle an exhausted
+     * replay budget: when `true` it exits so the queue redelivers; when
+     * `false` it writes `run_failed` best-effort and returns. See
+     * `packages/core/src/runtime/replay-budget.ts`.
+     */
+    processExitTriggersQueueRedelivery?: boolean;
+    /**
+     * A function that will be called to start any background tasks needed by the World implementation.
+     * For example, in the case of a queue backed World, this would start the queue processing.
+     */
+    start?(): Promise<void>;
+    /**
+     * Release any resources held by the World implementation (connection pools, listeners, etc.).
+     * After calling `close()`, the World instance should not be used again.
+     *
+     * This is important for CLI commands and short-lived processes that need to exit cleanly
+     * without relying on `process.exit()`.
+     */
+    close?(): Promise<void>;
+    /**
+     * Resolve the most recent deployment ID for the current deployment's environment.
+     *
+     * Used when `deploymentId: 'latest'` is passed to `start()`. The implementation
+     * determines the latest deployment that shares the same environment (e.g., same
+     * "production" target or same git branch for "preview" deployments) as the
+     * current deployment.
+     *
+     * Not all World implementations support this — it is only implemented by
+     * world-vercel where deployment routing is meaningful.
+     */
+    resolveLatestDeploymentId?(): Promise<string>;
+    /**
+     * Retrieve the AES-256 encryption key for a specific workflow run.
+     *
+     * The returned key is a ready-to-use 32-byte AES-256 key. The World
+     * implementation handles all key retrieval and derivation internally
+     * (e.g., HKDF from a deployment key). The core encryption module uses
+     * this key directly for AES-GCM encrypt/decrypt operations.
+     *
+     * Two overloads:
+     *
+     * - `getEncryptionKeyForRun(run)` — Preferred. Pass a `WorkflowRun` when
+     *   the run entity already exists. The World reads any context it needs
+     *   (e.g., `deploymentId`) directly from the run.
+     *
+     * - `getEncryptionKeyForRun(runId, context?)` — Used when the run entity
+     *   is not locally available, such as `start()` before run creation or a
+     *   forwarded writable stream carrying its owning deployment context. The
+     *   `context` parameter carries opaque world-specific data (e.g.,
+     *   `{ deploymentId }` for world-vercel) needed to resolve the correct key.
+     *   When `context` is omitted, the World assumes the current deployment.
+     *
+     * When not implemented, encryption is disabled — data is stored unencrypted.
+     */
+    getEncryptionKeyForRun?(run: WorkflowRun): Promise<Uint8Array | undefined>;
+    getEncryptionKeyForRun?(runId: string, context?: Record<string, unknown>): Promise<Uint8Array | undefined>;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/src/compiled/@workflow/world/queue.d.ts

@@ -0,0 +1,120 @@
+import { z } from '#compiled/zod/index.js';
+export declare const QueuePrefix: z.ZodUnion<readonly [z.ZodLiteral<"__wkf_step_">, z.ZodLiteral<"__wkf_workflow_">]>;
+export type QueuePrefix = z.infer<typeof QueuePrefix>;
+export declare const ValidQueueName: z.ZodTemplateLiteral<`__wkf_step_${string}` | `__wkf_workflow_${string}`>;
+export type ValidQueueName = z.infer<typeof ValidQueueName>;
+export declare const MessageId: z.core.$ZodBranded<z.ZodString, "MessageId", "out">;
+export type MessageId = z.infer<typeof MessageId>;
+/**
+ * OpenTelemetry trace context for distributed tracing
+ */
+export declare const TraceCarrierSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+export type TraceCarrier = z.infer<typeof TraceCarrierSchema>;
+/**
+ * Run creation data carried through the queue for resilient start.
+ * Only present on the first queue delivery — re-enqueues omit this.
+ * When the runtime processes the message, it passes this data to the
+ * run_started event so the server can create the run if it doesn't exist yet.
+ */
+export declare const RunInputSchema: z.ZodObject<{
+    input: z.ZodUnknown;
+    deploymentId: z.ZodString;
+    workflowName: z.ZodString;
+    specVersion: z.ZodNumber;
+    executionContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strip>;
+export type RunInput = z.infer<typeof RunInputSchema>;
+export declare const WorkflowInvokePayloadSchema: z.ZodObject<{
+    runId: z.ZodString;
+    traceCarrier: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    requestedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    serverErrorRetryCount: z.ZodOptional<z.ZodNumber>;
+    stepId: z.ZodOptional<z.ZodString>;
+    stepName: z.ZodOptional<z.ZodString>;
+    runInput: z.ZodOptional<z.ZodObject<{
+        input: z.ZodUnknown;
+        deploymentId: z.ZodString;
+        workflowName: z.ZodString;
+        specVersion: z.ZodNumber;
+        executionContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const StepInvokePayloadSchema: z.ZodObject<{
+    workflowName: z.ZodString;
+    workflowRunId: z.ZodString;
+    workflowStartedAt: z.ZodNumber;
+    stepId: z.ZodString;
+    traceCarrier: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    requestedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+}, z.core.$strip>;
+export type WorkflowInvokePayload = z.infer<typeof WorkflowInvokePayloadSchema>;
+export type StepInvokePayload = z.infer<typeof StepInvokePayloadSchema>;
+export type HealthCheckPayload = z.infer<typeof HealthCheckPayloadSchema>;
+/**
+ * Health check payload - used to verify that the queue pipeline
+ * can deliver messages to workflow/step endpoints.
+ */
+export declare const HealthCheckPayloadSchema: z.ZodObject<{
+    __healthCheck: z.ZodLiteral<true>;
+    correlationId: z.ZodString;
+}, z.core.$strip>;
+export declare const QueuePayloadSchema: z.ZodUnion<readonly [z.ZodObject<{
+    runId: z.ZodString;
+    traceCarrier: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    requestedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    serverErrorRetryCount: z.ZodOptional<z.ZodNumber>;
+    stepId: z.ZodOptional<z.ZodString>;
+    stepName: z.ZodOptional<z.ZodString>;
+    runInput: z.ZodOptional<z.ZodObject<{
+        input: z.ZodUnknown;
+        deploymentId: z.ZodString;
+        workflowName: z.ZodString;
+        specVersion: z.ZodNumber;
+        executionContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    workflowName: z.ZodString;
+    workflowRunId: z.ZodString;
+    workflowStartedAt: z.ZodNumber;
+    stepId: z.ZodString;
+    traceCarrier: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    requestedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    __healthCheck: z.ZodLiteral<true>;
+    correlationId: z.ZodString;
+}, z.core.$strip>]>;
+export type QueuePayload = z.infer<typeof QueuePayloadSchema>;
+export interface QueueOptions {
+    deploymentId?: string;
+    idempotencyKey?: string;
+    headers?: Record<string, string>;
+    /** Delay message delivery by this many seconds */
+    delaySeconds?: number;
+    /** Spec version of the target run. Used to select the queue transport format. */
+    specVersion?: number;
+}
+export interface Queue {
+    getDeploymentId(): Promise<string>;
+    /**
+     * Enqueues a message to the specified queue.
+     *
+     * @param queueName - The name of the queue to which the message will be sent.
+     * @param message - The content of the message to be sent to the queue.
+     * @param opts - Optional parameters for the queue operation.
+     */
+    queue(queueName: ValidQueueName, message: QueuePayload, opts?: QueueOptions): Promise<{
+        messageId: MessageId | null;
+    }>;
+    /**
+     * Creates an HTTP queue handler for processing messages from a specific queue.
+     */
+    createQueueHandler(queueNamePrefix: QueuePrefix, handler: (message: unknown, meta: {
+        attempt: number;
+        queueName: ValidQueueName;
+        messageId: MessageId;
+        requestId?: string;
+    }) => Promise<void | {
+        timeoutSeconds: number;
+    }>): (req: Request) => Promise<Response>;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/src/compiled/@workflow/world/recovery.d.ts

@@ -0,0 +1,13 @@
+import type { Queue } from './queue.js';
+import type { Storage } from './interfaces.js';
+/**
+ * Re-enqueue all active (pending/running) workflow runs so they resume
+ * processing after a world restart. The workflow handler is idempotent
+ * (event-log replay), so duplicate enqueues are safe.
+ *
+ * @param runs - Storage runs interface for listing active runs
+ * @param enqueue - Queue's enqueue method
+ * @param label - Log prefix for identifying the world implementation (e.g. "world-local")
+ */
+export declare function reenqueueActiveRuns(runs: Storage['runs'], enqueue: Queue['queue'], label: string): Promise<void>;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/src/compiled/@workflow/world/runs.d.ts

@@ -0,0 +1,144 @@
+import { z } from '#compiled/zod/index.js';
+import { type SerializedData } from './serialization.js';
+import type { PaginationOptions, ResolveData } from './shared.js';
+export declare const WorkflowRunStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    running: "running";
+    completed: "completed";
+    failed: "failed";
+    cancelled: "cancelled";
+}>;
+/**
+ * Base schema for the Workflow runs. Prefer using WorkflowRunSchema
+ * which implements a discriminatedUnion for various states.
+ *
+ * Note: input/output use SerializedDataSchema to support both:
+ * - specVersion >= 2: Uint8Array (binary devalue format)
+ * - specVersion 1: any (legacy JSON format)
+ */
+export declare const WorkflowRunBaseSchema: z.ZodObject<{
+    runId: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+    }>;
+    deploymentId: z.ZodString;
+    workflowName: z.ZodString;
+    specVersion: z.ZodOptional<z.ZodNumber>;
+    executionContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    input: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>]>>;
+    output: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>]>>;
+    error: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>]>>;
+    errorCode: z.ZodOptional<z.ZodString>;
+    attributes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    expiredAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    startedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    completedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    createdAt: z.ZodCoercedDate<unknown>;
+    updatedAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>;
+export declare const WorkflowRunSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    runId: z.ZodString;
+    deploymentId: z.ZodString;
+    workflowName: z.ZodString;
+    specVersion: z.ZodOptional<z.ZodNumber>;
+    executionContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    input: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>]>>;
+    errorCode: z.ZodOptional<z.ZodString>;
+    attributes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    expiredAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    startedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    createdAt: z.ZodCoercedDate<unknown>;
+    updatedAt: z.ZodCoercedDate<unknown>;
+    status: z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+    }>;
+    output: z.ZodOptional<z.ZodUndefined>;
+    error: z.ZodOptional<z.ZodUndefined>;
+    completedAt: z.ZodOptional<z.ZodUndefined>;
+}, z.core.$strip>, z.ZodObject<{
+    runId: z.ZodString;
+    deploymentId: z.ZodString;
+    workflowName: z.ZodString;
+    specVersion: z.ZodOptional<z.ZodNumber>;
+    executionContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    input: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>]>>;
+    errorCode: z.ZodOptional<z.ZodString>;
+    attributes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    expiredAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    startedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    createdAt: z.ZodCoercedDate<unknown>;
+    updatedAt: z.ZodCoercedDate<unknown>;
+    status: z.ZodLiteral<"cancelled">;
+    output: z.ZodOptional<z.ZodUndefined>;
+    error: z.ZodOptional<z.ZodUndefined>;
+    completedAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>, z.ZodObject<{
+    runId: z.ZodString;
+    deploymentId: z.ZodString;
+    workflowName: z.ZodString;
+    specVersion: z.ZodOptional<z.ZodNumber>;
+    executionContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    input: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>]>>;
+    errorCode: z.ZodOptional<z.ZodString>;
+    attributes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    expiredAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    startedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    createdAt: z.ZodCoercedDate<unknown>;
+    updatedAt: z.ZodCoercedDate<unknown>;
+    status: z.ZodLiteral<"completed">;
+    output: z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>]>;
+    error: z.ZodOptional<z.ZodUndefined>;
+    completedAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>, z.ZodObject<{
+    runId: z.ZodString;
+    deploymentId: z.ZodString;
+    workflowName: z.ZodString;
+    specVersion: z.ZodOptional<z.ZodNumber>;
+    executionContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    input: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>]>>;
+    errorCode: z.ZodOptional<z.ZodString>;
+    attributes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    expiredAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    startedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    createdAt: z.ZodCoercedDate<unknown>;
+    updatedAt: z.ZodCoercedDate<unknown>;
+    status: z.ZodLiteral<"failed">;
+    output: z.ZodOptional<z.ZodUndefined>;
+    error: z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>]>;
+    completedAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>], "status">;
+export type WorkflowRunStatus = z.infer<typeof WorkflowRunStatusSchema>;
+export type WorkflowRun = z.infer<typeof WorkflowRunSchema>;
+/**
+ * WorkflowRun with input/output fields excluded (when resolveData='none').
+ * Used for listing runs without fetching the full serialized data.
+ */
+export type WorkflowRunWithoutData = Omit<WorkflowRun, 'input' | 'output'> & {
+    input: undefined;
+    output: undefined;
+};
+export interface CreateWorkflowRunRequest {
+    deploymentId: string;
+    workflowName: string;
+    input: SerializedData;
+    executionContext?: SerializedData;
+    specVersion?: number;
+}
+export interface GetWorkflowRunParams {
+    resolveData?: ResolveData;
+}
+export interface ListWorkflowRunsParams {
+    workflowName?: string;
+    status?: WorkflowRunStatus;
+    pagination?: PaginationOptions;
+    resolveData?: ResolveData;
+}
+export interface CancelWorkflowRunParams {
+    resolveData?: ResolveData;
+}
+//# sourceMappingURL=runs.d.ts.map

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

@@ -0,0 +1,25 @@
+import { z } from '#compiled/zod/index.js';
+/**
+ * Binary serialized data using devalue format.
+ * This is the output of `TextEncoder.encode(devalue.stringify(...))`.
+ *
+ * The workflow core runtime handles serialization/deserialization,
+ * and World implementations store and transport this opaque binary payload.
+ */
+export type SerializedData = Uint8Array | unknown;
+/**
+ * Zod schema for validating SerializedData (Uint8Array).
+ * Used for specVersion >= 2.
+ */
+export declare const BinarySerializedDataSchema: z.ZodType<SerializedData>;
+/**
+ * Legacy schema for serialized data (specVersion 1).
+ * Legacy data was stored as JSON, so it can be any value.
+ */
+export declare const LegacySerializedDataSchemaV1: z.ZodType<unknown>;
+/**
+ * Union schema that accepts both v2+ (Uint8Array) and legacy (any) serialized data.
+ * Use this for validation when data may come from either specVersion.
+ */
+export declare const SerializedDataSchema: z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>]>;
+//# sourceMappingURL=serialization.d.ts.map

package/dist/src/compiled/@workflow/world/shared.d.ts

@@ -0,0 +1,83 @@
+import { z } from '#compiled/zod/index.js';
+export declare const zodJsonSchema: z.ZodType<unknown>;
+/**
+ * Options for paginated queries.
+ * Provides control over page size and cursor-based navigation.
+ */
+export interface PaginationOptions {
+    /** Maximum number of items to return (default varies by service, max: 1000) */
+    limit?: number;
+    /** Cursor for pagination - token from previous response */
+    cursor?: string;
+    sortOrder?: 'asc' | 'desc';
+}
+export declare const PaginatedResponseSchema: <T extends z.ZodTypeAny>(dataSchema: T) => z.ZodObject<{
+    data: z.ZodArray<T>;
+    cursor: z.ZodNullable<z.ZodString>;
+    hasMore: z.ZodBoolean;
+}, z.core.$strip>;
+export type PaginatedResponse<T> = z.infer<ReturnType<typeof PaginatedResponseSchema<z.ZodType<T>>>>;
+/**
+ * Controls how much data is resolved in the response.
+ * - "none": Returns minimal data with input: [] and output: undefined
+ * - "all": Returns full data with complete input and output
+ */
+export type ResolveData = 'none' | 'all';
+/**
+ * A standard error schema shape for propogating errors from runs and steps
+ */
+export declare const StructuredErrorSchema: z.ZodObject<{
+    message: z.ZodString;
+    stack: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StructuredError = z.infer<typeof StructuredErrorSchema>;
+/**
+ * A single chunk from a stream, with its 0-based index and raw binary data.
+ */
+export interface StreamChunk {
+    /** The 0-based position of this chunk in the stream */
+    index: number;
+    /** The raw chunk data */
+    data: Uint8Array;
+}
+/**
+ * Options for paginated chunk retrieval.
+ */
+export interface GetChunksOptions {
+    /** Maximum number of chunks to return per page (default: 100, max: 1000) */
+    limit?: number;
+    /** Opaque cursor from a previous response to fetch the next page */
+    cursor?: string;
+}
+/**
+ * Metadata about a stream, returned by {@link Streamer.getStreamInfo}.
+ */
+export interface StreamInfoResponse {
+    /**
+     * The index of the last known chunk (0-based).
+     * Returns `-1` when no chunks have been written yet.
+     */
+    tailIndex: number;
+    /** Whether the stream is fully complete (closed). */
+    done: boolean;
+}
+/**
+ * Paginated response for stream chunks.
+ *
+ * Extends the standard `PaginatedResponse` shape with a `done` field that
+ * indicates whether the stream has been fully written (closed). When `done`
+ * is `false`, additional chunks may appear in future requests even after
+ * `hasMore` returns `false` for the current set of available chunks.
+ */
+export interface StreamChunksResponse {
+    /** Array of stream chunks in index order */
+    data: StreamChunk[];
+    /** Cursor for the next page, or `null` when no more pages are available */
+    cursor: string | null;
+    /** Whether additional pages of already-written chunks exist */
+    hasMore: boolean;
+    /** Whether the stream is fully complete (all chunks have been written and the stream is closed) */
+    done: boolean;
+}
+//# sourceMappingURL=shared.d.ts.map