@lunora/workflow 1.0.0-alpha.29 → 1.0.0-alpha.30

package/README.md

@@ -85,10 +85,33 @@ The handler context bundles:
 - `ctx.step` — the native Cloudflare durable-step API (`do` / `sleep` / `sleepUntil` / `waitForEvent`).
 - `ctx.run(ref, args, opts?)` — call a Lunora query / mutation / action; wrap in `ctx.step.do(...)` for durability.
 - `ctx.runStep(step, args, opts?)` — run a reusable, schema-validated `defineStep` as a durable step (see below).
+- `ctx.waitForEvent(event, opts?)` — hibernate until a declared `defineWorkflowEvent` arrives; resolves with its validated payload (see below).
 - `ctx.event` / `ctx.params` — the triggering event and its payload.
 - `ctx.env` — the Worker bindings.
 - `ctx.log` — a workflow-prefixed logger surfaced in `wrangler tail` / Studio.
 
+### Declared events (`defineWorkflowEvent`)
+
+`step.waitForEvent(name, { type })` and `instance.sendEvent({ type })` match on a bare string, and the payload crosses as `unknown` — so a typo hibernates the instance until its timeout with no error anywhere, and a changed payload shape resumes the workflow on garbage. Declare the event once and both ends import the same value:
+
+```ts
+// lunora/events.ts
+import { defineWorkflowEvent } from "@lunora/workflow";
+import { v } from "@lunora/values";
+
+export const orderApproved = defineWorkflowEvent("order-approved", v.object({ approvedBy: v.string() }));
+```
+
+```ts
+// inside the workflow body — typed and parsed
+const { approvedBy } = await ctx.waitForEvent(orderApproved, { name: "await approval", timeout: "7 days" });
+
+// from a mutation/action — validated before the send
+await ctx.workflows.get("orderPipeline").sendEvent(instanceId, orderApproved, { approvedBy });
+```
+
+Pass a stable `{ name }` on any wait that can outlive a deploy: the step is otherwise labelled `event:<type>`, so renaming the event type also renames the durable step and an instance that already recorded the wait replays into a fresh one nothing will satisfy.
+
 ### Reusable steps (`defineStep`)
 
 A step authored inline with `ctx.step.do("name", () => …)` is fine for one-offs, but `defineStep` lets you define a step **once** — schema-validated and reusable across workflows. Args are validated (with `@lunora/values`) **before** the body runs, and the return value is validated **after** (when you declare `returns`), so a bad payload fails fast instead of corrupting later steps. Scaffold one with `vis generate lunora-step --name=chargeOrder` (appends to `lunora/steps.ts`), or write it by hand:
