experimental-ash 0.22.2 → 0.23.0

package/dist/src/compiled/@workflow/core/create-hook.d.ts

@@ -0,0 +1,179 @@
+import type { Serializable } from './schemas.js';
+/**
+ * An object that can be awaited to receive a value.
+ */
+interface Thenable<T> {
+    then: Promise<T>['then'];
+}
+/**
+ * A `Request` that can be responded to within a workflow
+ * step function by calling the `respondWith()` method.
+ */
+export interface RequestWithResponse extends Request {
+    respondWith: (response: Response) => Promise<void>;
+}
+/**
+ * A hook that can be awaited and/or iterated over to receive
+ * a value within a workflow from an external system.
+ *
+ * Hooks implement the TC39 Explicit Resource Management proposal,
+ * allowing them to be used with the `using` keyword for automatic disposal.
+ */
+export interface Hook<T = any> extends AsyncIterable<T>, Thenable<T> {
+    /**
+     * The token used to identify this hook.
+     */
+    token: string;
+    /**
+     * Disposes the hook, releasing its token for reuse by other workflows.
+     *
+     * After calling `dispose()`, the hook will no longer receive any events.
+     * This is useful when you want to explicitly release a hook token before
+     * the workflow completes, allowing another workflow to register a hook
+     * with the same token.
+     *
+     * @example
+     * ```ts
+     * const hook = createHook<{ message: string }>({ token: 'my-token' });
+     *
+     * for await (const payload of hook) {
+     *   if (payload.message === 'done') {
+     *     hook.dispose(); // Release the token early
+     *     break;
+     *   }
+     * }
+     * ```
+     */
+    dispose(): void;
+    /**
+     * Implements the TC39 Explicit Resource Management proposal.
+     * Called automatically when using the `using` keyword.
+     *
+     * @example
+     * ```ts
+     * {
+     *   using hook = createHook<{ message: string }>({ token: 'my-token' });
+     *   const payload = await hook;
+     *   // hook is automatically disposed when the block exits
+     * }
+     * ```
+     */
+    [Symbol.dispose](): void;
+}
+/**
+ * A webhook that can be used to suspend and resume the workflow run
+ * upon receiving an HTTP request to the specified URL.
+ *
+ * @see {@link createWebhook}
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Request
+ */
+export interface Webhook<T extends Request> extends Hook<T> {
+    /**
+     * The URL that external systems can call to send data to the workflow.
+     */
+    url: string;
+}
+export interface HookOptions {
+    /**
+     * Unique token that is used to associate with the hook.
+     *
+     * When specifying an explicit token, the token should be constructed
+     * with information that the dispatching side can reliably reconstruct
+     * the token with the information it has available.
+     *
+     * Deterministic tokens are intended for use with `createHook()` and
+     * server-side `resumeHook()` only. For webhooks (`createWebhook()`),
+     * tokens are always randomly generated to prevent unauthorized access
+     * to the public webhook endpoint.
+     *
+     * If not provided, a randomly generated token will be assigned.
+     *
+     * @example
+     *
+     * ```ts
+     * // Explicit token for a Slack bot (one workflow run per channel)
+     * const hook = createHook<SlackMessage>({
+     *   token: `slack_webhook:${channelId}`,
+     * });
+     * ```
+     */
+    token?: string;
+    /**
+     * Additional user-defined data to include with the hook payload.
+     *
+     * @example
+     *
+     * ```ts
+     * const hook = createHook<{ name: string }>({
+     *   metadata: {
+     *     type: "cat",
+     *     color: "orange",
+     *   },
+     * });
+     * ```
+     */
+    metadata?: Serializable;
+    /**
+     * Whether this hook can be resumed via the public webhook endpoint.
+     *
+     * When `true`, the hook can be triggered by sending an HTTP request to the
+     * public `/.well-known/workflow/v1/webhook/{token}` URL. This is automatically
+     * set when using `createWebhook()`.
+     *
+     * When `false` (the default), the hook can only be resumed server-side
+     * via `resumeHook()`.
+     *
+     * @default false
+     */
+    isWebhook?: boolean;
+}
+export interface WebhookOptions extends Omit<HookOptions, 'token' | 'isWebhook'> {
+    /**
+     * If set to a `Response` object, the webhook will automatically
+     * respond with the specified response.
+     *
+     * If set to `"manual"`, each individual request will need to
+     * be responded to manually from within the workflow by calling the
+     * `respondWith()` method.
+     *
+     * If not set then the webhook will automatically respond with
+     * a `202 Accepted` response.
+     */
+    respondWith?: Response | 'manual';
+}
+/**
+ * Creates a {@link Hook} that can be used to suspend and resume the workflow run with a payload.
+ *
+ * Hooks allow external systems to send arbitrary serializable data into a workflow.
+ *
+ * @param options - Configuration options for the hook.
+ * @returns A `Hook` that can be awaited to receive one or more payloads.
+ *
+ * @example
+ *
+ * ```ts
+ * export async function workflowWithHook() {
+ *   "use workflow";
+ *
+ *   const hook = createHook<{ message: string }>();
+ *   console.log('Hook token:', hook.token);
+ *
+ *   const payload = await hook;
+ *   console.log('Received:', payload.message);
+ * }
+ * ```
+ */
+export declare function createHook<T = any>(options?: HookOptions): Hook<T>;
+/**
+ * Creates a {@link Webhook} that can be used to suspend and resume the workflow
+ * run upon receiving an HTTP request to the specified URL.
+ *
+ * Webhooks will result in a {@link https://developer.mozilla.org/en-US/docs/Web/API/Request | Request} object
+ * that can be interacted with in workflow functions.
+ */
+export declare function createWebhook(options: WebhookOptions & {
+    respondWith: 'manual';
+}): Webhook<RequestWithResponse>;
+export declare function createWebhook(options?: WebhookOptions): Webhook<Request>;
+export {};
+//# sourceMappingURL=create-hook.d.ts.map

