@nanobpm/urban 0.94.2 → 0.96.0

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

@@ -6,7 +6,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { EngineClient, HttpRequest, HttpResponse } from "../host.ts";
 import { makeRouter } from "../router.ts";
-import { createPagesRoutes, type GridLayout, type PagesDataSource, type PagesDeps, parseGridLayout } from "./pages.ts";
+import { createPagesRoutes, type GridLayout, type PagesDataSource, type PagesDeps, parseGridLayout, RUNTIME_JS_PATH } from "./pages.ts";
 
 function req(
   method: string,
@@ -2123,3 +2123,138 @@ test("#572: parseGridLayout accepts only the declared layouts (anything else is
   assert.equal(parseGridLayout("grid"), undefined);
   assert.equal(parseGridLayout(1), undefined);
 });
+
+// nano-ide#578 — an app MAY ship `pages/app.css` / `pages/app.js`; the shell links them only when present.
+function appAssetRoutes(files: Record<string, string>) {
+  return makeRouter(
+    createPagesRoutes(
+      { pagesDir: "pages", homePage: "home", sourceName: "app" },
+      {
+        db: fakeDb(),
+        engine: fakeEngine().engine,
+        readPage: async () => "{}",
+        readAsset: async (p) => {
+          const body = files[p];
+          if (body === undefined) throw new Error(`ENOENT ${p}`);
+          return body;
+        },
+      },
+    ),
+  );
+}
+
+test("#578: no app.css/app.js → the shell references neither (no 404 noise)", async () => {
+  const body = (await appAssetRoutes({})(req("GET", "/"))).body ?? "";
+  assert.doesNotMatch(body, /app\.css/);
+  assert.doesNotMatch(body, /app\.js/);
+});
+
+test("#578: app.css is linked AFTER the built-in CSS, and app.js loads after the runtime", async () => {
+  const router = appAssetRoutes({ "pages/app.css": "body{color:red}", "pages/app.js": "export {};" });
+  const body = (await router(req("GET", "/"))).body ?? "";
+  const css = body.indexOf('<link rel="stylesheet" href="./app.css" />');
+  assert.ok(css > body.indexOf("</style>"), "app.css must follow the renderer <style> so its rules win");
+  // Compare against the actual fingerprinted runtime <script> tag — the bare word "runtime"
+  // also appears in the embedded renderer CSS, so a substring match would pass even if the
+  // app script were moved before the runtime module.
+  const runtimeTag = `<script type="module" src=".${RUNTIME_JS_PATH}"></script>`;
+  const runtimeAt = body.indexOf(runtimeTag);
+  assert.ok(runtimeAt >= 0, "the shell references the fingerprinted runtime module");
+  const js = body.indexOf('<script type="module" src="./app.js"></script>');
+  assert.ok(js > runtimeAt, "app.js must load after the runtime module");
+  const cssRes = await router(req("GET", "/app.css"));
+  assert.equal(cssRes.status, 200);
+  assert.equal(cssRes.body, "body{color:red}");
+  assert.match(String(cssRes.headers?.["content-type"]), /text\/css/);
+  // Mutable at a stable URL: the browser must revalidate on every load so an edit (or a
+  // remove/re-add) takes effect without a restart — same policy as `/app/runtime.js`.
+  assert.equal(cssRes.headers?.["cache-control"], "no-cache");
+  const jsRes = await router(req("GET", "/app.js"));
+  assert.equal(jsRes.status, 200);
+  assert.match(String(jsRes.headers?.["content-type"]), /javascript/);
+  assert.equal(jsRes.headers?.["cache-control"], "no-cache");
+  // A missing app asset 404s no-cache too, so a cached 404 can't mask a later re-add.
+  const missing = await appAssetRoutes({})(req("GET", "/app.css"));
+  assert.equal(missing.status, 404);
+  assert.equal(missing.headers?.["cache-control"], "no-cache");
+});
+
+test("#578: only the present asset is referenced", async () => {
+  const body = (await appAssetRoutes({ "pages/app.css": "x" })(req("GET", "/"))).body ?? "";
+  assert.match(body, /href="\.\/app\.css"/);
+  assert.doesNotMatch(body, /src="\.\/app\.js"/);
+});
+
+test("#578: the shell probes existence WITHOUT reading the assets when the host offers an exists seam", async () => {
+  const files: Record<string, string> = { "pages/app.js": "export {};" };
+  const reads: string[] = [];
+  const probes: string[] = [];
+  const router = makeRouter(
+    createPagesRoutes(
+      { pagesDir: "pages", homePage: "home", sourceName: "app" },
+      {
+        db: fakeDb(),
+        engine: fakeEngine().engine,
+        readPage: async () => "{}",
+        readAsset: async (p) => {
+          reads.push(p);
+          const body = files[p];
+          if (body === undefined) throw new Error(`ENOENT ${p}`);
+          return body;
+        },
+        existsAsset: async (p) => {
+          probes.push(p);
+          return p in files;
+        },
+      },
+    ),
+  );
+  const body = (await router(req("GET", "/"))).body ?? "";
+  assert.match(body, /src="\.\/app\.js"/, "a present app.js is linked");
+  assert.doesNotMatch(body, /href="\.\/app\.css"/, "an absent app.css is not");
+  assert.deepEqual([...probes].sort(), ["pages/app.css", "pages/app.js"], "both assets are probed per shell request");
+  assert.deepEqual(reads, [], "no asset bytes are read to build the shell");
+
+  // Per-request, NOT memoized (#578 no-restart): swap which asset exists and re-request. A shell
+  // that cached the first probe result would keep linking app.js (and omit app.css); a genuine
+  // per-request probe must reflect the removal/addition AND re-probe BOTH paths on the next load.
+  probes.length = 0;
+  delete files["pages/app.js"];
+  files["pages/app.css"] = "body{color:red}";
+  const body2 = (await router(req("GET", "/"))).body ?? "";
+  assert.match(body2, /href="\.\/app\.css"/, "a newly-added app.css is linked on the next request");
+  assert.doesNotMatch(body2, /src="\.\/app\.js"/, "a removed app.js is dropped on the next request");
+  assert.deepEqual(
+    [...probes].sort(),
+    ["pages/app.css", "pages/app.js"],
+    "both assets are re-probed on the second request (no memoization)",
+  );
+  assert.deepEqual(reads, [], "still no asset bytes are read to build the shell");
+});
+
+test("#578: a DIRECTORY at an asset path is not linked (the probe is file-only, like serving)", async () => {
+  // `HostContext.exists` is true for files AND directories; the probe contract must answer
+  // "would serving this path succeed?" — a `pages/app.css/` directory 404s when read, so the
+  // shell must not link it. The injected probe here is exactly what `mountPages` builds from
+  // `HostContext.statFile` (`(await statFile(p))?.isFile === true`).
+  const files: Record<string, string> = { "pages/app.js": "export {};" };
+  const dirs = new Set(["pages/app.css"]);
+  const router = makeRouter(
+    createPagesRoutes(
+      { pagesDir: "pages", homePage: "home", sourceName: "app" },
+      {
+        db: fakeDb(),
+        engine: fakeEngine().engine,
+        readPage: async () => "{}",
+        readAsset: async (p) => {
+          if (dirs.has(p)) throw new Error(`EISDIR ${p}`);
+          throw new Error(`ENOENT ${p}`);
+        },
+        existsAsset: async (p) => !dirs.has(p) && p in files,
+      },
+    ),
+  );
+  const body = (await router(req("GET", "/"))).body ?? "";
+  assert.doesNotMatch(body, /href="\.\/app\.css"/, "a directory named app.css is not linked");
+  assert.match(body, /src="\.\/app\.js"/, "a real app.js file still is");
+});

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

