@nanobpm/workflow 0.2.0 → 0.4.0

package/dist/envelope.js

@@ -0,0 +1,62 @@
+// Typed data envelopes — the code-first expression of a nano:shape.
+//
+// An envelope declares a named, typed payload contract IN CODE. It carries two
+// things at once:
+//   - a runtime schema (ordered fields + scalar types), which the model emitter
+//     LIFTS into the BPMN as a `nano:shape` (under `nano:shapes` on the process)
+//     plus the `io.nanobpm.dataEnvelope.in/out` `zeebe:property` on the service
+//     task / message — exactly the carrier the console derives worker I/O from
+//     (server/src/console/envelope_scan.rs); and
+//   - a phantom TypeScript type, inferred from the field spec, so `run`/`task`
+//     handlers and message payloads are statically typed at the call site.
+//
+// This is what makes code-first EJECTABLE to model-first: the generated `.bpmn`
+// already carries the typed shapes + envelope wiring the modeller and the Fused
+// Domain Model (ADR 0040) expect, so opening it in the Modeller loses nothing.
+//
+//   const PrReviewRoundIn = envelope("PrReviewRoundIn", {
+//     prUrl: "string", repo: "string", prNumber: "integer",
+//     prompt: "string", round: "integer",
+//     answer: { type: "string", optional: true },
+//   });
+//   // PrReviewRoundIn.type  ≅  { prUrl: string; repo: string; prNumber: number;
+//   //                            prompt: string; round: number; answer?: string }
+import { assertIdent } from "./xml.js";
+const SCALARS = new Set([
+    "string",
+    "integer",
+    "number",
+    "boolean",
+    "datetime",
+]);
+function normaliseField(name, spec) {
+    if (spec === null || (typeof spec !== "string" && typeof spec !== "object")) {
+        throw new Error(`envelope field "${name}": must be a scalar type or a { type, optional?, list? } object`);
+    }
+    const raw = typeof spec === "string" ? { type: spec } : spec;
+    if (!SCALARS.has(raw.type)) {
+        throw new Error(`envelope field "${name}": unknown type "${raw.type}" (expected one of ${[...SCALARS].join(", ")})`);
+    }
+    return {
+        name,
+        type: raw.type,
+        optional: typeof spec === "object" && spec.optional === true,
+        list: typeof spec === "object" && spec.list === true,
+    };
+}
+/**
+ * Declare a typed data envelope. `name` becomes the `nano:shape` id lifted into
+ * the model (must be a valid BPMN identifier); `fields` declares the payload.
+ * The returned envelope's `type` phantom carries the inferred TS payload type.
+ */
+export function envelope(name, fields) {
+    assertIdent("envelope name", name);
+    const list = Object.entries(fields).map(([k, v]) => normaliseField(k, v));
+    if (list.length === 0)
+        throw new Error(`envelope "${name}" declares no fields`);
+    for (const f of list)
+        assertIdent("envelope field name", f.name);
+    // `type` is phantom: never read at runtime; the cast keeps the value shape
+    // minimal while the declared type carries the inference.
+    return { name, fields: list, type: undefined };
+}

package/dist/index.d.ts

@@ -1,9 +1,12 @@
 export { defineWorkflow, imperativeToBpmn, replayOnce } from "./imperative.js";
 export type { Journal, ReplayStep } from "./imperative.js";
-export { defineFlow, declarativeToBpmn, externalJobTypes } from "./declarative.js";
+export { defineFlow, declarativeToBpmn, externalJobTypes, walkNodes } from "./declarative.js";
 export type { FlowBuilder } from "./declarative.js";
+export { layoutBpmn, declarativeToLayoutedBpmn } from "./layout.js";
+export { envelope } from "./envelope.js";
+export type { Envelope, EnvelopeType, EnvelopeField, FieldSpec, ScalarType, ScalarTs, FieldTs, } from "./envelope.js";
 export { WorkflowClient, WorkflowError, toBpmn } from "./client.js";
 export type { WorkflowClientOptions, ActivateOptions } from "./client.js";
 export { Worker } from "./worker.js";
 export type { WorkerOptions, ActivityEvent } from "./worker.js";