package/dist/src/compiled/@workflow/core/define-hook.d.ts

@@ -0,0 +1,68 @@
+import type { StandardSchemaV1 } from '#compiled/@standard-schema/spec/index.js';
+import type { Hook as HookEntity } from './_workflow-world.js';
+import type { Hook, HookOptions } from './create-hook.js';
+/**
+ * A typed hook interface for type-safe hook creation and resumption.
+ */
+export interface TypedHook<TInput, TOutput> {
+    /**
+     * Creates a new hook with the defined output type.
+     *
+     * Note: This method is not available in runtime bundles. Use it from workflow contexts only.
+     *
+     * @param options - Optional hook configuration
+     * @returns A Hook that resolves to the defined output type
+     */
+    create(options?: HookOptions): Hook<TOutput>;
+    /**
+     * Resumes a hook by sending a payload with the defined input type.
+     * This is a type-safe wrapper around the `resumeHook` runtime function.
+     *
+     * @param token - The unique token identifying the hook
+     * @param payload - The payload to send; if a `schema` is configured it is validated/transformed before resuming
+     * @returns Promise resolving to the hook entity
+     * @throws Error if the hook is not found or if there's an error during the process
+     */
+    resume(token: string, payload: TInput): Promise<HookEntity>;
+}
+export declare namespace TypedHook {
+    /**
+     * Extracts the input type from a {@link TypedHook}
+     */
+    type Input<T extends TypedHook<any, any>> = T extends TypedHook<infer I, any> ? I : never;
+}
+/**
+ * Defines a typed hook for type-safe hook creation and resumption.
+ *
+ * This helper provides type safety by allowing you to define the input and output types
+ * for the hook's payload, with optional validation and transformation via a schema.
+ *
+ * @param schema - Schema used to validate and transform the input payload before resuming
+ * @returns An object with `create` and `resume` functions pre-typed with the input and output types
+ *
+ * @example
+ *
+ * ```ts
+ * // Define a hook with a specific payload type
+ * const approvalHook = defineHook<{ approved: boolean; comment: string }>();
+ *
+ * // In a workflow
+ * export async function workflowWithApproval() {
+ *   "use workflow";
+ *
+ *   const hook = approvalHook.create();
+ *   const result = await hook; // Fully typed as { approved: boolean; comment: string; }
+ * }
+ *
+ * // In an API route
+ * export async function POST(request: Request) {
+ *   const { token, approved, comment } = await request.json();
+ *   await approvalHook.resume(token, { approved, comment }); // Input type
+ *   return Response.json({ success: true });
+ * }
+ * ```
+ */
+export declare function defineHook<TInput, TOutput = TInput>({ schema, }?: {
+    schema?: StandardSchemaV1<TInput, TOutput>;
+}): TypedHook<TInput, TOutput>;
+//# sourceMappingURL=define-hook.d.ts.map

