@nanobpm/workflow 0.1.0 → 0.3.0

package/dist/imperative.js

@@ -18,7 +18,13 @@
 // The orchestration body MUST be deterministic across replays (no wall-clock
 // branching, RNG, or I/O outside `ctx.run` handlers).
 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, orchestrate) {
     assertIdent("workflow id", id);
     if (typeof orchestrate !== "function")

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 } 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

@@ -1,28 +1,46 @@
-// @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 { defineFlow, declarativeToBpmn } 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,61 @@
+// 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 >= 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) {
+    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,28 +6,82 @@ 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;
 } | {
     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.d.ts

@@ -41,6 +41,18 @@ export declare class Worker {
     private loops;
     constructor(opts: WorkerOptions);
     private register;
+    /** 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;
+    /** Invoke the onError observer hook without letting it affect the poll loop —
+     *  a throwing observer must not permanently stop a route. */
+    private emitError;
+    /** 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 emitActivity;
     /** The derived job types this worker serves. */
     get servedTypes(): string[];
     /** Begin polling. Resolves once the loops are running (they run until stop()). */

package/dist/worker.js

@@ -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).
 //
@@ -12,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 {
@@ -39,7 +41,7 @@ export class Worker {
     }
     register(wf) {
         if (wf.kind === "imperative") {
-            this.routes.set(wf.orchestrateType, {
+            this.addRoute(wf.orchestrateType, {
                 workflowId: wf.id,
                 handle: async (job) => {
                     const input = job.variables.input ?? {};
@@ -53,15 +55,59 @@ export class Worker {
             });
         }
         else {
-            for (const s of wf.steps) {
+            // 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];
-                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)) ?? {}) }),
                 });
-            }
+            });
+        }
+    }
+    /** 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. */
+    addRoute(type, route) {
+        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. */
+    emitError(err, type) {
+        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. */
+    async emitActivity(e) {
+        try {
+            await this.onActivity?.(e);
+        }
+        catch {
+            /* observational only; swallow so it never triggers failJob */
         }
     }
     /** The derived job types this worker serves. */
@@ -94,7 +140,7 @@ export class Worker {
             }
             catch (e) {
                 // Transport/gateway error (e.g. engine restarting): back off, reconnect.
-                this.onError?.(e, { type });
+                this.emitError(e, type);
                 await sleep(this.backoffMs);
                 continue;
             }
@@ -104,7 +150,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,
@@ -116,7 +164,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, { type });
+                    this.emitError(e, type);
                     try {
                         await this.client.failJob(job.jobKey, e.message, 0);
                     }

package/dist/xml.js

@@ -22,7 +22,34 @@ export function assertIdent(kind, value) {
 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 "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;
+        }
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.1.0",
-  "description": "Code-first durable orchestration for nanobpmn (ADR 0044). Author durable workflows as ordinary async code — either an imperative function driven by engine replay (`defineWorkflow(id, async ctx => { await ctx.run(...) })`, the Temporal-style surface) or a declarative flow with human-in-the-loop signals (`defineFlow`) — and the SDK derives the executable BPMN model, the job types, and the message/correlation wiring, then hosts a generic worker. 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.3.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": "^1.3.0",
     "typescript": "^5.6.3"
   },
+  "peerDependencies": {
+    "bpmn-auto-layout": "^1.3.0"
+  },
+  "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` (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`).
+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";
@@ -102,13 +102,28 @@ export class WorkflowClient {
     );
   }
 
-  /** Correlate a signal to a parked declarative `signal` step. */
+  /** Correlate a signal to a parked declarative `signal` step. Fails fast on an
+   *  unknown signal name (a typo would otherwise send an uncorrelatable message
+   *  that the gateway silently drops). */
   async signal(
     flow: DeclarativeFlow,
     signalName: string,
     correlationKey: string,
     variables: JsonObject = {},
   ): Promise<JsonObject> {
+    // 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: ${
+          signals.length ? signals.map((s) => `"${s}"`).join(", ") : "(none)"
+        }`,
+      );
+    }
     return this.json<JsonObject>(
       `/v2/messages/correlation`,
       {