@nanobpm/urban 0.3.0 → 0.4.0

package/README.md

@@ -45,8 +45,10 @@ on Node < 23.6 the `urban` command re-executes with `--experimental-strip-types`
 | `-v`, `--version` | print the version | |
 
 The engine address comes from `$CAMUNDA_REST_ADDRESS` (default
-`http://localhost:8080/v2`). Set `$CAMUNDA_TRANSPORT` to a non-`rest` value to use
-the `@nanobpm/nano-sdk` transport when it is installed.
+`http://localhost:8080/v2`). Transport comes from `$CAMUNDA_TRANSPORT` (default
+`auto`): the `@nanobpm/nano-sdk` client upgrades instance creation and job
+serving to Falcon on a Nano server and falls back to REST elsewhere. Set it to
+`rest`, `falcon`, or `embedded` to pin a specific transport.
 
 ### A typical session
 
@@ -78,19 +80,23 @@ surfaces and webhook triggers), and installs SIGINT/SIGTERM handlers for a
 graceful shutdown. For full control, assemble the pieces yourself:
 
 ```ts
-import { createUrbanApp, selectHost, RestEngineClient } from "@nanobpm/urban";
+import { createUrbanApp, selectHost, createNanoSdkEngineClient } from "@nanobpm/urban";
 
 const host = selectHost();                       // picks the Node or Deno adapter
-const engine = new RestEngineClient({ baseUrl: process.env.CAMUNDA_REST_ADDRESS! });
+const engine = await createNanoSdkEngineClient({
+  restAddress: process.env.CAMUNDA_REST_ADDRESS!,
+  transport: process.env.CAMUNDA_TRANSPORT,      // "auto" (default) | "rest" | "falcon" | "embedded"
+});
 const app = await createUrbanApp({ host, engine, root: "." });
 await app.start();
 // ... later:
 await app.stop();                                // releases workers, server, datasources
 ```
 
-Two engine transports are built in: `RestEngineClient` (default, no extra
-dependencies) and `createNanoSdkEngineClient` (used when `CAMUNDA_TRANSPORT` is
-anything other than `rest`; needs the optional `@nanobpm/nano-sdk`).
+The runtime has a single engine client, `SdkEngineClient`, backed by one
+`@nanobpm/nano-sdk` client (a direct dependency). `createNanoSdkEngineClient`
+selects the wire transport via `CAMUNDA_TRANSPORT`: `auto` (default) upgrades to
+Falcon on a Nano server and falls back to REST elsewhere.
 
 ### Toolkit — derive artifacts (`urban gen`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
   "license": "Apache-2.0",
   "type": "module",
