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

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-gNYxuUwu.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-gNYxuUwu.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/NonRetryableError-Dn2dTyBS.mjs';
-import { createWorkflowRunContext } from '../packem_shared/createWorkflowRunContext-DJj_y0fa.mjs';
+import { stripBranchMarker, signalBranchParent, extractBranchMarker, errorOutcome, okOutcome } from '../packem_shared/MAX_BRANCHES-D6cQabJ1.mjs';
+import { createWorkflowRunContext } from '../packem_shared/createWorkflowRunContext-CYI9SeI9.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 signalBranchParent({ env: this.env, step: nativeStep }, marker, errorOutcome(error));
+      }
       return convertNonRetryableError(error, NonRetryableError);
     }
+    if (marker) {
+      await signalBranchParent({ env: this.env, step: nativeStep }, marker, okOutcome(output));
+    }
+    return output;
   }
 }
 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-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 WorkflowEventLike, g as WorkflowStepLike, h as WorkflowRunContext, i as WorkflowLogger, j as WorkflowRunFunction, k as WorkflowRunStepFunction } from "./packem_shared/types.d-gNYxuUwu.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-gNYxuUwu.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 '@lunora/values';
 /** Wiring info for one declared workflow, emitted by codegen into the generated shard. */
 interface WorkflowBindingSpec {
@@ -131,6 +131,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}. */
@@ -248,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, createWorkflowRunContext, 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,5 @@
-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 WorkflowEventLike, g as WorkflowStepLike, h as WorkflowRunContext, i as WorkflowLogger, j as WorkflowRunFunction, k as WorkflowRunStepFunction } from "./packem_shared/types.d-gNYxuUwu.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-gNYxuUwu.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 '@lunora/values';
 /** Wiring info for one declared workflow, emitted by codegen into the generated shard. */
 interface WorkflowBindingSpec {
@@ -131,6 +131,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}. */
@@ -248,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, createWorkflowRunContext, 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

@@ -3,6 +3,7 @@ export { default as createWorkflows } from './packem_shared/createWorkflows-BoSY
 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/NonRetryableError-Dn2dTyBS.mjs';
+export { MAX_BRANCHES, branch } from './packem_shared/MAX_BRANCHES-D6cQabJ1.mjs';
 export { WorkflowsRestError, createWorkflowsRestClient } from './packem_shared/WorkflowsRestError-b06i7K5j.mjs';
-export { createWorkflowRunContext } from './packem_shared/createWorkflowRunContext-DJj_y0fa.mjs';
+export { createWorkflowRunContext } from './packem_shared/createWorkflowRunContext-CYI9SeI9.mjs';
 export { createRunStep, validateStepArgs } from './packem_shared/createRunStep-8jOXxP2o.mjs';

package/dist/packem_shared/MAX_BRANCHES-D6cQabJ1.mjs

@@ -0,0 +1,132 @@
+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 };

package/dist/packem_shared/{createWorkflowRunContext-DJj_y0fa.mjs → createWorkflowRunContext-CYI9SeI9.mjs}

