@nanobpm/urban 0.94.2 → 0.96.0

package/dist/runtime/adapters/deno.js

@@ -94,6 +94,36 @@ export function createDenoHost(opts = {}) {
                 return false;
             }
         },
+        async statFile(p) {
+            // Classify with a bare `stat` FIRST, then only open a *regular file* to confirm it is
+            // readable. The order matters: a read-only open of a FIFO (named pipe) blocks indefinitely
+            // waiting for a writer, so opening before the type check would hang every shell request on
+            // a FIFO sitting at this conventional asset path. A plain `stat` never blocks, so it safely
+            // rejects non-regular entries (directory, FIFO, socket, device) up front. The subsequent
+            // open/stat still answers the real serving condition — a file `stat` reports as regular can
+            // be unreadable (ACLs / permissions), and the shell must not link an asset that then 404s.
+            // Missing path → `null`; non-regular → `isFile: false`; unreadable → `null`.
+            try {
+                const meta = await Deno.stat(abs(p));
+                if (!meta.isFile)
+                    return { isFile: false };
+            }
+            catch {
+                return null;
+            }
+            let file;
+            try {
+                file = await Deno.open(abs(p), { read: true });
+                const s = await file.stat();
+                return { isFile: s.isFile };
+            }
+            catch {
+                return null;
+            }
+            finally {
+                file?.close();
+            }
+        },
         openSqlite(path) {
             const db = new DatabaseSync(abs(path));
             return wrapSqlite(db);

package/dist/runtime/adapters/node.js

@@ -8,7 +8,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import { readFile, readdir, stat } from "node:fs/promises";
+import { open, readFile, readdir, stat } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { watch as fsWatch } from "node:fs";
 import { createServer } from "node:http";
@@ -133,6 +133,36 @@ export function createNodeHost(opts = {}) {
                 return false;
             }
         },
