@nanobpm/workflow 0.5.0 → 0.7.0

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/dist/xml.d.ts

@@ -8,4 +8,7 @@ export declare const messageName: (workflowId: string, step: string) => string;
 export declare const orchestrateType: (workflowId: string) => string;
 export declare function assertIdent(kind: string, value: string): void;
 export declare function assertJobType(kind: string, value: string): void;
+export declare function assertTimerDuration(kind: string, value: string): void;
+export declare function assertTimerCycle(kind: string, value: string): void;
+export declare function assertTimerDate(kind: string, value: string): void;
 export declare function assertWorkflowIds(wf: Workflow): void;

package/dist/xml.js

@@ -29,6 +29,56 @@ export function assertJobType(kind, value) {
         throw new Error(`${kind} "${value}" is not a valid job type (expected a non-empty token of letters, digits, and _ . : + -)`);
     }
 }
+// --- Timer definitions (BPMN timerEventDefinition bodies) --------------------
+//
+// The engine (engine-core/src/bpmn.rs) accepts a nested `timeDuration`,
+// `timeCycle`, or `timeDate` as either a static ISO-8601 literal or a FEEL
+// expression (a leading `=`). We validate the literal forms at authoring time so
+// a malformed timer fails fast in the DSL rather than at deploy.
+/** An ISO-8601 duration with integer week/day/hour/minute/second components
+ *  (no years/months — ambiguous length — matching the engine's parser). */
+const ISO_DURATION = /^P(?:\d+W)?(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+S)?)?$/;
+function isIsoDuration(v) {
+    if (!ISO_DURATION.test(v) || v === "P" || v === "PT" || v.endsWith("T"))
+        return false;
+    return /\d/.test(v);
+}
+/** A recurring ISO-8601 interval: an optional `R[n]/` repeat prefix + a
+ *  duration, or a bare duration (the engine repeats it unboundedly). */
+function isIsoCycle(v) {
+    const slash = v.indexOf("/");
+    if (slash < 0)
+        return isIsoDuration(v);
+    const repeat = v.slice(0, slash);
+    const interval = v.slice(slash + 1);
+    return /^R\d*$/.test(repeat) && isIsoDuration(interval);
+}
+/** An ISO-8601 date-time instant (a `timeDate`). A `timeDate` is an absolute
+ *  instant, so a zone designator (`Z` or an explicit `±HH:MM` offset) is
+ *  required — a bare local datetime like `2026-01-01T09:00:00` is ambiguous. */
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2})?(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+/** A FEEL expression body (a leading `=`, non-empty). */
+function isFeel(v) {
+    return v.startsWith("=") && v.length > 1;
+}
+export function assertTimerDuration(kind, value) {
+    const v = typeof value === "string" ? value.trim() : "";
+    if (v === "" || (!isFeel(v) && !isIsoDuration(v))) {
+        throw new Error(`${kind} "${value}" is not an ISO-8601 duration (e.g. PT1M30S, P1DT6H) or a FEEL expression (=...)`);
+    }
+}
+export function assertTimerCycle(kind, value) {
+    const v = typeof value === "string" ? value.trim() : "";
+    if (v === "" || (!isFeel(v) && !isIsoCycle(v))) {
+        throw new Error(`${kind} "${value}" is not an ISO-8601 repeating interval (e.g. R/PT1H, R5/PT30M), a bare duration (e.g. PT1H), or a FEEL expression (=...)`);
+    }
+}
+export function assertTimerDate(kind, value) {
+    const v = typeof value === "string" ? value.trim() : "";
+    if (v === "" || (!isFeel(v) && !ISO_DATE.test(v))) {
+        throw new Error(`${kind} "${value}" is not an ISO-8601 instant (e.g. 2026-01-01T09:00:00Z) or a FEEL expression (=...)`);
+    }
+}
 export function assertWorkflowIds(wf) {
     assertIdent("workflow id", wf.id);
     if (wf.kind === "declarative") {
@@ -42,6 +92,9 @@ function assertNodeNames(nodes) {
             case "signal":
                 assertIdent("step name", node.name);
                 break;
+            case "timer":
+                assertIdent("step name", node.name);
+                break;
             case "task":
                 assertIdent("step name", node.name);
                 if (node.jobType !== undefined)

package/package.json

@@ -1,12 +1,12 @@
 {
   "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.7.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": {
     "type": "git",
-    "url": "https://github.com/jwulf/nano-ide.git",
+    "url": "git+https://github.com/jwulf/nano-ide.git",
     "directory": "packages/workflow"
   },
   "main": "./dist/index.js",
@@ -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",
-    );
-  }
 }