@lunora/workflow 1.0.0-alpha.4 → 1.0.0-alpha.41

package/dist/packem_shared/types.d-C7jti0tm.d.mts

@@ -0,0 +1,522 @@
+import { ValidatorMap, InferValidatorMap, Validator } from '@lunora/values';
+/**
+ * The generated function-reference type, shared by every package that needs to
+ * infer a call's args or return from `api.<file>.<fn>`.
+ *
+ * This lives in `shared/` rather than in one package because the consumers span
+ * a dependency boundary they must not cross: `@lunora/scheduler` and
+ * `@lunora/workflow` accept a reference in `runAfter`/`runAt`/`step.run*` but
+ * cannot depend on `@lunora/client`, which is a browser package. Each of them
+ * previously hand-copied this declaration, and both copies silently rotted when
+ * the phantom carrier was renamed — the conditional matched an OPTIONAL property
+ * that no longer existed, so `ArgsOf<F>` quietly resolved to `unknown` and every
+ * `step.run(ref, args)` in the repo lost its arg checking without a single error.
+ *
+ * `shared/` is the repo's answer to exactly that shape: bundler-inlined,
+ * zero-dependency source imported by relative path, so it creates no runtime
+ * edge between the packages that inline it. Being ONE declaration, there is
+ * nothing to keep in lockstep and no drift test to write.
+ */
+/** The registered function kinds a {@link FunctionReference} can describe. `stream` is a query that yields multiple frames over the WS. */
+type FunctionKind = "action" | "mutation" | "query" | "stream";
+/**
+ * Opaque reference to a registered function emitted by `@lunora/codegen`.
+ *
+ * At runtime it carries the `<file>:<function>` identifier in `__lunoraRef`.
+ * Generated declarations decorate this with phantom type parameters so callers
+ * can infer args / return values per call site.
+ */
+interface FunctionReference<Kind extends FunctionKind = FunctionKind, Args = unknown, Return = unknown> {
+  /**
+   * Phantom marker carrying the `Kind`/`Args`/`Return` type parameters for
+   * inference. Never present at runtime; declared as a covariant (output)
+   * position so a concrete reference stays assignable to a widened one.
+   */
+  readonly __lunoraPhantom?: {
+    args: Args;
+    kind: Kind;
+    returns: Return;
+  };
+  readonly __lunoraRef: string;
+}
+/** Extract the args type from a {@link FunctionReference}. */
+type ArgsOf<F> = F extends FunctionReference<infer _K, infer A, infer _R> ? A : never;
+/** A workflow instance's lifecycle status. Mirrors `WorkflowInstanceStatus`. */
+type WorkflowInstanceStatus = "complete" | "errored" | "paused" | "queued" | "running" | "terminated" | "unknown" | "waiting" | "waitingForPause";
+/** Result of `WorkflowInstance.status()`. Mirrors Cloudflare's `InstanceStatus`. */
+interface WorkflowStatusResult {
+  error?: {
+    message: string;
+    name: string;
+  };
+  output?: unknown;
+  status: WorkflowInstanceStatus;
+}
+/** Options accepted by `Workflow.create`. Mirrors `WorkflowInstanceCreateOptions`. */
+interface WorkflowCreateOptions<Params = Record<string, unknown>> {
+  /** Unique-within-the-workflow instance id. Generated by Cloudflare when omitted. */
+  id?: string;
+  /** The event payload the instance is triggered with — surfaced as `event.payload`. */
+  params?: Params;
+  /** Instance retention policy (defaults to the account maximum). */
+  retention?: {
+    errorRetention?: string;
+    successRetention?: string;
+  };
+}
+/** A live handle to a single workflow instance. Mirrors `WorkflowInstance`. */
+interface WorkflowInstanceLike {
+  readonly id: string;
+  pause: () => Promise<void>;
+  restart: () => Promise<void>;
+  resume: () => Promise<void>;
+  sendEvent: (event: {
+    payload: unknown;
+    type: string;
+  }) => Promise<void>;
+  status: () => Promise<WorkflowStatusResult>;
+  terminate: () => Promise<void>;
+}
+/**
+ * The subset of the Cloudflare `Workflow` binding the package consumes.
+ * `createBatch` is a non-optional method on the real binding (Cloudflare's
+ * `Workflow` class declares it unconditionally), so it is required here too —
+ * the handle never has to guard for its absence.
+ */
+interface WorkflowBindingLike<Params = Record<string, unknown>> {
+  create: (options?: WorkflowCreateOptions<Params>) => Promise<WorkflowInstanceLike>;
+  createBatch: (batch: ReadonlyArray<WorkflowCreateOptions<Params>>) => Promise<WorkflowInstanceLike[]>;
+  get: (id: string) => Promise<WorkflowInstanceLike>;
+}
+/** The `event` argument a workflow `run` receives. Mirrors `WorkflowEvent<T>`. */
+interface WorkflowEventLike<Params = Record<string, unknown>> {
+  readonly instanceId: string;
+  readonly payload: Readonly<Params>;
+  readonly timestamp: Date;
+  readonly workflowName: string;
+}
+/** Per-step durability config. Mirrors the `WorkflowStepConfig.retries` shape. */
+interface WorkflowStepConfigLike {
+  retries?: {
+    backoff?: "constant" | "exponential" | "linear";
+    delay?: number | string;
+    limit: number;
+  };
+  timeout?: number | string;
+}
+/**
+ * The per-attempt info Cloudflare passes a `step.do` callback. Mirrors
+ * `WorkflowStepContext` — `attempt` is the 1-based retry counter (`> 1` on
+ * retries) and `step` carries the durable step's name + invocation count.
+ */
+interface WorkflowStepContextLike {
+  /** 1-based attempt counter — `> 1` means this is a retry. */
+  attempt: number;
+  /** The resolved per-step config for this invocation. */
+  config: WorkflowStepConfigLike;
+  /** The durable step's identity. */
+  step: {
+    count: number;
+    name: string;
+  };
+}
+/** The context a rollback handler receives. Mirrors `WorkflowRollbackContext` (`{ ctx, error, output, stepName }`). */
+interface WorkflowRollbackContextLike<T = unknown> {
+  /** The per-attempt step context (`attempt` / `config` / `step`) for the rolled-back step. */
+  ctx: WorkflowStepContextLike;
+  /** The error that triggered the rollback. */
+  error: Error;
+  /** The step's output if it completed before a later step failed, else `undefined`. */
+  output: T | undefined;
+  /** The durable step's name. */
+  stepName: string;
+}
+/** A native step rollback handler. Mirrors `WorkflowRollbackHandler`. */
+type WorkflowRollbackHandlerLike<T = unknown> = (context: WorkflowRollbackContextLike<T>) => Promise<void>;
+/** Native rollback options accepted by `step.do`. Mirrors the Cloudflare rollback-options shape. */
+interface WorkflowStepRollbackOptionsLike<T = unknown> {
+  rollback?: WorkflowRollbackHandlerLike<T>;
+  rollbackConfig?: WorkflowStepConfigLike;
+}
+/**
+ * The durable step API Cloudflare hands the workflow body. Mirrors
+ * `WorkflowStep` — `do` memoizes + retries its callback, `sleep`/`sleepUntil`
+ * are durable delays, and `waitForEvent` hibernates until an external event.
+ * `do`'s two overloads mirror Cloudflare's: an optional leading `config` and an
+ * optional trailing `rollback` (compensation run when a later step fails).
+ *
+ * Known mirror gap: Cloudflare constrains `do<T extends Rpc.Serializable<T>>` so
+ * a non-serializable step result (a function, `Map`, class instance, …) is a
+ * compile error there. `Rpc.Serializable` lives in `@cloudflare/workers-types`
+ * and is not Node-importable, so this Node-safe mirror uses a bare `<T>` and
+ * cannot enforce that — a non-serializable result type-checks here but fails at
+ * runtime on the platform. Keep step results JSON-serialisable.
+ */
+interface WorkflowStepLike {
+  do: {
+    <T>(name: string, callback: (context: WorkflowStepContextLike) => Promise<T>, rollback?: WorkflowStepRollbackOptionsLike<T>): Promise<T>;
+    <T>(name: string, config: WorkflowStepConfigLike, callback: (context: WorkflowStepContextLike) => Promise<T>, rollback?: WorkflowStepRollbackOptionsLike<T>): Promise<T>;
+  };
+  sleep: (name: string, duration: number | string) => Promise<void>;
+  sleepUntil: (name: string, timestamp: Date | number) => Promise<void>;
+  waitForEvent: <T = unknown>(name: string, options: {
+    timeout?: number | string;
+    type: string;
+  }) => Promise<{
+    payload: Readonly<T>;
+    type: string;
+  }>;
+}
+/** Minimal structured logger handed to the workflow body. */
+interface WorkflowLogger {
+  debug: (message: string, ...rest: unknown[]) => void;
+  error: (message: string, ...rest: unknown[]) => void;
+  info: (message: string, ...rest: unknown[]) => void;
+  warn: (message: string, ...rest: unknown[]) => void;
+}
+/** Per-call options for {@link WorkflowRunFunction}. */
+interface RunFunctionOptions {
+  /** Routing hint forwarded to the Worker so the call lands on the right shard. */
+  shardKey?: string;
+}
+/**
+ * Calls a Lunora query / mutation / action from inside a workflow and resolves
+ * with its result. Wrap it in {@link WorkflowStepLike.do} to make the call a
+ * durable, memoized, retried step:
+ *
+ * ```ts
+ * const charge = await ctx.step.do("charge", () => ctx.run(api.payments.charge, { id }));
+ * ```
+ */
+type WorkflowRunFunction = <F extends FunctionReference>(function_: F, args?: ArgsOf<F>, options?: RunFunctionOptions) => Promise<unknown>;
+/** Map of validators describing a step's args record — the same shape a Lunora function's `args` uses. Alias of `@lunora/values`' shared {@link ValidatorMap}. */
+type StepArgsValidator = ValidatorMap;
+/** Infer the args object type from a {@link StepArgsValidator} (optional validators → optional keys). Alias of `@lunora/values`' shared {@link InferValidatorMap}. */
+type InferStepArgs<A extends StepArgsValidator> = InferValidatorMap<A>;
+/**
+ * The context a {@link StepDefinition} handler receives as its first argument
+ * (the validated args are the second). Bundles the native per-attempt info
+ * (`attempt`, `config`, `step`) with the Worker `env`, the Lunora runner, and a
+ * logger.
+ */
+interface StepRunContext {
+  /** 1-based retry counter — `> 1` means Cloudflare is retrying the step. */
+  readonly attempt: number;
+  /** The resolved durability config for this invocation. */
+  readonly config: WorkflowStepConfigLike;
+  /** The Worker environment bindings. */
+  readonly env: Record<string, unknown>;
+  /** Structured logger surfaced in `wrangler tail` / Studio logs. */
+  readonly log: WorkflowLogger;
+  /** Invoke a Lunora query / mutation / action. */
+  readonly run: WorkflowRunFunction;
+  /** The durable step's identity (name + invocation count). */
+  readonly step: {
+    count: number;
+    name: string;
+  };
+}
+/** The work a step performs. Receives the {@link StepRunContext} and the validated args. */
+type StepHandler<A extends StepArgsValidator, Result> = (context: StepRunContext, args: InferStepArgs<A>) => Promise<Result> | Result;
+/** The context a step rollback handler receives — the Lunora-flavored mirror of `WorkflowRollbackContext`. */
+interface StepRollbackContext<A extends StepArgsValidator, Result> {
+  /** The validated args the step ran with. */
+  readonly args: InferStepArgs<A>;
+  /** The Worker environment bindings. */
+  readonly env: Record<string, unknown>;
+  /** The error that triggered the rollback. */
+  readonly error: Error;
+  /** Structured logger. */
+  readonly log: WorkflowLogger;
+  /** The step's output if it completed before a later step failed, else `undefined`. */
+  readonly output: Result | undefined;
+  /** Invoke a Lunora function — e.g. to undo a write the step made. */
+  readonly run: WorkflowRunFunction;
+}
+/** A step compensation handler — runs when a later step fails after this one completed. */
+type StepRollbackHandler<A extends StepArgsValidator, Result> = (context: StepRollbackContext<A, Result>) => Promise<void> | void;
+/** Author-supplied config for {@link StepDefinition}, passed to `defineStep`. */
+interface StepConfig<A extends StepArgsValidator, Result> {
+  /** Validators for the step's args — the same map shape a Lunora function uses. */
+  args: A;
+  /** Optional durability config (retries / timeout) applied to the step. */
+  config?: WorkflowStepConfigLike;
+  /** The work the step performs. */
+  handler: StepHandler<A, Result>;
+  /** Optional validator for the return value — validated before the result leaves the step. */
+  returns?: Validator<Result>;
+  /** Optional compensation run when a later step fails after this one completed. */
+  rollback?: StepRollbackHandler<A, Result>;
+  /** Optional durability config for the rollback step itself. */
+  rollbackConfig?: WorkflowStepConfigLike;
+}
+/**
+ * A `defineStep` result — a reusable, schema-validated durable step. Run it from
+ * a workflow body with `ctx.runStep(step, args)`. The phantom generics carry the
+ * inferred args + result types to the call site.
+ */
+interface StepDefinition<A extends StepArgsValidator = StepArgsValidator, Result = unknown> {
+  /** Validators for the step's args. */
+  readonly args: A;
+  /** Optional per-step durability config. */
+  readonly config?: WorkflowStepConfigLike;
+  /** The step body. */
+  readonly handler: StepHandler<A, Result>;
+  /** Runtime brand check (see `isStepDefinition`). */
+  readonly isLunoraStep: true;
+  /** The durable step's name — also the `step.do(...)` label. */
+  readonly name: string;
+  /** Optional result validator. */
+  readonly returns?: Validator<Result>;
+  /** Optional compensation handler. */
+  readonly rollback?: StepRollbackHandler<A, Result>;
+  /** Optional rollback durability config. */
+  readonly rollbackConfig?: WorkflowStepConfigLike;
+}
+/** Per-call options for {@link WorkflowRunStepFunction}. */
+interface RunStepOptions {
+  /** Override the step's declared durability config for this call. */
+  config?: WorkflowStepConfigLike;
+  /**
+   * Override the durable step name for this call. Cloudflare keys a durable
+   * step by name **and occurrence** (`step.count` counts the calls made under
+   * one name in a run), so reusing a name in a loop is fine and each
+   * occurrence caches independently — this is for giving a call its own
+   * addressable name, e.g. to target it with `instance.restart({ from })`.
+   * Must be deterministic across replays, like any step name.
+   */
+  name?: string;
+}
+/**
+ * Run a reusable {@link StepDefinition} as a durable, memoized, retried step:
+ * validates the args before the body runs and the result after (when the step
+ * declares `returns`), and forwards any rollback handler to Cloudflare.
+ *
+ * ```ts
+ * const data = await ctx.runStep(fetchImage, { imageKey });
+ * ```
+ */
+type WorkflowRunStepFunction = <A extends StepArgsValidator, Result>(step: StepDefinition<A, Result>, args: InferStepArgs<A>, options?: RunStepOptions) => Promise<Result>;
+/**
+ * A `defineWorkflowEvent` result — the single source of truth for one external
+ * event's wire `type` and payload shape. Both ends of the exchange import the same
+ * definition (`ctx.waitForEvent(orderApproved)` inside the workflow,
+ * `workflows.get(w).sendEvent(id, orderApproved, payload)` from the caller), so
+ * there is no string to typo and no second place to update on a rename, and the
+ * payload is parsed at both ends instead of crossing as `unknown`.
+ *
+ * It does NOT make every mismatch a compile error: two definitions with the same
+ * payload shape are mutually assignable, so sending `orderRejected` where the
+ * workflow awaits `orderApproved` still type-checks (and still hibernates until
+ * the timeout). What it removes is the hand-matched literal.
+ */
+interface WorkflowEventDefinition<Payload = unknown> {
+  /** Runtime brand check (see `isWorkflowEventDefinition`). */
+  readonly isLunoraWorkflowEvent: true;
+  /** Validator for the event payload — parsed on send and again on receive. */
+  readonly payload: Validator<Payload>;
+  /** The wire event type Cloudflare matches `sendEvent` against `waitForEvent`. */
+  readonly type: string;
+}
+/** Per-call options for {@link WorkflowWaitForEventFunction}. */
+interface WaitForEventOptions {
+  /**
+   * The durable step label, defaulting to `event:<type>`.
+   *
+   * Cloudflare identifies a memoized step by this name, so the default couples
+   * step identity to the wire type: renaming the event type also renames the
+   * step, and an instance that already recorded the wait replays into a *fresh*
+   * one that nothing will ever satisfy. Pass a stable `name` on any wait that can
+   * outlive a deploy (an approval held for days), and to tell two waits on the
+   * same event type apart in the timeline.
+   */
+  name?: string;
+  /** How long to wait before the wait rejects. Defaults to Cloudflare's 24h. */
+  timeout?: number | string;
+}
+/**
+ * Hibernate until a declared event is delivered to this instance, then resolve
+ * with its validated payload. The typed wrapper over
+ * {@link WorkflowStepLike.waitForEvent}: the event's `type` comes from the
+ * definition instead of a hand-written string, and the payload is parsed through
+ * the definition's validator before the workflow resumes on it.
+ *
+ * ```ts
+ * const { approvedBy } = await ctx.waitForEvent(orderApproved, { timeout: "1 hour" });
+ * ```
+ */
+type WorkflowWaitForEventFunction = <Payload>(event: WorkflowEventDefinition<Payload>, options?: WaitForEventOptions) => Promise<Payload>;
+/**
+ * One branch of a {@link WorkflowParallelFunction} fan-out — a declared child
+ * workflow (referenced by its `lunora/workflows.ts` export name) plus the params
+ * it is created with. The phantom `Output` carries the child's result type into
+ * the `ctx.parallel(...)` result tuple. Build one with the `branch(...)` helper.
+ */
+interface WorkflowBranch<Output = unknown> {
+  /** Phantom marker for the branch output type — never present at runtime. */
+  readonly __output?: Output;
+  /**
+   * Optional group-saga compensation (plan 075 Phase 3): the `lunora/workflows.ts`
+   * export name of a workflow to run if a **sibling** branch in the same
+   * `ctx.parallel(...)` group fails **after** this branch has already completed.
+   * It is spawned fire-and-forget (a durable, replay-safe idempotent create) with
+   * {@link BranchCompensationParams} as its `ctx.params`. Omit for no
+   * compensation — a group where no branch sets this behaves exactly as a plain
+   * fan-out (fail-fast, no rollback).
+   */
+  readonly compensateWith?: string;
+  /** Optional explicit child instance id (defaults to a deterministic parent-derived id). */
+  readonly id?: string;
+  /** The params the child instance is created with — surfaced as the child's `ctx.params`. */
+  readonly params?: Record<string, unknown>;
+  /** Optional wait timeout for this branch (the parent's `waitForEvent` timeout). */
+  readonly timeout?: number | string;
+  /** The `lunora/workflows.ts` export name of the child workflow to run. */
+  readonly workflow: string;
+}
+/**
+ * The `ctx.params` a group-saga compensation workflow (a branch's
+ * {@link WorkflowBranch.compensateWith}) receives when a sibling's failure rolls
+ * back the group. Everything is plain-serialisable — the compensation is an
+ * ordinary declared workflow, so it can `ctx.runStep(...)` its own undo logic.
+ */
+interface BranchCompensationParams {
+  /** Index signature: this is a workflow `params` bag, so it is a valid `Record<string, unknown>` payload. */
+  [key: string]: unknown;
+  /** The export name of the completed branch being compensated. */
+  branch: string;
+  /** The serialised error of the sibling branch whose failure triggered the group rollback. */
+  error: {
+    message: string;
+    name: string;
+  };
+  /** Declaration-order index of the completed branch being compensated. */
+  index: number;
+  /** The completed branch's output value — what it returned before the group failed. */
+  output?: unknown;
+}
+/** Map a tuple of {@link WorkflowBranch}es to the tuple of their output types, preserving order. */
+type WorkflowBranchOutputs<B extends ReadonlyArray<WorkflowBranch>> = { -readonly [K in keyof B]: B[K] extends WorkflowBranch<infer Output> ? Output : never; };
+/**
+ * Run branches as isolated child workflow instances and resolve with their
+ * outputs in declaration order. Each branch gets its own Durable Object (own
+ * memory / CPU / retry budget); the parent hibernates while they execute. Rejects
+ * (non-retryable) on the first branch that fails.
+ *
+ * ```ts
+ * const [tags, thumb] = await ctx.parallel([
+ *     branch("imageTag", { key }),
+ *     branch("thumbnail", { key }),
+ * ]);
+ * ```
+ */
+type WorkflowParallelFunction = <const B extends ReadonlyArray<WorkflowBranch>>(branches: B) => Promise<WorkflowBranchOutputs<B>>;
+/** Per-call options for {@link WorkflowSpawnFunction}. */
+interface WorkflowSpawnOptions {
+  /** Explicit child instance id (defaults to a deterministic parent-derived id). */
+  id?: string;
+}
+/**
+ * Fire-and-forget start of a declared child workflow from inside a workflow body
+ * — replay-safe (idempotent create), returns a live handle to the child. Use
+ * {@link WorkflowParallelFunction} instead when you need to await results.
+ */
+type WorkflowSpawnFunction = (workflow: string, params?: Record<string, unknown>, options?: WorkflowSpawnOptions) => Promise<WorkflowInstanceLike>;
+/**
+ * The context object passed to a `defineWorkflow` handler. Bundles the native
+ * Cloudflare durability primitives (`step`, `event`) with the Lunora runner
+ * (`run`), the reusable-step runner (`runStep`), the fan-out primitives
+ * (`parallel` / `spawn`), the Worker `env`, and a logger.
+ */
+interface WorkflowRunContext<Params = Record<string, unknown>> {
+  /** The Worker environment bindings. */
+  readonly env: Record<string, unknown>;
+  /** The triggering event (id, payload, timestamp, workflow name). */
+  readonly event: WorkflowEventLike<Params>;
+  /** Structured logger surfaced in `wrangler tail` / Studio logs. */
+  readonly log: WorkflowLogger;
+  /** Run branches as isolated child workflow instances and await their outputs (declaration-ordered tuple). */
+  readonly parallel: WorkflowParallelFunction;
+  /** Convenience alias for `event.payload`. */
+  readonly params: Readonly<Params>;
+  /** Invoke a Lunora function; wrap in `step.do(...)` for durability. */
+  readonly run: WorkflowRunFunction;
+  /** Run a reusable, schema-validated {@link StepDefinition} as a durable step. */
+  readonly runStep: WorkflowRunStepFunction;
+  /** Fire-and-forget start of a declared child workflow (replay-safe; returns a live handle). */
+  readonly spawn: WorkflowSpawnFunction;
+  /** The native Cloudflare Workflows durable-step API. */
+  readonly step: WorkflowStepLike;
+  /** Hibernate until a declared external event arrives; resolves with its validated payload. */
+  readonly waitForEvent: WorkflowWaitForEventFunction;
+}
+/** The workflow body. Receives a {@link WorkflowRunContext}, returns the output. */
+type WorkflowHandler<Params = Record<string, unknown>, Output = unknown> = (context: WorkflowRunContext<Params>) => Output | Promise<Output>;
+/** Author-supplied config for `defineWorkflow`. */
+interface WorkflowConfig<Params = Record<string, unknown>, Output = unknown> {
+  /** The workflow body — the multi-step durable program. */
+  handler: WorkflowHandler<Params, Output>;
+  /**
+   * Optional override for the deployed workflow name — the `workflows[].name`
+   * written to `wrangler.jsonc`. Defaults to a kebab-cased form of the
+   * `lunora/workflows.ts` export name (`orderPipeline` → `order-pipeline`).
+   * This does NOT change the binding name, which is always derived from the
+   * export name (`orderPipeline` → `WORKFLOW_ORDER_PIPELINE`).
+   */
+  name?: string;
+}
+/**
+ * A `defineWorkflow` result — the config plus the runtime brand codegen and the
+ * config layer use to discover it. The phantom `__params` / `__output` carry
+ * the inferred types to the generated `ctx.workflows` handle.
+ */
+interface WorkflowDefinition<Params = Record<string, unknown>, Output = unknown> extends WorkflowConfig<Params, Output> {
+  /** Phantom marker for the output type — never present at runtime. */
+  readonly __output?: Output;
+  /** Phantom marker for the params type — never present at runtime. */
+  readonly __params?: Params;
+  /** Runtime brand check (see `isWorkflowDefinition`). */
+  readonly isLunoraWorkflow: true;
+}
+/**
+ * A typed handle to one declared workflow, addressable from `ctx.workflows`.
+ * Thin pass-through over the Cloudflare `Workflow` binding, plus the declared-event
+ * send (which the raw binding cannot type).
+ */
+interface WorkflowHandle<Params = Record<string, unknown>> {
+  /** Start a new instance (optionally with an id + params). */
+  create: (options?: WorkflowCreateOptions<Params>) => Promise<WorkflowInstanceLike>;
+  /** Start many instances in one batched RPC. */
+  createBatch: (batch: ReadonlyArray<WorkflowCreateOptions<Params>>) => Promise<WorkflowInstanceLike[]>;
+  /** Get a handle to an existing instance by id. */
+  get: (id: string) => Promise<WorkflowInstanceLike>;
+  /**
+   * Deliver a declared event to one instance of this workflow — the typed
+   * counterpart of the workflow body's `ctx.waitForEvent`. The wire type comes
+   * from the definition (never a hand-written string) and the payload is parsed
+   * through the definition's validator **before** the send, so a bad value fails
+   * the caller's request instead of waking the workflow on garbage.
+   *
+   * Mirrors `ctx.agents.<name>.sendEvent(id, …)`: the instance is addressed by
+   * id rather than by holding an instance handle, so the common case is one call.
+   */
+  sendEvent: <Payload>(instanceId: string, event: WorkflowEventDefinition<Payload>, payload: Payload) => Promise<void>;
+}
+/**
+ * The `ctx.workflows` surface available on `MutationCtx` and `ActionCtx`. Each
+ * declared workflow is reachable by its `lunora/workflows.ts` export name.
+ */
+interface Workflows {
+  /** Resolve the handle for a declared workflow by export name. */
+  get: <Params = Record<string, unknown>>(name: string) => WorkflowHandle<Params>;
+}
+/** Options for `createWorkflows`. */
+interface LunoraWorkflowsOptions {
+  /**
+   * Map of `lunora/workflows.ts` export name → its Cloudflare `Workflow`
+   * binding. Codegen builds this from `env` (`{ orderPipeline:
+   * env.WORKFLOW_ORDER_PIPELINE }`); for manual wiring construct it yourself.
+   */
+  bindings: Record<string, WorkflowBindingLike>;
+}
+export { ArgsOf as A, BranchCompensationParams as B, WorkflowInstanceLike as C, WorkflowParallelFunction as D, WorkflowRollbackContextLike as E, FunctionKind as F, WorkflowRollbackHandlerLike as G, WorkflowSpawnFunction as H, InferStepArgs as I, WorkflowSpawnOptions as J, WorkflowStatusResult as K, LunoraWorkflowsOptions as L, WorkflowStepConfigLike as M, WorkflowStepContextLike as N, WorkflowStepRollbackOptionsLike as O, RunFunctionOptions as R, StepArgsValidator as S, WorkflowDefinition as W, Workflows as a, WorkflowEventDefinition as b, StepConfig as c, StepDefinition as d, WorkflowConfig as e, WorkflowBranch as f, WorkflowInstanceStatus as g, WorkflowEventLike as h, WorkflowStepLike as i, WorkflowRunContext as j, WorkflowLogger as k, WorkflowRunFunction as l, WorkflowRunStepFunction as m, WorkflowWaitForEventFunction as n, FunctionReference as o, RunStepOptions as p, StepHandler as q, StepRollbackContext as r, StepRollbackHandler as s, StepRunContext as t, WaitForEventOptions as u, WorkflowBindingLike as v, WorkflowBranchOutputs as w, WorkflowCreateOptions as x, WorkflowHandle as y, WorkflowHandler as z };