@nanobpm/workflow 0.13.0 → 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/client.d.ts

@@ -66,6 +66,37 @@ export interface NanoJobWorker {
         waitUpToMs?: number;
     }): Promise<void>;
 }
+/** The subset of a raw `@nanobpm/nano-sdk` job worker the adapter drives. Its
+ *  `start()` may be synchronous or async: on nano-sdk >=1.2.5's Falcon/auto path
+ *  it is async and the SDK self-starts the worker after an asynchronous transport
+ *  bind (see {@link adaptJobWorker}). */
+export interface RawNanoJobWorker {
+    start(): void | Promise<void>;
+    stop(): void | Promise<void>;
+    stopGracefully(opts?: {
+        waitUpToMs?: number;
+    }): Promise<unknown>;
+}
+/** Adapt a raw `@nanobpm/nano-sdk` job worker to the {@link NanoJobWorker} handle
+ *  the Worker runtime drives, making the eager `start()` NULL-SAFE.
+ *
+ *  nano-sdk >=1.2.5's Falcon/auto worker SELF-STARTS after an ASYNCHRONOUS
+ *  transport bind: `createJobWorker` hands back a worker whose transport is null
+ *  until Nano is detected, at which point the SDK `bindTransport(t)`s it and
+ *  `start()`s the worker ITSELF. Calling `start()` before that bind dereferences
+ *  the null transport and — because `start()` is async — surfaces as an UNHANDLED
+ *  REJECTION that crashes the process
+ *  (`TypeError: Cannot read properties of null (reading 'subscribe')`, #415). The
+ *  REST/manual worker, by contrast, never self-starts, so `start()` must still be
+ *  called here. We resolve the version-skew by starting eagerly but NULL-SAFELY:
+ *  swallow ONLY the pre-bind race (the SDK self-starts once the transport binds)
+ *  and SURFACE any other start failure via `console.warn` rather than masking it.
+ *  The SDK owns the start lifecycle end to end (it logs and falls back to REST on
+ *  its own subscribe failure), so discarding the resolved result — as the previous
+ *  `void worker.start()` already did — is safe. Pairs with the library-side
+ *  null-safe, idempotent start (jwulf/nano-sdk-js#12) so neither an eager nor a
+ *  duplicate start can crash. */
+export declare function adaptJobWorker(worker: RawNanoJobWorker): NanoJobWorker;
 /** An activated job as delivered to a nano-sdk job handler: the workflow `Job`
  *  fields plus the acknowledgement actions. */
 export type ActivatedJob = Job & {

package/dist/client.js

@@ -96,6 +96,71 @@ export async function toDeployableBpmn(wf, opts = {}) {
         return semantic;
     }
 }
