@nanobpm/urban 0.77.0 → 0.77.2

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

@@ -11,7 +11,8 @@
 //   GET  /              (+ /app/runtime.js)         → the schema-driven browser renderer
 //   GET  /app/pages/<id>                            → the page's page.json
 //   GET  /app/data/<source>/<table>[?where&order]   → rows (filtered/ordered, whitelisted)
-//   GET  /{embed,standalone}.html /mount.js /cockpit.css → appView sidecars (from pagesDir, #420)
+//   GET  /{embed,standalone}.html /mount.js /cockpit.css → flat appView sidecars (from pagesDir, #420)
+//   GET  /<subdir>/<asset>                          → nested appView sidecars (pages/<subdir>/…, #442)
 //   GET  /dist/<path>                               → the app dist/ bundle the sidecars reference
 //   POST /app/actions/start/<process>               → engine.createInstance
 //   POST /app/actions/cancel                        → engine.cancelInstance
@@ -107,7 +108,10 @@ function javascript(
 // document then pulls `./cockpit.css`, `./mount.js`, and (via its import-map)
 // `../dist/…`. A DEPLOYED app served none of these, so the src 404'd and the cockpit
 // iframe loaded nothing (#416's user-facing "nothing shows in the Cockpit"). These are
-// the root-served sidecar files, mapped 1:1 onto `pagesDir/<name>`. The `dist/` tree the
+// the root-served sidecar files, mapped 1:1 onto `pagesDir/<name>`. An app that ships
+// MORE than one `appView` gives each its own SUBDIR sidecar (`./cockpit/embed.html`,
+// `./board/embed.html`, …) — those are served by the nested prefix route below (#442);
+// this flat set stays as the single-appView back-compat case (#420). The `dist/` tree the
 // import-map references is served separately under the `/dist/` prefix below.
 const SIDECAR_ASSETS = ["embed.html", "standalone.html", "mount.js", "cockpit.css"] as const;
 
@@ -541,6 +545,44 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
     },
   });
 
+  // ── nested (multi-appView) sidecars (#442) ──────────────────────────────
+  // An app with more than one `appView` cannot share the four FLAT sidecar names above:
+  // each view ships its own SUBDIR sidecar — e.g. `pages/cockpit.page.json` →
+  // `./cockpit/embed.html`, `pages/board.page.json` → `./board/embed.html`. The renderer's
+  // `baseRelativeUrl(p.embed)` rebases those onto the mount root, so the browser fetches
+  // `/cockpit/embed.html`, `/board/mount.js`, … — every one of which #420's flat 4-name
+  // serve 404'd. Serve the `pagesDir` as a TREE, mapping `/<subpath>` onto
+  // `pagesDir/<subpath>` with the SAME traversal guard as the `/dist/` route (mirroring it).
+  // It is a `/`-prefix route, so to avoid a root catch-all silently swallowing `/healthz`,
+  // the app's own trigger routes, or any other route, the handler DECLINES (returns
+  // undefined → the router falls through to the next route, see `RouteHandler`) whenever it
+  // cannot serve a real nested asset:
+  //   • a bare single-segment path (`/healthz`, the flat sidecars) — owned by its own exact
+  //     route / the runtime's liveness route, never this tree;
+  //   • an unsafe subpath (`..`/absolute/percent-escaped/backslash) — traversal-rejected
+  //     before it reaches the filesystem;
+  //   • a miss (no such file) — so a same-path route registered AFTER the pages surface (a
+  //     trigger, the appended `/healthz`) still resolves instead of being masked by a 404.
+  // Registered LAST among the pages routes so every exact/prefix pages route above wins first.
+  routes.push({
+    method: "GET",
+    path: "/",
+    prefix: true,
+    source: "surface:pages",
+    handler: async (req) => {
+      const rest = req.path.slice(1); // drop the leading "/"
+      // Only a SUBDIR asset (has a `/`) belongs to this tree; a single-segment path is left
+      // to its own exact route / the appended `/healthz` liveness route.
+      if (!rest.includes("/")) return undefined;
+      const safe = safeAssetSubpath(rest);
+      if (safe === null) return undefined; // traversal/escape → decline (never touch the FS)
+      const res = await serveAsset(readAsset, `${pagesDir}/${safe}`);
+      // A miss declines rather than 404s, so a later same-path route (e.g. a trigger) can
+      // still claim it; the router's own default 404 covers a genuinely absent asset.
+      return res.status === 404 ? undefined : res;
+    },
+  });
+
   return routes;
 }
 

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

@@ -4,9 +4,10 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { mountSurfaces } from "./surfaces.ts";
-import type { EngineClient, HostContext, HttpRequest, HttpResponse } from "../host.ts";
+import type { EngineClient, HostContext, HttpResponse } from "../host.ts";
 import { DataLayer } from "./datasource.ts";
 import { createLogger } from "../logger.ts";
