@nanobpm/workflow 0.3.0 → 0.5.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,10 +180,28 @@ 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). |
+| `toBpmn(workflow)` | The DI-less semantic BPMN the engine runs (for inspection / deployment). |
+| `toDeployableBpmn(workflow, { layout? })` | The deployable BPMN **with an auto-generated diagram (DI)** so the deployed model is inspectable; what `deploy` sends by default. |
+| `layoutBpmn(xml)` / `declarativeToLayoutedBpmn(flow)` | Add DI to a model with `bpmn-auto-layout`. |
+
+### Inspectable deployments (diagram layout)
+
+`client.deploy(flow)` deploys the model **with an auto-generated diagram
+interchange (DI)** so it opens rendered and inspectable in a modeller/Operate
+rather than as a blank canvas. DI is generated with the optional peer dependency
+[`bpmn-auto-layout`](https://www.npmjs.com/package/bpmn-auto-layout):
+
+```sh
+npm i bpmn-auto-layout
+```
+
+If it is not installed, `deploy` degrades gracefully — it warns once and deploys
+the DI-less model. Pass `deploy(flow, { layout: false })` to skip layout
+deliberately. The semantic model stays authoritative; DI is derived and
+regenerable.
 
 See [ADR 0044](../docs/adr/0044-code-first-durable-orchestration.md) for the design
 rationale and [ADR 0047](../docs/adr/0047-declarative-flow-control-and-typed-envelopes.md)

package/dist/client.d.ts

@@ -1,6 +1,21 @@
 import type { DeclarativeFlow, DeployResult, Job, JsonObject, StartResult, Workflow } from "./types.js";
 /** Render a workflow (either surface) to its executable BPMN model. */
 export declare function toBpmn(wf: Workflow): string;
+/**
+ * Render a workflow to *deployable* BPMN — the executable model plus diagram
+ * interchange (DI), auto-generated with `bpmn-auto-layout` — so the deployed
+ * process opens rendered and inspectable in a modeller/Operate rather than as a
+ * blank canvas. The semantic model stays authoritative; DI is derived.
+ *
+ * DI generation needs the optional peer dependency `bpmn-auto-layout`. When it is
+ * absent, this degrades gracefully: it warns once and returns the DI-less model
+ * so `deploy` still works everywhere. Pass `{ layout: false }` to skip layout
+ * deliberately. A genuine layout failure (the dep is installed but errors) is
+ * surfaced, not swallowed.
+ */
+export declare function toDeployableBpmn(wf: Workflow, opts?: {
+    layout?: boolean;
+}): Promise<string>;
 type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 export interface WorkflowClientOptions {
     /** Base URL of the nanobpmn gateway, e.g. `http://localhost:8080`. */
@@ -29,8 +44,16 @@ export declare class WorkflowClient {
     /** Perform a request, throwing WorkflowError on transport error or !ok, and
      *  return the raw Response (for endpoints with an empty/no-content body). */
     private send;
-    /** Deploy a workflow's derived BPMN model. */
-    deploy(wf: Workflow): Promise<DeployResult>;
+    /**
+     * Deploy a workflow's derived BPMN model. The deployed model includes
+     * auto-generated diagram interchange (DI) so it is inspectable in a
+     * modeller/Operate; pass `{ layout: false }` to deploy the DI-less semantic
+     * model. DI needs the optional `bpmn-auto-layout` dependency — see
+     * `toDeployableBpmn` for the graceful-degradation behaviour when it is absent.
+     */
+    deploy(wf: Workflow, opts?: {
+        layout?: boolean;
+    }): Promise<DeployResult>;
     /**
      * Start a workflow instance. For imperative workflows the engine variables are
      * seeded with `{ input, journal: {}, wfDone: false }` (the replay state); for

package/dist/client.js

@@ -3,12 +3,50 @@
 // low-level job activate/complete/fail used by the Worker runtime.
 import { declarativeToBpmn, walkNodes } from "./declarative.js";
 import { imperativeToBpmn } from "./imperative.js";
+import { layoutBpmn } from "./layout.js";
 import { assertWorkflowIds, messageName } from "./xml.js";
 /** Render a workflow (either surface) to its executable BPMN model. */
 export function toBpmn(wf) {
     assertWorkflowIds(wf);
     return wf.kind === "imperative" ? imperativeToBpmn(wf) : declarativeToBpmn(wf);
 }
+let warnedNoLayout = false;
+/**
+ * Render a workflow to *deployable* BPMN — the executable model plus diagram
+ * interchange (DI), auto-generated with `bpmn-auto-layout` — so the deployed
+ * process opens rendered and inspectable in a modeller/Operate rather than as a
+ * blank canvas. The semantic model stays authoritative; DI is derived.
+ *
+ * DI generation needs the optional peer dependency `bpmn-auto-layout`. When it is
+ * absent, this degrades gracefully: it warns once and returns the DI-less model
+ * so `deploy` still works everywhere. Pass `{ layout: false }` to skip layout
+ * deliberately. A genuine layout failure (the dep is installed but errors) is
+ * surfaced, not swallowed.
+ */
+export async function toDeployableBpmn(wf, opts = {}) {
+    const semantic = toBpmn(wf);
+    if (opts.layout === false)
+        return semantic;
+    try {
+        return await layoutBpmn(semantic);
+    }
+    catch (e) {
+        // Only fall back for the "optional dep not installed" case (layoutBpmn wraps
+        // it with an ERR_MODULE_NOT_FOUND cause). Any other failure is a real layout
+        // problem and must surface rather than silently deploy an uninspectable model.
+        const cause = e?.cause;
+        if (cause?.code !== "ERR_MODULE_NOT_FOUND")
+            throw e;
+        if (!warnedNoLayout) {
+            warnedNoLayout = true;
+            console.warn(`[@nanobpm/workflow] Deploying "${wf.id}" without a diagram: the optional ` +
+                '"bpmn-auto-layout" dependency is not installed, so the model will be ' +
+                "uninspectable in a modeller/Operate. Install it for diagram layout: " +
+                "npm i bpmn-auto-layout");
+        }
+        return semantic;
+    }
+}
 export class WorkflowError extends Error {
     status;
     body;
@@ -51,9 +89,15 @@ export class WorkflowClient {
         }
         return res;
     }
-    /** Deploy a workflow's derived BPMN model. */
-    async deploy(wf) {
-        const xml = toBpmn(wf);
+    /**
+     * Deploy a workflow's derived BPMN model. The deployed model includes
+     * auto-generated diagram interchange (DI) so it is inspectable in a
+     * modeller/Operate; pass `{ layout: false }` to deploy the DI-less semantic
+     * model. DI needs the optional `bpmn-auto-layout` dependency — see
+     * `toDeployableBpmn` for the graceful-degradation behaviour when it is absent.
+     */
+    async deploy(wf, opts = {}) {
+        const xml = await toDeployableBpmn(wf, opts);
         const form = new FormData();
         form.append("resources", new Blob([xml], { type: "text/xml" }), `${wf.id}.bpmn`);
         return this.json(`/v2/deployments`, { method: "POST", body: form }, "deploy");

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/index.d.ts

@@ -5,7 +5,7 @@ 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 { WorkflowClient, WorkflowError, toBpmn, toDeployableBpmn } from "./client.js";
 export type { WorkflowClientOptions, ActivateOptions } from "./client.js";
 export { Worker } from "./worker.js";
 export type { WorkerOptions, ActivityEvent } from "./worker.js";

package/dist/index.js

@@ -42,5 +42,5 @@ export { defineWorkflow, imperativeToBpmn, replayOnce } from "./imperative.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 { WorkflowClient, WorkflowError, toBpmn, toDeployableBpmn } from "./client.js";
 export { Worker } from "./worker.js";

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,13 +1,13 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.3.0",
+  "version": "0.5.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": {
     "type": "git",
-    "url": "https://github.com/Magikcraft/nano-bpm",
-    "directory": "workflow"
+    "url": "https://github.com/jwulf/nano-ide.git",
+    "directory": "packages/workflow"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -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/client.ts

@@ -4,6 +4,7 @@
 
 import { declarativeToBpmn, walkNodes } from "./declarative.js";
 import { imperativeToBpmn } from "./imperative.js";
+import { layoutBpmn } from "./layout.js";
 import type { DeclarativeFlow, DeployResult, Job, JsonObject, StartResult, Workflow } from "./types.js";
 import { assertWorkflowIds, messageName } from "./xml.js";
 
@@ -13,6 +14,47 @@ export function toBpmn(wf: Workflow): string {
   return wf.kind === "imperative" ? imperativeToBpmn(wf) : declarativeToBpmn(wf);
 }
 
+let warnedNoLayout = false;
+
+/**
+ * Render a workflow to *deployable* BPMN — the executable model plus diagram
+ * interchange (DI), auto-generated with `bpmn-auto-layout` — so the deployed
+ * process opens rendered and inspectable in a modeller/Operate rather than as a
+ * blank canvas. The semantic model stays authoritative; DI is derived.
+ *
+ * DI generation needs the optional peer dependency `bpmn-auto-layout`. When it is
+ * absent, this degrades gracefully: it warns once and returns the DI-less model
+ * so `deploy` still works everywhere. Pass `{ layout: false }` to skip layout
+ * deliberately. A genuine layout failure (the dep is installed but errors) is
+ * surfaced, not swallowed.
+ */
+export async function toDeployableBpmn(
+  wf: Workflow,
+  opts: { layout?: boolean } = {},
+): Promise<string> {
+  const semantic = toBpmn(wf);
+  if (opts.layout === false) return semantic;
+  try {
+    return await layoutBpmn(semantic);
+  } catch (e) {
+    // Only fall back for the "optional dep not installed" case (layoutBpmn wraps
+    // it with an ERR_MODULE_NOT_FOUND cause). Any other failure is a real layout
+    // problem and must surface rather than silently deploy an uninspectable model.
+    const cause = (e as { cause?: NodeJS.ErrnoException })?.cause;
+    if (cause?.code !== "ERR_MODULE_NOT_FOUND") throw e;
+    if (!warnedNoLayout) {
+      warnedNoLayout = true;
+      console.warn(
+        `[@nanobpm/workflow] Deploying "${wf.id}" without a diagram: the optional ` +
+          '"bpmn-auto-layout" dependency is not installed, so the model will be ' +
+          "uninspectable in a modeller/Operate. Install it for diagram layout: " +
+          "npm i bpmn-auto-layout",
+      );
+    }
+    return semantic;
+  }
+}
+
 type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 
 export interface WorkflowClientOptions {
@@ -75,9 +117,15 @@ export class WorkflowClient {
     return res;
   }
 
-  /** Deploy a workflow's derived BPMN model. */
-  async deploy(wf: Workflow): Promise<DeployResult> {
-    const xml = toBpmn(wf);
+  /**
+   * Deploy a workflow's derived BPMN model. The deployed model includes
+   * auto-generated diagram interchange (DI) so it is inspectable in a
+   * modeller/Operate; pass `{ layout: false }` to deploy the DI-less semantic
+   * model. DI needs the optional `bpmn-auto-layout` dependency — see
+   * `toDeployableBpmn` for the graceful-degradation behaviour when it is absent.
+   */
+  async deploy(wf: Workflow, opts: { layout?: boolean } = {}): Promise<DeployResult> {
+    const xml = await toDeployableBpmn(wf, opts);
     const form = new FormData();
     form.append("resources", new Blob([xml], { type: "text/xml" }), `${wf.id}.bpmn`);
     return this.json<DeployResult>(`/v2/deployments`, { method: "POST", body: form }, "deploy");

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/index.ts

@@ -54,7 +54,7 @@ export type {
   ScalarTs,
   FieldTs,
 } from "./envelope.js";
-export { WorkflowClient, WorkflowError, toBpmn } from "./client.js";
+export { WorkflowClient, WorkflowError, toBpmn, toDeployableBpmn } from "./client.js";
 export type { WorkflowClientOptions, ActivateOptions } from "./client.js";
 export { Worker } from "./worker.js";
 export type { WorkerOptions, ActivityEvent } from "./worker.js";

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);