package/dist/src/compiled/@workflow/core/describe-error.d.ts

@@ -0,0 +1,70 @@
+import { type RunErrorCode } from '#compiled/@workflow/errors/index.js';
+/**
+ * Attribution of a workflow/step failure for presentation.
+ *
+ * - `user`: the error came from customer code (a step or workflow function
+ *   threw, or a value they passed across a boundary wasn't serializable).
+ * - `sdk`: the SDK produced the error itself — an internal invariant broke,
+ *   or a runtime guard rejected the call. These should be rare; when they
+ *   happen we want to frame the terminal output as "this is us, not you."
+ */
+export type ErrorAttribution = 'user' | 'sdk';
+export interface ErrorDescription {
+    attribution: ErrorAttribution;
+    errorCode: RunErrorCode;
+    /**
+     * Short, class-aware hint to help a user understand what the error means.
+     * Only set for well-known SDK error classes (SerializationError,
+     * WorkflowRuntimeError, context-violation errors); `undefined` for plain
+     * user errors, where the stack is already the most useful thing to show.
+     */
+    hint?: string;
+}
+/**
+ * Error signal fields carried on persisted failure events (e.g.
+ * `run_failed` / `step_failed`). The shape is intentionally loose:
+ *
+ * - `errorCode` is typed as `string` rather than `RunErrorCode` because
+ *   the value comes from stored JSON/CBOR and may predate the current
+ *   enum — callers should not narrow on it blindly. Values that don't
+ *   match a known `RUN_ERROR_CODES` entry fall through to USER_ERROR.
+ * - `errorName` is the thrown `Error#name`. It is not universally
+ *   persisted today; callers that have access to it (either via an
+ *   in-memory throw or a richer payload) can pass it in to sharpen
+ *   the attribution and hint. When absent, `describeRunError` still
+ *   returns a sensible attribution from `errorCode` alone.
+ */
+export interface PersistedErrorSignal {
+    errorCode?: string;
+    errorName?: string;
+}
+/**
+ * Data-driven variant of {@link describeError} that works from persisted
+ * event fields instead of a live `Error` instance. Intended for CLI/web
+ * renderers that read failure events and no longer have the original
+ * thrown object.
+ */
+export declare function describeRunError(signal: PersistedErrorSignal): ErrorDescription;
+/**
+ * Describe an error for user-facing presentation. Purely informational —
+ * does not change any persisted event data or error classification used by
+ * the runtime.
+ *
+ * The attribution here is more nuanced than `classifyRunError`:
+ *
+ * - `SerializationError` is technically raised by the SDK, but it almost
+ *   always points at something the caller did (passed a non-serializable
+ *   value, didn't register a class). We attribute it to the user.
+ * - Context-violation errors (`NotInWorkflowContextError`, etc.) likewise
+ *   describe a user mistake.
+ * - `WorkflowRuntimeError` (and subclasses like `StepNotRegisteredError`)
+ *   indicates an internal SDK invariant broke — surface that as `sdk`.
+ *
+ * @param err The error value thrown by the workflow / step.
+ * @param errorCode Optional precomputed error code. Callers that already
+ *   know the code (e.g. `REPLAY_TIMEOUT` or `MAX_DELIVERIES_EXCEEDED`, which
+ *   `classifyRunError` can't derive from the error alone) should pass it so
+ *   the attribution and hint reflect the actual failure category.
+ */
+export declare function describeError(err: unknown, errorCode?: RunErrorCode): ErrorDescription;
+//# sourceMappingURL=describe-error.d.ts.map

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

