@lunora/workflow 1.0.0-alpha.1 → 1.0.0-alpha.10

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-CQO_koGe.mjs";
+import { W as WorkflowDefinition } from "../packem_shared/types.d-C9W6rEWv.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-CQO_koGe.js";
+import { W as WorkflowDefinition } from "../packem_shared/types.d-C9W6rEWv.js";
 import '@lunora/values';
 /**
 * Base class for the generated `WorkflowEntrypoint` classes. Applies a

package/dist/do/index.mjs

@@ -1,7 +1,8 @@
 import { WorkflowEntrypoint } from 'cloudflare:workers';
 import { NonRetryableError } from 'cloudflare:workflows';
-import { convertNonRetryableError } from '../packem_shared/convertNonRetryableError-Dn2dTyBS.mjs';
-import { createWorkflowRunContext } from '../packem_shared/createWorkflowLogger-FktqxNLe.mjs';
+import { convertNonRetryableError } from '../packem_shared/NonRetryableError-Dn2dTyBS.mjs';
+import { extractBranchMarker, stripBranchMarker, signalBranchParentSafe, errorOutcome, okOutcome } from '../packem_shared/MAX_BRANCHES-EO5xYS_3.mjs';
+import { createWorkflowRunContext } from '../packem_shared/createWorkflowRunContext-D62MbkFK.mjs';
 
 class LunoraWorkflow extends WorkflowEntrypoint {
   /** The `lunora/workflows.ts` export name, for log correlation. */
@@ -14,18 +15,29 @@ class LunoraWorkflow extends WorkflowEntrypoint {
     this.#lunoraName = exportName ?? "workflow";
   }
   async run(event, step) {
+    const nativeStep = step;
+    const marker = extractBranchMarker(event.payload);
+    const handlerEvent = marker ? { ...event, payload: stripBranchMarker(event.payload) } : event;
     const context = createWorkflowRunContext({
       env: this.env,
-      event,
+      event: handlerEvent,
       exportName: this.#lunoraName,
       nonRetryableErrorClass: NonRetryableError,
-      step
+      step: nativeStep
     });
+    let output;
     try {
-      return await this.#definition.handler(context);
+      output = await this.#definition.handler(context);
     } catch (error) {
+      if (marker) {
+        await signalBranchParentSafe({ env: this.env, log: context.log, step: nativeStep }, marker, errorOutcome(error));
+      }
       return convertNonRetryableError(error, NonRetryableError);
     }
+    if (marker) {
+      await signalBranchParentSafe({ env: this.env, log: context.log, step: nativeStep }, marker, okOutcome(output));
+    }
+    return output;
   }
 }
 

package/dist/index.d.mts

