@lunora/workflow 1.0.0-alpha.5 → 1.0.0-alpha.50

package/dist/packem_shared/{types.d-C9W6rEWv.d.ts → types.d-C7jti0tm.d.ts}

@@ -1,21 +1,46 @@
 import { ValidatorMap, InferValidatorMap, Validator } from '@lunora/values';
 /**
-* Opaque reference to a Lunora function. Mirrors the `FunctionReference` shape
-* emitted by `@lunora/codegen` (and consumed by `@lunora/client`). We avoid a
-* direct dependency to keep this package usable from the codegen pipeline
-* itself — identical rationale to `@lunora/scheduler`'s copy.
-*
-* The runtime identifier lives in `__lunoraRef` — this MUST stay in lockstep
-* with the codegen emit + `@lunora/client`'s `FunctionReference`.
-*/
-interface FunctionReference {
+ * 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;
-  /** Marker phantom type — discriminates queries / mutations / actions. */
-  readonly _kind?: "query" | "mutation" | "action";
 }
-type ArgsOf<F extends FunctionReference> = F extends {
-  _args?: infer A;
-} ? A : Record<string, unknown>;
+/** 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`. */
@@ -53,17 +78,17 @@ interface WorkflowInstanceLike {
   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.
-*/
+ * 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&lt;T>`. */
+/** The `event` argument a workflow `run` receives. Mirrors `WorkflowEvent<T>`. */
 interface WorkflowEventLike<Params = Record<string, unknown>> {
   readonly instanceId: string;
   readonly payload: Readonly<Params>;
@@ -80,10 +105,10 @@ interface WorkflowStepConfigLike {
   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.
-*/
+ * 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;
@@ -114,19 +139,19 @@ interface WorkflowStepRollbackOptionsLike<T = unknown> {
   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&lt;T extends Rpc.Serializable&lt;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 `&lt;T>` and
-* cannot enforce that — a non-serializable result type-checks here but fails at
-* runtime on the platform. Keep step results JSON-serialisable.
-*/
+ * 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>;
@@ -155,25 +180,25 @@ interface RunFunctionOptions {
   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 }));
-* ```
-*/
+ * 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.
-*/
+ * 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;
@@ -226,10 +251,10 @@ interface StepConfig<A extends StepArgsValidator, Result> {
   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.
-*/
+ * 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;
@@ -252,35 +277,93 @@ interface StepDefinition<A extends StepArgsValidator = StepArgsValidator, Result
 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 });