@@ -0,0 +1,45 @@
+/**
+ * Browser-compatible AES-256-GCM encryption module.
+ *
+ * Uses the Web Crypto API (`globalThis.crypto.subtle`) which works in
+ * both modern browsers and Node.js 20+. This module is intentionally
+ * free of Node.js-specific imports so it can be bundled for the browser.
+ *
+ * The World interface (`getEncryptionKeyForRun`) returns a raw 32-byte
+ * AES-256 key. Callers should use `importKey()` once to convert it to a
+ * `CryptoKey`, then pass that to `encrypt()`/`decrypt()` for all
+ * operations within the same run. This avoids repeated `importKey()`
+ * calls on every encrypt/decrypt invocation.
+ *
+ * Wire format: `[nonce (12 bytes)][ciphertext + auth tag]`
+ * The `encr` format prefix is NOT part of this module — it's added/stripped
+ * by the serialization layer in `maybeEncrypt`/`maybeDecrypt`.
+ */
+export type CryptoKey = import('node:crypto').webcrypto.CryptoKey;
+/**
+ * Import a raw AES-256 key as a `CryptoKey` for use with `encrypt()`/`decrypt()`.
+ *
+ * Callers should call this once per run (after `getEncryptionKeyForRun()`)
+ * and pass the resulting `CryptoKey` to all subsequent encrypt/decrypt calls.
+ *
+ * @param raw - Raw 32-byte AES-256 key (from World.getEncryptionKeyForRun)
+ * @returns CryptoKey ready for AES-GCM operations
+ */
+export declare function importKey(raw: Uint8Array): Promise<import("crypto").webcrypto.CryptoKey>;
+/**
+ * Encrypt data using AES-256-GCM.
+ *
+ * @param key - CryptoKey from `importKey()`
+ * @param data - Plaintext to encrypt
+ * @returns `[nonce (12 bytes)][ciphertext + GCM auth tag]`
+ */
+export declare function encrypt(key: CryptoKey, data: Uint8Array): Promise<Uint8Array>;
+/**
+ * Decrypt data using AES-256-GCM.
+ *
+ * @param key - CryptoKey from `importKey()`
+ * @param data - `[nonce (12 bytes)][ciphertext + GCM auth tag]`
+ * @returns Decrypted plaintext
+ */
+export declare function decrypt(key: CryptoKey, data: Uint8Array): Promise<Uint8Array>;
+//# sourceMappingURL=encryption.d.ts.map

package/dist/src/compiled/@workflow/core/events-consumer.d.ts

@@ -0,0 +1,64 @@
+import type { Event } from './_workflow-world.js';
+/**
+ * Delay before firing the deferred unconsumed-event check after the promise
+ * queue has drained. Must be long enough for cross-VM microtask chains to
+ * propagate (resolve in host → workflow code in VM → subscribe call back
+ * in host). Any subscribe() arriving during this window cancels the check.
+ */
+export declare const DEFERRED_CHECK_DELAY_MS = 100;
+export declare enum EventConsumerResult {
+    /**
+     * Callback consumed the event, but should not be removed from the callbacks list
+     */
+    Consumed = 0,
+    /**
+     * Callback did not consume the event, so it should be passed to the next callback
+     */
+    NotConsumed = 1,
+    /**
+     * Callback consumed the event, and should be removed from the callbacks list
+     */
+    Finished = 2
+}
+type EventConsumerCallback = (event: Event | null) => EventConsumerResult;
+export interface EventsConsumerOptions {
+    /**
+     * Callback invoked when a non-null event cannot be consumed by any registered
+     * callback, indicating an orphaned or invalid event in the event log. The
+     * check is deferred until after the promise queue has drained, ensuring that
+     * any pending async work (e.g., deserialization/decryption) completes and
+     * downstream subscribe() calls have a chance to cancel the check first.
+     */
+    onUnconsumedEvent: (event: Event) => void;
+    /**
+     * Returns the current promise queue. The unconsumed event check is chained
+     * onto this queue so it only fires after all pending async work (e.g.,
+     * deserialization) has completed. This prevents false positives when async
+     * deserialization delays the resolve() that triggers the next subscribe().
+     */
+    getPromiseQueue: () => Promise<void>;
+}
+export declare class EventsConsumer {
+    eventIndex: number;
+    readonly events: Event[];
+    readonly callbacks: EventConsumerCallback[];
+    private onUnconsumedEvent;
+    private getPromiseQueue;
+    private pendingUnconsumedCheck;
+    private pendingUnconsumedTimeout;
+    private unconsumedCheckVersion;
+    constructor(events: Event[], options: EventsConsumerOptions);
+    /**
+     * Registers a callback function to be called after an event has been consumed
+     * by a different callback. The callback can return:
+     *  - `EventConsumerResult.Consumed` the event is considered consumed and will not be passed to any other callback, but the callback will remain in the callbacks list
+     *  - `EventConsumerResult.NotConsumed` the event is passed to the next callback
+     *  - `EventConsumerResult.Finished` the event is considered consumed and the callback is removed from the callbacks list
+     *
+     * @param fn - The callback function to register.
+     */
+    subscribe(fn: EventConsumerCallback): void;
+    private consume;
+}
+export {};
+//# sourceMappingURL=events-consumer.d.ts.map

