@nanobpm/workflow 0.1.0 → 0.2.0

package/README.md

@@ -97,6 +97,12 @@ await client.signal(onboarding, "approved", userId, { by: "alice" });
 - **The determinism constraint binds only the imperative orchestration
   function**, not the activities. Do all non-deterministic / side-effecting work
   inside `ctx.run(name, fn)` closures — never in the orchestration body directly.
+- **Never swallow `ctx.run`'s suspension.** The imperative surface advances one
+  step per turn by *throwing* out of the orchestration body after the frontier
+  step. Do not wrap the orchestration body in a broad `try/catch` that catches
+  everything — catching that internal suspension breaks replay (multiple steps
+  could run in one turn, or the workflow could hang). Keep `try/catch` *inside*
+  individual `ctx.run(name, fn)` closures instead.
 - **The worker uses a single `baseUrl`.** For the single-user SDLC use case this
   is fine; it is a client SPOF (no worker-side failover), not an engine limit.
 

package/dist/client.d.ts

@@ -37,7 +37,9 @@ export declare class WorkflowClient {
      * declarative flows `input` becomes the instance variables directly.
      */
     start(wf: Workflow, input?: JsonObject): Promise<StartResult>;
-    /** 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). */
     signal(flow: DeclarativeFlow, signalName: string, correlationKey: string, variables?: JsonObject): Promise<JsonObject>;
     /** Fetch an instance (used by demos/tests to observe completion). */
     getInstance(processInstanceKey: string): Promise<JsonObject | null>;

package/dist/client.js

@@ -71,8 +71,14 @@ export class WorkflowClient {
             body: JSON.stringify({ processDefinitionId: wf.id, variables }),
         }, "start");
     }
-    /** 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, signalName, correlationKey, variables = {}) {
+        const signals = flow.steps.filter((s) => s.kind === "signal").map((s) => s.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(`/v2/messages/correlation`, {
             method: "POST",
             headers: { "content-type": "application/json" },

package/dist/declarative.d.ts

@@ -1,7 +1,16 @@
 import type { DeclarativeFlow, StepHandler } from "./types.js";
 export interface FlowBuilder {
-    /** A durable activity served by a worker (a BPMN service task). */
+    /** A durable activity served by a worker THIS program hosts (a BPMN service
+     *  task; the handler runs in the in-process `Worker`). */
     run(name: string, handler: StepHandler): FlowBuilder;
+    /**
+     * A durable activity served by a worker OUTSIDE this program (a BPMN service
+     * task with the same derived job type `${flowId}:${name}`, but no
+     * locally-hosted handler). The engine offers the job to whichever worker
+     * subscribes to that type — in another process, service, or language. Use
+     * `externalJobTypes(flow)` to list the contract those workers must poll.
+     */
+    task(name: string): FlowBuilder;
     /**
      * A durable wait for an external/human event, correlated on a process
      * variable (a BPMN message intermediate catch event). Resume it with
@@ -13,5 +22,9 @@ export interface FlowBuilder {
 }
 /** Define a declarative flow. `build(w)` declares an ordered list of steps. */
 export declare function defineFlow(id: string, build: (w: FlowBuilder) => void): DeclarativeFlow;
+/** The derived job types of a flow's external `task` steps — the contract that
+ *  workers outside this program must subscribe to (the engine offers those jobs
+ *  to whoever polls the type). Empty when the flow hosts all its own steps. */
+export declare function externalJobTypes(flow: DeclarativeFlow): string[];
 /** Derive an executable BPMN model from a declarative flow. */
 export declare function declarativeToBpmn(flow: DeclarativeFlow): string;

package/dist/declarative.js

@@ -29,6 +29,14 @@ export function defineFlow(id, build) {
             handlers[name] = handler;
             return w;
         },
