@nanobpm/urban 0.71.0 → 0.72.0

package/src/context/adversarial/pii-guard.test.ts

@@ -0,0 +1,119 @@
+// Slice S7 (adversarial) — the no-PII guard holds BY CONSTRUCTION and under
+// evasion.
+//
+// The DEFAULT S3 write path (no special caller wiring) must reject a
+// PII-carrying record because S3 pre-registers the mandatory S6 guard. These
+// tests prove that, then attempt obfuscated / nested / edge-case PII and confirm
+// the guard still blocks it — and that a caller cannot bypass it.
+
+import assert from "node:assert/strict";
+import { after, test } from "node:test";
+import { ContextWriter } from "../git/index.ts";
+import { PiiGuardError, type PiiGuard, classifyPii, preCommitPiiGuard } from "../pii/index.ts";
+import { ContextRetriever } from "../retrieval/index.ts";
+import { cleanup, makeSubstrate, rec } from "./harness.ts";
+
+const TEMP_ROOTS: string[] = [];
+after(() => cleanup(TEMP_ROOTS));
+
+test("the DEFAULT write path (no wiring) rejects a PII-carrying record", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  // Plain default construction — the caller does NOT opt into any guard.
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+
+  // The mandatory PII guard is present — and FIRST — by construction.
+  assert.equal(
+    writer.guards[0],
+    preCommitPiiGuard,
+    "the mandatory PII guard must be registered first",
+  );
+
+  await assert.rejects(
+    () => writer.appendRecord(rec({ id: "pii-plain", statement: "reach me at alice@example.com" })),
+    PiiGuardError,
+  );
+
+  // Governance path is guarded too.
+  await assert.rejects(
+    () =>
+      writer.proposePrior(
+        rec({
+          id: "pii-propose",
+          provenance: "agent-retro",
+          mode: "normative",
+          authority: "hypothesis",
+          statement: "ssn 123-45-6789 belongs to the reporter",
+        }),
+      ),
+    PiiGuardError,
+  );
+
+  // Nothing leaked into the store.
+  const retriever = new ContextRetriever({ localPath: dir, ref: "main" });
+  assert.equal((await retriever.all()).length, 0);
+});
+
+test("PII hidden in a NESTED field (evidence array) is still blocked", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+  await assert.rejects(
+    () =>
+      writer.appendRecord(
+        rec({
+          id: "pii-nested",
+          statement: "clean summary",
+          evidence: ["run-1", "leaked contact alice@example.com in logs"],
+        }),
+      ),
+    PiiGuardError,
+  );
+});
+
+test("OBFUSCATED email evades a naive scan but not the guard", () => {
+  // The classifier's de-obfuscation pass catches spelled-out separators.
+  const obfuscated = "contact bob [at] example [dot] com for details";
+  const result = classifyPii(obfuscated);
+  assert.equal(result.clean, false, "obfuscated email must be detected");
+  assert.equal(result.findings.some((f) => f.kind === "email"), true);
+
+  // The default guard throws on it, mirroring the write path.
+  assert.throws(() => preCommitPiiGuard.assert(obfuscated), PiiGuardError);
+});
+
+test("clean content passes the guard and lands", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+  await writer.appendRecord(rec({ id: "clean-1", statement: "throughput improved to 42 rps" }));
+
+  const retriever = new ContextRetriever({ localPath: dir, ref: "main" });
+  assert.equal((await retriever.all()).some((s) => s.record.id === "clean-1"), true);
+});
+
+test("an extra caller guard can only make enforcement STRICTER, never bypass PII", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  // A DISTINCT, always-throwing caller guard. If a caller-supplied guard could
+  // displace the mandatory PII guard — or run before it — a PII write would
+  // surface THIS sentinel error instead of PiiGuardError.
+  const alwaysThrows: PiiGuard = {
+    name: "always-throws",
+    inspect: () => ({ clean: true, findings: [] }),
+    assert: () => {
+      throw new Error("extra caller guard ran");
+    },
+  };
+  const writer = new ContextWriter(
+    { localPath: dir, ref: "main" },
+    { guards: [alwaysThrows] },
+  );
+  // The mandatory guard is still FIRST; the caller guard is only appended.
+  assert.equal(writer.guards[0], preCommitPiiGuard, "mandatory PII guard must run first");
+  assert.equal(writer.guards.includes(alwaysThrows), true, "caller guard is added, not dropped");
+
+  // A PII write is rejected by the mandatory guard (which runs first) — with
+  // PiiGuardError, NOT the sentinel — proving the caller guard neither displaced
+  // nor pre-empted mandatory enforcement.
+  await assert.rejects(
+    () => writer.appendRecord(rec({ id: "pii-extra", statement: "email me: eve@example.org" })),
+    PiiGuardError,
+  );
+});

