@nanobpm/urban 0.17.1 → 0.19.0

package/src/runtime/core/modules/connectors.ts

@@ -0,0 +1,269 @@
+// connectors — mount connector-pack workers (ADR 0050, in-process port).
+//
+// A connector is an installed npm pack that ships a `nano-ide.ext.json` manifest
+// and a worker `entry` program. The app enables it by adding a `workers[]` entry
+// with a `connector: <pack-id>` field (no `handler`/`llm`) — see `urban add` and
+// `addConnector`. This module resolves each such enabled worker to its installed
+// pack, imports the pack `entry` in-process (via the host's `@nanobpm/worker`
+// alias), and registers the drained handler on the engine like any other worker.
+//
+// The old Rust host supervised each connector worker as its own child process
+// (ADR 0050 §4). The @nanobpm/urban runtime hosts app workers in-process, so it
+// hosts connector workers the same way — trading process isolation for a simpler,
+// single-process model. `job.error(code)` still routes to a real BPMN error.
+//
+// This file is runtime-agnostic (core purity): the Node/Deno specifics of aliasing
+// the pack's `@nanobpm/worker` import live behind `host.importConnectorModule`.
+
+import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
+import { BpmnError, type EngineJob, type JobHandler, type WorkerSubscription } from "../host.ts";
+import { workerJobType, type Worker } from "../manifest.ts";
+import {
+  drainDefinedWorkers,
+  type ConnectorWorkerJob,
+  type DefinedConnectorWorker,
+} from "../../connector-worker-sdk.ts";
+
+/** A config field a pack declares (subset of ext-types `ConfigField`): an env
+ *  pointer with an optional default. */
+interface PackConfigField {
+  key: string;
+  env?: string;
+  default?: string;
+}
+
+/** A worker a pack declares (subset of ext-types `WorkerSpec`). */
+interface PackWorkerSpec {
+  type: string;
+  entry: string;
+  maxParallelJobs?: number;
+  configFields?: PackConfigField[];
+}
+
+/** The pack manifest (`nano-ide.ext.json`) fields the runtime reads. */
+interface PackManifest {
+  id: string;
+  workers?: PackWorkerSpec[];
+}
+
+/** An installed connector pack, indexed by its manifest `id`. */
+interface InstalledPack {
+  id: string;
+  /** Pack dir relative to the app root, e.g. `node_modules/@nanobpm/nano-ide-connector-slack`. */
+  dir: string;
+  manifest: PackManifest;
+}
+
+export interface ConnectorsHandle extends Mounted {
+  readonly jobTypes: string[];
+}
+
+function joinRoot(root: string, p: string): string {
+  return p.startsWith("/") ? p : `${root.replace(/\/+$/, "")}/${p.replace(/^\/+/, "")}`;
+}
+
+/** Env vars a pack worker requires before it can be imported/run: every config
+ *  field that points at an env var and has no baked default. In-process, a missing
+ *  var would let the pack's top-level guard `process.exit` the whole app, so the
+ *  runtime skips the worker instead. */
+function requiredEnv(spec: PackWorkerSpec): string[] {
+  const seen = new Set<string>();
+  for (const f of spec.configFields ?? []) {
+    if (f.env && (f.default === undefined || f.default === "")) seen.add(f.env);
+  }
+  return [...seen];
+}
+
+/** Read + parse a JSON file under the app root; undefined if absent. In `strict`
+ *  mode a malformed file throws a named parse error (used for the app's own files);
+ *  otherwise a malformed file is treated as absent (used for third-party packs). */
+async function readJson<T>(
+  ctx: RuntimeContext,
+  relPath: string,
+  opts?: { strict?: boolean },
+): Promise<T | undefined> {
+  const path = joinRoot(ctx.root, relPath);
+  if (!(await ctx.host.exists(path))) return undefined;
+  try {
+    return JSON.parse(await ctx.host.readTextFile(path)) as T;
+  } catch (err) {
+    if (opts?.strict) {
+      throw new Error(`failed to parse ${relPath}: ${(err as Error).message}`);
+    }
+    return undefined;
+  }
+}
+
+/**
+ * Discover installed connector packs: read the app `package.json` dependencies,
+ * and for each that ships a `nano-ide.ext.json` with a worker, index it by its
+ * declared pack `id` (the value a manifest `worker.connector` field carries — NOT
+ * the npm package name).
+ */
+export async function resolveInstalledConnectors(
+  ctx: RuntimeContext,
+): Promise<Map<string, InstalledPack>> {
+  const out = new Map<string, InstalledPack>();
+  const pkg = await readJson<{
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+  }>(ctx, "package.json", { strict: true });
+  if (!pkg) return out;
+  const names = new Set<string>([
+    ...Object.keys(pkg.dependencies ?? {}),
+    ...Object.keys(pkg.devDependencies ?? {}),
+    ...Object.keys(pkg.optionalDependencies ?? {}),
+  ]);
+  for (const name of names) {
+    const dir = `node_modules/${name}`;
+    const manifest = await readJson<PackManifest>(ctx, `${dir}/nano-ide.ext.json`);
+    if (!manifest || typeof manifest.id !== "string" || !manifest.id) continue;
+    if (!Array.isArray(manifest.workers) || manifest.workers.length === 0) continue;
+    out.set(manifest.id, { id: manifest.id, dir, manifest });
+  }
+  return out;
+}
+
+/** Wrap a pack's `DefinedConnectorWorker.handle` as an engine `JobHandler`,
+ *  bridging the `@nanobpm/worker` job facade (complete/fail/error) to the engine
+ *  seam. `job.error(code)` becomes a thrown {@link BpmnError} (routed to a BPMN
+ *  error boundary by the engine adapter); `job.fail(msg)` a plain throw (retry). */
+export function adaptConnectorHandler(worker: DefinedConnectorWorker): JobHandler {
+  return async (job: EngineJob) => {
+    let outcome:
+      | { kind: "complete"; vars?: Record<string, unknown> }
+      | { kind: "fail"; message: string }
+      | { kind: "error"; code: string; message?: string }
+      | undefined;
+    const facade: ConnectorWorkerJob = {
+      jobKey: job.jobKey,
+      type: job.jobType,
+      processInstanceKey: job.processInstanceKey ?? "",
+      elementId: job.elementId,
+      variables: job.variables,
+      async complete(vars) {
+        outcome = { kind: "complete", vars };
+      },
+      async fail(message) {
+        outcome = { kind: "fail", message };
+      },
+      async error(code, message) {
+        outcome = { kind: "error", code, message };
+      },
+    };
+    const ret = await worker.handle(facade);
+    if (outcome?.kind === "error") throw new BpmnError(outcome.code, outcome.message);
+    if (outcome?.kind === "fail") throw new Error(outcome.message);
+    if (outcome?.kind === "complete") return outcome.vars ?? {};
+    // No explicit outcome: fall back to the handle's return value (SDK-style).
+    return ret && typeof ret === "object" ? (ret as Record<string, unknown>) : {};
+  };
+}
+
+/**
+ * Mount every enabled connector worker (`workers[]` entries carrying a
+ * `connector` field). Fails closed on a seam mismatch (an enabled connector whose
+ * pack or worker type is not installed); skips-with-warning a worker whose
+ * required env is unset (so a missing credential does not crash the app), or when
+ * the host cannot host connector workers (`importConnectorModule` absent).
+ */
+export async function mountConnectors(ctx: RuntimeContext, app: AppApi): Promise<ConnectorsHandle> {
+  const decls = (ctx.manifest.workers ?? []).filter((w) => (w as Worker).connector) as Worker[];
+  const subs: WorkerSubscription[] = [];
+  const jobTypes: string[] = [];
+  if (decls.length === 0) return makeHandle(subs, jobTypes);
+
+  const packs = await resolveInstalledConnectors(ctx);
+  // Cache drained workers per imported entry (an entry may register several).
+  const drainedByEntry = new Map<string, Map<string, DefinedConnectorWorker>>();
+
+  for (const decl of decls) {
+    const jobType = workerJobType(decl);
+    if (!jobType) continue;
+    const packId = decl.connector!;
+    const pack = packs.get(packId);
+    if (!pack) {
+      throw new Error(
+        `connector worker "${jobType}" references pack "${packId}", which is not installed ` +
+          `(no dependency exposes a nano-ide.ext.json with id "${packId}"). Run \`urban add <pkg>\`.`,
+      );
+    }
+    const spec = pack.manifest.workers?.find((w) => w.type === jobType);
+    if (!spec) {
+      throw new Error(
+        `connector worker "${jobType}" is not provided by pack "${packId}" ` +
+          `(its nano-ide.ext.json declares no worker of that type).`,
+      );
+    }
+
+    const missing = requiredEnv(spec).filter((name) => !app.env(name));
+    if (missing.length > 0) {
+      ctx.host.log("warn", "skipping connector worker: required env unset", {
+        jobType,
+        connector: packId,
+        missing: missing.join(", "),
+      });
+      continue;
+    }
+
+    if (!ctx.host.importConnectorModule) {
+      ctx.host.log("warn", "skipping connector worker: host cannot host connector packs", {
+        jobType,
+        connector: packId,
+        runtime: ctx.host.runtime,
+      });
+      continue;
+    }
+
+    const entryAbs = joinRoot(ctx.root, `${pack.dir}/${spec.entry}`);
+    let drained = drainedByEntry.get(entryAbs);
+    if (!drained) {
+      await ctx.host.importConnectorModule(entryAbs);
+      // Fail closed on a duplicate worker `type` within one pack entry: silently
+      // keeping the last registration would bind an arbitrary handler.
+      drained = new Map<string, ReturnType<typeof drainDefinedWorkers>[number]>();
+      for (const w of drainDefinedWorkers()) {
+        if (drained.has(w.type)) {
+          throw new Error(
+            `connector pack "${packId}" entry "${spec.entry}" registered the worker ` +
+              `type "${w.type}" more than once (duplicate defineWorker call).`,
+          );
+        }
+        drained.set(w.type, w);
+      }
+      drainedByEntry.set(entryAbs, drained);
+    }
+    const worker = drained.get(jobType);
+    if (!worker) {
+      throw new Error(
+        `connector pack "${packId}" entry "${spec.entry}" did not register a worker for ` +
+          `"${jobType}" (its defineWorker call declares a different type).`,
+      );
+    }
+
+    const wrapped = adaptConnectorHandler(worker);
+    const sub = await ctx.engine.registerWorker(jobType, wrapped, {
+      workerName: `${ctx.manifest.id}:${jobType}`,
+      // The pack's `defineWorker({ maxParallelJobs })` is the authoritative runtime
+      // value; the ext.json spec is a design-time default when the code omits it.
+      maxParallelJobs: worker.maxParallelJobs ?? spec.maxParallelJobs,
+    });
+    subs.push(sub);
+    jobTypes.push(jobType);
+    ctx.host.log("info", "connector worker registered", { jobType, connector: packId });
+  }
+
+  return makeHandle(subs, jobTypes);
+}
+
+function makeHandle(subs: WorkerSubscription[], jobTypes: string[]): ConnectorsHandle {
+  return {
+    name: "connectors",
+    jobTypes,
+    async stop() {
+      await Promise.allSettled(subs.map((s) => s.unsubscribe()));
+    },
+    describe: () => ({ jobTypes }),
+  };
+}

