@nanobpm/workflow 0.10.0 → 0.11.0

package/README.md

@@ -62,6 +62,13 @@ human-in-the-loop path), composed with control-flow combinators:
   (a message- or timer-event-definition), the arm bodies rejoining downstream by an
   implicit XOR merge. This is the shape a convergence loop uses to bound a
   human-in-the-loop wait with a timeout.
+- `w.run(...).boundary({ timer, onTimeout, interrupting?, name? })` — attach an
+  SLA (an interrupting timer boundary event) to the PRECEDING activity: when
+  `timer` elapses the activity is cancelled and the token routes to the
+  `onTimeout` escalation body, which then converges with the activity's normal
+  continuation. `timer` is an ISO-8601 duration (`PT24H`) or a FEEL
+  `=`-expression (`=escalationSlaTimeout`). `interrupting` defaults to `true`
+  (pass `false` for a non-interrupting boundary that leaves the activity running).
 
 ```ts
 import { defineFlow, WorkflowClient, Worker } from "@nanobpm/workflow";

package/dist/declarative.js

@@ -577,6 +577,7 @@ class Compiler {
         const shapeXml = this.emitShapes();
         return (`<?xml version="1.0" encoding="UTF-8"?>\n` +
             `<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" ` +
+            `xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ` +
             `xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" ` +
             `xmlns:nano="https://nanobpm.io/schema/shapes/1.0" ` +
             `id="Definitions_${escapeXml(this.flow.id)}" targetNamespace="http://bpmn.io/schema/bpmn">\n` +

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { defineWorkflow, imperativeToBpmn, replayOnce } from "./imperative.js";
 export type { Journal, ReplayStep } from "./imperative.js";
 export { defineFlow, declarativeToBpmn, externalJobTypes, walkNodes } from "./declarative.js";
 export type { FlowBuilder } from "./declarative.js";
+export type { BoundaryOptions } from "./nodes/boundary.js";
 export { layoutBpmn, declarativeToLayoutedBpmn } from "./layout.js";
 export { envelope } from "./envelope.js";
 export type { Envelope, EnvelopeType, EnvelopeField, FieldSpec, ScalarType, ScalarTs, FieldTs, } from "./envelope.js";

package/dist/nodes/boundary.d.ts

@@ -0,0 +1,46 @@
+import type { Block } from "../declarative.js";
+/** Options for `.boundary(...)`: an attached timer SLA on the preceding activity.
+ *  - `timer` — the timeout: an ISO-8601 duration (`PT24H`, `P1DT6H`) or a FEEL
+ *    `=`-expression (`=escalationSlaTimeout`); the duration need not be a literal.
+ *  - `onTimeout` — the escalation body run when the timer elapses (its danglers
+ *    converge with the activity's normal continuation).
+ *  - `interrupting` — whether firing cancels the host activity. Defaults to
+ *    `true` (an interrupting boundary; `cancelActivity` omitted, the BPMN default).
+ *    Pass `false` for a non-interrupting boundary (`cancelActivity="false"`).
+ *  - `name` — an optional label for the boundary event. */
+export interface BoundaryOptions<C extends object = object> {
+    timer: string;
+    onTimeout: Block<C>;
+    interrupting?: boolean;
+    name?: string;
+}
+declare module "../types.js" {
+    interface FlowNodeRegistry {
+        boundary: {
+            kind: "boundary";
+            /** The derived element id of the activity this boundary attaches to. */
+            attachedTo: string;
+            /** The timeout — an ISO-8601 duration or a FEEL `=`-expression. */
+            timer: string;
+            /** Whether firing cancels the host (interrupting). */
+            interrupting: boolean;
+            /** The escalation body wired from the boundary event's outgoing flow. */
+            onTimeout: FlowNode[];
+            /** Optional boundary-event label. */
+            label?: string;
+        };
+    }
+}
+declare module "../declarative.js" {
+    interface FlowBuilder<C extends object> {
+        /**
+         * Attach an interrupting timer boundary event (an SLA) to the PRECEDING
+         * activity (a `run`/`task`). When `timer` elapses, the activity is
+         * cancelled (for an interrupting boundary) and the token routes to the
+         * `onTimeout` escalation body; that body then converges with the activity's
+         * normal continuation. `timer` is an ISO-8601 duration or a FEEL
+         * `=`-expression. Chains as `w.run(...).boundary({ timer, onTimeout })`.
+         */
+        boundary(opts: BoundaryOptions<C>): FlowBuilder<C>;
+    }
+}