package/src/context/adversarial/provenance-forgery.test.ts

@@ -0,0 +1,126 @@
+// Slice S7 (adversarial) — PROVENANCE / AUTHORITY forgery resistance.
+//
+// The headline invariant of the whole layer is "hypothesis-never-fix": an
+// unratified / agent-retrospective prior can never be REPRESENTED as a measured
+// or authoritative fact. These tests attack that invariant directly — at the
+// schema, at the write path, and after ratification — at EVERY scope.
+
+import assert from "node:assert/strict";
+import { after, test } from "node:test";
+import { ContextWriter } from "../git/index.ts";
+import { ContextRetriever } from "../retrieval/index.ts";
+import {
+  MemoryRecordValidationError,
+  type MemoryScope,
+  SCOPE_LADDER,
+  assertMemoryRecord,
+  isAuthoritative,
+  validateMemoryRecord,
+} from "../schema/index.ts";
+import { cleanup, makeSubstrate, rec } from "./harness.ts";
+
+const TEMP_ROOTS: string[] = [];
+after(() => cleanup(TEMP_ROOTS));
+
+/** The forgery target: an agent-retro prior masquerading as an authoritative fact. */
+function forgedAtScope(scope: MemoryScope): Record<string, unknown> {
+  return {
+    schemaVersion: 1,
+    id: `forged-${scope}`,
+    scope,
+    mode: "empirical",
+    provenance: "agent-retro",
+    authority: "authoritative",
+    statement: "a hypothesis laundered into a fact",
+    createdAt: "2026-01-01T00:00:00Z",
+  };
+}
+
+test("schema: agent-retro can NEVER be authoritative — at every scope", () => {
+  for (const scope of SCOPE_LADDER) {
+    const result = validateMemoryRecord(forgedAtScope(scope));
+    assert.equal(result.ok, false, `scope ${scope}: forged record must be rejected`);
+    if (!result.ok) {
+      assert.equal(
+        result.errors.some((e) => e.code === "invariant-violation"),
+        true,
+        `scope ${scope}: expected an invariant-violation`,
+      );
+    }
+    assert.throws(() => assertMemoryRecord(forgedAtScope(scope)), MemoryRecordValidationError);
+  }
+});
+
+test("schema: no field permutation reaches authoritative via agent-retro", () => {
+  // The ONLY provenances that may be authoritative are human/measured/instance.
+  for (const mode of ["normative", "empirical"] as const) {
+    const result = validateMemoryRecord({
+      schemaVersion: 1,
+      id: "x",
+      scope: "repo",
+      mode,
+      provenance: "agent-retro",
+      authority: "authoritative",
+      statement: "s",
+      createdAt: "2026-01-01T00:00:00Z",
+    });
+    assert.equal(result.ok, false, `agent-retro/${mode}/authoritative must be rejected`);
+  }
+});
+
+test("write path: a forged agent-retro-authoritative record cannot be persisted", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+
+  // Neither write path will commit it: append validates+rejects the invariant
+  // (and also refuses agent-retro directly), propose validates+rejects it too.
+  await assert.rejects(() => writer.appendRecord(forgedAtScope("epic")));
+  await assert.rejects(() => writer.proposePrior(forgedAtScope("epic")));
+
+  // And nothing landed in the store.
+  const retriever = new ContextRetriever({ localPath: dir, ref: "main" });
+  const all = await retriever.all();
+  assert.equal(all.some((s) => s.record.id === "forged-epic"), false);
+  assert.equal(all.length, 0);
+});
+
+test("write path: agent-retro is refused on the DIRECT append path (must go via governance)", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+  // A perfectly valid agent-retro hypothesis is still not directly appendable.
+  await assert.rejects(() =>
+    writer.appendRecord(
+      rec({
+        id: "retro-direct",
+        provenance: "agent-retro",
+        mode: "normative",
+        authority: "hypothesis",
+        statement: "prefer X over Y",
+      }),
+    ),
+  );
+});
+
+test("ratification does NOT upgrade authority — the merged record stays a hypothesis", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+
+  const proposal = await writer.proposePrior(
+    rec({
+      id: "retro-1",
+      provenance: "agent-retro",
+      mode: "normative",
+      authority: "hypothesis",
+      statement: "a proposed prior",
+    }),
+  );
+  await writer.ratify(proposal);
+
+  const retriever = new ContextRetriever({ localPath: dir, ref: "main" });
+  const found = (await retriever.all()).find((s) => s.record.id === "retro-1");
+  assert.ok(found, "the ratified proposal is now on the authoritative line");
+  // Ratified ≠ authoritative: the record is an ACCEPTED hypothesis, never a fact.
+  assert.equal(found.record.authority, "hypothesis");
+  assert.equal(found.record.provenance, "agent-retro");
+  assert.equal(isAuthoritative(found.record), false);
+});