+        task(name) {
+            assertIdent("step name", name);
+            if (seen.has(name))
+                throw new Error(`duplicate step name "${name}" in flow "${id}"`);
+            seen.add(name);
+            steps.push({ kind: "task", name });
+            return w;
+        },
         signal(name, opts) {
             assertIdent("step name", name);
             if (seen.has(name))
@@ -46,6 +54,12 @@ export function defineFlow(id, build) {
         throw new Error(`flow "${id}" declared no steps`);
     return { kind: "declarative", id, steps, handlers };
 }
+/** The derived job types of a flow's external `task` steps — the contract that
+ *  workers outside this program must subscribe to (the engine offers those jobs
+ *  to whoever polls the type). Empty when the flow hosts all its own steps. */
+export function externalJobTypes(flow) {
+    return flow.steps.filter((s) => s.kind === "task").map((s) => jobType(flow.id, s.name));
+}
 /** Derive an executable BPMN model from a declarative flow. */
 export function declarativeToBpmn(flow) {
     const nodes = [];
@@ -56,7 +70,10 @@ export function declarativeToBpmn(flow) {
     flow.steps.forEach((step, i) => {
         const incoming = `flow_${i}`;
         const outgoing = `flow_${i + 1}`;
-        if (step.kind === "run") {
+        if (step.kind === "run" || step.kind === "task") {
+            // Both hosted (`run`) and external (`task`) steps are BPMN service tasks
+            // with the same derived job type; they differ only in whether the local
+            // Worker registers a handler for that type.
             nodes.push(`    <bpmn:serviceTask id="${escapeXml(step.name)}" name="${escapeXml(step.name)}">\n` +
                 `      <bpmn:extensionElements><zeebe:taskDefinition type="${escapeXml(jobType(flow.id, step.name))}" /></bpmn:extensionElements>\n` +
                 `      <bpmn:incoming>${incoming}</bpmn:incoming><bpmn:outgoing>${outgoing}</bpmn:outgoing>\n` +

package/dist/imperative.d.ts

@@ -1,5 +1,11 @@
 import type { ImperativeWorkflow, Json, JsonObject, Orchestration } from "./types.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 declare function defineWorkflow(id: string, orchestrate: Orchestration): ImperativeWorkflow;
 /** The looped-orchestrator model: start → orchestrate → gw → (done ? end : loop). */
 export declare function imperativeToBpmn(wf: ImperativeWorkflow): string;

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,6 +1,6 @@
 export { defineWorkflow, imperativeToBpmn, replayOnce } from "./imperative.js";
 export type { Journal, ReplayStep } from "./imperative.js";
-export { defineFlow, declarativeToBpmn } from "./declarative.js";
+export { defineFlow, declarativeToBpmn, externalJobTypes } from "./declarative.js";
 export type { FlowBuilder } from "./declarative.js";
 export { WorkflowClient, WorkflowError, toBpmn } from "./client.js";
 export type { WorkflowClientOptions, ActivateOptions } from "./client.js";

package/dist/index.js

@@ -1,28 +1,44 @@
-// @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 } from "./declarative.js";
 export { WorkflowClient, WorkflowError, toBpmn } from "./client.js";
 export { Worker } from "./worker.js";

package/dist/types.d.ts

@@ -18,6 +18,9 @@ export type StepHandler = (job: Job) => Promise<JsonObject | void> | JsonObject
 export type DeclarativeStep = {
     kind: "run";
     name: string;
+} | {
+    kind: "task";
+    name: string;
 } | {
     kind: "signal";
     name: string;

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).
 //
@@ -39,7 +40,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 ?? {};
@@ -54,16 +55,58 @@ export class Worker {
         }
         else {
             for (const s of wf.steps) {
+                // Only `run` steps are hosted locally; `signal` (message catch) and
+                // `task` (external worker) contribute no in-process route.
                 if (s.kind !== "run")
                     continue;
                 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. */
     get servedTypes() {
         return [...this.routes.keys()];
@@ -94,7 +137,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 +147,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 +161,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/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.2.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. Talks to a running nanobpmn gateway over the REST v2 API.",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {

package/src/client.ts

@@ -102,13 +102,23 @@ 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> {
+    const signals = flow.steps.filter((s) => s.kind === "signal").map((s) => s.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`,
       {

package/src/declarative.ts

@@ -15,8 +15,17 @@ import type { DeclarativeFlow, DeclarativeStep, StepHandler } from "./types.js";
 import { assertIdent, escapeXml, jobType, messageName } from "./xml.js";
 
 export interface FlowBuilder {
-  /** A durable activity served by a worker (a BPMN service task). */
+  /** A durable activity served by a worker THIS program hosts (a BPMN service
+   *  task; the handler runs in the in-process `Worker`). */
   run(name: string, handler: StepHandler): FlowBuilder;
+  /**
+   * A durable activity served by a worker OUTSIDE this program (a BPMN service
+   * task with the same derived job type `${flowId}:${name}`, but no
+   * locally-hosted handler). The engine offers the job to whichever worker
+   * subscribes to that type — in another process, service, or language. Use
+   * `externalJobTypes(flow)` to list the contract those workers must poll.
+   */
+  task(name: string): FlowBuilder;
   /**
    * A durable wait for an external/human event, correlated on a process
    * variable (a BPMN message intermediate catch event). Resume it with
@@ -41,6 +50,13 @@ export function defineFlow(id: string, build: (w: FlowBuilder) => void): Declara
       handlers[name] = handler;
       return w;
     },
+    task(name) {
+      assertIdent("step name", name);
+      if (seen.has(name)) throw new Error(`duplicate step name "${name}" in flow "${id}"`);
+      seen.add(name);
+      steps.push({ kind: "task", name });
+      return w;
+    },
     signal(name, opts) {
       assertIdent("step name", name);
       if (seen.has(name)) throw new Error(`duplicate step name "${name}" in flow "${id}"`);
@@ -56,6 +72,13 @@ export function defineFlow(id: string, build: (w: FlowBuilder) => void): Declara
   return { kind: "declarative", id, steps, handlers };
 }
 
+/** The derived job types of a flow's external `task` steps — the contract that
+ *  workers outside this program must subscribe to (the engine offers those jobs
+ *  to whoever polls the type). Empty when the flow hosts all its own steps. */
+export function externalJobTypes(flow: DeclarativeFlow): string[] {
+  return flow.steps.filter((s) => s.kind === "task").map((s) => jobType(flow.id, s.name));
+}
+
 /** Derive an executable BPMN model from a declarative flow. */
 export function declarativeToBpmn(flow: DeclarativeFlow): string {
   const nodes: string[] = [];
@@ -67,7 +90,10 @@ export function declarativeToBpmn(flow: DeclarativeFlow): string {
   flow.steps.forEach((step, i) => {
     const incoming = `flow_${i}`;
     const outgoing = `flow_${i + 1}`;
-    if (step.kind === "run") {
+    if (step.kind === "run" || step.kind === "task") {
+      // Both hosted (`run`) and external (`task`) steps are BPMN service tasks
+      // with the same derived job type; they differ only in whether the local
+      // Worker registers a handler for that type.
       nodes.push(
         `    <bpmn:serviceTask id="${escapeXml(step.name)}" name="${escapeXml(step.name)}">\n` +
           `      <bpmn:extensionElements><zeebe:taskDefinition type="${escapeXml(jobType(flow.id, step.name))}" /></bpmn:extensionElements>\n` +

package/src/imperative.ts

@@ -21,7 +21,13 @@
 import type { ImperativeWorkflow, Json, JsonObject, Orchestration, WorkflowContext } from "./types.js";
 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: string, orchestrate: Orchestration): ImperativeWorkflow {
   assertIdent("workflow id", id);
   if (typeof orchestrate !== "function") throw new Error("defineWorkflow needs an async orchestration function");

package/src/index.ts

@@ -1,31 +1,47 @@
-// @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 type { Journal, ReplayStep } from "./imperative.js";
-export { defineFlow, declarativeToBpmn } from "./declarative.js";
+export { defineFlow, declarativeToBpmn, externalJobTypes } from "./declarative.js";
 export type { FlowBuilder } from "./declarative.js";
 export { WorkflowClient, WorkflowError, toBpmn } from "./client.js";
 export type { WorkflowClientOptions, ActivateOptions } from "./client.js";

package/src/types.ts

@@ -20,6 +20,7 @@ export type StepHandler = (job: Job) => Promise<JsonObject | void> | JsonObject
 
 export type DeclarativeStep =
   | { kind: "run"; name: string }
+  | { kind: "task"; name: string }
   | { kind: "signal"; name: string; correlationKey: string };
 
 export interface DeclarativeFlow {

package/src/worker.ts

@@ -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).
 //
@@ -73,7 +74,7 @@ export class Worker {
 
   private register(wf: Workflow): void {
     if (wf.kind === "imperative") {
-      this.routes.set(wf.orchestrateType, {
+      this.addRoute(wf.orchestrateType, {
         workflowId: wf.id,
         handle: async (job) => {
           const input = (job.variables.input as JsonObject) ?? {};
@@ -86,9 +87,20 @@ export class Worker {
       });
     } else {
       for (const s of wf.steps) {
+        // Only `run` steps are hosted locally; `signal` (message catch) and
+        // `task` (external worker) contribute no in-process route.
         if (s.kind !== "run") continue;
         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)) ?? {}) as JsonObject }),
         });
@@ -96,6 +108,42 @@ export class Worker {
     }
   }
 
+  /** 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(type: string, route: { workflowId: string; handle: Handler }): void {
+    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. */
+  private emitError(err: Error, type: string): void {
+    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. */
+  private async emitActivity(e: ActivityEvent): Promise<void> {
+    try {
+      await this.onActivity?.(e);
+    } catch {
+      /* observational only; swallow so it never triggers failJob */
+    }
+  }
+
   /** The derived job types this worker serves. */
   get servedTypes(): string[] {
     return [...this.routes.keys()];
@@ -127,7 +175,7 @@ export class Worker {
         });
       } catch (e) {
         // Transport/gateway error (e.g. engine restarting): back off, reconnect.
-        this.onError?.(e as Error, { type });
+        this.emitError(e as Error, type);
         await sleep(this.backoffMs);
         continue;
       }
@@ -136,7 +184,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,
@@ -147,7 +197,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 as Error, { type });
+          this.emitError(e as Error, type);
           try {
             await this.client.failJob(job.jobKey, (e as Error).message, 0);
           } catch {