@@ -45,6 +45,7 @@
     "test:deno": "deno test -A --no-check src/"
   },
   "dependencies": {
+    "@nanobpm/nano-sdk": "^1.2.0",
     "@nanobpm/workflow": "^0.6.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2",
     "create-urban-app": "^0.2.0"

package/src/runtime/engine/nanosdk.test.ts

@@ -1,124 +1,278 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { createNanoSdkEngineClient } from "./nanosdk.ts";
-import type { EngineClient } from "../core/host.ts";
+import {
+  createNanoSdkEngineClient,
+  requireProcessInstanceKey,
+  SdkEngineClient,
+  type NanoSdkActivatedJob,
+  type NanoSdkClient,
+  type NanoSdkJobWorker,
+  type NanoSdkJobWorkerConfig,
+} from "./nanosdk.ts";
 
-/** A fallback that records which cold-path methods were used. */
-function recordingFallback(): EngineClient & { calls: string[] } {
+/** A fake nano-sdk client that records calls and lets a test drive its job worker. */
+function fakeSdkClient(overrides: Partial<NanoSdkClient> = {}): NanoSdkClient & {
+  calls: string[];
+  deployments: File[][];
+  workers: {
+    cfg: NanoSdkJobWorkerConfig;
+    started: number;
+    stopped: number;
+    dispatch: (job: NanoSdkActivatedJob) => Promise<unknown> | unknown;
+  }[];
+  closed: number;
+} {
   const calls: string[] = [];
-  return {
+  const deployments: File[][] = [];
+  const workers: {
+    cfg: NanoSdkJobWorkerConfig;
+    started: number;
+    stopped: number;
+    dispatch: (job: NanoSdkActivatedJob) => Promise<unknown> | unknown;
+  }[] = [];
+  let closed = 0;
+
+  const client: NanoSdkClient & {
+    calls: string[];
+    deployments: File[][];
+    workers: typeof workers;
+    closed: number;
+  } = {
     calls,
-    async deployResources() {
-      calls.push("deployResources");
-      return { deployed: 0 };
+    deployments,
+    workers,
+    get closed() {
+      return closed;
+    },
+    async createDeployment(input) {
+      calls.push("createDeployment");
+      deployments.push(input.resources);
+      return { deployments: input.resources.map((_, i) => ({ i })) };
     },
-    async createInstance() {
-      calls.push("createInstance");
-      return { processInstanceKey: "REST" };
+    async createProcessInstance(input) {
+      calls.push("createProcessInstance");
+      return { processInstanceKey: 99, variables: input.variables };
     },
-    async publishMessage() {
+    async publishMessage(input) {
       calls.push("publishMessage");
+      return { key: 1, ...input };
     },
     async searchUserTasks() {
       calls.push("searchUserTasks");
-      return [];
+      return { items: [] };
     },
     async completeUserTask() {
       calls.push("completeUserTask");
+      return {};
     },
-    async registerWorker(jobType: string) {
-      calls.push("registerWorker");
-      return { jobType, unsubscribe: async () => {} };
+    createJobWorker(cfg) {
+      calls.push("createJobWorker");
+      const rec = { cfg, started: 0, stopped: 0, dispatch: cfg.jobHandler };
+      workers.push(rec);
+      const worker: NanoSdkJobWorker = {
+        start() {
+          rec.started++;
+        },
+        stop() {
+          rec.stopped++;
+        },
+      };
+      return worker;
     },
-    async close() {
-      calls.push("close");
+    close() {
+      closed++;
     },
+    ...overrides,
   };
+  return client;
 }
 
-test("createInstance is routed through the nano-sdk client (Falcon hot path)", async () => {
-  let sdkCreated = 0;
-  const fallback = recordingFallback();
-  const engine = await createNanoSdkEngineClient({
-    restAddress: "http://x/v2",
-    fallback,
-    createClient: () => ({
-      createProcessInstance: async (input) => {
-        sdkCreated++;
-        assert.equal(input.processDefinitionId, "p");
-        return { processInstanceKey: 42, variables: { ok: true } };
-      },
-    }),
+test("requireProcessInstanceKey coerces and rejects empties", () => {
+  assert.equal(requireProcessInstanceKey(42), "42");
+  assert.equal(requireProcessInstanceKey("k"), "k");
+  assert.throws(() => requireProcessInstanceKey(null), /missing processInstanceKey/);
+  assert.throws(() => requireProcessInstanceKey(""), /missing processInstanceKey/);
+});
+
+test("deployResources builds web Files and calls createDeployment", async () => {
+  const client = fakeSdkClient();
+  const engine = new SdkEngineClient(client);
+  const res = await engine.deployResources([
+    { name: "a.bpmn", content: "<x/>", contentType: "text/xml" },
+    { name: "b.form", content: "{}", contentType: "application/json" },
+  ]);
+  assert.deepEqual(res, { deployed: 2 });
+  assert.equal(client.deployments.length, 1);
+  const [f0, f1] = client.deployments[0];
+  assert.ok(f0 instanceof File);
+  assert.equal(f0.name, "a.bpmn");
+  assert.equal(f0.type, "text/xml");
+  assert.equal(await f0.text(), "<x/>");
+  assert.equal(f1.name, "b.form");
+});
+
+test("createInstance routes through the SDK and coerces the key", async () => {
+  const client = fakeSdkClient();
+  const engine = new SdkEngineClient(client);
+  const res = await engine.createInstance({ processDefinitionId: "p", variables: { a: 1 } });
+  assert.equal(res.processInstanceKey, "99");
+  assert.deepEqual(res.variables, { a: 1 });
+  assert.ok(client.calls.includes("createProcessInstance"));
+});
+
+test("createInstance throws when the SDK response omits the instance key", async () => {
+  const client = fakeSdkClient({
+    createProcessInstance: async () => ({ variables: { ok: true } }),
   });
-  assert.ok(engine);
-  const res = await engine!.createInstance({ processDefinitionId: "p", variables: { a: 1 } });
-  assert.equal(sdkCreated, 1);
-  assert.equal(res.processInstanceKey, "42");
-  assert.deepEqual(res.variables, { ok: true });
-  assert.ok(!fallback.calls.includes("createInstance"), "did not use REST for create");
+  const engine = new SdkEngineClient(client);
+  await assert.rejects(
+    () => engine.createInstance({ processDefinitionId: "p" }),
+    /missing processInstanceKey/,
+  );
 });
 
-test("cold paths delegate to the REST fallback", async () => {
-  const fallback = recordingFallback();
-  const engine = await createNanoSdkEngineClient({
-    restAddress: "http://x/v2",
-    fallback,
-    createClient: () => ({ createProcessInstance: async () => ({ processInstanceKey: 1 }) }),
+test("publishMessage defaults correlationKey/variables", async () => {
+  let seen: Record<string, unknown> | undefined;
+  const client = fakeSdkClient({
+    publishMessage: async (input) => {
+      seen = input;
+      return {};
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  await engine.publishMessage({ name: "m" });
+  assert.deepEqual(seen, { name: "m", correlationKey: "", variables: {} });
+});
+
+test("searchUserTasks passes zero-wait consistency and maps items", async () => {
+  let consistency: unknown;
+  const client = fakeSdkClient({
+    searchUserTasks: async (_input, c) => {
+      consistency = c;
+      return {
+        items: [
+          { userTaskKey: 7, elementId: "task_a", variables: { x: 1 } },
+          { key: "" }, // keyless → skipped
+          { userTaskKey: "8" },
+        ],
+      };
+    },
   });
-  await engine!.deployResources([]);
-  await engine!.publishMessage({ name: "m" });
-  await engine!.searchUserTasks();
-  await engine!.completeUserTask("k");
-  await engine!.registerWorker("t", async () => ({}));
-  assert.deepEqual(fallback.calls, [
-    "deployResources",
-    "publishMessage",
-    "searchUserTasks",
-    "completeUserTask",
-    "registerWorker",
+  const engine = new SdkEngineClient(client);
+  const tasks = await engine.searchUserTasks({ processInstanceKey: "pi" });
+  assert.deepEqual(consistency, { consistency: { waitUpToMs: 0 } });
+  assert.deepEqual(tasks, [
+    { userTaskKey: "7", elementId: "task_a", variables: { x: 1 } },
+    { userTaskKey: "8", elementId: undefined, variables: undefined },
   ]);
 });
 
-test("returns null when the SDK cannot be loaded (so callers fall back to REST)", async () => {
-  const engine = await createNanoSdkEngineClient({
-    restAddress: "http://x/v2",
-    createClient: () => {
-      throw new Error("boom");
+test("completeUserTask routes through the SDK", async () => {
+  let seen: unknown;
+  const client = fakeSdkClient({
+    completeUserTask: async (input) => {
+      seen = input;
+      return {};
     },
   });
-  assert.equal(engine, null);
+  const engine = new SdkEngineClient(client);
+  await engine.completeUserTask("utk", { done: true });
+  assert.deepEqual(seen, { userTaskKey: "utk", variables: { done: true } });
 });
 
-test("close tears down both the SDK client and the fallback", async () => {
-  const fallback = recordingFallback();
-  let sdkClosed = 0;
-  const engine = await createNanoSdkEngineClient({
-    restAddress: "http://x/v2",
-    fallback,
-    createClient: () => ({
-      createProcessInstance: async () => ({ processInstanceKey: 1 }),
-      close: () => {
-        sdkClosed++;
-      },
-    }),
+test("registerWorker creates a worker (autoStart false), starts it, and dispatches + completes", async () => {
+  const client = fakeSdkClient();
+  const engine = new SdkEngineClient(client);
+  const handled: Record<string, unknown>[] = [];
+  const sub = await engine.registerWorker(
+    "svc",
+    (job) => {
+      handled.push(job.variables);
+      return { out: job.variables.n };
+    },
+    { maxParallelJobs: 4 },
+  );
+  assert.equal(sub.jobType, "svc");
+  const rec = client.workers[0];
+  assert.equal(rec.cfg.autoStart, false);
+  assert.equal(rec.cfg.workerName, "urban:svc");
+  assert.equal(rec.cfg.maxParallelJobs, 4);
+  assert.equal(rec.started, 1);
+
+  let completedWith: Record<string, unknown> | undefined;
+  await rec.dispatch({
+    jobKey: 12,
+    processInstanceKey: 34,
+    elementId: "e1",
+    variables: { n: 5 },
+    async complete(v?: Record<string, unknown>) {
+      completedWith = v;
+      return "receipt";
+    },
+    async fail() {
+      throw new Error("should not fail");
+    },
+  } as unknown as NanoSdkActivatedJob);
+  assert.deepEqual(handled, [{ n: 5 }]);
+  assert.deepEqual(completedWith, { out: 5 });
+
+  await sub.unsubscribe();
+  assert.equal(rec.stopped, 1);
+});
+
+test("registerWorker fails the job when the handler throws", async () => {
+  const client = fakeSdkClient();
+  const engine = new SdkEngineClient(client);
+  await engine.registerWorker("svc", () => {
+    throw new Error("boom");
   });
-  await engine!.close();
-  assert.equal(sdkClosed, 1);
-  assert.ok(fallback.calls.includes("close"));
+  const rec = client.workers[0];
+  let failBody: { errorMessage: string; retries?: number } | undefined;
+  await rec.dispatch({
+    jobKey: "j1",
+    variables: {},
+    async complete() {
+      throw new Error("should not complete");
+    },
+    async fail(body: { errorMessage: string; retries?: number }) {
+      failBody = body;
+      return "failed";
+    },
+  } as unknown as NanoSdkActivatedJob);
+  assert.equal(failBody?.errorMessage, "boom");
+  assert.equal(failBody?.retries, 0);
 });
 
-test("createInstance throws when the SDK response omits the instance key", async () => {
-  const fallback = recordingFallback();
+test("close stops every worker and closes the SDK client", async () => {
+  const client = fakeSdkClient();
+  const engine = new SdkEngineClient(client);
+  await engine.registerWorker("a", async () => ({}));
+  await engine.registerWorker("b", async () => ({}));
+  await engine.close();
+  assert.equal(client.workers[0].stopped, 1);
+  assert.equal(client.workers[1].stopped, 1);
+  assert.equal(client.closed, 1);
+});
+
+test("createNanoSdkEngineClient uses an injected client", async () => {
+  const client = fakeSdkClient();
+  const engine = await createNanoSdkEngineClient({ restAddress: "http://x/v2", client });
+  await engine.createInstance({ processDefinitionId: "p" });
+  assert.ok(client.calls.includes("createProcessInstance"));
+});
+
+test("createNanoSdkEngineClient uses an injected client factory with the resolved transport", async () => {
+  let seen: { restAddress: string; token?: string; transport?: string } | undefined;
+  const client = fakeSdkClient();
   const engine = await createNanoSdkEngineClient({
     restAddress: "http://x/v2",
-    fallback,
-    createClient: () => ({
-      createProcessInstance: async () => ({ variables: { ok: true } }) as unknown as { processInstanceKey: number },
-    }),
+    token: "t",
+    transport: "falcon",
+    createClient: (o) => {
+      seen = o;
+      return client;
+    },
   });
+  assert.deepEqual(seen, { restAddress: "http://x/v2", token: "t", transport: "falcon" });
   assert.ok(engine);
-  await assert.rejects(
-    () => engine!.createInstance({ processDefinitionId: "p" }),
-    /missing processInstanceKey/,
-  );
 });

package/src/runtime/engine/nanosdk.ts

@@ -1,19 +1,75 @@
-// nano-sdk engine adapter. The console wires every generated app to `@nanobpm/nano-sdk`'s
-// `createCamundaClient`, which upgrades the throughput-critical path — process-instance
-// creation — to the Falcon protocol (falling back to REST). This adapter lets the Urban
-// runtime use that same client, so the runtime and the IDE talk to the engine the same way
-// (ADR 0053).
+// The Urban runtime's single engine client. Every path to a Nano engine — deploy,
+// instance creation, message publication, user tasks, and job workers — routes
+// through one `@nanobpm/nano-sdk` client (ADR 0055). The SDK's `createCamundaClient`
+// transparently upgrades the throughput-critical paths (process-instance creation and
+// job serving) to the Falcon protocol on a Nano server and falls back to REST
+// everywhere else, so the runtime and the IDE talk to the engine the same way with a
+// single transport instead of a hand-rolled REST client plus a Falcon shim.
 //
-// Scope: the adapter routes instance creation (the hot path Falcon actually upgrades) through
-// the SDK client, and delegates the cold paths (deploy, publish, user tasks, workers) to a
-// REST fallback with the same address/token. `@nanobpm/nano-sdk` is an OPTIONAL dependency —
-// imported lazily — so the runtime keeps a dependency-free core and REST-only default.
+// `@nanobpm/nano-sdk` is a direct dependency, but it is imported lazily (via an
+// indirected specifier) so a caller that injects its own client — unit tests, the
+// Deno smoke, or an author bringing the embedded transport — never loads it, keeping
+// a dependency-free import graph for those paths.
 
-import type { EngineClient, JobHandler, WorkerSubscription } from "../core/host.ts";
-import { RestEngineClient, requireProcessInstanceKey } from "./rest.ts";
+import type {
+  EngineClient,
+  EngineJob,
+  JobHandler,
+  WorkerSubscription,
+} from "../core/host.ts";
 
-/** The subset of the `@nanobpm/nano-sdk` client the adapter uses. */
+/** Coerce an engine response's process-instance key to a non-empty string, or
+ * throw — a missing key means a malformed/partial response, not a real instance. */
+export function requireProcessInstanceKey(key: string | number | null | undefined): string {
+  if (key == null || key === "") {
+    throw new Error("engine response missing processInstanceKey/key");
+  }
+  return String(key);
+}
+
+/** A job as delivered to a nano-sdk job handler: the frame fields plus the
+ *  acknowledgement actions the handler must call. */
+export interface NanoSdkActivatedJob {
+  jobKey: string;
+  type?: string;
+  processInstanceKey?: string | number;
+  elementId?: string;
+  variables?: Record<string, unknown>;
+  complete(variables?: Record<string, unknown>): Promise<unknown>;
+  fail(body: { errorMessage: string; retries?: number }): Promise<unknown>;
+}
+
+/** Config for a nano-sdk job worker (the subset this adapter sets). */
+export interface NanoSdkJobWorkerConfig {
+  jobType: string;
+  jobHandler: (job: NanoSdkActivatedJob) => Promise<unknown> | unknown;
+  workerName?: string;
+  maxParallelJobs?: number;
+  jobTimeoutMs?: number;
+  pollTimeoutMs?: number;
+  fetchVariables?: string[];
+  /** Start polling immediately. This adapter sets it false and starts explicitly. */
+  autoStart?: boolean;
+}
+
+/** The handle returned by `createJobWorker`. */
+export interface NanoSdkJobWorker {
+  start(): void | Promise<void>;
+  stop(): void | Promise<void>;
+  stopGracefully?(opts?: { waitUpToMs?: number }): Promise<void>;
+}
+
+/**
+ * The subset of the `@nanobpm/nano-sdk` (Camunda orchestration-cluster) client the
+ * engine adapter 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;
@@ -22,26 +78,205 @@ export interface NanoSdkClient {
     },
     options?: unknown,
   ): Promise<Record<string, unknown>>;
+  publishMessage(
+    input: { name: string; correlationKey?: string; variables?: Record<string, unknown> },
+    options?: unknown,
+  ): Promise<Record<string, unknown>>;
+  searchUserTasks(
+    input: { filter?: Record<string, unknown> },
+    consistency?: unknown,
+    options?: unknown,
+  ): Promise<Record<string, unknown>>;
+  completeUserTask(
+    input: { userTaskKey: string; variables?: Record<string, unknown> },
+    options?: unknown,
+  ): Promise<unknown>;
+  createJobWorker(cfg: NanoSdkJobWorkerConfig): NanoSdkJobWorker;
   close?(): void | Promise<void>;
 }
 
+type Log = (level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>) => void;
+
+/**
+ * An `EngineClient` backed entirely by a `@nanobpm/nano-sdk` client. Deploy, create,
+ * message, and user-task calls map one-to-one onto the SDK's client methods; workers
+ * are the SDK's own job worker, which handles activation, completion, failure, and
+ * long-poll/backoff reconnect behind the same transport.
+ */
+export class SdkEngineClient implements EngineClient {
+  private readonly workers = new Set<NanoSdkJobWorker>();
+  private readonly client: NanoSdkClient;
+  private readonly log: Log;
+
+  constructor(client: NanoSdkClient, log: Log = () => {}) {
+    this.client = client;
+    this.log = log;
+  }
+
+  async deployResources(
+    resources: { name: string; content: string; contentType: string }[],
+  ): Promise<{ deployed: number }> {
+    const files = resources.map((r) => new File([r.content], r.name, { type: r.contentType }));
+    await this.client.createDeployment({ resources: files });
+    return { deployed: resources.length };
+  }
+
+  async createInstance(input: {
+    processDefinitionId: string;
+    variables?: Record<string, unknown>;
+    awaitCompletion?: boolean;
+  }): Promise<{ processInstanceKey: string; variables?: Record<string, unknown> }> {
+    const body = await this.client.createProcessInstance({
+      processDefinitionId: input.processDefinitionId,
+      variables: input.variables ?? {},
+      awaitCompletion: input.awaitCompletion ?? false,
+    });
+    const key =
+      (body.processInstanceKey as string | number | undefined) ??
+      (body.key as string | number | undefined);
+    return {
+      processInstanceKey: requireProcessInstanceKey(key),
+      variables: (body.variables as Record<string, unknown> | undefined) ?? undefined,
+    };
+  }
+
+  async publishMessage(input: {
+    name: string;
+    correlationKey?: string;
+    variables?: Record<string, unknown>;
+  }): Promise<void> {
+    await this.client.publishMessage({
+      name: input.name,
+      correlationKey: input.correlationKey ?? "",
+      variables: input.variables ?? {},
+    });
+  }
+
+  async searchUserTasks(filter?: {
+    processInstanceKey?: string;
+    assignee?: string;
+    candidateGroup?: string;
+  }): Promise<{ userTaskKey: string; elementId?: string; variables?: Record<string, unknown> }[]> {
+    // User tasks are an eventually consistent read; ask for zero-wait consistency so
+    // the search reflects what is currently visible without blocking.
+    const body = await this.client.searchUserTasks(
+      { filter: (filter ?? {}) as Record<string, unknown> },
+      { consistency: { waitUpToMs: 0 } },
+    );
+    const items = (body.items as Record<string, unknown>[] | undefined) ?? [];
+    return items.flatMap((it) => {
+      const userTaskKey = it.userTaskKey ?? it.key;
+      if (userTaskKey == null || userTaskKey === "") {
+        this.log("warn", "skipping user task with no key in engine response");
+        return [];
+      }
+      return [{
+        userTaskKey: String(userTaskKey),
+        elementId: it.elementId as string | undefined,
+        variables: it.variables as Record<string, unknown> | undefined,
+      }];
+    });
+  }
+
+  async completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void> {
+    await this.client.completeUserTask({ userTaskKey, variables: variables ?? {} });
+  }
+
+  async registerWorker(
+    jobType: string,
+    handler: JobHandler,
+    options?: { workerName?: string; maxParallelJobs?: number; fetchVariables?: string[] },
+  ): Promise<WorkerSubscription> {
+    const worker = this.client.createJobWorker({
+      jobType,
+      workerName: options?.workerName ?? `urban:${jobType}`,
+      maxParallelJobs: options?.maxParallelJobs ?? 8,
+      fetchVariables: options?.fetchVariables,
+      // Own the poll lifecycle here rather than leaving it to the SDK's auto-start
+      // default, so nothing polls until `start()` is called below.
+      autoStart: false,
+      jobHandler: async (job) => {
+        const rawKey = job.jobKey;
+        if (rawKey == null || rawKey === "") {
+          this.log("warn", `activation ${jobType}: skipping job with no jobKey in engine response`);
+          return undefined;
+        }
+        const engineJob: EngineJob = {
+          jobKey: String(rawKey),
+          jobType,
+          processInstanceKey:
+            job.processInstanceKey != null ? String(job.processInstanceKey) : undefined,
+          elementId: job.elementId,
+          variables: job.variables ?? {},
+        };
+        try {
+          const out = await handler(engineJob);
+          return await job.complete((out as Record<string, unknown> | undefined) ?? {});
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          this.log("error", `handler ${jobType} threw`, { err: message });
+          try {
+            // Best-effort failure report; the engine redelivers after the lock
+            // times out (at-least-once → handlers must be idempotent). Await +
+            // swallow so a rejected `fail` cannot escape as an unhandled rejection.
+            return await job.fail({ errorMessage: message.slice(0, 500), retries: 0 });
+          } catch {
+            return undefined;
+          }
+        }
+      },
+    });
+    await worker.start();
+    this.workers.add(worker);
+
+    return {
+      jobType,
+      unsubscribe: async () => {
+        await this.stopWorker(worker);
+        this.workers.delete(worker);
+      },
+    };
+  }
+
+  /** Stop one worker, tolerating a Falcon worker whose transport never bound
+   *  (detection still pending) — its `stop` throws, which must not fail teardown. */
+  private async stopWorker(worker: NanoSdkJobWorker): Promise<void> {
+    try {
+      await (worker.stopGracefully ? worker.stopGracefully() : worker.stop());
+    } catch {
+      /* worker never fully started (transport unbound); nothing to drain */
+    }
+  }
+
+  async close(): Promise<void> {
+    for (const w of this.workers) await this.stopWorker(w);
+    this.workers.clear();
+    try {
+      await this.client.close?.();
+    } catch {
+      /* transport already closed / never opened */
+    }
+  }
+}
+
 export interface NanoSdkEngineOptions {
   /** REST base, e.g. http://localhost:8080/v2. */
   restAddress: string;
   token?: string;
-  /** CAMUNDA_TRANSPORT: "auto" | "falcon" | "rest". Passed to createCamundaClient. */
+  /** CAMUNDA_TRANSPORT: "auto" | "falcon" | "rest" | "embedded". Passed to createCamundaClient. */
   transport?: string;
-  log?: (level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>) => void;
+  log?: Log;
+  /** Test seam: inject a ready-made SDK client (or a compatible fake). */
+  client?: NanoSdkClient;
   /** Test seam: provide the SDK client factory instead of importing @nanobpm/nano-sdk. */
   createClient?: (opts: { restAddress: string; token?: string; transport?: string }) => NanoSdkClient;
-  /** Test seam / customisation: the cold-path client. Defaults to a RestEngineClient. */
-  fallback?: EngineClient;
 }
 
 async function importNanoSdk(): Promise<
   (opts: Record<string, unknown>) => NanoSdkClient
 > {
-  // Indirect the specifier so the (optional, peer) module is not resolved at typecheck time.
+  // Indirect the specifier so the (lazily loaded) module is not resolved at
+  // typecheck time and stays out of the import graph for injected-client paths.
   const spec = "@nanobpm/nano-sdk";
   const mod = (await import(spec)) as {
     createCamundaClient?: (opts: Record<string, unknown>) => NanoSdkClient;
@@ -53,71 +288,32 @@ async function importNanoSdk(): Promise<
 }
 
 /**
- * Build an EngineClient backed by `@nanobpm/nano-sdk` for instance creation (Falcon) and a REST
- * fallback for everything else. Returns `null` if the SDK cannot be loaded (and no test seam was
- * given), so callers can fall back to plain REST.
+ * Build the Urban runtime's `EngineClient`, backed by a single `@nanobpm/nano-sdk`
+ * client. Provide a `client`/`createClient` seam to inject a fake (tests, embedded
+ * transport); otherwise a client is constructed from `restAddress`/`token`/`transport`.
  */
 export async function createNanoSdkEngineClient(
   opts: NanoSdkEngineOptions,
-): Promise<EngineClient | null> {
+): Promise<EngineClient> {
   const log = opts.log ?? (() => {});
   let client: NanoSdkClient;
-  try {
-    if (opts.createClient) {
-      client = opts.createClient({
-        restAddress: opts.restAddress,
-        token: opts.token,
-        transport: opts.transport,
-      });
-    } else {
-      const createCamundaClient = await importNanoSdk();
-      client = createCamundaClient({
-        config: {
-          CAMUNDA_REST_ADDRESS: opts.restAddress,
-          CAMUNDA_TOKEN: opts.token,
-          CAMUNDA_TRANSPORT: opts.transport ?? "auto",
-        },
-      });
-    }
-  } catch (err) {
-    log("warn", "nano-sdk unavailable; using REST transport", { error: String(err) });
-    return null;
+  if (opts.client) {
+    client = opts.client;
+  } else if (opts.createClient) {
+    client = opts.createClient({
+      restAddress: opts.restAddress,
+      token: opts.token,
+      transport: opts.transport,
+    });
+  } else {
+    const createCamundaClient = await importNanoSdk();
+    client = createCamundaClient({
+      config: {
+        CAMUNDA_REST_ADDRESS: opts.restAddress,
+        ...(opts.token ? { CAMUNDA_TOKEN: opts.token } : {}),
+        CAMUNDA_TRANSPORT: opts.transport ?? "auto",
+      },
+    });
   }
-
-  const fallback =
-    opts.fallback ?? new RestEngineClient({ baseUrl: opts.restAddress, token: opts.token, log });
-
-  const adapter: EngineClient = {
-    deployResources: (resources) => fallback.deployResources(resources),
-
-    async createInstance(input) {
-      const body = await client.createProcessInstance({
-        processDefinitionId: input.processDefinitionId,
-        variables: input.variables,
-        awaitCompletion: input.awaitCompletion ?? false,
-      });
-      const key =
-        (body.processInstanceKey as string | number | undefined) ?? (body.key as string | number | undefined);
-      return {
-        processInstanceKey: requireProcessInstanceKey(key),
-        variables: (body.variables as Record<string, unknown> | undefined) ?? undefined,
-      };
-    },
-
-    publishMessage: (input) => fallback.publishMessage(input),
-    searchUserTasks: (filter) => fallback.searchUserTasks(filter),
-    completeUserTask: (key, vars) => fallback.completeUserTask(key, vars),
-
-    registerWorker: (jobType: string, handler: JobHandler, options): Promise<WorkerSubscription> =>
-      fallback.registerWorker(jobType, handler, options),
-
-    async close() {
-      try {
-        await client.close?.();
-      } finally {
-        await fallback.close();
-      }
-    },
-  };
-  return adapter;
+  return new SdkEngineClient(client, log);
 }

package/src/runtime/index.ts

@@ -60,9 +60,12 @@ export { evalCorrelation } from "./core/modules/triggers.ts";
 export { createNodeHost } from "./adapters/node.ts";
 export { createDenoHost } from "./adapters/deno.ts";
 export { isDeno, selectHost } from "./adapters/detect.ts";
-export { RestEngineClient } from "./engine/rest.ts";
-export type { RestEngineOptions } from "./engine/rest.ts";
-export { createNanoSdkEngineClient } from "./engine/nanosdk.ts";
-export type { NanoSdkEngineOptions, NanoSdkClient } from "./engine/nanosdk.ts";
+export { createNanoSdkEngineClient, SdkEngineClient } from "./engine/nanosdk.ts";
+export type {
+  NanoSdkClient,
+  NanoSdkEngineOptions,
+  NanoSdkJobWorker,
+  NanoSdkJobWorkerConfig,
+} from "./engine/nanosdk.ts";
 export { runFromEnv } from "./run.ts";
 export type { RunOptions } from "./run.ts";

package/src/runtime/run.ts

@@ -1,10 +1,9 @@
 // runFromEnv — the one-call entrypoint a scaffolded app's main and the `urban run` CLI both
-// use: select the host for the current runtime, build a REST engine client from env, create
-// the Urban app, start it, and install a graceful-shutdown handler.
+// use: select the host for the current runtime, build the nano-sdk engine client from env,
+// create the Urban app, start it, and install a graceful-shutdown handler.
 
 import { createUrbanApp, type CreateUrbanAppOptions, type UrbanApp } from "./core/runtime.ts";
 import { selectHost } from "./adapters/detect.ts";
-import { RestEngineClient } from "./engine/rest.ts";
 import { createNanoSdkEngineClient } from "./engine/nanosdk.ts";
 import type { EngineClient } from "./core/host.ts";
 
@@ -14,9 +13,10 @@ export interface RunOptions extends Partial<CreateUrbanAppOptions> {
   /** Engine REST base. Default $CAMUNDA_REST_ADDRESS or http://localhost:8080/v2. */
   restAddress?: string;
   /**
-   * Engine transport: "rest" (default) uses the built-in REST client; "auto" | "falcon" try
-   * `@nanobpm/nano-sdk` (Falcon on instance creation, REST fallback), falling back to REST if the
-   * SDK is not installed. Overridable via $CAMUNDA_TRANSPORT.
+   * Engine transport passed to `@nanobpm/nano-sdk`: "auto" (default) upgrades
+   * process-instance creation and job serving to the Falcon protocol on a Nano
+   * server and falls back to REST elsewhere; "falcon" forces it; "rest" never
+   * upgrades; "embedded" runs an in-process engine. Overridable via $CAMUNDA_TRANSPORT.
    */
   transport?: string;
   /** Install SIGINT/SIGTERM handlers to stop the app. Default true. */
@@ -27,15 +27,16 @@ export async function runFromEnv(opts: RunOptions = {}): Promise<UrbanApp> {
   const host = opts.host ?? selectHost({ cwd: opts.root });
   const restAddress =
     opts.restAddress ?? host.env("CAMUNDA_REST_ADDRESS") ?? "http://localhost:8080/v2";
-  const transport = opts.transport ?? host.env("CAMUNDA_TRANSPORT") ?? "rest";
+  const transport = opts.transport ?? host.env("CAMUNDA_TRANSPORT") ?? "auto";
 
-  let engine: EngineClient | undefined = opts.engine;
-  if (!engine && transport !== "rest") {
-    engine =
-      (await createNanoSdkEngineClient({ restAddress, token: host.env("CAMUNDA_TOKEN"), transport, log: host.log })) ??
-      undefined;
-  }
-  engine ??= new RestEngineClient({ baseUrl: restAddress, token: host.env("CAMUNDA_TOKEN"), log: host.log });
+  const engine: EngineClient =
+    opts.engine ??
+    (await createNanoSdkEngineClient({
+      restAddress,
+      token: host.env("CAMUNDA_TOKEN"),
+      transport,
+      log: host.log,
+    }));
 
   const app = await createUrbanApp({
     host,

package/src/runtime/engine/rest.ts

@@ -1,243 +0,0 @@
-// A REST-backed EngineClient using only global `fetch`/`FormData`/`AbortController` — all
-// present in both Node 18+ and Deno, so this stays runtime-agnostic. Workers drain via the
-// v2 job-activation long-poll (no Falcon push dependency); the SDK-backed client can add
-// the push path later behind the same EngineClient seam.
-
-import type {
-  EngineClient,
-  EngineJob,
-  JobHandler,
-  WorkerSubscription,
-} from "../core/host.ts";
-
-export interface RestEngineOptions {
-  /** Base URL including the /v2 suffix, e.g. http://localhost:8080/v2. */
-  baseUrl: string;
-  /** Optional bearer token. */
-  token?: string;
-  /** Long-poll request timeout (ms) for job activation. Default 15000. */
-  longPollMs?: number;
-  log?: (level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>) => void;
-}
-
-function normBase(u: string): string {
-  const t = u.replace(/\/+$/, "");
-  return /\/v\d+$/.test(t) ? t : `${t}/v2`;
-}
-
-/** Coerce an engine response's process-instance key to a non-empty string, or
- * throw — a missing key means a malformed/partial response, not a real instance. */
-export function requireProcessInstanceKey(key: string | number | null | undefined): string {
-  if (key == null || key === "") {
-    throw new Error("engine response missing processInstanceKey/key");
-  }
-  return String(key);
-}
-
-export class RestEngineClient implements EngineClient {
-  private readonly base: string;
-  private readonly token?: string;
-  private readonly longPollMs: number;
-  private readonly log: NonNullable<RestEngineOptions["log"]>;
-  private readonly subs = new Set<{ stop: () => void }>();
-
-  constructor(opts: RestEngineOptions) {
-    this.base = normBase(opts.baseUrl);
-    this.token = opts.token;
-    this.longPollMs = opts.longPollMs ?? 15000;
-    this.log = opts.log ?? (() => {});
-  }
-
-  private headers(json = true): Record<string, string> {
-    const h: Record<string, string> = {};
-    if (json) h["content-type"] = "application/json";
-    if (this.token) h["authorization"] = `Bearer ${this.token}`;
-    return h;
-  }
-
-  private async req(path: string, body: unknown, init?: RequestInit): Promise<Response> {
-    const res = await fetch(`${this.base}${path}`, {
-      method: "POST",
-      headers: this.headers(),
-      body: body === undefined ? undefined : JSON.stringify(body),
-      ...init,
-    });
-    return res;
-  }
-
-  private async okJson<T>(path: string, body: unknown): Promise<T> {
-    const res = await this.req(path, body);
-    if (!res.ok) throw new Error(`${path} → ${res.status}: ${(await res.text()).slice(0, 300)}`);
-    const text = await res.text();
-    return (text ? JSON.parse(text) : {}) as T;
-  }
-
-  async deployResources(
-    resources: { name: string; content: string; contentType: string }[],
-  ): Promise<{ deployed: number }> {
-    const form = new FormData();
-    for (const r of resources) {
-      form.append("resources", new Blob([r.content], { type: r.contentType }), r.name);
-    }
-    const headers: Record<string, string> = {};
-    if (this.token) headers["authorization"] = `Bearer ${this.token}`;
-    const res = await fetch(`${this.base}/deployments`, { method: "POST", headers, body: form });
-    if (!res.ok) {
-      throw new Error(`deploy → ${res.status}: ${(await res.text()).slice(0, 300)}`);
-    }
-    return { deployed: resources.length };
-  }
-
-  async createInstance(input: {
-    processDefinitionId: string;
-    variables?: Record<string, unknown>;
-    awaitCompletion?: boolean;
-  }): Promise<{ processInstanceKey: string; variables?: Record<string, unknown> }> {
-    const r = await this.okJson<{ processInstanceKey?: string; key?: string; variables?: Record<string, unknown> }>(
-      "/process-instances",
-      {
-        processDefinitionId: input.processDefinitionId,
-        variables: input.variables ?? {},
-        awaitCompletion: input.awaitCompletion ?? false,
-      },
-    );
-    return { processInstanceKey: requireProcessInstanceKey(r.processInstanceKey ?? r.key), variables: r.variables };
-  }
-
-  async publishMessage(input: {
-    name: string;
-    correlationKey?: string;
-    variables?: Record<string, unknown>;
-  }): Promise<void> {
-    await this.okJson("/messages/publication", {
-      name: input.name,
-      correlationKey: input.correlationKey ?? "",
-      variables: input.variables ?? {},
-    });
-  }
-
-  async searchUserTasks(filter?: {
-    processInstanceKey?: string;
-    assignee?: string;
-    candidateGroup?: string;
-  }): Promise<{ userTaskKey: string; elementId?: string; variables?: Record<string, unknown> }[]> {
-    const r = await this.okJson<{ items?: Record<string, unknown>[] }>("/user-tasks/search", {
-      filter: filter ?? {},
-    });
-    return (r.items ?? []).flatMap((it) => {
-      const userTaskKey = it.userTaskKey ?? it.key;
-      if (userTaskKey == null || userTaskKey === "") {
-        this.log("warn", "skipping user task with no key in engine response");
-        return [];
-      }
-      return [{
-        userTaskKey: String(userTaskKey),
-        elementId: it.elementId as string | undefined,
-        variables: it.variables as Record<string, unknown> | undefined,
-      }];
-    });
-  }
-
-  async completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void> {
-    const res = await this.req(`/user-tasks/${userTaskKey}/completion`, { variables: variables ?? {} });
-    if (!res.ok && res.status !== 204) {
-      throw new Error(`complete user-task → ${res.status}: ${(await res.text()).slice(0, 300)}`);
-    }
-  }
-
-  async registerWorker(
-    jobType: string,
-    handler: JobHandler,
-    options?: { workerName?: string; maxParallelJobs?: number; fetchVariables?: string[] },
-  ): Promise<WorkerSubscription> {
-    const workerName = options?.workerName ?? `urban:${jobType}`;
-    const maxJobs = options?.maxParallelJobs ?? 8;
-    let running = true;
-    const control = { stop: () => (running = false) };
-    this.subs.add(control);
-
-    const activateOnce = async (): Promise<Record<string, unknown>[]> => {
-      const ctrl = new AbortController();
-      const timer = setTimeout(() => ctrl.abort(), this.longPollMs + 5000);
-      try {
-        const res = await this.req(
-          "/jobs/activation",
-          {
-            type: jobType,
-            worker: workerName,
-            timeout: 5 * 60 * 1000,
-            maxJobsToActivate: maxJobs,
-            requestTimeout: this.longPollMs,
-            fetchVariable: options?.fetchVariables ?? [],
-          },
-          { signal: ctrl.signal },
-        );
-        if (!res.ok) {
-          if (res.status !== 408) {
-            this.log("warn", `activation ${jobType} → ${res.status}`);
-          }
-          return [];
-        }
-        const body = (await res.json()) as { jobs?: Record<string, unknown>[] };
-        return body.jobs ?? [];
-      } catch (err) {
-        if (running) this.log("warn", `activation ${jobType} error`, { err: String(err) });
-        return [];
-      } finally {
-        clearTimeout(timer);
-      }
-    };
-
-    const runOne = async (raw: Record<string, unknown>): Promise<void> => {
-      const rawKey = raw.jobKey ?? raw.key;
-      if (rawKey == null || rawKey === "") {
-        this.log("warn", `activation ${jobType}: skipping job with no jobKey in engine response`);
-        return;
-      }
-      const key = String(rawKey);
-      const job: EngineJob = {
-        jobKey: key,
-        jobType,
-        processInstanceKey: raw.processInstanceKey ? String(raw.processInstanceKey) : undefined,
-        elementId: raw.elementId as string | undefined,
-        variables: (raw.variables as Record<string, unknown>) ?? {},
-      };
-      try {
-        const out = await handler(job);
-        const res = await this.req(`/jobs/${key}/completion`, { variables: out ?? {} });
-        if (!res.ok && res.status !== 204) {
-          this.log("warn", `complete ${jobType} → ${res.status}`);
-        }
-      } catch (err) {
-        await this.req(`/jobs/${key}/failure`, {
-          retries: 0,
-          errorMessage: String(err).slice(0, 500),
-        }).catch(() => {});
-        this.log("error", `handler ${jobType} threw`, { err: String(err) });
-      }
-    };
-
-    const loop = async (): Promise<void> => {
-      while (running) {
-        const jobs = await activateOnce();
-        if (!running) break;
-        if (jobs.length === 0) continue;
-        await Promise.all(jobs.map(runOne));
-      }
-    };
-    void loop();
-
-    return {
-      jobType,
-      unsubscribe: async () => {
-        control.stop();
-        this.subs.delete(control);
-      },
-    };
-  }
-
-  async close(): Promise<void> {
-    for (const s of this.subs) s.stop();
-    this.subs.clear();
-  }
-}