package/dist/nodes/boundary.js

@@ -0,0 +1,92 @@
+// Flow-node kind: `boundary` — an activity-level attached interrupting timer
+// boundary event (an SLA). Chained onto the activity it guards, it attaches a
+// `<bpmn:boundaryEvent … attachedToRef=… ><bpmn:timerEventDefinition>` to that
+// activity: when the timer elapses the activity is cancelled (interrupting) and
+// the token routes to the `onTimeout` escalation body, which then converges with
+// the activity's normal continuation. Contributed entirely from this module
+// through the extension seam (epic #314, S2/#317) — NO edit to the shared
+// `FlowNode` union, the `walkNodes`/`emitNode` dispatch, or the generated barrel.
+import { outgoingOnly } from "../declarative.js";
+import { assertTimerDuration, escapeXml } from "../xml.js";
+import { registerNodeKind } from "./registry.js";
+/** The flow-node kinds a boundary event may attach to. BPMN restricts boundary
+ *  events to ACTIVITIES, so this is the set of activity kinds (the ones that
+ *  render as a `<bpmn:serviceTask>`) — NOT merely "any node with a `name`", which
+ *  would also admit catch events like `signal`/`timer` and produce invalid BPMN. */
+const BOUNDARY_HOST_KINDS = new Set(["run", "task"]);
+/** True for a FEEL expression body (a leading `=`), which renders with an
+ *  `xsi:type="bpmn:tFormalExpression"` marker on the `timeDuration`. */
+function isFeel(value) {
+    return value.startsWith("=");
+}
+function renderBoundary(id, node, outg) {
+    const nameAttr = node.label ? ` name="${escapeXml(node.label)}"` : "";
+    // An interrupting boundary omits `cancelActivity` (its BPMN default is true),
+    // matching the hand-authored nwf goldens; a non-interrupting one is explicit.
+    const cancelAttr = node.interrupting ? "" : ` cancelActivity="false"`;
+    const durType = isFeel(node.timer) ? ` xsi:type="bpmn:tFormalExpression"` : "";
+    return (`    <bpmn:boundaryEvent id="${id}"${nameAttr} attachedToRef="${escapeXml(node.attachedTo)}"${cancelAttr}>\n` +
+        `      ${outgoingOnly(outg)}\n` +
+        `      <bpmn:timerEventDefinition>\n` +
+        `        <bpmn:timeDuration${durType}>${escapeXml(node.timer)}</bpmn:timeDuration>\n` +
+        `      </bpmn:timerEventDefinition>\n` +
+        `    </bpmn:boundaryEvent>`);
+}
+registerNodeKind("boundary", {
+    build: (api) => (opts) => {
+        if (!opts || typeof opts !== "object") {
+            throw new Error(`boundary(...) needs { timer, onTimeout }`);
+        }
+        if (typeof opts.timer !== "string" || opts.timer.trim() === "") {
+            throw new Error(`boundary(...) needs a { timer } duration (an ISO-8601 duration or a FEEL =expression)`);
+        }
+        const duration = opts.timer.trim();
+        assertTimerDuration("boundary(...) timer", duration);
+        if (typeof opts.onTimeout !== "function") {
+            throw new Error(`boundary(...) needs an { onTimeout } escalation body (b) => {…}`);
+        }
+        if (opts.interrupting !== undefined && typeof opts.interrupting !== "boolean") {
+            throw new Error(`boundary(...) { interrupting } must be a boolean`);
+        }
+        if (opts.name !== undefined && typeof opts.name !== "string") {
+            throw new Error(`boundary(...) { name } must be a string`);
+        }
+        const host = api.out[api.out.length - 1];
+        if (!host) {
+            throw new Error(`boundary(...) must follow the activity it attaches to (e.g. w.run(...).boundary(...))`);
+        }
+        if (!BOUNDARY_HOST_KINDS.has(host.kind) || !("name" in host) || typeof host.name !== "string") {
+            throw new Error(`boundary(...) can only attach to a named activity (run/task), not a "${host.kind}"`);
+        }
+        const onTimeout = api.child(opts.onTimeout, false);
+        if (onTimeout.length === 0) {
+            throw new Error(`boundary(...) needs a non-empty { onTimeout } escalation body (its outgoing flow has nowhere to go)`);
+        }
+        api.out.push({
+            kind: "boundary",
+            attachedTo: host.name,
+            timer: duration,
+            interrupting: opts.interrupting ?? true,
+            onTimeout,
+            label: opts.name,
+        });
+        return api.self();
+    },
+    walk: (node, recurse) => {
+        recurse(node.onTimeout);
+    },
+    emit: (node, incoming, loop, api) => {
+        // A boundary event has NO incoming sequence flow — it attaches to its host
+        // via `attachedToRef`. Place it, wire its outgoing to the escalation body,
+        // and return the host's normal continuation (`incoming`, passed through)
+        // PLUS the escalation danglers, so both converge on whatever follows.
+        const beId = `Be_${api.nextGw()}`;
+        api.addNode({
+            id: beId,
+            render: (_inc, outg) => renderBoundary(beId, node, outg),
+        });
+        const escalation = api.newEdge(beId);
+        const escOut = api.emitList(node.onTimeout, [escalation], loop);
+        return [...incoming, ...escOut];
+    },
+});

