eve 0.5.4 → 0.6.0-beta.3

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

@@ -0,0 +1,50 @@
+import { type World } from '#compiled/@workflow/world/index.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 '#compiled/@workflow/world/index.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,42 @@
+import type { World } from '#compiled/@workflow/world/index.js';
+import type { CryptoKey } from '../encryption.js';
+export interface StepExecutorParams {
+    world: World;
+    workflowRunId: string;
+    /** Deployment that owns the workflow run, for forwarded writable streams. */
+    workflowDeploymentId?: 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 '#compiled/@workflow/world/index.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

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

@@ -0,0 +1,32 @@
+import type { World } from '#compiled/@workflow/world/index.js';
+/**
+ * Create a new world instance based on environment variables.
+ * WORKFLOW_TARGET_WORLD is used to determine the target world.
+ *
+ * Note: WORKFLOW_VERCEL_* env vars (PROJECT, TEAM, AUTH_TOKEN, etc.) are
+ * intentionally NOT read here. Those are for CLI/observability tooling only
+ * and should not affect runtime behavior. The Vercel runtime provides
+ * authentication via OIDC tokens and project context via system env vars
+ * (VERCEL_DEPLOYMENT_ID, VERCEL_PROJECT_ID). Tooling that needs these env
+ * vars should call createVercelWorld() directly with an explicit config and
+ * use setWorld() to inject the instance.
+ */
+export declare const createWorld: () => Promise<World>;
+export type WorldHandlers = Pick<World, 'createQueueHandler' | 'specVersion'>;
+/**
+ * Some functions from the world are needed at build time, but we do NOT want
+ * to cache the world in those instances for general use, since we don't have
+ * the correct environment variables set yet. This is a safe function to
+ * call at build time, that only gives access to non-environment-bound world
+ * functions. The only binding value should be the target world.
+ * Once we migrate to a file-based configuration (workflow.config.ts), we should
+ * be able to re-combine getWorld and getWorldHandlers into one singleton.
+ */
+export declare const getWorldHandlers: () => Promise<WorldHandlers>;
+export declare const getWorld: () => Promise<World>;
+/**
+ * Reset the cached world instance. This should be called when environment
+ * variables change and you need to reinitialize the world with new config.
+ */
+export declare const setWorld: (world: World | undefined) => void;
+//# sourceMappingURL=world.d.ts.map

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

@@ -0,0 +1,22 @@
+import { type Event, type WorkflowRun } from '#compiled/@workflow/world/index.js';
+export type { Event, WorkflowRun };
+export { WorkflowSuspension } from './global.js';
+export { type HealthCheckEndpoint, type HealthCheckOptions, type HealthCheckResult, healthCheck, } from './runtime/helpers.js';
+export { getHookByToken, resumeHook, resumeWebhook, } from './runtime/resume-hook.js';
+export { getRun, Run, type WorkflowReadableStream, type WorkflowReadableStreamOptions, } from './runtime/run.js';
+export { cancelRun, listStreams, type ReadStreamOptions, type RecreateRunOptions, readStream, recreateRunFromExisting, reenqueueRun, type StopSleepOptions, type StopSleepResult, wakeUpRun, } from './runtime/runs.js';
+export { type StartOptions, type StartOptionsBase, type StartOptionsWithDeploymentId, type StartOptionsWithoutDeploymentId, start, } from './runtime/start.js';
+export { createWorld, getWorld, getWorldHandlers, setWorld, } from './runtime/world.js';
+/**
+ * Creates a single route which handles workflow execution requests,
+ * executing steps inline when possible to reduce function invocations
+ * and queue overhead.
+ *
+ * The handler loops: replay workflow → execute step inline → replay → ...
+ * until the workflow completes, times out, or encounters non-step suspensions.
+ *
+ * @param workflowCode - The workflow bundle code containing all workflow functions
+ * @returns A function that can be used as a Vercel API route
+ */
+export declare function workflowEntrypoint(workflowCode: string): (req: Request) => Promise<Response>;
+//# sourceMappingURL=runtime.d.ts.map