-* ```
-*/
+ * 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>;
 /**
-* 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.
-*/
+ * 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).
-  */
+   * 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;
@@ -292,13 +375,13 @@ interface WorkflowBranch<Output = unknown> {
   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.
-*/
+ * 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&lt;string, unknown>` payload. */
+  /** 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;
@@ -313,20 +396,20 @@ interface BranchCompensationParams {
   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 };
+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 }),
-* ]);
-* ```
-*/
+ * 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 {
@@ -334,17 +417,17 @@ interface WorkflowSpawnOptions {
   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.
-*/
+ * 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.
-*/
+ * 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>;
@@ -364,6 +447,8 @@ interface WorkflowRunContext<Params = Record<string, unknown>> {
   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>;
@@ -372,19 +457,19 @@ 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`).
-  */
+   * 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.
-*/
+ * 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;
@@ -394,9 +479,10 @@ interface WorkflowDefinition<Params = Record<string, unknown>, Output = unknown>
   readonly isLunoraWorkflow: true;
 }
 /**
-* A typed handle to one declared workflow, addressable from `ctx.workflows`.
-* Thin pass-through over the Cloudflare `Workflow` binding.
-*/
+ * 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>;
@@ -404,11 +490,22 @@ interface WorkflowHandle<Params = Record<string, unknown>> {
   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.
-*/
+ * 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>;
@@ -416,10 +513,10 @@ interface Workflows {
 /** 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.
-  */
+   * 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, WorkflowSpawnFunction as C, WorkflowSpawnOptions as D, WorkflowStatusResult as E, FunctionReference as F, WorkflowStepConfigLike as G, WorkflowStepContextLike as H, InferStepArgs as I, WorkflowStepRollbackOptionsLike as J, LunoraWorkflowsOptions as L, RunFunctionOptions as R, StepArgsValidator as S, WorkflowDefinition as W, Workflows as a, StepConfig as b, StepDefinition as c, WorkflowConfig as d, WorkflowBranch as e, WorkflowInstanceStatus as f, WorkflowEventLike as g, WorkflowStepLike as h, WorkflowRunContext as i, WorkflowLogger as j, WorkflowRunFunction as k, WorkflowRunStepFunction as l, RunStepOptions as m, StepHandler as n, StepRollbackContext as o, StepRollbackHandler as p, StepRunContext as q, WorkflowBindingLike as r, WorkflowBranchOutputs as s, WorkflowCreateOptions as t, WorkflowHandle as u, WorkflowHandler as v, WorkflowInstanceLike as w, WorkflowParallelFunction as x, WorkflowRollbackContextLike as y, WorkflowRollbackHandlerLike as z };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/workflow",
-  "version": "1.0.0-alpha.5",
+  "version": "1.0.0-alpha.50",
   "description": "Durable workflows for Lunora: defineWorkflow over Cloudflare Workflows, generated WorkflowEntrypoint classes, and the ctx.workflows surface",
   "keywords": [
     "cloudflare",
@@ -48,7 +48,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/values": "1.0.0-alpha.3"
+    "@lunora/errors": "1.0.0-alpha.35",
+    "@lunora/values": "1.0.0-alpha.44"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"

package/dist/packem_shared/MAX_BRANCHES-D6cQabJ1.mjs

@@ -1,132 +0,0 @@
-import { NonRetryableError } from './NonRetryableError-Dn2dTyBS.mjs';
-
-const MAX_BRANCHES = 100;
-const BRANCH_MARKER_KEY = "__lunoraBranch";
-const SPAWN_STEP_PREFIX = "lunora:spawn:";
-const AWAIT_STEP_PREFIX = "lunora:await:";
-const SIGNAL_STEP_PREFIX = "lunora:signal:";
-const COMPENSATE_STEP_PREFIX = "lunora:compensate:";
-const BRANCH_EVENT_PREFIX = "lunora:branch:";
-const branch = (workflow, params, options) => {
-  return { compensateWith: options?.compensateWith, id: options?.id, params, timeout: options?.timeout, workflow };
-};
-const serializeError = (error) => {
-  if (error instanceof Error) {
-    return { message: error.message, name: error.name };
-  }
-  return { message: String(error), name: "Error" };
-};
-const okOutcome = (value) => {
-  return { status: "ok", value };
-};
-const errorOutcome = (error) => {
-  return { error: serializeError(error), status: "error" };
-};
-const compensateCompleted = async (deps, completed, error) => {
-  for (let cursor = completed.length - 1; cursor >= 0; cursor -= 1) {
-    const done = completed[cursor];
-    const compensateWith = done?.plan.item.compensateWith;
-    if (done === void 0 || compensateWith === void 0) {
-      continue;
-    }
-    await deps.step.do(`${COMPENSATE_STEP_PREFIX}${done.plan.childId}`, async () => {
-      const compensateId = `${done.plan.childId}:compensate`;
-      const compensationParams = {
-        branch: done.plan.item.workflow,
-        error,
-        index: done.plan.index,
-        output: done.output
-      };
-      await deps.resolveBinding(compensateWith).create({ id: compensateId, params: compensationParams });
-      return compensateId;
-    });
-  }
-};
-const createParallel = (deps) => {
-  const run = async (branches) => {
-    if (branches.length === 0) {
-      return [];
-    }
-    if (branches.length > MAX_BRANCHES) {
-      throw new NonRetryableError(
-        `ctx.parallel: ${String(branches.length)} branches exceeds the cap of ${String(MAX_BRANCHES)} — split the fan-out or raise the work into fewer child workflows`
-      );
-    }
-    const planned = branches.map((item, index) => {
-      const childId = deps.nextChildId(item.id);
-      return { childId, eventType: `${BRANCH_EVENT_PREFIX}${childId}`, index, item };
-    });
-    await Promise.all(
-      planned.map(
-        (plan) => deps.step.do(`${SPAWN_STEP_PREFIX}${plan.childId}`, async () => {
-          const binding = deps.resolveBinding(plan.item.workflow);
-          const marker = { eventType: plan.eventType, index: plan.index, parentBinding: deps.parentBinding, parentId: deps.instanceId };
-          await binding.create({ id: plan.childId, params: { ...plan.item.params, [BRANCH_MARKER_KEY]: marker } });
-          return plan.childId;
-        })
-      )
-    );
-    const results = [];
-    const completed = [];
-    for (const plan of planned) {
-      const event = await deps.step.waitForEvent(`${AWAIT_STEP_PREFIX}${plan.childId}`, {
-        timeout: plan.item.timeout,
-        type: plan.eventType
-      });
-      const outcome = event.payload;
-      if (outcome.status === "error") {
-        await compensateCompleted(deps, completed, outcome.error);
-        throw new NonRetryableError(`ctx.parallel: branch "${plan.item.workflow}" (#${String(plan.index)}) failed: ${outcome.error.message}`);
-      }
-      completed.push({ output: outcome.value, plan });
-      results.push(outcome.value);
-    }
-    return results;
-  };
-  return run;
-};
-const createSpawn = (deps) => async (workflow, params, options) => {
-  const childId = deps.nextChildId(options?.id);
-  await deps.step.do(`${SPAWN_STEP_PREFIX}${childId}`, async () => {
-    const binding = deps.resolveBinding(workflow);
-    await binding.create({ id: childId, params });
-    return childId;
-  });
-  return deps.resolveBinding(workflow).get(childId);
-};
-const extractBranchMarker = (payload) => {
-  if (typeof payload !== "object" || payload === null) {
-    return void 0;
-  }
-  const marker = payload[BRANCH_MARKER_KEY];
-  if (typeof marker !== "object" || marker === null) {
-    return void 0;
-  }
-  const candidate = marker;
-  if (typeof candidate.eventType !== "string" || typeof candidate.parentBinding !== "string" || typeof candidate.parentId !== "string" || typeof candidate.index !== "number") {
-    return void 0;
-  }
-  return { eventType: candidate.eventType, index: candidate.index, parentBinding: candidate.parentBinding, parentId: candidate.parentId };
-};
-const stripBranchMarker = (payload) => {
-  if (typeof payload !== "object" || payload === null) {
-    return payload;
-  }
-  const rest = { ...payload };
-  Reflect.deleteProperty(rest, BRANCH_MARKER_KEY);
-  return rest;
-};
-const signalBranchParent = async (deps, marker, outcome) => {
-  const binding = deps.env[marker.parentBinding];
-  if (!binding || typeof binding.get !== "function") {
-    return;
-  }
-  const getParent = binding.get.bind(binding);
-  await deps.step.do(`${SIGNAL_STEP_PREFIX}${String(marker.index)}`, async () => {
-    const parent = await getParent(marker.parentId);
-    await parent.sendEvent({ payload: outcome, type: marker.eventType });
-    return marker.eventType;
-  });
-};
-
-export { BRANCH_MARKER_KEY, MAX_BRANCHES, branch, createParallel, createSpawn, errorOutcome, extractBranchMarker, okOutcome, signalBranchParent, stripBranchMarker };