package/src/context/adversarial/seams.test.ts

@@ -0,0 +1,104 @@
+// Slice S7 (adversarial) — the pluggable SEAMS don't leak a backend assumption.
+//
+// Retrieval must be correct from a COLD/empty derived cache (git is
+// authoritative, the cache is a disposable projection), and the binding / read
+// seams must NOT hard-wire "exclusively public git" — local paths, file:// URLs
+// and ssh remotes are first-class, and a custom RecordSource can back retrieval
+// without any git at all.
+
+import assert from "node:assert/strict";
+import { after, test } from "node:test";
+import { resolveContextIdentity, sameContext } from "../binding/index.ts";
+import { ContextWriter } from "../git/index.ts";
+import {
+  ContextRetriever,
+  type NamespaceSelector,
+  type RecordSource,
+  type StoredRecord,
+} from "../retrieval/index.ts";
+import type { MemoryRecord } from "../schema/index.ts";
+import { cleanup, makeSubstrate, rec } from "./harness.ts";
+
+const TEMP_ROOTS: string[] = [];
+after(() => cleanup(TEMP_ROOTS));
+
+test("retrieval is correct on a COLD cache — the first query falls back to git", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+  await writer.appendRecord(rec({ id: "cold-1", scope: "epic", scopeRef: "issue-303" }));
+  await writer.appendRecord(rec({ id: "cold-2", scope: "repo", scopeRef: "nano-ide", statement: "s2" }));
+
+  // Brand-new retriever: the derived cache is cold. This FIRST query has no
+  // warmed snapshot to read, so it falls back to git — and, as a side effect,
+  // populates the snapshot. We assert the cold-path result is complete.
+  const retriever = new ContextRetriever({ localPath: dir, ref: "main" });
+  const cold = await retriever.query({});
+  assert.equal(cold.length, 2, "a cold cache must still return every record via git");
+
+  // A path-scoped structured query on a COLD cache reads just that partition
+  // without forcing a full snapshot build. Use a FRESH retriever so the cache is
+  // genuinely cold here — the `query({})` above already warmed `retriever`.
+  const nsRetriever = new ContextRetriever({ localPath: dir, ref: "main" });
+  assert.equal(nsRetriever.cache.isWarm, false, "a fresh retriever's cache must be cold");
+  const scoped = await nsRetriever.byNamespace("repo", "nano-ide");
+  assert.equal(scoped.length, 1);
+  assert.equal(scoped[0].record.id, "cold-2");
+  assert.equal(nsRetriever.cache.isWarm, false, "a single-namespace query must not warm the full cache");
+});
+
+test("git is authoritative — the derived cache is disposable and rebuildable", async () => {
+  const dir = await makeSubstrate(TEMP_ROOTS);
+  const writer = new ContextWriter({ localPath: dir, ref: "main" });
+  await writer.appendRecord(rec({ id: "auth-1" }));
+
+  const retriever = new ContextRetriever({ localPath: dir, ref: "main" });
+  assert.equal((await retriever.all()).length, 1); // warms the cache
+
+  // A write happens in git AFTER the cache was warmed.
+  await writer.appendRecord(rec({ id: "auth-2", scope: "repo", scopeRef: "nano-ide", statement: "later" }));
+
+  // The stale snapshot doesn't see it; invalidating rebuilds purely from git.
+  retriever.invalidate();
+  const rebuilt = await retriever.all();
+  assert.equal(rebuilt.length, 2, "cache must rebuild the full truth from git");
+  assert.equal(rebuilt.some((s) => s.record.id === "auth-2"), true);
+
+  // The forward-compat embedding seam is opt-in and absent in the MVP.
+  assert.equal(retriever.embeddingIndex, undefined);
+});
+
+test("the READ seam is pluggable — retrieval works over a non-git RecordSource", async () => {
+  const record: MemoryRecord = rec({ id: "mem-1", subject: "latency", statement: "backend-agnostic" });
+  const stored: StoredRecord = { path: "records/epic/issue-303/mem-1.md", record };
+
+  // An in-memory source that never touches git — proving the seam isn't
+  // hard-wired to "exclusively public git".
+  const memorySource: RecordSource = {
+    async list(_selector?: NamespaceSelector) {
+      return [stored];
+    },
+    async read(relPath: string) {
+      return relPath === stored.path ? stored : undefined;
+    },
+  };
+
+  const retriever = new ContextRetriever("/unused/path", { source: memorySource });
+  const all = await retriever.all();
+  assert.equal(all.length, 1);
+  assert.equal(all[0].record.id, "mem-1");
+  const bySubject = await retriever.query({ subject: "latency" });
+  assert.equal(bySubject.length, 1);
+});
+
+test("binding identity is NOT hard-wired to public GitHub — local/file/ssh are first-class", () => {
+  // A local path and its file:// spelling name the SAME (self-hosted) context.
+  const localPath = "/srv/substrates/ctx";
+  const local = resolveContextIdentity({ repo: localPath, ref: "main" });
+  assert.ok(local.key.length > 0, "a local-path substrate must resolve to an identity");
+  assert.equal(sameContext({ repo: localPath, ref: "main" }, { repo: `file://${localPath}`, ref: "main" }), true);
+
+  // An ssh remote resolves too, and differs from an unrelated host.
+  const ssh = resolveContextIdentity({ repo: "git@example.com:team/ctx.git", ref: "main" });
+  assert.ok(ssh.key.length > 0);
+  assert.notEqual(ssh.key, local.key);
+});

