@nanobpm/urban 0.24.1 → 0.26.0

package/dist/toolkit/index.d.ts

@@ -2,14 +2,16 @@ export type { DerivedArtifact, Deriver } from "./artifact.ts";
 export { GENERATED_DIR, sortArtifacts } from "./artifact.ts";
 export { deriveMigrations, migrationsDeriver, sqlType, createTableSql, tableSchemaForType, groupTypesBySource, } from "./derivers/migrations.ts";
 export type { ToolkitManifest, ToolkitType, ToolkitField, DerivedColumn, DerivedTable, } from "./derivers/migrations.ts";
-export { deriveDomain, emitDomain, emitDomainModel, emitDomainDts, emitDomainDtsForSources, emitDomainTypeRegistry, domainDeriver, sourcesFromManifest, registryFromManifest, sqliteAffinityToTs, interfaceName, } from "./derivers/domain.ts";
-export type { SourceSchema, DomainFieldDef, DomainTypeDef, DomainTypeRegistry, } from "./derivers/domain.ts";
-export { deriveWorkerBindings, emitWorkerBindings, workerIoDeriver, scanModelWorkers, WORKER_BINDINGS_DTS, DOMAIN_DTS, } from "./derivers/worker-io.ts";
+export { deriveDomain, emitDomain, emitDomainModel, emitDomainBindings, emitDomainDts, emitDomainDtsForSources, emitDomainTypeRegistry, domainDeriver, isPrimitiveKeyword, sourcesFromManifest, registryFromManifest, sqliteAffinityToTs, interfaceName, DOMAIN_BINDINGS, } from "./derivers/domain.ts";
+export type { SourceSchema, DomainFieldDef, DomainTypeDef, DomainTypeRegistry, ColumnMeta, TableMeta, } from "./derivers/domain.ts";
+export { resolveShapes, columnToField, emitDomainModelJson, DOMAIN_MODEL_JSON, } from "./derivers/shapes.ts";
+export type { ShapeOp, ShapeDecl, ShapeDiagnostic, ShapeResolution, FusedMetaDecl, } from "./derivers/shapes.ts";
+export { deriveWorkerBindings, emitWorkerBindings, emitWorkerBindingsRuntime, overlayDerivedWorkerIo, workerIoDeriver, scanModelWorkers, WORKER_BINDINGS_DTS, WORKER_BINDINGS_TS, DOMAIN_DTS, } from "./derivers/worker-io.ts";
 export type { ModelSource, WorkerIo, WorkerBindingDecl } from "./derivers/worker-io.ts";
 export { byModelPath, typeRefFor } from "./derivers/worker-io.ts";
 export { deriveMeta, emitMeta, foldMeta, metaDeriver, scanModelMeta, META_TS, } from "./derivers/meta.ts";
 export type { MetaDecl } from "./derivers/meta.ts";
