@nanobpm/workflow 0.15.1 → 0.16.0

package/README.md

@@ -105,6 +105,19 @@ const { processInstanceKey } = await client.start(onboarding, {});
 await client.signal(onboarding, "approved", userId, { by: "alice" });
 ```
 
+A long-running step (transcription, an agent call, a multi-GB upload) can
+outlive the engine's default job lock: the lease expires mid-handler, the
+engine re-activates the job, and a second worker runs it again. Declare the
+lock timeout per step with `w.run(name, handler, { timeoutMs })` (overrides the
+`Worker`'s worker-wide `jobTimeoutMs`, default 30s, for that step's job type):
+
+```ts
+const flow = defineFlow("uploads", (w) => {
+  w.run("transcode", transcode, { timeoutMs: 3_600_000 }); // 1h lock for this step
+  w.run("notify", notify);
+});
+```
+
 A human-in-the-loop **approval gate** with a form, an assignment, and an output
 mapping that stamps the decision back onto a process variable:
 

package/dist/declarative.d.ts

@@ -45,6 +45,12 @@ export interface FlowBuilder<C extends object = object> {
      */
     run<K extends string>(name: K, handler: TypedHandler<VarsOf<C, K>, ResultOf<C, K>>, opts?: {
         io?: HumanIoMapping;
+        /** Job lock timeout, ms, for this step's derived worker (issue #596): how long the
+         *  engine leases an activated job before re-activating it elsewhere. Set it above the
+         *  handler's worst-case runtime for long steps (transcription, an agent call, a
+         *  multi-GB upload) so the lock cannot expire mid-handler and the job run twice.
+         *  Overrides the `Worker`'s worker-wide `jobTimeoutMs` for this step's job type. */
+        timeoutMs?: number;
     }): FlowBuilder<C>;
     /**
      * A durable activity served by a worker OUTSIDE this program (a BPMN service

package/dist/nodes/run.d.ts

@@ -6,6 +6,7 @@ declare module "../types.js" {
             name: string;
             envelopes?: NodeEnvelopes;
             io?: HumanIoMapping;
+            timeoutMs?: number;
         };
     }
 }

package/dist/nodes/run.js

@@ -11,8 +11,18 @@ registerNodeKind("run", {
         if (typeof handler !== "function")
             throw new Error(`run("${name}") needs a handler function`);
         assertIoMapping(`run("${name}")`, opts?.io);
+        const timeoutMs = opts?.timeoutMs;
+        if (timeoutMs !== undefined && (!Number.isInteger(timeoutMs) || timeoutMs <= 0)) {
+            throw new Error(`run("${name}"): timeoutMs must be a positive integer (ms)`);
+        }
         api.handlers[name] = handler;
-        api.out.push({ kind: "run", name, envelopes: api.contractEnvelopes(name), io: opts?.io });
+        api.out.push({
+            kind: "run",
+            name,
+            envelopes: api.contractEnvelopes(name),
+            io: opts?.io,
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        });
         return api.self();
     },
     emit: (node, incoming, _loop, api) => {

package/dist/worker.d.ts

@@ -54,6 +54,9 @@ export declare class Worker {
     private readonly onError?;
     /** job type → { workflowId, handle } */
     private readonly routes;
+    /** Job lock timeout (ms) per derived job type, from a `run` step's `{ timeoutMs }`
+     *  (issue #596). Overrides the worker-wide `jobTimeoutMs` for that type. */
+    private readonly typeTimeoutMs;
     private running;
     private workers;
     constructor(opts: WorkerOptions);

package/dist/worker.js

@@ -30,6 +30,9 @@ export class Worker {
     onError;
     /** job type → { workflowId, handle } */
     routes = new Map();
+    /** Job lock timeout (ms) per derived job type, from a `run` step's `{ timeoutMs }`
+     *  (issue #596). Overrides the worker-wide `jobTimeoutMs` for that type. */
+    typeTimeoutMs = new Map();
     running = false;
     workers = [];
     constructor(opts) {
@@ -87,6 +90,10 @@ export class Worker {
                         return { variables };
                     },
                 });
+                // A step-declared job lock timeout (issue #596) applies to this step's derived
+                // job type, overriding the worker-wide `jobTimeoutMs` at `start()`.
+                if (s.timeoutMs !== undefined)
+                    this.typeTimeoutMs.set(jobType(wf.id, s.name), s.timeoutMs);
             });
         }
     }
@@ -141,7 +148,8 @@ export class Worker {
                 jobType: type,
                 workerName: this.name,
                 maxParallelJobs: this.maxParallelJobs,
-                jobTimeoutMs: this.jobTimeoutMs,
+                // A step-declared `{ timeoutMs }` (issue #596) wins over the worker-wide default.
+                jobTimeoutMs: this.typeTimeoutMs.get(type) ?? this.jobTimeoutMs,
                 pollTimeoutMs: this.pollTimeoutMs,
                 autoStart: false,
                 jobHandler: (job) => this.handleJob(type, route, job),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.15.1",
+  "version": "0.16.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

@@ -102,7 +102,15 @@ export interface FlowBuilder<C extends object = object> {
   run<K extends string>(
     name: K,
     handler: TypedHandler<VarsOf<C, K>, ResultOf<C, K>>,
-    opts?: { io?: HumanIoMapping },
+    opts?: {
+      io?: HumanIoMapping;
+      /** Job lock timeout, ms, for this step's derived worker (issue #596): how long the
+       *  engine leases an activated job before re-activating it elsewhere. Set it above the
+       *  handler's worst-case runtime for long steps (transcription, an agent call, a
+       *  multi-GB upload) so the lock cannot expire mid-handler and the job run twice.
+       *  Overrides the `Worker`'s worker-wide `jobTimeoutMs` for this step's job type. */
+      timeoutMs?: number;
+    },
   ): FlowBuilder<C>;
   /**
    * A durable activity served by a worker OUTSIDE this program (a BPMN service

package/src/nodes/run.ts

@@ -11,17 +11,27 @@ import { registerNodeKind } from "./registry.js";
 
 declare module "../types.js" {
   interface FlowNodeRegistry {
-    run: { kind: "run"; name: string; envelopes?: NodeEnvelopes; io?: HumanIoMapping };
+    run: { kind: "run"; name: string; envelopes?: NodeEnvelopes; io?: HumanIoMapping; timeoutMs?: number };
   }
 }
 
 registerNodeKind("run", {
-  build: (api) => (name: string, handler: StepHandler, opts?: { io?: HumanIoMapping }) => {
+  build: (api) => (name: string, handler: StepHandler, opts?: { io?: HumanIoMapping; timeoutMs?: number }) => {
     api.claim(name);
     if (typeof handler !== "function") throw new Error(`run("${name}") needs a handler function`);
     assertIoMapping(`run("${name}")`, opts?.io);
+    const timeoutMs = opts?.timeoutMs;
+    if (timeoutMs !== undefined && (!Number.isInteger(timeoutMs) || timeoutMs <= 0)) {
+      throw new Error(`run("${name}"): timeoutMs must be a positive integer (ms)`);
+    }
     api.handlers[name] = handler;
-    api.out.push({ kind: "run", name, envelopes: api.contractEnvelopes(name), io: opts?.io });
+    api.out.push({
+      kind: "run",
+      name,
+      envelopes: api.contractEnvelopes(name),
+      io: opts?.io,
+      ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    });
     return api.self();
   },
   emit: (node, incoming, _loop, api) => {

package/src/worker.ts

@@ -84,6 +84,9 @@ export class Worker {
   private readonly onError?: WorkerOptions["onError"];
   /** job type → { workflowId, handle } */
   private readonly routes = new Map<string, { workflowId: string; handle: Handler }>();
+  /** Job lock timeout (ms) per derived job type, from a `run` step's `{ timeoutMs }`
+   *  (issue #596). Overrides the worker-wide `jobTimeoutMs` for that type. */
+  private readonly typeTimeoutMs = new Map<string, number>();
   private running = false;
   private workers: NanoJobWorker[] = [];
 
@@ -142,6 +145,9 @@ export class Worker {
             return { variables };
           },
         });
+        // A step-declared job lock timeout (issue #596) applies to this step's derived
+        // job type, overriding the worker-wide `jobTimeoutMs` at `start()`.
+        if (s.timeoutMs !== undefined) this.typeTimeoutMs.set(jobType(wf.id, s.name), s.timeoutMs);
       });
     }
   }
@@ -200,7 +206,8 @@ export class Worker {
         jobType: type,
         workerName: this.name,
         maxParallelJobs: this.maxParallelJobs,
-        jobTimeoutMs: this.jobTimeoutMs,
+        // A step-declared `{ timeoutMs }` (issue #596) wins over the worker-wide default.
+        jobTimeoutMs: this.typeTimeoutMs.get(type) ?? this.jobTimeoutMs,
         pollTimeoutMs: this.pollTimeoutMs,
         autoStart: false,
         jobHandler: (job) => this.handleJob(type, route, job),