@nanobpm/workflow 0.1.0 → 0.3.0

package/src/envelope.ts

@@ -0,0 +1,130 @@
+// 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";
+
+/** The scalar types a `nano:extend` field may declare (mirrors the vocabulary
+ *  the console's shape scan understands). `integer`/`number` are both `number`
+ *  in TS; `datetime` is an ISO `string`. */
+export type ScalarType = "string" | "integer" | "number" | "boolean" | "datetime";
+
+/** Map a scalar envelope type to its TypeScript representation. */
+export type ScalarTs<T extends ScalarType> = T extends "string" | "datetime"
+  ? string
+  : T extends "integer" | "number"
+    ? number
+    : T extends "boolean"
+      ? boolean
+      : never;
+
+/** A field spec: either a bare scalar type, or an object with modifiers. */
+export type FieldSpec =
+  | ScalarType
+  | { type: ScalarType; optional?: boolean; list?: boolean };
+
+/** The TS type of a single field spec (applies `list` before `optional`). */
+export type FieldTs<F> = F extends ScalarType
+  ? ScalarTs<F>
+  : F extends { type: infer T extends ScalarType; list: true }
+    ? ScalarTs<T>[]
+    : F extends { type: infer T extends ScalarType }
+      ? ScalarTs<T>
+      : never;
+
+type OptionalKeys<S> = {
+  [K in keyof S]: S[K] extends { optional: true } ? K : never;
+}[keyof S];
+type RequiredKeys<S> = Exclude<keyof S, OptionalKeys<S>>;
+
+/** The inferred payload type of an envelope: required + optional fields. */
+export type EnvelopeType<S extends Record<string, FieldSpec>> = {
+  [K in RequiredKeys<S>]: FieldTs<S[K]>;
+} & {
+  [K in OptionalKeys<S>]?: FieldTs<S[K]>;
+};
+
+/** A normalised field, as stored on an `Envelope` and lifted to `nano:extend`. */
+export interface EnvelopeField {
+  name: string;
+  type: ScalarType;
+  optional: boolean;
+  list: boolean;
+}
+
+/**
+ * A typed data envelope: a named schema (for the model) plus a phantom TS type
+ * (for the call site). Construct with {@link envelope}. `type` is a phantom
+ * property — it is `undefined` at runtime and exists only to carry the inferred
+ * payload type (use `typeof env.type` in type positions).
+ */
+export interface Envelope<S extends Record<string, FieldSpec> = Record<string, FieldSpec>> {
+  readonly name: string;
+  readonly fields: EnvelopeField[];
+  /** Phantom: the inferred payload type. Do not read at runtime. */
+  readonly type: EnvelopeType<S>;
+}
+
+const SCALARS: ReadonlySet<string> = new Set([
+  "string",
+  "integer",
+  "number",
+  "boolean",
+  "datetime",
+]);
+
+function normaliseField(name: string, spec: FieldSpec): EnvelopeField {
+  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<const S extends Record<string, FieldSpec>>(
+  name: string,
+  fields: S,
+): Envelope<S> {
+  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 as unknown as EnvelopeType<S> };
+}

package/src/imperative.ts

@@ -21,7 +21,13 @@
 import type { ImperativeWorkflow, Json, JsonObject, Orchestration, WorkflowContext } from "./types.js";
 import { assertIdent, escapeXml, orchestrateType } from "./xml.js";
 
