@nanobpm/urban 0.71.1 → 0.72.1

package/dist/runtime/core/context.d.ts

@@ -37,6 +37,22 @@ export interface AppApi {
      */
     sdk?: EngineSdkClient;
     env(name: string): string | undefined;
+    /**
+     * App clock seam — current time in ms since epoch, sourced from the runtime's injectable
+     * scheduler (`CreateUrbanAppOptions.scheduler`). The real wall clock in production; the virtual
+     * clock under the test kit. A handler doing time-bounded work (poll loops, backoff,
+     * budgets) should read `app.now()` instead of `Date.now()` so a whole-app `advanceTime()`
+     * bounds it deterministically rather than the loop burning real wall-time. See
+     * {@link AppApi.wait}.
+     */
+    now(): number;
+    /**
+     * Sleep `ms` on the app clock, resolving once that much time has elapsed on the runtime
+     * scheduler. Real timers in production (no behavior change on the live transport); under
+     * the test kit it advances with `advanceTime()`. Prefer over a hand-rolled `setTimeout`
+     * sleep in time-bounded work so the delay shares the engine's (virtual) clock.
+     */
+    wait(ms: number): Promise<void>;
     /**
      * Structured logger (see {@link Logger}). Callable for back-compat
      * (`log("info", msg, fields)`), but prefer the level methods and bound context:

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

@@ -85,11 +85,19 @@ export async function resolveInstalledConnectors(ctx) {
  *  error boundary by the engine adapter); `job.fail(msg)` a plain throw (retry). */
 export function adaptConnectorHandler(worker) {
     return async (job) => {
+        // A connector job always belongs to a process instance; a missing key is a
+        // protocol fault. Fail loud (the engine retries / raises an incident) rather
+        // than handing the connector a fabricated "" that would silently corrupt any
+        // instance-scoped call it makes.
+        const processInstanceKey = job.processInstanceKey;
+        if (processInstanceKey === undefined || processInstanceKey === "") {
+            throw new Error(`connector job '${job.jobType}' (${job.jobKey}) has no processInstanceKey`);
+        }
         let outcome;
         const facade = {
             jobKey: job.jobKey,
             type: job.jobType,
-            processInstanceKey: job.processInstanceKey ?? "",
+            processInstanceKey,
             elementId: job.elementId,
             variables: job.variables,
             async complete(vars) {

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

@@ -9,3 +9,27 @@ export interface SchedulerDeps {
 export declare const MAX_TIMER_DELAY_MS = 2147483647;
 /** Default (live) scheduler seam, backed by the global timer functions. */
 export declare function defaultScheduler(): SchedulerDeps;
+/**
+ * The app-facing clock/`wait` seam handed to handlers (see `AppApi.now`/`AppApi.wait`).
+ * A narrow read-only projection of a {@link SchedulerDeps}: `now()` reads its clock and
+ * `wait(ms)` sleeps on its timer. Real wall clock + real timers in production; the
+ * virtual clock under the test kit — so time-bounded worker work advances with
+ * `advanceTime()` instead of burning real wall-time.
+ */
+export interface AppClock {
+    /** Current time in ms since epoch on the scheduler's clock. */
+    now(): number;
+    /** Resolve after `ms` have elapsed on the scheduler's clock (armed via its timer seam). */
+    wait(ms: number): Promise<void>;
+}
+/**
+ * Derive the app clock/`wait` seam from a scheduler — the single canonical mapping from the
+ * runtime's injectable timer seam to the surface handlers use, so worker/trigger/surface
+ * handlers doing time-bounded work share the same clock as the background loops (no drift
+ * between a handler's budget and the engine's timers). A non-positive/non-finite `wait`
+ * delay clamps to fire at the current instant, and a far-future delay clamps to
+ * {@link MAX_TIMER_DELAY_MS} — matching the same clamp the background loops apply to their
+ * `setTimer` delays (see `mountTriggers`/`mountInstanceTracking`) — so `app.wait()` can
+ * never reintroduce a Node `TimeoutOverflowWarning`.
+ */
+export declare function schedulerClock(sched: SchedulerDeps): AppClock;

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

@@ -1,8 +1,8 @@
 // The injectable timer + clock seam shared by every background loop in urban (cron
-// triggers, the instance-tracking reconciler). 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.
+// triggers, the instance-tracking reconciler) and the app clock/`wait` seam handed to
+// 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.
 /** 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) {
@@ -19,3 +19,22 @@ export function defaultScheduler() {
         now: () => Date.now(),
     };
 }
+/**
+ * Derive the app clock/`wait` seam from a scheduler — the single canonical mapping from the
+ * runtime's injectable timer seam to the surface handlers use, so worker/trigger/surface
+ * handlers doing time-bounded work share the same clock as the background loops (no drift
+ * between a handler's budget and the engine's timers). A non-positive/non-finite `wait`
+ * delay clamps to fire at the current instant, and a far-future delay clamps to
+ * {@link MAX_TIMER_DELAY_MS} — matching the same clamp the background loops apply to their
+ * `setTimer` delays (see `mountTriggers`/`mountInstanceTracking`) — so `app.wait()` can
+ * never reintroduce a Node `TimeoutOverflowWarning`.
+ */
+export function schedulerClock(sched) {
+    return {
+        now: () => sched.now(),
+        wait: (ms) => new Promise((resolve) => {
+            const delay = Number.isFinite(ms) && ms > 0 ? Math.min(ms, MAX_TIMER_DELAY_MS) : 0;
+            sched.setTimer(() => resolve(), delay);
+        }),
+    };
+}

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

@@ -1,6 +1,7 @@
 import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
 import type { EngineJob } from "../host.ts";
 import { type DecisionEvaluator } from "./llm.ts";
+import { type SchedulerDeps } from "./scheduler.ts";
 /** Adapt an engine SDK client into the LLM module's `DecisionEvaluator`, parsing the
  *  decision's JSON-string `output` into the value fed back to the LLM job. Validates the
  *  SDK shape and adds decision context to a parse failure rather than surfacing a raw
@@ -34,4 +35,4 @@ export interface WorkersHandle extends Mounted {
     readonly jobTypes: string[];
 }
 /** Load handler modules and register a push worker per declared worker. */
-export declare function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<WorkersHandle>;
+export declare function mountWorkers(ctx: RuntimeContext, app: AppApi, sched?: SchedulerDeps): Promise<WorkersHandle>;

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

@@ -7,6 +7,7 @@ import { runLlmJob } from "./llm.js";
 import { runInJobContext } from "../execContext.js";
 import { readLineage } from "../lineage.js";
 import { LineageStore } from "./lineage-store.js";
+import { defaultScheduler, schedulerClock } from "./scheduler.js";
 /** Adapt an engine SDK client into the LLM module's `DecisionEvaluator`, parsing the
  *  decision's JSON-string `output` into the value fed back to the LLM job. Validates the
  *  SDK shape and adds decision context to a parse failure rather than surfacing a raw
@@ -125,10 +126,18 @@ export function resolveHandler(mod, jobType) {
     return undefined;
 }
 /** Load handler modules and register a push worker per declared worker. */
-export async function mountWorkers(ctx, app) {
+export async function mountWorkers(ctx, app, sched = defaultScheduler()) {
     const decls = ctx.manifest.workers ?? [];
     const subs = [];
     const jobTypes = [];
+    // Bind the app clock/`wait` seam to the injected scheduler, so a handler's time-bounded
+    // work (poll loops, backoff, budgets) sources `now`/`wait` from the same clock that drives
+    // the engine's timers and the other background loops. Under the test kit that is the
+    // virtual clock, so `advanceTime()` bounds the loop instead of it burning real wall-time;
+    // in production it is the live scheduler (real timers) — no behavior change. Mirrors how
+    // `mountTriggers`/`mountInstanceTracking` receive the same seam.
+    const clock = schedulerClock(sched);
+    const clockedApp = { ...app, now: clock.now, wait: clock.wait };
     // The framework lineage projection (issue #254): each activated job records the `_urban.lineage`
     // edge its instance carries, so intent→progress lineage materialises for free. Absent when the
     // app configures no default data source.
@@ -195,7 +204,7 @@ export async function mountWorkers(ctx, app) {
         const wrapped = (job) => {
             if (lineageStore)
                 recordJobLineage(lineageStore, job, ctx.host.log);
-            return runInJobContext(jobExecContext(job, jobType), () => handler(job, withJobLog(app, job)));
+            return runInJobContext(jobExecContext(job, jobType), () => handler(job, withJobLog(clockedApp, job)));
         };
         const sub = await ctx.engine.registerWorker(jobType, wrapped, {
             workerName: `${ctx.manifest.id}:${jobType}`,

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

@@ -2,7 +2,7 @@ import type { EngineClient, HostContext } from "./host.ts";
 import { type AppManifest } from "./manifest.ts";
 import { DataLayer } from "./modules/datasource.ts";
 import { type Logger } from "./logger.ts";
-import type { SchedulerDeps } from "./modules/scheduler.ts";
+import { type SchedulerDeps } from "./modules/scheduler.ts";
 import { type SecurityPolicy } from "./modules/security.ts";
 import { type UrbanEvents, type UrbanExtension } from "./extensions.ts";
 /** Resolve the HTTP port: explicit option, else $PORT, else 8090. Throws a clear
@@ -34,11 +34,13 @@ export interface CreateUrbanAppOptions {
     mount?: MountFlags;
     /**
      * Injectable timer + clock seam driving every background loop (the cron trigger loops
-     * and the instance-tracking reconciler). Defaults to the live scheduler (real timers,
-     * wall clock). The e2e test kit injects a manual scheduler so those loops advance
-     * deterministically over a virtual clock — the single seam that makes a whole-app
-     * `settle()` possible. Threaded verbatim into `mountTriggers` and `mountInstanceTracking`
-     * so one injected scheduler drives them both (no per-module wiring, no drift).
+     * and the instance-tracking reconciler) and the app clock/`wait` seam handed to worker
+     * handlers. Defaults to the live scheduler (real timers, wall clock). The e2e test kit
+     * injects a manual scheduler so those loops — and any time-bounded worker sourcing
+     * `app.now()`/`app.wait()` — advance deterministically over a virtual clock: the single
+     * seam that makes a whole-app `settle()` possible. Threaded verbatim into `mountWorkers`,
+     * `mountTriggers` and `mountInstanceTracking` so one injected scheduler drives them all
+     * (no per-module wiring, no drift).
      */
     scheduler?: SchedulerDeps;
     /**

package/dist/runtime/core/runtime.js

@@ -14,6 +14,7 @@ import { mountConnectors } from "./modules/connectors.js";
 import { mountSurfaces } from "./modules/surfaces.js";
 import { mountTriggers } from "./modules/triggers.js";
 import { mountInstanceTracking } from "./modules/instance-tracking.js";
+import { defaultScheduler, schedulerClock } from "./modules/scheduler.js";
 import { mountSecurity } from "./modules/security.js";
 import { EventBus } from "./events.js";
 import { createUrbanEvents, mountExtensions } from "./extensions.js";
@@ -157,6 +158,12 @@ export async function createUrbanApp(opts) {
                 if (flags.deploy)
                     describe.deploy = await deployModels(ctx);
                 data = flags.data ? await provisionData(ctx) : new DataLayer(new Map(), undefined, {});
+                // Resolve the injectable scheduler once (default: live real-timer seam) so the app
+                // clock/`wait` seam handed to handlers and every background loop share one clock —
+                // the single source the test kit swaps for a virtual clock to make `settle()` /
+                // `advanceTime()` bound the whole app (workers included).
+                const scheduler = opts.scheduler ?? defaultScheduler();
+                const clock = schedulerClock(scheduler);
                 const api = {
                     manifest,
                     data,
@@ -164,9 +171,11 @@ export async function createUrbanApp(opts) {
                     sdk: engineSdk(engine),
                     env: (n) => host.env(n),
                     log: appLog,
+                    now: clock.now,
+                    wait: clock.wait,
                 };
                 if (flags.workers) {
-                    const w = await mountWorkers(ctx, api);
+                    const w = await mountWorkers(ctx, api, scheduler);
                     mounted.push(w);
                     describe.workers = w.describe?.();
                     // Connector-pack workers share the `workers` flag: same lifecycle, same
@@ -191,13 +200,13 @@ export async function createUrbanApp(opts) {
                     describe.surfaces = s.describe();
                 }
                 if (flags.triggers) {
-                    const t = mountTriggers(ctx, api, opts.scheduler);
+                    const t = mountTriggers(ctx, api, scheduler);
                     routes.push(...t.routes);
                     mounted.push(t);
                     describe.triggers = t.describe?.();
                 }
                 if (flags.instanceTracking && (manifest.instanceTracking?.length ?? 0) > 0) {
-                    const it = mountInstanceTracking(ctx, api, opts.scheduler);
+                    const it = mountInstanceTracking(ctx, api, scheduler);
                     mounted.push(it);
                     describe.instanceTracking = it.describe?.();
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.71.1",
+	"version": "0.72.1",
 	"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",

package/src/runtime/core/context.ts

@@ -42,6 +42,22 @@ export interface AppApi {
    */
   sdk?: EngineSdkClient;
   env(name: string): string | undefined;
+  /**
+   * App clock seam — current time in ms since epoch, sourced from the runtime's injectable
+   * scheduler (`CreateUrbanAppOptions.scheduler`). The real wall clock in production; the virtual
+   * clock under the test kit. A handler doing time-bounded work (poll loops, backoff,
+   * budgets) should read `app.now()` instead of `Date.now()` so a whole-app `advanceTime()`
+   * bounds it deterministically rather than the loop burning real wall-time. See
+   * {@link AppApi.wait}.
+   */
+  now(): number;
+  /**
+   * Sleep `ms` on the app clock, resolving once that much time has elapsed on the runtime
+   * scheduler. Real timers in production (no behavior change on the live transport); under
+   * the test kit it advances with `advanceTime()`. Prefer over a hand-rolled `setTimeout`
+   * sleep in time-bounded work so the delay shares the engine's (virtual) clock.
+   */
+  wait(ms: number): Promise<void>;
   /**
    * Structured logger (see {@link Logger}). Callable for back-compat
    * (`log("info", msg, fields)`), but prefer the level methods and bound context:

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

@@ -27,6 +27,8 @@ function fakeApi(): AppApi {
     data: unused(),
     engine: unused(),
     env: () => undefined,
+    now: () => 0,
+    wait: () => Promise.resolve(),
     log: createLogger(() => {}),
   };
 }

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

@@ -45,6 +45,8 @@ function appFixture(over: Partial<AppApi> = {}): AppApi {
     data,
     engine,
     env: () => undefined,
+    now: () => 0,
+    wait: () => Promise.resolve(),
     log: createLogger(() => {}),
     ...over,
   };

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

@@ -39,7 +39,7 @@ const engine: EngineClient = {
 const data = new DataLayer(new Map(), undefined, {});
 
 function appFixture(): AppApi {
-  return { manifest: { schemaVersion: 1, id: "t", name: "T" }, data, engine, env: () => undefined, log: createLogger(() => {}) };
+  return { manifest: { schemaVersion: 1, id: "t", name: "T" }, data, engine, env: () => undefined, now: () => 0, wait: () => Promise.resolve(), log: createLogger(() => {}) };
 }
 
 const spec = JSON.stringify({
@@ -148,6 +148,8 @@ test("a delegate's app.log is bound to the request's correlation context", async
     data,
     engine,
     env: () => undefined,
+    now: () => 0,
+    wait: () => Promise.resolve(),
     log: createLogger((level, msg, fields) => {
       captured.push({ level, msg, fields });
     }),

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

@@ -111,6 +111,8 @@ async function withHarness(engine: EngineClient, seedStatus = "converging"): Pro
     data,
     engine,
     env: () => undefined,
+    now: () => 0,
+    wait: () => Promise.resolve(),
     log: createLogger((level, msg) => {
       logs.push({ level, msg });
     }),

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

@@ -86,6 +86,8 @@ function makeApp(env: Record<string, string> = {}): AppApi {
     data: new DataLayer(new Map(), undefined, {}),
     engine: new MiniEngine(),
     env: (n: string) => env[n],
+    now: () => 0,
+    wait: () => Promise.resolve(),
     log: createLogger(() => {}),
   };
 }
@@ -143,6 +145,7 @@ test("mountConnectors imports the pack entry and registers the drained worker",
   const out = await engine.deliver("slack:send-message", {
     jobKey: "j1",
     jobType: "slack:send-message",
+    processInstanceKey: "pi1",
     variables: { text: "hi" },
   });
   assert.deepEqual(out, { echoed: "hi" });
@@ -212,7 +215,7 @@ test("mountConnectors fails closed on a duplicate worker type in one pack entry"
 });
 
 test("adaptConnectorHandler maps complete/fail/error(BpmnError) and a returned value", async () => {
-  const job: EngineJob = { jobKey: "j", jobType: "t", variables: {} };
+  const job: EngineJob = { jobKey: "j", jobType: "t", processInstanceKey: "pi", variables: {} };
 
   const completes = adaptConnectorHandler({ type: "t", handle: async (j) => void (await j.complete({ a: 1 })) });
   assert.deepEqual(await completes(job), { a: 1 });
@@ -229,3 +232,22 @@ test("adaptConnectorHandler maps complete/fail/error(BpmnError) and a returned v
     (e: unknown) => e instanceof BpmnError && e.errorCode === "CODE",
   );
 });
+
+test("adaptConnectorHandler fails loud on a job with no processInstanceKey (no masking to '')", async () => {
+  // Guard for the decode-boundary defect class (Magikcraft/nano-bpm#940): a
+  // keyless job must reject, never invoke the connector with a fabricated "".
+  let handlerRan = false;
+  const h = adaptConnectorHandler({
+    type: "t",
+    handle: async () => {
+      handlerRan = true;
+    },
+  });
+  const keyless: EngineJob = { jobKey: "j", jobType: "t", variables: {} };
+  await assert.rejects(() => Promise.resolve(h(keyless)), /no processInstanceKey/);
+  assert.equal(handlerRan, false, "connector handler must not run for a keyless job");
+
+  // An empty-string key is the exact masking source and is rejected too.
+  const emptyKey: EngineJob = { jobKey: "j", jobType: "t", processInstanceKey: "", variables: {} };
+  await assert.rejects(() => Promise.resolve(h(emptyKey)), /no processInstanceKey/);
+});

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

@@ -134,6 +134,14 @@ export async function resolveInstalledConnectors(
  *  error boundary by the engine adapter); `job.fail(msg)` a plain throw (retry). */
 export function adaptConnectorHandler(worker: DefinedConnectorWorker): JobHandler {
   return async (job: EngineJob) => {
+    // A connector job always belongs to a process instance; a missing key is a
+    // protocol fault. Fail loud (the engine retries / raises an incident) rather
+    // than handing the connector a fabricated "" that would silently corrupt any
+    // instance-scoped call it makes.
+    const processInstanceKey = job.processInstanceKey;
+    if (processInstanceKey === undefined || processInstanceKey === "") {
+      throw new Error(`connector job '${job.jobType}' (${job.jobKey}) has no processInstanceKey`);
+    }
     let outcome:
       | { kind: "complete"; vars?: Record<string, unknown> }
       | { kind: "fail"; message: string }
@@ -142,7 +150,7 @@ export function adaptConnectorHandler(worker: DefinedConnectorWorker): JobHandle
     const facade: ConnectorWorkerJob = {
       jobKey: job.jobKey,
       type: job.jobType,
-      processInstanceKey: job.processInstanceKey ?? "",
+      processInstanceKey,
       elementId: job.elementId,
       variables: job.variables,
       async complete(vars) {

package/src/runtime/core/modules/instance-tracking.test.ts

@@ -17,53 +17,13 @@ import {
   WAITING_HUMAN_PROBE_CONCURRENCY,
 } from "./instance-tracking.ts";
 import { MAX_TIMER_DELAY_MS, type SchedulerDeps } from "./scheduler.ts";
+import { fakeScheduler } from "./scheduler.test-utils.ts";
 
 // A real-timer flush drains the entire pending microtask chain (find → engine → update)
 // each time a fake timer fires — deeper than a fixed number of `await Promise.resolve()`s.
 const realSetTimeout = globalThis.setTimeout;
 const flush = () => new Promise<void>((r) => realSetTimeout(r, 0));
 
-// A deterministic timer + clock seam (mirrors triggers.test.ts): `advance` fires every due
-// timer in order, draining microtasks between fires so the async reconcile completes.
-function fakeScheduler(): SchedulerDeps & { advance: (ms: number) => Promise<void>; pending: () => number } {
-  let clock = 0;
-  let seq = 0;
-  const timers = new Map<number, { at: number; fn: () => void }>();
-  return {
-    now: () => clock,
-    setTimer: (fn, delayMs) => {
-      const id = ++seq;
-      timers.set(id, { at: clock + delayMs, fn });
-      return id;
-    },
-    clearTimer: (h) => {
-      if (typeof h === "number") timers.delete(h);
-    },
-    pending: () => timers.size,
-    advance: async (ms) => {
-      const target = clock + ms;
-      // deno-lint-ignore no-constant-condition
-      while (true) {
-        let nextId = -1;
-        let nextAt = Infinity;
-        for (const [id, t] of timers) {
-          if (t.at <= target && t.at < nextAt) {
-            nextAt = t.at;
-            nextId = id;
-          }
-        }
-        if (nextId < 0) break;
-        const t = timers.get(nextId)!;
-        timers.delete(nextId);
-        clock = t.at;
-        t.fn();
-        await flush();
-      }
-      clock = target;
-    },
-  };
-}
-
 /** An EngineClient driven by a fixed map of processInstanceKey → state (for searchProcessInstances)
  *  and an optional map of processInstanceKey → number-of-open-user-tasks (for openUserTasks, the
  *  wait-on-human edge). Records the keys asked for on each call. `openUserTasks` models the engine
@@ -167,6 +127,8 @@ async function withHarness(
     data,
     engine,
     env: () => undefined,
+    now: () => 0,
+    wait: () => Promise.resolve(),
     log: createLogger((level, msg) => {
       logs.push({ level, msg });
     }),

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

@@ -0,0 +1,62 @@
+// Shared test-only fake for the injectable {@link SchedulerDeps} timer/clock seam. A single
+// canonical virtual-clock scheduler for every time-based test (workers, triggers, the
+// instance-tracking reconciler) so their virtual-time behavior can't drift apart — the drift
+// surface three per-file copies used to create. Excluded from the published build via the
+// `**/*.test-utils.ts` rule in tsconfig.build.json.
+
+import type { SchedulerDeps } from "./scheduler.ts";
+
+// A real-timer flush drains the entire pending microtask chain each time a fake timer fires —
+// deeper than a fixed number of `await Promise.resolve()`s, so an async follow-on chain (find →
+// engine → update, or a worker loop's next iteration) fully settles before the next timer fires.
+const realSetTimeout = globalThis.setTimeout;
+const flush = (): Promise<void> => new Promise<void>((resolve) => realSetTimeout(resolve, 0));
+
+/** A deterministic virtual-clock {@link SchedulerDeps}: timers fire only when the clock is advanced
+ *  past their deadline. `advance(ms)` fires every timer due within the interval in order, draining
+ *  microtasks between fires so an async loop's follow-on chain settles before the next fire, then
+ *  parks the clock at the target. `pending()` reports the number of armed timers. A non-positive /
+ *  non-finite delay clamps to fire at the current instant, mirroring the production
+ *  `schedulerClock` / `setTimer` clamp. Lets a test bound time-based work over virtual time without
+ *  touching the real wall clock. */
+export function fakeScheduler(
+  startMs = 0,
+): SchedulerDeps & { advance: (ms: number) => Promise<void>; pending: () => number } {
+  let clock = startMs;
+  let seq = 0;
+  const timers = new Map<number, { at: number; fn: () => void }>();
+  return {
+    now: () => clock,
+    setTimer: (fn, delayMs) => {
+      const id = ++seq;
+      timers.set(id, { at: clock + (Number.isFinite(delayMs) && delayMs > 0 ? delayMs : 0), fn });
+      return id;
+    },
+    clearTimer: (h) => {
+      if (typeof h === "number") timers.delete(h);
+    },
+    pending: () => timers.size,
+    advance: async (ms) => {
+      const target = clock + Math.max(0, ms);
+      // Fire due timers one at a time; a timer's callback may schedule a new one.
+      for (;;) {
+        let nextId = -1;
+        let nextAt = Number.POSITIVE_INFINITY;
+        for (const [id, t] of timers) {
+          if (t.at <= target && t.at < nextAt) {
+            nextAt = t.at;
+            nextId = id;
+          }
+        }
+        if (nextId < 0) break;
+        const t = timers.get(nextId);
+        if (!t) break;
+        timers.delete(nextId);
+        clock = t.at;
+        t.fn();
+        await flush();
+      }
+      clock = target;
+    },
+  };
+}

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

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { MAX_TIMER_DELAY_MS, type SchedulerDeps, schedulerClock } from "./scheduler.ts";
+
+// A capturing scheduler that records every delay handed to `setTimer` and fires it
+// synchronously, so a test can assert exactly what `schedulerClock().wait()` arms.
+function capturingScheduler(): SchedulerDeps & { delays: number[] } {
+  const delays: number[] = [];
+  return {
+    now: () => 0,
+    setTimer: (fn, delayMs) => {
+      delays.push(delayMs);
+      fn();
+      return 0;
+    },
+    clearTimer: () => {},
+    delays,
+  };
+}
+
+// Regression (PR #409 review, suppressed advisory scheduler.ts): `schedulerClock().wait()`
+// must clamp a far-future delay to MAX_TIMER_DELAY_MS so `app.wait()` can never pass a value
+// > setTimeout's 32-bit range and reintroduce a Node `TimeoutOverflowWarning`. The clamp lives
+// only here (the single canonical clock/`wait` seam), so it needs its own guard.
+test("schedulerClock.wait clamps a far-future delay to MAX_TIMER_DELAY_MS", async () => {
+  const sched = capturingScheduler();
+  await schedulerClock(sched).wait(MAX_TIMER_DELAY_MS * 3);
+  assert.deepEqual(sched.delays, [MAX_TIMER_DELAY_MS]);
+});
+
+test("schedulerClock.wait passes an in-range delay through unchanged", async () => {
+  const sched = capturingScheduler();
+  await schedulerClock(sched).wait(1234);
+  assert.deepEqual(sched.delays, [1234]);
+});
+
+test("schedulerClock.wait clamps non-positive / non-finite delays to the current instant", async () => {
+  const sched = capturingScheduler();
+  await schedulerClock(sched).wait(-5);
+  await schedulerClock(sched).wait(Number.NaN);
+  await schedulerClock(sched).wait(Number.POSITIVE_INFINITY);
+  assert.deepEqual(sched.delays, [0, 0, 0]);
+});

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

@@ -1,8 +1,8 @@
 // The injectable timer + clock seam shared by every background loop in urban (cron
-// triggers, the instance-tracking reconciler). 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.
+// triggers, the instance-tracking reconciler) and the app clock/`wait` seam handed to
+// 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.
 
 /** Injectable timer + clock seam so background scheduling is deterministic under test. */
 export interface SchedulerDeps {
@@ -29,3 +29,38 @@ export function defaultScheduler(): SchedulerDeps {
     now: () => Date.now(),
   };
 }
+
+/**
+ * The app-facing clock/`wait` seam handed to handlers (see `AppApi.now`/`AppApi.wait`).
+ * A narrow read-only projection of a {@link SchedulerDeps}: `now()` reads its clock and
+ * `wait(ms)` sleeps on its timer. Real wall clock + real timers in production; the
+ * virtual clock under the test kit — so time-bounded worker work advances with
+ * `advanceTime()` instead of burning real wall-time.
+ */
+export interface AppClock {
+  /** Current time in ms since epoch on the scheduler's clock. */
+  now(): number;
+  /** Resolve after `ms` have elapsed on the scheduler's clock (armed via its timer seam). */
+  wait(ms: number): Promise<void>;
+}
+
+/**
+ * Derive the app clock/`wait` seam from a scheduler — the single canonical mapping from the
+ * runtime's injectable timer seam to the surface handlers use, so worker/trigger/surface
+ * handlers doing time-bounded work share the same clock as the background loops (no drift
+ * between a handler's budget and the engine's timers). A non-positive/non-finite `wait`
+ * delay clamps to fire at the current instant, and a far-future delay clamps to
+ * {@link MAX_TIMER_DELAY_MS} — matching the same clamp the background loops apply to their
+ * `setTimer` delays (see `mountTriggers`/`mountInstanceTracking`) — so `app.wait()` can
+ * never reintroduce a Node `TimeoutOverflowWarning`.
+ */
+export function schedulerClock(sched: SchedulerDeps): AppClock {
+  return {
+    now: () => sched.now(),
+    wait: (ms) =>
+      new Promise<void>((resolve) => {
+        const delay = Number.isFinite(ms) && ms > 0 ? Math.min(ms, MAX_TIMER_DELAY_MS) : 0;
+        sched.setTimer(() => resolve(), delay);
+      }),
+  };
+}

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

@@ -58,6 +58,8 @@ const fakeApp: Parameters<typeof mountSurfaces>[1] = {
   data: new DataLayer(new Map(), undefined, {}),
   engine: fakeEngine,
   env: () => undefined,
+  now: () => 0,
+  wait: () => Promise.resolve(),
   log: createLogger(() => {}),
 };
 
@@ -108,6 +110,8 @@ function appWith(engine: EngineClient): Parameters<typeof mountSurfaces>[1] {
     data: new DataLayer(new Map(), undefined, {}),
     engine,
     env: () => undefined,
+    now: () => 0,
+    wait: () => Promise.resolve(),
     log: createLogger(() => {}),
   };
 }

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

@@ -6,7 +6,8 @@ import type { EngineClient, HostContext, HttpRequest } from "../host.ts";
 import type { Trigger } from "../manifest.ts";
 import { makeRouter } from "../router.ts";
 import { DataLayer } from "./datasource.ts";
-import { evalCorrelation, mountTriggers, runTriggerAction, type SchedulerDeps } from "./triggers.ts";
+import { evalCorrelation, mountTriggers, runTriggerAction } from "./triggers.ts";
+import { fakeScheduler } from "./scheduler.test-utils.ts";
 
 interface EngineCall {
   kind: "start" | "message";
@@ -49,6 +50,8 @@ function fakeApp(): { app: AppApi; calls: EngineCall[]; logs: Array<{ level: str
     data: new DataLayer(new Map(), undefined, {}),
     engine,
     env: () => undefined,
+    now: () => 0,
+    wait: () => Promise.resolve(),
     log: createLogger((level: string, msg: string) => {
       logs.push({ level, msg });
     }),
@@ -81,50 +84,6 @@ function fakeCtx(triggers: Trigger[]): { ctx: RuntimeContext; hostLogs: Array<{
   return { ctx, hostLogs };
 }
 
-/** A deterministic scheduler: timers fire only when the clock is advanced past their deadline. */
-function fakeScheduler(startMs: number): SchedulerDeps & { advance: (ms: number) => Promise<void>; pending: () => number } {
-  let clock = startMs;
-  let seq = 0;
-  const timers = new Map<number, { at: number; fn: () => void }>();
-  return {
-    now: () => clock,
-    setTimer: (fn, delayMs) => {
-      const id = ++seq;
-      timers.set(id, { at: clock + delayMs, fn });
-      return id;
-    },
-    clearTimer: (h) => {
-      if (typeof h === "number") timers.delete(h);
-    },
-    pending: () => timers.size,
-    // Advance the clock, firing every timer whose deadline has passed (in order), letting
-    // microtasks (the async action) drain between fires.
-    advance: async (ms) => {
-      const target = clock + ms;
-      // Fire due timers one at a time; a timer's callback may schedule a new one.
-      // deno-lint-ignore no-constant-condition
-      while (true) {
-        let nextId = -1;
-        let nextAt = Infinity;
-        for (const [id, t] of timers) {
-          if (t.at <= target && t.at < nextAt) {
-            nextAt = t.at;
-            nextId = id;
-          }
-        }
-        if (nextId < 0) break;
-        const t = timers.get(nextId)!;
-        timers.delete(nextId);
-        clock = t.at;
-        t.fn();
-        await Promise.resolve();
-        await Promise.resolve();
-      }
-      clock = target;
-    },
-  };
-}
-
 test("evalCorrelation resolves literals and = body paths", () => {
   const scope = { body: { taskId: 42 }, headers: {}, query: {} };
   assert.equal(evalCorrelation("lit", scope), "lit");

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

@@ -6,6 +6,7 @@ import type { EngineClient, EngineJob, HostContext, JobHandler, WorkerSubscripti
 import type { AppManifest } from "../manifest.ts";
 import { DataLayer, type ProvisionedSource } from "./datasource.ts";
 import { mountWorkers, sdkDecisionEvaluator, type AppJobHandler } from "./workers.ts";
+import { fakeScheduler } from "./scheduler.test-utils.ts";
 import { makeGateway } from "./gateway.ts";
 import { LineageStore } from "./lineage-store.ts";
 import {
@@ -79,6 +80,8 @@ function makeApp(over: Partial<AppApi> = {}): AppApi {
     engine: new MiniEngine(),
     env: (n) => env[n],
     log: createLogger(() => {}),
+    now: () => Date.now(),
+    wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
     ...over,
   };
 }
@@ -439,3 +442,95 @@ test("mountWorkers surfaces a configured-but-missing default source as a warn (n
   assert.ok(warned, "a configured-but-missing default source must warn, not silently degrade");
   assert.ok(!logs.some((l) => l.msg.includes("no default data source")), "must not claim the datasource is absent");
 });
+test("mountWorkers threads the injected scheduler: a worker's time-bounded loop is bounded by advanceTime, not real wall-time", async () => {
+  // The regression this guards (#408): before the scheduler was threaded into mountWorkers,
+  // a handler doing time-bounded work had to hardwire `Date.now()`/`setTimeout`, so under the
+  // test kit it burned the FULL real budget while virtual time had already moved on. Now the
+  // handler sources `now`/`wait` from `app`, so the loop advances only when the virtual clock
+  // does — and a whole-app `advanceTime` bounds it.
+  const BUDGET_MS = 60_000; // a real PT1M budget, like the readiness-probe symptom in the issue
+  const INTERVAL_MS = 10_000;
+  const sched = fakeScheduler(0);
+
+  let attempts = 0;
+  // A never-ready poll loop bound to the APP clock (deps-injected `now`/`wait` are the point).
+  const probe: AppJobHandler = async (_job, appApi) => {
+    const deadline = appApi.now() + BUDGET_MS;
+    while (appApi.now() < deadline) {
+      attempts += 1;
+      await appApi.wait(INTERVAL_MS); // never becomes ready; only the budget stops it
+    }
+    return { readied: false, attempts };
+  };
+
+  const engine = new MiniEngine();
+  const { ctx } = makeCtx({ workers: [{ taskType: "probe", handler: "workers/probe.ts" }] }, engine);
+  ctx.host.importModule = async () => ({ default: probe });
+
+  const handle = await mountWorkers(ctx, makeApp(), sched);
+  assert.deepEqual(handle.jobTypes, ["probe"]);
+
+  const wallStart = Date.now();
+  // Deliver the job: the handler runs up to its first `app.wait` and parks on the virtual timer.
+  const done = engine.deliver("probe", { jobKey: "j1", jobType: "probe", processInstanceKey: "pi", variables: {} });
+
+  // Nothing has advanced the clock yet, so the loop is parked — not spinning on real time.
+  assert.equal(sched.pending(), 1, "the handler must be parked on the virtual-clock wait, not a real timer");
+
+  // Advance the virtual clock across the whole budget; this is what bounds the loop.
+  await sched.advance(BUDGET_MS);
+  const out = await done;
+
+  const wallElapsed = Date.now() - wallStart;
+  assert.deepEqual(out, { readied: false, attempts: 6 }, "the loop must run exactly over its virtual budget");
+  assert.equal(sched.pending(), 0, "no virtual timers may leak past the budget");
+  assert.ok(
+    wallElapsed < 5_000,
+    `the loop must settle in virtual time, not burn the real ${BUDGET_MS}ms budget (took ${wallElapsed}ms real)`,
+  );
+
+  await handle.stop();
+});
+
+test("mountWorkers defaults the app clock to real timers when no scheduler is injected", async () => {
+  // Production parity: with no injected scheduler the handler's `app.now()`/`app.wait()` must fall
+  // through to the default seam — `Date.now()` + `globalThis.setTimeout`. Assert that seam directly
+  // by stubbing both globals, so the test is deterministic (no real 5ms sleep, no timer-jitter/clock-
+  // resolution race) and proves the exact wiring rather than an observable side effect of it.
+  const realSetTimeout = globalThis.setTimeout;
+  const realDateNow = Date.now;
+  const armedDelays: number[] = [];
+  let clock = 1_000;
+  try {
+    Date.now = () => clock;
+    // Object.assign carries realSetTimeout's full type (incl. `__promisify__`), so the merged value
+    // stays assignable to `typeof globalThis.setTimeout` without a cast; the spy fires ASAP and
+    // advances the fake clock by the armed delay, so no real wall-time elapses.
+    globalThis.setTimeout = Object.assign((fn: () => void, ms?: number) => {
+      armedDelays.push(ms ?? 0);
+      clock += ms ?? 0;
+      return realSetTimeout(fn, 0);
+    }, realSetTimeout);
+
+    let observed = -1;
+    const handler: AppJobHandler = async (_job, appApi) => {
+      const before = appApi.now();
+      await appApi.wait(5); // must arm the default (stubbed) setTimeout with delay 5
+      observed = appApi.now() - before;
+      return { ok: true };
+    };
+    const engine = new MiniEngine();
+    const { ctx } = makeCtx({ workers: [{ taskType: "tick", handler: "workers/tick.ts" }] }, engine);
+    ctx.host.importModule = async () => ({ default: handler });
+
+    const handle = await mountWorkers(ctx, makeApp()); // no scheduler → defaultScheduler()
+    const out = await engine.deliver("tick", { jobKey: "j1", jobType: "tick", processInstanceKey: "pi", variables: {} });
+    assert.deepEqual(out, { ok: true });
+    assert.ok(armedDelays.includes(5), "app.wait(5) must arm the default globalThis.setTimeout seam with delay 5");
+    assert.equal(observed, 5, "app.now must read the default Date.now clock (advanced by the armed 5ms timer)");
+    await handle.stop();
+  } finally {
+    globalThis.setTimeout = realSetTimeout;
+    Date.now = realDateNow;
+  }
+});

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

@@ -11,6 +11,7 @@ import { runInJobContext } from "../execContext.ts";
 import type { JobExecContext } from "../execContext.ts";
 import { readLineage } from "../lineage.ts";
 import { LineageStore } from "./lineage-store.ts";
+import { defaultScheduler, schedulerClock, type SchedulerDeps } from "./scheduler.ts";
 
 /** The subset of the engine SDK the LLM decision-rails need: evaluate a DMN decision,
  *  whose `output` comes back as a JSON string (the orchestration-cluster contract). */
@@ -168,11 +169,24 @@ export interface WorkersHandle extends Mounted {
 }
 
 /** Load handler modules and register a push worker per declared worker. */
-export async function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<WorkersHandle> {
+export async function mountWorkers(
+  ctx: RuntimeContext,
+  app: AppApi,
+  sched: SchedulerDeps = defaultScheduler(),
+): Promise<WorkersHandle> {
   const decls = ctx.manifest.workers ?? [];
   const subs: WorkerSubscription[] = [];
   const jobTypes: string[] = [];
 
+  // Bind the app clock/`wait` seam to the injected scheduler, so a handler's time-bounded
+  // work (poll loops, backoff, budgets) sources `now`/`wait` from the same clock that drives
+  // the engine's timers and the other background loops. Under the test kit that is the
+  // virtual clock, so `advanceTime()` bounds the loop instead of it burning real wall-time;
+  // in production it is the live scheduler (real timers) — no behavior change. Mirrors how
+  // `mountTriggers`/`mountInstanceTracking` receive the same seam.
+  const clock = schedulerClock(sched);
+  const clockedApp: AppApi = { ...app, now: clock.now, wait: clock.wait };
+
   // The framework lineage projection (issue #254): each activated job records the `_urban.lineage`
   // edge its instance carries, so intent→progress lineage materialises for free. Absent when the
   // app configures no default data source.
@@ -246,7 +260,7 @@ export async function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<Wo
       if (lineageStore) recordJobLineage(lineageStore, job, ctx.host.log);
       return runInJobContext(
         jobExecContext(job, jobType),
-        () => handler(job, withJobLog(app, job)),
+        () => handler(job, withJobLog(clockedApp, job)),
       );
     };
     const sub = await ctx.engine.registerWorker(jobType, wrapped, {

package/src/runtime/core/runtime.ts

@@ -18,7 +18,7 @@ import { mountConnectors } from "./modules/connectors.ts";
 import { mountSurfaces } from "./modules/surfaces.ts";
 import { mountTriggers } from "./modules/triggers.ts";
 import { mountInstanceTracking } from "./modules/instance-tracking.ts";
-import type { SchedulerDeps } from "./modules/scheduler.ts";
+import { defaultScheduler, schedulerClock, type SchedulerDeps } from "./modules/scheduler.ts";
 import { mountSecurity, type SecurityPolicy } from "./modules/security.ts";
 import { EventBus } from "./events.ts";
 import { createUrbanEvents, mountExtensions, type UrbanEvents, type UrbanExtension } from "./extensions.ts";
@@ -77,11 +77,13 @@ export interface CreateUrbanAppOptions {
   mount?: MountFlags;
   /**
    * Injectable timer + clock seam driving every background loop (the cron trigger loops
-   * and the instance-tracking reconciler). Defaults to the live scheduler (real timers,
-   * wall clock). The e2e test kit injects a manual scheduler so those loops advance
-   * deterministically over a virtual clock — the single seam that makes a whole-app
-   * `settle()` possible. Threaded verbatim into `mountTriggers` and `mountInstanceTracking`
-   * so one injected scheduler drives them both (no per-module wiring, no drift).
+   * and the instance-tracking reconciler) and the app clock/`wait` seam handed to worker
+   * handlers. Defaults to the live scheduler (real timers, wall clock). The e2e test kit
+   * injects a manual scheduler so those loops — and any time-bounded worker sourcing
+   * `app.now()`/`app.wait()` — advance deterministically over a virtual clock: the single
+   * seam that makes a whole-app `settle()` possible. Threaded verbatim into `mountWorkers`,
+   * `mountTriggers` and `mountInstanceTracking` so one injected scheduler drives them all
+   * (no per-module wiring, no drift).
    */
   scheduler?: SchedulerDeps;
   /**
@@ -258,6 +260,12 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
         if (flags.deploy) describe.deploy = await deployModels(ctx);
 
         data = flags.data ? await provisionData(ctx) : new DataLayer(new Map(), undefined, {});
+        // Resolve the injectable scheduler once (default: live real-timer seam) so the app
+        // clock/`wait` seam handed to handlers and every background loop share one clock —
+        // the single source the test kit swaps for a virtual clock to make `settle()` /
+        // `advanceTime()` bound the whole app (workers included).
+        const scheduler = opts.scheduler ?? defaultScheduler();
+        const clock = schedulerClock(scheduler);
         const api: AppApi = {
           manifest,
           data,
@@ -265,10 +273,12 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
           sdk: engineSdk(engine),
           env: (n) => host.env(n),
           log: appLog,
+          now: clock.now,
+          wait: clock.wait,
         };
 
         if (flags.workers) {
-          const w = await mountWorkers(ctx, api);
+          const w = await mountWorkers(ctx, api, scheduler);
           mounted.push(w);
           describe.workers = w.describe?.();
           // Connector-pack workers share the `workers` flag: same lifecycle, same
@@ -294,13 +304,13 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
           describe.surfaces = s.describe();
         }
         if (flags.triggers) {
-          const t = mountTriggers(ctx, api, opts.scheduler);
+          const t = mountTriggers(ctx, api, scheduler);
           routes.push(...t.routes);
           mounted.push(t);
           describe.triggers = t.describe?.();
         }
         if (flags.instanceTracking && (manifest.instanceTracking?.length ?? 0) > 0) {
-          const it = mountInstanceTracking(ctx, api, opts.scheduler);
+          const it = mountInstanceTracking(ctx, api, scheduler);
           mounted.push(it);
           describe.instanceTracking = it.describe?.();
         }