@@ -169,7 +192,7 @@ export const checkout = mutation.input({ orderId: v.string() }).mutation(async (
 });
 ```
 
-A handle exposes `create({ id?, params?, retention? })`, `createBatch([...])`, and `get(id)`. An instance handle exposes its lifecycle: `status()`, `pause()`, `resume()`, `terminate()`, and `sendEvent({ type, payload })` (to satisfy a `waitForEvent`).
+A handle exposes `create({ id?, params?, retention? })`, `createBatch([...])`, `get(id)`, and `sendEvent(instanceId, event, payload)` — the typed delivery of a declared event (see above). `create`/`get` return the native Cloudflare instance, which exposes its own lifecycle: `status()`, `pause()`, `resume()`, `restart()`, `terminate()`, and the untyped `sendEvent({ type, payload })`.
 
 ### Runtime requirements
 

package/dist/do/index.d.mts

@@ -1,5 +1,5 @@
 import { WorkflowEntrypoint, WorkflowEvent, WorkflowStep } from 'cloudflare:workers';
-import { W as WorkflowDefinition } from "../packem_shared/types.d-CZ1pcdmw.mjs";
+import { W as WorkflowDefinition } from "../packem_shared/types.d-BmtJnXue.mjs";
 import '@lunora/values';
 /**
  * Base class for the generated `WorkflowEntrypoint` classes. Applies a

package/dist/do/index.d.ts

@@ -1,5 +1,5 @@
 import { WorkflowEntrypoint, WorkflowEvent, WorkflowStep } from 'cloudflare:workers';
-import { W as WorkflowDefinition } from "../packem_shared/types.d-CZ1pcdmw.js";
+import { W as WorkflowDefinition } from "../packem_shared/types.d-BmtJnXue.js";
 import '@lunora/values';
 /**
  * Base class for the generated `WorkflowEntrypoint` classes. Applies a

package/dist/do/index.mjs

@@ -1 +1 @@
-import{WorkflowEntrypoint as p}from"cloudflare:workers";import{NonRetryableError as i}from"cloudflare:workflows";import{convertNonRetryableError as m}from"../packem_shared/NonRetryableError-9ZqDUzwT.mjs";import{extractBranchMarker as f,stripBranchMarker as h,signalBranchParentSafe as l,errorOutcome as u,okOutcome as y}from"../packem_shared/MAX_BRANCHES-ZS8UAw_t.mjs";import{createWorkflowRunContext as d}from"../packem_shared/createWorkflowRunContext-D1vdFtWC.mjs";class N extends p{#r;#t;constructor(t,e,o,r){super(t,e),this.#t=o,this.#r=r??"workflow"}async run(t,e){const o=e,r=f(t.payload),c=r?{...t,payload:h(t.payload)}:t,a=d({env:this.env,event:c,exportName:this.#r,nonRetryableErrorClass:i,step:o});let n;try{n=await this.#t.handler(a)}catch(s){return r&&await l({env:this.env,log:a.log,step:o},r,u(s)),m(s,i)}return r&&await l({env:this.env,log:a.log,step:o},r,y(n)),n}}export{N as default};
+import{WorkflowEntrypoint as p}from"cloudflare:workers";import{NonRetryableError as i}from"cloudflare:workflows";import{convertNonRetryableError as m}from"../packem_shared/NonRetryableError-9ZqDUzwT.mjs";import{extractBranchMarker as f,stripBranchMarker as h,signalBranchParentSafe as l,errorOutcome as u,okOutcome as y}from"../packem_shared/MAX_BRANCHES-C05O5LY9.mjs";import{createWorkflowRunContext as d}from"../packem_shared/createWorkflowRunContext-CNvJHMci.mjs";class N extends p{#r;#t;constructor(t,e,o,r){super(t,e),this.#t=o,this.#r=r??"workflow"}async run(t,e){const o=e,r=f(t.payload),c=r?{...t,payload:h(t.payload)}:t,a=d({env:this.env,event:c,exportName:this.#r,nonRetryableErrorClass:i,step:o});let n;try{n=await this.#t.handler(a)}catch(s){return r&&await l({env:this.env,log:a.log,step:o},r,u(s)),m(s,i)}return r&&await l({env:this.env,log:a.log,step:o},r,y(n)),n}}export{N as default};

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { a as Workflows, L as LunoraWorkflowsOptions, S as StepArgsValidator, b as StepConfig, c as StepDefinition, d as WorkflowConfig, W as WorkflowDefinition, e as WorkflowBranch, f as WorkflowInstanceStatus, g as WorkflowEventLike, h as WorkflowStepLike, i as WorkflowRunContext, j as WorkflowLogger, k as WorkflowRunFunction, l as WorkflowRunStepFunction } from "./packem_shared/types.d-CZ1pcdmw.mjs";
-export type { A as ArgsOf, B as BranchCompensationParams, F as FunctionReference, I as InferStepArgs, R as RunFunctionOptions, m as RunStepOptions, n as StepHandler, o as StepRollbackContext, p as StepRollbackHandler, q as StepRunContext, r as WorkflowBindingLike, s as WorkflowBranchOutputs, t as WorkflowCreateOptions, u as WorkflowHandle, v as WorkflowHandler, w as WorkflowInstanceLike, x as WorkflowParallelFunction, y as WorkflowRollbackContextLike, z as WorkflowRollbackHandlerLike, C as WorkflowSpawnFunction, D as WorkflowSpawnOptions, E as WorkflowStatusResult, G as WorkflowStepConfigLike, H as WorkflowStepContextLike, J as WorkflowStepRollbackOptionsLike } from "./packem_shared/types.d-CZ1pcdmw.mjs";
+import { a as Workflows, L as LunoraWorkflowsOptions, b as WorkflowEventDefinition, S as StepArgsValidator, c as StepConfig, d as StepDefinition, e as WorkflowConfig, W as WorkflowDefinition, f as WorkflowBranch, g as WorkflowInstanceStatus, h as WorkflowEventLike, i as WorkflowStepLike, j as WorkflowRunContext, k as WorkflowLogger, l as WorkflowRunFunction, m as WorkflowRunStepFunction, n as WorkflowWaitForEventFunction } from "./packem_shared/types.d-BmtJnXue.mjs";
+export type { A as ArgsOf, B as BranchCompensationParams, F as FunctionReference, I as InferStepArgs, R as RunFunctionOptions, o as RunStepOptions, p as StepHandler, q as StepRollbackContext, r as StepRollbackHandler, s as StepRunContext, t as WaitForEventOptions, u as WorkflowBindingLike, v as WorkflowBranchOutputs, w as WorkflowCreateOptions, x as WorkflowHandle, y as WorkflowHandler, z as WorkflowInstanceLike, C as WorkflowParallelFunction, D as WorkflowRollbackContextLike, E as WorkflowRollbackHandlerLike, G as WorkflowSpawnFunction, H as WorkflowSpawnOptions, J as WorkflowStatusResult, K as WorkflowStepConfigLike, M as WorkflowStepContextLike, N as WorkflowStepRollbackOptionsLike } from "./packem_shared/types.d-BmtJnXue.mjs";
+import { Validator } from '@lunora/values';
 import { LunoraError } from '@lunora/errors';
-import '@lunora/values';
 /** Wiring info for one declared workflow, emitted by codegen into the generated shard. */
 interface WorkflowBindingSpec {
   /** The Cloudflare `Workflow` binding name, e.g. `WORKFLOW_ORDER_PIPELINE`. */
@@ -23,6 +23,36 @@ declare const createWorkflowContext: (env: Record<string, unknown>, specs: Reado
  * an unknown name throws with the list of declared workflows.
  */
 declare const createWorkflows: (options: LunoraWorkflowsOptions) => Workflows;
+/**
+ * Declare an external event, its wire type, and its payload shape.
+ *
+ * ```ts
+ * // lunora/events.ts
+ * import { defineWorkflowEvent } from "@lunora/workflow";
+ * import { v } from "@lunora/values";
+ *
+ * export const orderApproved = defineWorkflowEvent("order-approved", v.object({ approvedBy: v.string() }));
+ * ```
+ *
+ * Wait on it inside a workflow body — the payload is typed and validated:
+ *
+ * ```ts
+ * const { approvedBy } = await ctx.waitForEvent(orderApproved, { name: "await approval", timeout: "7 days" });
+ * ```
+ *
+ * …and send it from a mutation/action with the same definition:
+ *
+ * ```ts
+ * await ctx.workflows.get("orderPipeline").sendEvent(instanceId, orderApproved, { approvedBy });
+ * ```
+ */
+declare const defineWorkflowEvent: <Payload>(type: string, payload: Validator<Payload>) => WorkflowEventDefinition<Payload>;
+/**
+ * True when a value is usable as an event definition. The brand alone is not the
+ * test: the predicate hands the caller a `type` and a `payload.parse`, so it checks
+ * for both (and for the reserved namespace) rather than trusting a public boolean.
+ */
+declare const isWorkflowEventDefinition: (value: unknown) => value is WorkflowEventDefinition;
 /**
  * Declare a reusable durable step. Same `args` map shape a Lunora `query` /
  * `mutation` / `action` uses, so a step reads like a function:
@@ -261,4 +291,23 @@ interface RunStepDeps {
  * converted to the native one and any declared rollback forwarded to Cloudflare.
  */
 declare const createRunStep: (deps: RunStepDeps) => WorkflowRunStepFunction;
-export { type LunoraWorkflowsOptions, MAX_BRANCHES, type NativeNonRetryableErrorConstructor, NonRetryableError, type StepArgsValidator, type StepConfig, type StepDefinition, type WorkflowBindingSpec, type WorkflowBranch, type WorkflowConfig, type WorkflowDefinition, type WorkflowEventLike, type WorkflowInstanceAction, type WorkflowInstanceDetail, type WorkflowInstancePage, type WorkflowInstanceStatus, type WorkflowInstanceSummary, type WorkflowLogger, type WorkflowRunContext, type WorkflowRunFunction, type WorkflowRunStepFunction, type WorkflowStepDetail, type WorkflowStepLike, type Workflows, type WorkflowsRestClient, type WorkflowsRestConfig, WorkflowsRestError, branch, convertNonRetryableError, createRunStep, createWorkflowContext, createWorkflowRunContext, createWorkflows, createWorkflowsRestClient, defineStep, defineWorkflow, isNonRetryableError, isStepDefinition, isWorkflowDefinition, toNativeNonRetryableError, validateStepArgs, workflowBindingName, workflowClassName, workflowDefaultName };
+/** Dependencies one workflow invocation's `ctx.waitForEvent` closes over. */
+interface WaitForEventDeps {
+  /** Native `cloudflare:workflows` `NonRetryableError` constructor — injected by `src/do`; absent in Node tests. */
+  nonRetryableErrorClass?: NativeNonRetryableErrorConstructor;
+  /** The native Cloudflare durable-step API. */
+  step: WorkflowStepLike;
+}
+/**
+ * Build `ctx.waitForEvent` for one workflow invocation.
+ *
+ * Every failure here is **non-retryable**. A malformed definition or a reserved
+ * step name is a deterministic programmer error, and a payload that fails the
+ * validator has already consumed the event — replaying the wait cannot produce a
+ * different value, it can only hibernate the instance until its timeout. Each is
+ * raised through the shared {@link raiseNonRetryable}, the same classification path
+ * `ctx.runStep` uses, so the native error reaches Cloudflare and the instance fails
+ * fast.
+ */
+declare const createWaitForEvent: (deps: WaitForEventDeps) => WorkflowWaitForEventFunction;
+export { type LunoraWorkflowsOptions, MAX_BRANCHES, type NativeNonRetryableErrorConstructor, NonRetryableError, type StepArgsValidator, type StepConfig, type StepDefinition, type WorkflowBindingSpec, type WorkflowBranch, type WorkflowConfig, type WorkflowDefinition, type WorkflowEventDefinition, type WorkflowEventLike, type WorkflowInstanceAction, type WorkflowInstanceDetail, type WorkflowInstancePage, type WorkflowInstanceStatus, type WorkflowInstanceSummary, type WorkflowLogger, type WorkflowRunContext, type WorkflowRunFunction, type WorkflowRunStepFunction, type WorkflowStepDetail, type WorkflowStepLike, type WorkflowWaitForEventFunction, type Workflows, type WorkflowsRestClient, type WorkflowsRestConfig, WorkflowsRestError, branch, convertNonRetryableError, createRunStep, createWaitForEvent, createWorkflowContext, createWorkflowRunContext, createWorkflows, createWorkflowsRestClient, defineStep, defineWorkflow, defineWorkflowEvent, isNonRetryableError, isStepDefinition, isWorkflowDefinition, isWorkflowEventDefinition, toNativeNonRetryableError, validateStepArgs, workflowBindingName, workflowClassName, workflowDefaultName };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { a as Workflows, L as LunoraWorkflowsOptions, S as StepArgsValidator, b as StepConfig, c as StepDefinition, d as WorkflowConfig, W as WorkflowDefinition, e as WorkflowBranch, f as WorkflowInstanceStatus, g as WorkflowEventLike, h as WorkflowStepLike, i as WorkflowRunContext, j as WorkflowLogger, k as WorkflowRunFunction, l as WorkflowRunStepFunction } from "./packem_shared/types.d-CZ1pcdmw.js";
-export type { A as ArgsOf, B as BranchCompensationParams, F as FunctionReference, I as InferStepArgs, R as RunFunctionOptions, m as RunStepOptions, n as StepHandler, o as StepRollbackContext, p as StepRollbackHandler, q as StepRunContext, r as WorkflowBindingLike, s as WorkflowBranchOutputs, t as WorkflowCreateOptions, u as WorkflowHandle, v as WorkflowHandler, w as WorkflowInstanceLike, x as WorkflowParallelFunction, y as WorkflowRollbackContextLike, z as WorkflowRollbackHandlerLike, C as WorkflowSpawnFunction, D as WorkflowSpawnOptions, E as WorkflowStatusResult, G as WorkflowStepConfigLike, H as WorkflowStepContextLike, J as WorkflowStepRollbackOptionsLike } from "./packem_shared/types.d-CZ1pcdmw.js";
+import { a as Workflows, L as LunoraWorkflowsOptions, b as WorkflowEventDefinition, S as StepArgsValidator, c as StepConfig, d as StepDefinition, e as WorkflowConfig, W as WorkflowDefinition, f as WorkflowBranch, g as WorkflowInstanceStatus, h as WorkflowEventLike, i as WorkflowStepLike, j as WorkflowRunContext, k as WorkflowLogger, l as WorkflowRunFunction, m as WorkflowRunStepFunction, n as WorkflowWaitForEventFunction } from "./packem_shared/types.d-BmtJnXue.js";
+export type { A as ArgsOf, B as BranchCompensationParams, F as FunctionReference, I as InferStepArgs, R as RunFunctionOptions, o as RunStepOptions, p as StepHandler, q as StepRollbackContext, r as StepRollbackHandler, s as StepRunContext, t as WaitForEventOptions, u as WorkflowBindingLike, v as WorkflowBranchOutputs, w as WorkflowCreateOptions, x as WorkflowHandle, y as WorkflowHandler, z as WorkflowInstanceLike, C as WorkflowParallelFunction, D as WorkflowRollbackContextLike, E as WorkflowRollbackHandlerLike, G as WorkflowSpawnFunction, H as WorkflowSpawnOptions, J as WorkflowStatusResult, K as WorkflowStepConfigLike, M as WorkflowStepContextLike, N as WorkflowStepRollbackOptionsLike } from "./packem_shared/types.d-BmtJnXue.js";
+import { Validator } from '@lunora/values';
 import { LunoraError } from '@lunora/errors';
-import '@lunora/values';
 /** Wiring info for one declared workflow, emitted by codegen into the generated shard. */
 interface WorkflowBindingSpec {
   /** The Cloudflare `Workflow` binding name, e.g. `WORKFLOW_ORDER_PIPELINE`. */
@@ -23,6 +23,36 @@ declare const createWorkflowContext: (env: Record<string, unknown>, specs: Reado
  * an unknown name throws with the list of declared workflows.
  */
 declare const createWorkflows: (options: LunoraWorkflowsOptions) => Workflows;
+/**
+ * Declare an external event, its wire type, and its payload shape.
+ *
+ * ```ts
+ * // lunora/events.ts
+ * import { defineWorkflowEvent } from "@lunora/workflow";
+ * import { v } from "@lunora/values";
+ *
+ * export const orderApproved = defineWorkflowEvent("order-approved", v.object({ approvedBy: v.string() }));
+ * ```
+ *
+ * Wait on it inside a workflow body — the payload is typed and validated:
+ *
+ * ```ts
+ * const { approvedBy } = await ctx.waitForEvent(orderApproved, { name: "await approval", timeout: "7 days" });
+ * ```
+ *
+ * …and send it from a mutation/action with the same definition:
+ *
+ * ```ts
+ * await ctx.workflows.get("orderPipeline").sendEvent(instanceId, orderApproved, { approvedBy });
+ * ```
+ */
+declare const defineWorkflowEvent: <Payload>(type: string, payload: Validator<Payload>) => WorkflowEventDefinition<Payload>;
+/**
+ * True when a value is usable as an event definition. The brand alone is not the
+ * test: the predicate hands the caller a `type` and a `payload.parse`, so it checks
+ * for both (and for the reserved namespace) rather than trusting a public boolean.
+ */
+declare const isWorkflowEventDefinition: (value: unknown) => value is WorkflowEventDefinition;
 /**
  * Declare a reusable durable step. Same `args` map shape a Lunora `query` /
  * `mutation` / `action` uses, so a step reads like a function:
@@ -261,4 +291,23 @@ interface RunStepDeps {
  * converted to the native one and any declared rollback forwarded to Cloudflare.
  */
 declare const createRunStep: (deps: RunStepDeps) => WorkflowRunStepFunction;
-export { type LunoraWorkflowsOptions, MAX_BRANCHES, type NativeNonRetryableErrorConstructor, NonRetryableError, type StepArgsValidator, type StepConfig, type StepDefinition, type WorkflowBindingSpec, type WorkflowBranch, type WorkflowConfig, type WorkflowDefinition, type WorkflowEventLike, type WorkflowInstanceAction, type WorkflowInstanceDetail, type WorkflowInstancePage, type WorkflowInstanceStatus, type WorkflowInstanceSummary, type WorkflowLogger, type WorkflowRunContext, type WorkflowRunFunction, type WorkflowRunStepFunction, type WorkflowStepDetail, type WorkflowStepLike, type Workflows, type WorkflowsRestClient, type WorkflowsRestConfig, WorkflowsRestError, branch, convertNonRetryableError, createRunStep, createWorkflowContext, createWorkflowRunContext, createWorkflows, createWorkflowsRestClient, defineStep, defineWorkflow, isNonRetryableError, isStepDefinition, isWorkflowDefinition, toNativeNonRetryableError, validateStepArgs, workflowBindingName, workflowClassName, workflowDefaultName };
+/** Dependencies one workflow invocation's `ctx.waitForEvent` closes over. */
+interface WaitForEventDeps {
+  /** Native `cloudflare:workflows` `NonRetryableError` constructor — injected by `src/do`; absent in Node tests. */
+  nonRetryableErrorClass?: NativeNonRetryableErrorConstructor;
+  /** The native Cloudflare durable-step API. */
+  step: WorkflowStepLike;
+}
+/**
+ * Build `ctx.waitForEvent` for one workflow invocation.
+ *
+ * Every failure here is **non-retryable**. A malformed definition or a reserved
+ * step name is a deterministic programmer error, and a payload that fails the
+ * validator has already consumed the event — replaying the wait cannot produce a
+ * different value, it can only hibernate the instance until its timeout. Each is
+ * raised through the shared {@link raiseNonRetryable}, the same classification path
+ * `ctx.runStep` uses, so the native error reaches Cloudflare and the instance fails
+ * fast.
+ */
+declare const createWaitForEvent: (deps: WaitForEventDeps) => WorkflowWaitForEventFunction;
+export { type LunoraWorkflowsOptions, MAX_BRANCHES, type NativeNonRetryableErrorConstructor, NonRetryableError, type StepArgsValidator, type StepConfig, type StepDefinition, type WorkflowBindingSpec, type WorkflowBranch, type WorkflowConfig, type WorkflowDefinition, type WorkflowEventDefinition, type WorkflowEventLike, type WorkflowInstanceAction, type WorkflowInstanceDetail, type WorkflowInstancePage, type WorkflowInstanceStatus, type WorkflowInstanceSummary, type WorkflowLogger, type WorkflowRunContext, type WorkflowRunFunction, type WorkflowRunStepFunction, type WorkflowStepDetail, type WorkflowStepLike, type WorkflowWaitForEventFunction, type Workflows, type WorkflowsRestClient, type WorkflowsRestConfig, WorkflowsRestError, branch, convertNonRetryableError, createRunStep, createWaitForEvent, createWorkflowContext, createWorkflowRunContext, createWorkflows, createWorkflowsRestClient, defineStep, defineWorkflow, defineWorkflowEvent, isNonRetryableError, isStepDefinition, isWorkflowDefinition, isWorkflowEventDefinition, toNativeNonRetryableError, validateStepArgs, workflowBindingName, workflowClassName, workflowDefaultName };

package/dist/index.mjs

@@ -1 +1 @@
-import{createWorkflowContext as e}from"./packem_shared/createWorkflowContext-DG-jCSoa.mjs";import{default as f}from"./packem_shared/createWorkflows-uoAhGKCA.mjs";import{defineStep as l,isStepDefinition as n}from"./packem_shared/defineStep-D1-9eOnA.mjs";import{defineWorkflow as s,isWorkflowDefinition as p,workflowBindingName as w,workflowClassName as m,workflowDefaultName as x}from"./packem_shared/defineWorkflow-tKaIifbZ.mjs";import{NonRetryableError as N,convertNonRetryableError as R,isNonRetryableError as c,toNativeNonRetryableError as W}from"./packem_shared/NonRetryableError-9ZqDUzwT.mjs";import{MAX_BRANCHES as b,branch as d}from"./packem_shared/MAX_BRANCHES-ZS8UAw_t.mjs";import{WorkflowsRestError as S,createWorkflowsRestClient as u}from"./packem_shared/WorkflowsRestError-HhBsn3PQ.mjs";import{createWorkflowRunContext as y}from"./packem_shared/createWorkflowRunContext-D1vdFtWC.mjs";import{c as D,v as g}from"./packem_shared/run-step-7RiMJYR7.mjs";export{b as MAX_BRANCHES,N as NonRetryableError,S as WorkflowsRestError,d as branch,R as convertNonRetryableError,D as createRunStep,e as createWorkflowContext,y as createWorkflowRunContext,f as createWorkflows,u as createWorkflowsRestClient,l as defineStep,s as defineWorkflow,c as isNonRetryableError,n as isStepDefinition,p as isWorkflowDefinition,W as toNativeNonRetryableError,g as validateStepArgs,w as workflowBindingName,m as workflowClassName,x as workflowDefaultName};
+import{createWorkflowContext as e}from"./packem_shared/createWorkflowContext-zQR_9N-v.mjs";import{default as f}from"./packem_shared/createWorkflows-LvAyUyKq.mjs";import{defineWorkflowEvent as a,isWorkflowEventDefinition as i}from"./packem_shared/defineWorkflowEvent-suERPEEV.mjs";import{defineStep as p,isStepDefinition as s}from"./packem_shared/defineStep-D1-9eOnA.mjs";import{defineWorkflow as m,isWorkflowDefinition as x,workflowBindingName as k,workflowClassName as W,workflowDefaultName as c}from"./packem_shared/defineWorkflow-tKaIifbZ.mjs";import{NonRetryableError as N,convertNonRetryableError as R,isNonRetryableError as v,toNativeNonRetryableError as d}from"./packem_shared/NonRetryableError-9ZqDUzwT.mjs";import{MAX_BRANCHES as C,branch as S}from"./packem_shared/MAX_BRANCHES-C05O5LY9.mjs";import{WorkflowsRestError as y,createWorkflowsRestClient as D}from"./packem_shared/WorkflowsRestError-HhBsn3PQ.mjs";import{createWorkflowRunContext as g}from"./packem_shared/createWorkflowRunContext-CNvJHMci.mjs";import{c as h,v as F}from"./packem_shared/run-step-7RiMJYR7.mjs";import{createWaitForEvent as M}from"./packem_shared/createWaitForEvent-DjWsI895.mjs";export{C as MAX_BRANCHES,N as NonRetryableError,y as WorkflowsRestError,S as branch,R as convertNonRetryableError,h as createRunStep,M as createWaitForEvent,e as createWorkflowContext,g as createWorkflowRunContext,f as createWorkflows,D as createWorkflowsRestClient,p as defineStep,m as defineWorkflow,a as defineWorkflowEvent,v as isNonRetryableError,s as isStepDefinition,x as isWorkflowDefinition,i as isWorkflowEventDefinition,d as toNativeNonRetryableError,F as validateStepArgs,k as workflowBindingName,W as workflowClassName,c as workflowDefaultName};

package/dist/packem_shared/MAX_BRANCHES-C05O5LY9.mjs

@@ -0,0 +1 @@
+import{LunoraError as E}from"@lunora/errors";import{h as y,B as I,a as p}from"./branch-marker-CCpWfS5k.mjs";import{RESERVED_EVENT_TYPE_PREFIX as v}from"./defineWorkflowEvent-suERPEEV.mjs";import{NonRetryableError as d}from"./NonRetryableError-9ZqDUzwT.mjs";const h=100,g="lunora:spawn:",$="lunora:await:",x="lunora:signal:",B="lunora:compensate:",m=`${v}branch:`,b=(t,r,n)=>({compensateWith:n?.compensateWith,id:n?.id,params:r,timeout:n?.timeout,workflow:t}),w=t=>t instanceof Error?{message:t.message,name:t.name}:{message:String(t),name:"Error"},A=t=>({status:"ok",value:t}),N=t=>({error:w(t),status:"error"}),f=async(t,r,n)=>{for(let a=r.length-1;a>=0;a-=1){const o=r[a],c=o?.plan.item.compensateWith;if(!(o===void 0||c===void 0))try{const s=t.resolveBinding(c);await t.step.do(`${B}${o.plan.childId}`,async()=>{const e=`${o.plan.childId}:compensate`,i={branch:o.plan.item.workflow,error:n,index:o.plan.index,output:o.output};return await s.create({id:e,params:i}),e})}catch(s){t.log?.error(`ctx.parallel: group-saga compensation "${c}" for branch "${o.plan.item.workflow}" (#${String(o.plan.index)}) failed`,s)}}},k=t=>async n=>{if(n.length===0)return[];if(n.length>h)throw new d(`ctx.parallel: ${String(n.length)} branches exceeds the cap of ${String(h)} — split the fan-out or raise the work into fewer child workflows`);const a=n.map((e,i)=>{const l=t.nextChildId(e.id);return{childId:l,eventType:`${m}${l}`,index:i,item:e}}),o=new Set;for(const e of a){if(o.has(e.childId))throw new d(`ctx.parallel: duplicate branch id "${e.childId}" — each branch in a group must resolve to a unique child instance id (check explicit \`id\` options)`);o.add(e.childId)}await Promise.all(a.map(e=>t.step.do(`${g}${e.childId}`,async()=>{const i=t.resolveBinding(e.item.workflow),l={eventType:e.eventType,index:e.index,parentBinding:t.parentBinding,parentId:t.instanceId};return await i.create({id:e.childId,params:{...e.item.params,[p]:l}}),e.childId})));const c=[],s=[];for(const e of a){let i;try{i=(await t.step.waitForEvent(`${$}${e.childId}`,{timeout:e.item.timeout,type:e.eventType})).payload}catch(l){const u=w(l);throw await f(t,s,u),new d(`ctx.parallel: branch "${e.item.workflow}" (#${String(e.index)}) join failed: ${u.message}`)}if(i.status==="error")throw await f(t,s,i.error),new d(`ctx.parallel: branch "${e.item.workflow}" (#${String(e.index)}) failed: ${i.error.message}`);s.push({output:i.value,plan:e}),c.push(i.value)}return c},W=t=>async(r,n,a)=>{if(y(n))throw new E("BAD_REQUEST",`@lunora/workflow: params ${I}`);const o=t.nextChildId(a?.id);return await t.step.do(`${g}${o}`,async()=>(await t.resolveBinding(r).create({id:o,params:n}),o)),t.resolveBinding(r).get(o)},C=t=>{if(typeof t!="object"||t===null)return;const r=t[p];if(typeof r!="object"||r===null)return;const n=r;if(!(typeof n.eventType!="string"||typeof n.parentBinding!="string"||typeof n.parentId!="string"||typeof n.index!="number")&&!(!n.parentBinding.startsWith("WORKFLOW_")||!n.eventType.startsWith(m)))return{eventType:n.eventType,index:n.index,parentBinding:n.parentBinding,parentId:n.parentId}},F=t=>{if(typeof t!="object"||t===null)return t;const r={...t};return Reflect.deleteProperty(r,p),r},T=async(t,r,n)=>{const a=t.env[r.parentBinding];if(!a||typeof a.get!="function")return;const o=a.get.bind(a);await t.step.do(`${x}${String(r.index)}`,async()=>(await(await o(r.parentId)).sendEvent({payload:n,type:r.eventType}),r.eventType))},M=async(t,r,n)=>{try{await T(t,r,n)}catch(a){t.log?.error(`@lunora/workflow: failed to signal branch parent "${r.parentId}" (event "${r.eventType}")`,a)}};export{h as MAX_BRANCHES,b as branch,k as createParallel,W as createSpawn,N as errorOutcome,C as extractBranchMarker,A as okOutcome,T as signalBranchParent,M as signalBranchParentSafe,F as stripBranchMarker};

package/dist/packem_shared/createWaitForEvent-DjWsI895.mjs

@@ -0,0 +1 @@
+import{eventDefinitionProblem as m,RESERVED_EVENT_TYPE_PREFIX as i}from"./defineWorkflowEvent-suERPEEV.mjs";import{raiseNonRetryable as a}from"./NonRetryableError-9ZqDUzwT.mjs";const c=e=>async(r,t)=>{const n=m(r);if(n!==void 0)return a(`@lunora/workflow: ctx.waitForEvent ${n}`,void 0,e.nonRetryableErrorClass);if(t?.name?.startsWith(i)===!0)return a(`@lunora/workflow: ctx.waitForEvent step name "${t.name}" is reserved — the "${i}" prefix is used by the framework's own steps`,void 0,e.nonRetryableErrorClass);const s=await e.step.waitForEvent(t?.name??`event:${r.type}`,{timeout:t?.timeout,type:r.type});try{return r.payload.parse(s.payload)}catch(o){const l=o instanceof Error?o.message:String(o);return a(`@lunora/workflow: event "${r.type}" payload validation failed: ${l}`,o,e.nonRetryableErrorClass)}};export{c as createWaitForEvent};

package/dist/packem_shared/{createWorkflowContext-DG-jCSoa.mjs → createWorkflowContext-zQR_9N-v.mjs}

@@ -1 +1 @@
-import r from"./createWorkflows-uoAhGKCA.mjs";const i=(n,c)=>{const o={};for(const e of c){const t=n[e.binding];t&&typeof t.create=="function"&&typeof t.createBatch=="function"&&typeof t.get=="function"&&(o[e.exportName]=t)}return r({bindings:o})};export{i as createWorkflowContext};
+import r from"./createWorkflows-LvAyUyKq.mjs";const i=(n,c)=>{const o={};for(const e of c){const t=n[e.binding];t&&typeof t.create=="function"&&typeof t.createBatch=="function"&&typeof t.get=="function"&&(o[e.exportName]=t)}return r({bindings:o})};export{i as createWorkflowContext};

package/dist/packem_shared/createWorkflowRunContext-CNvJHMci.mjs

@@ -0,0 +1 @@
+import{a as v,c as w}from"./run-step-7RiMJYR7.mjs";import{LunoraError as i}from"@lunora/errors";import{workflowBindingName as s}from"./defineWorkflow-tKaIifbZ.mjs";import{createSpawn as u,createParallel as m}from"./MAX_BRANCHES-C05O5LY9.mjs";import{createWaitForEvent as p}from"./createWaitForEvent-DjWsI895.mjs";const g=e=>({debug:(r,...n)=>{console.debug(e,r,...n)},error:(r,...n)=>{console.error(e,r,...n)},info:(r,...n)=>{console.info(e,r,...n)},warn:(r,...n)=>{console.warn(e,r,...n)}}),I=e=>{const r=g(`[workflow:${e.exportName}]`),n=v({env:e.env,fetchImpl:e.fetchImpl,label:"@lunora/workflow"}),f=t=>{const a=s(t),o=e.env[a];if(!o||typeof o.create!="function"||typeof o.get!="function")throw new i("INTERNAL",`@lunora/workflow: cannot spawn child workflow "${t}" — no Workflow binding "${a}" on env (is it declared in lunora/workflows.ts?)`);return o};let l=0;const d=t=>{if(t!==void 0)return t;const a=`${e.event.instanceId}-c${String(l)}`;return l+=1,a},c={env:e.env,instanceId:e.event.instanceId,log:r,nextChildId:d,parentBinding:s(e.exportName),resolveBinding:f,step:e.step};return{env:e.env,event:e.event,log:r,parallel:m(c),params:e.event.payload,run:n,runStep:w({env:e.env,log:r,nonRetryableErrorClass:e.nonRetryableErrorClass,run:n,step:e.step}),spawn:u(c),step:e.step,waitForEvent:p({nonRetryableErrorClass:e.nonRetryableErrorClass,step:e.step})}};export{I as createWorkflowRunContext};

package/dist/packem_shared/createWorkflows-LvAyUyKq.mjs

@@ -0,0 +1 @@
+import{LunoraError as a}from"@lunora/errors";import{h as w,B as f}from"./branch-marker-CCpWfS5k.mjs";import{eventDefinitionProblem as l}from"./defineWorkflowEvent-suERPEEV.mjs";const c=r=>{if(w(r?.params))throw new a("BAD_REQUEST",`@lunora/workflow: params ${f}`)},i=r=>({create:async o=>(c(o),r.create(o)),createBatch:async o=>{for(const e of o)c(e);return r.createBatch(o)},get:async o=>r.get(o),sendEvent:async(o,e,t)=>{const n=l(e);if(n!==void 0)throw new a("BAD_REQUEST",`@lunora/workflow: sendEvent ${n}`);await(await r.get(o)).sendEvent({payload:e.payload.parse(t),type:e.type})}}),k=r=>{const o=r.bindings??{};return{get:e=>{const t=o[e];if(t===void 0){const n=Object.keys(o),s=n.length===0?"no workflows are declared":`known workflows: ${n.join(", ")}`;throw new a("INTERNAL",`@lunora/workflow: no workflow named "${e}" (${s})`)}return i(t)}}};export{k as default};

package/dist/packem_shared/defineWorkflowEvent-suERPEEV.mjs

@@ -0,0 +1 @@
+const o="lunora:",r=e=>{if(typeof e!="object"||e===null||e.isLunoraWorkflowEvent!==!0)return"expects a `defineWorkflowEvent` definition";const t=e;if(typeof t.type!="string"||t.type.length===0)return"event `type` must be a non-empty string";if(t.type.startsWith(o))return`event type "${t.type}" is reserved — the "${o}" prefix is used by the framework's own events`;if(typeof t.payload?.parse!="function")return"event `payload` must be a validator (e.g. `v.object({ ok: v.boolean() })`)"},i=(e,t)=>{if(typeof e!="string"||e.length===0)throw new TypeError("defineWorkflowEvent: `type` must be a non-empty string (the wire event type)");const n=r({isLunoraWorkflowEvent:!0,payload:t,type:e});if(n!==void 0)throw new TypeError(`defineWorkflowEvent: ${n}`);return{isLunoraWorkflowEvent:!0,payload:t,type:e}},f=e=>r(e)===void 0;export{o as RESERVED_EVENT_TYPE_PREFIX,i as defineWorkflowEvent,r as eventDefinitionProblem,f as isWorkflowEventDefinition};

package/dist/packem_shared/{types.d-CZ1pcdmw.d.mts → types.d-BmtJnXue.d.mts}

@@ -263,6 +263,55 @@ interface RunStepOptions {
  * ```
  */
 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
@@ -364,6 +413,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>;
@@ -395,7 +446,8 @@ interface WorkflowDefinition<Params = Record<string, unknown>, Output = unknown>
 }
 /**
  * A typed handle to one declared workflow, addressable from `ctx.workflows`.
- * Thin pass-through over the Cloudflare `Workflow` binding.
+ * 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). */
@@ -404,6 +456,17 @@ 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
@@ -422,4 +485,4 @@ interface LunoraWorkflowsOptions {
    */
   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, WorkflowParallelFunction as C, WorkflowRollbackContextLike as D, WorkflowRollbackHandlerLike as E, FunctionReference as F, WorkflowSpawnFunction as G, WorkflowSpawnOptions as H, InferStepArgs as I, WorkflowStatusResult as J, WorkflowStepConfigLike as K, LunoraWorkflowsOptions as L, WorkflowStepContextLike as M, WorkflowStepRollbackOptionsLike as N, 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, RunStepOptions as o, StepHandler as p, StepRollbackContext as q, StepRollbackHandler as r, StepRunContext as s, WaitForEventOptions as t, WorkflowBindingLike as u, WorkflowBranchOutputs as v, WorkflowCreateOptions as w, WorkflowHandle as x, WorkflowHandler as y, WorkflowInstanceLike as z };

package/dist/packem_shared/{types.d-CZ1pcdmw.d.ts → types.d-BmtJnXue.d.ts}

@@ -263,6 +263,55 @@ interface RunStepOptions {
  * ```
  */
 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
@@ -364,6 +413,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>;
@@ -395,7 +446,8 @@ interface WorkflowDefinition<Params = Record<string, unknown>, Output = unknown>
 }
 /**
  * A typed handle to one declared workflow, addressable from `ctx.workflows`.
- * Thin pass-through over the Cloudflare `Workflow` binding.
+ * 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). */
@@ -404,6 +456,17 @@ 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
@@ -422,4 +485,4 @@ interface LunoraWorkflowsOptions {
    */
   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, WorkflowParallelFunction as C, WorkflowRollbackContextLike as D, WorkflowRollbackHandlerLike as E, FunctionReference as F, WorkflowSpawnFunction as G, WorkflowSpawnOptions as H, InferStepArgs as I, WorkflowStatusResult as J, WorkflowStepConfigLike as K, LunoraWorkflowsOptions as L, WorkflowStepContextLike as M, WorkflowStepRollbackOptionsLike as N, 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, RunStepOptions as o, StepHandler as p, StepRollbackContext as q, StepRollbackHandler as r, StepRunContext as s, WaitForEventOptions as t, WorkflowBindingLike as u, WorkflowBranchOutputs as v, WorkflowCreateOptions as w, WorkflowHandle as x, WorkflowHandler as y, WorkflowInstanceLike as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/workflow",
-  "version": "1.0.0-alpha.29",
+  "version": "1.0.0-alpha.30",
   "description": "Durable workflows for Lunora: defineWorkflow over Cloudflare Workflows, generated WorkflowEntrypoint classes, and the ctx.workflows surface",
   "keywords": [
     "cloudflare",

package/dist/packem_shared/MAX_BRANCHES-ZS8UAw_t.mjs

@@ -1 +0,0 @@
-import{LunoraError as y}from"@lunora/errors";import{h as E,B as v,a as p}from"./branch-marker-CCpWfS5k.mjs";import{NonRetryableError as d}from"./NonRetryableError-9ZqDUzwT.mjs";const h=100,g="lunora:spawn:",I="lunora:await:",$="lunora:signal:",x="lunora:compensate:",m="lunora:branch:",R=(t,r,n)=>({compensateWith:n?.compensateWith,id:n?.id,params:r,timeout:n?.timeout,workflow:t}),w=t=>t instanceof Error?{message:t.message,name:t.name}:{message:String(t),name:"Error"},b=t=>({status:"ok",value:t}),_=t=>({error:w(t),status:"error"}),f=async(t,r,n)=>{for(let o=r.length-1;o>=0;o-=1){const a=r[o],c=a?.plan.item.compensateWith;if(!(a===void 0||c===void 0))try{const s=t.resolveBinding(c);await t.step.do(`${x}${a.plan.childId}`,async()=>{const e=`${a.plan.childId}:compensate`,i={branch:a.plan.item.workflow,error:n,index:a.plan.index,output:a.output};return await s.create({id:e,params:i}),e})}catch(s){t.log?.error(`ctx.parallel: group-saga compensation "${c}" for branch "${a.plan.item.workflow}" (#${String(a.plan.index)}) failed`,s)}}},A=t=>async n=>{if(n.length===0)return[];if(n.length>h)throw new d(`ctx.parallel: ${String(n.length)} branches exceeds the cap of ${String(h)} — split the fan-out or raise the work into fewer child workflows`);const o=n.map((e,i)=>{const l=t.nextChildId(e.id);return{childId:l,eventType:`${m}${l}`,index:i,item:e}}),a=new Set;for(const e of o){if(a.has(e.childId))throw new d(`ctx.parallel: duplicate branch id "${e.childId}" — each branch in a group must resolve to a unique child instance id (check explicit \`id\` options)`);a.add(e.childId)}await Promise.all(o.map(e=>t.step.do(`${g}${e.childId}`,async()=>{const i=t.resolveBinding(e.item.workflow),l={eventType:e.eventType,index:e.index,parentBinding:t.parentBinding,parentId:t.instanceId};return await i.create({id:e.childId,params:{...e.item.params,[p]:l}}),e.childId})));const c=[],s=[];for(const e of o){let i;try{i=(await t.step.waitForEvent(`${I}${e.childId}`,{timeout:e.item.timeout,type:e.eventType})).payload}catch(l){const u=w(l);throw await f(t,s,u),new d(`ctx.parallel: branch "${e.item.workflow}" (#${String(e.index)}) join failed: ${u.message}`)}if(i.status==="error")throw await f(t,s,i.error),new d(`ctx.parallel: branch "${e.item.workflow}" (#${String(e.index)}) failed: ${i.error.message}`);s.push({output:i.value,plan:e}),c.push(i.value)}return c},k=t=>async(r,n,o)=>{if(E(n))throw new y("BAD_REQUEST",`@lunora/workflow: params ${v}`);const a=t.nextChildId(o?.id);return await t.step.do(`${g}${a}`,async()=>(await t.resolveBinding(r).create({id:a,params:n}),a)),t.resolveBinding(r).get(a)},N=t=>{if(typeof t!="object"||t===null)return;const r=t[p];if(typeof r!="object"||r===null)return;const n=r;if(!(typeof n.eventType!="string"||typeof n.parentBinding!="string"||typeof n.parentId!="string"||typeof n.index!="number")&&!(!n.parentBinding.startsWith("WORKFLOW_")||!n.eventType.startsWith(m)))return{eventType:n.eventType,index:n.index,parentBinding:n.parentBinding,parentId:n.parentId}},W=t=>{if(typeof t!="object"||t===null)return t;const r={...t};return Reflect.deleteProperty(r,p),r},B=async(t,r,n)=>{const o=t.env[r.parentBinding];if(!o||typeof o.get!="function")return;const a=o.get.bind(o);await t.step.do(`${$}${String(r.index)}`,async()=>(await(await a(r.parentId)).sendEvent({payload:n,type:r.eventType}),r.eventType))},C=async(t,r,n)=>{try{await B(t,r,n)}catch(o){t.log?.error(`@lunora/workflow: failed to signal branch parent "${r.parentId}" (event "${r.eventType}")`,o)}};export{h as MAX_BRANCHES,R as branch,A as createParallel,k as createSpawn,_ as errorOutcome,N as extractBranchMarker,b as okOutcome,B as signalBranchParent,C as signalBranchParentSafe,W as stripBranchMarker};

package/dist/packem_shared/createWorkflowRunContext-D1vdFtWC.mjs

@@ -1 +0,0 @@
-import{a as w,c as u}from"./run-step-7RiMJYR7.mjs";import{LunoraError as v}from"@lunora/errors";import{workflowBindingName as f}from"./defineWorkflow-tKaIifbZ.mjs";import{createSpawn as i,createParallel as m}from"./MAX_BRANCHES-ZS8UAw_t.mjs";const g=e=>({debug:(n,...r)=>{console.debug(e,n,...r)},error:(n,...r)=>{console.error(e,n,...r)},info:(n,...r)=>{console.info(e,n,...r)},warn:(n,...r)=>{console.warn(e,n,...r)}}),h=e=>{const n=g(`[workflow:${e.exportName}]`),r=w({env:e.env,fetchImpl:e.fetchImpl,label:"@lunora/workflow"}),s=t=>{const a=f(t),o=e.env[a];if(!o||typeof o.create!="function"||typeof o.get!="function")throw new v("INTERNAL",`@lunora/workflow: cannot spawn child workflow "${t}" — no Workflow binding "${a}" on env (is it declared in lunora/workflows.ts?)`);return o};let l=0;const d=t=>{if(t!==void 0)return t;const a=`${e.event.instanceId}-c${String(l)}`;return l+=1,a},c={env:e.env,instanceId:e.event.instanceId,log:n,nextChildId:d,parentBinding:f(e.exportName),resolveBinding:s,step:e.step};return{env:e.env,event:e.event,log:n,parallel:m(c),params:e.event.payload,run:r,runStep:u({env:e.env,log:n,nonRetryableErrorClass:e.nonRetryableErrorClass,run:r,step:e.step}),spawn:i(c),step:e.step}};export{h as createWorkflowRunContext};

package/dist/packem_shared/createWorkflows-uoAhGKCA.mjs

@@ -1 +0,0 @@
-import{LunoraError as s}from"@lunora/errors";import{h as w,B as f}from"./branch-marker-CCpWfS5k.mjs";const a=o=>{if(w(o?.params))throw new s("BAD_REQUEST",`@lunora/workflow: params ${f}`)},l=o=>({create:async r=>(a(r),o.create(r)),createBatch:async r=>{for(const e of r)a(e);return o.createBatch(r)},get:async r=>o.get(r)}),i=o=>{const r=o.bindings??{};return{get:e=>{const n=r[e];if(n===void 0){const t=Object.keys(r),c=t.length===0?"no workflows are declared":`known workflows: ${t.join(", ")}`;throw new s("INTERNAL",`@lunora/workflow: no workflow named "${e}" (${c})`)}return l(n)}}};export{i as default};