@nanobpm/urban 0.47.0 → 0.49.0

package/dist/toolkit/gen.d.ts

@@ -7,6 +7,12 @@ export interface GenIO {
     writeText(path: string, content: string): Promise<void>;
     /** File names (not paths) in a directory; empty if it does not exist. */
     listDir(path: string): Promise<string[]>;
+    /**
+     * Sub-directory names (not files) in a directory; empty if it does not exist. Optional: the
+     * deploy-by-convention model scan uses it to descend one level into `resources/<subdir>/`. When
+     * absent, only files directly under `resources/` are scanned.
+     */
+    listSubdirs?(path: string): Promise<string[]>;
     exists(path: string): Promise<boolean>;
     /**
      * Import an app module and return its exports. Optional: only present when the caller runs on
@@ -50,7 +56,26 @@ declare function join(root: string, rel: string): string;
 declare function dirOf(p: string): string;
 /** Resolve a `dir/*.ext` (or literal) manifest pattern to file paths relative to root. */
 export declare function expandPattern(root: string, io: GenIO, pattern: string): Promise<string[]>;
-/** Read + resolve the app's process models from the manifest's `models.processes` patterns. */
+/** The deploy-by-convention directory (ADR 0062): when the manifest declares no `models`, both the
+ *  runtime deploy and this codegen scan discover deployables/models under it — shallow, one level
+ *  deep (`resources/*` and `resources/<subdir>/*`). Deploy-only by convention. */
+export declare const RESOURCES_DIR = "resources";
+/**
+ * Discover model files under `resources/` by convention — shallow, one level deep (`resources/*`
+ * and `resources/<subdir>/*`), never deeper — mirroring the runtime deploy walk so the codegen scan
+ * and the deploy see the same set. Returns root-relative paths, sorted. Descending one level needs
+ * `io.listSubdirs`; without it only the files directly under `resources/` are scanned.
+ */
+export declare function discoverResourceModels(root: string, io: GenIO): Promise<string[]>;
+/**
+ * Read + resolve the app's process models. Convention is keyed off the *absence* of the entire
+ * `models` block — mirroring the runtime deploy (ADR 0062): with no `models` block, models are
+ * discovered by convention under `resources/`; with a `models` block declared, `models.processes`
+ * is the explicit override (used verbatim, possibly empty). Keying off a missing `models.processes`
+ * alone would fall back to convention even when a `models` block is present for other overrides
+ * (e.g. forms), letting gen scan/derive process models the runtime deploy will never deploy —
+ * gen/runtime drift.
+ */
 export declare function readModels(root: string, io: GenIO, manifest: {
     models?: {
         processes?: string[];

package/dist/toolkit/gen.js

@@ -4,10 +4,11 @@
 // pure; all IO is confined here behind a tiny FS port so the same code runs on Node and Deno.
 import { GENERATED_DIR, isAbsolutePath, RUNTIME_MATERIALIZED_ARTIFACTS, sortArtifacts } from "./artifact.js";
 import { deriveMigrations } from "./derivers/migrations.js";
-import { deriveDomain } from "./derivers/domain.js";
-import { deriveWorkerBindings } from "./derivers/worker-io.js";
+import { emitDomainModel, registryFromManifest, sourcesFromManifest } from "./derivers/domain.js";
+import { byModelPath, deriveWorkerBindings, detectEnvelopeConflicts, DOMAIN_DTS, formatEnvelopeConflict, scanModelWorkers } from "./derivers/worker-io.js";
 import { deriveMeta } from "./derivers/meta.js";
 import { deriveMessageBindings } from "./derivers/messages.js";
+import { resolveShapes, scanModelShapes } from "./derivers/shapes.js";
 import { deriveApi } from "./derivers/api.js";
 import { parseSpec, sharedRequestBodySchemas } from "../openapi/spec.js";
 import { deriveModels, MODEL_PROVENANCE } from "./models.js";
@@ -45,15 +46,63 @@ export async function expandPattern(root, io, pattern) {
         .map((n) => (dir === "." ? n : `${dir}/${n}`))
         .sort();
 }
-/** Read + resolve the app's process models from the manifest's `models.processes` patterns. */
+/** The deploy-by-convention directory (ADR 0062): when the manifest declares no `models`, both the
+ *  runtime deploy and this codegen scan discover deployables/models under it — shallow, one level
+ *  deep (`resources/*` and `resources/<subdir>/*`). Deploy-only by convention. */
+export const RESOURCES_DIR = "resources";
+/** Model file extensions the `nano:shape`/code-first scan reads by convention (BPMN + DMN). */
+const MODEL_EXTS = [".bpmn", ".dmn"];
+/**
+ * Discover model files under `resources/` by convention — shallow, one level deep (`resources/*`
+ * and `resources/<subdir>/*`), never deeper — mirroring the runtime deploy walk so the codegen scan
+ * and the deploy see the same set. Returns root-relative paths, sorted. Descending one level needs
+ * `io.listSubdirs`; without it only the files directly under `resources/` are scanned.
+ */
+export async function discoverResourceModels(root, io) {
+    const isModel = (n) => MODEL_EXTS.some((e) => n.endsWith(e));
+    const out = [];
+    for (const n of await io.listDir(join(root, RESOURCES_DIR))) {
+        if (isModel(n))
+            out.push(`${RESOURCES_DIR}/${n}`);
+    }
+    const subdirs = io.listSubdirs ? await io.listSubdirs(join(root, RESOURCES_DIR)) : [];
+    for (const sub of subdirs.slice().sort()) {
+        for (const n of await io.listDir(join(root, `${RESOURCES_DIR}/${sub}`))) {
+            if (isModel(n))
+                out.push(`${RESOURCES_DIR}/${sub}/${n}`);
+        }
+    }
+    return out.sort();
+}
+/**
+ * Read + resolve the app's process models. Convention is keyed off the *absence* of the entire
+ * `models` block — mirroring the runtime deploy (ADR 0062): with no `models` block, models are
+ * discovered by convention under `resources/`; with a `models` block declared, `models.processes`
+ * is the explicit override (used verbatim, possibly empty). Keying off a missing `models.processes`
+ * alone would fall back to convention even when a `models` block is present for other overrides
+ * (e.g. forms), letting gen scan/derive process models the runtime deploy will never deploy —
+ * gen/runtime drift.
+ */
 export async function readModels(root, io, manifest) {
-    const procPatterns = manifest.models?.processes ?? [];
-    const models = [];
-    for (const pat of procPatterns) {
-        for (const rel of await expandPattern(root, io, pat)) {
-            models.push({ path: rel, xml: await io.readText(join(root, rel)) });
+    const byConvention = manifest.models === undefined;
+    let rels;
+    if (byConvention) {
+        rels = await discoverResourceModels(root, io);
+    }
+    else {
+        rels = [];
+        for (const pat of manifest.models?.processes ?? []) {
+            rels.push(...(await expandPattern(root, io, pat)));
         }
     }
+    const models = [];
+    const seen = new Set();
+    for (const rel of rels) {
+        if (seen.has(rel))
+            continue;
+        seen.add(rel);
+        models.push({ path: rel, xml: await io.readText(join(root, rel)) });
+    }
     return models;
 }
 /** Collect all artifacts a run would produce, without touching disk beyond reads. */
@@ -69,28 +118,60 @@ async function collectAll(opts) {
     const manifest = JSON.parse(await io.readText(manifestPath));
     const artifacts = [];
     const warnings = [];
-    // 1. types → migrations + domain row types (DomainTables spine + DomainTypes registry)
-    if (!opts.modelsOnly && manifest.types && Object.keys(manifest.types).length > 0) {
-        artifacts.push(...deriveMigrations(manifest));
-        artifacts.push(...deriveDomain(manifest));
-    }
-    // 2. code-first models → derive BPMN from `workflows/*.ts` (executes the app's TS). The derived
-    //    `.bpmn` are emitted only when `emitModels` (default), but always fed to the type-contract
-    //    derivers below so worker I/O works for a code-first app even on a `--no-models` run.
+    // 1. Resolve the app's models first (code-first `workflows/*.ts` → BPMN, plus authored on-disk
+    //    `.bpmn`): the fused domain model (below) lifts `nano:shape` envelopes *from* the models, so
+    //    they must be in hand before the domain + worker/message type-contracts are derived.
     const derived = await deriveModels(root, io, manifest);
+    //    The derived `.bpmn` are emitted only when `emitModels` (default), but always fed to the
+    //    type-contract derivers so worker I/O works for a code-first app even on a `--no-models` run.
     if (emitModels)
         artifacts.push(...derived.artifacts);
-    // 3. models (authored on-disk + derived) → worker I/O index + meta accessor + message map.
-    //    Drop any on-disk model whose path a derived model already covers, to avoid double-counting.
+    const derivedPaths = new Set(derived.artifacts.map((a) => a.path));
+    const diskModels = (await readModels(root, io, manifest)).filter((m) => !derivedPaths.has(m.path));
+    const models = [...diskModels, ...derived.models];
+    // 2. Fused domain model (ADR 0040): the `DomainTypes` registry is the union of the manifest
+    //    `types` registry and the model-authored `nano:shape` envelopes, resolved through the same
+    //    fuse the console reifier (`envelope_scan.rs`) uses. Without this the standalone `urban gen`
+    //    would honour only `manifest.types` and silently ignore every model-authored data envelope,
+    //    so worker/message I/O against those envelopes would fall back to the untyped `WorkerVars`.
+    const manifestRegistry = registryFromManifest(manifest);
+    const sources = sourcesFromManifest(manifest);
+    const shapeDecls = models.flatMap((m) => scanModelShapes(m.xml));
+    const shapeResolution = resolveShapes(shapeDecls, manifestRegistry, sources);
+    const fusedTypes = { ...manifestRegistry, ...shapeResolution.types };
+    for (const d of shapeResolution.diagnostics) {
+        warnings.push(`data-envelope shape "${d.shape}" (${d.kind}): ${d.message}`);
+    }
+    // 3. types → migrations (persisted `manifest.types` only — shapes are transient wire envelopes,
+    //    never tables) + the fused domain row types (`DomainTables` spine + `DomainTypes` registry).
+    if (!opts.modelsOnly && manifest.types && Object.keys(manifest.types).length > 0) {
+        artifacts.push(...deriveMigrations(manifest));
+    }
+    if (!opts.modelsOnly && Object.keys(fusedTypes).length > 0) {
+        artifacts.push({
+            path: `${GENERATED_DIR}/${DOMAIN_DTS}`,
+            content: emitDomainModel(sources, manifest.data?.default ?? "app", fusedTypes),
+        });
+    }
+    // 4. models (authored on-disk + derived) → worker I/O index + meta accessor + message map. The
+    //    declared type ids include the fused shapes, so an envelope ref to a model-authored shape
+    //    resolves to its `DomainTypes[...]` entry instead of degrading to the untyped fallback.
     if (!opts.modelsOnly) {
-        const derivedPaths = new Set(derived.artifacts.map((a) => a.path));
-        const diskModels = (await readModels(root, io, manifest)).filter((m) => !derivedPaths.has(m.path));
-        const models = [...diskModels, ...derived.models];
         if (models.length > 0) {
-            const declaredTypeIds = Object.keys(manifest.types ?? {});
+            const declaredTypeIds = Object.keys(fusedTypes);
             artifacts.push(...deriveWorkerBindings(models, declaredTypeIds));
             artifacts.push(...deriveMeta(models));
             artifacts.push(...deriveMessageBindings(models, declaredTypeIds));
+            // Surface genuine data-envelope conflicts: a taskType whose variants disagree on a field's
+            // TYPE. The emitted contract is the union of the variants (sound for a shared handler), so a
+            // type clash would silently widen to `A | B` — warn instead so the author unifies the envelope.
+            const scannedWorkers = [...models]
+                .sort(byModelPath)
+                .flatMap((m) => scanModelWorkers(m.xml))
+                .map((w) => ({ taskType: w.taskType, inputType: w.in, outputType: w.out }));
+            for (const c of detectEnvelopeConflicts(scannedWorkers, fusedTypes)) {
+                warnings.push(formatEnvelopeConflict(c));
+            }
         }
     }
     // 4. OpenAPI `api` binding → typed endpoint contracts (ADR 0058). Fail-closed: a declared spec

package/dist/toolkit/models.d.ts

@@ -4,9 +4,11 @@ import type { GenIO } from "./gen.ts";
 import type { ModelSource } from "./derivers/worker-io.ts";
 /** Default source glob for code-first flows (matches the code-first scaffold layout). */
 export declare const DEFAULT_WORKFLOW_PATTERNS: string[];
-/** Default output dir for derived models (matches the model-first scaffold, so a derived
- * model is ejectable to model-first and picked up by `models.processes: ["processes/*.bpmn"]`). */
-export declare const PROCESSES_DIR = "processes";
+/** Default output dir for derived models when the manifest declares no `models.processes`: under
+ * the deploy-by-convention `resources/` tree (ADR 0062), one level deep, so a derived model lands
+ * exactly where the convention deploy + codegen scan look for it. When `models.processes` IS set,
+ * `processesOutDir` derives the dir from that glob instead (the model-first override). */
+export declare const PROCESSES_DIR = "resources/processes";
 /** Marker stamped into every derived `.bpmn` (an XML comment) so re-gen overwrites and the
  * stale sweep deletes ONLY derived output — never an authored, human-owned model. */
 export declare const MODEL_PROVENANCE = "Generated by @nanobpm/urban from workflows/*.ts \u2014 do not edit; edit the flow and re-run `urban gen`.";
@@ -29,7 +31,7 @@ export interface ModelError {
     message: string;
 }
 export interface DerivedModels {
-    /** `processes/<id>.bpmn` artifacts (path + provenance-stamped content). */
+    /** `resources/processes/<id>.bpmn` artifacts (path + provenance-stamped content). */
     artifacts: DerivedArtifact[];
     /** The same models, in-memory, for feeding the type-contract derivers (worker I/O, meta, messages). */
     models: ModelSource[];

package/dist/toolkit/models.js

@@ -2,7 +2,8 @@
 //
 // Unlike the pure derivers (migrations, domain, worker I/O), which transform strings, this
 // imports the app's `workflows/*.ts`, turns each `defineFlow` into executable BPMN via
-// `@nanobpm/workflow` (`toBpmn` + `bpmn-auto-layout` DI), and writes `processes/<id>.bpmn`.
+// `@nanobpm/workflow` (`toBpmn` + `bpmn-auto-layout` DI), and writes `resources/processes/<id>.bpmn`
+// (the deploy-by-convention `resources/` tree, ADR 0062 — see `PROCESSES_DIR`).
 // Executing the app's TypeScript needs a runtime module loader, so this is gated on the
 // optional `GenIO.importModule` (present on Node with type-stripping, and on Deno). When the
 // loader is absent — or the app authors its models directly (model-first) — derivation is a
@@ -12,9 +13,11 @@ import { expandPattern, joinPath } from "./gen.js";
 import { isRecord } from "../runtime/core/guards.js";
 /** Default source glob for code-first flows (matches the code-first scaffold layout). */
 export const DEFAULT_WORKFLOW_PATTERNS = ["workflows/*.ts"];
-/** Default output dir for derived models (matches the model-first scaffold, so a derived
- * model is ejectable to model-first and picked up by `models.processes: ["processes/*.bpmn"]`). */
-export const PROCESSES_DIR = "processes";
+/** Default output dir for derived models when the manifest declares no `models.processes`: under
+ * the deploy-by-convention `resources/` tree (ADR 0062), one level deep, so a derived model lands
+ * exactly where the convention deploy + codegen scan look for it. When `models.processes` IS set,
+ * `processesOutDir` derives the dir from that glob instead (the model-first override). */
+export const PROCESSES_DIR = "resources/processes";
 /** Marker stamped into every derived `.bpmn` (an XML comment) so re-gen overwrites and the
  * stale sweep deletes ONLY derived output — never an authored, human-owned model. */
 export const MODEL_PROVENANCE = "Generated by @nanobpm/urban from workflows/*.ts — do not edit; edit the flow and re-run `urban gen`.";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.47.0",
+	"version": "0.49.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/adapters/deno.ts

@@ -17,6 +17,7 @@ import type {
   SqliteDb,
 } from "../core/host.ts";
 import { resolveModulePath } from "../core/module-path.ts";
+import { LOOPBACK_HOST } from "../core/manifest.ts";
 import { formatLogRecord, levelEnabled, parseLogLevel } from "../core/logger.ts";
 
 type SqliteParam = string | number | bigint | Uint8Array | null;
@@ -48,11 +49,11 @@ interface DenoGlobal {
   env: { get(name: string): string | undefined };
   cwd(): string;
   readTextFile(path: string): Promise<string>;
-  readDir(path: string): AsyncIterable<{ name: string; isFile: boolean }>;
+  readDir(path: string): AsyncIterable<{ name: string; isFile: boolean; isDirectory: boolean }>;
   stat(path: string): Promise<unknown>;
   watchFs(paths: string | string[], options?: { recursive?: boolean }): DenoFsWatcher;
   serve(
-    opts: { port: number; onListen?: (a: { port: number }) => void },
+    opts: { port: number; hostname?: string; onListen?: (a: { port: number }) => void },
     handler: (req: Request) => Response | Promise<Response>,
   ): DenoHttpServer;
 }
@@ -104,6 +105,17 @@ export function createDenoHost(opts: DenoHostOptions = {}): HostContext {
         return [];
       }
     },
+    async listSubdirs(dir) {
+      try {
+        const names: string[] = [];
+        for await (const e of Deno.readDir(abs(dir))) {
+          if (e.isDirectory) names.push(e.name);
+        }
+        return names;
+      } catch {
+        return [];
+      }
+    },
     async exists(p) {
       try {
         await Deno.stat(abs(p));
@@ -123,8 +135,8 @@ export function createDenoHost(opts: DenoHostOptions = {}): HostContext {
       const mod: Promise<Record<string, unknown>> = import(href);
       return mod;
     },
-    async serveHttp(port, handler) {
-      return startDenoServer(port, handler);
+    async serveHttp(port, handler, bindHost) {
+      return startDenoServer(port, handler, bindHost);
     },
     watch(onChange) {
       const w = Deno.watchFs(cwd, { recursive: true });
@@ -177,9 +189,17 @@ function wrapSqlite(db: DatabaseSync): SqliteDb {
   };
 }
 
-function startDenoServer(port: number, handler: HttpHandler): Promise<HttpServer> {
+function startDenoServer(
+  port: number,
+  handler: HttpHandler,
+  bindHost?: string,
+): Promise<HttpServer> {
   return new Promise<HttpServer>((resolveServer) => {
-    const server = Deno.serve({ port, onListen: ({ port: p }) => {
+    // `hostname` binds the interface (issue #235): `"127.0.0.1"` loopback-only, `"0.0.0.0"`
+    // all interfaces. When no bind host is resolved we fail *closed* to loopback rather than
+    // inheriting Deno's default, so a caller that omits it can never silently expose the server
+    // off-box.
+    const server = Deno.serve({ port, hostname: bindHost ?? LOOPBACK_HOST, onListen: ({ port: p }) => {
       resolveServer({
         port: p,
         stop: () => server.shutdown(),

package/src/runtime/adapters/node.test.ts

@@ -0,0 +1,67 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import * as http from "node:http";
+import { createNodeHost } from "./node.ts";
+import type { HttpServer } from "../core/host.ts";
+
+// Issue #235: the node adapter must bind the interface it is handed so the manifest's
+// `network.bind` setting actually controls off-box reachability. We assert the *listen host*
+// the socket bound to for each setting by reading the native server's address.
+function boundAddress(server: HttpServer): string {
+  const native = server.native;
+  assert.ok(native instanceof http.Server, "adapter exposes a node http.Server as native");
+  const addr = native.address();
+  assert.ok(addr && typeof addr === "object", "server has a bound AddressInfo");
+  return addr.address;
+}
+
+test("serveHttp binds loopback when handed 127.0.0.1 (refuses off-box)", async () => {
+  const host = createNodeHost({ log: () => {} });
+  const server = await host.serveHttp(0, () => ({ status: 200 }), "127.0.0.1");
+  try {
+    assert.equal(boundAddress(server), "127.0.0.1");
+  } finally {
+    await server.stop();
+  }
+});
+
+test("serveHttp binds all interfaces when handed 0.0.0.0 (reachable on the LAN)", async () => {
+  const host = createNodeHost({ log: () => {} });
+  const server = await host.serveHttp(0, () => ({ status: 200 }), "0.0.0.0");
+  try {
+    assert.equal(boundAddress(server), "0.0.0.0");
+  } finally {
+    await server.stop();
+  }
+});
+
+// Issue #235 (fail closed): omitting the bind host must NOT inherit Node's bind-all default —
+// a caller that forgets to resolve one should still get loopback, never off-box exposure.
+test("serveHttp fails closed to loopback when no bind host is given", async () => {
+  const host = createNodeHost({ log: () => {} });
+  const server = await host.serveHttp(0, () => ({ status: 200 }));
+  try {
+    assert.equal(boundAddress(server), "127.0.0.1");
+  } finally {
+    await server.stop();
+  }
+});
+
+// A bind failure (EADDRINUSE) must reject the serveHttp promise instead of hanging forever
+// waiting for a `listening` event that never fires.
+test("serveHttp rejects when the port is already in use (does not hang)", async () => {
+  const host = createNodeHost({ log: () => {} });
+  const first = await host.serveHttp(0, () => ({ status: 200 }), "127.0.0.1");
+  const taken = first.native;
+  assert.ok(taken instanceof http.Server);
+  const addr = taken.address();
+  assert.ok(addr && typeof addr === "object");
+  try {
+    await assert.rejects(
+      () => host.serveHttp(addr.port, () => ({ status: 200 }), "127.0.0.1"),
+      (err: NodeJS.ErrnoException) => err.code === "EADDRINUSE",
+    );
+  } finally {
+    await first.stop();
+  }
+});

package/src/runtime/adapters/node.ts

@@ -21,6 +21,7 @@ import type {
   WatchHandle,
 } from "../core/host.ts";
 import { resolveModulePath } from "../core/module-path.ts";
+import { LOOPBACK_HOST } from "../core/manifest.ts";
 import { formatLogLine, levelEnabled, parseLogLevel } from "../core/logger.ts";
 
 /**
@@ -137,6 +138,14 @@ export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
         return [];
       }
     },
+    async listSubdirs(dir) {
+      try {
+        const entries = await readdir(abs(dir), { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+      } catch {
+        return [];
+      }
+    },
     async exists(p) {
       try {
         await stat(abs(p));
@@ -166,8 +175,8 @@ export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
         pathToFileURL(abs(entry)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
       await import(href);
     },
-    async serveHttp(port, handler) {
-      return await startNodeServer(port, handler);
+    async serveHttp(port, handler, bindHost) {
+      return await startNodeServer(port, handler, bindHost);
     },
     watch(onChange) {
       const onFsEvent = (_event: unknown, filename: string | Buffer | null) => {
@@ -216,7 +225,11 @@ function wrapNodeSqlite(db: DatabaseSync): SqliteDb {
   };
 }
 
-async function startNodeServer(port: number, handler: HttpHandler): Promise<HttpServer> {
+async function startNodeServer(
+  port: number,
+  handler: HttpHandler,
+  bindHost?: string,
+): Promise<HttpServer> {
   const server = createServer(async (nreq, nres) => {
     const chunks: Buffer[] = [];
     for await (const c of nreq) {
@@ -263,7 +276,27 @@ async function startNodeServer(port: number, handler: HttpHandler): Promise<Http
     sockets.add(socket);
     socket.once("close", () => sockets.delete(socket));
   });
-  await new Promise<void>((res) => server.listen(port, res));
+  // Bind to the requested interface (issue #235): `"127.0.0.1"` keeps the app loopback-only
+  // (secure default), `"0.0.0.0"` exposes it on the LAN. When no bind host is resolved we fail
+  // *closed* to loopback rather than inheriting Node's bind-all default, so a caller that omits
+  // it can never silently expose the server off-box.
+  const listenHost = bindHost ?? LOOPBACK_HOST;
+  // `server.listen` reports bind failures (EADDRINUSE/EACCES/…) via the `error` event, not the
+  // listening callback. Reject on the first such error so callers see the failure instead of
+  // hanging forever waiting for a `listening` that will never fire.
+  await new Promise<void>((res, rej) => {
+    const onError = (err: Error) => {
+      server.removeListener("listening", onListening);
+      rej(err);
+    };
+    const onListening = () => {
+      server.removeListener("error", onError);
+      res();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, listenHost);
+  });
   const addr = server.address();
   const actualPort = typeof addr === "object" && addr ? addr.port : port;
   return {

package/src/runtime/core/context.ts

@@ -1,7 +1,6 @@
 import type { AppManifest } from "./manifest.ts";
 import type { EngineClient, HostContext } from "./host.ts";
 import type { EngineSdkClient } from "../engine/sdk.ts";
-import type { TemplateSource } from "./modules/templates.ts";
 
 /** Everything a runtime module needs. Passed to each module's mount function. */
 export interface RuntimeContext {
@@ -10,9 +9,6 @@ export interface RuntimeContext {
   engine: EngineClient;
   /** App root directory (paths in the manifest are relative to this). */
   root: string;
-  /** Programmatic `{{name}}` template source for deploy-time substitution (globs or a
-   *  `name → content` map), merged over the manifest's `models.templates`. See `deployModels`. */
-  templates?: TemplateSource;
 }
 
 /** A mounted module returns a disposer so the runtime can tear it down cleanly. */

package/src/runtime/core/glob.ts

@@ -61,3 +61,27 @@ export async function expandPatterns(
   }
   return out;
 }
+
+/**
+ * Discover deployables under a convention directory (`resources/`), **shallow, one level deep**:
+ * the files directly under `dir` plus the files one sub-directory down (`dir/<subdir>/*`), but
+ * never deeper. The shallow bound is deliberate — deploy dedupes by basename (filename only), so a
+ * deep recursive walk would reintroduce cross-directory basename-collision risk. Sub-directory
+ * descent needs `host.listSubdirs`; a host that can't enumerate directories yields only the
+ * top-level files. Returns root-prefixed paths, sorted for determinism.
+ */
+export async function discoverResources(
+  host: HostContext,
+  root: string,
+  dir: string,
+): Promise<string[]> {
+  const base = joinPath(root, dir);
+  const out: string[] = [];
+  for (const name of await host.listDir(base)) out.push(joinPath(base, name));
+  const subdirs = host.listSubdirs ? await host.listSubdirs(base) : [];
+  for (const sub of subdirs.slice().sort()) {
+    const subBase = joinPath(base, sub);
+    for (const name of await host.listDir(subBase)) out.push(joinPath(subBase, name));
+  }
+  return out.sort();
+}

package/src/runtime/core/host.ts

@@ -80,6 +80,12 @@ export interface HostContext {
   readTextFile(path: string): Promise<string>;
   /** List file names (not directories) directly under `dir`. Returns [] if missing. */
   listDir(dir: string): Promise<string[]>;
+  /**
+   * List sub-directory names (not files) directly under `dir`. Returns [] if missing. Optional:
+   * the deploy-by-convention walk uses it to descend one level into `resources/<subdir>/` (a host
+   * that can't enumerate directories then deploys only the files directly under `resources/`).
+   */
+  listSubdirs?(dir: string): Promise<string[]>;
   /** True if the path exists (file or directory). */
   exists(path: string): Promise<boolean>;
   /** Open (creating if needed) a SQLite database at a filesystem path. */
@@ -99,8 +105,16 @@ export interface HostContext {
    * connector mount then reports the workers as unsupported rather than crashing.
    */
   importConnectorModule?(entry: string): Promise<void>;
-  /** Start an HTTP server. Routing is done by the caller inside `handler`. */
-  serveHttp(port: number, handler: HttpHandler): Promise<HttpServer>;
+  /**
+   * Start an HTTP server. Routing is done by the caller inside `handler`. `bindHost` is the
+   * network interface to bind (e.g. `"127.0.0.1"` for loopback, `"0.0.0.0"` for all interfaces);
+   * the runtime always resolves it from the manifest `network.bind` setting (issue #235,
+   * loopback by default). It stays optional so hosts that can't bind-control still satisfy the
+   * contract, but the built-in node/deno adapters fail *closed* to loopback when it is omitted —
+   * they never inherit a bind-all default — so the secure-by-default guarantee can't silently
+   * regress.
+   */
+  serveHttp(port: number, handler: HttpHandler, bindHost?: string): Promise<HttpServer>;
   /**
    * Recursively watch the app root for file changes, invoking `onChange` with the
    * changed path (app-root-relative when the runtime reports it that way). Optional:
@@ -174,6 +188,20 @@ export function isBpmnError(err: unknown): err is { errorCode: string; message?:
   );
 }
 
+/**
+ * The canonical presence rule for a form identifier ({@link EngineClient.getForm}): an
+ * empty or whitespace-only value is treated as *absent*. Returns the *trimmed* value when
+ * present (so a padded `" form-123 "` resolves against the space-free deployed key),
+ * otherwise `undefined`. This is the single source of truth shared by `getForm`'s
+ * resolution gate ({@link EngineClient.getForm} adapters) and the `taskInbox`
+ * `/api/form` route's presence check, so the two cannot drift on what counts as "an
+ * identifier was provided" (e.g. a whitespace-only `?formKey=   ` is absent in both).
+ */
+export function presentFormIdentifier(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
 /** A registered worker subscription. */
 export interface WorkerSubscription {
   readonly jobType: string;
@@ -195,6 +223,37 @@ export interface ProcessInstanceSnapshot {
   readonly state: ProcessInstanceState;
 }
 
+/**
+ * A single open user task as {@link EngineClient.searchUserTasks} reports it. Carries the
+ * task's identity plus its resolved form linkage so the `taskInbox` surface (ADR 0026) can
+ * fetch and render the linked `.form`. `formKey` is the engine's resolution of a
+ * `<zeebe:formDefinition formId="X" />` linkage to the latest deployed form at task-creation
+ * time; `externalFormReference` is a form linked outside the deployment. Both are absent for a
+ * task with no linked form (the surface then falls back to the raw key-list + complete path).
+ */
+export interface UserTaskSummary {
+  readonly userTaskKey: string;
+  readonly elementId?: string;
+  readonly variables?: Record<string, unknown>;
+  /** The resolved key of the linked deployed form, if the task has one. */
+  readonly formKey?: string;
+  /** An external form reference (a form linked outside the deployment), if any. */
+  readonly externalFormReference?: string;
+}
+
+/**
+ * A deployed form's form-js schema plus its identifying metadata, as
+ * {@link EngineClient.getForm} returns it. `schema` is the parsed form-js document
+ * (`{ type: "default", schemaVersion, components: [...] }`) that the surface renders
+ * client-side; `formKey`/`formId`/`version` identify the exact deployed form resolved.
+ */
+export interface FormSchema {
+  readonly formKey?: string;
+  readonly formId?: string;
+  readonly version?: number;
+  readonly schema: Record<string, unknown>;
+}
+
 /**
  * EngineClient is the seam onto a Nano engine. The SDK/REST-backed adapter implements
  * it against a live engine; tests implement it in-memory. Core modules depend only on this.
@@ -218,12 +277,23 @@ export interface EngineClient {
     correlationKey?: string;
     variables?: Record<string, unknown>;
   }): Promise<void>;
-  /** Search open user tasks (optionally by process instance). */
+  /** Search open user tasks (optionally by process instance). Each result carries the
+   *  task's resolved form linkage (`formKey`/`externalFormReference`) when present. */
   searchUserTasks(filter?: {
     processInstanceKey?: string;
     assignee?: string;
     candidateGroup?: string;
-  }): Promise<{ userTaskKey: string; elementId?: string; variables?: Record<string, unknown> }[]>;
+  }): Promise<UserTaskSummary[]>;
+  /**
+   * Fetch a deployed form's form-js schema for the `taskInbox` surface. Resolve by
+   * `formKey` (the linkage the engine attaches to a user task) or, as a best-effort
+   * fallback, by `formId`. An empty or whitespace-only identifier is treated as absent,
+   * so a blank `formKey` falls through to `formId`. How `formId` is addressed is
+   * adapter-specific: an adapter may pass it straight through as the lookup key, or
+   * resolve it to the latest deployed form's key. Returns `null` when no matching form
+   * exists — the caller then falls back to the no-form path.
+   */
+  getForm(input: { formKey?: string; formId?: string }): Promise<FormSchema | null>;
   /** Complete a user task. */
   completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void>;
   /**