-export type { Json, JsonObject, Job, StepHandler, DeclarativeFlow, DeclarativeStep, ImperativeWorkflow, Orchestration, WorkflowContext, Workflow, DeployResult, StartResult, } from "./types.js";
+export type { Json, JsonObject, Job, StepHandler, DeclarativeFlow, DeclarativeStep, FlowNode, SwitchCase, NodeEnvelopes, StepContract, FlowContracts, ImperativeWorkflow, Orchestration, WorkflowContext, Workflow, DeployResult, StartResult, } from "./types.js";

package/dist/index.js

@@ -39,6 +39,8 @@
 // code-first surface (steps are not engine-visible; requires determinism
 // discipline). Retained for advanced durable-orchestration use only.
 export { defineWorkflow, imperativeToBpmn, replayOnce } from "./imperative.js";
-export { defineFlow, declarativeToBpmn, externalJobTypes } from "./declarative.js";
+export { defineFlow, declarativeToBpmn, externalJobTypes, walkNodes } from "./declarative.js";
+export { layoutBpmn, declarativeToLayoutedBpmn } from "./layout.js";
+export { envelope } from "./envelope.js";
 export { WorkflowClient, WorkflowError, toBpmn } from "./client.js";
 export { Worker } from "./worker.js";

package/dist/layout.d.ts

@@ -0,0 +1,22 @@
+import type { DeclarativeFlow } from "./types.js";
+/**
+ * Generate BPMN diagram interchange (DI) for a BPMN XML string using bpmn-io's
+ * `bpmn-auto-layout`, returning the same model with an auto-laid-out diagram
+ * (`bpmndi:BPMNDiagram`). Works on DI-less *or* already-laid-out input, and
+ * preserves `zeebe:` extension elements (task definitions, message
+ * subscriptions) through the round-trip.
+ *
+ * Requires the optional peer dependency `bpmn-auto-layout` to be installed; a
+ * clear error is thrown if it is missing.
+ */
+export declare function layoutBpmn(bpmnXml: string): Promise<string>;
+/**
+ * Derive an executable BPMN model from a declarative flow AND auto-generate its
+ * diagram (DI), so the model opens rendered in a modeller/viewer. Convenience
+ * over `layoutBpmn(declarativeToBpmn(flow))`; async because layout is async. The
+ * semantic model stays authoritative — see `declarativeToBpmn` for the DI-less
+ * model the engine actually runs.
+ *
+ * Requires the optional peer dependency `bpmn-auto-layout` to be installed.
+ */
+export declare function declarativeToLayoutedBpmn(flow: DeclarativeFlow): Promise<string>;

package/dist/layout.js

