@nanobpm/workflow 0.3.0 → 0.4.0

package/README.md

@@ -34,7 +34,9 @@ Both compile to the same engine durability; pick per workflow.
 ### 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
+locally-hosted service task), `w.task` (an external-worker service task — job
+type `${flowId}:${name}` by default, or pass `w.task(name, { jobType })` to
+target an existing worker pool, e.g. a `senior:pr-review` agent token), and
 `w.signal` (a durable message catch that resumes via a correlated message — the
 human-in-the-loop path), composed with control-flow combinators:
 
@@ -178,7 +180,7 @@ once.
 | `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. |
+| `externalJobTypes(flow)` | The job types of a flow's external `task` steps (each overridable per-step via `w.task(name, { jobType })`). |
 | `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). |

package/dist/declarative.d.ts

@@ -33,12 +33,19 @@ export interface FlowBuilder<C extends FlowContracts = Record<string, never>> {
     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 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, but no locally-hosted handler). Its job type defaults to the derived
+     * `${flowId}:${name}`; pass `{ jobType }` to override it with an explicit
+     * worker token (e.g. a `rank:capability` token like `senior:pr-review` that a
+     * `c8ctl nano work` matrix subscribes to) so an existing pool of agents can
+     * service it without renaming the flow. The step name stays the BPMN element
+     * id; only the emitted `zeebe:taskDefinition` type changes. Use
+     * `externalJobTypes(flow)` to list the (possibly overridden) types those
+     * workers must poll. Its contract envelopes (if any) type the model, not a
+     * local handler.
      */
-    task<K extends string>(name: K): FlowBuilder<C>;
+    task<K extends string>(name: K, opts?: {
+        jobType?: string;
+    }): FlowBuilder<C>;
     /**
      * A durable wait for an external/human event, correlated on a process
      * variable (a BPMN message intermediate catch event). Resume it with
@@ -89,8 +96,11 @@ export declare function defineFlow(id: string, build: (w: FlowBuilder) => void):
 /** 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. */
+/** The job types of a flow's external `task` steps (anywhere in the tree) — the
+ *  contract workers outside this program must subscribe to. Each is the derived
+ *  `<flowId>:<stepName>` unless the step overrode it via `w.task(name,
+ *  { jobType })`. Deduplicated (preserving first-seen order) since several steps
+ *  may intentionally share one override token. */
 export declare function externalJobTypes(flow: DeclarativeFlow): string[];
 /** Derive an executable BPMN model from a declarative flow. */
 export declare function declarativeToBpmn(flow: DeclarativeFlow): string;

package/dist/declarative.js

@@ -34,7 +34,7 @@
 // Typed data envelopes are LIFTED into the model (nano:shape + dataEnvelope
 // zeebe:property), so the generated .bpmn is ejectable to model-first with its
 // typed contracts intact.
-import { assertIdent, escapeXml, jobType, messageName } from "./xml.js";
+import { assertIdent, assertJobType, escapeXml, jobType, messageName } from "./xml.js";
 /** Ids the emitter generates for structural nodes / flows / messages. A step
  *  name that collides with one of these would produce a duplicate BPMN id and an
  *  invalid model, so reject them at authoring time. */
@@ -77,9 +77,12 @@ function makeBuilder(id, out, ctx) {
             out.push({ kind: "run", name, envelopes: contractEnvelopes(ctx, name) });
             return b;
         },
-        task(name) {
+        task(name, opts) {
             claimName(ctx, id, name);
-            out.push({ kind: "task", name, envelopes: contractEnvelopes(ctx, name) });
+            const override = opts?.jobType;
+            if (override !== undefined)
+                assertJobType("task jobType", override);
+            out.push({ kind: "task", name, envelopes: contractEnvelopes(ctx, name), jobType: override });
             return b;
         },
         signal(name, opts) {
@@ -181,13 +184,22 @@ export function walkNodes(nodes, visit) {
         }
     }
 }
-/** The derived job types of a flow's external `task` steps (anywhere in the
- *  tree) — the contract workers outside this program must subscribe to. */
+/** The job types of a flow's external `task` steps (anywhere in the tree) — the
+ *  contract workers outside this program must subscribe to. Each is the derived
+ *  `<flowId>:<stepName>` unless the step overrode it via `w.task(name,
+ *  { jobType })`. Deduplicated (preserving first-seen order) since several steps
+ *  may intentionally share one override token. */
 export function externalJobTypes(flow) {
+    const seen = new Set();
     const types = [];
     walkNodes(flow.steps, (n) => {
-        if (n.kind === "task")
-            types.push(jobType(flow.id, n.name));
+        if (n.kind !== "task")
+            return;
+        const type = n.jobType ?? jobType(flow.id, n.name);
+        if (seen.has(type))
+            return;
+        seen.add(type);
+        types.push(type);
     });
     return types;
 }
