@nanobpm/workflow 0.13.1 → 0.14.0

package/README.md

@@ -73,13 +73,19 @@ approval gate rendered on a task list), 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
+- `w.run(...).boundary({ timer, onTimeout, interrupting?, fireAndForget?, name? })`
+  — attach an SLA (a timer boundary event) to the PRECEDING
+  activity: when `timer` elapses the boundary fires and the token routes to
+  the `onTimeout` escalation body, which then converges with the activity's normal
+  continuation (and, for an interrupting boundary — the default — the host activity
+  is cancelled). `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).
+  Pass `fireAndForget: true` for a NON-CONVERGING escape path — the `onTimeout`
+  body ends in a `<bpmn:endEvent>` and contributes no danglers to the
+  continuation (the correct shape for a non-interrupting reviewer nudge: a
+  side-effect that ends its own token and must not re-enter the reviewed
+  activity).
 
 ```ts
 import { defineFlow, WorkflowClient, Worker } from "@nanobpm/workflow";

package/dist/nodes/boundary.d.ts

@@ -2,16 +2,25 @@ 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).
+ *  - `onTimeout` — the escalation body run when the timer elapses. By default its
+ *    danglers converge with the activity's normal continuation; with
+ *    `fireAndForget: true` the body is capped by an end event instead (see below).
  *  - `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"`).
