@nanobpm/urban 0.27.0 → 0.29.0

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

@@ -34,7 +34,7 @@ export function createPagesRoutes(opts, deps) {
     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
     // refreshes grids repeatedly — re-introspecting on every `/app/data` hit would be a hot
@@ -75,6 +75,36 @@ export function createPagesRoutes(opts, deps) {
         source: "surface:pages",
         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 = [];
+            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",
@@ -297,6 +327,13 @@ export function mountPages(ctx, app) {
         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 {
@@ -400,6 +437,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
 // /app/runtime.js — it does NOT ship Craft.js (authoring is console-side only). It
@@ -409,6 +462,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
@@ -857,15 +941,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,
@@ -920,7 +1060,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;
@@ -937,16 +1077,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/dist/runtime/core/modules/scheduler.d.ts

@@ -0,0 +1,11 @@
+/** 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 declare const MAX_TIMER_DELAY_MS = 2147483647;
+/** Default (live) scheduler seam, backed by the global timer functions. */
+export declare function defaultScheduler(): SchedulerDeps;

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

@@ -0,0 +1,21 @@
+// 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.
+/** 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) {
+    return typeof handle === "number" || (typeof handle === "object" && handle !== null);
+}
+/** Default (live) scheduler seam, backed by the global timer functions. */
+export function defaultScheduler() {
+    return {
+        setTimer: (fn, ms) => globalThis.setTimeout(fn, ms),
+        clearTimer: (h) => {
+            if (isTimerHandle(h))
+                globalThis.clearTimeout(h);
+        },
+        now: () => Date.now(),
+    };
+}

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

@@ -1,15 +1,10 @@
 import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
 import { type Route } from "../router.ts";
+import { 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>;
@@ -58,4 +53,3 @@ export declare function runTriggerAction(app: AppApi, action: RuntimeTriggerActi
 /** Mount webhook + cron triggers. Webhooks contribute HTTP routes; cron triggers arm
  *  background timers that fire their action on schedule. `stop()` clears every timer. */
 export declare function mountTriggers(ctx: RuntimeContext, app: AppApi, sched?: SchedulerDeps): TriggersHandle;
-export {};

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

@@ -5,6 +5,7 @@
 import { isRecord } from "../guards.js";
 import { json, normalizeRoutePath } from "../router.js";
 import { nextCronFire, parseCron } from "./cron.js";
+import { defaultScheduler, MAX_TIMER_DELAY_MS } from "./scheduler.js";
 /**
  * Resolve a tiny FEEL-ish expression against the event scope: a `= body.a.b` path walk
  * returns the raw value at that path (or `undefined` if any segment is missing); a literal
@@ -92,22 +93,6 @@ export async function runTriggerAction(app, action, scope) {
     return { kind: "none" };
 }
 const emptyScope = { 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() {
-    return {
-        setTimer: (fn, ms) => globalThis.setTimeout(fn, ms),
-        clearTimer: (h) => {
-            if (isTimerHandle(h))
-                globalThis.clearTimeout(h);
-        },
-        now: () => Date.now(),
-    };
-}
-function isTimerHandle(handle) {
-    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(ctx, app, sched = defaultScheduler()) {

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

@@ -4,6 +4,7 @@
 import { isRecord } from "../guards.js";
 import { workerJobType } from "../manifest.js";
 import { runLlmJob } from "./llm.js";
+import { runInJobContext } from "../execContext.js";
 /** Adapt an engine SDK client into the LLM module's `DecisionEvaluator`, parsing the
  *  decision's JSON-string `output` into the value fed back to the LLM job. Validates the
  *  SDK shape and adds decision context to a parse failure rather than surfacing a raw
@@ -98,7 +99,7 @@ export async function mountWorkers(ctx, app) {
                 env: (n) => app.env(n),
                 evaluateDecision: app.sdk ? sdkDecisionEvaluator(app.sdk) : undefined,
             };
-            const wrapped = (job) => runLlmJob(job.variables, binding, rt);
+            const wrapped = (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}`,
             });
@@ -113,7 +114,7 @@ export async function mountWorkers(ctx, app) {
             throw new Error(`worker "${jobType}": ${decl.handler} exports no handler for it ` +
                 `(expected handlers["${jobType}"], a named export, or a default function)`);
         }
-        const wrapped = (job) => handler(job, app);
+        const wrapped = (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/dist/runtime/core/runtime.d.ts

@@ -13,6 +13,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 {
     host: HostContext;

package/dist/runtime/core/runtime.js

@@ -7,10 +7,12 @@ import { validateManifest } from "./validate.js";
 import { makeRouter } from "./router.js";
 import { deployModels } from "./modules/deploy.js";
 import { provisionData, DataLayer } from "./modules/datasource.js";
+import { installExecStore } from "./execContext.js";
 import { mountWorkers } from "./modules/workers.js";
 import { mountConnectors } from "./modules/connectors.js";
 import { mountSurfaces } from "./modules/surfaces.js";
 import { mountTriggers } from "./modules/triggers.js";
+import { mountInstanceTracking } from "./modules/instance-tracking.js";
 import { mountSecurity } from "./modules/security.js";
 /** Resolve the HTTP port: explicit option, else $PORT, else 8090. Throws a clear
  * error when $PORT is set but not a valid integer in 0..65535. */
@@ -43,8 +45,13 @@ export async function createUrbanApp(opts) {
         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?.());
     let data;
     let security;
     let server;
@@ -144,6 +151,11 @@ export async function createUrbanApp(opts) {
                     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)

package/dist/runtime/core/validate.js

@@ -131,6 +131,44 @@ export function collectManifestIssues(m) {
                 issues.push({ path: `triggers[${i}].type`, message: "missing type" });
         });
     }
+    // instanceTracking: each binding must name the table + key column it tracks and a
+    // non-empty `onTerminated.set` patch — a reconciler with nothing to write is inert
+    // and almost certainly a mistake. `activeStatuses` without `statusField` is incoherent
+    // (no column to read the statuses from), so the runtime would silently poll every row.
+    const tracking = Array.isArray(obj.instanceTracking) ? obj.instanceTracking : undefined;
+    if (tracking) {
+        tracking.forEach((t, i) => {
+            const b = isRecord(t) ? t : undefined;
+            if (typeof b?.table !== "string" || b.table.length === 0) {
+                issues.push({ path: `instanceTracking[${i}].table`, message: "missing table" });
+            }
+            if (typeof b?.keyField !== "string" || b.keyField.length === 0) {
+                issues.push({ path: `instanceTracking[${i}].keyField`, message: "missing keyField" });
+            }
+            const onTerminated = isRecord(b?.onTerminated) ? b.onTerminated : undefined;
+            const set = isRecord(onTerminated?.set) ? onTerminated.set : undefined;
+            if (!set || Object.keys(set).length === 0) {
+                issues.push({
+                    path: `instanceTracking[${i}].onTerminated.set`,
+                    message: "missing onTerminated.set patch (a non-empty column → value map)",
+                });
+            }
+            if (Array.isArray(b?.activeStatuses) && (typeof b?.statusField !== "string" || b.statusField.length === 0)) {
+                issues.push({
+                    path: `instanceTracking[${i}].activeStatuses`,
+                    message: "activeStatuses requires statusField",
+                });
+            }
+            // `pollMs`, when set, schedules a self-rescheduling timer; a non-number/NaN/non-positive
+            // value would become a 0-delay hot loop at runtime, so reject it at author time.
+            if (b?.pollMs !== undefined && (typeof b.pollMs !== "number" || !Number.isFinite(b.pollMs) || b.pollMs <= 0)) {
+                issues.push({
+                    path: `instanceTracking[${i}].pollMs`,
+                    message: "pollMs must be a finite positive number of milliseconds",
+                });
+            }
+        });
+    }
     return issues;
 }
 export function assertValidManifest(m) {

package/dist/runtime/engine/nanosdk.d.ts

@@ -1,8 +1,13 @@
-import type { EngineClient, JobHandler, WorkerSubscription } from "../core/host.ts";
+import type { EngineClient, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, WorkerSubscription } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
 export declare function requireProcessInstanceKey(key: string | number | null | undefined): string;
+/** Map the engine's process-instance `state` onto the transport-agnostic
+ *  {@link ProcessInstanceState} union, or `undefined` for an unrecognized value
+ *  (which the caller skips rather than mis-reconciling). Case-insensitive so a
+ *  future casing tweak on the engine side doesn't silently drop instances. */
+export declare function normalizeProcessInstanceState(raw: unknown): ProcessInstanceState | undefined;
 /** A job as delivered to a nano-sdk job handler: the frame fields plus the
  *  acknowledgement actions the handler must call. */
 export interface NanoSdkActivatedJob {
@@ -76,6 +81,10 @@ export interface NanoSdkClient {
         userTaskKey: string;
         variables?: Record<string, unknown>;
     }, options?: unknown): Promise<unknown>;
+    searchProcessInstances(input: {
+        filter?: Record<string, unknown>;
+        page?: Record<string, unknown>;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
     createJobWorker(cfg: NanoSdkJobWorkerConfig): NanoSdkJobWorker;
     /** Stop every worker created on this client. Used on teardown to also drain a
      * REST-fallback worker, whose handle the `createJobWorker` proxy starts internally
@@ -134,6 +143,10 @@ export declare class SdkEngineClient implements EngineClient {
         variables?: Record<string, unknown>;
     }[]>;
     completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void>;
+    searchProcessInstances(filter?: {
+        processInstanceKeys?: string[];
+        state?: ProcessInstanceState;
+    }): Promise<ProcessInstanceSnapshot[]>;
     registerWorker(jobType: string, handler: JobHandler, options?: {
         workerName?: string;
         maxParallelJobs?: number;

package/dist/runtime/engine/nanosdk.js

@@ -28,6 +28,24 @@ export function requireProcessInstanceKey(key) {
     }
     return String(key);
 }
+/** Map the engine's process-instance `state` onto the transport-agnostic
+ *  {@link ProcessInstanceState} union, or `undefined` for an unrecognized value
+ *  (which the caller skips rather than mis-reconciling). Case-insensitive so a
+ *  future casing tweak on the engine side doesn't silently drop instances. */
+export function normalizeProcessInstanceState(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    switch (raw.toUpperCase()) {
+        case "ACTIVE":
+            return "ACTIVE";
+        case "COMPLETED":
+            return "COMPLETED";
+        case "TERMINATED":
+            return "TERMINATED";
+        default:
+            return undefined;
+    }
+}
 /**
  * An `EngineClient` backed entirely by a `@nanobpm/nano-sdk` client. Deploy, create,
  * message, and user-task calls map one-to-one onto the SDK's client methods; workers
@@ -101,6 +119,37 @@ export class SdkEngineClient {
     async completeUserTask(userTaskKey, variables) {
         await this.client.completeUserTask({ userTaskKey, variables: variables ?? {} });
     }
+    async searchProcessInstances(filter) {
+        const f = {};
+        if (filter?.state)
+            f.state = filter.state;
+        const keys = filter?.processInstanceKeys?.filter((k) => k != null && k !== "");
+        if (keys && keys.length > 0)
+            f.processInstanceKey = { $in: keys };
+        // A process-instance search is an eventually consistent read; ask for zero-wait
+        // consistency so it reflects what is currently visible without blocking. Cap the page
+        // to the number of keys asked for (each key matches at most one instance), so a bounded
+        // reconcile query never silently truncates on the API's default page size.
+        const page = keys && keys.length > 0 ? { limit: keys.length } : undefined;
+        const body = await this.client.searchProcessInstances({ filter: f, ...(page ? { page } : {}) }, { consistency: { waitUpToMs: 0 } });
+        const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
+        return items.flatMap((it) => {
+            const key = it.processInstanceKey;
+            if (key == null || key === "") {
+                this.log("warn", "skipping process instance with no key in engine response");
+                return [];
+            }
+            const state = normalizeProcessInstanceState(it.state);
+            if (!state) {
+                this.log("warn", "skipping process instance with unrecognized state", {
+                    processInstanceKey: String(key),
+                    state: String(it.state),
+                });
+                return [];
+            }
+            return [{ processInstanceKey: String(key), state }];
+        });
+    }
     async registerWorker(jobType, handler, options) {
         const worker = this.client.createJobWorker({
             jobType,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
   "license": "Apache-2.0",
   "type": "module",
@@ -62,7 +62,7 @@
     "test:deno": "deno test -A --no-check src/"
   },
   "dependencies": {
-    "@nanobpm/nano-app-schema": "^0.3.0",
+    "@nanobpm/nano-app-schema": "^0.4.0",
     "@nanobpm/nano-sdk": "^1.2.3",
     "@nanobpm/workflow": "^0.8.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2",

package/src/runtime/adapters/deno.ts

@@ -6,7 +6,9 @@
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
+import { AsyncLocalStorage } from "node:async_hooks";
 import type {
+  AsyncStore,
   HostContext,
   HttpHandler,
   HttpRequest,
@@ -134,6 +136,10 @@ export function createDenoHost(opts: DenoHostOptions = {}): HostContext {
       };
     },
     now: () => Date.now(),
+    createAsyncStore<T>(): AsyncStore<T> {
+      const als = new AsyncLocalStorage<T>();
+      return { run: <R>(value: T, fn: () => R): R => als.run(value, fn), current: () => als.getStore() };
+    },
     log,
   };
 }

package/src/runtime/adapters/node.ts

@@ -9,7 +9,9 @@ import { register } from "node:module";
 import { isAbsolute, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
+import { AsyncLocalStorage } from "node:async_hooks";
 import type {
+  AsyncStore,
   HostContext,
   HttpHandler,
   HttpRequest,
@@ -176,6 +178,10 @@ export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
       return { close: () => w.close() } satisfies WatchHandle;
     },
     now: () => Date.now(),
+    createAsyncStore<T>(): AsyncStore<T> {
+      const als = new AsyncLocalStorage<T>();
+      return { run: <R>(value: T, fn: () => R): R => als.run(value, fn), current: () => als.getStore() };
+    },
     log,
   };
 }