package/src/runtime/core/modules/datasource.migrations.test.ts

@@ -0,0 +1,114 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createNodeHost } from "../../adapters/node.ts";
+import { provisionData } from "./datasource.ts";
+import type { RuntimeContext } from "../context.ts";
+import type { EngineClient } from "../host.ts";
+import type { AppManifest } from "../manifest.ts";
+
+// provisionData never touches the engine — a bare stub is enough for these datasource tests.
+const noEngine = {} as EngineClient;
+
+async function fixture(migrations: Record<string, string>): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "urban-mig-"));
+  await mkdir(join(dir, "db", "migrations"), { recursive: true });
+  for (const [name, sql] of Object.entries(migrations)) {
+    await writeFile(join(dir, "db", "migrations", name), sql);
+  }
+  return dir;
+}
+
+function ctx(dir: string): RuntimeContext {
+  const manifest = {
+    schemaVersion: 1,
+    id: "mig-fixture",
+    name: "Migration Fixture",
+    data: {
+      default: "app",
+      sources: { app: { driver: "sqlite", url: "file:./app.db", migrations: "db/migrations" } },
+    },
+  } as unknown as AppManifest;
+  return { manifest, host: createNodeHost({ cwd: dir, log: () => {} }), engine: noEngine, root: "." };
+}
+
+function columns(dir: string, table: string): string[] {
+  const db = createNodeHost({ cwd: dir, log: () => {} }).openSqlite(join(dir, "app.db"));
+  try {
+    return db.all<{ name: string }>(`PRAGMA table_info(${table})`).map((r) => r.name);
+  } finally {
+    db.close();
+  }
+}
+
+function ledger(dir: string): string[] {
+  const db = createNodeHost({ cwd: dir, log: () => {} }).openSqlite(join(dir, "app.db"));
+  try {
+    return db.all<{ name: string }>("SELECT name FROM _urban_migrations ORDER BY name").map((r) => r.name);
+  } finally {
+    db.close();
+  }
+}
+
+test("migrations apply once and are skipped on the next boot (idempotent)", async () => {
+  const dir = await fixture({
+    "001_init.sql": "CREATE TABLE rounds (id INTEGER PRIMARY KEY, summary TEXT);",
+    "002_transcript.sql": "ALTER TABLE rounds ADD COLUMN transcript TEXT;",
+  });
+  try {
+    const first = await provisionData(ctx(dir));
+    assert.deepEqual(first.source("app").migrationsApplied, ["001_init.sql", "002_transcript.sql"]);
+    first.closeAll();
+
+    assert.deepEqual(ledger(dir), ["001_init.sql", "002_transcript.sql"]);
+    assert.ok(columns(dir, "rounds").includes("transcript"));
+
+    // Second boot: everything is already recorded, so nothing re-runs (no "duplicate column").
+    const second = await provisionData(ctx(dir));
+    assert.deepEqual(second.source("app").migrationsApplied, []);
+    second.closeAll();
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("a failing migration rolls back atomically — schema is never left ahead of the ledger", async () => {
+  // Models the real urban-pr-review failure: an interrupted/failing migration must NOT leave a
+  // column present while its `_urban_migrations` row is missing, or every future boot re-applies
+  // it and dies with "duplicate column name". 002 adds `transcript`, then hits an error.
+  const dir = await fixture({
+    "001_init.sql": "CREATE TABLE rounds (id INTEGER PRIMARY KEY, summary TEXT);",
+    "002_transcript.sql":
+      "ALTER TABLE rounds ADD COLUMN transcript TEXT;\nINSERT INTO does_not_exist VALUES (1);",
+  });
+  try {
+    await assert.rejects(
+      provisionData(ctx(dir)),
+      /migration "002_transcript.sql" failed and was rolled back/,
+    );
+
+    // The whole migration rolled back: 001 is applied, but 002 left NO trace.
+    assert.deepEqual(ledger(dir), ["001_init.sql"]);
+    assert.ok(
+      !columns(dir, "rounds").includes("transcript"),
+      "the partially-applied ALTER must have been rolled back",
+    );
+
+    // Repair the migration and re-boot: because the earlier attempt left no partial state,
+    // `transcript` applies cleanly instead of colliding — the poisoned state can never arise.
+    await writeFile(
+      join(dir, "db", "migrations", "002_transcript.sql"),
+      "ALTER TABLE rounds ADD COLUMN transcript TEXT;",
+    );
+    const repaired = await provisionData(ctx(dir));
+    assert.deepEqual(repaired.source("app").migrationsApplied, ["002_transcript.sql"]);
+    repaired.closeAll();
+
+    assert.deepEqual(ledger(dir), ["001_init.sql", "002_transcript.sql"]);
+    assert.ok(columns(dir, "rounds").includes("transcript"));
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/runtime/core/modules/datasource.ts

@@ -188,11 +188,30 @@ async function applyMigrations(
   for (const file of files) {
     if (applied.has(file)) continue;
     const sql = await host.readTextFile(`${dir}/${file}`);
-    db.exec(sql);
-    db.run("INSERT INTO _urban_migrations (name, applied_at) VALUES (?, ?)", [
-      file,
-      new Date(host.now()).toISOString(),
-    ]);
+    // Apply the migration and record it in the ledger atomically. SQLite DDL is
+    // transactional, so wrapping both in one BEGIN/COMMIT makes a migration all-or-nothing:
+    // either the schema change AND its `_urban_migrations` row commit together, or neither
+    // does. Without this, an interruption (or an error later in the file's SQL) can leave the
+    // schema changed but the migration unrecorded — which poisons every future boot, because
+    // the runner then re-applies the "unapplied" migration and hits e.g. "duplicate column".
+    // Migration files must therefore not contain their own transaction-control statements.
+    db.exec("BEGIN");
+    try {
+      db.exec(sql);
+      db.run("INSERT INTO _urban_migrations (name, applied_at) VALUES (?, ?)", [
+        file,
+        new Date(host.now()).toISOString(),
+      ]);
+      db.exec("COMMIT");
+    } catch (err) {
+      db.exec("ROLLBACK");
+      throw new Error(
+        `migration "${file}" failed and was rolled back (no partial schema change, not recorded as applied): ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+        { cause: err },
+      );
+    }
     newlyApplied.push(file);
   }
   return newlyApplied;

package/src/runtime/core/modules/workers.test.ts

@@ -157,6 +157,19 @@ test("sdkDecisionEvaluator throws a clear error when the SDK lacks evaluateDecis
   await assert.rejects(evaluate("risk", {}), /does not support evaluateDecision.*"risk"/);
 });
 
+test("mountWorkers silently skips a connector-backed worker (mountConnectors owns it)", async () => {
+  const engine = new MiniEngine();
+  const { ctx, logs } = makeCtx(
+    { workers: [{ taskType: "slack:send-message", connector: "nano-ide-connector-slack" }] },
+    engine,
+  );
+  const handle = await mountWorkers(ctx, makeApp());
+  assert.deepEqual(handle.jobTypes, []);
+  assert.equal(engine.workers.size, 0);
+  // No spurious "neither a handler nor an llm" warning for a connector worker.
+  assert.ok(!logs.some((l) => l.msg.includes("neither a handler nor an llm")));
+});
+
 // ── AppJobHandler generics: optional In/Out type parameters ──────────────────────────────
 // These are primarily compile-time assertions (the suite is typechecked by `tsc --noEmit`),
 // with a runtime smoke that a typed handler still returns its output when delivered a job.

package/src/runtime/core/modules/workers.ts

@@ -109,6 +109,10 @@ export async function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<Wo
   for (const decl of decls as Worker[]) {
     const jobType = workerJobType(decl);
     if (!jobType) continue;
+    // Connector-backed workers (a `connector` field, no handler/llm) are mounted
+    // separately by mountConnectors — skip them here silently so they don't trip
+    // the "neither handler nor llm" warning below on every startup.
+    if (decl.connector) continue;
     if (!decl.handler) {
       // LLM-backed worker (schema `oneOf` handler|llm): synthesise a handler that runs
       // the job through the bound LLM (and optional decision rails) instead of loading a

package/src/runtime/core/runtime.ts

@@ -12,6 +12,7 @@ import { makeRouter, type Route } from "./router.ts";
 import { deployModels } from "./modules/deploy.ts";
 import { provisionData, DataLayer } from "./modules/datasource.ts";
 import { mountWorkers } from "./modules/workers.ts";
+import { mountConnectors } from "./modules/connectors.ts";
 import { mountSurfaces } from "./modules/surfaces.ts";
 import { mountTriggers } from "./modules/triggers.ts";
 import { mountSecurity, type SecurityPolicy } from "./modules/security.ts";
@@ -169,6 +170,11 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
           const w = await mountWorkers(ctx, api);
           mounted.push(w);
           describe.workers = w.describe?.();
+          // Connector-pack workers share the `workers` flag: same lifecycle, same
+          // engine, distinguished only by a `connector` field on the declaration.
+          const c = await mountConnectors(ctx, api);
+          mounted.push(c);
+          if (c.jobTypes.length > 0) describe.connectors = c.describe?.();
         }
 
         const routes: Route[] = [];

package/src/runtime/core/validate.test.ts

@@ -72,6 +72,30 @@ test("data.default must reference an existing source", () => {
   assert.ok(issues.some((i) => i.path === "data.default"));
 });
 
+test("a worker connection must reference a declared connections entry", () => {
+  const missing = collectManifestIssues({
+    ...valid,
+    workers: [{ taskType: "a.b", connector: "slack", connection: "slack" }],
+  });
+  assert.ok(missing.some((i) => i.path === "workers[0].connection"));
+
+  const present = collectManifestIssues({
+    ...valid,
+    workers: [{ taskType: "a.b", connector: "slack", connection: "slack" }],
+    connections: { slack: { type: "slack" } },
+  });
+  assert.ok(!present.some((i) => i.path === "workers[0].connection"));
+});
+
+test("a non-object connections does not throw and flags the reference", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    workers: [{ taskType: "a.b", connector: "slack", connection: "slack" }],
+    connections: "nope",
+  });
+  assert.ok(issues.some((i) => i.path === "workers[0].connection"));
+});
+
 test("validateManifest throws ManifestValidationError with issues", () => {
   assert.throws(() => validateManifest({ schemaVersion: 1 }), (e: unknown) => {
     assert.ok(e instanceof ManifestValidationError);

package/src/runtime/core/validate.ts

@@ -76,14 +76,38 @@ export function collectManifestIssues(m: unknown): ValidationIssue[] {
       if (!workerJobType(w)) {
         issues.push({ path: `workers[${i}]`, message: "missing taskType" });
       }
-      // The schema allows a worker backed by either a `handler` file or an `llm`
-      // binding (oneOf). Require exactly one — don't force `handler`.
-      const hasHandler = typeof w?.handler === "string" && w.handler.length > 0;
-      const hasLlm = typeof w?.llm === "string" && w.llm.length > 0;
-      if (!hasHandler && !hasLlm) {
-        issues.push({ path: `workers[${i}]`, message: "worker requires a `handler` or `llm`" });
-      } else if (hasHandler && hasLlm) {
-        issues.push({ path: `workers[${i}]`, message: "worker declares both `handler` and `llm` (mutually exclusive)" });
+      // A worker is backed by exactly one of: a `handler` file, an `llm` binding,
+      // or an installed `connector` pack (ADR 0050). The schema models these as a
+      // oneOf; enforce the "exactly one" here without forcing `handler`. Whether a
+      // `connector` actually resolves to an installed pack is a runtime seam check
+      // (mountConnectors), not something this static manifest check can see.
+      const backings: string[] = [];
+      if (typeof w?.handler === "string" && w.handler.length > 0) backings.push("handler");
+      if (typeof w?.llm === "string" && w.llm.length > 0) backings.push("llm");
+      if (typeof w?.connector === "string" && w.connector.length > 0) backings.push("connector");
+      if (backings.length === 0) {
+        issues.push({
+          path: `workers[${i}]`,
+          message: "worker requires a `handler`, `llm`, or `connector`",
+        });
+      } else if (backings.length > 1) {
+        issues.push({
+          path: `workers[${i}]`,
+          message: `worker declares ${backings.join(" + ")} (mutually exclusive)`,
+        });
+      }
+      // A `connection` must reference a declared top-level `connections` entry.
+      if (typeof w?.connection === "string" && w.connection.length > 0) {
+        const conns =
+          man.connections && typeof man.connections === "object" && !Array.isArray(man.connections)
+            ? (man.connections as Record<string, unknown>)
+            : undefined;
+        if (!conns || !(w.connection in conns)) {
+          issues.push({
+            path: `workers[${i}].connection`,
+            message: `no such connection "${w.connection}" (add it to connections)`,
+          });
+        }
       }
     });
   }

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

@@ -9,6 +9,7 @@ import {
   type NanoSdkJobWorker,
   type NanoSdkJobWorkerConfig,
 } from "./nanosdk.ts";
+import { BpmnError } from "../core/host.ts";
 
 /** A fake nano-sdk client that records calls and lets a test drive its job worker. */
 function fakeSdkClient(overrides: Partial<NanoSdkClient> = {}): NanoSdkClient & {
@@ -266,6 +267,81 @@ test("registerWorker fails the job when the handler throws", async () => {
   assert.equal(failBody?.retries, 0);
 });
 
+test("registerWorker routes a thrown BpmnError to the engine's error()", async () => {
+  const client = fakeSdkClient();
+  const engine = new SdkEngineClient(client);
+  await engine.registerWorker("svc", () => {
+    throw new BpmnError("NOT_FOUND", "no such record");
+  });
+  const rec = client.workers[0];
+  let errorBody: { errorCode: string; errorMessage?: string } | undefined;
+  await rec.dispatch({
+    jobKey: "j1",
+    variables: {},
+    async complete() {
+      throw new Error("should not complete");
+    },
+    async fail() {
+      throw new Error("should not fail — a BPMN error is not a job failure");
+    },
+    async error(body: { errorCode: string; errorMessage?: string }) {
+      errorBody = body;
+      return "raised";
+    },
+  } as unknown as NanoSdkActivatedJob);
+  assert.equal(errorBody?.errorCode, "NOT_FOUND");
+  assert.equal(errorBody?.errorMessage, "no such record");
+});
+
+test("registerWorker falls back to fail() for a BpmnError when the SDK has no error()", async () => {
+  const client = fakeSdkClient();
+  const engine = new SdkEngineClient(client);
+  await engine.registerWorker("svc", () => {
+    throw new BpmnError("NOT_FOUND", "no such record");
+  });
+  const rec = client.workers[0];
+  let failBody: { errorMessage: string } | undefined;
+  await rec.dispatch({
+    jobKey: "j1",
+    variables: {},
+    async complete() {
+      throw new Error("should not complete");
+    },
+    async fail(body: { errorMessage: string }) {
+      failBody = body;
+      return "failed";
+    },
+    // no error() — older transport
+  } as unknown as NanoSdkActivatedJob);
+  assert.equal(failBody?.errorMessage, "no such record");
+});
+
+test("registerWorker falls back to fail() when the BPMN error report itself throws", async () => {
+  const client = fakeSdkClient();
+  const engine = new SdkEngineClient(client);
+  await engine.registerWorker("svc", () => {
+    throw new BpmnError("NOT_FOUND", "no such record");
+  });
+  const rec = client.workers[0];
+  let failBody: { errorMessage: string } | undefined;
+  await rec.dispatch({
+    jobKey: "j1",
+    variables: {},
+    async complete() {
+      throw new Error("should not complete");
+    },
+    async error() {
+      throw new Error("transport down");
+    },
+    async fail(body: { errorMessage: string }) {
+      failBody = body;
+      return "failed";
+    },
+  } as unknown as NanoSdkActivatedJob);
+  // The job must still be acknowledged via fail() rather than silently dropped.
+  assert.equal(failBody?.errorMessage, "no such record");
+});
+
 test("close stops every worker and closes the SDK client", async () => {
   const client = fakeSdkClient();
   const engine = new SdkEngineClient(client);