@@ -27,7 +27,7 @@
 
 import type { AppApi, RuntimeContext } from "../context.ts";
 import { errorMessage, isRecord } from "../guards.ts";
-import type { EngineClient } from "../host.ts";
+import type { EngineClient, HttpResponse } from "../host.ts";
 import { html, json, type Route } from "../router.ts";
 import { cancelInstanceReconciling, type CancelInstanceResult } from "./cancel.ts";
 import { apiDocsPath } from "./api.ts";
@@ -89,6 +89,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"`.
@@ -118,6 +133,13 @@ function javascript(
   };
 }
 
+// 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"] as const;
+
 // 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
@@ -130,7 +152,7 @@ function javascript(
 // `./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"] as const;
+const SIDECAR_ASSETS = ["embed.html", "standalone.html", "mount.js", "cockpit.css", ...APP_ASSETS] as const;
 
 // 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`
@@ -226,6 +248,9 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
   // 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: string) => 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
@@ -262,16 +287,25 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
   };
 
   const routes: Route[] = [];
-  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 (): Promise<HttpResponse> => {
+    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",
@@ -299,11 +333,21 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
   // 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` →
@@ -653,12 +697,24 @@ export function mountPages(ctx: RuntimeContext, app: AppApi): PagesHandle {
   };
   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: string) => (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(() => []);
@@ -679,7 +735,12 @@ function escapeAttr(s: string): string {
   return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
-function rendererShell(homePage: string, apiDocsPath: string | undefined, gridLayout: GridLayout): string {
+function rendererShell(
+  homePage: string,
+  apiDocsPath: string | undefined,
+  gridLayout: GridLayout,
+  app: { appCss: boolean; appJs: boolean } = { appCss: false, appJs: false },
+): string {
   // 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).
@@ -704,12 +765,12 @@ function rendererShell(homePage: string, apiDocsPath: string | undefined, gridLa
   <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>`;
 }
@@ -1095,5 +1156,8 @@ function fnv1aHex(s: string): string {
 // 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/src/runtime/core/modules/surfaces.test.ts

@@ -16,6 +16,7 @@ function ctxWith(surfaces: Record<string, unknown>): Parameters<typeof mountSurf
     readTextFile: async () => "",
     listDir: async () => [],
     exists: async () => false,
+    statFile: async () => null,
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },

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

@@ -80,6 +80,7 @@ function fakeCtx(triggers: Trigger[]): { ctx: RuntimeContext; hostLogs: Array<{
     readTextFile: async () => "",
     listDir: async () => [],
     exists: async () => false,
+    statFile: async () => null,
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },

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

@@ -68,6 +68,7 @@ function makeCtx(
     readTextFile: async () => "",
     listDir: async () => [],
     exists: async () => false,
+    statFile: async () => null,
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },

package/src/runtime/core/process-identity.test.ts

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  pickProcessDefinitionIdentity,
+  presentEngineKey,
+  presentString,
+} from "./process-identity.ts";
+
+// The canonical, adapter-agnostic process-definition-identity normalizer. These cases pin the
+// class the shared helper exists to keep consistent (No Drift Surfaces): a padded/numeric key is
+// normalized, a blank/whitespace/non-string/non-finite value is *absent* and never coerced, and a
+// version is kept only when a positive integer number. Scope today: only the SDK adapter
+// (`engine/nanosdk.ts`) routes through this mapping; the WASM test adapter
+// (`@nanobpm/urban-testkit`) runs a deliberately mirrored local copy until #585, pinned to this
+// behaviour by its own identity cases (`wasm-engine.test.ts`).
+
+test("presentEngineKey coerces a finite numeric key, trims a string, and drops blank/non-finite/non-string", () => {
+  assert.equal(presentEngineKey(7), "7");
+  assert.equal(presentEngineKey(" order "), "order");
+  assert.equal(presentEngineKey("   "), undefined);
+  assert.equal(presentEngineKey(""), undefined);
+  assert.equal(presentEngineKey(Number.NaN), undefined);
+  assert.equal(presentEngineKey(Number.POSITIVE_INFINITY), undefined);
+  assert.equal(presentEngineKey({}), undefined);
+  assert.equal(presentEngineKey(null), undefined);
+  assert.equal(presentEngineKey(undefined), undefined);
+});
+
+test("presentString keeps a trimmed non-empty string and drops blank/non-string (never coerces)", () => {
+  assert.equal(presentString(" human "), "human");
+  assert.equal(presentString("   "), undefined);
+  assert.equal(presentString(""), undefined);
+  // A number id is absent — never String(...)-coerced into a garbage id.
+  assert.equal(presentString(5), undefined);
+  assert.equal(presentString({}), undefined);
+  assert.equal(presentString(undefined), undefined);
+});
+
+test("pickProcessDefinitionIdentity normalizes present fields and omits blank/malformed ones", () => {
+  assert.deepEqual(
+    pickProcessDefinitionIdentity({
+      processDefinitionKey: 7,
+      processDefinitionId: " order ",
+      processDefinitionVersion: 2,
+    }),
+    { processDefinitionKey: "7", processDefinitionId: "order", processDefinitionVersion: 2 },
+  );
+});
+
+test("pickProcessDefinitionIdentity drops a blank key, a non-string id, and a stringly version", () => {
+  assert.deepEqual(
+    pickProcessDefinitionIdentity({
+      processDefinitionKey: "  ",
+      processDefinitionId: 5,
+      processDefinitionVersion: "2",
+    }),
+    {},
+  );
+});
+
+test("pickProcessDefinitionIdentity keeps a version only when a positive integer number", () => {
+  assert.deepEqual(pickProcessDefinitionIdentity({ processDefinitionVersion: 1.5 }), {});
+  assert.deepEqual(pickProcessDefinitionIdentity({ processDefinitionVersion: 0 }), {});
+  assert.deepEqual(pickProcessDefinitionIdentity({ processDefinitionVersion: -1 }), {});
+  assert.deepEqual(pickProcessDefinitionIdentity({ processDefinitionVersion: 3 }), {
+    processDefinitionVersion: 3,
+  });
+});
+
+test("pickProcessDefinitionIdentity on an empty row returns an empty identity (fully absent)", () => {
+  assert.deepEqual(pickProcessDefinitionIdentity({}), {});
+});

package/src/runtime/core/process-identity.ts

@@ -0,0 +1,66 @@
+// 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.
+
+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 function presentEngineKey(value: unknown): string | undefined {
+  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: unknown): string | undefined {
+  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: {
+  processDefinitionKey?: unknown;
+  processDefinitionId?: unknown;
+  processDefinitionVersion?: unknown;
+}): ProcessDefinitionIdentity {
+  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/src/runtime/core/runtime.test.ts

@@ -757,3 +757,30 @@ test('#572: an omitted surfaces.pages.gridLayout falls back to the "auto" layout
 test('#572: an invalid surfaces.pages.gridLayout falls back to the "auto" layout', async () => {
   assert.equal(await shellGridLayout({ gridLayout: "grid" }), "auto");
 });
+
+// #578: app-owned `pages/app.css`/`pages/app.js` by convention, driven end-to-end through the real
+// node host (createUrbanApp → mountPages → HostContext.statFile), not an injected `existsAsset`.
+// This guards the production wiring the focused pages.test.ts probe tests can't: that `mountPages`
+// forwards the host's file-only probe (so a DIRECTORY at an asset path is NOT linked — it would
+// 404 on serving) and that a real regular file IS linked.
+test("#578: the shell links a real pages/app.js file but not a pages/app.css DIRECTORY (real host)", async () => {
+  const dir = await makeFixture({ surfaces: { pages: { enabled: true } } });
+  // A regular file at pages/app.js (should be linked) and a DIRECTORY at pages/app.css (should not).
+  await mkdir(join(dir, "pages"), { recursive: true });
+  await writeFile(join(dir, "pages", "app.js"), "export {};");
+  await mkdir(join(dir, "pages", "app.css"), { recursive: true });
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  await app.start();
+  try {
+    const res = await fetch(`http://localhost:${app.httpPort!}/`);
+    assert.equal(res.status, 200);
+    const body = await res.text();
+    assert.match(body, /src="\.\/app\.js"/, "a real app.js file is linked");
+    assert.doesNotMatch(body, /href="\.\/app\.css"/, "a DIRECTORY named app.css is not linked");
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/runtime/devserver.test.ts

@@ -205,6 +205,7 @@ function fakeHost(): { host: HostContext; fire: (p: string) => void; closed: ()
     readTextFile: async () => "",
     listDir: async () => [],
     exists: async () => false,
+    statFile: async () => null,
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },

package/src/runtime/engine/nanosdk.test.ts

@@ -200,6 +200,43 @@ test("createInstance routes through the SDK and coerces the key", async () => {
   assert.ok(client.calls.includes("createProcessInstance"));
 });
 
+test("createInstance returns the started definition's identity (key, id, version)", async () => {
+  // The create response names exactly which deployed definition version the instance runs; the
+  // seam must surface it (normalized through the same presence rule as the search snapshot) so a
+  // caller need not race an eventually consistent search to learn it.
+  const client = fakeSdkClient({
+    createProcessInstance: async () => ({
+      processInstanceKey: 99,
+      processDefinitionKey: 2251799813685249,
+      processDefinitionId: " order ",
+      processDefinitionVersion: 3,
+    }),
+  });
+  const engine = new SdkEngineClient(client);
+  const res = await engine.createInstance({ processDefinitionId: "order" });
+  assert.deepEqual(res, {
+    processInstanceKey: "99",
+    processDefinitionKey: "2251799813685249",
+    processDefinitionId: "order",
+    processDefinitionVersion: 3,
+    variables: undefined,
+  });
+});
+
+test("createInstance omits definition identity fields the engine leaves blank or malformed", async () => {
+  const client = fakeSdkClient({
+    createProcessInstance: async () => ({
+      processInstanceKey: "99",
+      processDefinitionKey: "  ",
+      processDefinitionId: "",
+      processDefinitionVersion: "3", // not a number → omitted, never coerced
+    }),
+  });
+  const engine = new SdkEngineClient(client);
+  const res = await engine.createInstance({ processDefinitionId: "order" });
+  assert.deepEqual(res, { processInstanceKey: "99", variables: undefined });
+});
+
 test("createInstance throws when the SDK response omits the instance key", async () => {
   const client = fakeSdkClient({
     createProcessInstance: async () => ({ variables: { ok: true } }),
@@ -622,6 +659,51 @@ test("searchProcessInstances surfaces the parent/root linkage keys and drops bla
   ]);
 });
 
+test("searchProcessInstances forwards a processDefinitionId selector (trimmed, blank dropped)", async () => {
+  const seen: unknown[] = [];
+  const client = fakeSdkClient({
+    searchProcessInstances: async (input) => {
+      seen.push(input);
+      return { items: [] };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  await engine.searchProcessInstances({ processDefinitionId: " order ", state: "ACTIVE" });
+  await engine.searchProcessInstances({ processDefinitionId: "   " });
+  assert.deepEqual(seen, [
+    { filter: { state: "ACTIVE", processDefinitionId: "order" } },
+    { filter: {} },
+  ]);
+});
+
+test("searchProcessInstances surfaces each instance's definition identity", async () => {
+  const client = fakeSdkClient({
+    searchProcessInstances: async () => ({
+      items: [
+        {
+          processInstanceKey: 10,
+          state: "ACTIVE",
+          processDefinitionKey: 5,
+          processDefinitionId: "order",
+          processDefinitionVersion: 2,
+        },
+        { processInstanceKey: 11, state: "ACTIVE", processDefinitionId: " ", processDefinitionVersion: null },
+      ],
+    }),
+  });
+  const engine = new SdkEngineClient(client);
+  assert.deepEqual(await engine.searchProcessInstances(), [
+    {
+      processInstanceKey: "10",
+      state: "ACTIVE",
+      processDefinitionKey: "5",
+      processDefinitionId: "order",
+      processDefinitionVersion: 2,
+    },
+    { processInstanceKey: "11", state: "ACTIVE" },
+  ]);
+});
+
 test("normalizeProcessInstanceState maps the terminal set and rejects others", () => {
   assert.equal(normalizeProcessInstanceState("ACTIVE"), "ACTIVE");
   assert.equal(normalizeProcessInstanceState("completed"), "COMPLETED");