@@ -0,0 +1,62 @@
+// Optional diagram-interchange (DI) generation for the code-first surfaces.
+//
+// The authoring surfaces emit *semantic* BPMN — process, flow nodes, sequence
+// flows, messages — with no `bpmndi:` diagram: the engine runs the semantic model
+// and DI is an authoring-time concern only (a derived flow has no diagram of its
+// own). This module layers bpmn-io's `bpmn-auto-layout` on top so a derived model
+// opens with a rendered, auto-laid-out diagram in a modeller/viewer, which makes
+// code-first flows visually inspectable, reviewable, and round-trippable.
+//
+// `bpmn-auto-layout` is an *optional peer dependency*: the runtime client stays
+// dependency-free and the layout engine is loaded lazily, only when you ask for a
+// diagram. Install it alongside this package (`npm i bpmn-auto-layout`) to use
+// these helpers.
+//
+// DI is best-effort and *regenerable* — the semantic model (`declarativeToBpmn`)
+// stays authoritative. Re-run layout whenever the flow changes rather than
+// hand-editing the generated diagram.
+import { declarativeToBpmn } from "./declarative.js";
+/**
+ * Generate BPMN diagram interchange (DI) for a BPMN XML string using bpmn-io's
+ * `bpmn-auto-layout`, returning the same model with an auto-laid-out diagram
+ * (`bpmndi:BPMNDiagram`). Works on DI-less *or* already-laid-out input, and
+ * preserves `zeebe:` extension elements (task definitions, message
+ * subscriptions) through the round-trip.
+ *
+ * Requires the optional peer dependency `bpmn-auto-layout` to be installed; a
+ * clear error is thrown if it is missing.
+ */
+export async function layoutBpmn(bpmnXml) {
+    let layoutProcess;
+    try {
+        ({ layoutProcess } = await import("bpmn-auto-layout"));
+    }
+    catch (cause) {
+        // Only substitute the friendly "not installed" message when the module
+        // genuinely cannot be resolved. A different failure (the package is present
+        // but fails to load — syntax, a broken transitive dep, a runtime throw at
+        // import time) must surface as-is so it isn't masked as a missing dependency.
+        if (cause?.code !== "ERR_MODULE_NOT_FOUND") {
+            throw cause;
+        }
+        throw new Error('layoutBpmn requires the optional peer dependency "bpmn-auto-layout". ' +
+            "Install it to generate diagram layout: npm i bpmn-auto-layout", { cause });
+    }
+    const result = await layoutProcess(bpmnXml);
+    // Version-shape normalization: bpmn-auto-layout 2.x (and >= 1.4) resolves to
+    // `{ xml, warnings }`; 1.3.x resolved to the laid-out XML string directly. We
+    // pin >= 2.0.0-alpha.2 but normalize both so the SDK tolerates the whole range.
+    return typeof result === "string" ? result : result.xml;
+}
+/**
+ * Derive an executable BPMN model from a declarative flow AND auto-generate its
+ * diagram (DI), so the model opens rendered in a modeller/viewer. Convenience
+ * over `layoutBpmn(declarativeToBpmn(flow))`; async because layout is async. The
+ * semantic model stays authoritative — see `declarativeToBpmn` for the DI-less
+ * model the engine actually runs.
+ *
+ * Requires the optional peer dependency `bpmn-auto-layout` to be installed.
+ */
+export function declarativeToLayoutedBpmn(flow) {
+    return layoutBpmn(declarativeToBpmn(flow));
+}

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { Envelope } from "./envelope.js";
 /** A JSON-serialisable value, as carried by process variables. */
 export type Json = null | boolean | number | string | Json[] | {
     [k: string]: Json;
@@ -5,31 +6,83 @@ export type Json = null | boolean | number | string | Json[] | {
 export type JsonObject = {
     [k: string]: Json;
 };
-/** A job as delivered by the nanobpmn gateway's `POST /v2/jobs/activation`. */
-export interface Job {
+/** A job as delivered by the nanobpmn gateway's `POST /v2/jobs/activation`. The
+ *  `variables` type parameter carries the input envelope's inferred payload when
+ *  a step is declared with a typed envelope; it defaults to the untyped
+ *  `JsonObject`. */
+export interface Job<V extends JsonObject = JsonObject> {
     jobKey: string;
     processInstanceKey: string;
     elementId: string;
     type: string;
-    variables: JsonObject;
+    variables: V;
 }
+/** The input/output data envelopes lifted onto an activity node. */
+export interface NodeEnvelopes {
+    in?: Envelope;
+    out?: Envelope;
+}
+/** A typed I/O contract for one step: its input and/or output data envelope.
+ *  For a `signal`, `in` types the message payload. */
+export interface StepContract {
+    in?: Envelope;
+    out?: Envelope;
+}
+/** A flow's typed I/O registry, keyed by step name — the single source of truth
+ *  for each step's envelopes. Passed to `defineFlow`; a step whose name is a key
+ *  is typed (and its envelopes lifted to the model), others fall back to the
+ *  untyped `JsonObject`. */
+export type FlowContracts = Record<string, StepContract>;
 /** Handler for a declarative `run` step: does real work, returns variables. */
 export type StepHandler = (job: Job) => Promise<JsonObject | void> | JsonObject | void;
-export type DeclarativeStep = {
+/** A node in a declarative flow tree. Leaf activities carry optional data
+ *  envelopes (lifted to `nano:shape` + `dataEnvelope` in the model); structural
+ *  combinators carry nested `FlowNode[]` bodies. */
+export type FlowNode = {
     kind: "run";
     name: string;
+    envelopes?: NodeEnvelopes;
 } | {
     kind: "task";
     name: string;
+    envelopes?: NodeEnvelopes;
+    jobType?: string;
 } | {
     kind: "signal";
     name: string;
     correlationKey: string;
+    payload?: Envelope;
+} | {
+    kind: "switch";
+    subject: string;
+    cases: SwitchCase[];
+    default?: FlowNode[];
+} | {
+    kind: "branch";
+    condition: string;
+    then: FlowNode[];
+    else?: FlowNode[];
+} | {
+    kind: "loop";
+    body: FlowNode[];
+} | {
+    kind: "break";
+} | {
+    kind: "continue";
 };
+/** One case of a `switch`: routed when `subject = value` (FEEL equality). */
+export interface SwitchCase {
+    value: string;
+    body: FlowNode[];
+}
+/** @deprecated Renamed to {@link FlowNode} now that a flow is a tree of nodes,
+ *  not a flat list of steps. Kept as an alias for source compatibility. */
+export type DeclarativeStep = FlowNode;
 export interface DeclarativeFlow {
     kind: "declarative";
     id: string;
-    steps: DeclarativeStep[];
+    /** The flow's node tree (top-level sequence). */
+    steps: FlowNode[];
     handlers: Record<string, StepHandler>;
 }
 /** The context passed to an imperative orchestration function. */

package/dist/worker.js

@@ -13,6 +13,7 @@
 // the ADR 0044 spike proved.
 import { WorkflowClient } from "./client.js";
 import { replayOnce } from "./imperative.js";
+import { walkNodes } from "./declarative.js";
 import { jobType } from "./xml.js";
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 export class Worker {
@@ -54,11 +55,13 @@ export class Worker {
             });
         }
         else {
-            for (const s of wf.steps) {
-                // Only `run` steps are hosted locally; `signal` (message catch) and
-                // `task` (external worker) contribute no in-process route.
+            // Walk the flow tree; only `run` steps are hosted locally. `signal`
+            // (message catch) and `task` (external worker) contribute no in-process
+            // route, and structural combinators (`switch`/`branch`/`loop`) are pure
+            // routing with no job of their own.
+            walkNodes(wf.steps, (s) => {
                 if (s.kind !== "run")
-                    continue;
+                    return;
                 const handler = wf.handlers[s.name];
                 if (typeof handler !== "function") {
                     // `DeclarativeFlow` is a public type; a consumer-constructed flow could
@@ -71,7 +74,7 @@ export class Worker {
                     workflowId: wf.id,
                     handle: async (job) => ({ variables: ((await handler(job)) ?? {}) }),
                 });
-            }
+            });
         }
     }
     /** Register a derived job type, failing fast on a collision. Two workflows can

package/dist/xml.d.ts

@@ -7,4 +7,5 @@ export declare const messageName: (workflowId: string, step: string) => string;
 /** The single orchestrator job type of an imperative workflow. */
 export declare const orchestrateType: (workflowId: string) => string;
 export declare function assertIdent(kind: string, value: string): void;
+export declare function assertJobType(kind: string, value: string): void;
 export declare function assertWorkflowIds(wf: Workflow): void;

package/dist/xml.js

@@ -19,10 +19,51 @@ export function assertIdent(kind, value) {
         throw new Error(`${kind} "${value}" is not a valid BPMN identifier (expected an NCName)`);
     }
 }
+/** An explicit job type override (e.g. a `rank:capability` worker token like
+ *  `senior:pr-review`). Unlike a step name it is NOT a BPMN element id, so it may
+ *  carry the `:`/`+` token delimiters a `c8ctl nano work` matrix uses; it only
+ *  has to be a non-empty, whitespace-free token. */
+const JOB_TYPE = /^[A-Za-z0-9_][A-Za-z0-9_.:+-]*$/;
+export function assertJobType(kind, value) {
+    if (typeof value !== "string" || !JOB_TYPE.test(value)) {
+        throw new Error(`${kind} "${value}" is not a valid job type (expected a non-empty token of letters, digits, and _ . : + -)`);
+    }
+}
 export function assertWorkflowIds(wf) {
     assertIdent("workflow id", wf.id);
     if (wf.kind === "declarative") {
-        for (const step of wf.steps)
-            assertIdent("step name", step.name);
+        assertNodeNames(wf.steps);
+    }
+}
+function assertNodeNames(nodes) {
+    for (const node of nodes) {
+        switch (node.kind) {
+            case "run":
+            case "signal":
+                assertIdent("step name", node.name);
+                break;
+            case "task":
+                assertIdent("step name", node.name);
+                if (node.jobType !== undefined)
+                    assertJobType("job type", node.jobType);
+                break;
+            case "switch":
+                for (const c of node.cases)
+                    assertNodeNames(c.body);
+                if (node.default)
+                    assertNodeNames(node.default);
+                break;
+            case "branch":
+                assertNodeNames(node.then);
+                if (node.else)
+                    assertNodeNames(node.else);
+                break;
+            case "loop":
+                assertNodeNames(node.body);
+                break;
+            case "break":
+            case "continue":
+                break;
+        }
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.2.0",
-  "description": "Code-first durable orchestration for nanobpmn (ADR 0044/0045). Author a durable workflow as a declarative flow — `defineFlow(id, w => { w.run(...); w.signal(...); w.task(...) })` — and the SDK derives the executable BPMN model, the job types, and the message/correlation wiring, then hosts a generic worker. `w.run` is a local step, `w.signal` is a durable human-in-the-loop wait, `w.task` is a step serviced by an external worker. `defineFlow` is the single code-first surface; the imperative `defineWorkflow` replay function is experimental/internal, not a recommended API. No diagram, no task-type wiring, no correlation plumbing authored by hand. Talks to a running nanobpmn gateway over the REST v2 API.",
+  "version": "0.4.0",
+  "description": "Code-first durable orchestration for nanobpmn (ADR 0044/0045). Author a durable workflow as a declarative flow — `defineFlow(id, w => { w.run(...); w.signal(...); w.task(...) })` — and the SDK derives the executable BPMN model, the job types, and the message/correlation wiring, then hosts a generic worker. `w.run` is a local step, `w.signal` is a durable human-in-the-loop wait, `w.task` is a step serviced by an external worker. `defineFlow` is the single code-first surface; the imperative `defineWorkflow` replay function is experimental/internal, not a recommended API. No diagram, no task-type wiring, no correlation plumbing authored by hand — and you can optionally auto-generate a diagram (DI) for the derived model with `declarativeToLayoutedBpmn` via the optional `bpmn-auto-layout` peer dependency. Talks to a running nanobpmn gateway over the REST v2 API.",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
@@ -37,8 +37,17 @@
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
+    "bpmn-auto-layout": "^2.0.0-alpha.2",
     "typescript": "^5.6.3"
   },
+  "peerDependencies": {
+    "bpmn-auto-layout": "^2.0.0-alpha.2"
+  },
+  "peerDependenciesMeta": {
+    "bpmn-auto-layout": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public"
   }

package/src/bpmn-auto-layout.d.ts

@@ -0,0 +1,10 @@
+// Minimal ambient types for `bpmn-auto-layout` (ships none of its own).
+// `layoutProcess` adds diagram interchange (DI) to a BPMN XML string. The
+// resolved shape has settled on `{ xml, warnings }` in 2.x (and >= 1.4); 1.3.x
+// resolved to the laid-out XML string directly. We type the union and normalize
+// at the call site (see `layout.ts`) so the SDK still works across that range.
+declare module "bpmn-auto-layout" {
+  export function layoutProcess(
+    xml: string,
+  ): Promise<string | { xml: string; warnings?: unknown[] }>;
+}

package/src/client.ts

@@ -2,7 +2,7 @@
 // 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 type { DeclarativeFlow, DeployResult, Job, JsonObject, StartResult, Workflow } from "./types.js";
 import { assertWorkflowIds, messageName } from "./xml.js";
@@ -111,7 +111,12 @@ export class WorkflowClient {
     correlationKey: string,
     variables: JsonObject = {},
   ): Promise<JsonObject> {
-    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: string[] = [];
+    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: ${