@@ -224,7 +236,7 @@ class Compiler {
         this.envelopes.set(env.name, env.fields);
     }
     addServiceTask(node) {
-        const type = jobType(this.flow.id, node.name);
+        const type = node.jobType ?? jobType(this.flow.id, node.name);
         this.recordEnvelope(node.envelopes?.in);
         this.recordEnvelope(node.envelopes?.out);
         const props = [];

package/dist/layout.js

@@ -43,8 +43,9 @@ export async function layoutBpmn(bpmnXml) {
             "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.
+    // 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;
 }
 /**

package/dist/types.d.ts

@@ -46,6 +46,7 @@ export type FlowNode = {
     kind: "task";
     name: string;
     envelopes?: NodeEnvelopes;
+    jobType?: string;
 } | {
     kind: "signal";
     name: string;

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,6 +19,16 @@ 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") {
@@ -29,10 +39,14 @@ function assertNodeNames(nodes) {
     for (const node of nodes) {
         switch (node.kind) {
             case "run":
-            case "task":
             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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.3.0",
+  "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",
@@ -37,11 +37,11 @@
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
-    "bpmn-auto-layout": "^1.3.0",
+    "bpmn-auto-layout": "^2.0.0-alpha.2",
     "typescript": "^5.6.3"
   },
   "peerDependencies": {
-    "bpmn-auto-layout": "^1.3.0"
+    "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "peerDependenciesMeta": {
     "bpmn-auto-layout": {

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

@@ -1,8 +1,8 @@
-// Minimal ambient types for `bpmn-auto-layout` (1.3.0 ships none). `layoutProcess`
-// adds diagram interchange (DI) to a BPMN XML string. The resolved shape changed
-// across versions: 1.3.x resolves to the laid-out XML string; >= 1.4 / `main`
-// resolves to `{ xml, warnings }`. We type the union and normalize at the call
-// site (see `layout.ts`).
+// 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,

package/src/declarative.ts

@@ -46,7 +46,7 @@ import type {
   SwitchCase,
 } from "./types.js";
 import type { Envelope, EnvelopeField } from "./envelope.js";
-import { assertIdent, escapeXml, jobType, messageName } from "./xml.js";
+import { assertIdent, assertJobType, escapeXml, jobType, messageName } from "./xml.js";
 
 // --- Authoring surface -------------------------------------------------------
 
@@ -82,12 +82,17 @@ export interface FlowBuilder<C extends FlowContracts = Record<string, never>> {
   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 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, but no locally-hosted handler). Its job type defaults to the derived
+   * `${flowId}:${name}`; pass `{ jobType }` to override it with an explicit
+   * worker token (e.g. a `rank:capability` token like `senior:pr-review` that a
+   * `c8ctl nano work` matrix subscribes to) so an existing pool of agents can
+   * service it without renaming the flow. The step name stays the BPMN element
+   * id; only the emitted `zeebe:taskDefinition` type changes. Use
+   * `externalJobTypes(flow)` to list the (possibly overridden) types those
+   * workers must poll. Its contract envelopes (if any) type the model, not a
+   * local handler.
    */
-  task<K extends string>(name: K): FlowBuilder<C>;
+  task<K extends string>(name: K, opts?: { jobType?: string }): FlowBuilder<C>;
   /**
    * A durable wait for an external/human event, correlated on a process
    * variable (a BPMN message intermediate catch event). Resume it with
@@ -173,9 +178,11 @@ function makeBuilder<C extends FlowContracts>(id: string, out: FlowNode[], ctx:
       out.push({ kind: "run", name, envelopes: contractEnvelopes(ctx, name) });
       return b as unknown as FlowBuilder<C>;
     },
-    task(name: string): FlowBuilder<C> {
+    task(name: string, opts?: { jobType?: string }): FlowBuilder<C> {
       claimName(ctx, id, name);
-      out.push({ kind: "task", name, envelopes: contractEnvelopes(ctx, name) });
+      const override = opts?.jobType;
+      if (override !== undefined) assertJobType("task jobType", override);
+      out.push({ kind: "task", name, envelopes: contractEnvelopes(ctx, name), jobType: override });
       return b as unknown as FlowBuilder<C>;
     },
     signal(name: string, opts: { correlationKey: string }): FlowBuilder<C> {
@@ -286,12 +293,20 @@ export 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. */
+/** The job types of a flow's external `task` steps (anywhere in the tree) — the
+ *  contract workers outside this program must subscribe to. Each is the derived
+ *  `<flowId>:<stepName>` unless the step overrode it via `w.task(name,
+ *  { jobType })`. Deduplicated (preserving first-seen order) since several steps
+ *  may intentionally share one override token. */
 export function externalJobTypes(flow: DeclarativeFlow): string[] {
+  const seen = new Set<string>();
   const types: string[] = [];
   walkNodes(flow.steps, (n) => {
-    if (n.kind === "task") types.push(jobType(flow.id, n.name));
+    if (n.kind !== "task") return;
+    const type = n.jobType ?? jobType(flow.id, n.name);
+    if (seen.has(type)) return;
+    seen.add(type);
+    types.push(type);
   });
   return types;
 }
@@ -352,8 +367,8 @@ class Compiler {
     this.envelopes.set(env.name, env.fields);
   }
 
-  private addServiceTask(node: { name: string; envelopes?: NodeEnvelopes }): void {
-    const type = jobType(this.flow.id, node.name);
+  private addServiceTask(node: { name: string; envelopes?: NodeEnvelopes; jobType?: string }): void {
+    const type = node.jobType ?? jobType(this.flow.id, node.name);
     this.recordEnvelope(node.envelopes?.in);
     this.recordEnvelope(node.envelopes?.out);
     const props: string[] = [];

package/src/layout.ts

@@ -48,8 +48,9 @@ export async function layoutBpmn(bpmnXml: string): Promise<string> {
     );
   }
   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.
+  // 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;
 }
 

package/src/types.ts

@@ -51,7 +51,7 @@ export type StepHandler = (job: Job) => Promise<JsonObject | void> | JsonObject
  *  combinators carry nested `FlowNode[]` bodies. */
 export type FlowNode =
   | { kind: "run"; name: string; envelopes?: NodeEnvelopes }
-  | { kind: "task"; 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[] }

package/src/xml.ts

@@ -27,6 +27,19 @@ export function assertIdent(kind: string, value: string): void {
   }
 }
 
+/** 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: string, value: string): void {
+  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: Workflow): void {
   assertIdent("workflow id", wf.id);
   if (wf.kind === "declarative") {
@@ -38,10 +51,13 @@ 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 "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);