-export { deriveMessageBindings, emitMessageBindings, messagesDeriver, scanModelMessages, MESSAGE_BINDINGS_DTS, } from "./derivers/messages.ts";
+export { deriveMessageBindings, emitMessageBindings, emitMessageBindingsRuntime, messagesDeriver, scanModelMessages, MESSAGE_BINDINGS_DTS, MESSAGE_BINDINGS_TS, } from "./derivers/messages.ts";
 export type { MessageIo, MessageBindingDecl } from "./derivers/messages.ts";
 export declare const DERIVERS: readonly [import("./artifact.ts").Deriver<import("./derivers/migrations.ts").ToolkitManifest>, import("./artifact.ts").Deriver<import("./derivers/migrations.ts").ToolkitManifest>, import("./artifact.ts").Deriver<{
     models: import("./derivers/worker-io.ts").ModelSource[];

package/dist/toolkit/index.js

@@ -5,11 +5,12 @@
 export { GENERATED_DIR, sortArtifacts } from "./artifact.js";
 // Derivers
 export { deriveMigrations, migrationsDeriver, sqlType, createTableSql, tableSchemaForType, groupTypesBySource, } from "./derivers/migrations.js";
-export { deriveDomain, emitDomain, emitDomainModel, emitDomainDts, emitDomainDtsForSources, emitDomainTypeRegistry, domainDeriver, sourcesFromManifest, registryFromManifest, sqliteAffinityToTs, interfaceName, } from "./derivers/domain.js";
-export { deriveWorkerBindings, emitWorkerBindings, workerIoDeriver, scanModelWorkers, WORKER_BINDINGS_DTS, DOMAIN_DTS, } from "./derivers/worker-io.js";
+export { deriveDomain, emitDomain, emitDomainModel, emitDomainBindings, emitDomainDts, emitDomainDtsForSources, emitDomainTypeRegistry, domainDeriver, isPrimitiveKeyword, sourcesFromManifest, registryFromManifest, sqliteAffinityToTs, interfaceName, DOMAIN_BINDINGS, } from "./derivers/domain.js";
+export { resolveShapes, columnToField, emitDomainModelJson, DOMAIN_MODEL_JSON, } from "./derivers/shapes.js";
+export { deriveWorkerBindings, emitWorkerBindings, emitWorkerBindingsRuntime, overlayDerivedWorkerIo, workerIoDeriver, scanModelWorkers, WORKER_BINDINGS_DTS, WORKER_BINDINGS_TS, DOMAIN_DTS, } from "./derivers/worker-io.js";
 export { byModelPath, typeRefFor } from "./derivers/worker-io.js";
 export { deriveMeta, emitMeta, foldMeta, metaDeriver, scanModelMeta, META_TS, } from "./derivers/meta.js";
-export { deriveMessageBindings, emitMessageBindings, messagesDeriver, scanModelMessages, MESSAGE_BINDINGS_DTS, } from "./derivers/messages.js";
+export { deriveMessageBindings, emitMessageBindings, emitMessageBindingsRuntime, messagesDeriver, scanModelMessages, MESSAGE_BINDINGS_DTS, MESSAGE_BINDINGS_TS, } from "./derivers/messages.js";
 // The registry of all derivers (for discovery / IDE migration).
 import { migrationsDeriver } from "./derivers/migrations.js";
 import { domainDeriver } from "./derivers/domain.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.24.1",
+  "version": "0.26.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",

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

@@ -46,6 +46,11 @@ function expectRecords(value: unknown): Record<string, unknown>[] {
   return value;
 }
 
+function expectString(value: unknown): string {
+  if (typeof value !== "string") throw new TypeError("expected a string");
+  return value;
+}
+
 test("sources lists declared datasources and the default", async () => {
   const { dir, cleanup } = await fixture();
   try {
@@ -225,15 +230,6 @@ test("migrations treats a missing migrations dir as an empty list", async () =>
   }
 });
 
-test("domaintypes is not yet implemented and errors clearly", async () => {
-  const { dir, cleanup } = await fixture();
-  try {
-    await assert.rejects(run(dir, { op: "domaintypes" }), /not yet implemented/);
-  } finally {
-    await cleanup();
-  }
-});
-
 test("an unknown op and an unknown source error", async () => {
   const { dir, cleanup } = await fixture();
   try {
@@ -304,3 +300,130 @@ test("an absolute --manifest path is honoured as-is (not re-prefixed with root)"
     await cleanup();
   }
 });
+
+// --- domaintypes: live-schema reification + shape fuse (ADR 0029 §4/§6, ADR 0040 §9/§10) ---
+//
+// The op ported off the console's vendored data_cli (host dry-out nano-bpm#576). It migrates each
+// sqlite source (write mode only), introspects the live schema, folds the manifest `types` + the
+// model's composed shapes through the fuse, and RETURNS every artifact's content (the read-only
+// host never writes files — the caller persists). These lock that contract.
+
+test("domaintypes migrates, introspects the live schema, and returns every artifact", async () => {
+  const { dir, cleanup } = await fixture();
+  try {
+    const r = await run(dir, { op: "domaintypes" });
+    // Both migrations ran on the shared `_urban_migrations` ledger before introspection.
+    assert.deepEqual(r.migrated, { app: ["001_orders.sql", "002_customers.sql"] });
+    // Two tables reified from the live schema.
+    assert.equal(r.tables, 2);
+    // The domain `.d.ts` carries an interface per live table.
+    assert.equal(typeof r.text, "string");
+    assert.match(expectString(r.text), /export interface Orders\b/);
+    assert.match(expectString(r.text), /export interface Customers\b/);
+    // Persisting: every `*Path` is the app-relative nano-generated target.
+    assert.equal(r.path, "nano-generated/domain-rows.d.ts");
+    assert.equal(r.bindingsPath, "nano-generated/domain.ts");
+    assert.equal(r.workerBindingsPath, "nano-generated/worker-io.d.ts");
+    assert.equal(r.workerRuntimePath, "nano-generated/workers.ts");
+    assert.equal(r.messageBindingsPath, "nano-generated/message-io.d.ts");
+    assert.equal(r.messageRuntimePath, "nano-generated/messages.ts");
+    assert.equal(r.metaPath, "nano-generated/meta.ts");
+    assert.equal(r.domainModelPath, "nano-generated/domain.json");
+    // The Fused Domain Model is emitted and lists both live tables.
+    assert.equal(typeof r.domainModel, "string");
+    const model = JSON.parse(expectString(r.domainModel));
+    assert.deepEqual(
+      model.entities.map((e: { id: string }) => e.id).sort(),
+      ["app.customers", "app.orders"],
+    );
+    // The static runtime wrappers are returned verbatim for the caller to write.
+    assert.equal(typeof r.workerRuntime, "string");
+    assert.equal(typeof r.messageRuntime, "string");
+    assert.deepEqual(r.shapeDiagnostics, []);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("domaintypes write:false is a side-effect-free preview (no migrate, null paths)", async () => {
+  const { dir, cleanup } = await fixture();
+  try {
+    const r = await run(dir, { op: "domaintypes", write: false });
+    // The preview never migrates — nothing applied, DB stays fresh.
+    assert.deepEqual(r.migrated, {});
+    // …and because this fixture's DB is fresh (unmigrated), introspecting the *current* live schema
+    // finds no tables. (An existing DB could legitimately report tables here; this count is scoped
+    // to the fresh fixture, not a general preview guarantee.)
+    assert.equal(r.tables, 0);
+    // Content is still returned (the composer preview needs `text`)…
+    assert.equal(typeof r.text, "string");
+    // …but every persistence target is null and the largest artifact is skipped.
+    assert.equal(r.path, null);
+    assert.equal(r.bindingsPath, null);
+    assert.equal(r.workerBindingsPath, null);
+    assert.equal(r.workerRuntimePath, null);
+    assert.equal(r.messageBindingsPath, null);
+    assert.equal(r.messageRuntimePath, null);
+    assert.equal(r.metaPath, null);
+    assert.equal(r.domainModelPath, null);
+    assert.equal(r.domainModel, null);
+    // A second preview did not leave a migrated DB behind for the next write.
+    const applied = await run(dir, { op: "migrations" });
+    assert.ok(expectRecords(applied.entries).every((e) => e.applied === false));
+  } finally {
+    await cleanup();
+  }
+});
+
+test("domaintypes folds a composed shape into DomainTypes and reports its diagnostics", async () => {
+  const { dir, cleanup } = await fixture();
+  try {
+    const r = await run(dir, {
+      op: "domaintypes",
+      derivedShapes: [
+        {
+          id: "ReviewRound",
+          ops: [
+            { op: "extend", name: "prUrl", type: "string" },
+            { op: "extend", name: "approved", type: "boolean" },
+          ],
+        },
+        // A broken shape: unresolved extend type → error diagnostic, omitted from the emit.
+        { id: "Broken", ops: [{ op: "extend", name: "ref", type: "NoSuchType" }] },
+      ],
+    });
+    // The good shape reifies into the `DomainTypes` registry surfaced by the domain `.d.ts`.
+    assert.match(expectString(r.text), /ReviewRound/);
+    assert.doesNotMatch(expectString(r.text), /Broken/);
+    // The broken shape's diagnostic is returned so the panel can surface it.
+    const diags = expectRecords(r.shapeDiagnostics);
+    assert.equal(diags.length, 1);
+    assert.equal(diags[0].shape, "Broken");
+    assert.equal(diags[0].severity, "error");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("domaintypes emits worker/message bindings from the injected model IO maps", async () => {
+  const { dir, cleanup } = await fixture();
+  try {
+    const r = await run(dir, {
+      op: "domaintypes",
+      derivedShapes: [
+        { id: "Order", ops: [{ op: "extend", name: "total", type: "integer" }] },
+      ],
+      derivedWorkers: [
+        { taskType: "review", inputType: "Order", outputType: "Order", headerKeys: ["priority"] },
+      ],
+      derivedMessages: [{ messageName: "approved", inputType: "Order" }],
+    });
+    // The worker binding names the task type and threads the declared header key.
+    assert.match(expectString(r.workerBindings), /review/);
+    assert.match(expectString(r.workerBindings), /priority/);
+    // The message binding names the message.
+    assert.match(expectString(r.messageBindings), /approved/);
+  } finally {
+    await cleanup();
+  }
+});

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

@@ -14,9 +14,10 @@
 //   op = "sources" | "schema" | "query" | "exec" | "script" | "migrations" | "migrate"
 //      | "domaintypes"
 //
-// `domaintypes` (live-schema reification + shape resolution) is a known protocol op but is
-// intentionally NOT handled here yet — it is ported to `urban data` in a follow-up (PR 2 of
-// #576) and errors clearly for now.
+// `domaintypes` (live-schema reification + shape resolution) composes the domain reifier from the
+// pure toolkit derivers (ported from the console's `domain_types.ts`, host dry-out #576); it never
+// writes files (the host is read-only) — it returns every artifact's content and the caller
+// persists it.
 
 import type { HostContext, SqliteDb } from "../host.ts";
 import { isRecord } from "../guards.ts";
@@ -25,11 +26,48 @@ import { loadManifest } from "../manifest.ts";
 import { validateManifest } from "../validate.ts";
 import { makeGateway, type DataSource as GatewayDataSource } from "./gateway.ts";
 import { applyMigrations, MIGRATIONS_TABLE, openSqliteSource, resolveAppPath } from "./datasource.ts";
+// The `domaintypes` op composes the domain reifier from the pure toolkit derivers (single source of
+// truth for the IDE's codegen, host dry-out nano-bpm#576). Imported directly from the deriver files
+// (not the `toolkit/` barrel, which pulls the Node fs IO) so core stays free of `node:*`/Deno; the
+// derivers' only core dependency is the gateway's `TableMeta`/`ColumnMeta` *types*, which erase.
+import { GENERATED_DIR } from "../../../toolkit/artifact.ts";
+import {
+  DOMAIN_BINDINGS,
+  type DomainTypeDef,
+  type DomainTypeRegistry,
+  emitDomainBindings,
+  emitDomainModel,
+  registryFromManifest,
+  type SourceSchema,
+} from "../../../toolkit/derivers/domain.ts";
+import {
+  DOMAIN_MODEL_JSON,
+  emitDomainModelJson,
+  type FusedMetaDecl,
+  resolveShapes,
+  type ShapeDecl,
+} from "../../../toolkit/derivers/shapes.ts";
+import {
+  DOMAIN_DTS,
+  emitWorkerBindings,
+  emitWorkerBindingsRuntime,
+  overlayDerivedWorkerIo,
+  WORKER_BINDINGS_DTS,
+  WORKER_BINDINGS_TS,
+  type WorkerBindingDecl,
+} from "../../../toolkit/derivers/worker-io.ts";
+import {
+  emitMessageBindings,
+  emitMessageBindingsRuntime,
+  MESSAGE_BINDINGS_DTS,
+  MESSAGE_BINDINGS_TS,
+  type MessageBindingDecl,
+} from "../../../toolkit/derivers/messages.ts";
+import { emitMeta, META_TS, type MetaDecl } from "../../../toolkit/derivers/meta.ts";
 
-/** The DB-manager op protocol's known op set. `domaintypes` is part of the protocol but is not
- * yet handled here (it errors clearly — see the file header); every other op is dispatched by
- * `runDataOp`. Typing `op` as this union (instead of `string`) gives SDK/console callers
- * type-safety and catches typos at compile time. */
+/** The DB-manager op protocol's known op set — every op (including `domaintypes`) is dispatched by
+ * `runDataOp`. Typing `op` as this union (instead of `string`) gives SDK/console callers type-safety
+ * and catches typos at compile time. */
 export type DataOp =
   | "sources"
   | "schema"
@@ -46,6 +84,27 @@ export interface DataRequest {
   sql?: string;
   params?: unknown[];
   statements?: string[];
+  /**
+   * `domaintypes`: persist the derived artifacts (default true). A `write:false` request is the
+   * latency-sensitive composer preview — it introspects WITHOUT migrating the DB first and returns
+   * only the artifact *content* (never a DB side-effect per keystroke). `urban data` never writes
+   * files itself (the host is read-only); the caller persists the returned content when `write` is
+   * not false. This flag only gates the pre-introspection migration side-effect.
+   */
+  write?: boolean;
+  /** `domaintypes`: the model-derived worker-IO map (`taskType → {in,out,headerKeys}`), scanned
+   * from the process models by the caller. Overlaid on the manifest `workers[]` (authoritative for
+   * the envelope). Absent → the manifest projection alone. */
+  derivedWorkers?: WorkerBindingDecl[];
+  /** `domaintypes`: the model-derived message-payload map (`messageName → {in,out}`), scanned from
+   * the models' `bpmn:message` envelopes. Authoritative (no manifest projection). */
+  derivedMessages?: MessageBindingDecl[];
+  /** `domaintypes`: the model-derived composed shapes (`nano:shape`). Each is resolved through the
+   * fuse into a flat domain type folded into the `types` registry. Absent → no shapes. */
+  derivedShapes?: ShapeDecl[];
+  /** `domaintypes`: the model-derived model-level metadata (`nano:meta`). Folded into `meta.ts` and
+   * the structured `domain.json`. Absent → no metadata. */
+  derivedMeta?: MetaDecl[];
 }
 
 /** One datasource the manifest declares, resolved against the environment (env templates in
@@ -281,10 +340,120 @@ export async function runDataOp(
       }
     }
     case "domaintypes": {
-      throw new Error(
-        "`domaintypes` is not yet implemented in `urban data` — the Nano console still serves it " +
-          "(tracked as PR 2 of nano-bpm#576)",
-      );
+      // ADR 0029 §4.1/§4.2/§6 + ADR 0040 §9/§10: reify the domain model from the *live* schema.
+      // Union every declared datasource (the table spine), fold in the manifest `types` registry and
+      // the model's composed `nano:shape`s (resolved through the fuse), and derive the worker/message
+      // typed accessors. Unlike the vendored data_cli, this op NEVER writes files (the host is
+      // read-only): it returns every artifact's content and the caller persists it. `write:false` is
+      // the latency-sensitive composer preview — it skips the pre-introspection migration so a
+      // debounced keystroke has no DB side-effect and pays only for `text` + `shapeDiagnostics`.
+      const { default: def, sources } = listSources(manifest);
+      const persist = req.write !== false;
+      // Introspect each sqlite source's live schema. When persisting, migrate first (the domain
+      // model is derived from `gw.schema()`, so a regen that raced ahead of `migrate` on a fresh DB
+      // would emit an empty `Domain`); the migration runs on the shared `_urban_migrations` ledger.
+      const migrated: Record<string, string[]> = {};
+      const schemas: SourceSchema[] = [];
+      for (const s of sources) {
+        if (String(s.driver) !== "sqlite") continue; // only sqlite is introspectable (see openGateway)
+        const { gw, db } = await openGateway(host, root, manifest, s.name);
+        try {
+          if (persist) {
+            const applied = await applyMigrations(
+              host,
+              db,
+              root,
+              s.migrations ?? DEFAULT_MIGRATIONS_DIR,
+            );
+            if (applied.length) migrated[s.name] = applied;
+          }
+          schemas.push({ source: s.name, tables: await gw.schema() });
+        } finally {
+          db.close();
+        }
+      }
+
+      const types = registryFromManifest(manifest);
+      // Snapshot the manifest `types` *before* folding the resolved shapes so `domain.json` can tag
+      // each entity with its true provenance (manifest vs model) — once folded they are
+      // indistinguishable in `types`.
+      const manifestTypesSnapshot: DomainTypeRegistry = { ...types };
+      // Composed motion shapes (ADR 0040 §9/§10): resolve each `nano:shape` against the leaf fuse
+      // into a flat domain type and fold it into the registry *before* it feeds the domain model and
+      // the worker/message bindings, so a composed shape becomes a first-class `DomainTypes` entry.
+      // Broken shapes are omitted; their diagnostics are returned so the panel can surface them.
+      const shapeResolution = resolveShapes(req.derivedShapes ?? [], types, schemas);
+      const shapeDeclById = new Map((req.derivedShapes ?? []).map((s) => [s.id, s]));
+      const shapeEntities: { decl: ShapeDecl; def: DomainTypeDef }[] = [];
+      for (const [id, shapeDef] of Object.entries(shapeResolution.types)) {
+        types[id] = shapeDef;
+        shapeEntities.push({ decl: shapeDeclById.get(id) ?? { id, ops: [] }, def: shapeDef });
+      }
+      const declaredIds = Object.keys(types);
+
+      const text = emitDomainModel(schemas, def, types);
+      const bindings = emitDomainBindings(schemas, def);
+      const derivedMeta: MetaDecl[] = req.derivedMeta ?? [];
+      const metaAccessor = emitMeta(derivedMeta);
+      // Worker-IO map (ADR 0033 §3): the model is authoritative for the envelope, so an injected
+      // `derivedWorkers` is overlaid on the manifest `workers[]` (which still carries non-IO
+      // bindings such as `llm`); absent, the manifest projection stands alone.
+      const manifestWorkers: WorkerBindingDecl[] = (manifest.workers ?? []).map((w) => ({
+        taskType: w.taskType,
+        inputType: w.inputType,
+        outputType: w.outputType,
+      }));
+      const workers = req.derivedWorkers
+        ? overlayDerivedWorkerIo(manifestWorkers, req.derivedWorkers)
+        : manifestWorkers;
+      const workerBindings = emitWorkerBindings(workers, declaredIds);
+      const workerRuntime = emitWorkerBindingsRuntime();
+      // Message-payload registry (ADR 0040 slice 2): no manifest projection, so the model-derived
+      // map is authoritative and emitted directly.
+      const messages = req.derivedMessages ?? [];
+      const messageBindings = emitMessageBindings(messages, declaredIds);
+      const messageRuntime = emitMessageBindingsRuntime();
+      // The structured Fused Domain Model (`domain.json`, ADR 0040 §1): the largest artifact, so it
+      // is built only when persisting (the preview consumes only `text` + `shapeDiagnostics`).
+      const meta: FusedMetaDecl[] = derivedMeta;
+      const domainModel = persist
+        ? emitDomainModelJson({
+            sources: schemas,
+            default: def,
+            manifestTypes: manifestTypesSnapshot,
+            shapes: shapeEntities,
+            meta,
+            diagnostics: shapeResolution.diagnostics,
+          })
+        : null;
+
+      const rel = (name: string): string => `${GENERATED_DIR}/${name}`;
+      const tables = schemas.reduce((n, s) => n + s.tables.length, 0);
+      // The returned `*Path` fields are the app-relative targets the caller writes to when
+      // persisting (null on a preview). `urban data` returns content only — persisting is the
+      // caller's job (host dry-out nano-bpm#576). The static runtime wrappers (`workers.ts`,
+      // `messages.ts`) are returned too so the caller can write them verbatim.
+      return {
+        path: persist ? rel(DOMAIN_DTS) : null,
+        text,
+        tables,
+        bindingsPath: persist ? rel(DOMAIN_BINDINGS) : null,
+        bindings,
+        workerBindingsPath: persist ? rel(WORKER_BINDINGS_DTS) : null,
+        workerBindings,
+        workerRuntimePath: persist ? rel(WORKER_BINDINGS_TS) : null,
+        workerRuntime,
+        messageBindingsPath: persist ? rel(MESSAGE_BINDINGS_DTS) : null,
+        messageBindings,
+        messageRuntimePath: persist ? rel(MESSAGE_BINDINGS_TS) : null,
+        messageRuntime,
+        metaPath: persist ? rel(META_TS) : null,
+        meta: metaAccessor,
+        domainModelPath: persist ? rel(DOMAIN_MODEL_JSON) : null,
+        domainModel,
+        migrated,
+        shapeDiagnostics: shapeResolution.diagnostics,
+      };
     }
     default:
       throw new Error(`unknown op "${req.op}"`);

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

@@ -86,12 +86,22 @@ test("GET / serves the renderer shell with the home marker", async () => {
   assert.equal(res.status, 200);
   assert.match(res.headers?.["content-type"] ?? "", /text\/html/);
   assert.match(res.body ?? "", /data-home="home"/);
+  // The runtime module is loaded by a *relative* src so it resolves against the
+  // document's mount path — works both at the origin root and under the Nano
+  // console's /console/app-view/<name>/ reverse proxy. A root-absolute
+  // "/app/runtime.js" would 404 against the console origin and never hydrate.
+  assert.match(res.body ?? "", /src="\.\/app\/runtime\.js"/);
+  assert.doesNotMatch(res.body ?? "", /src="\/app\/runtime\.js"/);
 });
 
 test("GET /app/runtime.js serves the renderer module", async () => {
   const res = await dispatch("GET", "/app/runtime.js");
   assert.match(res.headers?.["content-type"] ?? "", /javascript/);
   assert.match(res.body ?? "", /pc:refresh/);
+  // Endpoints are rebased against the served module URL so the app works under a
+  // path-prefixed reverse proxy (Nano console embed), not just at the origin root.
+  assert.match(res.body ?? "", /new URL\("\.\.\/", import\.meta\.url\)/);
+  assert.match(res.body ?? "", /function apiUrl\(u\)/);
 });
 
 test("renderer preserves grid row-detail expansion across refreshes", async () => {

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

@@ -348,7 +348,7 @@ function rendererShell(homePage: string): string {
 </head>
 <body>
   <main id="page" data-home="${escapeAttr(homePage)}"><p class="pc-empty">Loading…</p></main>
-  <script type="module" src="/app/runtime.js"></script>
+  <script type="module" src="./app/runtime.js"></script>
 </body>
 </html>`;
 }
@@ -404,8 +404,23 @@ const RENDERER_JS = String.raw`
 const root = document.getElementById("page");
 const HOME = root.dataset.home || "home";
 
+// Resolve every app endpoint against where THIS module was actually served from,
+// so absolute-looking "/app/…" paths work both at the origin root (direct run,
+// e.g. the CLI on :3000) and under a path-prefixed reverse proxy (the Nano
+// console embeds the app at /console/app-view/<name>/). "../" drops the trailing
+// "app/runtime.js" to land on the app's mount root (always ends in "/").
+const APP_BASE = new URL("../", import.meta.url);
+function apiUrl(u) {
+  // Rebase root-absolute app paths ("/app/…") onto the mount root. Leave a
+  // protocol-relative ("//host/…") or otherwise non-root-relative string alone —
+  // only a single leading slash denotes an app path we own.
+  return typeof u === "string" && u.startsWith("/") && !u.startsWith("//")
+    ? new URL(u.slice(1), APP_BASE).toString()
+    : u;
+}
+
 async function getJSON(url, opts) {
-  const r = await fetch(url, opts);
+  const r = await fetch(apiUrl(url), opts);
   const body = await r.json().catch(() => ({}));
   if (!r.ok) throw new Error(body.error || ("HTTP " + r.status));
   return body;

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

@@ -324,3 +324,81 @@ test("runFromEnv anchors the host at a non-'.' root without double-prefixing pat
     await rm(dir, { recursive: true, force: true });
   }
 });
+
+// Captures console.log for the duration of `fn`, restoring it after.
+async function captureStdout(fn: () => Promise<void>): Promise<string[]> {
+  const lines: string[] = [];
+  const original = console.log;
+  console.log = (...args: unknown[]) => {
+    lines.push(args.map((a) => (typeof a === "string" ? a : String(a))).join(" "));
+  };
+  try {
+    await fn();
+  } finally {
+    console.log = original;
+  }
+  return lines;
+}
+
+test("emits the ADR 0057 boot handshake when NANOBPMN_APP_HANDSHAKE is set", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  const prev = process.env.NANOBPMN_APP_HANDSHAKE;
+  process.env.NANOBPMN_APP_HANDSHAKE = "1";
+  try {
+    const lines = await captureStdout(() => app.start());
+    const handshake = lines.find((l) => l.startsWith("@@NBPM_LISTENING@@"));
+    assert.ok(handshake, "a @@NBPM_LISTENING@@ line was emitted");
+    const payload = JSON.parse(handshake!.slice("@@NBPM_LISTENING@@".length));
+    assert.equal(payload.port, app.httpPort, "handshake reports the actual bound port");
+    assert.ok(payload.port > 0);
+  } finally {
+    if (prev === undefined) delete process.env.NANOBPMN_APP_HANDSHAKE;
+    else process.env.NANOBPMN_APP_HANDSHAKE = prev;
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("does NOT emit the boot handshake without NANOBPMN_APP_HANDSHAKE", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  const prev = process.env.NANOBPMN_APP_HANDSHAKE;
+  delete process.env.NANOBPMN_APP_HANDSHAKE;
+  try {
+    const lines = await captureStdout(() => app.start());
+    assert.ok(
+      !lines.some((l) => l.startsWith("@@NBPM_LISTENING@@")),
+      "no handshake line when the supervisor env is unset (clean terminal runs)",
+    );
+  } finally {
+    if (prev !== undefined) process.env.NANOBPMN_APP_HANDSHAKE = prev;
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("treats NANOBPMN_APP_HANDSHAKE other than \"1\" as opt-out", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  const prev = process.env.NANOBPMN_APP_HANDSHAKE;
+  process.env.NANOBPMN_APP_HANDSHAKE = "0";
+  try {
+    const lines = await captureStdout(() => app.start());
+    assert.ok(
+      !lines.some((l) => l.startsWith("@@NBPM_LISTENING@@")),
+      '"0" is not the opt-in sentinel ("1"), so no handshake is emitted',
+    );
+  } finally {
+    if (prev === undefined) delete process.env.NANOBPMN_APP_HANDSHAKE;
+    else process.env.NANOBPMN_APP_HANDSHAKE = prev;
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/runtime/core/runtime.ts

@@ -191,9 +191,11 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
         }
 
         const routes: Route[] = [];
+        let hasUiSurfaces = false;
         if (flags.surfaces) {
           const s = mountSurfaces(ctx, api);
           routes.push(...s.routes);
+          hasUiSurfaces = s.routes.length > 0;
           describe.surfaces = s.describe();
         }
         if (flags.triggers) {
@@ -219,6 +221,22 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
           server = await host.serveHttp(port, makeRouter(routes));
           httpPort = server.port;
           host.log("info", "urban app serving surfaces/triggers", { port: httpPort, routes: routes.length });
+          // ADR 0057 boot handshake: under a supervising host (the nano-bpm
+          // Studio sets NANOBPMN_APP_HANDSHAKE), announce the port we actually
+          // bound on a machine-readable stdout control line so the host can
+          // locate the app's UI even when the app picks its port at runtime.
+          // Only emitted when the app actually serves UI surfaces (a trigger- or
+          // worker-only app binds a port too, but it has no webview for the host
+          // to frame), and gated on the env var so direct terminal runs aren't
+          // cluttered. `=== "1"` so an app that sets the var to "0" opts out.
+          if (httpPort !== undefined && hasUiSurfaces && host.env("NANOBPMN_APP_HANDSHAKE") === "1") {
+            try {
+              console.log(`@@NBPM_LISTENING@@${JSON.stringify({ port: httpPort })}`);
+            } catch {
+              // stdout may be closed / non-writable — the handshake is
+              // best-effort telemetry, never fatal to the app.
+            }
+          }
         }
         host.log("info", `urban app "${manifest.id}" started`, {});
       } catch (err) {