+ *  - `fireAndForget` — when `true`, the `onTimeout` escalation body is a
+ *    NON-CONVERGING escape path: its danglers terminate in a `<bpmn:endEvent>`
+ *    rather than merging back into the host activity's continuation. This is the
+ *    correct model for a non-interrupting reviewer nudge (an SLA side-effect that
+ *    ends its own token and must NOT re-enter the reviewed activity). Defaults to
+ *    `false` (the converging boundary). Typically paired with
+ *    `interrupting: false`.
  *  - `name` — an optional label for the boundary event. */
 export interface BoundaryOptions<C extends object = object> {
     timer: string;
     onTimeout: Block<C>;
     interrupting?: boolean;
+    fireAndForget?: boolean;
     name?: string;
 }
 declare module "../types.js" {
@@ -24,6 +33,9 @@ declare module "../types.js" {
             timer: string;
             /** Whether firing cancels the host (interrupting). */
             interrupting: boolean;
+            /** When true, the escalation body is capped by an end event and does NOT
+             *  converge with the host activity's continuation (fire-and-forget). */
+            fireAndForget: boolean;
             /** The escalation body wired from the boundary event's outgoing flow. */
             onTimeout: FlowNode[];
             /** Optional boundary-event label. */
@@ -40,6 +52,11 @@ declare module "../declarative.js" {
          * `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 })`.
+         *
+         * Pass `fireAndForget: true` for a NON-CONVERGING escape path: the
+         * `onTimeout` body is capped by a `<bpmn:endEvent>` and contributes no
+         * danglers to the host continuation — the correct model for a
+         * non-interrupting reviewer nudge (typically with `interrupting: false`).
          */
         boundary(opts: BoundaryOptions<C>): FlowBuilder<C>;
     }

package/dist/nodes/boundary.js

@@ -1,11 +1,15 @@
-// Flow-node kind: `boundary` — an activity-level attached interrupting timer
-// boundary event (an SLA). Chained onto the activity it guards, it attaches a
+// Flow-node kind: `boundary` — an activity-level attached 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.
+// activity: when the timer elapses the boundary fires and the token routes to
+// the `onTimeout` escalation body (and, for an interrupting boundary — the
+// default — the host activity is cancelled; a non-interrupting boundary leaves
+// it running). By default the escalation body then converges with
+// the activity's normal continuation — OR, with `fireAndForget: true`, ends in a
+// `<bpmn:endEvent>` without converging (a non-converging escape path). 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";
@@ -48,6 +52,9 @@ registerNodeKind("boundary", {
         if (opts.interrupting !== undefined && typeof opts.interrupting !== "boolean") {
             throw new Error(`boundary(...) { interrupting } must be a boolean`);
         }
+        if (opts.fireAndForget !== undefined && typeof opts.fireAndForget !== "boolean") {
+            throw new Error(`boundary(...) { fireAndForget } must be a boolean`);
+        }
         if (opts.name !== undefined && typeof opts.name !== "string") {
             throw new Error(`boundary(...) { name } must be a string`);
         }
@@ -67,6 +74,7 @@ registerNodeKind("boundary", {
             attachedTo: host.name,
             timer: duration,
             interrupting: opts.interrupting ?? true,
+            fireAndForget: opts.fireAndForget ?? false,
             onTimeout,
             label: opts.name,
         });
@@ -78,8 +86,7 @@ registerNodeKind("boundary", {
     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.
+        // then either converge or fire-and-forget (see below).
         const beId = `Be_${api.nextGw()}`;
         api.addNode({
             id: beId,
@@ -87,6 +94,21 @@ registerNodeKind("boundary", {
         });
         const escalation = api.newEdge(beId);
         const escOut = api.emitList(node.onTimeout, [escalation], loop);
+        if (node.fireAndForget) {
+            // Fire-and-forget: cap the escalation body with a plain `<bpmn:endEvent>` so
+            // its token ENDS instead of converging into the host activity's
+            // continuation. Return only `incoming` (the host's own danglers), so the
+            // escape path contributes nothing to whatever follows the activity — no
+            // spurious second incoming on the reviewed task / downstream gateway.
+            if (escOut.length > 0) {
+                const endId = `${beId}_End`;
+                api.addPlainEnd(endId);
+                api.connect(escOut, endId);
+            }
+            return [...incoming];
+        }
+        // Converging boundary: return the host's normal continuation (`incoming`)
+        // PLUS the escalation danglers, so both converge on whatever follows.
         return [...incoming, ...escOut];
     },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.13.1",
+  "version": "0.14.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/nodes/boundary.ts

@@ -1,11 +1,15 @@
-// Flow-node kind: `boundary` — an activity-level attached interrupting timer
-// boundary event (an SLA). Chained onto the activity it guards, it attaches a
+// Flow-node kind: `boundary` — an activity-level attached 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.
+// activity: when the timer elapses the boundary fires and the token routes to
+// the `onTimeout` escalation body (and, for an interrupting boundary — the
+// default — the host activity is cancelled; a non-interrupting boundary leaves
+// it running). By default the escalation body then converges with
+// the activity's normal continuation — OR, with `fireAndForget: true`, ends in a
+// `<bpmn:endEvent>` without converging (a non-converging escape path). 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";
@@ -16,16 +20,25 @@ 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).
+ *  - `onTimeout` — the escalation body run when the timer elapses. By default its
+ *    danglers converge with the activity's normal continuation; with
+ *    `fireAndForget: true` the body is capped by an end event instead (see below).
  *  - `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"`).
+ *  - `fireAndForget` — when `true`, the `onTimeout` escalation body is a
+ *    NON-CONVERGING escape path: its danglers terminate in a `<bpmn:endEvent>`
+ *    rather than merging back into the host activity's continuation. This is the
+ *    correct model for a non-interrupting reviewer nudge (an SLA side-effect that
+ *    ends its own token and must NOT re-enter the reviewed activity). Defaults to
+ *    `false` (the converging boundary). Typically paired with
+ *    `interrupting: false`.
  *  - `name` — an optional label for the boundary event. */
 export interface BoundaryOptions<C extends object = object> {
   timer: string;
   onTimeout: Block<C>;
   interrupting?: boolean;
+  fireAndForget?: boolean;
   name?: string;
 }
 
@@ -39,6 +52,9 @@ declare module "../types.js" {
       timer: string;
       /** Whether firing cancels the host (interrupting). */
       interrupting: boolean;
+      /** When true, the escalation body is capped by an end event and does NOT
+       *  converge with the host activity's continuation (fire-and-forget). */
+      fireAndForget: boolean;
       /** The escalation body wired from the boundary event's outgoing flow. */
       onTimeout: FlowNode[];
       /** Optional boundary-event label. */
@@ -56,6 +72,11 @@ declare module "../declarative.js" {
      * `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 })`.
+     *
+     * Pass `fireAndForget: true` for a NON-CONVERGING escape path: the
+     * `onTimeout` body is capped by a `<bpmn:endEvent>` and contributes no
+     * danglers to the host continuation — the correct model for a
+     * non-interrupting reviewer nudge (typically with `interrupting: false`).
      */
     boundary(opts: BoundaryOptions<C>): FlowBuilder<C>;
   }
@@ -105,6 +126,9 @@ registerNodeKind("boundary", {
     if (opts.interrupting !== undefined && typeof opts.interrupting !== "boolean") {
       throw new Error(`boundary(...) { interrupting } must be a boolean`);
     }
+    if (opts.fireAndForget !== undefined && typeof opts.fireAndForget !== "boolean") {
+      throw new Error(`boundary(...) { fireAndForget } must be a boolean`);
+    }
     if (opts.name !== undefined && typeof opts.name !== "string") {
       throw new Error(`boundary(...) { name } must be a string`);
     }
@@ -124,6 +148,7 @@ registerNodeKind("boundary", {
       attachedTo: host.name,
       timer: duration,
       interrupting: opts.interrupting ?? true,
+      fireAndForget: opts.fireAndForget ?? false,
       onTimeout,
       label: opts.name,
     });
@@ -135,8 +160,7 @@ registerNodeKind("boundary", {
   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.
+    // then either converge or fire-and-forget (see below).
     const beId = `Be_${api.nextGw()}`;
     api.addNode({
       id: beId,
@@ -144,6 +168,21 @@ registerNodeKind("boundary", {
     });
     const escalation: Edge = api.newEdge(beId);
     const escOut = api.emitList(node.onTimeout, [escalation], loop);
+    if (node.fireAndForget) {
+      // Fire-and-forget: cap the escalation body with a plain `<bpmn:endEvent>` so
+      // its token ENDS instead of converging into the host activity's
+      // continuation. Return only `incoming` (the host's own danglers), so the
+      // escape path contributes nothing to whatever follows the activity — no
+      // spurious second incoming on the reviewed task / downstream gateway.
+      if (escOut.length > 0) {
+        const endId = `${beId}_End`;
+        api.addPlainEnd(endId);
+        api.connect(escOut, endId);
+      }
+      return [...incoming];
+    }
+    // Converging boundary: return the host's normal continuation (`incoming`)
+    // PLUS the escalation danglers, so both converge on whatever follows.
     return [...incoming, ...escOut];
   },
 });