@nanobpm/workflow 0.5.0 → 0.6.0

package/dist/client.d.ts

@@ -16,34 +16,101 @@ export declare function toBpmn(wf: Workflow): string;
 export declare function toDeployableBpmn(wf: Workflow, opts?: {
     layout?: boolean;
 }): Promise<string>;
-type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
-export interface WorkflowClientOptions {
-    /** Base URL of the nanobpmn gateway, e.g. `http://localhost:8080`. */
-    baseUrl: string;
-    /** Injectable fetch (defaults to the global). Useful for tests/proxies. */
-    fetch?: FetchLike;
+/**
+ * The subset of the `@nanobpm/nano-sdk` (Camunda orchestration-cluster) client
+ * that the workflow surface uses. `createCamundaClient` returns a superset of
+ * this, so a test — or an author bringing their own transport (e.g. the embedded
+ * engine) — can inject any object satisfying it.
+ */
+export interface NanoSdkClient {
+    createDeployment(input: {
+        resources: File[];
+        [k: string]: unknown;
+    }, options?: unknown): Promise<Record<string, unknown>>;
+    createProcessInstance(input: {
+        processDefinitionId: string;
+        variables?: JsonObject;
+    }, options?: unknown): Promise<Record<string, unknown>>;
+    correlateMessage(input: {
+        name: string;
+        correlationKey: string;
+        variables?: JsonObject;
+    }, options?: unknown): Promise<Record<string, unknown>>;
+    getProcessInstance(input: {
+        processInstanceKey: string;
+    }, consistency: {
+        consistency: {
+            waitUpToMs: number;
+        };
+    }, options?: unknown): Promise<Record<string, unknown>>;
+    createJobWorker(cfg: JobWorkerConfig): NanoJobWorker;
 }
-export interface ActivateOptions {
-    worker: string;
-    maxJobsToActivate?: number;
-    /** Job timeout in ms (how long the worker holds the job). Default 30000. */
-    timeout?: number;
-    /** Long-poll timeout in ms; `< 0` disables long-poll. Default 15000. */
-    requestTimeout?: number;
+/** Config for a nano-sdk job worker (the subset the Worker runtime sets). */
+export interface JobWorkerConfig {
+    jobType: string;
+    jobHandler: (job: ActivatedJob) => Promise<unknown> | unknown;
+    workerName?: string;
+    maxParallelJobs?: number;
+    /** Job lock timeout in ms. */
+    jobTimeoutMs?: number;
+    /** Long-poll timeout in ms. */
+    pollTimeoutMs?: number;
+    /** Start polling immediately. The Worker runtime sets this false and starts explicitly. */
+    autoStart?: boolean;
 }
+/** The handle returned by `createJobWorker`. */
+export interface NanoJobWorker {
+    start(): void;
+    stop(): void | Promise<void>;
+    stopGracefully?(opts?: {
+        waitUpToMs?: number;
+    }): Promise<void>;
+}
+/** An activated job as delivered to a nano-sdk job handler: the workflow `Job`
+ *  fields plus the acknowledgement actions. */
+export type ActivatedJob = Job & {
+    complete(variables?: JsonObject): Promise<unknown>;
+    fail(body: {
+        errorMessage: string;
+        retries?: number;
+    }): Promise<unknown>;
+};
+/** Options common to both ways of building a `WorkflowClient`. */
+interface WorkflowClientCommon {
+    /** Auth token for the gateway (CAMUNDA_TOKEN). */
+    token?: string;
+    /** Transport mode passed to `createCamundaClient`: "auto" | "falcon" | "rest".
+     *  Default "auto" (Falcon on a Nano server, REST elsewhere). */
+    transport?: "auto" | "falcon" | "rest";
+}
+/** Construct a `WorkflowClient` from **either** a `baseUrl` (a nano-sdk client is
+ *  built for you) **or** a pre-built `client`. The union makes TypeScript enforce
+ *  that exactly one is supplied, matching the constructor's runtime requirement. */
+export type WorkflowClientOptions = (WorkflowClientCommon & {
+    /** Base URL of the nanobpmn gateway, e.g. `http://localhost:8080`. The
+     *  nano-sdk client normalises this to the `/v2` REST address. */
+    baseUrl: string;
+    client?: never;
+}) | (WorkflowClientCommon & {
+    /** Inject a pre-built nano-sdk client (or a compatible fake) instead of
+     *  constructing one from `baseUrl`. Useful for tests, the embedded
+     *  transport, and advanced authors who build the client themselves. */
+    client: NanoSdkClient;
+    baseUrl?: never;
+});
 export declare class WorkflowError extends Error {
     readonly status?: number | undefined;
     readonly body?: string | undefined;
     constructor(message: string, status?: number | undefined, body?: string | undefined);
 }
 export declare class WorkflowClient {
-    private readonly baseUrl;
-    private readonly fetchImpl;
+    /** The underlying nano-sdk client, exposed so the Worker runtime and app
+     *  authors can reach the engine through the same transport (ADR 0055). The
+     *  exported `NanoSdkClient` type intentionally models only the subset of
+     *  methods this package uses (deploy, create, correlate, get, job workers);
+     *  the runtime value is the full nano-sdk client. */
+    readonly sdk: NanoSdkClient;
     constructor(opts: WorkflowClientOptions);
-    private json;
-    /** Perform a request, throwing WorkflowError on transport error or !ok, and
-     *  return the raw Response (for endpoints with an empty/no-content body). */
-    private send;
     /**
      * Deploy a workflow's derived BPMN model. The deployed model includes
      * auto-generated diagram interchange (DI) so it is inspectable in a
@@ -64,10 +131,8 @@ export declare class WorkflowClient {
      *  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). */
+    /** Fetch an instance (used by demos/tests to observe completion). Reads with
+     *  zero-wait consistency; returns null when the instance is not (yet) visible. */
     getInstance(processInstanceKey: string): Promise<JsonObject | null>;
-    activateJobs(type: string, opts: ActivateOptions): Promise<Job[]>;
-    completeJob(jobKey: string, variables?: JsonObject): Promise<void>;
-    failJob(jobKey: string, errorMessage: string, retries?: number): Promise<void>;
 }
 export {};

package/dist/client.js

@@ -1,6 +1,9 @@
-// A thin, dependency-free client for a running nanobpmn gateway (REST v2):
-// deploy a workflow's derived model, start instances, correlate signals, and the
-// low-level job activate/complete/fail used by the Worker runtime.
+// A client for a running nanobpmn gateway, built on `@nanobpm/nano-sdk` (the
+// single engine-transport spine — ADR 0055). It derives a workflow's model,
+// deploys it (with diagram interchange), starts instances, and correlates
+// signals; the low-level job protocol used by the Worker runtime is the SDK's
+// own job worker, reached through the exposed `sdk` client.
+import { createCamundaClient } from "@nanobpm/nano-sdk";
 import { declarativeToBpmn, walkNodes } from "./declarative.js";
 import { imperativeToBpmn } from "./imperative.js";
 import { layoutBpmn } from "./layout.js";
@@ -57,37 +60,36 @@ export class WorkflowError extends Error {
         this.name = "WorkflowError";
     }
 }
+/** Normalise a thrown SDK/transport error into a WorkflowError, preserving an
+ *  HTTP status when the SDK attached one. */
+function asWorkflowError(e, what) {
+    if (e instanceof WorkflowError)
+        return e;
+    const err = e;
+    const status = err?.status ?? err?.response?.status;
+    return new WorkflowError(`${what} failed: ${err?.message ?? String(e)}`, status);
+}
 export class WorkflowClient {
-    baseUrl;
-    fetchImpl;
+    /** The underlying nano-sdk client, exposed so the Worker runtime and app
+     *  authors can reach the engine through the same transport (ADR 0055). The
+     *  exported `NanoSdkClient` type intentionally models only the subset of
+     *  methods this package uses (deploy, create, correlate, get, job workers);
+     *  the runtime value is the full nano-sdk client. */
+    sdk;
     constructor(opts) {
-        if (!opts?.baseUrl)
-            throw new Error("WorkflowClient needs a baseUrl");
-        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
-        const f = opts.fetch ?? globalThis.fetch;
-        if (!f)
-            throw new Error("no fetch available; pass options.fetch (Node < 18)");
-        this.fetchImpl = f;
-    }
-    async json(path, init, what) {
-        const res = await this.send(path, init, what);
-        return (await res.json());
-    }
-    /** Perform a request, throwing WorkflowError on transport error or !ok, and
-     *  return the raw Response (for endpoints with an empty/no-content body). */
-    async send(path, init, what) {
-        let res;
-        try {
-            res = await this.fetchImpl(`${this.baseUrl}${path}`, init);
-        }
-        catch (e) {
-            throw new WorkflowError(`${what} transport error: ${e.message}`);
+        if (opts?.client) {
+            this.sdk = opts.client;
+            return;
         }
-        if (!res.ok) {
-            const body = await res.text().catch(() => "");
-            throw new WorkflowError(`${what} failed: ${res.status}`, res.status, body);
-        }
-        return res;
+        if (!opts?.baseUrl)
+            throw new Error("WorkflowClient needs a baseUrl or a client");
+        this.sdk = createCamundaClient({
+            config: {
+                CAMUNDA_REST_ADDRESS: opts.baseUrl.replace(/\/+$/, ""),
+                ...(opts.token ? { CAMUNDA_TOKEN: opts.token } : {}),
+                CAMUNDA_TRANSPORT: opts.transport ?? "auto",
+            },
+        });
     }
     /**
      * Deploy a workflow's derived BPMN model. The deployed model includes
@@ -98,9 +100,13 @@ export class WorkflowClient {
      */
     async deploy(wf, opts = {}) {
         const xml = await toDeployableBpmn(wf, opts);
-        const form = new FormData();
-        form.append("resources", new Blob([xml], { type: "text/xml" }), `${wf.id}.bpmn`);
-        return this.json(`/v2/deployments`, { method: "POST", body: form }, "deploy");
+        const file = new File([xml], `${wf.id}.bpmn`, { type: "text/xml" });
+        try {
+            return (await this.sdk.createDeployment({ resources: [file] }));
+        }
+        catch (e) {
+            throw asWorkflowError(e, "deploy");
+        }
     }
     /**
      * Start a workflow instance. For imperative workflows the engine variables are
@@ -109,11 +115,15 @@ export class WorkflowClient {
      */
     async start(wf, input = {}) {
         const variables = wf.kind === "imperative" ? { input, journal: {}, wfDone: false } : input;
-        return this.json(`/v2/process-instances`, {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({ processDefinitionId: wf.id, variables }),
-        }, "start");
+        try {
+            return (await this.sdk.createProcessInstance({
+                processDefinitionId: wf.id,
+                variables,
+            }));
+        }
+        catch (e) {
+            throw asWorkflowError(e, "start");
+        }
     }
     /** Correlate a signal to a parked declarative `signal` step. Fails fast on an
      *  unknown signal name (a typo would otherwise send an uncorrelatable message
@@ -129,40 +139,25 @@ export class WorkflowClient {
         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" },
-            body: JSON.stringify({ name: messageName(flow.id, signalName), correlationKey, variables }),
-        }, `signal "${signalName}"`);
+        try {
+            return (await this.sdk.correlateMessage({
+                name: messageName(flow.id, signalName),
+                correlationKey,
+                variables,
+            }));
+        }
+        catch (e) {
+            throw asWorkflowError(e, `signal "${signalName}"`);
+        }
     }
-    /** Fetch an instance (used by demos/tests to observe completion). */
+    /** Fetch an instance (used by demos/tests to observe completion). Reads with
+     *  zero-wait consistency; returns null when the instance is not (yet) visible. */
     async getInstance(processInstanceKey) {
         try {
-            const res = await this.fetchImpl(`${this.baseUrl}/v2/process-instances/${processInstanceKey}`);
-            if (!res.ok)
-                return null;
-            return (await res.json());
+            return (await this.sdk.getProcessInstance({ processInstanceKey }, { consistency: { waitUpToMs: 0 } }));
         }
         catch {
             return null;
         }
     }
-    // --- low-level job protocol (used by the Worker runtime) -------------------
-    async activateJobs(type, opts) {
-        const body = {
-            type,
-            worker: opts.worker,
-            maxJobsToActivate: opts.maxJobsToActivate ?? 1,
-            timeout: opts.timeout ?? 30000,
-            requestTimeout: opts.requestTimeout ?? 15000,
-        };
-        const res = await this.json(`/v2/jobs/activation`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) }, `activate ${type}`);
-        return res.jobs ?? [];
-    }
-    async completeJob(jobKey, variables = {}) {
-        await this.send(`/v2/jobs/${jobKey}/completion`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ variables }) }, "complete job");
-    }
-    async failJob(jobKey, errorMessage, retries = 0) {
-        await this.send(`/v2/jobs/${jobKey}/failure`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ errorMessage, retries }) }, "fail job");
-    }
 }

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { layoutBpmn, declarativeToLayoutedBpmn } from "./layout.js";
 export { envelope } from "./envelope.js";
 export type { Envelope, EnvelopeType, EnvelopeField, FieldSpec, ScalarType, ScalarTs, FieldTs, } from "./envelope.js";
 export { WorkflowClient, WorkflowError, toBpmn, toDeployableBpmn } from "./client.js";