@@ -1,5 +1,6 @@
-import { a as Workflows, L as LunoraWorkflowsOptions, S as StepArgsValidator, b as StepConfig, c as StepDefinition, d as WorkflowConfig, W as WorkflowDefinition, e as WorkflowInstanceStatus, f as WorkflowLogger, g as WorkflowEventLike, h as WorkflowStepLike, i as WorkflowRunContext, j as WorkflowRunFunction, k as WorkflowRunStepFunction } from "./packem_shared/types.d-CQO_koGe.mjs";
-export type { A as ArgsOf, F as FunctionReference, I as InferStepArgs, R as RunFunctionOptions, l as RunStepOptions, m as StepHandler, n as StepRollbackContext, o as StepRollbackHandler, p as StepRunContext, q as WorkflowBindingLike, r as WorkflowCreateOptions, s as WorkflowHandle, t as WorkflowHandler, u as WorkflowInstanceLike, v as WorkflowRollbackContextLike, w as WorkflowRollbackHandlerLike, x as WorkflowStatusResult, y as WorkflowStepConfigLike, z as WorkflowStepContextLike, B as WorkflowStepRollbackOptionsLike } from "./packem_shared/types.d-CQO_koGe.mjs";
+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-C9W6rEWv.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-C9W6rEWv.mjs";
+import { LunoraError } from '@lunora/errors';
 import '@lunora/values';
 /** Wiring info for one declared workflow, emitted by codegen into the generated shard. */
 interface WorkflowBindingSpec {
@@ -131,6 +132,22 @@ declare const toNativeNonRetryableError: (error: NonRetryableError, NativeNonRet
 * Always throws — the `never` return lets callers `return convertNonRetryableError(...)`.
 */
 declare const convertNonRetryableError: (error: unknown, NativeNonRetryableError: NativeNonRetryableErrorConstructor | undefined) => never;
+/** Hard cap on branches per `ctx.parallel` call — auto-scale, never silently spawn unbounded DOs. */
+declare const MAX_BRANCHES = 100;
+/** The params key the parent injects so a child knows to signal completion back. Stripped before the user handler sees `ctx.params`. */
+
+/**
+* Build a single fan-out branch: a declared child workflow referenced by its
+* `lunora/workflows.ts` export name, plus the params it is created with. Pass the
+* output type as the generic argument so `ctx.parallel(...)` infers the result
+* tuple — e.g. `branch("imageTag", { key })` typed as `branch` of `{ tags }`.
+*/
+declare const branch: <Output = unknown>(workflow: string, params?: Record<string, unknown>, options?: {
+  compensateWith?: string;
+  id?: string;
+  timeout?: number | string;
+}) => WorkflowBranch<Output>;
+/** Build the success outcome a completed branch reports to its parent. */
 /** The lifecycle mutations the REST API exposes via `PATCH .../instances/{id}`. */
 type WorkflowInstanceAction = "pause" | "resume" | "terminate";
 /** Configuration for a {@link WorkflowsRestClient}. */
@@ -178,8 +195,7 @@ interface WorkflowInstancePage {
   totalCount?: number;
 }
 /** Thrown when the REST API responds non-2xx or `success: false`; carries the status plus body for the caller to surface. */
-declare class WorkflowsRestError extends Error {
-  readonly status: number;
+declare class WorkflowsRestError extends LunoraError {
   constructor(status: number, body: string);
 }
 /** The observe client: list instances, read one instance's steps, and (with Edit scope) mutate its status. */
@@ -209,24 +225,6 @@ interface WorkflowsRestClient {
 * snake_case payload into the camelCase shapes the studio renders.
 */
 declare const createWorkflowsRestClient: (config: WorkflowsRestConfig) => WorkflowsRestClient;
-interface RunnerOptions {
-  /** Worker `env` — read `LUNORA_ORIGIN_URL` + `LUNORA_ADMIN_TOKEN` at call time. */
-  env: Record<string, unknown>;
-  /** Injectable fetch (tests); defaults to the global. */
-  fetchImpl?: typeof fetch;
-}
-/**
-* Build a {@link WorkflowRunFunction} that invokes a Lunora function by POSTing
-* to the Worker's `/_lunora/scheduler/dispatch` endpoint — the same path the
-* SchedulerDO and the Queues workpool dispatch through — authenticated with the
-* admin bearer. The parsed JSON body (the function's return value) is resolved;
-* an empty/non-JSON body resolves to `undefined`.
-*
-* Wrap calls in `ctx.step.do(...)` to make them durable + memoized + retried.
-*/
-declare const createWorkflowRunner: (options: RunnerOptions) => WorkflowRunFunction;
-/** Console-backed logger, prefixed with the workflow name for log correlation. */
-declare const createWorkflowLogger: (exportName: string) => WorkflowLogger;
 interface RunContextOptions<Params> {
   env: Record<string, unknown>;
   event: WorkflowEventLike<Params>;
@@ -266,4 +264,4 @@ interface RunStepDeps {
 * converted to the native one and any declared rollback forwarded to Cloudflare.
 */
 declare const createRunStep: (deps: RunStepDeps) => WorkflowRunStepFunction;
-export { type LunoraWorkflowsOptions, type NativeNonRetryableErrorConstructor, NonRetryableError, type StepArgsValidator, type StepConfig, type StepDefinition, type WorkflowBindingSpec, 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, convertNonRetryableError, createRunStep, createWorkflowContext, createWorkflowLogger, createWorkflowRunContext, createWorkflowRunner, createWorkflows, createWorkflowsRestClient, defineStep, defineWorkflow, isNonRetryableError, isStepDefinition, isWorkflowDefinition, toNativeNonRetryableError, validateStepArgs, workflowBindingName, workflowClassName, workflowDefaultName };
+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 };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { a as Workflows, L as LunoraWorkflowsOptions, S as StepArgsValidator, b as StepConfig, c as StepDefinition, d as WorkflowConfig, W as WorkflowDefinition, e as WorkflowInstanceStatus, f as WorkflowLogger, g as WorkflowEventLike, h as WorkflowStepLike, i as WorkflowRunContext, j as WorkflowRunFunction, k as WorkflowRunStepFunction } from "./packem_shared/types.d-CQO_koGe.js";
-export type { A as ArgsOf, F as FunctionReference, I as InferStepArgs, R as RunFunctionOptions, l as RunStepOptions, m as StepHandler, n as StepRollbackContext, o as StepRollbackHandler, p as StepRunContext, q as WorkflowBindingLike, r as WorkflowCreateOptions, s as WorkflowHandle, t as WorkflowHandler, u as WorkflowInstanceLike, v as WorkflowRollbackContextLike, w as WorkflowRollbackHandlerLike, x as WorkflowStatusResult, y as WorkflowStepConfigLike, z as WorkflowStepContextLike, B as WorkflowStepRollbackOptionsLike } from "./packem_shared/types.d-CQO_koGe.js";
+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-C9W6rEWv.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-C9W6rEWv.js";
+import { LunoraError } from '@lunora/errors';
 import '@lunora/values';
 /** Wiring info for one declared workflow, emitted by codegen into the generated shard. */
 interface WorkflowBindingSpec {
@@ -131,6 +132,22 @@ declare const toNativeNonRetryableError: (error: NonRetryableError, NativeNonRet
 * Always throws — the `never` return lets callers `return convertNonRetryableError(...)`.
 */
 declare const convertNonRetryableError: (error: unknown, NativeNonRetryableError: NativeNonRetryableErrorConstructor | undefined) => never;
+/** Hard cap on branches per `ctx.parallel` call — auto-scale, never silently spawn unbounded DOs. */
+declare const MAX_BRANCHES = 100;
+/** The params key the parent injects so a child knows to signal completion back. Stripped before the user handler sees `ctx.params`. */
+
+/**
+* Build a single fan-out branch: a declared child workflow referenced by its
+* `lunora/workflows.ts` export name, plus the params it is created with. Pass the
+* output type as the generic argument so `ctx.parallel(...)` infers the result
+* tuple — e.g. `branch("imageTag", { key })` typed as `branch` of `{ tags }`.
+*/
+declare const branch: <Output = unknown>(workflow: string, params?: Record<string, unknown>, options?: {
+  compensateWith?: string;
+  id?: string;
+  timeout?: number | string;
+}) => WorkflowBranch<Output>;
+/** Build the success outcome a completed branch reports to its parent. */
 /** The lifecycle mutations the REST API exposes via `PATCH .../instances/{id}`. */
 type WorkflowInstanceAction = "pause" | "resume" | "terminate";
 /** Configuration for a {@link WorkflowsRestClient}. */
@@ -178,8 +195,7 @@ interface WorkflowInstancePage {
   totalCount?: number;
 }
 /** Thrown when the REST API responds non-2xx or `success: false`; carries the status plus body for the caller to surface. */
-declare class WorkflowsRestError extends Error {
-  readonly status: number;
+declare class WorkflowsRestError extends LunoraError {
   constructor(status: number, body: string);
 }
 /** The observe client: list instances, read one instance's steps, and (with Edit scope) mutate its status. */
@@ -209,24 +225,6 @@ interface WorkflowsRestClient {
 * snake_case payload into the camelCase shapes the studio renders.
 */
 declare const createWorkflowsRestClient: (config: WorkflowsRestConfig) => WorkflowsRestClient;
-interface RunnerOptions {
-  /** Worker `env` — read `LUNORA_ORIGIN_URL` + `LUNORA_ADMIN_TOKEN` at call time. */
-  env: Record<string, unknown>;
-  /** Injectable fetch (tests); defaults to the global. */
-  fetchImpl?: typeof fetch;
-}
-/**
-* Build a {@link WorkflowRunFunction} that invokes a Lunora function by POSTing
-* to the Worker's `/_lunora/scheduler/dispatch` endpoint — the same path the
-* SchedulerDO and the Queues workpool dispatch through — authenticated with the
-* admin bearer. The parsed JSON body (the function's return value) is resolved;
-* an empty/non-JSON body resolves to `undefined`.
-*
-* Wrap calls in `ctx.step.do(...)` to make them durable + memoized + retried.
-*/
-declare const createWorkflowRunner: (options: RunnerOptions) => WorkflowRunFunction;
-/** Console-backed logger, prefixed with the workflow name for log correlation. */
-declare const createWorkflowLogger: (exportName: string) => WorkflowLogger;
 interface RunContextOptions<Params> {
   env: Record<string, unknown>;
   event: WorkflowEventLike<Params>;
@@ -266,4 +264,4 @@ interface RunStepDeps {
 * converted to the native one and any declared rollback forwarded to Cloudflare.
 */
 declare const createRunStep: (deps: RunStepDeps) => WorkflowRunStepFunction;
-export { type LunoraWorkflowsOptions, type NativeNonRetryableErrorConstructor, NonRetryableError, type StepArgsValidator, type StepConfig, type StepDefinition, type WorkflowBindingSpec, 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, convertNonRetryableError, createRunStep, createWorkflowContext, createWorkflowLogger, createWorkflowRunContext, createWorkflowRunner, createWorkflows, createWorkflowsRestClient, defineStep, defineWorkflow, isNonRetryableError, isStepDefinition, isWorkflowDefinition, toNativeNonRetryableError, validateStepArgs, workflowBindingName, workflowClassName, workflowDefaultName };
+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 };

package/dist/index.mjs

@@ -1,8 +1,9 @@
-export { createWorkflowContext } from './packem_shared/createWorkflowContext-D6thzmlF.mjs';
-export { default as createWorkflows } from './packem_shared/createWorkflows-BoSYVIXg.mjs';
+export { createWorkflowContext } from './packem_shared/createWorkflowContext-oxZ5zj3x.mjs';
+export { default as createWorkflows } from './packem_shared/createWorkflows-wq4fs72q.mjs';
 export { defineStep, isStepDefinition } from './packem_shared/defineStep-DJQtLw7g.mjs';
 export { defineWorkflow, isWorkflowDefinition, workflowBindingName, workflowClassName, workflowDefaultName } from './packem_shared/defineWorkflow-DbUC-oCN.mjs';
-export { NonRetryableError, convertNonRetryableError, isNonRetryableError, toNativeNonRetryableError } from './packem_shared/convertNonRetryableError-Dn2dTyBS.mjs';
-export { WorkflowsRestError, createWorkflowsRestClient } from './packem_shared/WorkflowsRestError-b06i7K5j.mjs';
-export { createWorkflowLogger, createWorkflowRunContext, createWorkflowRunner } from './packem_shared/createWorkflowLogger-FktqxNLe.mjs';
-export { createRunStep, validateStepArgs } from './packem_shared/createRunStep-BsK4LsUX.mjs';
+export { NonRetryableError, convertNonRetryableError, isNonRetryableError, toNativeNonRetryableError } from './packem_shared/NonRetryableError-Dn2dTyBS.mjs';
+export { MAX_BRANCHES, branch } from './packem_shared/MAX_BRANCHES-EO5xYS_3.mjs';
+export { WorkflowsRestError, createWorkflowsRestClient } from './packem_shared/WorkflowsRestError-zmjOxTR1.mjs';
+export { createWorkflowRunContext } from './packem_shared/createWorkflowRunContext-D62MbkFK.mjs';
+export { createRunStep, validateStepArgs } from './packem_shared/createRunStep-8jOXxP2o.mjs';

package/dist/packem_shared/MAX_BRANCHES-EO5xYS_3.mjs

@@ -0,0 +1,170 @@
+import { LunoraError } from '@lunora/errors';
+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;
+    }
+    try {
+      const compensation = deps.resolveBinding(compensateWith);
+      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 compensation.create({ id: compensateId, params: compensationParams });
+        return compensateId;
+      });
+    } catch (compensationError) {
+      deps.log?.error(
+        `ctx.parallel: group-saga compensation "${compensateWith}" for branch "${done.plan.item.workflow}" (#${String(done.plan.index)}) failed`,
+        compensationError
+      );
+    }
+  }
+};
+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 };
+    });
+    const seenIds = /* @__PURE__ */ new Set();
+    for (const plan of planned) {
+      if (seenIds.has(plan.childId)) {
+        throw new NonRetryableError(
+          `ctx.parallel: duplicate branch id "${plan.childId}" — each branch in a group must resolve to a unique child instance id (check explicit \`id\` options)`
+        );
+      }
+      seenIds.add(plan.childId);
+    }
+    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) {
+      let outcome;
+      try {
+        const event = await deps.step.waitForEvent(`${AWAIT_STEP_PREFIX}${plan.childId}`, {
+          timeout: plan.item.timeout,
+          type: plan.eventType
+        });
+        outcome = event.payload;
+      } catch (joinError) {
+        const joinFailure = serializeError(joinError);
+        await compensateCompleted(deps, completed, joinFailure);
+        throw new NonRetryableError(`ctx.parallel: branch "${plan.item.workflow}" (#${String(plan.index)}) join failed: ${joinFailure.message}`);
+      }
+      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) => {
+  if (params !== void 0 && Object.hasOwn(params, BRANCH_MARKER_KEY)) {
+    throw new LunoraError("BAD_REQUEST", `@lunora/workflow: params may not contain the reserved key "${BRANCH_MARKER_KEY}"`);
+  }
+  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;
+  }
+  if (!candidate.parentBinding.startsWith("WORKFLOW_") || !candidate.eventType.startsWith(BRANCH_EVENT_PREFIX)) {
+    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;
+  });
+};
+const signalBranchParentSafe = async (deps, marker, outcome) => {
+  try {
+    await signalBranchParent(deps, marker, outcome);
+  } catch (signalError) {
+    deps.log?.error(`@lunora/workflow: failed to signal branch parent "${marker.parentId}" (event "${marker.eventType}")`, signalError);
+  }
+};
+
+export { BRANCH_MARKER_KEY, MAX_BRANCHES, branch, createParallel, createSpawn, errorOutcome, extractBranchMarker, okOutcome, signalBranchParent, signalBranchParentSafe, stripBranchMarker };