+import type { Route } from "../router.ts";
 
 function ctxWith(surfaces: Record<string, unknown>): Parameters<typeof mountSurfaces>[0] {
   const host: HostContext = {
@@ -63,7 +64,7 @@ const fakeApp: Parameters<typeof mountSurfaces>[1] = {
   log: createLogger(() => {}),
 };
 
-async function render(route: { handler: (req: HttpRequest) => HttpResponse | Promise<HttpResponse> }): Promise<string> {
+async function render(route: Route): Promise<string> {
   const res = await route.handler({
     method: "GET",
     path: "/",
@@ -71,6 +72,7 @@ async function render(route: { handler: (req: HttpRequest) => HttpResponse | Pro
     headers: new Headers(),
     text: async () => "",
   });
+  assert.ok(res, "handler should not decline");
   return String(res.body);
 }
 
@@ -118,16 +120,18 @@ function appWith(engine: EngineClient): Parameters<typeof mountSurfaces>[1] {
 
 /** Invoke a route handler with an optional query string and POST body. */
 async function call(
-  route: { handler: (req: HttpRequest) => HttpResponse | Promise<HttpResponse> },
+  route: Route,
   opts: { method?: string; query?: string; body?: string } = {},
 ): Promise<HttpResponse> {
-  return route.handler({
+  const res = await route.handler({
     method: opts.method ?? "GET",
     path: "/",
     query: new URLSearchParams(opts.query ?? ""),
     headers: new Headers(),
     text: async () => opts.body ?? "",
   });
+  assert.ok(res, "handler should not decline");
+  return res;
 }
 
 function inboxRoutes(engine: EngineClient) {

package/src/runtime/core/router.ts

@@ -4,12 +4,25 @@
 
 import type { HttpHandler, HttpRequest, HttpResponse } from "./host.ts";
 
+/**
+ * A route handler that may DECLINE a matched request by returning `undefined`
+ * (or a promise of it). The router then treats the route as if it had not matched
+ * and continues to the next route (fall-through). This lets a broad prefix route —
+ * e.g. the pages surface's nested static serve at `/` — claim only the requests it
+ * can actually satisfy (a real, safe asset) and let everything else (`/healthz`, an
+ * app's own trigger routes registered *after* it) resolve to their own handlers,
+ * instead of a root catch-all silently swallowing them. A handler that returns a
+ * concrete `HttpResponse` (including a 404) still short-circuits as before, so this
+ * is backwards-compatible with every existing handler (none return `undefined`).
+ */
+export type RouteHandler = (req: HttpRequest) => Promise<HttpResponse | undefined> | HttpResponse | undefined;
+
 export interface Route {
   method: string;
   path: string;
   /** When true, match any path that starts with `path`. */
   prefix?: boolean;
-  handler: HttpHandler;
+  handler: RouteHandler;
   /** For diagnostics / inspect(). */
   source?: string;
 }
@@ -61,7 +74,13 @@ function matches(route: Route, req: HttpRequest): boolean {
 export function makeRouter(routes: Route[]): HttpHandler {
   return async (req: HttpRequest): Promise<HttpResponse> => {
     for (const route of routes) {
-      if (matches(route, req)) return route.handler(req);
+      if (matches(route, req)) {
+        // A handler may DECLINE by returning `undefined` (see RouteHandler): treat the
+        // route as unmatched and keep looking, so a broad prefix serve can't shadow a
+        // later exact route (`/healthz`, a trigger) it didn't actually satisfy.
+        const res = await route.handler(req);
+        if (res !== undefined) return res;
+      }
     }
     return text("not found", 404);
   };

package/src/toolkit/derivers/api.test.ts

@@ -108,6 +108,34 @@ test("emitApiController on an empty spec is a valid empty registry (never = {})"
   assert.match(out, /export const operations = \{\s*\} satisfies \{/);
 });
 
+test("emitApiBindings on an empty spec emits the Record<never, never> ApiOperations fallback (not an empty interface)", () => {
+  const empty: OpenApiDoc = { openapi: "3.0.0", paths: {} };
+  const out = emitApiBindings(empty);
+  assert.match(out, /export type ApiOperationId = never;/);
+  // A generated `.ts` file is now linted in the scaffold, where `interface ApiOperations {}` would
+  // trip `suspicious/noEmptyInterface`; the empty spec must degrade to the non-empty-safe alias.
+  assert.match(out, /export type ApiOperations = Record<never, never>;/);
+  assert.doesNotMatch(out, /interface ApiOperations/);
+});
+
+test("emitApiController orders imports by true numeric value for digit runs beyond IEEE-754 precision", () => {
+  // 16- vs 17-digit runs: `Number()` collapses these to the same float (and can yield NaN), so a
+  // float-subtraction sort would treat them as equal and leave order to chance. The 17-digit run is
+  // numerically larger and must sort last regardless.
+  const doc: OpenApiDoc = {
+    openapi: "3.0.0",
+    paths: {
+      "/b": { get: { operationId: "op10000000000000001", responses: { "200": {} } } },
+      "/a": { get: { operationId: "op9999999999999999", responses: { "200": {} } } },
+    },
+  };
+  const out = emitApiController(doc, "handlers");
+  const iShort = out.indexOf("op9999999999999999.ts");
+  const iLong = out.indexOf("op10000000000000001.ts");
+  assert.ok(iShort >= 0 && iLong >= 0, out);
+  assert.ok(iShort < iLong, `16-digit run must sort before the larger 17-digit run:\n${out}`);
+});
+
 test("emitApiController throws on a duplicate operationId (would silently overwrite a map key)", () => {
   const dupe: OpenApiDoc = {
     openapi: "3.0.0",

package/src/toolkit/derivers/api.ts

@@ -34,6 +34,44 @@ export const API_CONTROLLER_TS = "controller.ts";
 export { DEFAULT_OPERATIONS_DIR };
 
 
+/** Order two import source specifiers the way Biome's `organizeImports` assist does, so the
+ *  controller emits its delegate imports in Biome's canonical order and the generated file passes
+ *  `biome check` without a post-generation import sort. Biome's collation is, per character:
+ *  digit-runs compared numerically (`item2` before `item10`), letters compared case-insensitively
+ *  as the primary key, and — when two characters are the same letter differing only in case — the
+ *  uppercase one sorts first as an immediate tiebreak (`getAgentInstructions` before
+ *  `getAgenticRegistry` before `getAgentSkill`). */
+function naturalCompare(a: string, b: string): number {
+  const tokens = (s: string): string[] => s.match(/\d+|\D/g) ?? [];
+  const isDigitRun = (t: string): boolean => t.charCodeAt(0) >= 48 && t.charCodeAt(0) <= 57;
+  const ax = tokens(a);
+  const bx = tokens(b);
+  const n = Math.min(ax.length, bx.length);
+  for (let i = 0; i < n; i++) {
+    const ca = ax[i];
+    const cb = bx[i];
+    if (ca === undefined || cb === undefined) break;
+    if (isDigitRun(ca) && isDigitRun(cb)) {
+      // Compare digit runs by numeric value *without* floating-point loss: strip leading zeros,
+      // then a longer run is the larger number, else compare the equal-length digits lexically.
+      // (`Number(ca) - Number(cb)` collapses 17+-digit runs to the same IEEE-754 value and yields
+      //  `NaN` beyond `Number.MAX_SAFE_INTEGER`, both of which break the total order `sort` needs.)
+      const na = ca.replace(/^0+/, "");
+      const nb = cb.replace(/^0+/, "");
+      if (na.length !== nb.length) return na.length < nb.length ? -1 : 1;
+      if (na !== nb) return na < nb ? -1 : 1;
+      if (ca !== cb) return ca < cb ? -1 : 1; // equal value, differing leading zeros
+    } else if (ca !== cb) {
+      const la = ca.toLowerCase();
+      const lb = cb.toLowerCase();
+      if (la !== lb) return la < lb ? -1 : 1; // case-insensitive primary key
+      return ca < cb ? -1 : 1; // same letter, different case → uppercase (lower code point) first
+    }
+  }
+  return ax.length - bx.length;
+}
+
+
 /** A TS identifier form of an operationId (used for the per-op type names). */
 function typeStem(operationId: string): string {
   const cleaned = operationId.replace(/[^A-Za-z0-9]+/g, " ").trim();
@@ -156,7 +194,7 @@ function objectToTs(schema: OpenApiSchema, depth: number): string {
  *  not enforce presence for ejected ops, so a "required" query param may in fact be absent. */
 function paramsTs(op: OperationInfo, where: "path" | "query", ejected: boolean): string {
   const ps = op.parameters.filter((p) => p.in === where);
-  if (ps.length === 0) return "{}";
+  if (ps.length === 0) return "Record<string, never>";
   const rawWire = where === "query" ? "string | string[]" : "string";
   const fields = ps.map((p) => {
     // Coerced to the schema type (number/boolean/array/enum/…); optionality is carried by the `?`
@@ -211,8 +249,7 @@ export function emitApiBindings(doc: OpenApiDoc, surfaceEject = false): string {
     "// The endpoint type map: each operationId maps to its typed request (coerced path/query params\n" +
     "// + JSON body) and response (a union of every documented JSON response body), derived from the\n" +
     "// spec. Do not edit — regenerated from\n" +
-    "// the spec; erased to plain JS at compile.\n" +
-    "// eslint-disable\n\n";
+    "// the spec; erased to plain JS at compile.\n\n";
 
   const componentDecls = Object.entries(components)
     .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
@@ -272,6 +309,13 @@ export function emitApiBindings(doc: OpenApiDoc, surfaceEject = false): string {
     })
     .join("\n");
 
+  // With generated `.ts` now linted in the scaffold, an empty operation set must NOT emit an empty
+  // `interface ApiOperations {}` (`suspicious/noEmptyInterface`); fall back to the same non-empty-safe
+  // `Record<never, never>` used elsewhere (its `keyof` is `never`, matching `ApiOperationId = never`).
+  const apiOperations = ops.length > 0
+    ? `export interface ApiOperations {\n${mapEntries}\n}\n`
+    : `export type ApiOperations = Record<never, never>;\n`;
+
   return (
     header +
     (componentDecls ? `${componentDecls}\n\n` : "") +
@@ -279,7 +323,7 @@ export function emitApiBindings(doc: OpenApiDoc, surfaceEject = false): string {
     `/** Every declared operationId (ADR 0058): the delegate key set. */\n` +
     `export type ApiOperationId = ${idUnion};\n\n` +
     `/** Request/response contract per operationId. */\n` +
-    `export interface ApiOperations {\n${mapEntries}\n}\n`
+    apiOperations
   );
 }
 
@@ -291,10 +335,9 @@ export function emitApiBindingsRuntime(): string {
     "// AUTO-GENERATED by @nanobpm/urban (ADR 0058): the typed `defineOperation`.\n" +
     "// Re-exports the operation SDK and overrides `defineOperation` with an operationId-keyed\n" +
     "// signature (the delegate's validated request + result typed from the spec). Erased to a\n" +
-    "// pass-through at runtime. Do not edit.\n" +
-    "// eslint-disable\n\n" +
-    `import { defineOperation as defineOperationRaw } from "@nanobpm/urban";\n` +
+    "// pass-through at runtime. Do not edit.\n\n" +
     `import type { OperationHandler } from "@nanobpm/urban";\n` +
+    `import { defineOperation as defineOperationRaw } from "@nanobpm/urban";\n` +
     `import type { ApiOperationId, ApiOperations } from "./${API_BINDINGS_DTS}";\n\n` +
     `type ReqFor<K extends ApiOperationId> = ApiOperations[K]["request"];\n` +
     `type ResFor<K extends ApiOperationId> = ApiOperations[K]["response"];\n\n` +
@@ -342,23 +385,26 @@ export function emitApiController(doc: OpenApiDoc, operationsDir: string = DEFAU
     "// registry. Statically imports every operation delegate and asserts the complete, correctly-\n" +
     "// typed set via `satisfies` — a missing, mismatched, or orphan delegate fails `tsc`. The\n" +
     "// runtime dispatches through this map, so endpoints cannot drift from the spec. Do not edit —\n" +
-    "// regenerated from the spec.\n" +
-    "// eslint-disable\n\n";
-
-  const typeImports =
-    `import type { OperationHandler } from "@nanobpm/urban";\n` +
-    `import type { ApiOperationId, ApiOperations } from "./${API_BINDINGS_DTS}";\n`;
+    "// regenerated from the spec.\n\n";
 
+  // Emit imports in Biome's canonical `organizeImports` order so the generated file is lint-clean
+  // without a post-gen fixup: the bare package import first, then the delegate imports sorted by
+  // source specifier (Biome's natural, numeric-aware collation), then the relative `./api-io.d.ts`
+  // type import last. Alias bindings (`op<i>`) stay tied to the original index so the `operations`
+  // map below still resolves each operationId to its delegate regardless of import line order.
   const delegateImports = ops
-    .map((op, i) => `import op${i} from ${JSON.stringify(`../${dir}/${op.operationId}.ts`)};`)
+    .map((op, i) => ({ i, spec: `../${dir}/${op.operationId}.ts` }))
+    .sort((a, b) => naturalCompare(a.spec, b.spec))
+    .map(({ i, spec }) => `import op${i} from ${JSON.stringify(spec)};`)
     .join("\n");
 
   const mapEntries = ops.map((op, i) => `  ${JSON.stringify(op.operationId)}: op${i},`).join("\n");
 
   return (
     header +
-    typeImports +
+    `import type { OperationHandler } from "@nanobpm/urban";\n` +
     (delegateImports ? `${delegateImports}\n` : "") +
+    `import type { ApiOperationId, ApiOperations } from "./${API_BINDINGS_DTS}";\n` +
     `\n` +
     `type ReqFor<K extends ApiOperationId> = ApiOperations[K]["request"];\n` +
     `type ResFor<K extends ApiOperationId> = ApiOperations[K]["response"];\n\n` +

package/src/toolkit/derivers/bindings-parity.test.ts

@@ -7,7 +7,7 @@ import { emitMessageBindings, emitMessageBindingsRuntime } from "./messages.ts";
 // Byte-exact goldens for the emitters ported into the toolkit for the domaintypes op (host dry-out
 // nano-bpm#576). Captured verbatim from the console's own emitters via Deno; these lock the toolkit
 // output to the console byte-for-byte so the two can never drift while both exist.
-const GOLDENS: Record<string, string> = JSON.parse("{\"bindings\":\"// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1/§6).\\n// The typed data-object layer: `openDomain()` → one `Table<T>` per table, so\\n// workers manipulate typed rows instead of hand-writing SQL. Do not edit —\\n// regenerated from the live tables. Erased to plain JS at `deno compile`.\\n// eslint-disable\\n\\nimport { openDataSource, type DataSource, type Table } from \\\"./data-sdk.ts\\\";\\nimport type { Customers, Orders } from \\\"./domain-rows.d.ts\\\";\\n\\nexport interface Domain {\\n  /** The underlying datasource handle — the raw-SQL escape hatch. */\\n  readonly raw: DataSource;\\n  readonly orders: Table<Orders>;\\n  readonly customers: Table<Customers>;\\n  /** Close the underlying connection. */\\n  close(): void;\\n}\\n\\n/**\\n * Open the App's datasource as a typed domain: each table is\\n * a `Table<T>` gateway (`db.orders.insert(...)`, `db.orders.get(id)`), with the\\n * raw `DataSource` at `db.raw` for anything the gateway doesn't cover.\\n */\\nexport async function openDomain(source?: string): Promise<Domain> {\\n  const raw = await openDataSource(source);\\n  return {\\n    raw,\\n    orders: raw.table<Orders>(\\\"orders\\\", \\\"id\\\"),\\n    customers: raw.table<Customers>(\\\"customers\\\", \\\"id\\\"),\\n    close: () => raw.close(),\\n  };\\n}\\n\\nexport type { Table };\\n\",\"workerRuntime\":\"// AUTO-GENERATED by nanobpmn (ADR 0033 §3): the typed `defineWorker`.\\n// Re-exports the worker SDK and overrides `defineWorker` with a taskType-keyed\\n// typed signature (job.variables, job.customHeaders + result typed from the\\n// worker's declared input/output/header contract). Erased to a pass-through at\\n// runtime. Do not edit.\\n// eslint-disable\\n\\nimport { defineWorker as defineWorkerRaw } from \\\"./worker-sdk.ts\\\";\\nimport type { WorkerOptions } from \\\"./worker-sdk.ts\\\";\\nimport type { WorkerInputs, WorkerOutputs, WorkerHeaders, WorkerTaskType, WorkerVars, WorkerHdrs } from \\\"./worker-io.d.ts\\\";\\n\\nexport * from \\\"./worker-sdk.ts\\\";\\n\\ntype InFor<K extends WorkerTaskType> = K extends keyof WorkerInputs ? WorkerInputs[K] : WorkerVars;\\ntype OutFor<K extends WorkerTaskType> = K extends keyof WorkerOutputs ? WorkerOutputs[K] : WorkerVars;\\ntype HdrFor<K extends WorkerTaskType> = K extends keyof WorkerHeaders ? WorkerHeaders[K] : WorkerHdrs;\\n\\n/**\\n * Typed `defineWorker`: `type` is constrained to the model's declared job types\\n * (`WorkerTaskType`, ADR 0033 §3) so it autocompletes and rejects unknown jobs,\\n * and the handler's `job.variables`, `job.customHeaders` + result are typed from\\n * the worker's declared `inputType`/`outputType`/header keys. A declared job type\\n * with no declared type falls back to WorkerVars / WorkerHdrs.\\n */\\nexport function defineWorker<K extends WorkerTaskType>(\\n  opts: { type: K } & WorkerOptions<InFor<K> & object, OutFor<K> & object, HdrFor<K> & object>,\\n): void {\\n  defineWorkerRaw(opts as unknown as WorkerOptions);\\n}\\n\",\"messageRuntime\":\"// AUTO-GENERATED by nanobpmn (ADR 0040 slice 2): the typed `publishMessage`.\\n// Re-exports the worker SDK's `publishMessage` and overrides it with a\\n// messageName-keyed typed signature (variables typed from the message's declared\\n// envelope). Erased to a pass-through at runtime. Do not edit.\\n// eslint-disable\\n\\nimport { publishMessage as publishMessageRaw } from \\\"./worker-sdk.ts\\\";\\nimport type { PublishMessageOptions, PublishMessageResult } from \\\"./worker-sdk.ts\\\";\\nimport type { MessageName, MessagePayloads, MessageVars } from \\\"./message-io.d.ts\\\";\\n\\nexport type { PublishMessageOptions, PublishMessageResult } from \\\"./worker-sdk.ts\\\";\\n\\ntype PayloadFor<K extends MessageName> = K extends keyof MessagePayloads ? MessagePayloads[K] : MessageVars;\\n\\n/**\\n * Typed `publishMessage`: `name` is constrained to the model's declared message\\n * names (`MessageName`, ADR 0040 slice 2) so it autocompletes and rejects unknown\\n * messages, and `variables` are typed from the message's declared envelope. A\\n * declared message with no domain type falls back to MessageVars.\\n */\\nexport function publishMessage<K extends MessageName>(\\n  name: K,\\n  opts?: PublishMessageOptions<PayloadFor<K> & object>,\\n): Promise<PublishMessageResult> {\\n  return publishMessageRaw(name, opts as unknown as PublishMessageOptions);\\n}\\n\",\"workerBindingsWithHeaders\":\"// AUTO-GENERATED by nanobpmn from the App manifest (ADR 0033 §3).\\n// The bridge from the process model to the worker type system: each declared\\n// worker's `taskType` maps to the TS type of its input payload (`job.variables`)\\n// and result, so the typed `defineWorker` types a handler by its job type. Do\\n// not edit — regenerated from the manifest. Erased to plain JS at compile.\\n// eslint-disable\\n\\nimport type { DomainTypes } from \\\"./domain-rows.d.ts\\\";\\n\\n/** Untyped fallback for a job whose worker declares no input/output type. */\\nexport type WorkerVars = Record<string, unknown>;\\n\\n/** Untyped fallback for a job whose worker declares no custom headers. */\\nexport type WorkerHdrs = Record<string, unknown>;\\n\\n/** Every declared worker `taskType` (ADR 0033 §3): the model-derived set the\\n * typed `defineWorker` accepts, so `type` autocompletes and rejects unknown jobs. */\\nexport type WorkerTaskType = \\\"review\\\";\\n\\n/** Input payload (`job.variables`) per declared worker, keyed by `taskType`. */\\nexport interface WorkerInputs {\\n  \\\"review\\\": DomainTypes[\\\"Order\\\"];\\n}\\n\\n/** Output payload (worker result) per declared worker, keyed by `taskType`. */\\nexport interface WorkerOutputs {\\n  \\\"review\\\": DomainTypes[\\\"Order\\\"];\\n}\\n\\n/** Custom headers (`job.customHeaders`) per declared worker, keyed by `taskType`.\\n * Header values are strings on the wire, so each declared key maps to `string`;\\n * the extra index signature keeps undeclared headers accessible (non-breaking). */\\nexport interface WorkerHeaders {\\n  \\\"review\\\": { \\\"priority\\\": string; \\\"x-flag\\\": string; [key: string]: string };\\n}\\n\",\"messageBindings\":\"// AUTO-GENERATED by nanobpmn from the process model (ADR 0040 slice 2).\\n// The bridge from a `bpmn:message`'s data envelope to the message type system:\\n// each named message maps to the TS type of its payload, so the typed\\n// `publishMessage` types a call by its message name. Do not edit — regenerated\\n// from the model. Erased to plain JS at compile.\\n// eslint-disable\\n\\nimport type { DomainTypes } from \\\"./domain-rows.d.ts\\\";\\n\\n/** Untyped fallback payload for a message that declares no envelope type. */\\nexport type MessageVars = Record<string, unknown>;\\n\\n/** Every declared message `name` (ADR 0040 slice 2): the model-derived set the\\n * typed `publishMessage` accepts, so `name` autocompletes and rejects unknown messages. */\\nexport type MessageName = \\\"approved\\\";\\n\\n/** Payload (`variables`) per declared message, keyed by `name`. */\\nexport interface MessagePayloads {\\n  \\\"approved\\\": DomainTypes[\\\"Order\\\"];\\n}\\n\"}\n");
+const GOLDENS: Record<string, string> = JSON.parse("{\"bindings\":\"// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1/§6).\\n// The typed data-object layer: `openDomain()` → one `Table<T>` per table, so\\n// workers manipulate typed rows instead of hand-writing SQL. Do not edit —\\n// regenerated from the live tables. Erased to plain JS at `deno compile`.\\n\\nimport { type DataSource, openDataSource, type Table } from \\\"./data-sdk.ts\\\";\\nimport type { Customers, Orders } from \\\"./domain-rows.d.ts\\\";\\n\\nexport interface Domain {\\n  /** The underlying datasource handle — the raw-SQL escape hatch. */\\n  readonly raw: DataSource;\\n  readonly orders: Table<Orders>;\\n  readonly customers: Table<Customers>;\\n  /** Close the underlying connection. */\\n  close(): void;\\n}\\n\\n/**\\n * Open the App's datasource as a typed domain: each table is\\n * a `Table<T>` gateway (`db.orders.insert(...)`, `db.orders.get(id)`), with the\\n * raw `DataSource` at `db.raw` for anything the gateway doesn't cover.\\n */\\nexport async function openDomain(source?: string): Promise<Domain> {\\n  const raw = await openDataSource(source);\\n  return {\\n    raw,\\n    orders: raw.table<Orders>(\\\"orders\\\", \\\"id\\\"),\\n    customers: raw.table<Customers>(\\\"customers\\\", \\\"id\\\"),\\n    close: () => raw.close(),\\n  };\\n}\\n\\nexport type { Table };\\n\",\"workerRuntime\":\"// AUTO-GENERATED by nanobpmn (ADR 0033 §3): the typed `defineWorker`.\\n// Re-exports the worker SDK and overrides `defineWorker` with a taskType-keyed\\n// typed signature (job.variables, job.customHeaders + result typed from the\\n// worker's declared input/output/header contract). Erased to a pass-through at\\n// runtime. Do not edit.\\n\\nimport type { WorkerHdrs, WorkerHeaders, WorkerInputs, WorkerOutputs, WorkerTaskType, WorkerVars } from \\\"./worker-io.d.ts\\\";\\nimport type { WorkerOptions } from \\\"./worker-sdk.ts\\\";\\nimport { defineWorker as defineWorkerRaw } from \\\"./worker-sdk.ts\\\";\\n\\nexport * from \\\"./worker-sdk.ts\\\";\\n\\ntype InFor<K extends WorkerTaskType> = K extends keyof WorkerInputs ? WorkerInputs[K] : WorkerVars;\\ntype OutFor<K extends WorkerTaskType> = K extends keyof WorkerOutputs ? WorkerOutputs[K] : WorkerVars;\\ntype HdrFor<K extends WorkerTaskType> = K extends keyof WorkerHeaders ? WorkerHeaders[K] : WorkerHdrs;\\n\\n/**\\n * Typed `defineWorker`: `type` is constrained to the model's declared job types\\n * (`WorkerTaskType`, ADR 0033 §3) so it autocompletes and rejects unknown jobs,\\n * and the handler's `job.variables`, `job.customHeaders` + result are typed from\\n * the worker's declared `inputType`/`outputType`/header keys. A declared job type\\n * with no declared type falls back to WorkerVars / WorkerHdrs.\\n */\\nexport function defineWorker<K extends WorkerTaskType>(\\n  opts: { type: K } & WorkerOptions<InFor<K> & object, OutFor<K> & object, HdrFor<K> & object>,\\n): void {\\n  // biome-ignore lint/plugin: generic-to-raw erasure at the worker-SDK boundary; the wire stays untyped JSON (ADR 0033 §3).\\n  defineWorkerRaw(opts as unknown as WorkerOptions);\\n}\\n\",\"messageRuntime\":\"// AUTO-GENERATED by nanobpmn (ADR 0040 slice 2): the typed `publishMessage`.\\n// Re-exports the worker SDK's `publishMessage` and overrides it with a\\n// messageName-keyed typed signature (variables typed from the message's declared\\n// envelope). Erased to a pass-through at runtime. Do not edit.\\n\\nimport type { MessageName, MessagePayloads, MessageVars } from \\\"./message-io.d.ts\\\";\\nimport type { PublishMessageOptions, PublishMessageResult } from \\\"./worker-sdk.ts\\\";\\nimport { publishMessage as publishMessageRaw } from \\\"./worker-sdk.ts\\\";\\n\\nexport type { PublishMessageOptions, PublishMessageResult } from \\\"./worker-sdk.ts\\\";\\n\\ntype PayloadFor<K extends MessageName> = K extends keyof MessagePayloads ? MessagePayloads[K] : MessageVars;\\n\\n/**\\n * Typed `publishMessage`: `name` is constrained to the model's declared message\\n * names (`MessageName`, ADR 0040 slice 2) so it autocompletes and rejects unknown\\n * messages, and `variables` are typed from the message's declared envelope. A\\n * declared message with no domain type falls back to MessageVars.\\n */\\nexport function publishMessage<K extends MessageName>(\\n  name: K,\\n  opts?: PublishMessageOptions<PayloadFor<K> & object>,\\n): Promise<PublishMessageResult> {\\n  // biome-ignore lint/plugin: generic-to-raw erasure at the message-SDK boundary; the wire stays untyped JSON (ADR 0040 slice 2).\\n  return publishMessageRaw(name, opts as unknown as PublishMessageOptions);\\n}\\n\",\"workerBindingsWithHeaders\":\"// AUTO-GENERATED by nanobpmn from the App manifest (ADR 0033 §3).\\n// The bridge from the process model to the worker type system: each declared\\n// worker's `taskType` maps to the TS type of its input payload (`job.variables`)\\n// and result, so the typed `defineWorker` types a handler by its job type. Do\\n// not edit — regenerated from the manifest. Erased to plain JS at compile.\\n\\nimport type { DomainTypes } from \\\"./domain-rows.d.ts\\\";\\n\\n/** Untyped fallback for a job whose worker declares no input/output type. */\\nexport type WorkerVars = Record<string, unknown>;\\n\\n/** Untyped fallback for a job whose worker declares no custom headers. */\\nexport type WorkerHdrs = Record<string, unknown>;\\n\\n/** Every declared worker `taskType` (ADR 0033 §3): the model-derived set the\\n * typed `defineWorker` accepts, so `type` autocompletes and rejects unknown jobs. */\\nexport type WorkerTaskType = \\\"review\\\";\\n\\n/** Input payload (`job.variables`) per declared worker, keyed by `taskType`. */\\nexport interface WorkerInputs {\\n  \\\"review\\\": DomainTypes[\\\"Order\\\"];\\n}\\n\\n/** Output payload (worker result) per declared worker, keyed by `taskType`. */\\nexport interface WorkerOutputs {\\n  \\\"review\\\": DomainTypes[\\\"Order\\\"];\\n}\\n\\n/** Custom headers (`job.customHeaders`) per declared worker, keyed by `taskType`.\\n * Header values are strings on the wire, so each declared key maps to `string`;\\n * the extra index signature keeps undeclared headers accessible (non-breaking). */\\nexport interface WorkerHeaders {\\n  \\\"review\\\": { \\\"priority\\\": string; \\\"x-flag\\\": string; [key: string]: string };\\n}\\n\",\"messageBindings\":\"// AUTO-GENERATED by nanobpmn from the process model (ADR 0040 slice 2).\\n// The bridge from a `bpmn:message`'s data envelope to the message type system:\\n// each named message maps to the TS type of its payload, so the typed\\n// `publishMessage` types a call by its message name. Do not edit — regenerated\\n// from the model. Erased to plain JS at compile.\\n\\nimport type { DomainTypes } from \\\"./domain-rows.d.ts\\\";\\n\\n/** Untyped fallback payload for a message that declares no envelope type. */\\nexport type MessageVars = Record<string, unknown>;\\n\\n/** Every declared message `name` (ADR 0040 slice 2): the model-derived set the\\n * typed `publishMessage` accepts, so `name` autocompletes and rejects unknown messages. */\\nexport type MessageName = \\\"approved\\\";\\n\\n/** Payload (`variables`) per declared message, keyed by `name`. */\\nexport interface MessagePayloads {\\n  \\\"approved\\\": DomainTypes[\\\"Order\\\"];\\n}\\n\"}");
 
 const sources: SourceSchema[] = [
   {

package/src/toolkit/derivers/domain.test.ts

@@ -17,7 +17,7 @@ import type { ToolkitManifest } from "./migrations.ts";
 
 // Goldens captured verbatim from the console's `emitDomainModel` (server domain_types.ts) via
 // Deno — this IS the per-emitter drift gate (ADR 0053): the toolkit must be byte-identical.
-const GOLDENS: Record<string, string> = JSON.parse("{\n  \"empty\": \"// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1).\\n// Do not edit — regenerated from the live tables. Erased at `deno compile`.\\n// eslint-disable\\n\\nexport interface DomainTables {}\\n\",\n  \"tablesOnly\": \"// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1).\\n// Do not edit — regenerated from the live tables. Erased at `deno compile`.\\n// eslint-disable\\n\\nexport interface Customers {\\n  /** INTEGER (primary key) */\\n  id: number;\\n  /** TEXT */\\n  email: string;\\n  /** TEXT */\\n  tier: string | null;\\n}\\n\\nexport interface OrderItems {\\n  /** INTEGER (primary key) */\\n  id: number;\\n  /** INTEGER */\\n  qty: number;\\n  /** REAL */\\n  \\\"unit price\\\": number | null;\\n}\\n\\n/** Every table keyed by its wire name — index it for a row type. */\\nexport interface DomainTables {\\n  \\\"customers\\\": Customers;\\n  \\\"order_items\\\": OrderItems;\\n}\\n\",\n  \"typesOnly\": \"// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1).\\n// Do not edit — regenerated from the live tables. Erased at `deno compile`.\\n// eslint-disable\\n\\nexport interface DomainTables {}\\n\\n/** Declared (transient) domain types from the manifest `types` registry (ADR 0029 §4.2), keyed by id. */\\nexport interface DomainTypes {\\n  \\\"taxReturn\\\": {\\n    year: number;\\n    notes?: string;\\n    lines: DomainTypes[\\\"lineItem\\\"][];\\n  };\\n  \\\"lineItem\\\": {\\n    \\\"line no\\\": number;\\n    amount: number;\\n  };\\n}\\n\",\n  \"both\": \"// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1).\\n// Do not edit — regenerated from the live tables. Erased at `deno compile`.\\n// eslint-disable\\n\\nexport interface Greetings {\\n  /** INTEGER (primary key) */\\n  id: number;\\n  /** TEXT */\\n  who: string;\\n  /** TEXT */\\n  message: string;\\n  /** TEXT */\\n  createdAt: string | null;\\n}\\n\\n/** Every table keyed by its wire name — index it for a row type. */\\nexport interface DomainTables {\\n  \\\"greetings\\\": Greetings;\\n}\\n\\n/** Declared (transient) domain types from the manifest `types` registry (ADR 0029 §4.2), keyed by id. */\\nexport interface DomainTypes {\\n  \\\"greeting\\\": {\\n    who: string;\\n    message: string;\\n    createdAt?: string;\\n  };\\n}\\n\",\n  \"multi\": \"// AUTO-GENERATED by nanobpmn from the datasource schemas (ADR 0029 §4.1/§6).\\n// Do not edit — regenerated from the live tables. Erased at `deno compile`.\\n// eslint-disable\\n\\nexport interface AppCustomers {\\n  /** INTEGER (primary key) */\\n  id: number;\\n  /** TEXT */\\n  email: string;\\n}\\n\\nexport interface AnalyticsEvents {\\n  /** INTEGER (primary key) */\\n  id: number;\\n  /** TEXT */\\n  kind: string;\\n}\\n\\n/** Every datasource keyed by alias, then table by wire name. */\\nexport interface DomainSources {\\n  \\\"app\\\": {\\n    \\\"customers\\\": AppCustomers;\\n  };\\n  \\\"analytics\\\": {\\n    \\\"events\\\": AnalyticsEvents;\\n  };\\n}\\n\\n/** The default datasource's tables — index by wire name. */\\nexport type DomainTables = DomainSources[\\\"analytics\\\"];\\n\"\n}");
+const GOLDENS: Record<string, string> = JSON.parse("{\"empty\":\"// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1).\\n// Do not edit — regenerated from the live tables. Erased at `deno compile`.\\n\\nexport type DomainTables = Record<never, never>;\\n\",\"tablesOnly\":\"// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1).\\n// Do not edit — regenerated from the live tables. Erased at `deno compile`.\\n\\nexport interface Customers {\\n  /** INTEGER (primary key) */\\n  id: number;\\n  /** TEXT */\\n  email: string;\\n  /** TEXT */\\n  tier: string | null;\\n}\\n\\nexport interface OrderItems {\\n  /** INTEGER (primary key) */\\n  id: number;\\n  /** INTEGER */\\n  qty: number;\\n  /** REAL */\\n  \\\"unit price\\\": number | null;\\n}\\n\\n/** Every table keyed by its wire name — index it for a row type. */\\nexport interface DomainTables {\\n  \\\"customers\\\": Customers;\\n  \\\"order_items\\\": OrderItems;\\n}\\n\",\"typesOnly\":\"// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1).\\n// Do not edit — regenerated from the live tables. Erased at `deno compile`.\\n\\nexport type DomainTables = Record<never, never>;\\n\\n/** Declared (transient) domain types from the manifest `types` registry (ADR 0029 §4.2), keyed by id. */\\nexport interface DomainTypes {\\n  \\\"taxReturn\\\": {\\n    year: number;\\n    notes?: string;\\n    lines: DomainTypes[\\\"lineItem\\\"][];\\n  };\\n  \\\"lineItem\\\": {\\n    \\\"line no\\\": number;\\n    amount: number;\\n  };\\n}\\n\",\"both\":\"// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1).\\n// Do not edit — regenerated from the live tables. Erased at `deno compile`.\\n\\nexport interface Greetings {\\n  /** INTEGER (primary key) */\\n  id: number;\\n  /** TEXT */\\n  who: string;\\n  /** TEXT */\\n  message: string;\\n  /** TEXT */\\n  createdAt: string | null;\\n}\\n\\n/** Every table keyed by its wire name — index it for a row type. */\\nexport interface DomainTables {\\n  \\\"greetings\\\": Greetings;\\n}\\n\\n/** Declared (transient) domain types from the manifest `types` registry (ADR 0029 §4.2), keyed by id. */\\nexport interface DomainTypes {\\n  \\\"greeting\\\": {\\n    who: string;\\n    message: string;\\n    createdAt?: string;\\n  };\\n}\\n\",\"multi\":\"// AUTO-GENERATED by nanobpmn from the datasource schemas (ADR 0029 §4.1/§6).\\n// Do not edit — regenerated from the live tables. Erased at `deno compile`.\\n\\nexport interface AppCustomers {\\n  /** INTEGER (primary key) */\\n  id: number;\\n  /** TEXT */\\n  email: string;\\n}\\n\\nexport interface AnalyticsEvents {\\n  /** INTEGER (primary key) */\\n  id: number;\\n  /** TEXT */\\n  kind: string;\\n}\\n\\n/** Every datasource keyed by alias, then table by wire name. */\\nexport interface DomainSources {\\n  \\\"app\\\": {\\n    \\\"customers\\\": AppCustomers;\\n  };\\n  \\\"analytics\\\": {\\n    \\\"events\\\": AnalyticsEvents;\\n  };\\n}\\n\\n/** The default datasource's tables — index by wire name. */\\nexport type DomainTables = DomainSources[\\\"analytics\\\"];\\n\"}");
 
 const col = (name: string, type: string, notNull: boolean, primaryKey: boolean) =>
   ({ name, type, notNull, primaryKey });

package/src/toolkit/derivers/domain.ts

@@ -104,10 +104,9 @@ function tableInterface(t: TableMeta): string {
 export function emitDomainDts(tables: TableMeta[]): string {
   const header =
     "// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1).\n" +
-    "// Do not edit — regenerated from the live tables. Erased at `deno compile`.\n" +
-    "// eslint-disable\n";
+    "// Do not edit — regenerated from the live tables. Erased at `deno compile`.\n";
   if (tables.length === 0) {
-    return `${header}\nexport interface DomainTables {}\n`;
+    return `${header}\nexport type DomainTables = Record<never, never>;\n`;
   }
   const interfaces = tables.map(tableInterface).join("\n\n");
   const map = tables
@@ -140,8 +139,7 @@ export function emitDomainDtsForSources(
   }
   const header =
     "// AUTO-GENERATED by nanobpmn from the datasource schemas (ADR 0029 §4.1/§6).\n" +
-    "// Do not edit — regenerated from the live tables. Erased at `deno compile`.\n" +
-    "// eslint-disable\n";
+    "// Do not edit — regenerated from the live tables. Erased at `deno compile`.\n";
 
   const interfaces = sources
     .flatMap((s) =>
@@ -153,7 +151,7 @@ export function emitDomainDtsForSources(
 
   const sourceMap = sources
     .map((s) => {
-      if (s.tables.length === 0) return `  ${JSON.stringify(s.source)}: {};`;
+      if (s.tables.length === 0) return `  ${JSON.stringify(s.source)}: Record<never, never>;`;
       const tableMap = s.tables
         .map((t) =>
           `    ${JSON.stringify(t.name)}: ${prefixedInterfaceName(s.source, t.name)};`
@@ -241,7 +239,7 @@ export function emitDomainTypeRegistry(types: DomainTypeRegistry): string {
           return `    ${key}${opt}: ${fieldTsType(field, ids)};`;
         })
         .join("\n");
-      const body = fields.length > 0 ? `{\n${fields}\n  }` : "{}";
+      const body = fields.length > 0 ? `{\n${fields}\n  }` : "Record<never, never>";
       return `  ${JSON.stringify(id)}: ${body};`;
     })
     .join("\n");
@@ -308,8 +306,7 @@ export function emitDomainBindings(
     "// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1/§6).\n" +
     "// The typed data-object layer: `openDomain()` → one `Table<T>` per table, so\n" +
     "// workers manipulate typed rows instead of hand-writing SQL. Do not edit —\n" +
-    "// regenerated from the live tables. Erased to plain JS at `deno compile`.\n" +
-    "// eslint-disable\n";
+    "// regenerated from the live tables. Erased to plain JS at `deno compile`.\n";
 
   const multi = sources.length > 1;
   const def = defaultSource && sources.some((s) => s.source === defaultSource)
@@ -365,7 +362,7 @@ export function emitDomainBindings(
     `    close: () => raw.close(),\n  };\n}`;
 
   return `${header}\n` +
-    `import { openDataSource, type DataSource, type Table } from "./data-sdk.ts";\n` +
+    `import { type DataSource, openDataSource, type Table } from "./data-sdk.ts";\n` +
     importTypes +
     `\n${domainIface}\n\n${openFn}\n\nexport type { Table };\n`;
 }
@@ -422,14 +419,15 @@ function emitKeyedDomainBindings(
     `export async function openDomain<K extends DomainSource = ${JSON.stringify(def)}>(\n` +
     `  source?: K,\n` +
     `): Promise<Domain<DomainSources[K]>> {\n` +
-    `  const key = (source ?? DEFAULT_SOURCE) as string;\n` +
+    `  const key = source ?? DEFAULT_SOURCE;\n` +
     `  const raw = await openDataSource(key);\n` +
     `  const db: Record<string, unknown> = { raw, close: () => raw.close() };\n` +
     `  for (const t of DOMAIN_TABLES[key] ?? []) db[t.name] = raw.table(t.name, t.pk);\n` +
+    `  // biome-ignore lint/plugin: the per-source table set is bound dynamically from DOMAIN_TABLES; the Domain<M> shape can't be expressed statically over the runtime loop.\n` +
     `  return db as Domain<DomainSources[K]>;\n}`;
 
   return `${header}\n` +
-    `import { openDataSource, type DataSource, type Table } from "./data-sdk.ts";\n` +
+    `import { type DataSource, openDataSource, type Table } from "./data-sdk.ts";\n` +
     `import type { DomainSources } from "./${DOMAIN_DTS}";\n\n` +
     `${runtimeMap}\n\n${types}\n\n${openFn}\n\nexport type { Table };\n`;
 }