-export type { WorkflowClientOptions, ActivateOptions } from "./client.js";
+export type { WorkflowClientOptions, NanoSdkClient, NanoJobWorker, JobWorkerConfig, ActivatedJob, } from "./client.js";
 export { Worker } from "./worker.js";
 export type { WorkerOptions, ActivityEvent } from "./worker.js";
 export type { Json, JsonObject, Job, StepHandler, DeclarativeFlow, DeclarativeStep, FlowNode, SwitchCase, NodeEnvelopes, StepContract, FlowContracts, ImperativeWorkflow, Orchestration, WorkflowContext, Workflow, DeployResult, StartResult, } from "./types.js";

package/dist/worker.d.ts

@@ -9,36 +9,53 @@ export interface ActivityEvent {
     /** For an imperative orchestrator turn: the journalled step key, or "__done". */
     step?: string;
 }
-export interface WorkerOptions {
-    /** Provide a baseUrl (a client is created) or an existing client. */
-    baseUrl?: string;
-    client?: WorkflowClient;
+/** Options common to both ways of building a `Worker`. */
+interface WorkerCommon {
     workflows: Workflow[];
     /** Worker name reported to the gateway. Default "nanobpm-workflow". */
     name?: string;
+    /** Transport for the worker's own client (used only when `client` is not
+     *  supplied): "auto" | "falcon" | "rest". Defaults to "rest" — job serving is
+     *  resilience-critical, and REST long-poll reconnects with backoff after an
+     *  engine restart (the ADR 0044 property), whereas the Falcon push transport
+     *  does not recover a mid-stream disconnect. Instance creation, by contrast,
+     *  defaults to Falcon on its own `WorkflowClient` for throughput. */
+    transport?: "auto" | "falcon" | "rest";
     /** Long-poll timeout per activation, ms. Also bounds stop() latency. Default 10000. */
     pollTimeoutMs?: number;
     /** Job lock timeout, ms. Default 30000. */
     jobTimeoutMs?: number;
-    /** Backoff after a transport error, ms. Default 500. */
-    backoffMs?: number;
+    /** Max jobs handled in parallel per derived job type. Default 1. */
+    maxParallelJobs?: number;
     onActivity?: (e: ActivityEvent) => void | Promise<void>;
     onError?: (err: Error, context: {
         type: string;
     }) => void;
 }
+/** Build a `Worker` from **either** a `baseUrl` (a `WorkflowClient` is created)
+ *  **or** an existing `client`. The union makes TypeScript enforce that exactly
+ *  one is supplied, matching the constructor's runtime requirement. */
+export type WorkerOptions = (WorkerCommon & {
+    /** Base URL of the nanobpmn gateway; a `WorkflowClient` is created for you. */
+    baseUrl: string;
+    client?: never;
+}) | (WorkerCommon & {
+    /** An existing `WorkflowClient` to serve jobs through. */
+    client: WorkflowClient;
+    baseUrl?: never;
+});
 export declare class Worker {
     private readonly client;
     private readonly name;
     private readonly pollTimeoutMs;
     private readonly jobTimeoutMs;
-    private readonly backoffMs;
+    private readonly maxParallelJobs;
     private readonly onActivity?;
     private readonly onError?;
     /** job type → { workflowId, handle } */
     private readonly routes;
     private running;
-    private loops;
+    private workers;
     constructor(opts: WorkerOptions);
     private register;
     /** Register a derived job type, failing fast on a collision. Two workflows can
@@ -55,9 +72,18 @@ export declare class Worker {
     private emitActivity;
     /** The derived job types this worker serves. */
     get servedTypes(): string[];
-    /** Begin polling. Resolves once the loops are running (they run until stop()). */
+    /** Begin serving. Creates one nano-sdk job worker per derived job type with
+     *  `autoStart: false`, then starts each explicitly, so the poll lifecycle is
+     *  deterministic and owned here rather than left to the SDK's auto-start
+     *  default (matching the `JobWorkerConfig.autoStart` contract). Nothing polls
+     *  before `start()` is called. */
     start(): void;
-    /** Stop polling and wait for in-flight loops to unwind (≤ pollTimeoutMs). */
+    /** Stop serving and wait for in-flight jobs to drain. Stopping is best-effort
+     *  per worker: the Falcon worker's `stop` throws if it never bound a transport
+     *  (detection still pending), which must not fail the whole shutdown. */
     stop(): Promise<void>;
-    private pollLoop;
+    /** Dispatch one activated job to its route handler and acknowledge it. Returns
+     *  the nano-sdk action receipt (its `complete`/`fail` result). */
+    private handleJob;
 }
+export {};

package/dist/worker.js

@@ -1,6 +1,7 @@
 // The Worker runtime — hosts one or more workflows against a gateway and drives
-// them: long-polls each derived job type, dispatches jobs to handlers, completes
-// them. It generalises the two surfaces:
+// them: it registers one nano-sdk job worker per derived job type, dispatches
+// each activated job to its handler, and completes it. It generalises the two
+// surfaces:
 //
 //   - a declarative flow contributes one job type per `run` step, dispatched to
 //     the user handler (external `task` steps are intentionally NOT hosted here —
@@ -8,32 +9,34 @@
 //   - an imperative workflow contributes its single orchestrator job type,
 //     dispatched to the replay engine (which advances the journal one step).
 //
-// It is resilient to the gateway disappearing (each poll loop backs off and
-// reconnects on its own), so it survives an engine crash/restart — the property
-// the ADR 0044 spike proved.
+// Transport (activation, completion, failure, long-poll, backoff/reconnect) is
+// the nano-sdk job worker (ADR 0055), reached through `WorkflowClient.sdk`. The
+// nano-sdk worker reschedules its poll on an activation error, so the runtime
+// survives an engine crash/restart — the property the ADR 0044 spike proved.
 import { WorkflowClient } from "./client.js";
 import { replayOnce } from "./imperative.js";
 import { walkNodes } from "./declarative.js";
 import { jobType } from "./xml.js";
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 export class Worker {
     client;
     name;
     pollTimeoutMs;
     jobTimeoutMs;
-    backoffMs;
+    maxParallelJobs;
     onActivity;
     onError;
     /** job type → { workflowId, handle } */
     routes = new Map();
     running = false;
-    loops = [];
+    workers = [];
     constructor(opts) {
-        this.client = opts.client ?? new WorkflowClient({ baseUrl: requireBaseUrl(opts) });
+        this.client =
+            opts.client ??
+                new WorkflowClient({ baseUrl: requireBaseUrl(opts), transport: opts.transport ?? "rest" });
         this.name = opts.name ?? "nanobpm-workflow";
         this.pollTimeoutMs = opts.pollTimeoutMs ?? 10000;
         this.jobTimeoutMs = opts.jobTimeoutMs ?? 30000;
-        this.backoffMs = opts.backoffMs ?? 500;
+        this.maxParallelJobs = opts.maxParallelJobs ?? 1;
         this.onActivity = opts.onActivity;
         this.onError = opts.onError;
         for (const wf of opts.workflows)
@@ -114,64 +117,80 @@ export class Worker {
     get servedTypes() {
         return [...this.routes.keys()];
     }
-    /** Begin polling. Resolves once the loops are running (they run until stop()). */
+    /** Begin serving. Creates one nano-sdk job worker per derived job type with
+     *  `autoStart: false`, then starts each explicitly, so the poll lifecycle is
+     *  deterministic and owned here rather than left to the SDK's auto-start
+     *  default (matching the `JobWorkerConfig.autoStart` contract). Nothing polls
+     *  before `start()` is called. */
     start() {
         if (this.running)
             return;
         this.running = true;
-        this.loops = [...this.routes.entries()].map(([type, route]) => this.pollLoop(type, route));
+        this.workers = [...this.routes.entries()].map(([type, route]) => {
+            const worker = this.client.sdk.createJobWorker({
+                jobType: type,
+                workerName: this.name,
+                maxParallelJobs: this.maxParallelJobs,
+                jobTimeoutMs: this.jobTimeoutMs,
+                pollTimeoutMs: this.pollTimeoutMs,
+                autoStart: false,
+                jobHandler: (job) => this.handleJob(type, route, job),
+            });
+            worker.start();
+            return worker;
+        });
     }
-    /** Stop polling and wait for in-flight loops to unwind (≤ pollTimeoutMs). */
+    /** Stop serving and wait for in-flight jobs to drain. Stopping is best-effort
+     *  per worker: the Falcon worker's `stop` throws if it never bound a transport
+     *  (detection still pending), which must not fail the whole shutdown. */
     async stop() {
         this.running = false;
-        await Promise.all(this.loops);
-        this.loops = [];
-    }
-    async pollLoop(type, route) {
-        while (this.running) {
-            let jobs = [];
+        await Promise.all(this.workers.map(async (w) => {
             try {
-                jobs = await this.client.activateJobs(type, {
-                    worker: this.name,
-                    maxJobsToActivate: 1,
-                    timeout: this.jobTimeoutMs,
-                    requestTimeout: this.pollTimeoutMs,
-                });
+                await (w.stopGracefully
+                    ? w.stopGracefully({ waitUpToMs: this.pollTimeoutMs })
+                    : w.stop());
             }
-            catch (e) {
-                // Transport/gateway error (e.g. engine restarting): back off, reconnect.
-                this.emitError(e, type);
-                await sleep(this.backoffMs);
-                continue;
+            catch {
+                /* worker never fully started (transport unbound); nothing to drain */
             }
-            for (const job of jobs) {
-                if (!this.running)
-                    break;
-                try {
-                    const { variables, step } = await route.handle(job);
-                    await this.client.completeJob(job.jobKey, variables);
-                    // 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,
-                        elementId: job.elementId,
-                        step,
-                    });
-                }
-                catch (e) {
-                    // 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.emitError(e, type);
-                    try {
-                        await this.client.failJob(job.jobKey, e.message, 0);
-                    }
-                    catch {
-                        /* engine may be down; the lock will expire and redeliver */
-                    }
-                }
+        }));
+        this.workers = [];
+    }
+    /** Dispatch one activated job to its route handler and acknowledge it. Returns
+     *  the nano-sdk action receipt (its `complete`/`fail` result). */
+    async handleJob(type, route, job) {
+        try {
+            const { variables, step } = await route.handle(job);
+            const receipt = await job.complete(variables);
+            // 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,
+                elementId: job.elementId,
+                step,
+            });
+            return receipt;
+        }
+        catch (e) {
+            // 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.
+            // Normalise non-Error throws (strings, objects) so emitError always gets
+            // an Error and errorMessage is never undefined in the failure report.
+            const err = e instanceof Error ? e : new Error(String(e));
+            this.emitError(err, type);
+            try {
+                return await job.fail({ errorMessage: err.message, retries: 0 });
+            }
+            catch {
+                // Even reporting the failure failed (e.g. the gateway is unreachable).
+                // Awaited + swallowed so a rejected `fail` can't escape as an unhandled
+                // rejection out of the SDK worker's handler; the engine redelivers the
+                // job once its lock times out regardless.
+                return undefined;
             }
         }
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.5.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 over the REST v2 API.",
+  "version": "0.6.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",
   "repository": {
@@ -24,9 +24,12 @@
     "src"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22.6"
   },
   "sideEffects": false,
+  "dependencies": {
+    "@nanobpm/nano-sdk": "^1.2.0"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",

package/src/client.ts

@@ -1,7 +1,10 @@
-// A thin, dependency-free client for a running nanobpmn gateway (REST v2):
-// deploy a workflow's derived model, start instances, correlate signals, and the
-// low-level job activate/complete/fail used by the Worker runtime.
+// A client for a running nanobpmn gateway, built on `@nanobpm/nano-sdk` (the
+// single engine-transport spine — ADR 0055). It derives a workflow's model,
+// deploys it (with diagram interchange), starts instances, and correlates
+// signals; the low-level job protocol used by the Worker runtime is the SDK's
+// own job worker, reached through the exposed `sdk` client.
 
+import { createCamundaClient } from "@nanobpm/nano-sdk";
 import { declarativeToBpmn, walkNodes } from "./declarative.js";
 import { imperativeToBpmn } from "./imperative.js";
 import { layoutBpmn } from "./layout.js";
@@ -55,24 +58,89 @@ export async function toDeployableBpmn(
   }
 }
 
-type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 
-export interface WorkflowClientOptions {
-  /** Base URL of the nanobpmn gateway, e.g. `http://localhost:8080`. */
-  baseUrl: string;
-  /** Injectable fetch (defaults to the global). Useful for tests/proxies. */
-  fetch?: FetchLike;
+/**
+ * The subset of the `@nanobpm/nano-sdk` (Camunda orchestration-cluster) client
+ * that the workflow surface uses. `createCamundaClient` returns a superset of
+ * this, so a test — or an author bringing their own transport (e.g. the embedded
+ * engine) — can inject any object satisfying it.
+ */
+export interface NanoSdkClient {
+  createDeployment(
+    input: { resources: File[]; [k: string]: unknown },
+    options?: unknown,
+  ): Promise<Record<string, unknown>>;
+  createProcessInstance(
+    input: { processDefinitionId: string; variables?: JsonObject },
+    options?: unknown,
+  ): Promise<Record<string, unknown>>;
+  correlateMessage(
+    input: { name: string; correlationKey: string; variables?: JsonObject },
+    options?: unknown,
+  ): Promise<Record<string, unknown>>;
+  getProcessInstance(
+    input: { processInstanceKey: string },
+    consistency: { consistency: { waitUpToMs: number } },
+    options?: unknown,
+  ): Promise<Record<string, unknown>>;
+  createJobWorker(cfg: JobWorkerConfig): NanoJobWorker;
 }
 
-export interface ActivateOptions {
-  worker: string;
-  maxJobsToActivate?: number;
-  /** Job timeout in ms (how long the worker holds the job). Default 30000. */
-  timeout?: number;
-  /** Long-poll timeout in ms; `< 0` disables long-poll. Default 15000. */
-  requestTimeout?: number;
+/** Config for a nano-sdk job worker (the subset the Worker runtime sets). */
+export interface JobWorkerConfig {
+  jobType: string;
+  jobHandler: (job: ActivatedJob) => Promise<unknown> | unknown;
+  workerName?: string;
+  maxParallelJobs?: number;
+  /** Job lock timeout in ms. */
+  jobTimeoutMs?: number;
+  /** Long-poll timeout in ms. */
+  pollTimeoutMs?: number;
+  /** Start polling immediately. The Worker runtime sets this false and starts explicitly. */
+  autoStart?: boolean;
 }
 
+/** The handle returned by `createJobWorker`. */
+export interface NanoJobWorker {
+  start(): void;
+  stop(): void | Promise<void>;
+  stopGracefully?(opts?: { waitUpToMs?: number }): Promise<void>;
+}
+
+/** An activated job as delivered to a nano-sdk job handler: the workflow `Job`
+ *  fields plus the acknowledgement actions. */
+export type ActivatedJob = Job & {
+  complete(variables?: JsonObject): Promise<unknown>;
+  fail(body: { errorMessage: string; retries?: number }): Promise<unknown>;
+};
+
+/** Options common to both ways of building a `WorkflowClient`. */
+interface WorkflowClientCommon {
+  /** Auth token for the gateway (CAMUNDA_TOKEN). */
+  token?: string;
+  /** Transport mode passed to `createCamundaClient`: "auto" | "falcon" | "rest".
+   *  Default "auto" (Falcon on a Nano server, REST elsewhere). */
+  transport?: "auto" | "falcon" | "rest";
+}
+
+/** Construct a `WorkflowClient` from **either** a `baseUrl` (a nano-sdk client is
+ *  built for you) **or** a pre-built `client`. The union makes TypeScript enforce
+ *  that exactly one is supplied, matching the constructor's runtime requirement. */
+export type WorkflowClientOptions =
+  | (WorkflowClientCommon & {
+      /** Base URL of the nanobpmn gateway, e.g. `http://localhost:8080`. The
+       *  nano-sdk client normalises this to the `/v2` REST address. */
+      baseUrl: string;
+      client?: never;
+    })
+  | (WorkflowClientCommon & {
+      /** Inject a pre-built nano-sdk client (or a compatible fake) instead of
+       *  constructing one from `baseUrl`. Useful for tests, the embedded
+       *  transport, and advanced authors who build the client themselves. */
+      client: NanoSdkClient;
+      baseUrl?: never;
+    });
+
 export class WorkflowError extends Error {
   constructor(
     message: string,
@@ -84,37 +152,36 @@ export class WorkflowError extends Error {
   }
 }
 
+/** Normalise a thrown SDK/transport error into a WorkflowError, preserving an
+ *  HTTP status when the SDK attached one. */
+function asWorkflowError(e: unknown, what: string): WorkflowError {
+  if (e instanceof WorkflowError) return e;
+  const err = e as { message?: string; status?: number; response?: { status?: number } };
+  const status = err?.status ?? err?.response?.status;
+  return new WorkflowError(`${what} failed: ${err?.message ?? String(e)}`, status);
+}
+
 export class WorkflowClient {
-  private readonly baseUrl: string;
-  private readonly fetchImpl: FetchLike;
+  /** The underlying nano-sdk client, exposed so the Worker runtime and app
+   *  authors can reach the engine through the same transport (ADR 0055). The
+   *  exported `NanoSdkClient` type intentionally models only the subset of
+   *  methods this package uses (deploy, create, correlate, get, job workers);
+   *  the runtime value is the full nano-sdk client. */
+  readonly sdk: NanoSdkClient;
 
   constructor(opts: WorkflowClientOptions) {
-    if (!opts?.baseUrl) throw new Error("WorkflowClient needs a baseUrl");
-    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
-    const f = opts.fetch ?? (globalThis.fetch as FetchLike | undefined);
-    if (!f) throw new Error("no fetch available; pass options.fetch (Node < 18)");
-    this.fetchImpl = f;
-  }
-
-  private async json<T>(path: string, init: RequestInit, what: string): Promise<T> {
-    const res = await this.send(path, init, what);
-    return (await res.json()) as T;
-  }
-
-  /** Perform a request, throwing WorkflowError on transport error or !ok, and
-   *  return the raw Response (for endpoints with an empty/no-content body). */
-  private async send(path: string, init: RequestInit, what: string): Promise<Response> {
-    let res: Response;
-    try {
-      res = await this.fetchImpl(`${this.baseUrl}${path}`, init);
-    } catch (e) {
-      throw new WorkflowError(`${what} transport error: ${(e as Error).message}`);
-    }
-    if (!res.ok) {
-      const body = await res.text().catch(() => "");
-      throw new WorkflowError(`${what} failed: ${res.status}`, res.status, body);
+    if (opts?.client) {
+      this.sdk = opts.client;
+      return;
     }
-    return res;
+    if (!opts?.baseUrl) throw new Error("WorkflowClient needs a baseUrl or a client");
+    this.sdk = createCamundaClient({
+      config: {
+        CAMUNDA_REST_ADDRESS: opts.baseUrl.replace(/\/+$/, ""),
+        ...(opts.token ? { CAMUNDA_TOKEN: opts.token } : {}),
+        CAMUNDA_TRANSPORT: opts.transport ?? "auto",
+      },
+    }) as unknown as NanoSdkClient;
   }
 
   /**
@@ -126,9 +193,12 @@ export class WorkflowClient {
    */
   async deploy(wf: Workflow, opts: { layout?: boolean } = {}): Promise<DeployResult> {
     const xml = await toDeployableBpmn(wf, opts);
-    const form = new FormData();
-    form.append("resources", new Blob([xml], { type: "text/xml" }), `${wf.id}.bpmn`);
-    return this.json<DeployResult>(`/v2/deployments`, { method: "POST", body: form }, "deploy");
+    const file = new File([xml], `${wf.id}.bpmn`, { type: "text/xml" });
+    try {
+      return (await this.sdk.createDeployment({ resources: [file] })) as DeployResult;
+    } catch (e) {
+      throw asWorkflowError(e, "deploy");
+    }
   }
 
   /**
@@ -139,15 +209,14 @@ export class WorkflowClient {
   async start(wf: Workflow, input: JsonObject = {}): Promise<StartResult> {
     const variables: JsonObject =
       wf.kind === "imperative" ? { input, journal: {}, wfDone: false } : input;
-    return this.json<StartResult>(
-      `/v2/process-instances`,
-      {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ processDefinitionId: wf.id, variables }),
-      },
-      "start",
-    );
+    try {
+      return (await this.sdk.createProcessInstance({
+        processDefinitionId: wf.id,
+        variables,
+      })) as StartResult;
+    } catch (e) {
+      throw asWorkflowError(e, "start");
+    }
   }
 
   /** Correlate a signal to a parked declarative `signal` step. Fails fast on an
@@ -172,59 +241,27 @@ export class WorkflowClient {
         }`,
       );
     }
-    return this.json<JsonObject>(
-      `/v2/messages/correlation`,
-      {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ name: messageName(flow.id, signalName), correlationKey, variables }),
-      },
-      `signal "${signalName}"`,
-    );
+    try {
+      return (await this.sdk.correlateMessage({
+        name: messageName(flow.id, signalName),
+        correlationKey,
+        variables,
+      })) as JsonObject;
+    } catch (e) {
+      throw asWorkflowError(e, `signal "${signalName}"`);
+    }
   }
 
-  /** Fetch an instance (used by demos/tests to observe completion). */
+  /** Fetch an instance (used by demos/tests to observe completion). Reads with
+   *  zero-wait consistency; returns null when the instance is not (yet) visible. */
   async getInstance(processInstanceKey: string): Promise<JsonObject | null> {
     try {
-      const res = await this.fetchImpl(`${this.baseUrl}/v2/process-instances/${processInstanceKey}`);
-      if (!res.ok) return null;
-      return (await res.json()) as JsonObject;
+      return (await this.sdk.getProcessInstance(
+        { processInstanceKey },
+        { consistency: { waitUpToMs: 0 } },
+      )) as JsonObject;
     } catch {
       return null;
     }
   }
-
-  // --- low-level job protocol (used by the Worker runtime) -------------------
-
-  async activateJobs(type: string, opts: ActivateOptions): Promise<Job[]> {
-    const body = {
-      type,
-      worker: opts.worker,
-      maxJobsToActivate: opts.maxJobsToActivate ?? 1,
-      timeout: opts.timeout ?? 30000,
-      requestTimeout: opts.requestTimeout ?? 15000,
-    };
-    const res = await this.json<{ jobs?: Job[] }>(
-      `/v2/jobs/activation`,
-      { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) },
-      `activate ${type}`,
-    );
-    return res.jobs ?? [];
-  }
-
-  async completeJob(jobKey: string, variables: JsonObject = {}): Promise<void> {
-    await this.send(
-      `/v2/jobs/${jobKey}/completion`,
-      { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ variables }) },
-      "complete job",
-    );
-  }
-
-  async failJob(jobKey: string, errorMessage: string, retries = 0): Promise<void> {
-    await this.send(
-      `/v2/jobs/${jobKey}/failure`,
-      { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ errorMessage, retries }) },
-      "fail job",
-    );
-  }
 }

package/src/index.ts

@@ -55,7 +55,13 @@ export type {
   FieldTs,
 } from "./envelope.js";
 export { WorkflowClient, WorkflowError, toBpmn, toDeployableBpmn } from "./client.js";
-export type { WorkflowClientOptions, ActivateOptions } from "./client.js";
+export type {
+  WorkflowClientOptions,
+  NanoSdkClient,
+  NanoJobWorker,
+  JobWorkerConfig,
+  ActivatedJob,
+} from "./client.js";
 export { Worker } from "./worker.js";
 export type { WorkerOptions, ActivityEvent } from "./worker.js";
 export type {

package/src/worker.ts

@@ -1,6 +1,7 @@
 // The Worker runtime — hosts one or more workflows against a gateway and drives
-// them: long-polls each derived job type, dispatches jobs to handlers, completes
-// them. It generalises the two surfaces:
+// them: it registers one nano-sdk job worker per derived job type, dispatches
+// each activated job to its handler, and completes it. It generalises the two
+// surfaces:
 //
 //   - a declarative flow contributes one job type per `run` step, dispatched to
 //     the user handler (external `task` steps are intentionally NOT hosted here —
@@ -8,11 +9,13 @@
 //   - an imperative workflow contributes its single orchestrator job type,
 //     dispatched to the replay engine (which advances the journal one step).
 //
-// It is resilient to the gateway disappearing (each poll loop backs off and
-// reconnects on its own), so it survives an engine crash/restart — the property
-// the ADR 0044 spike proved.
+// Transport (activation, completion, failure, long-poll, backoff/reconnect) is
+// the nano-sdk job worker (ADR 0055), reached through `WorkflowClient.sdk`. The
+// nano-sdk worker reschedules its poll on an activation error, so the runtime
+// survives an engine crash/restart — the property the ADR 0044 spike proved.
 
 import { WorkflowClient } from "./client.js";
+import type { ActivatedJob, NanoJobWorker } from "./client.js";
 import { replayOnce } from "./imperative.js";
 import { walkNodes } from "./declarative.js";
 import type { Job, JsonObject, Workflow } from "./types.js";
@@ -28,46 +31,66 @@ export interface ActivityEvent {
   step?: string;
 }
 
-export interface WorkerOptions {
-  /** Provide a baseUrl (a client is created) or an existing client. */
-  baseUrl?: string;
-  client?: WorkflowClient;
+/** Options common to both ways of building a `Worker`. */
+interface WorkerCommon {
   workflows: Workflow[];
   /** Worker name reported to the gateway. Default "nanobpm-workflow". */
   name?: string;
+  /** Transport for the worker's own client (used only when `client` is not
+   *  supplied): "auto" | "falcon" | "rest". Defaults to "rest" — job serving is
+   *  resilience-critical, and REST long-poll reconnects with backoff after an
+   *  engine restart (the ADR 0044 property), whereas the Falcon push transport
+   *  does not recover a mid-stream disconnect. Instance creation, by contrast,
+   *  defaults to Falcon on its own `WorkflowClient` for throughput. */
+  transport?: "auto" | "falcon" | "rest";
   /** Long-poll timeout per activation, ms. Also bounds stop() latency. Default 10000. */
   pollTimeoutMs?: number;
   /** Job lock timeout, ms. Default 30000. */
   jobTimeoutMs?: number;
-  /** Backoff after a transport error, ms. Default 500. */
-  backoffMs?: number;
+  /** Max jobs handled in parallel per derived job type. Default 1. */
+  maxParallelJobs?: number;
   onActivity?: (e: ActivityEvent) => void | Promise<void>;
   onError?: (err: Error, context: { type: string }) => void;
 }
 
-type Handler = (job: Job) => Promise<{ variables: JsonObject; step?: string }>;
+/** Build a `Worker` from **either** a `baseUrl` (a `WorkflowClient` is created)
+ *  **or** an existing `client`. The union makes TypeScript enforce that exactly
+ *  one is supplied, matching the constructor's runtime requirement. */
+export type WorkerOptions =
+  | (WorkerCommon & {
+      /** Base URL of the nanobpmn gateway; a `WorkflowClient` is created for you. */
+      baseUrl: string;
+      client?: never;
+    })
+  | (WorkerCommon & {
+      /** An existing `WorkflowClient` to serve jobs through. */
+      client: WorkflowClient;
+      baseUrl?: never;
+    });
 
-const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+type Handler = (job: Job) => Promise<{ variables: JsonObject; step?: string }>;
 
 export class Worker {
   private readonly client: WorkflowClient;
   private readonly name: string;
   private readonly pollTimeoutMs: number;
   private readonly jobTimeoutMs: number;
-  private readonly backoffMs: number;
+  private readonly maxParallelJobs: number;
   private readonly onActivity?: WorkerOptions["onActivity"];
   private readonly onError?: WorkerOptions["onError"];
   /** job type → { workflowId, handle } */
   private readonly routes = new Map<string, { workflowId: string; handle: Handler }>();
   private running = false;
-  private loops: Promise<void>[] = [];
+  private workers: NanoJobWorker[] = [];
 
   constructor(opts: WorkerOptions) {
-    this.client = opts.client ?? new WorkflowClient({ baseUrl: requireBaseUrl(opts) });
+    this.client =
+      opts.client ??
+      new WorkflowClient({ baseUrl: requireBaseUrl(opts), transport: opts.transport ?? "rest" });
     this.name = opts.name ?? "nanobpm-workflow";
     this.pollTimeoutMs = opts.pollTimeoutMs ?? 10000;
     this.jobTimeoutMs = opts.jobTimeoutMs ?? 30000;
-    this.backoffMs = opts.backoffMs ?? 500;
+    this.maxParallelJobs = opts.maxParallelJobs ?? 1;
     this.onActivity = opts.onActivity;
     this.onError = opts.onError;
     for (const wf of opts.workflows) this.register(wf);
@@ -152,61 +175,84 @@ export class Worker {
     return [...this.routes.keys()];
   }
 
-  /** Begin polling. Resolves once the loops are running (they run until stop()). */
+  /** Begin serving. Creates one nano-sdk job worker per derived job type with
+   *  `autoStart: false`, then starts each explicitly, so the poll lifecycle is
+   *  deterministic and owned here rather than left to the SDK's auto-start
+   *  default (matching the `JobWorkerConfig.autoStart` contract). Nothing polls
+   *  before `start()` is called. */
   start(): void {
     if (this.running) return;
     this.running = true;
-    this.loops = [...this.routes.entries()].map(([type, route]) => this.pollLoop(type, route));
+    this.workers = [...this.routes.entries()].map(([type, route]) => {
+      const worker = this.client.sdk.createJobWorker({
+        jobType: type,
+        workerName: this.name,
+        maxParallelJobs: this.maxParallelJobs,
+        jobTimeoutMs: this.jobTimeoutMs,
+        pollTimeoutMs: this.pollTimeoutMs,
+        autoStart: false,
+        jobHandler: (job) => this.handleJob(type, route, job),
+      });
+      worker.start();
+      return worker;
+    });
   }
 
-  /** Stop polling and wait for in-flight loops to unwind (≤ pollTimeoutMs). */
+  /** Stop serving and wait for in-flight jobs to drain. Stopping is best-effort
+   *  per worker: the Falcon worker's `stop` throws if it never bound a transport
+   *  (detection still pending), which must not fail the whole shutdown. */
   async stop(): Promise<void> {
     this.running = false;
-    await Promise.all(this.loops);
-    this.loops = [];
+    await Promise.all(
+      this.workers.map(async (w) => {
+        try {
+          await (w.stopGracefully
+            ? w.stopGracefully({ waitUpToMs: this.pollTimeoutMs })
+            : w.stop());
+        } catch {
+          /* worker never fully started (transport unbound); nothing to drain */
+        }
+      }),
+    );
+    this.workers = [];
   }
 
-  private async pollLoop(type: string, route: { workflowId: string; handle: Handler }): Promise<void> {
-    while (this.running) {
-      let jobs: Job[] = [];
+  /** Dispatch one activated job to its route handler and acknowledge it. Returns
+   *  the nano-sdk action receipt (its `complete`/`fail` result). */
+  private async handleJob(
+    type: string,
+    route: { workflowId: string; handle: Handler },
+    job: ActivatedJob,
+  ): Promise<unknown> {
+    try {
+      const { variables, step } = await route.handle(job);
+      const receipt = await job.complete(variables);
+      // 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,
+        elementId: job.elementId,
+        step,
+      });
+      return receipt;
+    } catch (e) {
+      // 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.
+      // Normalise non-Error throws (strings, objects) so emitError always gets
+      // an Error and errorMessage is never undefined in the failure report.
+      const err = e instanceof Error ? e : new Error(String(e));
+      this.emitError(err, type);
       try {
-        jobs = await this.client.activateJobs(type, {
-          worker: this.name,
-          maxJobsToActivate: 1,
-          timeout: this.jobTimeoutMs,
-          requestTimeout: this.pollTimeoutMs,
-        });
-      } catch (e) {
-        // Transport/gateway error (e.g. engine restarting): back off, reconnect.
-        this.emitError(e as Error, type);
-        await sleep(this.backoffMs);
-        continue;
-      }
-      for (const job of jobs) {
-        if (!this.running) break;
-        try {
-          const { variables, step } = await route.handle(job);
-          await this.client.completeJob(job.jobKey, variables);
-          // 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,
-            elementId: job.elementId,
-            step,
-          });
-        } catch (e) {
-          // 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.emitError(e as Error, type);
-          try {
-            await this.client.failJob(job.jobKey, (e as Error).message, 0);
-          } catch {
-            /* engine may be down; the lock will expire and redeliver */
-          }
-        }
+        return await job.fail({ errorMessage: err.message, retries: 0 });
+      } catch {
+        // Even reporting the failure failed (e.g. the gateway is unreachable).
+        // Awaited + swallowed so a rejected `fail` can't escape as an unhandled
+        // rejection out of the SDK worker's handler; the engine redelivers the
+        // job once its lock times out regardless.
+        return undefined;
       }
     }
   }