package/dist/src/compiled/@workflow/core/flushable-stream.d.ts

@@ -0,0 +1,82 @@
+import { type PromiseWithResolvers } from './_workflow-utils.js';
+/**
+ * Polling interval (in ms) for lock release detection.
+ *
+ * The Web Streams API does not expose an event for "lock released but stream
+ * still open"; we can only distinguish that state by periodically attempting
+ * to acquire a reader/writer. For that reason we use polling instead of a
+ * fully event-driven approach here.
+ *
+ * 10ms is chosen so the polling tick almost never sits on the critical path:
+ * the V2 step-executor's `opsSettled` race waits for this state to resolve
+ * after each step body returns, so a coarser interval (the previous 100ms)
+ * adds visible per-step latency to streaming workflows. With a uniformly
+ * distributed offset between step return and the next tick, the expected
+ * wait is half the interval — so 10ms means ~5ms average wait per step
+ * instead of ~50ms. The per-tick work is `writable.locked` plus a
+ * `getWriter()`/`releaseLock()` probe, both microsecond-scale; 10× more
+ * ticks during a stream's lifetime is not measurable in practice.
+ */
+export declare const LOCK_POLL_INTERVAL_MS = 10;
+/**
+ * State tracker for flushable stream operations.
+ * Resolves when either:
+ * 1. Stream completes (close/error), OR
+ * 2. Lock is released AND all pending operations are flushed
+ *
+ * Note: `doneResolved` and `streamEnded` are separate:
+ * - `doneResolved`: The `done` promise has been resolved (step can complete)
+ * - `streamEnded`: The underlying stream has actually closed/errored
+ *
+ * Once `doneResolved` is set to true, the `done` promise will not resolve
+ * again. Re-acquiring locks after release is not supported as a way to
+ * trigger additional completion signaling.
+ */
+export interface FlushableStreamState extends PromiseWithResolvers<void> {
+    /** Number of write operations currently in flight to the server */
+    pendingOps: number;
+    /** Whether the `done` promise has been resolved */
+    doneResolved: boolean;
+    /** Whether the underlying stream has actually closed/errored */
+    streamEnded: boolean;
+    /** Interval ID for writable lock polling (if active) */
+    writablePollingInterval?: ReturnType<typeof setInterval>;
+    /** Interval ID for readable lock polling (if active) */
+    readablePollingInterval?: ReturnType<typeof setInterval>;
+}
+export declare function createFlushableState(): FlushableStreamState;
+/**
+ * Polls a WritableStream to check if the user has released their lock.
+ * Resolves the done promise when lock is released and no pending ops remain.
+ *
+ * Note: Only resolves if stream is unlocked but NOT closed. If the user closes
+ * the stream, the pump will handle resolution via the stream ending naturally.
+ *
+ * Protection: If polling is already active on this state, the existing interval
+ * is used to avoid creating multiple simultaneous polling operations.
+ */
+export declare function pollWritableLock(writable: WritableStream, state: FlushableStreamState): void;
+/**
+ * Polls a ReadableStream to check if the user has released their lock.
+ * Resolves the done promise when lock is released and no pending ops remain.
+ *
+ * Note: Only resolves if stream is unlocked but NOT closed. If the user closes
+ * the stream, the pump will handle resolution via the stream ending naturally.
+ *
+ * Protection: If polling is already active on this state, the existing interval
+ * is used to avoid creating multiple simultaneous polling operations.
+ */
+export declare function pollReadableLock(readable: ReadableStream, state: FlushableStreamState): void;
+/**
+ * Creates a flushable pipe from a ReadableStream to a WritableStream.
+ * Unlike pipeTo(), this resolves when:
+ * 1. The source stream completes (close/error), OR
+ * 2. The user releases their lock on userStream AND all pending writes are flushed
+ *
+ * @param source - The readable stream to read from (e.g., transform's readable)
+ * @param sink - The writable stream to write to (e.g., server writable)
+ * @param state - The flushable state tracker
+ * @returns Promise that resolves when stream ends (not when done promise resolves)
+ */
+export declare function flushablePipe(source: ReadableStream, sink: WritableStream, state: FlushableStreamState): Promise<void>;
+//# sourceMappingURL=flushable-stream.d.ts.map

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