@@ -1,3 +1,5 @@
+import { workflowBindingName } from './defineWorkflow-DbUC-oCN.mjs';
+import { createSpawn, createParallel } from './MAX_BRANCHES-D6cQabJ1.mjs';
 import { createRunStep } from './createRunStep-8jOXxP2o.mjs';
 
 const createDispatchLogger = (prefix) => {
@@ -65,13 +67,42 @@ const createDispatchRunner = (options) => {
 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 Error(
+        `@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,
+    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
   };
 };

package/dist/packem_shared/{types.d-gNYxuUwu.d.mts → types.d-C9W6rEWv.d.mts}

@@ -264,9 +264,86 @@ interface RunStepOptions {
 */
 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.
+*/
+interface WorkflowBranch<Output = unknown> {
+  /** Phantom marker for the branch output type — never present at runtime. */
+  readonly __output?: Output;
+  /**
+  * Optional group-saga compensation (plan 075 Phase 3): the `lunora/workflows.ts`
+  * export name of a workflow to run if a **sibling** branch in the same
+  * `ctx.parallel(...)` group fails **after** this branch has already completed.
+  * It is spawned fire-and-forget (a durable, replay-safe idempotent create) with
+  * {@link BranchCompensationParams} as its `ctx.params`. Omit for no
+  * compensation — a group where no branch sets this behaves exactly as a plain
+  * fan-out (fail-fast, no rollback).
+  */
+  readonly compensateWith?: string;
+  /** Optional explicit child instance id (defaults to a deterministic parent-derived id). */
+  readonly id?: string;
+  /** The params the child instance is created with — surfaced as the child's `ctx.params`. */
+  readonly params?: Record<string, unknown>;
+  /** Optional wait timeout for this branch (the parent's `waitForEvent` timeout). */
+  readonly timeout?: number | string;
+  /** The `lunora/workflows.ts` export name of the child workflow to run. */
+  readonly workflow: string;
+}
+/**
+* The `ctx.params` a group-saga compensation workflow (a branch's
+* {@link WorkflowBranch.compensateWith}) receives when a sibling's failure rolls
+* back the group. Everything is plain-serialisable — the compensation is an
+* ordinary declared workflow, so it can `ctx.runStep(...)` its own undo logic.
+*/
+interface BranchCompensationParams {
+  /** Index signature: this is a workflow `params` bag, so it is a valid `Record&lt;string, unknown>` payload. */
+  [key: string]: unknown;
+  /** The export name of the completed branch being compensated. */
+  branch: string;
+  /** The serialised error of the sibling branch whose failure triggered the group rollback. */
+  error: {
+    message: string;
+    name: string;
+  };
+  /** Declaration-order index of the completed branch being compensated. */
+  index: number;
+  /** The completed branch's output value — what it returned before the group failed. */
+  output?: unknown;
+}
+/** Map a tuple of {@link WorkflowBranch}es to the tuple of their output types, preserving order. */
+type WorkflowBranchOutputs<B extends ReadonlyArray<WorkflowBranch>> = { -readonly [K in keyof B]: B[K] extends WorkflowBranch<infer Output> ? Output : never };
+/**
+* Run branches as isolated child workflow instances and resolve with their
+* outputs in declaration order. Each branch gets its own Durable Object (own
+* memory / CPU / retry budget); the parent hibernates while they execute. Rejects
+* (non-retryable) on the first branch that fails.
+*
+* ```ts
+* const [tags, thumb] = await ctx.parallel([
+*     branch("imageTag", { key }),
+*     branch("thumbnail", { key }),
+* ]);
+* ```
+*/
+type WorkflowParallelFunction = <const B extends ReadonlyArray<WorkflowBranch>>(branches: B) => Promise<WorkflowBranchOutputs<B>>;
+/** Per-call options for {@link WorkflowSpawnFunction}. */
+interface WorkflowSpawnOptions {
+  /** Explicit child instance id (defaults to a deterministic parent-derived id). */
+  id?: string;
+}
+/**
+* Fire-and-forget start of a declared child workflow from inside a workflow body
+* — replay-safe (idempotent create), returns a live handle to the child. Use
+* {@link WorkflowParallelFunction} instead when you need to await results.
+*/
+type WorkflowSpawnFunction = (workflow: string, params?: Record<string, unknown>, options?: WorkflowSpawnOptions) => Promise<WorkflowInstanceLike>;
+/**
 * The context object passed to a `defineWorkflow` handler. Bundles the native
 * Cloudflare durability primitives (`step`, `event`) with the Lunora runner
-* (`run`), the reusable-step runner (`runStep`), the Worker `env`, and a logger.
+* (`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. */
@@ -275,12 +352,16 @@ interface WorkflowRunContext<Params = Record<string, unknown>> {
   readonly event: WorkflowEventLike<Params>;
   /** Structured logger surfaced in `wrangler tail` / Studio logs. */
   readonly log: WorkflowLogger;
+  /** Run branches as isolated child workflow instances and await their outputs (declaration-ordered tuple). */
+  readonly parallel: WorkflowParallelFunction;
   /** Convenience alias for `event.payload`. */
   readonly params: Readonly<Params>;
   /** Invoke a Lunora function; wrap in `step.do(...)` for durability. */
   readonly run: WorkflowRunFunction;
   /** Run a reusable, schema-validated {@link StepDefinition} as a durable step. */
   readonly runStep: WorkflowRunStepFunction;
+  /** Fire-and-forget start of a declared child workflow (replay-safe; returns a live handle). */
+  readonly spawn: WorkflowSpawnFunction;
   /** The native Cloudflare Workflows durable-step API. */
   readonly step: WorkflowStepLike;
 }
@@ -341,4 +422,4 @@ interface LunoraWorkflowsOptions {
   */
   bindings: Record<string, WorkflowBindingLike>;
 }
-export { ArgsOf as A, WorkflowStepRollbackOptionsLike as B, FunctionReference as F, InferStepArgs as I, LunoraWorkflowsOptions as L, RunFunctionOptions as R, StepArgsValidator as S, WorkflowDefinition as W, Workflows as a, StepConfig as b, StepDefinition as c, WorkflowConfig as d, WorkflowInstanceStatus as e, WorkflowEventLike as f, WorkflowStepLike as g, WorkflowRunContext as h, WorkflowLogger as i, WorkflowRunFunction as j, WorkflowRunStepFunction as k, RunStepOptions as l, StepHandler as m, StepRollbackContext as n, StepRollbackHandler as o, StepRunContext as p, WorkflowBindingLike as q, WorkflowCreateOptions as r, WorkflowHandle as s, WorkflowHandler as t, WorkflowInstanceLike as u, WorkflowRollbackContextLike as v, WorkflowRollbackHandlerLike as w, WorkflowStatusResult as x, WorkflowStepConfigLike as y, WorkflowStepContextLike as z };
+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 };

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

@@ -264,9 +264,86 @@ interface RunStepOptions {
 */
 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.
+*/
+interface WorkflowBranch<Output = unknown> {
+  /** Phantom marker for the branch output type — never present at runtime. */
+  readonly __output?: Output;
+  /**
+  * Optional group-saga compensation (plan 075 Phase 3): the `lunora/workflows.ts`
+  * export name of a workflow to run if a **sibling** branch in the same
+  * `ctx.parallel(...)` group fails **after** this branch has already completed.
+  * It is spawned fire-and-forget (a durable, replay-safe idempotent create) with
+  * {@link BranchCompensationParams} as its `ctx.params`. Omit for no
+  * compensation — a group where no branch sets this behaves exactly as a plain
+  * fan-out (fail-fast, no rollback).
+  */
+  readonly compensateWith?: string;
+  /** Optional explicit child instance id (defaults to a deterministic parent-derived id). */
+  readonly id?: string;
+  /** The params the child instance is created with — surfaced as the child's `ctx.params`. */
+  readonly params?: Record<string, unknown>;
+  /** Optional wait timeout for this branch (the parent's `waitForEvent` timeout). */
+  readonly timeout?: number | string;
+  /** The `lunora/workflows.ts` export name of the child workflow to run. */
+  readonly workflow: string;
+}
+/**
+* The `ctx.params` a group-saga compensation workflow (a branch's
+* {@link WorkflowBranch.compensateWith}) receives when a sibling's failure rolls
+* back the group. Everything is plain-serialisable — the compensation is an
+* ordinary declared workflow, so it can `ctx.runStep(...)` its own undo logic.
+*/
+interface BranchCompensationParams {
+  /** Index signature: this is a workflow `params` bag, so it is a valid `Record&lt;string, unknown>` payload. */
+  [key: string]: unknown;
+  /** The export name of the completed branch being compensated. */
+  branch: string;
+  /** The serialised error of the sibling branch whose failure triggered the group rollback. */
+  error: {
+    message: string;
+    name: string;
+  };
+  /** Declaration-order index of the completed branch being compensated. */
+  index: number;
+  /** The completed branch's output value — what it returned before the group failed. */
+  output?: unknown;
+}
+/** Map a tuple of {@link WorkflowBranch}es to the tuple of their output types, preserving order. */
+type WorkflowBranchOutputs<B extends ReadonlyArray<WorkflowBranch>> = { -readonly [K in keyof B]: B[K] extends WorkflowBranch<infer Output> ? Output : never };
+/**
+* Run branches as isolated child workflow instances and resolve with their
+* outputs in declaration order. Each branch gets its own Durable Object (own
+* memory / CPU / retry budget); the parent hibernates while they execute. Rejects
+* (non-retryable) on the first branch that fails.
+*
+* ```ts
+* const [tags, thumb] = await ctx.parallel([
+*     branch("imageTag", { key }),
+*     branch("thumbnail", { key }),
+* ]);
+* ```
+*/
+type WorkflowParallelFunction = <const B extends ReadonlyArray<WorkflowBranch>>(branches: B) => Promise<WorkflowBranchOutputs<B>>;
+/** Per-call options for {@link WorkflowSpawnFunction}. */
+interface WorkflowSpawnOptions {
+  /** Explicit child instance id (defaults to a deterministic parent-derived id). */
+  id?: string;
+}
+/**
+* Fire-and-forget start of a declared child workflow from inside a workflow body
+* — replay-safe (idempotent create), returns a live handle to the child. Use
+* {@link WorkflowParallelFunction} instead when you need to await results.
+*/
+type WorkflowSpawnFunction = (workflow: string, params?: Record<string, unknown>, options?: WorkflowSpawnOptions) => Promise<WorkflowInstanceLike>;
+/**
 * The context object passed to a `defineWorkflow` handler. Bundles the native
 * Cloudflare durability primitives (`step`, `event`) with the Lunora runner
-* (`run`), the reusable-step runner (`runStep`), the Worker `env`, and a logger.
+* (`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. */
@@ -275,12 +352,16 @@ interface WorkflowRunContext<Params = Record<string, unknown>> {
   readonly event: WorkflowEventLike<Params>;
   /** Structured logger surfaced in `wrangler tail` / Studio logs. */
   readonly log: WorkflowLogger;
+  /** Run branches as isolated child workflow instances and await their outputs (declaration-ordered tuple). */
+  readonly parallel: WorkflowParallelFunction;
   /** Convenience alias for `event.payload`. */
   readonly params: Readonly<Params>;
   /** Invoke a Lunora function; wrap in `step.do(...)` for durability. */
   readonly run: WorkflowRunFunction;
   /** Run a reusable, schema-validated {@link StepDefinition} as a durable step. */
   readonly runStep: WorkflowRunStepFunction;
+  /** Fire-and-forget start of a declared child workflow (replay-safe; returns a live handle). */
+  readonly spawn: WorkflowSpawnFunction;
   /** The native Cloudflare Workflows durable-step API. */
   readonly step: WorkflowStepLike;
 }
@@ -341,4 +422,4 @@ interface LunoraWorkflowsOptions {
   */
   bindings: Record<string, WorkflowBindingLike>;
 }
-export { ArgsOf as A, WorkflowStepRollbackOptionsLike as B, FunctionReference as F, InferStepArgs as I, LunoraWorkflowsOptions as L, RunFunctionOptions as R, StepArgsValidator as S, WorkflowDefinition as W, Workflows as a, StepConfig as b, StepDefinition as c, WorkflowConfig as d, WorkflowInstanceStatus as e, WorkflowEventLike as f, WorkflowStepLike as g, WorkflowRunContext as h, WorkflowLogger as i, WorkflowRunFunction as j, WorkflowRunStepFunction as k, RunStepOptions as l, StepHandler as m, StepRollbackContext as n, StepRollbackHandler as o, StepRunContext as p, WorkflowBindingLike as q, WorkflowCreateOptions as r, WorkflowHandle as s, WorkflowHandler as t, WorkflowInstanceLike as u, WorkflowRollbackContextLike as v, WorkflowRollbackHandlerLike as w, WorkflowStatusResult as x, WorkflowStepConfigLike as y, WorkflowStepContextLike as z };
+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 };

package/package.json

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