@nanobpm/urban 0.77.1 → 0.77.3

package/dist/runtime/core/modules/scheduler.d.ts

@@ -4,6 +4,14 @@ export interface SchedulerDeps {
     clearTimer: (handle: unknown) => void;
     /** Current wall-clock time in ms since epoch. */
     now: () => number;
+    /** Optional shutdown signal. When it aborts, a pending {@link schedulerClock} `wait()` clears its
+     *  armed timer and rejects, so a handler parked on the (virtual) clock unwinds at teardown instead
+     *  of wedging whoever awaits it. Under the test kit this is the engine's shutdown signal: a worker
+     *  handler parked on `app.wait()` sits on a virtual timer that no `advanceTime` will fire during
+     *  `engine.close()`, so without this its promise never settles and `close()` hangs (the issue #446
+     *  follow-up — the virtual-timer sibling of the real-time use-after-free). Absent on the live
+     *  scheduler, where real timers always fire on wall-clock time, so `wait()` never rejects there. */
+    readonly signal?: AbortSignal;
 }
 /** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
 export declare const MAX_TIMER_DELAY_MS = 2147483647;

package/dist/runtime/core/modules/scheduler.js

@@ -3,6 +3,13 @@
 // worker handlers. Keeping one definition here — rather than a copy per module — means a
 // test's fake scheduler drives them all the same way, and the "clamp a far-future delay to
 // setTimeout's 32-bit range" rule has a single home.
+/** The rejection surfaced to a `wait()` cancelled by a shutdown {@link SchedulerDeps.signal}: the
+ *  signal's `reason` when it is an {@link Error}, else a generic teardown error. Reusing the reason
+ *  keeps a caller's fail-loud message (e.g. "WasmEngineClient closing") intact. */
+function schedulerAbortError(signal) {
+    const reason = signal.reason;
+    return reason instanceof Error ? reason : new Error("app.wait aborted: scheduler shutting down");
+}
 /** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
 export const MAX_TIMER_DELAY_MS = 2_147_483_647;
 function isTimerHandle(handle) {
@@ -32,9 +39,48 @@ export function defaultScheduler() {
 export function schedulerClock(sched) {
     return {
         now: () => sched.now(),
-        wait: (ms) => new Promise((resolve) => {
+        wait: (ms) => new Promise((resolve, reject) => {
+            const signal = sched.signal;
+            // Already shutting down: reject immediately rather than arm a timer that would outlive the
+            // teardown (and, under the virtual clock, never fire).
+            if (signal?.aborted) {
+                reject(schedulerAbortError(signal));
+                return;
+            }
             const delay = Number.isFinite(ms) && ms > 0 ? Math.min(ms, MAX_TIMER_DELAY_MS) : 0;
-            sched.setTimer(() => resolve(), delay);
+            let settled = false;
+            let onAbort;
+            const handle = sched.setTimer(() => {
+                settled = true;
+                if (onAbort && signal)
+                    signal.removeEventListener("abort", onAbort);
+                resolve();
+            }, delay);
+            // When a shutdown signal is present, a mid-wait abort disarms the timer and rejects, so a
+            // handler parked here unwinds at teardown instead of wedging its awaiter. Inert (no listener,
+            // no behaviour change) on the live scheduler, which supplies no signal.
+            //
+            // `settled` guards the synchronous-timer case: this seam permits `setTimer` to invoke its
+            // callback synchronously (the test `capturingScheduler` does exactly that), which resolves
+            // the wait *before* we get here. Installing an abort listener on that already-settled promise
+            // would leak its closure until the signal fires (and have shutdown clear an already-fired
+            // handle), so skip it entirely when the callback already ran.
+            if (signal && !settled) {
+                onAbort = () => {
+                    sched.clearTimer(handle);
+                    reject(schedulerAbortError(signal));
+                };
+                signal.addEventListener("abort", onAbort, { once: true });
+                // Re-entrant seam: `setTimer` above is injectable and may abort `signal` *synchronously*
+                // without firing the timer callback (so `settled` is still false). An abort event is not
+                // replayed to a listener added after the fact, so the listener just registered would never
+                // run and the wait would hang until the runner timeout. Re-check and drive the abort path
+                // by hand — removing the (now-inert) listener first so it cannot also fire and double-reject.
+                if (signal.aborted && !settled) {
+                    signal.removeEventListener("abort", onAbort);
+                    onAbort();
+                }
+            }
         }),
     };
 }

package/dist/toolkit/derivers/api.js

@@ -17,6 +17,48 @@ export const API_BINDINGS_TS = "operations.ts";
  *  `tsc` (ADR 0059). The runtime dispatches through this map instead of per-op path imports. */
 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, b) {
+    const tokens = (s) => s.match(/\d+|\D/g) ?? [];
+    const isDigitRun = (t) => 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) {
     const cleaned = operationId.replace(/[^A-Za-z0-9]+/g, " ").trim();
@@ -139,7 +181,7 @@ function objectToTs(schema, depth) {
 function paramsTs(op, where, ejected) {
     const ps = op.parameters.filter((p) => p.in === where);
     if (ps.length === 0)
-        return "{}";
+        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 `?`
@@ -188,8 +230,7 @@ export function emitApiBindings(doc, surfaceEject = false) {
         "// 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))
         .map(([name, schema]) => `export type ${typeStem(name)} = ${schemaToTs(schema)};`)
@@ -242,13 +283,19 @@ export function emitApiBindings(doc, surfaceEject = false) {
         return `  ${JSON.stringify(op.operationId)}: { request: ${stem}Request; response: ${stem}Response };`;
     })
         .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` : "") +
         (opDecls ? `${opDecls}\n\n` : "") +
         `/** 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);
 }
 /** Emit `operations.ts`: the typed `defineOperation` wrapper, keyed by operationId (mirrors the
  *  generated typed `defineWorker`). Written verbatim (it never changes with the spec) — it only
@@ -257,10 +304,9 @@ export function emitApiBindingsRuntime() {
     return ("// 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` +
@@ -303,17 +349,22 @@ export function emitApiController(doc, operationsDir = DEFAULT_OPERATIONS_DIR) {
         "// 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/dist/toolkit/derivers/domain.js

@@ -83,10 +83,9 @@ function tableInterface(t) {
  */
 export function emitDomainDts(tables) {
     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
@@ -113,15 +112,14 @@ export function emitDomainDtsForSources(sources, defaultSource) {
         return emitDomainDts(sources[0]?.tables ?? []);
     }
     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) => s.tables.map((t) => tableInterfaceNamed(prefixedInterfaceName(s.source, t.name), t)))
         .join("\n\n");
     const sourceMap = sources
         .map((s) => {
         if (s.tables.length === 0)
-            return `  ${JSON.stringify(s.source)}: {};`;
+            return `  ${JSON.stringify(s.source)}: Record<never, never>;`;
         const tableMap = s.tables
             .map((t) => `    ${JSON.stringify(t.name)}: ${prefixedInterfaceName(s.source, t.name)};`)
             .join("\n");
@@ -181,7 +179,7 @@ export function emitDomainTypeRegistry(types) {
             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");
@@ -233,8 +231,7 @@ export function emitDomainBindings(sources, defaultSource) {
     const header = "// 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)
         ? defaultSource
@@ -279,7 +276,7 @@ export function emitDomainBindings(sources, defaultSource) {
         (binds ? `${binds}\n` : "") +
         `    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`;
 }
@@ -323,13 +320,14 @@ function emitKeyedDomainBindings(header, sources, def) {
         `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`;
 }

package/dist/toolkit/derivers/messages.js

@@ -79,15 +79,14 @@ export function emitMessageBindings(messages, declaredTypeIds) {
         "// 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";
+        "// from the model. Erased to plain JS at compile.\n";
     const needsRegistry = payloads.length > 0;
     const importTypes = needsRegistry
         ? `import type { DomainTypes } from "./${DOMAIN_DTS}";\n`
         : "";
     const payloadsIface = payloads.length > 0
         ? `export interface MessagePayloads {\n${payloads.join("\n")}\n}\n`
-        : `export interface MessagePayloads {}\n`;
+        : `export type MessagePayloads = Record<never, never>;\n`;
     return `${header}\n` +
         importTypes +
         `\n/** Untyped fallback payload for a message that declares no envelope type. */\n` +
@@ -149,11 +148,10 @@ export function emitMessageBindingsRuntime() {
     return "// 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\n" +
-        `import { publishMessage as publishMessageRaw } from "./worker-sdk.ts";\n` +
+        "// envelope). Erased to a pass-through at runtime. Do not edit.\n\n" +
+        `import type { MessageName, MessagePayloads, MessageVars } from "./${MESSAGE_BINDINGS_DTS}";\n` +
         `import type { PublishMessageOptions, PublishMessageResult } from "./worker-sdk.ts";\n` +
-        `import type { MessageName, MessagePayloads, MessageVars } from "./${MESSAGE_BINDINGS_DTS}";\n\n` +
+        `import { publishMessage as publishMessageRaw } from "./worker-sdk.ts";\n\n` +
         `export type { PublishMessageOptions, PublishMessageResult } from "./worker-sdk.ts";\n\n` +
         `type PayloadFor<K extends MessageName> = K extends keyof MessagePayloads ? MessagePayloads[K] : MessageVars;\n\n` +
         `/**\n` +
@@ -166,6 +164,7 @@ export function emitMessageBindingsRuntime() {
         `  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`;
 }

package/dist/toolkit/derivers/meta.js

@@ -67,23 +67,25 @@ export function emitMeta(metas) {
     const header = "// AUTO-GENERATED by nanobpmn from the process model (ADR 0040 §5): the typed\n" +
         "// model-metadata accessor. Each `nano:meta` key/value the models declare becomes\n" +
         "// a checked `AppMeta` property, so `meta(key)` is typed and app-wide queryable\n" +
-        "// without a second store. Do not edit — regenerated from the model.\n" +
-        "// eslint-disable\n\n";
+        "// without a second store. Do not edit — regenerated from the model.\n\n";
     const iface = keys.length > 0
         ? `export interface AppMeta {\n${keys.map((k) => `  ${propKey(k)}: string;`).join("\n")}\n}\n`
-        : `export interface AppMeta {}\n`;
+        : `export type AppMeta = Record<never, never>;\n`;
+    // Dot-access satisfies Biome's `useLiteralKeys`, but `__proto__` must stay a computed key: dot
+    // access would trip `noProto` and (off a null-prototype dict) change semantics.
+    const assignTarget = (k) => isIdent(k) && k !== "__proto__" ? `m.${k}` : `m[${JSON.stringify(k)}]`;
     const constDecl = keys.length > 0
         ? `export const appMeta: AppMeta = (() => {\n` +
-            `  const m: Record<string, string> = Object.create(null);\n` +
-            keys.map((k) => `  m[${JSON.stringify(k)}] = ${JSON.stringify(folded[k])};`).join("\n") +
-            `\n  return m as AppMeta;\n})();\n`
-        : `export const appMeta: AppMeta = Object.create(null) as AppMeta;\n`;
+            `  const m: AppMeta = Object.create(null);\n` +
+            keys.map((k) => `  ${assignTarget(k)} = ${JSON.stringify(folded[k])};`).join("\n") +
+            `\n  return m;\n})();\n`
+        : `export const appMeta: AppMeta = Object.create(null);\n`;
     const accessor = `\n/** Read a model-level metadata value. A declared key is typed; a dynamic key\n` +
         ` * returns \`string | undefined\`. */\n` +
         `export function meta<K extends keyof AppMeta>(key: K): AppMeta[K];\n` +
         `export function meta(key: string): string | undefined;\n` +
         `export function meta(key: string): string | undefined {\n` +
-        `  return (appMeta as Record<string, string>)[key];\n` +
+        `  return Reflect.get(appMeta, key);\n` +
         `}\n`;
     return `${header}/** Every model-level metadata key the App's models declare (ADR 0040 §5). */\n` +
         iface + "\n" + constDecl + accessor;

package/dist/toolkit/derivers/worker-io.js

@@ -143,21 +143,20 @@ export function emitWorkerBindings(workers, declaredTypeIds) {
         "// 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";
+        "// not edit — regenerated from the manifest. Erased to plain JS at compile.\n";
     const needsRegistry = inputs.length > 0 || outputs.length > 0;
     const importTypes = needsRegistry
         ? `import type { DomainTypes } from "./${DOMAIN_DTS}";\n`
         : "";
     const inputsIface = inputs.length > 0
         ? `export interface WorkerInputs {\n${inputs.join("\n")}\n}\n`
-        : `export interface WorkerInputs {}\n`;
+        : `export type WorkerInputs = Record<never, never>;\n`;
     const outputsIface = outputs.length > 0
         ? `export interface WorkerOutputs {\n${outputs.join("\n")}\n}\n`
-        : `export interface WorkerOutputs {}\n`;
+        : `export type WorkerOutputs = Record<never, never>;\n`;
     const headersIface = headers.length > 0
         ? `export interface WorkerHeaders {\n${headers.join("\n")}\n}\n`
-        : `export interface WorkerHeaders {}\n`;
+        : `export type WorkerHeaders = Record<never, never>;\n`;
     return `${header}\n` +
         importTypes +
         `\n/** Untyped fallback for a job whose worker declares no input/output type. */\n` +
@@ -315,11 +314,10 @@ export function emitWorkerBindingsRuntime() {
         "// 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\n" +
-        `import { defineWorker as defineWorkerRaw } from "./worker-sdk.ts";\n` +
+        "// runtime. Do not edit.\n\n" +
+        `import type { WorkerHdrs, WorkerHeaders, WorkerInputs, WorkerOutputs, WorkerTaskType, WorkerVars } from "./${WORKER_BINDINGS_DTS}";\n` +
         `import type { WorkerOptions } from "./worker-sdk.ts";\n` +
-        `import type { WorkerInputs, WorkerOutputs, WorkerHeaders, WorkerTaskType, WorkerVars, WorkerHdrs } from "./${WORKER_BINDINGS_DTS}";\n\n` +
+        `import { defineWorker as defineWorkerRaw } from "./worker-sdk.ts";\n\n` +
         `export * from "./worker-sdk.ts";\n\n` +
         `type InFor<K extends WorkerTaskType> = K extends keyof WorkerInputs ? WorkerInputs[K] : WorkerVars;\n` +
         `type OutFor<K extends WorkerTaskType> = K extends keyof WorkerOutputs ? WorkerOutputs[K] : WorkerVars;\n` +
@@ -334,6 +332,7 @@ export function emitWorkerBindingsRuntime() {
         `export 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`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.77.1",
+	"version": "0.77.3",
 	"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",
@@ -103,7 +103,7 @@
 		"@nanobpm/nano-sdk": "^1.2.5",
 		"@nanobpm/workflow": "^0.14.0",
 		"bpmn-auto-layout": "^2.0.0-alpha.2",
-		"create-urban-app": "^0.15.0",
+		"create-urban-app": "^0.15.1",
 		"yaml": "^2.9.0"
 	},
 	"devDependencies": {

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

@@ -42,3 +42,108 @@ test("schedulerClock.wait clamps non-positive / non-finite delays to the current
   await schedulerClock(sched).wait(Number.POSITIVE_INFINITY);
   assert.deepEqual(sched.delays, [0, 0, 0]);
 });
+
+// Regression (issue #446 follow-up): a handler parked on `app.wait()` sits on a (virtual) timer that
+// no clock advance fires during teardown, so whoever awaits it — the test kit's `engine.close()` —
+// hangs forever. `schedulerClock().wait()` now honours an optional shutdown `signal`: a mid-wait
+// abort disarms the armed timer and rejects, so the parked handler unwinds at teardown. The live
+// scheduler supplies no signal, so this is wholly inert in production.
+test("schedulerClock.wait disarms its timer and rejects when the shutdown signal aborts mid-wait", async () => {
+  const controller = new AbortController();
+  const cleared: unknown[] = [];
+  let armed: (() => void) | undefined;
+  const sched: SchedulerDeps = {
+    now: () => 0,
+    signal: controller.signal,
+    setTimer: (fn) => {
+      armed = fn;
+      return 42;
+    },
+    clearTimer: (h) => cleared.push(h),
+  };
+  const waiting = schedulerClock(sched).wait(10_000);
+  assert.equal(typeof armed, "function", "wait must arm a timer while not aborted");
+  controller.abort(new Error("engine shutting down"));
+  await assert.rejects(waiting, /engine shutting down/, "an aborted wait must reject with the signal's reason");
+  assert.deepEqual(cleared, [42], "the armed timer must be cleared on abort so it cannot fire later");
+});
+
+test("schedulerClock.wait rejects immediately (arming no timer) when the signal is already aborted", async () => {
+  const controller = new AbortController();
+  controller.abort(new Error("already shutting down"));
+  let armedCount = 0;
+  const sched: SchedulerDeps = {
+    now: () => 0,
+    signal: controller.signal,
+    setTimer: () => {
+      armedCount += 1;
+      return 0;
+    },
+    clearTimer: () => {},
+  };
+  await assert.rejects(schedulerClock(sched).wait(1000), /already shutting down/);
+  assert.equal(armedCount, 0, "an already-aborted signal must reject without arming a timer");
+});
+
+// Regression (PR #447 review, scheduler.ts): this seam permits `setTimer` to fire its callback
+// SYNCHRONOUSLY (the `capturingScheduler` above does). When it does — and a shutdown `signal` is
+// present — the wait resolves before we would install the abort listener, so we must NOT install
+// one: attaching a listener to an already-settled promise leaks its closure until the signal fires
+// and later has shutdown clear an already-fired timer handle. A synchronously-resolved wait must
+// leave zero listeners on the signal and must not clear its (already-fired) handle on a later abort.
+test("schedulerClock.wait installs no abort listener when a signalled wait resolves synchronously", async () => {
+  const controller = new AbortController();
+  const cleared: unknown[] = [];
+  const sched: SchedulerDeps = {
+    now: () => 0,
+    signal: controller.signal,
+    setTimer: (fn) => {
+      fn(); // fire synchronously — the wait resolves before any listener could be installed
+      return 7;
+    },
+    clearTimer: (h) => cleared.push(h),
+  };
+  await schedulerClock(sched).wait(0);
+  // A leaked listener would fire here and clear the stale handle; the fix installs none.
+  controller.abort(new Error("shutting down"));
+  assert.deepEqual(cleared, [], "a synchronously-resolved wait must not install an abort listener");
+});
+// The abort reason is attacker/caller-controlled: guard the case where it is a bare value rather
+// than an Error so `wait()` still rejects with a generic teardown error instead of leaking it.
+test("schedulerClock.wait rejects with a generic teardown error when the abort reason is not an Error", async () => {
+  const controller = new AbortController();
+  const sched: SchedulerDeps = {
+    now: () => 0,
+    signal: controller.signal,
+    setTimer: () => 0,
+    clearTimer: () => {},
+  };
+  const waiting = schedulerClock(sched).wait(1000);
+  controller.abort("not-an-error");
+  await assert.rejects(waiting, /scheduler shutting down/);
+});
+
+// Regression (PR #447 review, scheduler.ts:108): `setTimer` is an injectable seam that may abort the
+// shutdown `signal` SYNCHRONOUSLY while arming, WITHOUT firing its callback (a re-entrant scheduler).
+// An abort event is not replayed to a listener added after the fact, so a wait that merely installed
+// its listener would hang forever — never rejecting, never clearing the armed timer. `wait()` must
+// re-check `signal.aborted` after installing the listener and drive the abort path by hand.
+test("schedulerClock.wait rejects (and clears its timer) when setTimer aborts the signal synchronously", async () => {
+  const controller = new AbortController();
+  const cleared: unknown[] = [];
+  const sched: SchedulerDeps = {
+    now: () => 0,
+    signal: controller.signal,
+    setTimer: () => {
+      controller.abort(new Error("aborted during setTimer"));
+      return 99;
+    },
+    clearTimer: (h) => cleared.push(h),
+  };
+  await assert.rejects(
+    schedulerClock(sched).wait(1000),
+    /aborted during setTimer/,
+    "a synchronous mid-arm abort must reject the wait, not leave it hanging",
+  );
+  assert.deepEqual(cleared, [99], "the armed timer must be cleared when the synchronous abort is handled");
+});

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

@@ -10,6 +10,22 @@ export interface SchedulerDeps {
   clearTimer: (handle: unknown) => void;
   /** Current wall-clock time in ms since epoch. */
   now: () => number;
+  /** Optional shutdown signal. When it aborts, a pending {@link schedulerClock} `wait()` clears its
+   *  armed timer and rejects, so a handler parked on the (virtual) clock unwinds at teardown instead
+   *  of wedging whoever awaits it. Under the test kit this is the engine's shutdown signal: a worker
+   *  handler parked on `app.wait()` sits on a virtual timer that no `advanceTime` will fire during
+   *  `engine.close()`, so without this its promise never settles and `close()` hangs (the issue #446
+   *  follow-up — the virtual-timer sibling of the real-time use-after-free). Absent on the live
+   *  scheduler, where real timers always fire on wall-clock time, so `wait()` never rejects there. */
+  readonly signal?: AbortSignal;
+}
+
+/** The rejection surfaced to a `wait()` cancelled by a shutdown {@link SchedulerDeps.signal}: the
+ *  signal's `reason` when it is an {@link Error}, else a generic teardown error. Reusing the reason
+ *  keeps a caller's fail-loud message (e.g. "WasmEngineClient closing") intact. */
+function schedulerAbortError(signal: AbortSignal): Error {
+  const reason: unknown = signal.reason;
+  return reason instanceof Error ? reason : new Error("app.wait aborted: scheduler shutting down");
 }
 
 /** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
@@ -58,9 +74,47 @@ export function schedulerClock(sched: SchedulerDeps): AppClock {
   return {
     now: () => sched.now(),
     wait: (ms) =>
-      new Promise<void>((resolve) => {
+      new Promise<void>((resolve, reject) => {
+        const signal = sched.signal;
+        // Already shutting down: reject immediately rather than arm a timer that would outlive the
+        // teardown (and, under the virtual clock, never fire).
+        if (signal?.aborted) {
+          reject(schedulerAbortError(signal));
+          return;
+        }
         const delay = Number.isFinite(ms) && ms > 0 ? Math.min(ms, MAX_TIMER_DELAY_MS) : 0;
-        sched.setTimer(() => resolve(), delay);
+        let settled = false;
+        let onAbort: (() => void) | undefined;
+        const handle = sched.setTimer(() => {
+          settled = true;
+          if (onAbort && signal) signal.removeEventListener("abort", onAbort);
+          resolve();
+        }, delay);
+        // When a shutdown signal is present, a mid-wait abort disarms the timer and rejects, so a
+        // handler parked here unwinds at teardown instead of wedging its awaiter. Inert (no listener,
+        // no behaviour change) on the live scheduler, which supplies no signal.
+        //
+        // `settled` guards the synchronous-timer case: this seam permits `setTimer` to invoke its
+        // callback synchronously (the test `capturingScheduler` does exactly that), which resolves
+        // the wait *before* we get here. Installing an abort listener on that already-settled promise
+        // would leak its closure until the signal fires (and have shutdown clear an already-fired
+        // handle), so skip it entirely when the callback already ran.
+        if (signal && !settled) {
+          onAbort = () => {
+            sched.clearTimer(handle);
+            reject(schedulerAbortError(signal));
+          };
+          signal.addEventListener("abort", onAbort, { once: true });
+          // Re-entrant seam: `setTimer` above is injectable and may abort `signal` *synchronously*
+          // without firing the timer callback (so `settled` is still false). An abort event is not
+          // replayed to a listener added after the fact, so the listener just registered would never
+          // run and the wait would hang until the runner timeout. Re-check and drive the abort path
+          // by hand — removing the (now-inert) listener first so it cannot also fire and double-reject.
+          if (signal.aborted && !settled) {
+            signal.removeEventListener("abort", onAbort);
+            onAbort();
+          }
+        }
       }),
   };
 }