@nanobpm/workflow 0.2.0 → 0.3.0

package/README.md

@@ -31,7 +31,92 @@ Requires Node ≥ 20 and a reachable nanobpmn gateway (default `http://localhost
 
 Both compile to the same engine durability; pick per workflow.
 
-### Imperative (Temporal-style, engine-replayed)
+### Declarative (with control flow, human-in-the-loop signals, and typed I/O)
+
+**The recommended surface.** Describe the flow as a **tree of nodes**: `w.run` (a
+locally-hosted service task), `w.task` (an external-worker service task), and
+`w.signal` (a durable message catch that resumes via a correlated message — the
+human-in-the-loop path), composed with control-flow combinators:
+
+- `w.switch(subject, cases)` — a multi-way exclusive choice; each case key routes
+  when `subject = value`; an optional `default` case is the fallback.
+- `w.branch(condition, { then, else? })` — a two-way choice on a FEEL boolean.
+- `w.loop(body)` — a durable loop (back-edge to the loop head).
+- `w.break()` / `w.continue()` — exit the enclosing loop, or jump back to its head.
+
+```ts
+import { defineFlow, WorkflowClient, Worker } from "@nanobpm/workflow";
+
+const onboarding = defineFlow("onboarding", (w) => {
+  w.run("createAccount", async (job) => ({ userId: makeId() }));
+  w.signal("approved", { correlationKey: "userId" });
+  w.run("provision", async (job) => ({ ok: true }));
+});
+
+const client = new WorkflowClient({ baseUrl: "http://localhost:8080" });
+await client.deploy(onboarding);
+new Worker({ baseUrl: "http://localhost:8080", workflows: [onboarding] }).start();
+
+const { processInstanceKey } = await client.start(onboarding, {});
+// ... later, when a human approves:
+await client.signal(onboarding, "approved", userId, { by: "alice" });
+```
+
+A durable convergence loop (the shape `urban-pr-review` uses) — a loop wrapping a
+status switch with a nested guard:
+
+```ts
+const convergence = defineFlow("convergence-loop", (w) => {
+  w.loop((b) => {
+    b.run("review-round", async (job) => ({ status: classify(job.variables) }));
+    b.switch("status", {
+      converged: (c) => { c.run("persist-converged", finalize); c.break(); },
+      addressed: (c) => c.branch("round >= maxRounds", {
+        then: (g) => { g.run("persist-escalation", persist);
+                       g.signal("wait-answer", { correlationKey: "prKey" }); },
+        else: (g) => { g.run("persist-round", persist);   // returns { round: round + 1 }
+                       g.signal("wait-review", { correlationKey: "prKey" }); },
+      }),
+      default: (c) => { c.run("persist-blocked", persist);
+                        c.signal("wait-input", { correlationKey: "prKey" }); },
+    });
+  });
+});
+```
+
+Each combinator compiles to a BPMN primitive the engine already runs: `switch` /
+`branch` → an exclusive gateway (in-order conditions, first match wins, default =
+unconditional flow); `loop` → a convergent gateway whose body falls through back to
+the head; nodes with multiple incoming flows are an implicit XOR merge. See
+**ADR 0047**.
+
+#### Typed data envelopes (eject to model-first with contracts intact)
+
+Declare typed payload contracts in code with `envelope(name, fields)`, then pass a
+**contracts map keyed by step name** as `defineFlow`'s second argument. The step
+name auto-types the handler's `job.variables` (from `in`) and its return (from
+`out`), and the envelopes are **lifted into the emitted model** as `nano:shape` +
+`io.nanobpm.dataEnvelope.*` — the exact carrier the Fused Domain Model (ADR 0040)
+derives worker I/O from. So the generated `.bpmn` is ejectable to the modeller with
+its typed contracts intact — no cliff between code-first and model-first.
+
+```ts
+import { defineFlow, envelope } from "@nanobpm/workflow";
+
+const ChargeIn  = envelope("ChargeIn",  { orderId: "string", total: "number" });
+const ChargeOut = envelope("ChargeOut", { ok: "boolean" });
+
+const orders = defineFlow(
+  "orders",
+  { charge: { in: ChargeIn, out: ChargeOut } },
+  (w) => w.run("charge", async (job) => {
+    // job.variables is typed { orderId: string; total: number }
+    return { ok: await gateway.charge(job.variables) };  // typed ChargeOut
+  }),
+);
+```
+
+### Imperative (Temporal-style, engine-replayed) — experimental/internal
 
 Write the orchestration as a function. `ctx.run(name, fn)` is a durable step: its
 result is journalled in an engine process variable, so on resume a completed step
@@ -39,6 +124,10 @@ is **replayed from the journal** (its side effect is **not** re-run) and only th
 frontier step executes. The engine drives the function by re-invoking a single
 looped orchestrator job each turn.
 
+> This surface is **experimental/internal** — the declarative `defineFlow` above is
+> the one true code-first surface (ADR 0044 update, 2026-07-30). The replay
+> machinery is retained as the seed for a future code-block-in-a-node escape hatch.
+
 ```ts
 import { defineWorkflow, WorkflowClient, Worker } from "@nanobpm/workflow";
 
@@ -61,30 +150,6 @@ If the engine crashes after `review` commits and restarts cold, `fetchDiff` and
 `review` are **not** re-run — the workflow resumes at `merge`, which runs exactly
 once.
 
-### Declarative (with human-in-the-loop signals)
-
-Describe the flow as an ordered set of steps and signals. Each `w.run` is a
-service task (its own job type + handler); each `w.signal` parks the instance on a
-message-catch that resumes via a correlated message — the human-in-the-loop path.
-
-```ts
-import { defineFlow, WorkflowClient, Worker } from "@nanobpm/workflow";
-
-const onboarding = defineFlow("onboarding", (w) => {
-  w.run("createAccount", async (job) => ({ userId: makeId() }));
-  w.signal("approved", { correlationKey: "userId" });
-  w.run("provision", async (job) => ({ ok: true }));
-});
-
-const client = new WorkflowClient({ baseUrl: "http://localhost:8080" });
-await client.deploy(onboarding);
-new Worker({ baseUrl: "http://localhost:8080", workflows: [onboarding] }).start();
-
-const { processInstanceKey } = await client.start(onboarding, {});
-// ... later, when a human approves:
-await client.signal(onboarding, "approved", userId, { by: "alice" });
-```
-
 ## Honest scope
 
 - **Durability is the engine's**, via leader-durable replication (ADR 0003). On a
@@ -110,14 +175,17 @@ await client.signal(onboarding, "approved", userId, { by: "alice" });
 
 | Export | Purpose |
 | --- | --- |
-| `defineWorkflow(id, orchFn)` | Imperative (replayed) workflow. |
-| `defineFlow(id, build)` | Declarative flow with `w.run` / `w.signal`. |
+| `defineWorkflow(id, orchFn)` | Imperative (replayed) workflow — experimental/internal. |
+| `defineFlow(id, [contracts,] build)` | Declarative flow: `run`/`task`/`signal` + `switch`/`branch`/`loop`/`break`/`continue`, with an optional typed contracts map. |
+| `envelope(name, fields)` | A typed data envelope; lifted into the model as a `nano:shape` + `dataEnvelope` wiring. |
+| `externalJobTypes(flow)` | The derived job types of a flow's external `task` steps. |
 | `WorkflowClient` | `deploy`, `start`, `signal`, `getInstance` over REST v2. |
 | `Worker` | Generic job runtime; routes job types → handlers, hosts the replay loop. |
 | `toBpmn(workflow)` | The derived BPMN XML (for inspection / deployment). |
 
 See [ADR 0044](../docs/adr/0044-code-first-durable-orchestration.md) for the design
-rationale and the de-risking spike.
+rationale and [ADR 0047](../docs/adr/0047-declarative-flow-control-and-typed-envelopes.md)
+for the control-flow combinators and typed data envelopes.
 
 ## Development
 

package/dist/client.js

@@ -1,7 +1,7 @@
 // A thin, dependency-free client for a running nanobpmn gateway (REST v2):
 // deploy a workflow's derived model, start instances, correlate signals, and the
 // low-level job activate/complete/fail used by the Worker runtime.
-import { declarativeToBpmn } from "./declarative.js";
+import { declarativeToBpmn, walkNodes } from "./declarative.js";
 import { imperativeToBpmn } from "./imperative.js";
 import { assertWorkflowIds, messageName } from "./xml.js";
 /** Render a workflow (either surface) to its executable BPMN model. */
@@ -75,7 +75,13 @@ export class WorkflowClient {
      *  unknown signal name (a typo would otherwise send an uncorrelatable message
      *  that the gateway silently drops). */
     async signal(flow, signalName, correlationKey, variables = {}) {
-        const signals = flow.steps.filter((s) => s.kind === "signal").map((s) => s.name);
+        // Signal steps can live anywhere in the tree (inside switch/branch/loop),
+        // so walk the whole flow, not just the top-level sequence.
+        const signals = [];
+        walkNodes(flow.steps, (n) => {
+            if (n.kind === "signal")
+                signals.push(n.name);
+        });
         if (!signals.includes(signalName)) {
             throw new WorkflowError(`unknown signal "${signalName}" on flow "${flow.id}" — declared signals: ${signals.length ? signals.map((s) => `"${s}"`).join(", ") : "(none)"}`);
         }

package/dist/declarative.d.ts

@@ -1,30 +1,97 @@
-import type { DeclarativeFlow, StepHandler } from "./types.js";
-export interface FlowBuilder {
-    /** A durable activity served by a worker THIS program hosts (a BPMN service
-     *  task; the handler runs in the in-process `Worker`). */
-    run(name: string, handler: StepHandler): FlowBuilder;
+import type { DeclarativeFlow, FlowContracts, FlowNode, JsonObject } from "./types.js";
+import type { Envelope } from "./envelope.js";
+/** The TS payload type of a contract's input envelope (untyped fallback). */
+type InPayload<Ct> = Ct extends {
+    in: Envelope;
+} ? Ct["in"]["type"] : JsonObject;
+/** The TS payload type of a contract's output envelope (untyped fallback). */
+type OutPayload<Ct> = Ct extends {
+    out: Envelope;
+} ? Ct["out"]["type"] : JsonObject;
+/** The input payload type of step `K` under contracts `C`. */
+type VarsOf<C, K extends string> = K extends keyof C ? InPayload<C[K]> : JsonObject;
+/** The output payload type of step `K` under contracts `C`. */
+type ResultOf<C, K extends string> = K extends keyof C ? OutPayload<C[K]> : JsonObject;
+/** A typed handler for a `run` step: its job variables and result are resolved
+ *  from the flow contracts by the step name. */
+type TypedHandler<V, R> = (job: {
+    jobKey: string;
+    processInstanceKey: string;
+    elementId: string;
+    type: string;
+    variables: V;
+}) => Promise<R | void> | R | void;
+/** A block: the callback that populates a nested body (a case, arm, or loop). */
+type Block<C extends FlowContracts> = (b: FlowBuilder<C>) => void;
+export interface FlowBuilder<C extends FlowContracts = Record<string, never>> {
+    /**
+     * A durable activity served by a worker THIS program hosts (a BPMN service
+     * task; the handler runs in the in-process `Worker`). If `name` is a key in
+     * the flow's contracts, the handler's job variables and return value are typed
+     * from that contract's `in`/`out` envelopes; otherwise they are `JsonObject`.
+     */
+    run<K extends string>(name: K, handler: TypedHandler<VarsOf<C, K>, ResultOf<C, K>>): FlowBuilder<C>;
     /**
      * A durable activity served by a worker OUTSIDE this program (a BPMN service
-     * task with the same derived job type `${flowId}:${name}`, but no
-     * locally-hosted handler). The engine offers the job to whichever worker
-     * subscribes to that type — in another process, service, or language. Use
-     * `externalJobTypes(flow)` to list the contract those workers must poll.
+     * task with the derived job type `${flowId}:${name}`, but no locally-hosted
+     * handler). Use `externalJobTypes(flow)` to list the contract those workers
+     * must poll. Its contract envelopes (if any) type the model, not a local
+     * handler.
      */
-    task(name: string): FlowBuilder;
+    task<K extends string>(name: K): FlowBuilder<C>;
     /**
      * A durable wait for an external/human event, correlated on a process
      * variable (a BPMN message intermediate catch event). Resume it with
-     * `WorkflowClient.signal(flow, name, correlationKeyValue, vars)`.
+     * `WorkflowClient.signal(flow, name, correlationKeyValue, vars)`. The message
+     * payload envelope, if any, comes from the contract's `in`.
      */
-    signal(name: string, opts: {
+    signal<K extends string>(name: K, opts: {
         correlationKey: string;
-    }): FlowBuilder;
+    }): FlowBuilder<C>;
+    /**
+     * A multi-way exclusive choice (a BPMN exclusive gateway). `subject` is a FEEL
+     * expression (usually a variable name); each case routes when `subject` equals
+     * the case value. An optional `default` case is the unconditional fallback.
+     */
+    switch(subject: string, cases: Record<string, Block<C>> & {
+        default?: Block<C>;
+    }): FlowBuilder<C>;
+    /**
+     * A two-way exclusive choice on a FEEL boolean `condition` (a BPMN exclusive
+     * gateway). The `then` branch is guarded by the condition; the `else` branch
+     * (the gateway default) runs otherwise. Omitting `else` skips to whatever
+     * follows the branch when the condition is false.
+     */
+    branch(condition: string, arms: {
+        then: Block<C>;
+        else?: Block<C>;
+    }): FlowBuilder<C>;
+    /**
+     * A durable loop (a back-edge to the loop head). The body runs, then control
+     * returns to the top of the loop unless a branch calls `break()`. Nodes after
+     * the loop run once `break()` is reached.
+     */
+    loop(body: Block<C>): FlowBuilder<C>;
+    /** Exit the enclosing loop (routes to whatever follows it). Only valid inside
+     *  a `loop`. */
+    break(): FlowBuilder<C>;
+    /** Jump straight back to the top of the enclosing loop, skipping the rest of
+     *  the body. Only valid inside a `loop`. */
+    continue(): FlowBuilder<C>;
 }
-/** Define a declarative flow. `build(w)` declares an ordered list of steps. */
+/**
+ * Define a declarative flow. Pass a typed `contracts` map (keyed by step name)
+ * to type each step's I/O and lift its data envelopes into the model; or omit it
+ * for an untyped flow. `build(w)` declares a tree of nodes.
+ */
+export declare function defineFlow<C extends FlowContracts>(id: string, contracts: C, build: (w: FlowBuilder<C>) => void): DeclarativeFlow;
 export declare function defineFlow(id: string, build: (w: FlowBuilder) => void): DeclarativeFlow;
-/** The derived job types of a flow's external `task` steps — the contract that
- *  workers outside this program must subscribe to (the engine offers those jobs
- *  to whoever polls the type). Empty when the flow hosts all its own steps. */
+/** Depth-first visit of every node in a flow tree (structural combinators
+ *  recurse into their bodies). */
+export declare function walkNodes(nodes: FlowNode[], visit: (n: FlowNode) => void): void;
+/** The derived job types of a flow's external `task` steps (anywhere in the
+ *  tree) — the contract workers outside this program must subscribe to. */
 export declare function externalJobTypes(flow: DeclarativeFlow): string[];
 /** Derive an executable BPMN model from a declarative flow. */
 export declare function declarativeToBpmn(flow: DeclarativeFlow): string;
+export {};