-/** Define an imperative, replay-driven durable workflow. */
+/** Define an imperative, replay-driven durable workflow.
+ *
+ * @experimental Not the recommended code-first surface. Prefer `defineFlow`
+ * (declarative), whose steps are engine-visible BPMN nodes. This imperative
+ * replay surface compiles to a single opaque looping orchestrator and requires
+ * determinism discipline in the orchestration body; it is retained for advanced
+ * durable-orchestration use only. */
 export function defineWorkflow(id: string, orchestrate: Orchestration): ImperativeWorkflow {
   assertIdent("workflow id", id);
   if (typeof orchestrate !== "function") throw new Error("defineWorkflow needs an async orchestration function");

package/src/index.ts

@@ -1,32 +1,59 @@
-// @nanobpm/workflow — code-first durable orchestration for nanobpmn (ADR 0044).
+// @nanobpm/workflow — code-first durable workflows for nanobpmn (ADR 0044/0045).
 //
-// Two authoring surfaces over the same engine durability:
+// THE code-first surface is the declarative flow builder — a list of steps the
+// engine runs and shows you one at a time, because each compiles to a real,
+// engine-visible BPMN node:
 //
-//   defineWorkflow(id, async (ctx) => { await ctx.run(...) })   // imperative (replay)
-//   defineFlow(id, (w) => { w.run(...); w.signal(...); })       // declarative (+signals)
+//   defineFlow(id, (w) => {
+//     w.run("fetchDiff", async (job) => ({ diff: await gh.diff(job.variables.prId) }));
+//     w.signal("humanApproval", { correlationKey: "prId" }); // durable human wait
+//     w.task("signPdf");                                      // served by an EXTERNAL worker
+//     w.run("merge", async (job) => ({ merged: await gh.merge(job.variables.prId) }));
+//   });
+//
+// The SDK derives the BPMN model, the job types (`${flowId}:${step}`), and the
+// message/correlation wiring; the Worker hosts your `run` steps; the
+// WorkflowClient deploys, starts, and signals. `w.task` steps are served by a
+// worker outside this program (see `externalJobTypes`).
 //
-// The SDK derives the BPMN model, job types, and message/correlation wiring; the
-// Worker runtime hosts them; the WorkflowClient deploys, starts, and signals.
+// `defineWorkflow` (imperative, Temporal-style replay) is EXPERIMENTAL and kept
+// for advanced durable-orchestration use only; prefer `defineFlow`. Its steps
+// are not engine-visible (a single looping orchestrator) and it requires
+// determinism discipline. It is not the recommended authoring surface.
 //
 // Quickstart:
 //
-//   import { defineWorkflow, WorkflowClient, Worker } from "@nanobpm/workflow";
+//   import { defineFlow, WorkflowClient, Worker } from "@nanobpm/workflow";
 //
-//   const wf = defineWorkflow("pr-review", async (ctx) => {
-//     const diff = await ctx.run("fetchDiff", () => gh.diff(ctx.input.prId));
-//     await ctx.run("merge", () => gh.merge(ctx.input.prId));
+//   const prReview = defineFlow("pr-review", (w) => {
+//     w.run("fetchDiff", async (job) => ({ files: 3 }));
+//     w.run("merge", async (job) => ({ merged: true }));
 //   });
 //
 //   const client = new WorkflowClient({ baseUrl: "http://localhost:8080" });
-//   await client.deploy(wf);
-//   const worker = new Worker({ baseUrl: "http://localhost:8080", workflows: [wf] });
+//   await client.deploy(prReview);
+//   const worker = new Worker({ baseUrl: "http://localhost:8080", workflows: [prReview] });
 //   worker.start();
-//   await client.start(wf, { prId: "PR-1234" });
+//   await client.start(prReview, { prId: "PR-1234" });
 
+// EXPERIMENTAL — imperative (Temporal-style replay) surface. Not the recommended
+// 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 type { Journal, ReplayStep } from "./imperative.js";
-export { defineFlow, declarativeToBpmn } 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";
@@ -38,6 +65,11 @@ export type {
   StepHandler,
   DeclarativeFlow,
   DeclarativeStep,
+  FlowNode,
+  SwitchCase,
+  NodeEnvelopes,
+  StepContract,
+  FlowContracts,
   ImperativeWorkflow,
   Orchestration,
   WorkflowContext,

package/src/layout.ts

@@ -0,0 +1,67 @@
+// 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 type { DeclarativeFlow } from "./types.js";
+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: string): Promise<string> {
+  let layoutProcess: typeof import("bpmn-auto-layout").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 as NodeJS.ErrnoException | undefined)?.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 >= 1.4 (and `main`) resolves to
+  // `{ xml, warnings }`; 1.3.x resolves to the laid-out XML string directly.
+  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: DeclarativeFlow): Promise<string> {
+  return layoutBpmn(declarativeToBpmn(flow));
+}

package/src/types.ts

@@ -1,31 +1,79 @@
 // Public types for @nanobpm/workflow.
 
+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 };
 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;
 }
 
