experimental-ash 0.22.2 → 0.24.0

package/dist/src/compiled/@workflow/core/runtime/helpers.d.ts

@@ -0,0 +1,97 @@
+import type { Event, HealthCheckPayload, ValidQueueName, WorkflowRun, World } from '../_workflow-world.js';
+import { type CryptoKey } from '../encryption.js';
+/**
+ * Validates a workflow name and returns the corresponding queue name.
+ * Ensures the workflow name only contains safe characters before
+ * interpolating it into the queue name string.
+ */
+export declare function getWorkflowQueueName(workflowName: string): ValidQueueName;
+/**
+ * Result of a health check operation.
+ */
+export interface HealthCheckResult {
+    healthy: boolean;
+    /** Error message if health check failed */
+    error?: string;
+    /** Latency if the health check was successful */
+    latencyMs?: number;
+    /** Spec version of the responding deployment */
+    specVersion?: number;
+}
+/**
+ * Checks if the given message is a health check payload.
+ * If so, returns the parsed payload. Otherwise returns undefined.
+ */
+export declare function parseHealthCheckPayload(message: unknown): HealthCheckPayload | undefined;
+/**
+ * Handles a health check message by writing the result to the world's stream.
+ * The caller can listen to this stream to get the health check response.
+ *
+ * @param healthCheck - The parsed health check payload
+ * @param endpoint - Which endpoint is responding ('workflow' or 'step')
+ */
+export declare function handleHealthCheckMessage(healthCheck: HealthCheckPayload, endpoint: 'workflow' | 'step', worldSpecVersion?: number): Promise<void>;
+export type HealthCheckEndpoint = 'workflow' | 'step';
+export interface HealthCheckOptions {
+    /** Timeout in milliseconds to wait for health check response. Default: 30000 (30s) */
+    timeout?: number;
+    /** Deployment ID to send the health check to. Falls back to process.env.VERCEL_DEPLOYMENT_ID. */
+    deploymentId?: string;
+}
+export declare function healthCheck(world: World, endpoint: HealthCheckEndpoint, options?: HealthCheckOptions): Promise<HealthCheckResult>;
+/**
+ * Loads workflow run events by iterating through all pages of paginated
+ * results. Events are returned in chronological (ascending) order for
+ * deterministic workflow replay.
+ *
+ * @param runId - The workflow run ID.
+ * @param afterCursor - If provided, only events after this cursor are
+ *   returned (incremental load). If omitted, all events are returned.
+ *   The returned cursor can be passed back in on a subsequent call for
+ *   incremental loading.
+ */
+export declare function loadWorkflowRunEvents(runId: string, afterCursor?: string): Promise<{
+    events: Event[];
+    cursor: string | null;
+}>;
+/**
+ * Wraps a request/response handler and adds a health check "mode"
+ * based on the presence of a `__health` query parameter.
+ */
+export declare function withHealthCheck(handler: (req: Request) => Promise<Response>, worldSpecVersion?: number): (req: Request) => Promise<Response>;
+/**
+ * Queues a message to the specified queue with tracing.
+ */
+export declare function queueMessage(world: World, ...args: Parameters<typeof world.queue>): Promise<void>;
+/**
+ * Calculates the queue overhead time in milliseconds for a given message.
+ */
+export declare function getQueueOverhead(message: {
+    requestedAt?: Date;
+}): {
+    [k: string]: number;
+} | undefined;
+/**
+ * Returns a memoized accessor for the per-run AES-256 encryption key.
+ *
+ * The first call resolves the key via `world.getEncryptionKeyForRun` (which
+ * may do HKDF derivation locally on Vercel, or a network fetch from
+ * external contexts) and imports it as a `CryptoKey`; subsequent calls
+ * await the same cached promise. If the world doesn't support encryption
+ * or the run has no key configured, the cached value is `undefined`.
+ *
+ * Used by step / workflow handlers to defer the (potentially expensive)
+ * key fetch until the first code path that actually needs it — typically
+ * input hydration on the success path, or error dehydration on a failure
+ * path. Both paths can race-call the accessor without triggering duplicate
+ * fetches.
+ *
+ * Errors thrown by `getEncryptionKeyForRun` propagate to every caller
+ * (the cached promise rejects). This is intentional: when encryption is
+ * configured, we never want to silently fall back to plaintext
+ * serialization. A propagated error in an event-emission path leaves the
+ * outer try/catch to log and surface the issue; the queue's redelivery
+ * semantics will retry the key fetch on the next attempt.
+ */
+export declare function memoizeEncryptionKey(world: World, runOrId: WorkflowRun | string): () => Promise<CryptoKey | undefined>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/replay-budget.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Per-invocation accounting of the *non-step* portion of a workflow
+ * handler run: deterministic event-log replay, workflow-VM execution
+ * between step boundaries, suspension handling, queue round-trips, etc.
+ * Inline step bodies (`"use step"` functions invoked via `executeStep`)
+ * are intentionally excluded — they are bounded by the platform's
+ * function `maxDuration` and the `NO_INLINE_REPLAY_AFTER_MS` early-return
+ * guard.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const budget = new ReplayBudget();
+ * // …non-step work happens here, accumulates against the budget…
+ * budget.pause();
+ * try {
+ *   await executeStep(...); // not charged
+ * } finally {
+ *   budget.resume();
+ * }
+ * // back to charging
+ * if (budget.isExhausted()) { ... }
+ * ```
+ *
+ * Implementation notes:
+ *
+ * - `pause()` and `resume()` are idempotent: calling `pause()` while
+ *   already paused (or `resume()` while already resumed) is a no-op.
+ *   This protects against double-counting in future refactors that nest
+ *   step execution or take an early-return path between a `pause()` and
+ *   the matching `resume()`.
+ * - `isExhausted()` is checked at loop boundaries by the caller — the
+ *   budget itself does not arm any timers. This means an in-flight
+ *   pathological `runWorkflow` call (e.g. a huge event-log replay) can
+ *   overshoot the budget by up to one iteration's worth of work before
+ *   the next check fires. In practice the 20s headroom built into
+ *   `MAX_REPLAY_TIMEOUT_MS` (and the function `maxDuration` ceiling)
+ *   gives us slack; the old `setTimeout`-based approach also ultimately
+ *   relied on the platform SIGTERM as the hard backstop.
+ */
+export declare class ReplayBudget {
+    private readonly limitMs;
+    private elapsedMs;
+    private intervalStart;
+    constructor(limitMs?: number);
+    /**
+     * The configured replay-timeout limit, in ms. Useful for log messages.
+     */
+    get configuredLimitMs(): number;
+    /**
+     * Total non-step time accumulated so far, in ms. Includes the
+     * currently-active interval if the budget is not paused.
+     */
+    elapsed(): number;
+    /**
+     * Stop counting elapsed time toward the budget. Idempotent — safe to
+     * call multiple times in a row; subsequent calls are no-ops until
+     * `resume()` reopens an interval.
+     */
+    pause(): void;
+    /**
+     * Resume counting elapsed time toward the budget. Idempotent — safe to
+     * call multiple times in a row; subsequent calls re-anchor the
+     * interval start to `now()`, which is fine because no time accrues
+     * between back-to-back `resume()` calls.
+     */
+    resume(): void;
+    /**
+     * True if the budget has been exhausted (`elapsed() >= limitMs`).
+     * Callers should invoke `handleExhausted(...)` afterward and return
+     * from the handler.
+     */
+    isExhausted(): boolean;
+}
+/**
+ * Fail the run (or retry, on early attempts) when the replay budget is
+ * exhausted. The handling depends on whether the underlying World
+ * supports `process.exit(1)` as a queue redelivery signal (see
+ * `World.processExitTriggersQueueRedelivery`):
+ *
+ * - **Managed-platform Worlds** (`world-vercel`): on attempts <=
+ *   `REPLAY_TIMEOUT_MAX_RETRIES` exit the process so the platform fails
+ *   the invocation and the queue redelivers; on the next attempt write
+ *   `run_failed` with `RUN_ERROR_CODES.REPLAY_TIMEOUT` and exit.
+ *
+ * - **In-process Worlds** (`world-local`, dev servers): calling
+ *   `process.exit()` would terminate the host (e.g. `pnpm dev`), so
+ *   instead log a warning, write `run_failed` best-effort, and return.
+ *   The framework completes the request normally.
+ */
+export declare function handleReplayBudgetExhausted(args: {
+    runId: string;
+    workflowName: string;
+    requestId: string | undefined;
+    attempt: number;
+    limitMs: number;
+}): Promise<void>;
+//# sourceMappingURL=replay-budget.d.ts.map

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

@@ -0,0 +1,77 @@
+import { type Hook } from '../_workflow-world.js';
+import { type CryptoKey } from '../encryption.js';
+/**
+ * Get the hook by token to find the associated workflow run,
+ * and hydrate the `metadata` property if it was set from within
+ * the workflow run.
+ *
+ * @param token - The unique token identifying the hook
+ */
+export declare function getHookByToken(token: string): Promise<Hook>;
+/**
+ * Resumes a workflow run by sending a payload to a hook identified by its token.
+ *
+ * This function is called externally (e.g., from an API route or server action)
+ * to send data to a hook and resume the associated workflow run.
+ *
+ * @param tokenOrHook - The unique token identifying the hook, or the hook object itself
+ * @param payload - The data payload to send to the hook
+ * @returns Promise resolving to the hook
+ * @throws Error if the hook is not found or if there's an error during the process
+ *
+ * @example
+ *
+ * ```ts
+ * // In an API route
+ * import { resumeHook } from '@workflow/core/runtime';
+ *
+ * export async function POST(request: Request) {
+ *   const { token, data } = await request.json();
+ *
+ *   try {
+ *     const hook = await resumeHook(token, data);
+ *     return Response.json({ runId: hook.runId });
+ *   } catch (error) {
+ *     return new Response('Hook not found', { status: 404 });
+ *   }
+ * }
+ * ```
+ */
+export declare function resumeHook<T = any>(tokenOrHook: string | Hook, payload: T, encryptionKeyOverride?: CryptoKey): Promise<Hook>;
+/**
+ * Resumes a webhook by sending a {@link https://developer.mozilla.org/en-US/docs/Web/API/Request | Request}
+ * object to a hook identified by its token.
+ *
+ * This function is called externally (e.g., from an API route or server action)
+ * to send a request to a webhook and resume the associated workflow run.
+ *
+ * @param token - The unique token identifying the hook
+ * @param request - The request to send to the hook
+ * @returns Promise resolving to the response
+ * @throws Error if the hook is not found or if there's an error during the process
+ *
+ * @example
+ *
+ * ```ts
+ * // In an API route
+ * import { resumeWebhook } from '@workflow/core/runtime';
+ *
+ * export async function POST(request: Request) {
+ *   const url = new URL(request.url);
+ *   const token = url.searchParams.get('token');
+ *
+ *   if (!token) {
+ *     return new Response('Missing token', { status: 400 });
+ *   }
+ *
+ *   try {
+ *     const response = await resumeWebhook(token, request);
+ *     return response;
+ *   } catch (error) {
+ *     return new Response('Webhook not found', { status: 404 });
+ *   }
+ * }
+ * ```
+ */
+export declare function resumeWebhook(token: string, request: Request): Promise<Response>;
+//# sourceMappingURL=resume-hook.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/run.d.ts

@@ -0,0 +1,134 @@
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from '../_workflow-serde.js';
+import { type WorkflowRunStatus } from '../_workflow-world.js';
+import { type StopSleepOptions, type StopSleepResult } from './runs.js';
+/**
+ * A `ReadableStream` extended with workflow-specific helpers.
+ */
+export type WorkflowReadableStream<R = any> = ReadableStream<R> & {
+    /**
+     * Returns the tail index (index of the last known chunk, 0-based) of the
+     * underlying workflow stream. Useful for resolving a negative `startIndex`
+     * into an absolute position — for example, when building reconnection
+     * endpoints that need to inform the client where the stream starts.
+     *
+     * Returns `-1` when no chunks have been written yet.
+     */
+    getTailIndex(): Promise<number>;
+};
+/**
+ * Options for configuring a workflow's readable stream.
+ */
+export interface WorkflowReadableStreamOptions {
+    /**
+     * An optional namespace to distinguish between multiple streams associated
+     * with the same workflow run.
+     */
+    namespace?: string;
+    /**
+     * The index number of the starting chunk to begin reading the stream from.
+     * Negative values start from the end (e.g. -3 reads the last 3 chunks).
+     */
+    startIndex?: number;
+    /**
+     * Any asynchronous operations that need to be performed before the execution
+     * environment is paused / terminated
+     * (i.e. using [`waitUntil()`](https://developer.mozilla.org/docs/Web/API/ExtendableEvent/waitUntil) or similar).
+     */
+    ops?: Promise<any>[];
+    /**
+     * The global object to use for hydrating types from the global scope.
+     *
+     * Defaults to {@link [`globalThis`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/globalThis)}.
+     */
+    global?: Record<string, any>;
+}
+/**
+ * A handler class for a workflow run.
+ */
+export declare class Run<TResult> {
+    #private;
+    static [WORKFLOW_SERIALIZE](instance: Run<unknown>): {
+        runId: string;
+        resilientStart: boolean;
+    };
+    static [WORKFLOW_DESERIALIZE](data: {
+        runId: string;
+        resilientStart?: boolean;
+    }): Run<unknown>;
+    /**
+     * The ID of the workflow run.
+     */
+    runId: string;
+    constructor(runId: string, opts?: {
+        resilientStart?: boolean;
+    });
+    /**
+     * Interrupts pending `sleep()` calls, resuming the workflow early.
+     *
+     * @param options - Optional settings to target specific sleep calls by correlation ID.
+     *   If not provided, all pending sleep calls will be interrupted.
+     * @returns A {@link StopSleepResult} object containing the number of sleep calls that were interrupted.
+     */
+    wakeUp(options?: StopSleepOptions): Promise<StopSleepResult>;
+    /**
+     * Cancels the workflow run.
+     */
+    cancel(): Promise<void>;
+    /**
+     * Whether the workflow run exists.
+     */
+    get exists(): Promise<boolean>;
+    /**
+     * The status of the workflow run.
+     */
+    get status(): Promise<WorkflowRunStatus>;
+    /**
+     * The return value of the workflow run.
+     * Polls the workflow return value until it is completed.
+     */
+    get returnValue(): Promise<TResult>;
+    /**
+     * The name of the workflow.
+     */
+    get workflowName(): Promise<string>;
+    /**
+     * The timestamp when the workflow run was created.
+     */
+    get createdAt(): Promise<Date>;
+    /**
+     * The timestamp when the workflow run started execution.
+     * Returns undefined if the workflow has not started yet.
+     */
+    get startedAt(): Promise<Date | undefined>;
+    /**
+     * The timestamp when the workflow run completed.
+     * Returns undefined if the workflow has not completed yet.
+     */
+    get completedAt(): Promise<Date | undefined>;
+    /**
+     * The readable stream of the workflow run.
+     */
+    get readable(): WorkflowReadableStream;
+    /**
+     * Retrieves the workflow run's default readable stream, which reads chunks
+     * written to the corresponding writable stream {@link getWritable}.
+     *
+     * The returned stream has an additional {@link WorkflowReadableStream.getTailIndex | getTailIndex()}
+     * helper that returns the index of the last known chunk. This is useful when
+     * building reconnection endpoints that need to inform clients where the
+     * stream starts.
+     *
+     * @param options - The options for the readable stream.
+     * @returns A `WorkflowReadableStream` for the workflow run.
+     */
+    getReadable<R = any>(options?: WorkflowReadableStreamOptions): WorkflowReadableStream<R>;
+}
+/**
+ * Retrieves a `Run` object for a given run ID.
+ *
+ * @param runId - The workflow run ID obtained from {@link start}.
+ * @returns A `Run` object.
+ * @throws WorkflowRunNotFoundError if the run ID is not found.
+ */
+export declare function getRun<TResult>(runId: string): Run<TResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/runs.d.ts

@@ -0,0 +1,50 @@
+import { type World } from '../_workflow-world.js';
+export interface RecreateRunOptions {
+    deploymentId?: string;
+    specVersion?: number;
+}
+export interface StopSleepResult {
+    /** Number of pending sleeps that were stopped */
+    stoppedCount: number;
+}
+export interface ReadStreamOptions {
+    /**
+     * The index to start reading from. Defaults to 0.
+     * Negative values start from the end (e.g. -3 reads the last 3 chunks).
+     */
+    startIndex?: number;
+}
+export interface StopSleepOptions {
+    /**
+     * Optional list of specific correlation IDs to target.
+     * If provided, only these sleep calls will be interrupted.
+     * If not provided, all pending sleep calls will be interrupted.
+     */
+    correlationIds?: string[];
+}
+/**
+ * Start a new workflow run based on an existing run.
+ */
+export declare function recreateRunFromExisting(world: World, runId: string, options?: RecreateRunOptions): Promise<string>;
+/**
+ * Cancel a workflow run.
+ */
+export declare function cancelRun(world: World, runId: string): Promise<void>;
+/**
+ * Re-enqueue a workflow run.
+ */
+export declare function reenqueueRun(world: World, runId: string): Promise<void>;
+/**
+ * Wake up a workflow run by interrupting pending sleep() calls.
+ */
+export declare function wakeUpRun(world: World, runId: string, options?: StopSleepOptions): Promise<StopSleepResult>;
+/**
+ * Read from a stream by stream ID.
+ * Returns a ReadableStream of Uint8Array chunks.
+ */
+export declare function readStream(world: World, runId: string, streamId: string, options?: ReadStreamOptions): Promise<ReadableStream<Uint8Array>>;
+/**
+ * List all stream IDs for a workflow run.
+ */
+export declare function listStreams(world: World, runId: string): Promise<string[]>;
+//# sourceMappingURL=runs.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/start.d.ts

@@ -0,0 +1,59 @@
+import type { World } from '../_workflow-world.js';
+import { Run } from './run.js';
+export interface StartOptionsBase {
+    /**
+     * The world to use for the workflow run creation,
+     * by default the world is inferred from the environment variables.
+     */
+    world?: World;
+    /**
+     * The spec version to use for the workflow run. Defaults to the latest version.
+     */
+    specVersion?: number;
+}
+export interface StartOptionsWithDeploymentId extends StartOptionsBase {
+    /**
+     * The deployment ID to use for the workflow run.
+     *
+     * By default, this is automatically inferred from environment variables
+     * when deploying to Vercel.
+     *
+     * Set to `'latest'` to automatically resolve the most recent deployment
+     * for the current environment (same production target or git branch).
+     * This is currently a Vercel-specific feature.
+     *
+     * **Note:** When `deploymentId` is provided, the argument and return types become `unknown`
+     * since there is no guarantee the types will be consistent across deployments.
+     */
+    deploymentId: 'latest' | (string & {});
+}
+export interface StartOptionsWithoutDeploymentId extends StartOptionsBase {
+    deploymentId?: undefined;
+}
+/**
+ * Options for starting a workflow run.
+ */
+export type StartOptions = StartOptionsWithDeploymentId | StartOptionsWithoutDeploymentId;
+/**
+ * Represents an imported workflow function.
+ */
+export type WorkflowFunction<TArgs extends unknown[], TResult> = (...args: TArgs) => Promise<TResult>;
+/**
+ * Represents the generated metadata of a workflow function.
+ */
+export type WorkflowMetadata = {
+    workflowId: string;
+};
+/**
+ * Starts a workflow run.
+ *
+ * @param workflow - The imported workflow function to start.
+ * @param args - The arguments to pass to the workflow (optional).
+ * @param options - The options for the workflow run (optional).
+ * @returns The unique run ID for the newly started workflow invocation.
+ */
+export declare function start<TArgs extends unknown[], TResult>(workflow: WorkflowFunction<TArgs, TResult> | WorkflowMetadata, args: unknown[], options: StartOptionsWithDeploymentId): Promise<Run<unknown>>;
+export declare function start<TResult>(workflow: WorkflowFunction<[], TResult> | WorkflowMetadata, options: StartOptionsWithDeploymentId): Promise<Run<unknown>>;
+export declare function start<TArgs extends unknown[], TResult>(workflow: WorkflowFunction<TArgs, TResult> | WorkflowMetadata, args: TArgs, options?: StartOptionsWithoutDeploymentId): Promise<Run<TResult>>;
+export declare function start<TResult>(workflow: WorkflowFunction<[], TResult> | WorkflowMetadata, options?: StartOptionsWithoutDeploymentId): Promise<Run<TResult>>;
+//# sourceMappingURL=start.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/step-executor.d.ts

@@ -0,0 +1,40 @@
+import type { World } from '../_workflow-world.js';
+import type { CryptoKey } from '../encryption.js';
+export interface StepExecutorParams {
+    world: World;
+    workflowRunId: string;
+    workflowName: string;
+    workflowStartedAt: number;
+    stepId: string;
+    stepName: string;
+    encryptionKey?: CryptoKey;
+}
+/**
+ * Result of a step execution attempt. The caller decides what to do
+ * based on the result type (e.g., queue workflow continuation, replay inline, etc.).
+ */
+export type StepExecutionResult = {
+    type: 'completed';
+    hasPendingOps?: boolean;
+} | {
+    type: 'failed';
+} | {
+    type: 'retry';
+    timeoutSeconds: number;
+} | {
+    type: 'skipped';
+} | {
+    type: 'gone';
+} | {
+    type: 'throttled';
+    timeoutSeconds: number;
+};
+/**
+ * Executes a single step: creates step_started event, hydrates input,
+ * runs the step function, creates step_completed/step_failed/step_retrying events.
+ *
+ * Does NOT queue workflow continuation messages — the caller decides what to do next.
+ * Used by both the V1 step handler and the V2 combined handler.
+ */
+export declare function executeStep(params: StepExecutorParams): Promise<StepExecutionResult>;
+//# sourceMappingURL=step-executor.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/step-handler.d.ts

@@ -0,0 +1,2 @@
+export declare const stepEntrypoint: (req: Request) => Promise<Response>;
+//# sourceMappingURL=step-handler.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/suspension-handler.d.ts

@@ -0,0 +1,42 @@
+import type { Span } from '#compiled/@opentelemetry/api/index.js';
+import { type WorkflowRun, type World } from '../_workflow-world.js';
+import type { StepInvocationQueueItem, WorkflowSuspension } from '../global.js';
+export interface SuspensionHandlerParams {
+    suspension: WorkflowSuspension;
+    world: World;
+    run: WorkflowRun;
+    span?: Span;
+    requestId?: string;
+}
+/**
+ * Result of handling a suspension. Returns pending step items so the caller
+ * can decide which to execute inline vs queue to background.
+ */
+export interface SuspensionHandlerResult {
+    /** Pending step items with events created but NOT queued */
+    pendingSteps: StepInvocationQueueItem[];
+    /**
+     * Correlation IDs for which this suspension call actually wrote the
+     * step_created event (as opposed to catching EntityConflictError because
+     * a concurrent handler wrote it first). Only the handler that wrote the
+     * step_created event should queue / inline-execute the step — this
+     * guarantees a single owner per step, even when multiple handlers race
+     * into the same batch boundary.
+     */
+    createdStepCorrelationIds: Set<string>;
+    /** Timeout from waits, if any */
+    timeoutSeconds?: number;
+    /** Whether a hook conflict was detected (should re-invoke immediately) */
+    hasHookConflict: boolean;
+}
+/**
+ * Handles a workflow suspension by processing all pending operations (hooks, steps, waits).
+ * Creates events for all operations but does NOT queue step messages — returns the pending
+ * steps so the caller can decide which to execute inline vs queue to background.
+ *
+ * Processing order:
+ * 1. Hooks are processed first to prevent race conditions with webhook receivers
+ * 2. Step events and wait events are created in parallel
+ */
+export declare function handleSuspension({ suspension, world, run, span, requestId, }: SuspensionHandlerParams): Promise<SuspensionHandlerResult>;
+//# sourceMappingURL=suspension-handler.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/world-init.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Server-only side-effect module that ensures `world.ts` is loaded so its
+ * module-load side effect — `globalThis[GetWorldFnKey] ??= getWorld` —
+ * fires in host bundles.
+ *
+ * # Why this exists
+ *
+ * `getWorldLazy()` in `./get-world-lazy.ts` checks the globalThis cache
+ * (populated by `world.ts`'s module-load side effect) before falling back
+ * to a runtime-built dynamic `import('./world.js')`. When a server route
+ * only consumes a single helper that goes through `getWorldLazy` — most
+ * commonly `start` from `workflow/api` — webpack/turbopack tree-shake the
+ * named import `{ getWorld } from './runtime/world.js'` out of
+ * `runtime.ts`, taking `world.ts`'s module evaluation with it. The
+ * globalThis registration never fires.
+ *
+ * `getWorldLazy` then falls through to its dynamic-import fallback, which
+ * itself fails: webpack inlines `get-world-lazy.js` into the bundled route
+ * file, so the relative specifier `./world.js` resolves against
+ * `/var/task/<app>/.next/server/app/<...>/route.js` — where no sibling
+ * `world.js` exists — and Node throws `MODULE_NOT_FOUND`. The symptom is a
+ * cold-start regression: the very first user request that goes through
+ * `start()` fails until some other code path (typically the queue-driven
+ * `/.well-known/workflow/v1/flow` route, which uses `getWorld` directly
+ * via `workflowEntrypoint`) has loaded `world.ts` and populated the
+ * cache.
+ *
+ * Importing this module for its side effect — exactly once, from the
+ * host-side `workflow/api` (`packages/workflow/src/api.ts`) — guarantees
+ * `world.ts` enters the bundle, the global is registered at module load,
+ * and `getWorldLazy()` short-circuits to the registered function on the
+ * first call.
+ *
+ * # Why a separate module instead of importing `./world.js` directly
+ *
+ * `world.ts` is internal to `@workflow/core` and not part of the public
+ * exports surface. Adding a dedicated public init entry (this file)
+ * keeps the side-effect intent obvious to anyone reading
+ * `packages/workflow/src/api.ts`, and lets the `workflow` export
+ * condition route to a stub for VM/step bundles (see below).
+ *
+ * # Why this doesn't break VM/step bundles
+ *
+ * The `@workflow/core/runtime/world-init` export resolves via the
+ * `workflow` condition to `./dist/workflow/world-init-stub.js`, an empty
+ * module. Esbuild runs the workflow VM and step bundlers with the
+ * `workflow` condition active, so they pick up the stub and never reach
+ * `world.ts`. Host bundlers (webpack, turbopack, Node.js) use the
+ * `default` (or `node`) condition and pick up this file, loading
+ * `world.ts` as intended. The split keeps `@workflow/world-vercel`,
+ * `@workflow/world-local`, `cbor-x`, and other server-only deps out of
+ * the workflow sandbox bundle.
+ *
+ * # Why we keep the `getWorldLazy` dynamic-import fallback
+ *
+ * The fallback remains in `./get-world-lazy.ts` as a defense-in-depth for
+ * environments we haven't accounted for (CJS test runners, scripts that
+ * import `start` without going through `workflow/api`, future bundlers
+ * with stricter tree-shaking). With this init module in place, the
+ * fallback should never fire in normal use — but if it does, the
+ * dynamic-import branch still resolves correctly when `world.js` is
+ * physically adjacent on disk (e.g., direct Node.js execution of
+ * unbundled source).
+ *
+ * # Maintenance notes
+ *
+ * If you add another `getWorldLazy()` consumer that's reachable from a
+ * host route without going through `workflow/api` (e.g., a new helper in
+ * `workflow/runtime`), make sure that entry also imports this module —
+ * or that it transitively reaches `world.ts` via a non-tree-shakeable
+ * path. Adding a regression test in `world-init.test.ts` is preferred to
+ * relying on careful manual tracing.
+ */
+import './world.js';
+//# sourceMappingURL=world-init.d.ts.map