+/** Adapt a raw `@nanobpm/nano-sdk` job worker to the {@link NanoJobWorker} handle
+ *  the Worker runtime drives, making the eager `start()` NULL-SAFE.
+ *
+ *  nano-sdk >=1.2.5's Falcon/auto worker SELF-STARTS after an ASYNCHRONOUS
+ *  transport bind: `createJobWorker` hands back a worker whose transport is null
+ *  until Nano is detected, at which point the SDK `bindTransport(t)`s it and
+ *  `start()`s the worker ITSELF. Calling `start()` before that bind dereferences
+ *  the null transport and — because `start()` is async — surfaces as an UNHANDLED
+ *  REJECTION that crashes the process
+ *  (`TypeError: Cannot read properties of null (reading 'subscribe')`, #415). The
+ *  REST/manual worker, by contrast, never self-starts, so `start()` must still be
+ *  called here. We resolve the version-skew by starting eagerly but NULL-SAFELY:
+ *  swallow ONLY the pre-bind race (the SDK self-starts once the transport binds)
+ *  and SURFACE any other start failure via `console.warn` rather than masking it.
+ *  The SDK owns the start lifecycle end to end (it logs and falls back to REST on
+ *  its own subscribe failure), so discarding the resolved result — as the previous
+ *  `void worker.start()` already did — is safe. Pairs with the library-side
+ *  null-safe, idempotent start (jwulf/nano-sdk-js#12) so neither an eager nor a
+ *  duplicate start can crash. */
+export function adaptJobWorker(worker) {
+    return {
+        start: () => {
+            try {
+                const started = worker.start();
+                if (isPromiseLike(started))
+                    started.then(undefined, handleStartError);
+            }
+            catch (e) {
+                handleStartError(e);
+            }
+        },
+        stop: () => worker.stop(),
+        stopGracefully: async (opts) => {
+            await worker.stopGracefully(opts);
+        },
+    };
+}
+function isPromiseLike(v) {
+    return isRecord(v) && typeof v.then === "function";
+}
+/** The SDK's pre-bind start race is a NULL/undefined-transport dereference the SDK
+ *  recovers from via its own self-start: a `TypeError` from reading the transport's
+ *  `subscribe` off a `null`/`undefined` transport
+ *  (`Cannot read properties of null (reading 'subscribe')`, #415). Match it NARROWLY
+ *  — the specific `subscribe` dereference signature, not any null/undefined deref —
+ *  so a genuine start failure on the REST/manual path (or an unrelated null-deref
+ *  bug during `start()`) is never mistaken for the race and silently masked. */
+function isPreBindStartRace(e) {
+    return (e instanceof TypeError &&
+        /Cannot read propert(?:y|ies) of (?:null|undefined) \(reading ['"]subscribe['"]\)/.test(e.message));
+}
+/** Handle an eager-start error NULL-SAFELY. Swallow ONLY the SDK's known pre-bind
+ *  transport race (it self-starts once its transport binds — see
+ *  {@link adaptJobWorker}); any OTHER error is a real start failure (e.g. on the
+ *  REST/manual path) and is SURFACED via `console.warn` so it is not silently
+ *  masked. Never rethrows — callers rely on this to keep an async `start()` from
+ *  escaping as an unhandled rejection that crashes the process. The SDK owns the
+ *  start lifecycle end to end (it logs and falls back to REST on its own subscribe
+ *  failure), so we surface-and-continue rather than propagate. */
+function handleStartError(e) {
+    if (isPreBindStartRace(e))
+        return;
+    console.warn("[@nanobpm/workflow] job worker start() failed (not the known pre-bind transport " +
+        "race); the SDK owns start and REST fallback, so this is surfaced but not rethrown:", e);
+}
 export class WorkflowError extends Error {
     status;
     body;
@@ -153,15 +218,7 @@ export class WorkflowClient {
                         return JobActionReceiptSymbol;
                     },
                 });
-                return {
-                    start: () => {
-                        void worker.start();
-                    },
-                    stop: () => worker.stop(),
-                    stopGracefully: async (opts) => {
-                        await worker.stopGracefully(opts);
-                    },
-                };
+                return adaptJobWorker(worker);
             },
         };
     }

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.0",
+  "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/client.ts

@@ -154,6 +154,87 @@ export interface NanoJobWorker {
   stopGracefully?(opts?: { waitUpToMs?: number }): Promise<void>;
 }
 
