@nanobpm/urban 0.27.0 → 0.29.0

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

@@ -0,0 +1,345 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createNodeHost } from "../../adapters/node.ts";
+import { makeGateway } from "./gateway.ts";
+import type { Table } from "./gateway.ts";
+import { DataLayer, type ProvisionedSource } from "./datasource.ts";
+import type { AppApi } from "../context.ts";
+import type { EngineClient, ProcessInstanceSnapshot } from "../host.ts";
+import type { InstanceTracking } from "../manifest.ts";
+import {
+  DEFAULT_INSTANCE_TRACKING_POLL_MS,
+  mountInstanceTracking,
+} from "./instance-tracking.ts";
+import { MAX_TIMER_DELAY_MS, type SchedulerDeps } from "./scheduler.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 whose only live method is searchProcessInstances, driven by a fixed map of
+ *  processInstanceKey → state. Records the keys asked for on each call. */
+function fakeEngine(states: Record<string, ProcessInstanceSnapshot["state"]>): {
+  engine: EngineClient;
+  queries: string[][];
+} {
+  const queries: string[][] = [];
+  const notUsed = (m: string) => (): never => {
+    throw new Error(`fakeEngine.${m} is not exercised by this test`);
+  };
+  // Typed as EngineClient (not `as unknown as`) so the compiler enforces the full contract:
+  // if EngineClient gains/changes a method, this fake fails to compile instead of drifting.
+  const engine: EngineClient = {
+    async searchProcessInstances(filter?: {
+      processInstanceKeys?: string[];
+      state?: ProcessInstanceSnapshot["state"];
+    }): Promise<ProcessInstanceSnapshot[]> {
+      const keys = filter?.processInstanceKeys ?? [];
+      queries.push([...keys]);
+      const out: ProcessInstanceSnapshot[] = [];
+      for (const key of keys) {
+        const state = states[key];
+        if (state && (!filter?.state || filter.state === state)) {
+          out.push({ processInstanceKey: key, state });
+        }
+      }
+      return out;
+    },
+    deployResources: notUsed("deployResources"),
+    createInstance: notUsed("createInstance"),
+    cancelInstance: notUsed("cancelInstance"),
+    publishMessage: notUsed("publishMessage"),
+    searchUserTasks: notUsed("searchUserTasks"),
+    completeUserTask: notUsed("completeUserTask"),
+    registerWorker: notUsed("registerWorker"),
+    close: notUsed("close"),
+  };
+  return { engine, queries };
+}
+
+interface Harness {
+  api: AppApi;
+  table: Table<PlanRow>;
+  dir: string;
+  close: () => Promise<void>;
+  logs: { level: string; msg: string }[];
+}
+
+// The row shape every test seeds (matches PLANS_DDL); typing the harness table with it lets
+// `table.get(...)` return a typed row instead of the generic `object` constraint that
+// `ReturnType<DataLayer["table"]>` collapses to.
+interface PlanRow {
+  plan_key: string;
+  process_key: string | null;
+  status: string;
+  note: string | null;
+}
+
+async function withHarness(
+  engine: EngineClient,
+  ddl: string,
+  seed: (t: Table<PlanRow>) => Promise<void>,
+  keyField = "process_key",
+  table = "plans",
+): Promise<Harness> {
+  const dir = await mkdtemp(join(tmpdir(), "urban-instance-tracking-"));
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const db = host.openSqlite(join(dir, "test.db"));
+  db.exec(ddl);
+  const source: ProvisionedSource = {
+    name: "app",
+    driver: "sqlite",
+    db,
+    source: makeGateway(db),
+    migrationsApplied: [],
+    close: () => db.close(),
+  };
+  const data = new DataLayer(new Map([["app", source]]), "app", {});
+  const tbl = data.table<PlanRow>(table, keyField);
+  await seed(tbl);
+  const logs: { level: string; msg: string }[] = [];
+  const api: AppApi = {
+    manifest: { schemaVersion: 1, id: "app", name: "App" },
+    data,
+    engine,
+    env: () => undefined,
+    log: (level, msg) => logs.push({ level, msg }),
+  };
+  return {
+    api,
+    table: tbl,
+    dir,
+    logs,
+    close: async () => {
+      db.close();
+      await rm(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+const PLANS_DDL =
+  "CREATE TABLE plans (plan_key TEXT PRIMARY KEY, process_key TEXT, status TEXT NOT NULL, note TEXT)";
+
+const planBinding = (over: Partial<InstanceTracking> = {}): InstanceTracking => ({
+  table: "plans",
+  keyField: "process_key",
+  statusField: "status",
+  activeStatuses: ["planning", "dispatched"],
+  onTerminated: { set: { status: "abandoned", note: null } },
+  pollMs: 1000,
+  ...over,
+});
+
+test("reconciles an active row whose instance is TERMINATED", async () => {
+  const { engine } = fakeEngine({ pi1: "TERMINATED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: "hi" });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [planBinding()], sched);
+  await sched.advance(1000);
+  const row = await h.table.get("pi1");
+  assert.equal(row?.status, "abandoned");
+  assert.equal(row?.note, null);
+  await handle.stop();
+  await h.close();
+});
+
+test("leaves an active row whose instance is still ACTIVE untouched", async () => {
+  const { engine } = fakeEngine({ pi1: "ACTIVE" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: "hi" });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [planBinding()], sched);
+  await sched.advance(1000);
+  const row = await h.table.get("pi1");
+  assert.equal(row?.status, "dispatched");
+  await handle.stop();
+  await h.close();
+});
+
+test("does NOT reconcile a COMPLETED instance (a finalize worker owns that row)", async () => {
+  const { engine, queries } = fakeEngine({ pi1: "COMPLETED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: "hi" });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [planBinding()], sched);
+  await sched.advance(1000);
+  const row = await h.table.get("pi1");
+  assert.equal(row?.status, "dispatched"); // untouched
+  // and it did ask the engine, filtered to TERMINATED
+  assert.deepEqual(queries, [["pi1"]]);
+  await handle.stop();
+  await h.close();
+});
+
+test("only polls rows in an active status (skips already-terminal rows)", async () => {
+  const { engine, queries } = fakeEngine({ pi1: "TERMINATED", pi2: "TERMINATED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: null });
+    await t.insert({ plan_key: "p2", process_key: "pi2", status: "abandoned", note: null }); // terminal
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [planBinding()], sched);
+  await sched.advance(1000);
+  assert.deepEqual(queries, [["pi1"]]); // pi2 was already terminal, never polled
+  await handle.stop();
+  await h.close();
+});
+
+test("skips rows whose key column is null/empty", async () => {
+  const { engine, queries } = fakeEngine({});
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: null, status: "dispatched", note: null });
+    await t.insert({ plan_key: "p2", process_key: "", status: "dispatched", note: null });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [planBinding()], sched);
+  await sched.advance(1000);
+  assert.equal(queries.length, 0); // no keys to poll → no engine call
+  await handle.stop();
+  await h.close();
+});
+
+test("re-arms after each tick and stops cleanly", async () => {
+  const { engine, queries } = fakeEngine({ pi1: "ACTIVE" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: null });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [planBinding()], sched);
+  await sched.advance(1000);
+  await sched.advance(1000);
+  await sched.advance(1000);
+  assert.equal(queries.length, 3); // polled once per interval
+  assert.equal(sched.pending(), 1); // one timer armed for the next tick
+  await handle.stop();
+  assert.equal(sched.pending(), 0); // stop() cleared it
+  await h.close();
+});
+
+test("without statusField/activeStatuses, polls every row", async () => {
+  const { engine, queries } = fakeEngine({ pi1: "TERMINATED", pi2: "TERMINATED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "abandoned", note: null });
+    await t.insert({ plan_key: "p2", process_key: "pi2", status: "dispatched", note: null });
+  });
+  const sched = fakeScheduler();
+  const binding = planBinding({ statusField: undefined, activeStatuses: undefined });
+  const handle = mount(h, [binding], sched);
+  await sched.advance(1000);
+  assert.deepEqual(queries[0]?.sort(), ["pi1", "pi2"]);
+  // both got reconciled (already-abandoned p1 is a no-op change, p2 flips)
+  assert.equal((await h.table.get("pi2"))?.status, "abandoned");
+  await handle.stop();
+  await h.close();
+});
+
+test("defaults pollMs when the binding omits it", async () => {
+  const { engine, queries } = fakeEngine({ pi1: "ACTIVE" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: null });
+  });
+  const sched = fakeScheduler();
+  const binding = planBinding({ pollMs: undefined });
+  const handle = mount(h, [binding], sched);
+  await sched.advance(DEFAULT_INSTANCE_TRACKING_POLL_MS - 1);
+  assert.equal(queries.length, 0); // not yet
+  await sched.advance(1);
+  assert.equal(queries.length, 1); // fired at the default interval
+  await handle.stop();
+  await h.close();
+});
+
+test("clamps a pollMs beyond setTimeout's 32-bit range instead of firing immediately", async () => {
+  const { engine, queries } = fakeEngine({ pi1: "ACTIVE" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: null });
+  });
+  const sched = fakeScheduler();
+  // A pollMs past the 32-bit signed range would overflow setTimeout and fire at ~0 (a hot loop).
+  const handle = mount(h, [planBinding({ pollMs: MAX_TIMER_DELAY_MS * 3 })], sched);
+  await sched.advance(1000);
+  assert.equal(queries.length, 0); // did NOT fire immediately …
+  await sched.advance(MAX_TIMER_DELAY_MS);
+  assert.equal(queries.length, 1); // … it fired at the clamped delay
+  await handle.stop();
+  await h.close();
+});
+
+// A binding mounted without validation (or with a hand-built binding) must not become a
+// 0-delay hot loop when pollMs is non-positive/NaN — it falls back to the default interval.
+for (const bad of [0, -1000, Number.NaN]) {
+  test(`falls back to the default interval for a non-positive/NaN pollMs (${bad})`, async () => {
+    const { engine, queries } = fakeEngine({ pi1: "ACTIVE" });
+    const h = await withHarness(engine, PLANS_DDL, async (t) => {
+      await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: null });
+    });
+    const sched = fakeScheduler();
+    const handle = mount(h, [planBinding({ pollMs: bad })], sched);
+    await sched.advance(DEFAULT_INSTANCE_TRACKING_POLL_MS - 1);
+    assert.equal(queries.length, 0); // did NOT hot-loop at ~0 …
+    await sched.advance(1);
+    assert.equal(queries.length, 1); // … it fired at the default interval instead
+    await handle.stop();
+    await h.close();
+  });
+}
+
+
+function mount(h: Harness, bindings: InstanceTracking[], sched: SchedulerDeps) {
+  h.api.manifest.instanceTracking = bindings;
+  return mountInstanceTracking(
+    // biome-ignore lint/plugin: RuntimeContext test double — mountInstanceTracking reads only manifest/engine/root; host is unused here.
+    { manifest: h.api.manifest, host: {} as never, engine: h.api.engine, root: "." },
+    h.api,
+    sched,
+  );
+}

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

