@nanobpm/urban 0.27.0 → 0.29.0

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

@@ -43,6 +43,12 @@ export interface PagesDeps {
   engine: EngineClient;
   /** Read a page file; injectable for tests. */
   readPage(path: string): Promise<string>;
+  /**
+   * List the available page ids (the `*.page.json` basenames under `pagesDir`),
+   * powering the `/app/pages` index endpoint and a `nav` node's `items: "auto"`.
+   * Optional; when absent the index is empty. Injectable for tests.
+   */
+  listPages?(): Promise<string[]>;
 }
 
 /** A JavaScript-body response (the renderer module served at /app/runtime.js). */
@@ -64,7 +70,7 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
   const rowLimitRaw = opts.rowLimit ?? 200;
   const rowLimit = Number.isFinite(rowLimitRaw) ? Math.max(0, Math.floor(rowLimitRaw)) : 200;
   const sourceName = opts.sourceName ?? "app";
-  const { db, engine, readPage } = deps;
+  const { db, engine, readPage, listPages } = deps;
 
   // The table-name whitelist is memoised: an Urban app runs its migrations at boot
   // (before serving), so the schema is stable for the process lifetime, and the renderer
@@ -113,6 +119,34 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
     handler: () => javascript(RENDERER_JS),
   });
 
+  // ── GET /app/pages (index of available pages) ───────────────────────────
+  // Powers multi-page navigation: a `nav` node with `items: "auto"` lists every
+  // page here, and it lets any client enumerate the app's screens. Each entry
+  // carries the page's own `title` (best-effort — an unreadable/!JSON page still
+  // appears by id) and a `home` flag. Registered as an exact path so it never
+  // shadows the `/app/pages/<id>` prefix route below.
+  routes.push({
+    method: "GET",
+    path: "/app/pages",
+    source: "surface:pages",
+    handler: async () => {
+      const ids = listPages ? await listPages().catch(() => []) : [];
+      const pages: { id: string; title: string; home: boolean }[] = [];
+      for (const id of ids) {
+        if (!/^[A-Za-z0-9_-]+$/.test(id)) continue;
+        let title = id;
+        try {
+          const doc = JSON.parse(await readPage(`${pagesDir}/${id}.page.json`));
+          if (isRecord(doc) && typeof doc.title === "string" && doc.title) title = doc.title;
+        } catch {
+          // Unreadable or non-JSON page: still list it by id.
+        }
+        pages.push({ id, title, home: id === homePage });
+      }
+      return json({ pages, home: homePage });
+    },
+  });
+
   // ── GET /app/pages/<id> ─────────────────────────────────────────────────
   routes.push({
     method: "GET",
@@ -324,6 +358,13 @@ export function mountPages(ctx: RuntimeContext, app: AppApi): PagesHandle {
     db: app.data.open(sourceName),
     engine: app.engine,
     readPage: (p) => ctx.host.readTextFile(p),
+    listPages: async () => {
+      const dir = opts.pagesDir ?? "pages";
+      const names = await ctx.host.listDir(dir).catch(() => []);
+      return names
+        .filter((n) => n.endsWith(".page.json"))
+        .map((n) => n.slice(0, -".page.json".length));
+    },
   });
   ctx.host.log("info", "pages surface mounted", { source: sourceName, home: opts.homePage ?? "home" });
   return {
@@ -430,6 +471,22 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-collapse-header { display:flex; align-items:center; gap:.5rem; width:100%; margin:0 0 .75rem; padding:0; background:transparent; border:0; color:inherit; font:inherit; font-size:1rem; font-weight:600; cursor:pointer; text-align:left; }
 .pc-chevron-inline { color:var(--nano-text-faint); font-size:.75rem; width:1em; }
 .pc-card-body[hidden] { display:none; }
+/* Multi-page navigation: a horizontal menu bar or a vertical side rail. */
+.pc-layout { display:flex; gap:1.5rem; align-items:flex-start; }
+.pc-rail-wrap { flex:0 0 12rem; position:sticky; top:1rem; align-self:flex-start; }
+.pc-main-col { flex:1 1 auto; min-width:0; }
+.pc-nav-title { font-weight:650; }
+.pc-bar { display:flex; align-items:center; gap:.6rem; flex-wrap:wrap; border-bottom:1px solid var(--nano-edge); padding-bottom:.6rem; margin-bottom:1.25rem; }
+.pc-bar .pc-nav-title { margin-right:.5rem; }
+.pc-bar .pc-nav-items { display:flex; gap:.25rem; flex-wrap:wrap; }
+.pc-rail { display:flex; flex-direction:column; gap:.5rem; }
+.pc-rail .pc-nav-title { margin-bottom:.25rem; padding:0 .7rem; }
+.pc-rail .pc-nav-items { display:flex; flex-direction:column; gap:.15rem; }
+.pc-nav-link { display:flex; align-items:center; gap:.4rem; padding:.4rem .7rem; border-radius:.4rem; color:var(--nano-text-muted); text-decoration:none; font-size:.9rem; }
+.pc-nav-link:hover { background:var(--nano-hover); color:var(--nano-text); }
+.pc-nav-link.active { background:var(--nano-accent); color:var(--nano-on-accent); }
+.pc-nav-icon { line-height:1; }
+.pc-nav-empty { color:var(--nano-text-faint); font-size:.85rem; padding:.4rem .7rem; }
 `;
 
 // The schema-driven browser renderer (ADR 0042 §3). Plain ES module string served at
@@ -440,6 +497,37 @@ const RENDERER_JS = String.raw`
 const root = document.getElementById("page");
 const HOME = root.dataset.home || "home";
 
+// ── Multi-page routing (hash-based, reverse-proxy safe) ──────────────────
+// Pages are selected by the URL fragment (#/<page>) so navigation never hits
+// the server and works identically at the origin root and under the Nano
+// console's /console/app-view/<name>/ path-prefixed proxy (the hash is never
+// sent upstream). An empty/invalid hash falls back to the home page. Only a
+// safe id charset is accepted so the fragment can't smuggle a path/URL.
+const PAGE_ID = /^[A-Za-z0-9_-]+$/;
+function safePageId(value) {
+  return typeof value === "string" && PAGE_ID.test(value);
+}
+function currentPage() {
+  try {
+    const raw = decodeURIComponent((location.hash || "").replace(/^#\/?/, ""));
+    return safePageId(raw) ? raw : HOME;
+  } catch (e) {
+    return HOME;
+  }
+}
+let CURRENT = currentPage();
+
+// Per-render teardown. Each dataGrid registers its poll interval + pc:refresh
+// listener here; navigating to another page runs every disposer before the new
+// page renders, so a switched-away grid stops polling (otherwise every visited
+// page would leave a live setInterval fetching forever).
+const disposers = [];
+function teardown() {
+  while (disposers.length) {
+    try { disposers.pop()(); } catch (e) { /* best-effort cleanup */ }
+  }
+}
+
 // Theme bridge for the Nano console embed. The app runs in a sandboxed,
 // same-origin iframe, so the console's --nano-* custom properties and its
 // data-appearance never cascade in. Instead the console postMessages its
@@ -888,15 +976,71 @@ function renderDataGrid(node) {
     }
   }
   document.addEventListener("pc:refresh", refresh);
+  disposers.push(() => document.removeEventListener("pc:refresh", refresh));
   // Skip the automatic poll while the user is typing in the grid — an explicit pc:refresh
   // (e.g. after submitting an answer) still runs — so rows never shift under an in-progress
-  // answer and the detail input keeps focus across ticks.
-  if (p.refreshMs && p.refreshMs > 0) setInterval(() => { if (!editingInGrid()) refresh(); }, p.refreshMs);
+  // answer and the detail input keeps focus across ticks. The interval is registered as a
+  // disposer so a page switch (hashchange → renderPage → teardown) stops it.
+  if (p.refreshMs && p.refreshMs > 0) {
+    const timer = setInterval(() => { if (!editingInGrid()) refresh(); }, p.refreshMs);
+    disposers.push(() => clearInterval(timer));
+  }
   refresh();
   return card;
 }
 
-const RENDERERS = { text: renderText, actionForm: renderActionForm, dataGrid: renderDataGrid };
+// A navigation node — a horizontal menu bar (variant "bar", default) or a
+// vertical side rail (variant "rail"). Each item links either to another page
+// ({ label, page } -> an in-app #/<page> hash link, highlighted when it's the
+// current page) or to an external URL ({ label, href } -> a hardened new-tab
+// link; only http(s) is honoured). With items:"auto" (or omitted) the nav
+// lists every page from the /app/pages index, using each page's title.
+function navLink(item) {
+  const isPage = safePageId(item.page);
+  const isExt = !isPage && typeof item.href === "string" && /^https?:\/\//i.test(item.href);
+  if (!isPage && !isExt) return null;
+  const attrs = { class: "pc-nav-link" };
+  if (isPage) {
+    attrs.href = "#/" + encodeURIComponent(item.page);
+    if (item.page === CURRENT) { attrs.class += " active"; attrs["aria-current"] = "page"; }
+  } else {
+    attrs.href = item.href; attrs.target = "_blank"; attrs.rel = "noopener noreferrer";
+  }
+  const kids = [];
+  if (item.icon != null) kids.push(el("span", { class: "pc-nav-icon" }, String(item.icon)));
+  kids.push(el("span", { class: "pc-nav-label" }, String(item.label != null ? item.label : (item.page || item.href))));
+  return el("a", attrs, ...kids);
+}
+function fillNav(list, items) {
+  list.replaceChildren();
+  let n = 0;
+  for (const item of items || []) {
+    if (!item || typeof item !== "object") continue;
+    const a = navLink(item);
+    if (a) { list.append(a); n++; }
+  }
+  if (!n) list.append(el("span", { class: "pc-nav-empty" }, "No pages"));
+}
+function renderNav(node) {
+  const p = node.props || {};
+  const rail = p.variant === "rail";
+  const nav = el("nav", { class: rail ? "pc-nav pc-rail" : "pc-nav pc-bar" });
+  if (p.title != null) nav.append(el("div", { class: "pc-nav-title" }, String(p.title)));
+  const list = el("div", { class: "pc-nav-items" });
+  nav.append(list);
+  const items = p.items;
+  if (Array.isArray(items)) {
+    fillNav(list, items);
+  } else {
+    // "auto" (or unspecified): enumerate every page and link to each.
+    getJSON("/app/pages")
+      .then((res) => fillNav(list, (res.pages || []).map((pg) => ({ label: pg.title || pg.id, page: pg.id }))))
+      .catch(() => list.append(el("span", { class: "pc-nav-empty" }, "No pages")));
+  }
+  return nav;
+}
+
+const RENDERERS = { text: renderText, actionForm: renderActionForm, dataGrid: renderDataGrid, nav: renderNav };
 
 // Durable per-node UI state. localStorage is keyed by the home page id + node
 // id so two grids on the same page (or the same grid across pages) don't clash,
@@ -951,7 +1095,7 @@ function makeCollapsible(node, card) {
     chevron,
     el("span", { class: "pc-collapse-title" }, titleText),
   );
-  const storageKey = "pc:collapsed:" + HOME + ":" + (node.id || titleText);
+  const storageKey = "pc:collapsed:" + CURRENT + ":" + (node.id || titleText);
   let collapsed = readCollapsed(storageKey, !!props.defaultCollapsed);
   function apply() {
     body.hidden = collapsed;
@@ -968,16 +1112,30 @@ function makeCollapsible(node, card) {
   return container;
 }
 
-async function main() {
+// Render the page named by the current hash route. A rail nav is lifted into a
+// left <aside> and the rest of the nodes flow into a content column; otherwise
+// (bar nav or none) nodes render in document order. Re-runs on every hashchange,
+// tearing down the previous page's grid polls first.
+async function renderPage() {
+  teardown();
+  CURRENT = currentPage();
   try {
-    const doc = await getJSON("/app/pages/" + encodeURIComponent(HOME));
-    if (doc.title) document.title = doc.title;
-    root.replaceChildren(
-      ...(doc.nodes || []).map((n) => makeCollapsible(n, (RENDERERS[n.type] || (() => el("div")))(n))),
-    );
+    const doc = await getJSON("/app/pages/" + encodeURIComponent(CURRENT));
+    document.title = (doc && doc.title) || "Urban App";
+    const nodes = (doc && doc.nodes) || [];
+    const built = nodes.map((n) => ({ n, node: makeCollapsible(n, (RENDERERS[n.type] || (() => el("div")))(n)) }));
+    const rail = built.find((b) => b.n.type === "nav" && b.n.props && b.n.props.variant === "rail");
+    if (rail) {
+      const col = el("div", { class: "pc-main-col" });
+      for (const b of built) if (b !== rail) col.append(b.node);
+      root.replaceChildren(el("div", { class: "pc-layout" }, el("aside", { class: "pc-rail-wrap" }, rail.node), col));
+    } else {
+      root.replaceChildren(...built.map((b) => b.node));
+    }
   } catch (e) {
-    root.replaceChildren(el("p", { class: "pc-msg err" }, "Failed to load page: " + String(e.message || e)));
+    root.replaceChildren(el("p", { class: "pc-msg err" }, "Failed to load page: " + String((e && e.message) || e)));
   }
 }
-main();
+window.addEventListener("hashchange", renderPage);
+renderPage();
 `;

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

@@ -0,0 +1,181 @@
+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 {
+  ensureProvenanceTable,
+  makeProvenanceRecorder,
+  WRITE_PROVENANCE_TABLE,
+} from "./datasource.ts";
+import {
+  __resetExecStoreForTests,
+  currentJobContext,
+  installExecStore,
+  runInJobContext,
+  type JobExecContext,
+} from "../execContext.ts";
+import type { HostContext, SqliteDb } from "../host.ts";
+
+interface Note {
+  id: number;
+  body: string;
+}
+
+interface ProvRow {
+  source: string;
+  table_name: string;
+  pk_value: string;
+  instance_key: string | null;
+  element_id: string | null;
+  job_type: string | null;
+  op: string;
+  at: string;
+}
+
+async function withSource(
+  fn: (host: HostContext, db: SqliteDb) => Promise<void>,
+): Promise<void> {
+  const dir = await mkdtemp(join(tmpdir(), "urban-prov-"));
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const db = host.openSqlite(join(dir, "test.db"));
+  db.exec("CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT NOT NULL)");
+  try {
+    await fn(host, db);
+  } finally {
+    db.close();
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+function provRows(db: SqliteDb): ProvRow[] {
+  return db.all<ProvRow>(`SELECT * FROM ${WRITE_PROVENANCE_TABLE} ORDER BY seq`);
+}
+
+test("insert inside a job context records a provenance row linking row → instance/element", async () => {
+  __resetExecStoreForTests();
+  await withSource(async (host, db) => {
+    installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+    ensureProvenanceTable(db);
+    const src = makeGateway(db, makeProvenanceRecorder(host, db, "main"));
+    const notes = src.table<Note>("notes");
+
+    let id: number | bigint = 0;
+    await runInJobContext(
+      { instanceKey: "inst-1", elementId: "Task_persist", jobType: "notes.write" },
+      async () => {
+        id = await notes.insert({ body: "hello" });
+      },
+    );
+
+    const rows = provRows(db);
+    assert.equal(rows.length, 1);
+    assert.equal(rows[0].source, "main");
+    assert.equal(rows[0].table_name, "notes");
+    assert.equal(rows[0].pk_value, String(id));
+    assert.equal(rows[0].instance_key, "inst-1");
+    assert.equal(rows[0].element_id, "Task_persist");
+    assert.equal(rows[0].job_type, "notes.write");
+    assert.equal(rows[0].op, "insert");
+    assert.ok(rows[0].at.length > 0);
+  });
+});
+
+test("insert outside any job context records no provenance (graceful degradation)", async () => {
+  __resetExecStoreForTests();
+  await withSource(async (host, db) => {
+    installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+    ensureProvenanceTable(db);
+    const src = makeGateway(db, makeProvenanceRecorder(host, db, "main"));
+    await src.table<Note>("notes").insert({ body: "no ctx" });
+    assert.equal(provRows(db).length, 0);
+  });
+});
+
+test("a job context without an instance key records no provenance", async () => {
+  __resetExecStoreForTests();
+  await withSource(async (host, db) => {
+    installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+    ensureProvenanceTable(db);
+    const src = makeGateway(db, makeProvenanceRecorder(host, db, "main"));
+    await runInJobContext({ jobType: "notes.write" }, async () => {
+      await src.table<Note>("notes").insert({ body: "no instance" });
+    });
+    assert.equal(provRows(db).length, 0);
+  });
+});
+
+test("a provenance-write failure never breaks the app insert", async () => {
+  __resetExecStoreForTests();
+  await withSource(async (host, db) => {
+    installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+    // Deliberately do NOT create the provenance table, so the recorder's own INSERT throws.
+    const src = makeGateway(db, makeProvenanceRecorder(host, db, "main"));
+    let id: number | bigint = 0;
+    await runInJobContext({ instanceKey: "inst-9" }, async () => {
+      id = await src.table<Note>("notes").insert({ body: "resilient" });
+    });
+    // The app row is written despite provenance capture failing.
+    assert.equal((await src.table<Note>("notes").get(id))?.body, "resilient");
+  });
+});
+
+test("the recorder does not record writes to urban/engine-internal tables", async () => {
+  __resetExecStoreForTests();
+  await withSource(async (host, db) => {
+    installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+    ensureProvenanceTable(db);
+    const recorder = makeProvenanceRecorder(host, db, "main");
+    runInJobContext({ instanceKey: "inst-1" }, () => {
+      recorder("_urban_migrations", 1);
+      recorder(WRITE_PROVENANCE_TABLE, 2);
+      recorder("_nano_events", 3);
+      recorder("sqlite_sequence", 4);
+    });
+    assert.equal(provRows(db).length, 0);
+  });
+});
+
+test("with no store installed, capture is a transparent no-op", async () => {
+  __resetExecStoreForTests();
+  // No installExecStore call: runInJobContext must pass through and currentJobContext be undefined.
+  let ran = false;
+  const out = runInJobContext({ instanceKey: "x" }, () => {
+    ran = true;
+    assert.equal(currentJobContext(), undefined);
+    return 42;
+  });
+  assert.equal(ran, true);
+  assert.equal(out, 42);
+});
+
+test("installExecStore is idempotent — the first install wins", async () => {
+  __resetExecStoreForTests();
+  await withSource(async (host, db) => {
+    void db;
+    installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+    // A second install with a factory that would throw must be ignored (never invoked).
+    installExecStore(() => {
+      throw new Error("second install must not run");
+    });
+    runInJobContext({ instanceKey: "inst-2" }, () => {
+      assert.equal(currentJobContext()?.instanceKey, "inst-2");
+    });
+  });
+});
+
+test("installExecStore can install after an incapable host returns no store", async () => {
+  __resetExecStoreForTests();
+  await withSource(async (host, db) => {
+    void db;
+    installExecStore(() => undefined);
+    assert.equal(currentJobContext(), undefined);
+
+    installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+    runInJobContext({ instanceKey: "inst-3" }, () => {
+      assert.equal(currentJobContext()?.instanceKey, "inst-3");
+    });
+  });
+});

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

@@ -0,0 +1,31 @@
+// 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.
+
+/** Injectable timer + clock seam so background scheduling is deterministic under test. */
+export interface SchedulerDeps {
+  setTimer: (fn: () => void, delayMs: number) => unknown;
+  clearTimer: (handle: unknown) => void;
+  /** Current wall-clock time in ms since epoch. */
+  now: () => number;
+}
+
+/** 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: unknown): handle is ReturnType<typeof setTimeout> {
+  return typeof handle === "number" || (typeof handle === "object" && handle !== null);
+}
+
+/** Default (live) scheduler seam, backed by the global timer functions. */
+export function defaultScheduler(): SchedulerDeps {
+  return {
+    setTimer: (fn, ms) => globalThis.setTimeout(fn, ms),
+    clearTimer: (h) => {
+      if (isTimerHandle(h)) globalThis.clearTimeout(h);
+    },
+    now: () => Date.now(),
+  };
+}

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

@@ -29,6 +29,7 @@ function ctxWith(surfaces: Record<string, unknown>): Parameters<typeof mountSurf
     publishMessage: async () => {},
     searchUserTasks: async () => [],
     completeUserTask: async () => {},
+    searchProcessInstances: async () => [],
     registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
     close: async () => {},
   };
@@ -42,6 +43,7 @@ const fakeEngine: EngineClient = {
   publishMessage: async () => {},
   searchUserTasks: async () => [],
   completeUserTask: async () => {},
+  searchProcessInstances: async () => [],
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
   close: async () => {},
 };

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

@@ -30,6 +30,7 @@ class MiniEngine implements EngineClient {
   }
   async searchUserTasks(): Promise<[]> { return []; }
   async completeUserTask(): Promise<void> {}
+  async searchProcessInstances(): Promise<[]> { return []; }
   async registerWorker(jobType: string): Promise<{ jobType: string; unsubscribe(): Promise<void> }> {
     return { jobType, unsubscribe: async () => {} };
   }

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

@@ -9,18 +9,14 @@ import type { HttpRequest } from "../host.ts";
 import { json, normalizeRoutePath, type Route } from "../router.ts";
 import type { Trigger } from "../manifest.ts";
 import { nextCronFire, parseCron } from "./cron.ts";
+import { defaultScheduler, MAX_TIMER_DELAY_MS, type SchedulerDeps } from "./scheduler.ts";
+
+export type { SchedulerDeps };
 
 export interface TriggersHandle extends Mounted {
   routes: Route[];
 }
 
-/** Injectable timer + clock seam so cron scheduling is deterministic under test. */
-export interface SchedulerDeps {
-  setTimer: (fn: () => void, delayMs: number) => unknown;
-  clearTimer: (handle: unknown) => void;
-  /** Current wall-clock time in ms since epoch. */
-  now: () => number;
-}
 
 type Scope = { body: unknown; headers: Record<string, string>; query: Record<string, string> };
 
@@ -149,24 +145,6 @@ export async function runTriggerAction(
 
 const emptyScope: Scope = { body: {}, headers: {}, query: {} };
 
-/** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
-const MAX_TIMER_DELAY_MS = 2_147_483_647;
-
-/** Default (live) scheduler seam, backed by the global timer functions. */
-function defaultScheduler(): SchedulerDeps {
-  return {
-    setTimer: (fn, ms) => globalThis.setTimeout(fn, ms),
-    clearTimer: (h) => {
-      if (isTimerHandle(h)) globalThis.clearTimeout(h);
-    },
-    now: () => Date.now(),
-  };
-}
-
-function isTimerHandle(handle: unknown): handle is ReturnType<typeof setTimeout> {
-  return typeof handle === "number" || (typeof handle === "object" && handle !== null);
-}
-
 /** Mount webhook + cron triggers. Webhooks contribute HTTP routes; cron triggers arm
  *  background timers that fire their action on schedule. `stop()` clears every timer. */
 export function mountTriggers(

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

@@ -15,6 +15,7 @@ class MiniEngine implements EngineClient {
   async publishMessage(): Promise<void> {}
   async searchUserTasks(): Promise<[]> { return []; }
   async completeUserTask(): Promise<void> {}
+  async searchProcessInstances(): Promise<[]> { return []; }
   async close(): Promise<void> {}
   async registerWorker(jobType: string, handler: JobHandler): Promise<WorkerSubscription> {
     this.workers.set(jobType, handler);

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

@@ -7,6 +7,7 @@ import { isRecord } from "../guards.ts";
 import type { EngineJob, JobHandler, WorkerSubscription } from "../host.ts";
 import { workerJobType, type Worker } from "../manifest.ts";
 import { type DecisionEvaluator, type LlmRuntime, runLlmJob } from "./llm.ts";
+import { runInJobContext } from "../execContext.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). */
@@ -142,7 +143,11 @@ export async function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<Wo
         env: (n) => app.env(n),
         evaluateDecision: app.sdk ? sdkDecisionEvaluator(app.sdk) : undefined,
       };
-      const wrapped: JobHandler = (job) => runLlmJob(job.variables, binding, rt);
+      const wrapped: JobHandler = (job) =>
+        runInJobContext(
+          { instanceKey: job.processInstanceKey, elementId: job.elementId, jobType },
+          () => runLlmJob(job.variables, binding, rt),
+        );
       const sub = await ctx.engine.registerWorker(jobType, wrapped, {
         workerName: `${ctx.manifest.id}:${jobType}`,
       });
@@ -159,7 +164,11 @@ export async function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<Wo
           `(expected handlers["${jobType}"], a named export, or a default function)`,
       );
     }
-    const wrapped: JobHandler = (job) => handler(job, app);
+    const wrapped: JobHandler = (job) =>
+      runInJobContext(
+        { instanceKey: job.processInstanceKey, elementId: job.elementId, jobType },
+        () => handler(job, app),
+      );
     const sub = await ctx.engine.registerWorker(jobType, wrapped, {
       workerName: `${ctx.manifest.id}:${jobType}`,
     });

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

@@ -42,6 +42,9 @@ class FakeEngine implements EngineClient {
   async completeUserTask(key: string, variables?: Record<string, unknown>) {
     this.completedTasks.push({ key, variables });
   }
+  async searchProcessInstances() {
+    return [];
+  }
   async registerWorker(jobType: string, handler: JobHandler): Promise<WorkerSubscription> {
     this.workers.set(jobType, handler);
     return { jobType, unsubscribe: async () => void this.workers.delete(jobType) };

package/src/runtime/core/runtime.ts

@@ -12,10 +12,12 @@ import { makeRouter, type Route } from "./router.ts";
 import { deployModels } from "./modules/deploy.ts";
 import type { TemplateSource } from "./modules/templates.ts";
 import { provisionData, DataLayer } from "./modules/datasource.ts";
+import { installExecStore, type JobExecContext } from "./execContext.ts";
 import { mountWorkers } from "./modules/workers.ts";
 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 { mountSecurity, type SecurityPolicy } from "./modules/security.ts";
 
 /** Resolve the HTTP port: explicit option, else $PORT, else 8090. Throws a clear
@@ -52,6 +54,9 @@ export interface MountFlags {
   surfaces?: boolean;
   triggers?: boolean;
   security?: boolean;
+  /** The `instanceTracking` reconciler poll loop. Shares no HTTP surface; safe to disable
+   *  in hosts that only render surfaces (e.g. the console preview). */
+  instanceTracking?: boolean;
 }
 
 export interface CreateUrbanAppOptions {
@@ -104,9 +109,15 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
     surfaces: opts.mount?.surfaces ?? true,
     triggers: opts.mount?.triggers ?? true,
     security: opts.mount?.security ?? true,
+    instanceTracking: opts.mount?.instanceTracking ?? true,
   };
   const ctx = { manifest, host, engine, root, templates: opts.templates };
 
+  // Install the ambient job-execution store once per process (idempotent) so worker dispatch can
+  // stamp write-provenance onto DataLayer inserts. Absent-safe: a host without `createAsyncStore`
+  // leaves provenance capture disabled.
+  installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+
   let data: DataLayer | undefined;
   let security: SecurityPolicy | undefined;
   let server: HttpServer | undefined;
@@ -204,6 +215,11 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
           mounted.push(t);
           describe.triggers = t.describe?.();
         }
+        if (flags.instanceTracking && (manifest.instanceTracking?.length ?? 0) > 0) {
+          const it = mountInstanceTracking(ctx, api);
+          mounted.push(it);
+          describe.instanceTracking = it.describe?.();
+        }
         if (security) describe.security = security.describe();
         if (data) describe.data = data.describe();