-// --- Declarative surface (Strategy A: compile a step list to a linear model) --
+// --- Declarative surface (Strategy A: compile a step tree to a BPMN model) ----
+//
+// A flow is a TREE of nodes, not a flat list: leaf activities (`run`/`task`/
+// `signal`) plus structural combinators (`switch`/`branch`/`loop`) that compile
+// to real XOR gateways and back-edges. See declarative.ts for the compiler.
+
+/** 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 =
-  | { kind: "run"; name: string }
-  | { kind: "signal"; name: string; correlationKey: string };
+/** 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 }
+  | { 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>;
 }
 

package/src/worker.ts

@@ -3,7 +3,8 @@
 // them. It generalises the two surfaces:
 //
 //   - a declarative flow contributes one job type per `run` step, dispatched to
-//     the user handler;
+//     the user handler (external `task` steps are intentionally NOT hosted here —
+//     a worker outside this program serves them);
 //   - an imperative workflow contributes its single orchestrator job type,
 //     dispatched to the replay engine (which advances the journal one step).
 //
@@ -13,6 +14,7 @@
 
 import { WorkflowClient } from "./client.js";
 import { replayOnce } from "./imperative.js";
+import { walkNodes } from "./declarative.js";
 import type { Job, JsonObject, Workflow } from "./types.js";
 import { jobType } from "./xml.js";
 
@@ -73,7 +75,7 @@ export class Worker {
 
   private register(wf: Workflow): void {
     if (wf.kind === "imperative") {
-      this.routes.set(wf.orchestrateType, {
+      this.addRoute(wf.orchestrateType, {
         workflowId: wf.id,
         handle: async (job) => {
           const input = (job.variables.input as JsonObject) ?? {};
@@ -85,14 +87,63 @@ export class Worker {
         },
       });
     } else {
-      for (const s of wf.steps) {
-        if (s.kind !== "run") continue;
+      // 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") return;
         const handler = wf.handlers[s.name];
-        this.routes.set(jobType(wf.id, s.name), {
+        if (typeof handler !== "function") {
+          // `DeclarativeFlow` is a public type; a consumer-constructed flow could
+          // carry a `run` step with no handler. Fail fast at registration with a
+          // clear message rather than a `handler is not a function` TypeError on
+          // the first job activation.
+          throw new Error(
+            `workflow "${wf.id}": run step "${s.name}" has no handler function`,
+          );
+        }
+        this.addRoute(jobType(wf.id, s.name), {
           workflowId: wf.id,
           handle: async (job) => ({ variables: ((await handler(job)) ?? {}) as JsonObject }),
         });
-      }
+      });
+    }
+  }
+
+  /** Register a derived job type, failing fast on a collision. Two workflows can
+   *  resolve to the same job type (duplicate workflow ids, or a declarative step
+   *  name that collides with another workflow's); silently overwriting the route
+   *  would drop a handler, so we reject it at construction time. */
+  private addRoute(type: string, route: { workflowId: string; handle: Handler }): void {
+    const existing = this.routes.get(type);
+    if (existing) {
+      throw new Error(
+        `duplicate derived job type "${type}": workflows "${existing.workflowId}" and "${route.workflowId}" ` +
+          `resolve to the same job type (check for duplicate workflow ids or colliding step names)`,
+      );
+    }
+    this.routes.set(type, route);
+  }
+
+  /** Invoke the onError observer hook without letting it affect the poll loop —
+   *  a throwing observer must not permanently stop a route. */
+  private emitError(err: Error, type: string): void {
+    try {
+      this.onError?.(err, { type });
+    } catch {
+      /* observer hooks are purely observational; swallow their failures */
+    }
+  }
+
+  /** Invoke the onActivity observer hook in isolation. It runs after the job has
+   *  already been completed, so a throwing observer must not fall into the
+   *  failure path and try to fail an already-completed job. */
+  private async emitActivity(e: ActivityEvent): Promise<void> {
+    try {
+      await this.onActivity?.(e);
+    } catch {
+      /* observational only; swallow so it never triggers failJob */
     }
   }
 
@@ -127,7 +178,7 @@ export class Worker {
         });
       } catch (e) {
         // Transport/gateway error (e.g. engine restarting): back off, reconnect.
-        this.onError?.(e as Error, { type });
+        this.emitError(e as Error, type);
         await sleep(this.backoffMs);
         continue;
       }
@@ -136,7 +187,9 @@ export class Worker {
         try {
           const { variables, step } = await route.handle(job);
           await this.client.completeJob(job.jobKey, variables);
-          await this.onActivity?.({
+          // Job is now completed; the observer hook is isolated (emitActivity
+          // swallows its own errors) so it can never fall into the failure path.
+          await this.emitActivity({
             workflowId: route.workflowId,
             type,
             jobKey: job.jobKey,
@@ -147,7 +200,7 @@ export class Worker {
           // A handler or completion failed. Report; the engine will redeliver the
           // job after its lock times out (at-least-once → handlers must be
           // idempotent). Best-effort surface it as an incident-worthy failure.
-          this.onError?.(e as Error, { type });
+          this.emitError(e as Error, type);
           try {
             await this.client.failJob(job.jobKey, (e as Error).message, 0);
           } catch {

package/src/xml.ts

@@ -1,6 +1,6 @@
 // XML helpers + derived-name conventions shared by both model emitters.
 
-import type { Workflow } from "./types.js";
+import type { FlowNode, Workflow } from "./types.js";
 
 export function escapeXml(s: string): string {
   return String(s)
@@ -30,6 +30,32 @@ export function assertIdent(kind: string, value: string): void {
 export function assertWorkflowIds(wf: Workflow): void {
   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: FlowNode[]): void {
+  for (const node of nodes) {
+    switch (node.kind) {
+      case "run":
+      case "task":
+      case "signal":
+        assertIdent("step name", node.name);
+        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;
+    }
   }
 }