@@ -0,0 +1,158 @@
+// instance-tracking — the process-instance lifecycle reconciler (manifest `instanceTracking`).
+//
+// The problem it closes: an Urban app derives a row's status from the workers that run
+// along a process's *happy path*. When an instance instead reaches a terminal state with
+// no completion job — an operator/`cancelInstance` termination, or a crash — no worker
+// runs, so the read-model row stays "active" forever and any UI derived from it lies.
+//
+// Each `instanceTracking` binding names a datasource table whose rows track an instance by
+// a key column. This module polls the engine for those rows' instances and, when one is
+// `TERMINATED`, applies the binding's `onTerminated.set` patch to the row. It deliberately
+// reconciles only on `TERMINATED` — the state that by definition runs no completion worker
+// — and never on `COMPLETED`, whose terminal row-write the app's own finalize worker owns
+// (reconciling it here would race that worker and could clobber a legitimately-completed
+// row). The poll is driven through the shared `SchedulerDeps` seam so tests are deterministic.
+
+import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
+import type { InstanceTracking } from "../manifest.ts";
+import { defaultScheduler, MAX_TIMER_DELAY_MS, type SchedulerDeps } from "./scheduler.ts";
+
+/** Default poll interval when a binding does not set `pollMs`. */
+export const DEFAULT_INSTANCE_TRACKING_POLL_MS = 15_000;
+
+export interface InstanceTrackingHandle extends Mounted {
+  /** `table.keyField` labels of the armed bindings, for `inspect()`. */
+  readonly bindings: string[];
+}
+
+type Row = Record<string, unknown>;
+
+/** Poll one binding's instances once. Selects the active rows, asks the engine which of their
+ *  instances are TERMINATED, and applies `onTerminated.set` to each. Returns how many keys were
+ *  scanned and how many rows were reconciled this tick. */
+async function reconcileOnce(
+  api: AppApi,
+  binding: InstanceTracking,
+): Promise<{ scanned: number; reconciled: number }> {
+  const table = api.data.table<Row>(binding.table, binding.keyField);
+
+  // Select the rows worth polling. With a statusField + activeStatuses, only rows in an
+  // active status are candidates, so a row already in a terminal status is skipped; without
+  // them every row is polled and a terminal instance's row is idempotently re-patched (the
+  // engine query returns only TERMINATED instances and the patch is a no-op once applied).
+  let candidates: Row[];
+  const statusField = binding.statusField;
+  if (statusField && binding.activeStatuses && binding.activeStatuses.length > 0) {
+    const perStatus = await Promise.all(
+      binding.activeStatuses.map((s): Promise<Row[]> => table.find({ [statusField]: s })),
+    );
+    candidates = perStatus.flat();
+  } else {
+    candidates = await table.all();
+  }
+
+  // Map each active row to its tracked instance key. A row with no/empty key can't be
+  // reconciled (it never started an instance, or the column is unset) — skip it.
+  const keyToRows = new Map<string, Row[]>();
+  for (const row of candidates) {
+    const raw = row[binding.keyField];
+    if (raw == null || raw === "") continue;
+    const key = String(raw);
+    const list = keyToRows.get(key);
+    if (list) list.push(row);
+    else keyToRows.set(key, [row]);
+  }
+  const keys = [...keyToRows.keys()];
+  if (keys.length === 0) return { scanned: 0, reconciled: 0 };
+
+  const snapshots = await api.engine.searchProcessInstances({
+    processInstanceKeys: keys,
+    state: "TERMINATED",
+  });
+
+  const patch: Partial<Row> = binding.onTerminated.set;
+  let reconciled = 0;
+  for (const snap of snapshots) {
+    if (snap.state !== "TERMINATED") continue; // defensive; we asked for TERMINATED only
+    if (!keyToRows.has(snap.processInstanceKey)) continue; // not one we were tracking
+    const changed = await table.update(snap.processInstanceKey, patch);
+    if (changed > 0) {
+      reconciled += changed;
+      api.log("info", "instanceTracking: reconciled terminated instance", {
+        table: binding.table,
+        keyField: binding.keyField,
+        processInstanceKey: snap.processInstanceKey,
+        rowsChanged: changed,
+      });
+    }
+  }
+  return { scanned: keys.length, reconciled };
+}
+
+/**
+ * Mount the `instanceTracking` reconciler: arm one poll loop per binding. Each loop selects
+ * the active rows, asks the engine which of their instances are terminated, and applies the
+ * declared patch. `stop()` cancels every armed timer.
+ */
+export function mountInstanceTracking(
+  ctx: RuntimeContext,
+  api: AppApi,
+  sched: SchedulerDeps = defaultScheduler(),
+): InstanceTrackingHandle {
+  const bindings = ctx.manifest.instanceTracking ?? [];
+  const timers = new Set<unknown>();
+  const armed: string[] = [];
+  let stopped = false;
+
+  for (const binding of bindings) {
+    // `pollMs` feeds a self-rescheduling timer, so a non-number/NaN/zero/negative value would
+    // clamp to a 0-delay hot loop. `??` only guards null/undefined; sanitize to a finite positive
+    // number and otherwise fall back to the default. (Manifest validation rejects bad values up
+    // front; this is belt-and-suspenders for a binding mounted without validation.)
+    const rawPoll = binding.pollMs;
+    const pollMs = typeof rawPoll === "number" && Number.isFinite(rawPoll) && rawPoll > 0
+      ? rawPoll
+      : DEFAULT_INSTANCE_TRACKING_POLL_MS;
+    // A single setTimeout delay overflows its 32-bit signed range (~24.8 days) and fires
+    // immediately — which for a self-rescheduling poll would become a hot loop. Clamp through
+    // the one shared constant the cron trigger loop uses (derive-don't-duplicate).
+    const delayMs = Math.min(pollMs, MAX_TIMER_DELAY_MS);
+    const label = `${binding.table}.${binding.keyField}`;
+    armed.push(label);
+
+    const arm = (): void => {
+      if (stopped) return;
+      let handle: unknown;
+      handle = sched.setTimer(() => {
+        timers.delete(handle);
+        if (stopped) return;
+        void (async () => {
+          try {
+            await reconcileOnce(api, binding);
+          } catch (err) {
+            api.log("error", `instanceTracking "${label}": reconcile failed`, {
+              error: String(err),
+            });
+          } finally {
+            arm(); // reschedule regardless of outcome (at-least-once, idempotent)
+          }
+        })();
+      }, delayMs);
+      timers.add(handle);
+    };
+    arm();
+  }
+
+  return {
+    name: "instanceTracking",
+    bindings: armed,
+    async stop(): Promise<void> {
+      stopped = true;
+      for (const h of timers) sched.clearTimer(h);
+      timers.clear();
+    },
+    describe(): Record<string, unknown> {
+      return { bindings: armed };
+    },
+  };
+}

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