@@ -0,0 +1,48 @@
+import type { Serializable } from './schemas.js';
+export interface StepInvocationQueueItem {
+    type: 'step';
+    correlationId: string;
+    stepName: string;
+    args: Serializable[];
+    closureVars?: Record<string, Serializable>;
+    thisVal?: Serializable;
+    hasCreatedEvent?: boolean;
+}
+export interface HookInvocationQueueItem {
+    type: 'hook';
+    correlationId: string;
+    token: string;
+    metadata?: Serializable;
+    hasCreatedEvent?: boolean;
+    disposed?: boolean;
+    isWebhook?: boolean;
+    isSystem?: boolean;
+    abortRequested?: boolean;
+    abortReason?: unknown;
+}
+export interface WaitInvocationQueueItem {
+    type: 'wait';
+    correlationId: string;
+    resumeAt: Date;
+    hasCreatedEvent?: boolean;
+}
+export type QueueItem = StepInvocationQueueItem | HookInvocationQueueItem | WaitInvocationQueueItem;
+/**
+ * An error that is thrown when one or more operations (steps/hooks/etc.) are called but do
+ * not yet have corresponding entries in the event log. The workflow
+ * dispatcher will catch this error and push the operations
+ * onto the queue.
+ */
+export declare class WorkflowSuspension extends Error {
+    steps: QueueItem[];
+    globalThis: typeof globalThis;
+    stepCount: number;
+    hookCount: number;
+    waitCount: number;
+    hookDisposedCount: number;
+    abortCount: number;
+    constructor(stepsInput: Map<string, QueueItem>, global: typeof globalThis);
+    static is(value: unknown): value is WorkflowSuspension;
+}
+export declare function ENOTSUP(): never;
+//# sourceMappingURL=global.d.ts.map

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