package/src/context/adversarial/sharing.test.ts

@@ -0,0 +1,84 @@
+// Slice S7 (adversarial) — cross-instance SHARING semantics.
+//
+// Proves the "private-per-app / shared-on-same-name" contract can't be broken:
+// two instances naming the SAME context (repo+ref) see each other's ratified
+// writes, and two instances naming DISTINCT contexts stay isolated. Exercised at
+// both the S1 identity layer and end-to-end through S3's write path + S4 reads.
+
+import assert from "node:assert/strict";
+import { after, test } from "node:test";
+import {
+  type ContextBinding,
+  contextIdentityKey,
+  resolveContextIdentity,
+  sameContext,
+} from "../binding/index.ts";
+import { ContextWriter } from "../git/index.ts";
+import { ContextRetriever } from "../retrieval/index.ts";
+import { cleanup, makeSubstrate, rec } from "./harness.ts";
+
+const TEMP_ROOTS: string[] = [];
+after(() => cleanup(TEMP_ROOTS));
+
+const binding = (repo: string, ref: string): ContextBinding => ({ repo, ref });
+
+test("identity: same (repo, ref) name shares; a distinct name stays private", () => {
+  const a = binding("nanobpm/nano-ide", "main");
+  const same = binding("nanobpm/nano-ide", "main");
+  const otherRef = binding("nanobpm/nano-ide", "release");
+  const otherRepo = binding("nanobpm/nano-workforce", "main");
+
+  assert.equal(sameContext(a, same), true);
+  assert.equal(contextIdentityKey(a), contextIdentityKey(same));
+
+  // A different ref OR a different repo is a genuinely different context.
+  assert.equal(sameContext(a, otherRef), false);
+  assert.equal(sameContext(a, otherRepo), false);
+  assert.notEqual(contextIdentityKey(a), contextIdentityKey(otherRef));
+  assert.notEqual(contextIdentityKey(a), contextIdentityKey(otherRepo));
+
+  // On-disk slug tracks the key: shared names → shared location; distinct → not.
+  assert.equal(resolveContextIdentity(a).slug, resolveContextIdentity(same).slug);
+  assert.notEqual(resolveContextIdentity(a).slug, resolveContextIdentity(otherRef).slug);
+});
+
+test("identity: equivalent repo spellings collapse to one shared substrate", () => {
+  // Shorthand, HTTPS clone URL, and a credentialed URL all name one context.
+  // The credentialed form uses the repo's redacted userinfo placeholder (`***@`)
+  // — it still exercises the "userinfo must not affect identity" invariant
+  // without embedding a credential-in-URL literal that trips secret scanning.
+  const shorthand = binding("nanobpm/nano-ide", "main");
+  const https = binding("https://github.com/nanobpm/nano-ide.git", "main");
+  const credential = binding("https://***@github.com/nanobpm/nano-ide.git", "main");
+
+  assert.equal(sameContext(shorthand, https), true);
+  assert.equal(sameContext(shorthand, credential), true, "credentials must not split identity");
+});
+
+test("end-to-end: a second instance on the same context reads the first's write", async () => {
+  const shared = await makeSubstrate(TEMP_ROOTS);
+
+  // Instance A writes a ratified fact into the shared substrate.
+  const writerA = new ContextWriter({ localPath: shared, ref: "main" });
+  await writerA.appendRecord(
+    rec({ id: "shared-fact", scope: "epic", scopeRef: "issue-303", statement: "A observed 42 rps" }),
+  );
+
+  // Instance B — a distinct object naming the SAME context — sees it.
+  const retrieverB = new ContextRetriever({ localPath: shared, ref: "main" });
+  const seenByB = await retrieverB.all();
+  assert.equal(seenByB.some((s) => s.record.id === "shared-fact"), true);
+});
+
+test("end-to-end: a distinct-name instance cannot see another context's writes", async () => {
+  const shared = await makeSubstrate(TEMP_ROOTS);
+  const other = await makeSubstrate(TEMP_ROOTS);
+
+  const writerA = new ContextWriter({ localPath: shared, ref: "main" });
+  await writerA.appendRecord(rec({ id: "private-fact", statement: "only visible in shared" }));
+
+  const retrieverOther = new ContextRetriever({ localPath: other, ref: "main" });
+  const seen = await retrieverOther.all();
+  assert.equal(seen.some((s) => s.record.id === "private-fact"), false);
+  assert.equal(seen.length, 0, "an unrelated context must stay empty/private");
+});

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(() => {}),
   };
 }

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;
+    },
+  };
+}