@@ -41,6 +41,7 @@ function fakeEngine(): { engine: EngineClient; calls: FakeEngineCalls } {
     },
     async searchUserTasks() { return []; },
     async completeUserTask() {},
+    async searchProcessInstances() { return []; },
     async registerWorker(jobType) { return { jobType, unsubscribe: async () => {} }; },
     async close() {},
   };
@@ -65,12 +66,14 @@ function build(dbOverrides: Partial<PagesDataSource> = {}) {
   const db = fakeDb(dbOverrides);
   const readPage = async (path: string) => {
     if (path === "pages/home.page.json") return JSON.stringify({ title: "Home", nodes: [] });
+    if (path === "pages/epic.page.json") return JSON.stringify({ title: "Epic Coordination", nodes: [] });
     throw new Error("not found");
   };
   const routes = createPagesRoutes({ pagesDir: "pages", homePage: "home", sourceName: "app" }, {
     db,
     engine,
     readPage,
+    listPages: async () => ["home", "epic"],
   });
   const router = makeRouter(routes);
   return { router, calls };
@@ -212,8 +215,9 @@ test("renderer makes collapsible nodes persist their state across sessions", asy
   assert.match(js, /if \(!props\.collapsible\) return card;/);
   // Seed from defaultCollapsed the first time, then from persisted state.
   assert.match(js, /readCollapsed\(storageKey, !!props\.defaultCollapsed\)/);
-  // Namespaced, per-node storage key.
-  assert.match(js, /"pc:collapsed:" \+ HOME \+ ":" \+ \(node\.id/);
+  // Namespaced, per-node storage key — keyed by the *current* page id so two
+  // pages that reuse a node id don't share collapse state across navigation.
+  assert.match(js, /"pc:collapsed:" \+ CURRENT \+ ":" \+ \(node\.id/);
   // Persist on toggle.
   assert.match(js, /writeCollapsed\(storageKey, collapsed\)/);
   // Every storage access is wrapped so a throwing localStorage can't break the UI.
@@ -239,6 +243,77 @@ test("GET /app/pages/<id> returns the page json, 404 for unknown", async () => {
   assert.equal(miss.status, 404);
 });
 
+test("GET /app/pages indexes the available pages with titles + home flag", async () => {
+  const res = await dispatch("GET", "/app/pages");
+  assert.equal(res.status, 200);
+  const body = JSON.parse(res.body ?? "{}");
+  assert.equal(body.home, "home");
+  const byId = Object.fromEntries((body.pages ?? []).map((p: { id: string }) => [p.id, p]));
+  assert.deepEqual(byId.home, { id: "home", title: "Home", home: true });
+  assert.deepEqual(byId.epic, { id: "epic", title: "Epic Coordination", home: false });
+  // The exact index path must not be shadowed by the /app/pages/<id> prefix route.
+  assert.equal((await dispatch("GET", "/app/pages/epic")).status, 200);
+});
+
+test("GET /app/pages is empty (not an error) when listing is unavailable", async () => {
+  // listPages is optional — without it the index is an empty list, not a 500.
+  const routes = createPagesRoutes({ pagesDir: "pages", homePage: "home", sourceName: "app" }, {
+    db: fakeDb(),
+    engine: fakeEngine().engine,
+    readPage: async () => "{}",
+  });
+  const res = await makeRouter(routes)(req("GET", "/app/pages"));
+  assert.equal(res.status, 200);
+  assert.deepEqual(JSON.parse(res.body ?? "{}"), { pages: [], home: "home" });
+});
+
+test("the renderer routes between pages by hash and tears down grid polls", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // A page is chosen by the URL fragment (#/<page>), validated to a safe id, and
+  // re-rendered on hashchange — proxy-safe because the hash never hits the server.
+  assert.match(js, /const PAGE_ID = \/\^\[A-Za-z0-9_-/);
+  assert.match(js, /function safePageId\(value\)/);
+  assert.match(js, /function currentPage\(\)/);
+  assert.match(js, /try \{\s*const raw = decodeURIComponent/s);
+  assert.match(js, /catch \(e\) \{\s*return HOME;/s);
+  assert.match(js, /location\.hash/);
+  assert.match(js, /window\.addEventListener\("hashchange", renderPage\)/);
+  assert.match(js, /async function renderPage\(\)/);
+  // Navigation runs every registered disposer first, so a switched-away grid's
+  // poll interval + pc:refresh listener are removed rather than leaking forever.
+  assert.match(js, /const disposers = \[\]/);
+  assert.match(js, /function teardown\(\)/);
+  assert.match(js, /disposers\.push\(\(\) => document\.removeEventListener\("pc:refresh", refresh\)\)/);
+  assert.match(js, /disposers\.push\(\(\) => clearInterval\(timer\)\)/);
+});
+
+test("the renderer ships a nav node (menu bar / rail) with in-app + external links", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // nav is a first-class node type.
+  assert.match(js, /nav: renderNav/);
+  assert.match(js, /function renderNav\(node\)/);
+  // "rail" variant renders a side rail; anything else is a horizontal bar.
+  assert.match(js, /p\.variant === "rail"/);
+  assert.match(js, /"pc-nav pc-rail"/);
+  assert.match(js, /"pc-nav pc-bar"/);
+  // A page item becomes an in-app hash link, active-highlighted on the current page.
+  assert.match(js, /const isPage = safePageId\(item\.page\)/);
+  assert.match(js, /attrs\.href = "#\/" \+ encodeURIComponent\(item\.page\)/);
+  assert.match(js, /item\.page === CURRENT/);
+  assert.match(js, /aria-current/);
+  // An external item is an http(s)-only, hardened new-tab link.
+  assert.match(js, /\^https\?:\\\/\\\//);
+  assert.match(js, /attrs\.rel = "noopener noreferrer"/);
+  // items:"auto" (or omitted) enumerates every page from the index endpoint.
+  assert.match(js, /getJSON\("\/app\/pages"\)/);
+  // A rail is lifted into a left <aside>; the rest flow into a content column.
+  assert.match(js, /pc-rail-wrap/);
+  assert.match(js, /pc-layout/);
+  assert.match(js, /pc-main-col/);
+});
+
 test("GET /app/data/<source>/<table> returns rows", async () => {
   const res = await dispatch("GET", "/app/data/app/orders");
   assert.equal(res.status, 200);