package/dist/packem_shared/{WorkflowsRestError-b06i7K5j.mjs → WorkflowsRestError-zmjOxTR1.mjs}

@@ -1,3 +1,5 @@
+import { LunoraError } from '@lunora/errors';
+
 const API_BASE = "https://api.cloudflare.com/client/v4/accounts";
 const KNOWN_STATUSES = {
   complete: true,
@@ -41,12 +43,9 @@ const toStep = (raw) => {
     type: asString(raw["type"])
   };
 };
-class WorkflowsRestError extends Error {
-  status;
+class WorkflowsRestError extends LunoraError {
   constructor(status, body) {
-    super(`Cloudflare Workflows REST API returned ${String(status)}: ${body}`);
-    this.name = "WorkflowsRestError";
-    this.status = status;
+    super("WORKFLOWS_REST_ERROR", `Cloudflare Workflows REST API returned ${String(status)}: ${body}`, { name: "WorkflowsRestError", status });
   }
 }
 const createWorkflowsRestClient = (config) => {

package/dist/packem_shared/{createRunStep-BsK4LsUX.mjs → createRunStep-8jOXxP2o.mjs}

@@ -1,5 +1,5 @@
 import { parseValidatorMap } from '@lunora/values';
-import { convertNonRetryableError, NonRetryableError } from './convertNonRetryableError-Dn2dTyBS.mjs';
+import { convertNonRetryableError, NonRetryableError } from './NonRetryableError-Dn2dTyBS.mjs';
 
 const validateStepArgs = (validators, source) => parseValidatorMap(validators, source, "step args");
 const createRunStep = (deps) => async (step, args, options) => {

package/dist/packem_shared/{createWorkflowContext-D6thzmlF.mjs → createWorkflowContext-oxZ5zj3x.mjs}

@@ -1,4 +1,4 @@
-import createWorkflows from './createWorkflows-BoSYVIXg.mjs';
+import createWorkflows from './createWorkflows-wq4fs72q.mjs';
 
 const createWorkflowContext = (env, specs) => {
   const bindings = {};

package/dist/packem_shared/createWorkflowRunContext-D62MbkFK.mjs

@@ -0,0 +1,134 @@
+import { LunoraError } from '@lunora/errors';
+import { workflowBindingName } from './defineWorkflow-DbUC-oCN.mjs';
+import { createSpawn, createParallel } from './MAX_BRANCHES-EO5xYS_3.mjs';
+import { createRunStep } from './createRunStep-8jOXxP2o.mjs';
+
+const createDispatchLogger = (prefix) => {
+  return {
+    debug: (message, ...rest) => {
+      console.debug(prefix, message, ...rest);
+    },
+    error: (message, ...rest) => {
+      console.error(prefix, message, ...rest);
+    },
+    info: (message, ...rest) => {
+      console.info(prefix, message, ...rest);
+    },
+    warn: (message, ...rest) => {
+      console.warn(prefix, message, ...rest);
+    }
+  };
+};
+
+const SCHEDULER_DISPATCH_PATH = "/_lunora/scheduler/dispatch";
+const trimTrailingSlashes = (value) => {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") {
+    end -= 1;
+  }
+  return value.slice(0, end);
+};
+const toDispatchError = (label, status, rawBody) => {
+  try {
+    const parsed = JSON.parse(rawBody);
+    const errorBody = parsed?.error;
+    if (typeof errorBody === "object" && errorBody !== null && typeof errorBody.code === "string") {
+      const { code, data, message } = errorBody;
+      return new LunoraError(code, typeof message === "string" ? message : void 0, { data, status });
+    }
+  } catch {
+  }
+  return new LunoraError("INTERNAL", `${label}: function dispatch failed (${String(status)}): ${rawBody}`, { status });
+};
+const createDispatchRunner = (options) => {
+  const { label } = options;
+  const globalFetch = globalThis.fetch;
+  const fetchImpl = options.fetchImpl ?? (typeof globalFetch === "function" ? globalFetch.bind(globalThis) : void 0);
+  return async (function_, args, runOptions = {}) => {
+    if (typeof fetchImpl !== "function") {
+      throw new TypeError(`${label}: no fetch implementation available — pass fetchImpl or run on a platform with global fetch`);
+    }
+    const origin = options.env.LUNORA_ORIGIN_URL;
+    if (typeof origin !== "string" || origin.length === 0) {
+      throw new LunoraError("INTERNAL", `${label}: \`LUNORA_ORIGIN_URL\` must be set on the Worker env so a handler can call back into Lunora functions`);
+    }
+    const token = options.env.LUNORA_ADMIN_TOKEN;
+    if (typeof token !== "string" || token.length === 0) {
+      throw new LunoraError("INTERNAL", `${label}: \`LUNORA_ADMIN_TOKEN\` must be set on the Worker env to authenticate function dispatch`);
+    }
+    const url = `${trimTrailingSlashes(origin)}${SCHEDULER_DISPATCH_PATH}`;
+    const headers = { authorization: `Bearer ${token}`, "content-type": "application/json" };
+    if (options.identity?.userId !== void 0) {
+      headers["x-lunora-userid"] = options.identity.userId;
+    }
+    if (options.identity?.claims !== void 0) {
+      headers["x-lunora-identity"] = JSON.stringify(options.identity.claims);
+    }
+    const response = await fetchImpl(url, {
+      body: JSON.stringify({ args: args ?? {}, functionPath: function_.__lunoraRef, shardKey: runOptions.shardKey }),
+      headers,
+      method: "POST"
+    });
+    if (!response.ok) {
+      throw toDispatchError(label, response.status, await response.text());
+    }
+    const text = await response.text();
+    if (text.length === 0) {
+      return void 0;
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new LunoraError("INTERNAL", `${label}: function dispatch returned a non-JSON body (${String(response.status)}): ${text}`, {
+        status: response.status
+      });
+    }
+  };
+};
+
+const createWorkflowRunContext = (options) => {
+  const log = createDispatchLogger(`[workflow:${options.exportName}]`);
+  const run = createDispatchRunner({ env: options.env, fetchImpl: options.fetchImpl, label: "@lunora/workflow" });
+  const resolveBinding = (workflow) => {
+    const bindingName = workflowBindingName(workflow);
+    const binding = options.env[bindingName];
+    if (!binding || typeof binding.create !== "function" || typeof binding.get !== "function") {
+      throw new LunoraError(
+        "INTERNAL",
+        `@lunora/workflow: cannot spawn child workflow "${workflow}" — no Workflow binding "${bindingName}" on env (is it declared in lunora/workflows.ts?)`
+      );
+    }
+    return binding;
+  };
+  let childCounter = 0;
+  const nextChildId = (explicit) => {
+    if (explicit !== void 0) {
+      return explicit;
+    }
+    const id = `${options.event.instanceId}-c${String(childCounter)}`;
+    childCounter += 1;
+    return id;
+  };
+  const fanOutDeps = {
+    env: options.env,
+    instanceId: options.event.instanceId,
+    log,
+    nextChildId,
+    parentBinding: workflowBindingName(options.exportName),
+    resolveBinding,
+    step: options.step
+  };
+  return {
+    env: options.env,
+    event: options.event,
+    log,
+    parallel: createParallel(fanOutDeps),
+    params: options.event.payload,
+    run,
+    runStep: createRunStep({ env: options.env, log, nonRetryableErrorClass: options.nonRetryableErrorClass, run, step: options.step }),
+    spawn: createSpawn(fanOutDeps),
+    step: options.step
+  };
+};
+
+export { createWorkflowRunContext };

package/dist/packem_shared/createWorkflows-wq4fs72q.mjs

@@ -0,0 +1,40 @@
+import { LunoraError } from '@lunora/errors';
+import { BRANCH_MARKER_KEY } from './MAX_BRANCHES-EO5xYS_3.mjs';
+
+const rejectReservedParams = (options) => {
+  const { params } = options ?? {};
+  if (params !== void 0 && Object.hasOwn(params, BRANCH_MARKER_KEY)) {
+    throw new LunoraError("BAD_REQUEST", `@lunora/workflow: params may not contain the reserved key "${BRANCH_MARKER_KEY}"`);
+  }
+};
+const handleFor = (binding) => {
+  return {
+    create: async (options) => {
+      rejectReservedParams(options);
+      return binding.create(options);
+    },
+    createBatch: async (batch) => {
+      for (const options of batch) {
+        rejectReservedParams(options);
+      }
+      return binding.createBatch(batch);
+    },
+    get: async (id) => binding.get(id)
+  };
+};
+const createWorkflows = (options) => {
+  const bindings = options.bindings ?? {};
+  return {
+    get: (name) => {
+      const binding = bindings[name];
+      if (binding === void 0) {
+        const known = Object.keys(bindings);
+        const suffix = known.length === 0 ? "no workflows are declared" : `known workflows: ${known.join(", ")}`;
+        throw new LunoraError("INTERNAL", `@lunora/workflow: no workflow named "${name}" (${suffix})`);
+      }
+      return handleFor(binding);
+    }
+  };
+};
+
+export { createWorkflows as default };