@nanobpm/urban 0.71.0 → 0.72.0

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?.();
         }