+/** The subset of a raw `@nanobpm/nano-sdk` job worker the adapter drives. Its
+ *  `start()` may be synchronous or async: on nano-sdk >=1.2.5's Falcon/auto path
+ *  it is async and the SDK self-starts the worker after an asynchronous transport
+ *  bind (see {@link adaptJobWorker}). */
+export interface RawNanoJobWorker {
+  start(): void | Promise<void>;
+  stop(): void | Promise<void>;
+  stopGracefully(opts?: { waitUpToMs?: number }): Promise<unknown>;
+}
+
+/** Adapt a raw `@nanobpm/nano-sdk` job worker to the {@link NanoJobWorker} handle
+ *  the Worker runtime drives, making the eager `start()` NULL-SAFE.
+ *
+ *  nano-sdk >=1.2.5's Falcon/auto worker SELF-STARTS after an ASYNCHRONOUS
+ *  transport bind: `createJobWorker` hands back a worker whose transport is null
+ *  until Nano is detected, at which point the SDK `bindTransport(t)`s it and
+ *  `start()`s the worker ITSELF. Calling `start()` before that bind dereferences
+ *  the null transport and — because `start()` is async — surfaces as an UNHANDLED
+ *  REJECTION that crashes the process
+ *  (`TypeError: Cannot read properties of null (reading 'subscribe')`, #415). The
+ *  REST/manual worker, by contrast, never self-starts, so `start()` must still be
+ *  called here. We resolve the version-skew by starting eagerly but NULL-SAFELY:
+ *  swallow ONLY the pre-bind race (the SDK self-starts once the transport binds)
+ *  and SURFACE any other start failure via `console.warn` rather than masking it.
+ *  The SDK owns the start lifecycle end to end (it logs and falls back to REST on
+ *  its own subscribe failure), so discarding the resolved result — as the previous
+ *  `void worker.start()` already did — is safe. Pairs with the library-side
+ *  null-safe, idempotent start (jwulf/nano-sdk-js#12) so neither an eager nor a
+ *  duplicate start can crash. */
+export function adaptJobWorker(worker: RawNanoJobWorker): NanoJobWorker {
+  return {
+    start: () => {
+      try {
+        const started = worker.start();
+        if (isPromiseLike(started)) started.then(undefined, handleStartError);
+      } catch (e) {
+        handleStartError(e);
+      }
+    },
+    stop: () => worker.stop(),
+    stopGracefully: async (opts) => {
+      await worker.stopGracefully(opts);
+    },
+  };
+}
+
+function isPromiseLike(v: unknown): v is PromiseLike<unknown> {
+  return isRecord(v) && typeof v.then === "function";
+}
+
+/** The SDK's pre-bind start race is a NULL/undefined-transport dereference the SDK
+ *  recovers from via its own self-start: a `TypeError` from reading the transport's
+ *  `subscribe` off a `null`/`undefined` transport
+ *  (`Cannot read properties of null (reading 'subscribe')`, #415). Match it NARROWLY
+ *  — the specific `subscribe` dereference signature, not any null/undefined deref —
+ *  so a genuine start failure on the REST/manual path (or an unrelated null-deref
+ *  bug during `start()`) is never mistaken for the race and silently masked. */
+function isPreBindStartRace(e: unknown): boolean {
+  return (
+    e instanceof TypeError &&
+    /Cannot read propert(?:y|ies) of (?:null|undefined) \(reading ['"]subscribe['"]\)/.test(e.message)
+  );
+}
+
+/** Handle an eager-start error NULL-SAFELY. Swallow ONLY the SDK's known pre-bind
+ *  transport race (it self-starts once its transport binds — see
+ *  {@link adaptJobWorker}); any OTHER error is a real start failure (e.g. on the
+ *  REST/manual path) and is SURFACED via `console.warn` so it is not silently
+ *  masked. Never rethrows — callers rely on this to keep an async `start()` from
+ *  escaping as an unhandled rejection that crashes the process. The SDK owns the
+ *  start lifecycle end to end (it logs and falls back to REST on its own subscribe
+ *  failure), so we surface-and-continue rather than propagate. */
+function handleStartError(e: unknown): void {
+  if (isPreBindStartRace(e)) return;
+  console.warn(
+    "[@nanobpm/workflow] job worker start() failed (not the known pre-bind transport " +
+      "race); the SDK owns start and REST fallback, so this is surfaced but not rethrown:",
+    e,
+  );
+}
+
 /** An activated job as delivered to a nano-sdk job handler: the workflow `Job`
  *  fields plus the acknowledgement actions. */
 export type ActivatedJob = Job & {
@@ -253,15 +334,7 @@ export class WorkflowClient {
             return JobActionReceiptSymbol;
           },
         });
-        return {
-          start: () => {
-            void worker.start();
-          },
-          stop: () => worker.stop(),
-          stopGracefully: async (opts) => {
-            await worker.stopGracefully(opts);
-          },
-        };
+        return adaptJobWorker(worker);
       },
     };
   }

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];
   },
 });