@@ -1,38 +1,19 @@
-import type { WorkflowWritableStreamOptions } from "./runtime.js";
-
-export interface Hook<T = unknown> extends AsyncIterable<T> {
-  readonly token: string;
-  dispose(): void;
-  [Symbol.dispose](): void;
-}
-export interface HookOptions {
-  token?: string | undefined;
-  timeout?: string | number | undefined;
-}
-export type RequestWithResponse<T = unknown> = any;
-export type RetryableErrorOptions = any;
-export type Webhook<T = unknown> = any;
-export type WebhookOptions = HookOptions;
-export interface StepMetadata {
-  [key: string]: unknown;
-}
-export interface WorkflowMetadata {
-  readonly url: string;
-  readonly workflowRunId: string;
-  readonly workflowName: string;
-  readonly workflowStartedAt: Date;
-  [key: string]: unknown;
-}
-export declare class FatalError extends Error {}
-export declare class RetryableError extends Error {
-  constructor(message: string, options?: RetryableErrorOptions);
-}
-export declare function createHook<T = unknown>(options?: HookOptions): Hook<T>;
-export declare function createWebhook<T = unknown>(options?: WebhookOptions): Webhook<T>;
-export declare function defineHook<T = unknown>(): Hook<T>;
-export declare function getStepMetadata(): StepMetadata;
-export declare function getWorkflowMetadata(): WorkflowMetadata;
-export declare function getWritable<T = unknown>(
-  options?: WorkflowWritableStreamOptions,
-): WritableStream<T>;
-export declare function sleep(duration: string | number): Promise<void>;
+/**
+ * Just the core utilities that are meant to be imported by user
+ * steps/workflows. This allows the bundler to tree-shake and limit what goes
+ * into the final user bundles. Logic for running/handling steps/workflows
+ * should live in runtime. Eventually these might be separate packages
+ * `workflow` and `workflow/runtime`?
+ *
+ * Everything here will get re-exported under the 'workflow' top level package.
+ * This should be a minimal set of APIs so **do not anything here** unless it's
+ * needed for userland workflow code.
+ */
+export { FatalError, RetryableError, type RetryableErrorOptions, } from '#compiled/@workflow/errors/index.js';
+export { createHook, createWebhook, type Hook, type HookOptions, type RequestWithResponse, type Webhook, type WebhookOptions, } from './create-hook.js';
+export { defineHook, type TypedHook } from './define-hook.js';
+export { sleep } from './sleep.js';
+export { getStepMetadata, type StepMetadata, } from './step/get-step-metadata.js';
+export { getWorkflowMetadata, type WorkflowMetadata, } from './step/get-workflow-metadata.js';
+export { getWritable, type WorkflowWritableStreamOptions, } from './step/writable-stream.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,25 @@
+/**
+ * Structured-log composition for `console.error` / `console.warn`. Emits
+ * one string in three sections so the most useful information is at the
+ * top, stack trace at the bottom:
+ *
+ *     [workflow-sdk] <framing line>
+ *       user error · FatalError
+ *       run    wrun_…
+ *       step   step_… · add (./workflows/x)
+ *       hint:  Move the call to a step function.
+ *     FatalError: …
+ *         at … (trimmed stack — internals collapsed)
+ *
+ * Without this composition, callers passing `${framing}\n${stack}` as the
+ * message and structured fields as the metadata object got `util.inspect`'s
+ * default object dump appended *after* the stack, which buries the run ID
+ * and attribution badge under 30+ lines of `node_modules/.pnpm/...` frames.
+ *
+ * The same metadata is also emitted as structured OTel span events from
+ * the logger itself, so backends that want JSON-shaped data still get it.
+ * web/web-shared do not consume stderr at all — they read CBOR/JSON event
+ * payloads from the World event log.
+ */
+export declare function composeLogLine(prefix: string, message: string, metadata: Record<string, unknown> | undefined): string;
+//# sourceMappingURL=log-format.d.ts.map

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

@@ -0,0 +1,29 @@
+type LogMetadata = Record<string, unknown>;
+type LogFn = (message: string, metadata?: LogMetadata) => void;
+export interface Logger {
+    debug: LogFn;
+    info: LogFn;
+    warn: LogFn;
+    error: LogFn;
+    /**
+     * Returns a child logger that merges the given metadata into every call.
+     * Useful for attaching stable context (e.g. `workflowRunId`, `workflowName`,
+     * `stepId`) so callers don't have to repeat it on every log.
+     *
+     * Call-site metadata wins on conflict, so children can still override.
+     */
+    child: (metadata: LogMetadata) => Logger;
+    /**
+     * Convenience child logger for a workflow run. Equivalent to
+     * `logger.child({ workflowRunId, workflowName })`, but centralized so all
+     * runtime code structures run metadata consistently.
+     */
+    forRun: (workflowRunId: string, workflowName?: string, extra?: LogMetadata) => Logger;
+}
+export declare const stepLogger: Logger;
+export declare const runtimeLogger: Logger;
+export declare const webhookLogger: Logger;
+export declare const eventsLogger: Logger;
+export declare const adapterLogger: Logger;
+export {};
+//# sourceMappingURL=logger.d.ts.map