+        async statFile(p) {
+            // Classify with a bare `stat` FIRST, then only open a *regular file* to confirm it is
+            // readable. The order matters: a read-only open of a FIFO (named pipe) blocks indefinitely
+            // waiting for a writer, so opening before the type check would hang every shell request on
+            // a FIFO sitting at this conventional asset path. A plain `stat` never blocks, so it safely
+            // rejects non-regular entries (directory, FIFO, socket, device) up front. The subsequent
+            // handle open/stat still answers the real serving condition — a file `stat` reports as
+            // regular can be unreadable (ACLs / permissions), and the shell must not link an asset that
+            // then 404s. Missing path → `null`; non-regular → `isFile: false`; unreadable → `null`.
+            try {
+                const meta = await stat(abs(p));
+                if (!meta.isFile())
+                    return { isFile: false };
+            }
+            catch {
+                return null;
+            }
+            let handle;
+            try {
+                handle = await open(abs(p), "r");
+                const s = await handle.stat();
+                return { isFile: s.isFile() };
+            }
+            catch {
+                return null;
+            }
+            finally {
+                await handle?.close();
+            }
+        },
         openSqlite(path) {
             const db = new DatabaseSync(abs(path));
             return wrapNodeSqlite(db);

package/dist/runtime/core/host.d.ts

@@ -80,6 +80,27 @@ export interface HostContext {
     listSubdirs?(dir: string): Promise<string[]>;
     /** True if the path exists (file or directory). */
     exists(path: string): Promise<boolean>;
+    /**
+     * Probe a path as a READABLE REGULAR FILE without reading its bytes: `{ isFile }` when it
+     * can be opened for reading, or `null` when it is absent or unreadable. The pages surface
+     * uses this to probe the app-owned `app.css`/`app.js` convention on the per-request shell
+     * hot path: `exists` is too broad (true for a DIRECTORY, which the shell would then link and
+     * the browser would 404 on), and probing via `readTextFile` reads and allocates a
+     * potentially large file just to answer "is it there?". A bare metadata `stat` is not
+     * enough either — it can succeed for a regular file that `readTextFile` cannot open (ACLs /
+     * permissions), so the shell would link an asset that then 404s on serving. Implementations
+     * therefore OPEN the file for reading (consuming no bytes) and stat the open handle, so this
+     * answers the same success condition as serving.
+     *
+     * OPTIONAL: `HostContext` is a public, externally-implementable seam (re-exported from
+     * `runtime/index.ts`, documented in the README as a supported custom-host extension point),
+     * so a new required member would be source-breaking. The pages surface falls back to a
+     * read-based probe when a host does not provide it; the built-in adapters do, as an
+     * allocation-free optimization on the hot path.
+     */
+    statFile?(path: string): Promise<{
+        isFile: boolean;
+    } | null>;
     /** Open (creating if needed) a SQLite database at a filesystem path. */
     openSqlite(path: string): SqliteDb;
     /**
@@ -195,14 +216,33 @@ export type ProcessInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED";
  * never surface in the `taskInbox` as if it were actionable.
  */
 export type UserTaskState = "CREATED" | "COMPLETED" | "CANCELED" | "FAILED";
-/** A single process instance's lifecycle snapshot returned by {@link EngineClient.searchProcessInstances}. */
-export interface ProcessInstanceSnapshot {
-    readonly processInstanceKey: string;
-    readonly state: ProcessInstanceState;
+/**
+ * Which deployed process definition an instance runs — shared by the instance a
+ * {@link EngineClient.createInstance} starts and the {@link ProcessInstanceSnapshot} a
+ * {@link EngineClient.searchProcessInstances} reports, so the two describe the same instance
+ * identically. Each field is absent when the engine omits it (or reports it blank/malformed).
+ */
+export interface ProcessDefinitionIdentity {
     /** The key of the deployed process definition this instance runs — the handle a caller feeds to
      *  {@link EngineClient.getProcessDefinitionXml} to fetch the deployed BPMN (the instance →
-     *  `processDefinitionKey` → deployed XML path, no repo checkout). Absent when the engine omits it. */
+     *  `processDefinitionKey` → deployed XML path, no repo checkout). Unique per deployed version. */
     readonly processDefinitionKey?: string;
+    /** The BPMN process id (`<bpmn:process id>`) — stable across versions; the selector
+     *  {@link EngineClient.searchProcessInstances} accepts as `processDefinitionId`. */
+    readonly processDefinitionId?: string;
+    /** The deployed version of `processDefinitionId` this instance runs (1-based). */
+    readonly processDefinitionVersion?: number;
+}
+/** The instance {@link EngineClient.createInstance} started: its key, the exact deployed
+ *  definition version it runs, and — when `awaitCompletion` was requested — its final variables. */
+export interface CreatedProcessInstance extends ProcessDefinitionIdentity {
+    readonly processInstanceKey: string;
+    readonly variables?: Record<string, unknown>;
+}
+/** A single process instance's lifecycle snapshot returned by {@link EngineClient.searchProcessInstances}. */
+export interface ProcessInstanceSnapshot extends ProcessDefinitionIdentity {
+    readonly processInstanceKey: string;
+    readonly state: ProcessInstanceState;
     /** The key of this instance's *immediate* parent process instance — the caller that instantiated
      *  it as a native child (a `<bpmn:callActivity>`). `undefined` for a top-level (root) instance,
      *  and absent when the engine omits it (same optional/engine-provided convention as
@@ -643,15 +683,14 @@ export interface EngineClient {
     }[]): Promise<{
         deployed: number;
     }>;
-    /** Start a process instance. */
+    /** Start a process instance of the latest deployed version of `processDefinitionId`. Returns
+     *  the new instance's key plus the {@link ProcessDefinitionIdentity} (key, id, version) of the
+     *  definition it actually runs. */
     createInstance(input: {
         processDefinitionId: string;
         variables?: Record<string, unknown>;
         awaitCompletion?: boolean;
-    }): Promise<{
-        processInstanceKey: string;
-        variables?: Record<string, unknown>;
-    }>;
+    }): Promise<CreatedProcessInstance>;
     /** Cancel a running process instance (the pages surface's row-cancel action). */
     cancelInstance(input: {
         processInstanceKey: string;
@@ -704,7 +743,8 @@ export interface EngineClient {
     /** Complete a user task. */
     completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void>;
     /**
-     * Search process instances by key and/or lifecycle state. The instance-tracking
+     * Search process instances by key, BPMN process id (`processDefinitionId`, any version),
+     * and/or lifecycle state. The instance-tracking
      * reconciler uses this to detect a tracked instance reaching a terminal state
      * (`TERMINATED`/`COMPLETED`) even though no completion worker ran for it — the
      * read-model row it backs would otherwise stay "active" forever. An eventually
@@ -714,6 +754,9 @@ export interface EngineClient {
     searchProcessInstances(filter?: {
         processInstanceKeys?: string[];
         state?: ProcessInstanceState;
+        /** Select only instances of this BPMN process id (every deployed version). A blank or
+         *  whitespace-only value is treated as absent (no filter). */
+        processDefinitionId?: string;
         /** Select only instances whose *immediate* parent is this process instance — the reduced-path
          *  query for "the native children spawned by this subject". */
         parentProcessInstanceKey?: string;

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

@@ -428,11 +428,12 @@ function buildDebugTools(app) {
     return [
         {
             name: `${DEBUG_PREFIX}search_process_instances`,
-            description: "Engine truth: search process instances by key and/or lifecycle state.",
+            description: "Engine truth: search process instances by key, BPMN process id (processDefinitionId, any version), and/or lifecycle state.",
             inputSchema: {
                 type: "object",
                 properties: {
                     processInstanceKeys: { type: "array", items: OPTIONAL_STRING },
+                    processDefinitionId: OPTIONAL_STRING,
                     state: { type: "string", enum: ["ACTIVE", "COMPLETED", "TERMINATED"] },
                 },
             },
@@ -444,6 +445,9 @@ function buildDebugTools(app) {
                 const state = readProcessInstanceState(args, "state");
                 if (state)
                     filter.state = state;
+                const processDefinitionId = readPresentString(args, "processDefinitionId");
+                if (processDefinitionId)
+                    filter.processDefinitionId = processDefinitionId;
                 return app.engine.searchProcessInstances(filter);
             },
         },

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

@@ -50,6 +50,21 @@ export interface PagesDeps {
      * Injectable for tests. Rejects (→ 404) when the file is missing.
      */
     readAsset?(path: string): Promise<string>;
+    /**
+     * Probe whether a static asset exists as a READABLE REGULAR FILE at an app-root-relative
+     * path, WITHOUT reading its bytes. The per-request shell build uses this for the app-owned
+     * `app.css`/`app.js` convention (#578): those files can be large and the shell is revalidated
+     * on every load, so probing via a full `readAsset` would put an avoidable read + allocation
+     * on the HTML hot path (and read the file twice — once here, once when the browser fetches
+     * it). Must answer the same question the `readAsset` fallback answers — "would serving this
+     * path succeed?" — so a directory (or unreadable entry) at the path is a NO. `mountPages`
+     * wires this to the optional `HostContext.statFile` (which opens the file for reading to
+     * confirm a readable regular file — never `HostContext.exists`, which is true for directories
+     * too, and a `pages/app.css/` DIRECTORY would link an asset the browser then 404s on).
+     * Optional; falls back to a read-based probe when absent.
+     * Injectable for tests.
+     */
+    existsAsset?(path: string): Promise<boolean>;
     /**
      * List the available page ids (the `*.page.json` basenames under `pagesDir`),
      * powering the `/app/pages` index endpoint and a `nav` node's `items: "auto"`.
@@ -64,6 +79,7 @@ export interface PagesDeps {
      */
     cancel?(processInstanceKey: string): Promise<CancelInstanceResult>;
 }
+export declare const APP_ASSETS: readonly ["app.css", "app.js"];
 /**
  * Build the page-runtime routes over an injected datasource + engine. Pure over its deps
  * so it is unit-testable without a real host/server (see pages.test.ts).
@@ -80,3 +96,4 @@ export interface PagesHandle {
  * Returns no routes when the surface is disabled or absent.
  */
 export declare function mountPages(ctx: RuntimeContext, app: AppApi): PagesHandle;
+export declare const RUNTIME_JS_PATH: string;

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

@@ -46,6 +46,12 @@ function javascript(body, status = 200, extraHeaders) {
         body,
     };
 }
+// App-owned shell customisation by convention (nano-ide#578): an app MAY ship `pagesDir/app.css`
+// (linked AFTER the built-in renderer CSS, so its rules win — themes, restyling) and/or
+// `pagesDir/app.js` (an ES module loaded after the runtime — e.g. a theme picker). Each is served
+// as a root sidecar and referenced from the shell ONLY when the file exists, so apps without them
+// see no change and no 404.
+export const APP_ASSETS = ["app.css", "app.js"];
 // The `appView` sidecar documents an app ships alongside its `*.page.json` under
 // `pagesDir` (ADR 0057 / #416 / #420). The renderer (#419) mounts an <iframe> whose
 // src is the node's base-relative `embed` (`./embed.html`), which — resolved against
@@ -58,7 +64,7 @@ function javascript(body, status = 200, extraHeaders) {
 // `./board/embed.html`, …) — those are served by the nested prefix route below (#442);
 // this flat set stays as the single-appView back-compat case (#420). The `dist/` tree the
 // import-map references is served separately under the `/dist/` prefix below.
-const SIDECAR_ASSETS = ["embed.html", "standalone.html", "mount.js", "cockpit.css"];
+const SIDECAR_ASSETS = ["embed.html", "standalone.html", "mount.js", "cockpit.css", ...APP_ASSETS];
 // The app `dist/` directory (app-root sibling of the pages dir) the sidecar import-maps
 // resolve `../dist/…` onto. Because the embed is served at the mount root, `../dist`
 // resolves to `/dist` regardless of `pagesDir`, so the URL→disk mapping is fixed.
@@ -151,6 +157,9 @@ export function createPagesRoutes(opts, deps) {
     // Falls back to `readPage` when no dedicated reader is injected — both delegate to the same
     // `host.readTextFile`, so there is one source of file bytes, not two.
     const readAsset = deps.readAsset ?? readPage;
+    // Existence probe for the app-owned shell assets (#578): a dedicated `existsAsset` when the
+    // host offers one (a metadata stat — no file bytes cross the seam), else a read-based probe.
+    const existsAsset = deps.existsAsset ?? ((path) => readAsset(path).then(() => true, () => false));
     // 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
@@ -181,15 +190,24 @@ export function createPagesRoutes(opts, deps) {
         return p;
     };
     const routes = [];
-    const shell = html(rendererShell(homePage, opts.apiDocsPath, opts.gridLayout ?? "auto"));
     // The shell must never be pinned by the browser: it carries the *current* fingerprinted
     // runtime URL, so a stale shell would keep pointing at an old module hash. `no-cache` forces
     // a revalidation on every load; the shell body is tiny, and the expensive module it references
     // is what gets the long-lived immutable caching (via its content-hashed URL).
-    shell.headers = { ...shell.headers, "cache-control": "no-cache" };
+    // Built per request: it probes for the app-owned `app.css`/`app.js` (#578) so adding or removing
+    // one takes effect without a restart.
+    const shell = async () => {
+        const [appCss, appJs] = await Promise.all([
+            existsAsset(`${pagesDir}/app.css`),
+            existsAsset(`${pagesDir}/app.js`),
+        ]);
+        const res = html(rendererShell(homePage, opts.apiDocsPath, opts.gridLayout ?? "auto", { appCss, appJs }));
+        res.headers = { ...res.headers, "cache-control": "no-cache" };
+        return res;
+    };
     // ── the renderer shell + module ─────────────────────────────────────────
-    routes.push({ method: "GET", path: "/", source: "surface:pages", handler: () => shell });
-    routes.push({ method: "GET", path: "/index.html", source: "surface:pages", handler: () => shell });
+    routes.push({ method: "GET", path: "/", source: "surface:pages", handler: shell });
+    routes.push({ method: "GET", path: "/index.html", source: "surface:pages", handler: shell });
     // The fingerprinted module URL (referenced by the shell): unique per content, so cache it hard.
     routes.push({
         method: "GET",
@@ -216,11 +234,22 @@ export function createPagesRoutes(opts, deps) {
     // onto `pagesDir/<name>` (exact routes — never a root catch-all, which would shadow the
     // `/healthz` liveness route the runtime appends after the pages surface).
     for (const name of SIDECAR_ASSETS) {
+        // The app-owned `app.css`/`app.js` are MUTABLE at stable URLs — the whole point of the
+        // convention is that an edit (or a remove/re-add) takes effect without a restart, and the
+        // shell re-probes on every load. Serve them `no-cache` (like `/app/runtime.js`) so a
+        // browser/intermediary must revalidate instead of replaying a heuristically-cached 200/404.
+        // The other sidecars are deploy-time fixtures, so they keep the generic response.
+        const mutable = APP_ASSETS.some((a) => a === name);
         routes.push({
             method: "GET",
             path: `/${name}`,
             source: "surface:pages",
-            handler: () => serveAsset(readAsset, `${pagesDir}/${name}`),
+            handler: async () => {
+                const res = await serveAsset(readAsset, `${pagesDir}/${name}`);
+                if (mutable)
+                    res.headers = { ...res.headers, "cache-control": "no-cache" };
+                return res;
+            },
         });
     }
     // The `dist/` tree the sidecars' import-maps reference (`../dist/cockpit/index.js` →
@@ -580,12 +609,24 @@ export function mountPages(ctx, app) {
     };
     const sourceName = opts.sourceName ?? "app";
     const bindings = ctx.manifest.instanceTracking ?? [];
+    // Probe "would serving this app-owned asset succeed?" — a READABLE REGULAR FILE, not the
+    // broader `HostContext.exists` (which is true for directories too, and a `pages/app.css/`
+    // DIRECTORY would link an asset the browser then 404s on). `statFile` is an OPTIONAL public
+    // host capability (a custom host need not implement it), and it opens the file for reading so
+    // no bytes cross the seam on the per-request shell hot path. Only wire the optimized probe
+    // when the host provides it; otherwise `createPagesRoutes` falls back to a read-based probe
+    // that answers the identical question.
+    const statFile = ctx.host.statFile?.bind(ctx.host);
+    const existsAsset = statFile
+        ? async (p) => (await statFile(p))?.isFile === true
+        : undefined;
     const routes = createPagesRoutes(opts, {
         db: app.data.open(sourceName),
         engine: app.engine,
         cancel: (key) => cancelInstanceReconciling(app, bindings, key),
         readPage: (p) => ctx.host.readTextFile(p),
         readAsset: (p) => ctx.host.readTextFile(p),
+        existsAsset,
         listPages: async () => {
             const dir = opts.pagesDir ?? "pages";
             const names = await ctx.host.listDir(dir).catch(() => []);
@@ -604,7 +645,7 @@ export function mountPages(ctx, app) {
 function escapeAttr(s) {
     return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
-function rendererShell(homePage, apiDocsPath, gridLayout) {
+function rendererShell(homePage, apiDocsPath, gridLayout, app = { appCss: false, appJs: false }) {
     // A persistent "API docs" badge (spec-first apps get their Swagger UI linked from their own
     // UI for free). `target="_blank"` + hardened `rel` so the docs open without giving the docs
     // tab a handle back to this window (reverse-tabnabbing).
@@ -628,12 +669,12 @@ function rendererShell(homePage, apiDocsPath, gridLayout) {
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>Urban App</title>
-  <style>${RENDERER_CSS}</style>
+  <style>${RENDERER_CSS}</style>${app.appCss ? '\n  <link rel="stylesheet" href="./app.css" />' : ""}
 </head>
 <body data-grid-layout="${gridLayout}">${apiDocsBadge}
   <main id="page" data-home="${escapeAttr(homePage)}"><p class="pc-empty">Loading…</p></main>
   <script>${FORMJS_JS}</script>
-  <script type="module" src=".${RUNTIME_JS_PATH}"></script>
+  <script type="module" src=".${RUNTIME_JS_PATH}"></script>${app.appJs ? '\n  <script type="module" src="./app.js"></script>' : ""}
 </body>
 </html>`;
 }
@@ -1015,5 +1056,8 @@ function fnv1aHex(s) {
 // other page action) do nothing after an upgrade until a hard refresh. Because the URL is unique
 // per content, the response itself is served `immutable` with a one-year max-age.
 const RUNTIME_JS_HASH = fnv1aHex(RENDERER_JS);
-const RUNTIME_JS_PATH = `/app/runtime.${RUNTIME_JS_HASH}.js`;
+// Exported so tests can locate the actual fingerprinted runtime <script> tag in the shell
+// (asserting against the bare word "runtime" is unsound — it also appears in the embedded
+// renderer CSS, so such a test passes even if the app script were moved before the runtime).
+export const RUNTIME_JS_PATH = `/app/runtime.${RUNTIME_JS_HASH}.js`;
 const IMMUTABLE_CACHE = "public, max-age=31536000, immutable";

package/dist/runtime/core/process-identity.d.ts

@@ -0,0 +1,21 @@
+import type { ProcessDefinitionIdentity } from "./host.ts";
+export type { ProcessDefinitionIdentity };
+/** A non-empty string form of an engine key/id, or `undefined` when absent/blank (including a
+ *  whitespace-only string). Coerces a *finite* numeric key to a string (the engine may serialize a
+ *  key either way) but never `String(...)`-coerces an arbitrary object into a garbage
+ *  `"[object Object]"` id, nor a non-finite number into `"NaN"`/`"Infinity"`. The blank check trims,
+ *  matching the read-path blank-key guards, so a `"   "` key can never leak into a result. */
+export declare function presentEngineKey(value: unknown): string | undefined;
+/** A present string-only identifier (e.g. a BPMN process id) under the shared trim rule; a
+ *  non-string is absent and never `String(...)`-coerced. */
+export declare function presentString(value: unknown): string | undefined;
+/** The {@link ProcessDefinitionIdentity} an engine row (a create response or a process-instance
+ *  search row) reports — the single mapping both `createInstance` and `searchProcessInstances` use,
+ *  so a created instance and its later snapshot describe the same definition identically. Each field
+ *  passes the shared presence rule; a version that is not a positive integer number is omitted
+ *  (never coerced). */
+export declare function pickProcessDefinitionIdentity(row: {
+    processDefinitionKey?: unknown;
+    processDefinitionId?: unknown;
+    processDefinitionVersion?: unknown;
+}): ProcessDefinitionIdentity;

package/dist/runtime/core/process-identity.js

@@ -0,0 +1,56 @@
+// The single, transport-agnostic normalizer for a {@link ProcessDefinitionIdentity}. Both engine
+// adapters — the live SDK/REST adapter (`engine/nanosdk.ts`, `SdkEngineClient`) and the in-process
+// WASM test adapter (`@nanobpm/urban-testkit`, `WasmEngineClient`) — report which deployed
+// definition an instance runs on *both* `createInstance` and `searchProcessInstances`. Each used to
+// carry its own hand-mirrored `pickProcessDefinitionIdentity` (plus a re-declared identity type), so
+// the two could silently diverge the moment identity validation changed — exactly the drift class
+// the shared form-contract normalizer exists to kill (`./form-contract.ts`, issue #252). Centralizing
+// the mapper (and reusing the canonical {@link ProcessDefinitionIdentity}) here removes that surface:
+// a created instance and its later snapshot describe the same definition identically wherever this
+// normalizer runs, because they run the *same* code.
+//
+// Ownership today: only the SDK adapter runs this implementation. `WasmEngineClient` still defines
+// and calls its own behaviourally identical copy (`urban-testkit/src/wasm-engine.ts`) — a deliberate,
+// temporary fork: this module is introduced by the same change, so it exists in no published urban
+// release, and a value import would force the testkit's peer floor up to an urban version that does
+// not yet exist (AGENTS.md: depend on an unreleased sibling only after it is published). Follow-up
+// #585 switches the WASM adapter to this canonical import once the urban release carrying it is
+// published; until then the testkit's own identity cases pin its copy to this normalizer's behaviour.
+/** A non-empty string form of an engine key/id, or `undefined` when absent/blank (including a
+ *  whitespace-only string). Coerces a *finite* numeric key to a string (the engine may serialize a
+ *  key either way) but never `String(...)`-coerces an arbitrary object into a garbage
+ *  `"[object Object]"` id, nor a non-finite number into `"NaN"`/`"Infinity"`. The blank check trims,
+ *  matching the read-path blank-key guards, so a `"   "` key can never leak into a result. */
+export function presentEngineKey(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? String(value) : undefined;
+    }
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/** A present string-only identifier (e.g. a BPMN process id) under the shared trim rule; a
+ *  non-string is absent and never `String(...)`-coerced. */
+export function presentString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/** The {@link ProcessDefinitionIdentity} an engine row (a create response or a process-instance
+ *  search row) reports — the single mapping both `createInstance` and `searchProcessInstances` use,
+ *  so a created instance and its later snapshot describe the same definition identically. Each field
+ *  passes the shared presence rule; a version that is not a positive integer number is omitted
+ *  (never coerced). */
+export function pickProcessDefinitionIdentity(row) {
+    const processDefinitionKey = presentEngineKey(row.processDefinitionKey);
+    const processDefinitionId = presentString(row.processDefinitionId);
+    const version = row.processDefinitionVersion;
+    const processDefinitionVersion = typeof version === "number" && Number.isInteger(version) && version > 0 ? version : undefined;
+    return {
+        ...(processDefinitionKey ? { processDefinitionKey } : {}),
+        ...(processDefinitionId ? { processDefinitionId } : {}),
+        ...(processDefinitionVersion !== undefined ? { processDefinitionVersion } : {}),
+    };
+}

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

@@ -1,4 +1,4 @@
-import type { EngineClient, AgentHistoryFilter, AgentHistoryRecord, AgentInstanceFilter, AgentInstanceSummary, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, FormSchema, IncidentFilter, IncidentState, IncidentSummary, JobFilter, JobHandler, JobSummary, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, UserTaskFilter, VariableFilter, VariableSummary, WorkerSubscription } from "../core/host.ts";
+import type { EngineClient, AgentHistoryFilter, AgentHistoryRecord, AgentInstanceFilter, AgentInstanceSummary, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, FormSchema, IncidentFilter, IncidentState, IncidentSummary, JobFilter, JobHandler, JobSummary, CreatedProcessInstance, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, UserTaskFilter, VariableFilter, VariableSummary, 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. */
@@ -233,10 +233,7 @@ export declare class SdkEngineClient implements EngineClient {
         processDefinitionId: string;
         variables?: Record<string, unknown>;
         awaitCompletion?: boolean;
-    }): Promise<{
-        processInstanceKey: string;
-        variables?: Record<string, unknown>;
-    }>;
+    }): Promise<CreatedProcessInstance>;
     cancelInstance(input: {
         processInstanceKey: string;
     }): Promise<void>;
@@ -260,6 +257,7 @@ export declare class SdkEngineClient implements EngineClient {
     searchProcessInstances(filter?: {
         processInstanceKeys?: string[];
         state?: ProcessInstanceState;
+        processDefinitionId?: string;
         parentProcessInstanceKey?: string;
         rootProcessInstanceKey?: string;
     }): Promise<ProcessInstanceSnapshot[]>;

package/dist/runtime/engine/nanosdk.js

@@ -19,6 +19,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { assertDeployedWaitStateType, isBpmnError } from "../core/host.js";
+import { pickProcessDefinitionIdentity, presentEngineKey, presentString, } from "../core/process-identity.js";
 import { buildFormSchema, parseFormSchema, pickFormLinkage, resolveFormIdentifier, } from "../core/form-contract.js";
 import { isRecord } from "../core/guards.js";
 import { applyAmbientLineage } from "../core/lineage.js";
@@ -111,20 +112,11 @@ export function normalizeIncidentState(raw) {
             return "UNKNOWN";
     }
 }
-/** A non-empty string form of an engine key/id, or `undefined` when absent/blank (including a
- *  whitespace-only string). Coerces a numeric key to a string (the engine may serialize a key
- *  either way) but never `String(...)`-coerces an arbitrary object into a garbage
- *  `"[object Object]"` id. The blank check trims, matching `getElementInstance`'s blank-key
- *  guard and the form-key presence helpers, so a `"   "` key can never leak into a result. */
-function presentEngineKey(value) {
-    if (typeof value === "number") {
-        return Number.isFinite(value) ? String(value) : undefined;
-    }
-    if (typeof value !== "string")
-        return undefined;
-    const trimmed = value.trim();
-    return trimmed === "" ? undefined : trimmed;
-}
+// Engine-key / process-definition-identity normalization now lives in the shared, adapter-agnostic
+// `../core/process-identity.ts` (imported above), so this adapter's `createInstance` and
+// `searchProcessInstances` run the *same* mapping — see that module's header for the drift class
+// this removes. The WASM test adapter keeps a mirrored local copy until #585 (that module header's
+// "Ownership today" note), so the shared mapping is not yet a cross-adapter guarantee.
 /** The non-empty, trimmed string form of a *required* engine key, or throws when the value is
  *  absent/blank (including a whitespace-only string). A mutating seam operation addresses a
  *  single entity by key, so a blank key is a caller bug that must fail fast with an actionable
@@ -632,6 +624,7 @@ export class SdkEngineClient {
         const variables = isRecord(body.variables) ? body.variables : undefined;
         return {
             processInstanceKey: requireProcessInstanceKey(key),
+            ...pickProcessDefinitionIdentity(body),
             variables,
         };
     }
@@ -749,6 +742,10 @@ export class SdkEngineClient {
         const f = {};
         if (filter?.state)
             f.state = filter.state;
+        // A blank BPMN process-id selector is absent, not an empty filter that matches nothing.
+        const processDefinitionId = presentString(filter?.processDefinitionId);
+        if (processDefinitionId)
+            f.processDefinitionId = processDefinitionId;
         // Normalize each requested key through the shared presence rule (drop blank/whitespace-only
         // entries, trim padded ones like `" 123 "`) so the `$in` filter carries only present keys that
         // match the normalized keys we surface — mirroring `WasmEngineClient` and the selector
@@ -792,13 +789,12 @@ export class SdkEngineClient {
                 });
                 return [];
             }
-            const processDefinitionKey = presentEngineKey(it.processDefinitionKey);
             const parentProcessInstanceKey = presentEngineKey(it.parentProcessInstanceKey);
             const rootProcessInstanceKey = presentEngineKey(it.rootProcessInstanceKey);
             return [{
                     processInstanceKey,
                     state,
-                    ...(processDefinitionKey ? { processDefinitionKey } : {}),
+                    ...pickProcessDefinitionIdentity(it),
                     ...(parentProcessInstanceKey ? { parentProcessInstanceKey } : {}),
                     ...(rootProcessInstanceKey ? { rootProcessInstanceKey } : {}),
                 }];

package/dist/runtime/index.d.ts

@@ -8,9 +8,10 @@ export { bindModeToHost, expandEnv, expandEnvString, isBindMode, loadManifest, p
 export type { ActionDecl, AppManifest, BindMode, ChatSurface, DataSource, DomainField, DomainType, InstanceTracking, LlmBinding, NetworkConfig, PagesSurface, Surfaces, TaskInboxSurface, Trigger, Worker, } from "./core/manifest.ts";
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.ts";
 export type { ValidationIssue } from "./core/validate.ts";
-export type { EngineClient, AgentHistoryFilter, AgentHistoryRecord, AgentInstanceFilter, AgentInstanceMetrics, AgentInstanceSummary, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, EngineJob, FormSchema, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, IncidentState, EngineIncidentState, IncidentFilter, IncidentSummary, JobFilter, JobHandler, JobSummary, ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb, UserTaskState, UserTaskSummary, UserTaskFilter, VariableFilter, VariableSummary, WatchHandle, WorkerSubscription, } from "./core/host.ts";
+export type { EngineClient, AgentHistoryFilter, AgentHistoryRecord, AgentInstanceFilter, AgentInstanceMetrics, AgentInstanceSummary, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, EngineJob, FormSchema, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, IncidentState, EngineIncidentState, IncidentFilter, IncidentSummary, JobFilter, JobHandler, JobSummary, CreatedProcessInstance, ProcessDefinitionIdentity, ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb, UserTaskState, UserTaskSummary, UserTaskFilter, VariableFilter, VariableSummary, WatchHandle, WorkerSubscription, } from "./core/host.ts";
 export type { TranscriptContentBlock, TranscriptContentType, TranscriptToolCall, TranscriptTurnMetrics, TranscriptTurnRole, } from "@nanobpm/agentic/transcript";
 export { buildFormSchema, parseFormSchema, pickFormLinkage, presentFormIdentifier, resolveFormIdentifier, } from "./core/form-contract.ts";
+export { pickProcessDefinitionIdentity, presentEngineKey, presentString, } from "./core/process-identity.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 export { createLogger } from "./core/logger.ts";
 export type { Logger, LogLevel, LogFields, LogSink } from "./core/logger.ts";

package/dist/runtime/index.js

@@ -12,6 +12,11 @@ export { collectManifestIssues, ManifestValidationError, validateManifest, } fro
 // both engine adapters (SDK/REST + WASM test double) call, so their form-identifier,
 // form-schema, and user-task form-linkage handling cannot drift.
 export { buildFormSchema, parseFormSchema, pickFormLinkage, presentFormIdentifier, resolveFormIdentifier, } from "./core/form-contract.js";
+// The adapter-agnostic process-definition-identity normalizer (the single mapping both
+// `createInstance` and `searchProcessInstances` use), owned today by the live SDK adapter; the WASM
+// test adapter keeps a mirrored local copy until #585, so cross-adapter drift-freedom is not yet
+// claimed. `ProcessDefinitionIdentity` itself is re-exported from `./core/host.ts`.
+export { pickProcessDefinitionIdentity, presentEngineKey, presentString, } from "./core/process-identity.js";
 // Structured logging surface (see core/logger.ts): the shape of `AppApi.log`, plus `createLogger`
 // so consumers can build a Logger for a custom sink or a no-op test double (`createLogger(() => {})`).
 export { createLogger } from "./core/logger.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.94.2",
+	"version": "0.96.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",
@@ -106,7 +106,7 @@
 		"@nanobpm/agentic": "^0.15.0",
 		"@nanobpm/nano-app-schema": "^0.11.0",
 		"@nanobpm/nano-sdk": "^1.2.5",
-		"@nanobpm/workflow": "^0.14.0",
+		"@nanobpm/workflow": "^0.15.0",
 		"bpmn-auto-layout": "^2.0.0-alpha.2",
 		"create-urban-app": "^0.15.2",
 		"yaml": "^2.9.0"