package/dist/nodes/index.d.ts

@@ -1,3 +1,4 @@
+import "./boundary.js";
 import "./branch.js";
 import "./break.js";
 import "./continue.js";

package/dist/nodes/index.js

@@ -5,6 +5,7 @@
 // table `makeBuilder`/`walkNodes`/the emitter route through. A new kind is
 // picked up automatically by re-running the generator (a prebuild step) — no
 // hand-edit here.
+import "./boundary.js";
 import "./branch.js";
 import "./break.js";
 import "./continue.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.10.0",
+  "version": "0.11.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 through @nanobpm/nano-sdk (the shared engine-transport spine — ADR 0055), which negotiates the Falcon protocol on a Nano server and REST elsewhere.",
   "type": "module",
   "license": "Apache-2.0",

package/src/declarative.ts

@@ -933,6 +933,7 @@ class Compiler {
     return (
       `<?xml version="1.0" encoding="UTF-8"?>\n` +
       `<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" ` +
+      `xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ` +
       `xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" ` +
       `xmlns:nano="https://nanobpm.io/schema/shapes/1.0" ` +
       `id="Definitions_${escapeXml(this.flow.id)}" targetNamespace="http://bpmn.io/schema/bpmn">\n` +

package/src/index.ts

@@ -43,6 +43,9 @@ export { defineWorkflow, imperativeToBpmn, replayOnce } from "./imperative.js";
 export type { Journal, ReplayStep } from "./imperative.js";
 export { defineFlow, declarativeToBpmn, externalJobTypes, walkNodes } from "./declarative.js";
 export type { FlowBuilder } from "./declarative.js";
+// The `.boundary(...)` option type (its builder method augments FlowBuilder from
+// the boundary kind module — S2/#317).
+export type { BoundaryOptions } from "./nodes/boundary.js";
 export { layoutBpmn, declarativeToLayoutedBpmn } from "./layout.js";
 export { envelope } from "./envelope.js";
 export type {

package/src/nodes/boundary.ts

@@ -0,0 +1,149 @@
+// Flow-node kind: `boundary` — an activity-level attached interrupting timer
+// boundary event (an SLA). Chained onto the activity it guards, it attaches a
+// `<bpmn:boundaryEvent … attachedToRef=… ><bpmn:timerEventDefinition>` to that
+// activity: when the timer elapses the activity is cancelled (interrupting) and
+// the token routes to the `onTimeout` escalation body, which then converges with
+// the activity's normal continuation. Contributed entirely from this module
+// through the extension seam (epic #314, S2/#317) — NO edit to the shared
+// `FlowNode` union, the `walkNodes`/`emitNode` dispatch, or the generated barrel.
+
+import type { FlowNode } from "../types.js";
+import type { Block, Edge } from "../declarative.js";
+import { outgoingOnly } from "../declarative.js";
+import { assertTimerDuration, escapeXml } from "../xml.js";
+import { registerNodeKind } from "./registry.js";
+
+/** Options for `.boundary(...)`: an attached timer SLA on the preceding activity.
+ *  - `timer` — the timeout: an ISO-8601 duration (`PT24H`, `P1DT6H`) or a FEEL
+ *    `=`-expression (`=escalationSlaTimeout`); the duration need not be a literal.
+ *  - `onTimeout` — the escalation body run when the timer elapses (its danglers
+ *    converge with the activity's normal continuation).
+ *  - `interrupting` — whether firing cancels the host activity. Defaults to
+ *    `true` (an interrupting boundary; `cancelActivity` omitted, the BPMN default).
+ *    Pass `false` for a non-interrupting boundary (`cancelActivity="false"`).
+ *  - `name` — an optional label for the boundary event. */
+export interface BoundaryOptions<C extends object = object> {
+  timer: string;
+  onTimeout: Block<C>;
+  interrupting?: boolean;
+  name?: string;
+}
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    boundary: {
+      kind: "boundary";
+      /** The derived element id of the activity this boundary attaches to. */
+      attachedTo: string;
+      /** The timeout — an ISO-8601 duration or a FEEL `=`-expression. */
+      timer: string;
+      /** Whether firing cancels the host (interrupting). */
+      interrupting: boolean;
+      /** The escalation body wired from the boundary event's outgoing flow. */
+      onTimeout: FlowNode[];
+      /** Optional boundary-event label. */
+      label?: string;
+    };
+  }
+}
+
+declare module "../declarative.js" {
+  interface FlowBuilder<C extends object> {
+    /**
+     * Attach an interrupting timer boundary event (an SLA) to the PRECEDING
+     * activity (a `run`/`task`). When `timer` elapses, the activity is
+     * cancelled (for an interrupting boundary) and the token routes to the
+     * `onTimeout` escalation body; that body then converges with the activity's
+     * normal continuation. `timer` is an ISO-8601 duration or a FEEL
+     * `=`-expression. Chains as `w.run(...).boundary({ timer, onTimeout })`.
+     */
+    boundary(opts: BoundaryOptions<C>): FlowBuilder<C>;
+  }
+}
+
+/** The flow-node kinds a boundary event may attach to. BPMN restricts boundary
+ *  events to ACTIVITIES, so this is the set of activity kinds (the ones that
+ *  render as a `<bpmn:serviceTask>`) — NOT merely "any node with a `name`", which
+ *  would also admit catch events like `signal`/`timer` and produce invalid BPMN. */
+const BOUNDARY_HOST_KINDS = new Set(["run", "task"]);
+
+/** True for a FEEL expression body (a leading `=`), which renders with an
+ *  `xsi:type="bpmn:tFormalExpression"` marker on the `timeDuration`. */
+function isFeel(value: string): boolean {
+  return value.startsWith("=");
+}
+
+function renderBoundary(id: string, node: Extract<FlowNode, { kind: "boundary" }>, outg: string[]): string {
+  const nameAttr = node.label ? ` name="${escapeXml(node.label)}"` : "";
+  // An interrupting boundary omits `cancelActivity` (its BPMN default is true),
+  // matching the hand-authored nwf goldens; a non-interrupting one is explicit.
+  const cancelAttr = node.interrupting ? "" : ` cancelActivity="false"`;
+  const durType = isFeel(node.timer) ? ` xsi:type="bpmn:tFormalExpression"` : "";
+  return (
+    `    <bpmn:boundaryEvent id="${id}"${nameAttr} attachedToRef="${escapeXml(node.attachedTo)}"${cancelAttr}>\n` +
+    `      ${outgoingOnly(outg)}\n` +
+    `      <bpmn:timerEventDefinition>\n` +
+    `        <bpmn:timeDuration${durType}>${escapeXml(node.timer)}</bpmn:timeDuration>\n` +
+    `      </bpmn:timerEventDefinition>\n` +
+    `    </bpmn:boundaryEvent>`
+  );
+}
+
+registerNodeKind("boundary", {
+  build: (api) => (opts: BoundaryOptions) => {
+    if (!opts || typeof opts !== "object") {
+      throw new Error(`boundary(...) needs { timer, onTimeout }`);
+    }
+    if (typeof opts.timer !== "string" || opts.timer.trim() === "") {
+      throw new Error(`boundary(...) needs a { timer } duration (an ISO-8601 duration or a FEEL =expression)`);
+    }
+    const duration = opts.timer.trim();
+    assertTimerDuration("boundary(...) timer", duration);
+    if (typeof opts.onTimeout !== "function") {
+      throw new Error(`boundary(...) needs an { onTimeout } escalation body (b) => {…}`);
+    }
+    if (opts.interrupting !== undefined && typeof opts.interrupting !== "boolean") {
+      throw new Error(`boundary(...) { interrupting } must be a boolean`);
+    }
+    if (opts.name !== undefined && typeof opts.name !== "string") {
+      throw new Error(`boundary(...) { name } must be a string`);
+    }
+    const host = api.out[api.out.length - 1];
+    if (!host) {
+      throw new Error(`boundary(...) must follow the activity it attaches to (e.g. w.run(...).boundary(...))`);
+    }
+    if (!BOUNDARY_HOST_KINDS.has(host.kind) || !("name" in host) || typeof host.name !== "string") {
+      throw new Error(`boundary(...) can only attach to a named activity (run/task), not a "${host.kind}"`);
+    }
+    const onTimeout = api.child(opts.onTimeout, false);
+    if (onTimeout.length === 0) {
+      throw new Error(`boundary(...) needs a non-empty { onTimeout } escalation body (its outgoing flow has nowhere to go)`);
+    }
+    api.out.push({
+      kind: "boundary",
+      attachedTo: host.name,
+      timer: duration,
+      interrupting: opts.interrupting ?? true,
+      onTimeout,
+      label: opts.name,
+    });
+    return api.self();
+  },
+  walk: (node, recurse) => {
+    recurse(node.onTimeout);
+  },
+  emit: (node, incoming, loop, api) => {
+    // A boundary event has NO incoming sequence flow — it attaches to its host
+    // via `attachedToRef`. Place it, wire its outgoing to the escalation body,
+    // and return the host's normal continuation (`incoming`, passed through)
+    // PLUS the escalation danglers, so both converge on whatever follows.
+    const beId = `Be_${api.nextGw()}`;
+    api.addNode({
+      id: beId,
+      render: (_inc, outg) => renderBoundary(beId, node, outg),
+    });
+    const escalation: Edge = api.newEdge(beId);
+    const escOut = api.emitList(node.onTimeout, [escalation], loop);
+    return [...incoming, ...escOut];
+  },
+});

package/src/nodes/index.ts

@@ -6,6 +6,7 @@
 // picked up automatically by re-running the generator (a prebuild step) — no
 // hand-edit here.
 
+import "./boundary.js";
 import "./branch.js";
 import "./break.js";
 import "./continue.js";