@nanobpm/urban 0.48.0 → 0.49.1

package/dist/runtime/core/validate.js

@@ -9,6 +9,7 @@
 // silently — the whole point of consuming the package rather than vendoring a copy.
 import schema from "@nanobpm/nano-app-schema/schema" with { type: "json" };
 import { isRecord } from "./guards.js";
+import { BIND_MODES, NETWORK_KEYS, isBindMode, isConfiguredStatusSelector } from "./manifest.js";
 export class ManifestValidationError extends Error {
     issues;
     constructor(issues) {
@@ -32,6 +33,13 @@ export function collectManifestIssues(m) {
             issues.push({ path: req, message: "required by nano-app.schema.json" });
     }
     const allowed = new Set(Object.keys(S.properties ?? {}));
+    // `network` (issue #235) is threaded as a runtime-side setting until
+    // @nanobpm/nano-app-schema ships the field in its JSON Schema; allow it here so the
+    // envelope check doesn't reject it. Remove this once the schema owns `network` (it
+    // then flows from `S.properties` like every other block). The matching local type
+    // (NetworkConfig) lives in manifest.ts — mirrored like the `api` binding (ADR 0058),
+    // never via a `declare module` augmentation (CI bans augmenting the schema type).
+    allowed.add("network");
     if (S.additionalProperties === false) {
         for (const k of Object.keys(obj)) {
             if (!allowed.has(k)) {
@@ -39,6 +47,28 @@ export function collectManifestIssues(m) {
             }
         }
     }
+    if ("network" in obj) {
+        const network = isRecord(obj.network) ? obj.network : undefined;
+        if (!network) {
+            issues.push({ path: "network", message: "must be an object" });
+        }
+        else {
+            if ("bind" in network && !isBindMode(network.bind)) {
+                issues.push({
+                    path: "network.bind",
+                    message: `must be one of: ${BIND_MODES.map((mode) => `"${mode}"`).join(", ")}`,
+                });
+            }
+            // `network` is mirrored runtime-side until the schema owns it, so this is its only
+            // validation surface: mirror the schema's `additionalProperties: false` intent and
+            // reject unknown keys so typos (e.g. `binn`) fail loudly instead of silently no-op'ing.
+            for (const k of Object.keys(network)) {
+                if (!NETWORK_KEYS.some((known) => known === k)) {
+                    issues.push({ path: `network.${k}`, message: "unknown key (network additionalProperties: false)" });
+                }
+            }
+        }
+    }
     if ("schemaVersion" in obj && obj.schemaVersion !== 1) {
         issues.push({ path: "schemaVersion", message: "must be 1" });
     }
@@ -153,12 +183,46 @@ export function collectManifestIssues(m) {
                     message: "missing onTerminated.set patch (a non-empty column → value map)",
                 });
             }
-            if (Array.isArray(b?.activeStatuses) && (typeof b?.statusField !== "string" || b.statusField.length === 0)) {
+            // `activeStatuses` (fail-closed allow-list) and `terminalStatuses` (fail-open exclusion) are
+            // both consumed as arrays of status strings. A malformed value — a bare string, or an array
+            // holding a non-string/empty entry — would misbehave at runtime (`new Set("abandoned")`
+            // becomes a set of characters; `activeStatuses.map(...)` crashes), so reject any non-`unset`
+            // shape that isn't a non-empty array of non-empty strings. An empty array is treated as
+            // "unset" (the runtime's `isConfiguredStatusSelector` gate does the same), so it is allowed.
+            for (const sel of ["activeStatuses", "terminalStatuses"]) {
+                const v = b?.[sel];
+                const malformed = v !== undefined &&
+                    (!Array.isArray(v) || v.some((s) => typeof s !== "string" || s.length === 0));
+                if (malformed) {
+                    issues.push({
+                        path: `instanceTracking[${i}].${sel}`,
+                        message: `${sel} must be an array of non-empty strings`,
+                    });
+                }
+            }
+            if (isConfiguredStatusSelector(b?.activeStatuses) && (typeof b?.statusField !== "string" || b.statusField.length === 0)) {
                 issues.push({
                     path: `instanceTracking[${i}].activeStatuses`,
                     message: "activeStatuses requires statusField",
                 });
             }
+            // `terminalStatuses` is the fail-open exclusion selector (poll every row NOT in one of
+            // these). Like `activeStatuses` it reads `statusField`, so it too requires one; and the two
+            // selectors are mutually exclusive — declaring both is ambiguous, so reject it.
+            if (isConfiguredStatusSelector(b?.terminalStatuses) && (typeof b?.statusField !== "string" || b.statusField.length === 0)) {
+                issues.push({
+                    path: `instanceTracking[${i}].terminalStatuses`,
+                    message: "terminalStatuses requires statusField",
+                });
+            }
+            // Mutual exclusion is gated on the same "configured" predicate the runtime uses, so an empty
+            // array (which the runtime treats as unset) does not spuriously trip the both-declared error.
+            if (isConfiguredStatusSelector(b?.activeStatuses) && isConfiguredStatusSelector(b?.terminalStatuses)) {
+                issues.push({
+                    path: `instanceTracking[${i}].terminalStatuses`,
+                    message: "activeStatuses and terminalStatuses are mutually exclusive; declare only one",
+                });
+            }
             // `pollMs`, when set, schedules a self-rescheduling timer; a non-number/NaN/non-positive
             // value would become a 0-delay hot loop at runtime, so reject it at author time.
             if (b?.pollMs !== undefined && (typeof b.pollMs !== "number" || !Number.isFinite(b.pollMs) || b.pollMs <= 0)) {

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

@@ -1,4 +1,4 @@
-import type { EngineClient, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, WorkerSubscription } from "../core/host.ts";
+import type { EngineClient, FormSchema, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, WorkerSubscription } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
@@ -81,6 +81,9 @@ export interface NanoSdkClient {
         userTaskKey: string;
         variables?: Record<string, unknown>;
     }, options?: unknown): Promise<unknown>;
+    getFormByKey(input: {
+        formKey: string;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
     searchProcessInstances(input: {
         filter?: Record<string, unknown>;
         page?: Record<string, unknown>;
@@ -137,11 +140,12 @@ export declare class SdkEngineClient implements EngineClient {
         processInstanceKey?: string;
         assignee?: string;
         candidateGroup?: string;
-    }): Promise<{
-        userTaskKey: string;
-        elementId?: string;
-        variables?: Record<string, unknown>;
-    }[]>;
+        state?: UserTaskState;
+    }): Promise<UserTaskSummary[]>;
+    getForm(input: {
+        formKey?: string;
+        formId?: string;
+    }): Promise<FormSchema | null>;
     completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void>;
     searchProcessInstances(filter?: {
         processInstanceKeys?: string[];

package/dist/runtime/engine/nanosdk.js

@@ -18,7 +18,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import { isBpmnError } from "../core/host.js";
+import { isBpmnError, presentFormIdentifier } from "../core/host.js";
 import { isRecord } from "../core/guards.js";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
@@ -101,7 +101,13 @@ export class SdkEngineClient {
     async searchUserTasks(filter) {
         // User tasks are an eventually consistent read; ask for zero-wait consistency so
         // the search reflects what is currently visible without blocking.
-        const body = await this.client.searchUserTasks({ filter: { ...(filter ?? {}) } }, { consistency: { waitUpToMs: 0 } });
+        const body = await this.client.searchUserTasks(
+        // This method is contracted to return *open* tasks; constrain the read to
+        // CREATED so answered/canceled tasks never surface as answerable (e.g. a
+        // re-escalated instance whose prior escalation task is already COMPLETED).
+        // Spread caller filters first and pin `state` last so a caller can never
+        // override the open-only (CREATED) constraint this method contracts to.
+        { filter: { ...(filter ?? {}), state: "CREATED" } }, { consistency: { waitUpToMs: 0 } });
         const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
         return items.flatMap((it) => {
             const userTaskKey = it.userTaskKey ?? it.key;
@@ -109,13 +115,77 @@ export class SdkEngineClient {
                 this.log("warn", "skipping user task with no key in engine response");
                 return [];
             }
+            // The engine resolves a `formId="X"` linkage to the latest deployed form's key at
+            // task creation, so `formKey` (not a form id) is the linkage it reports on the task.
+            const formKey = it.formKey != null && it.formKey !== "" ? String(it.formKey) : undefined;
+            const externalFormReference = typeof it.externalFormReference === "string" && it.externalFormReference !== ""
+                ? it.externalFormReference
+                : undefined;
             return [{
                     userTaskKey: String(userTaskKey),
                     elementId: typeof it.elementId === "string" ? it.elementId : undefined,
                     variables: isRecord(it.variables) ? it.variables : undefined,
+                    ...(formKey ? { formKey } : {}),
+                    ...(externalFormReference ? { externalFormReference } : {}),
                 }];
         });
     }
+    async getForm(input) {
+        // The engine addresses deployed forms by key (`GET /forms/{formKey}`). A user task's
+        // `formKey` is the engine's resolution of its `formId` linkage to the latest deployed
+        // form, so callers pass that key. `formId` is accepted as a fallback identifier for
+        // engines that address a form by its id; either way the engine returns the current
+        // form or 404s (→ null) when there is no such form.
+        //
+        // This is the single gate that resolves which identifier addresses the form: an
+        // empty/whitespace identifier is treated as *absent* (via `presentFormIdentifier`, the
+        // shared presence rule) so a blank `formKey` (e.g. a `?formKey=` query param) falls
+        // through to a valid `formId` instead of being taken as a present-but-unresolvable key
+        // that short-circuits to null.
+        const key = presentFormIdentifier(input.formKey) ?? presentFormIdentifier(input.formId);
+        if (key == null)
+            return null;
+        let body;
+        try {
+            body = await this.client.getFormByKey({ formKey: key }, { consistency: { waitUpToMs: 0 } });
+        }
+        catch (err) {
+            this.log("warn", "getForm: engine form fetch failed", {
+                key,
+                formKey: input.formKey,
+                formId: input.formId,
+                err: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        }
+        if (!isRecord(body))
+            return null;
+        const rawSchema = body.schema;
+        // The engine serializes the form-js schema as a JSON string; parse it to the object
+        // the surface renders. Tolerate an already-parsed object (an in-memory/embedded engine).
+        let schema;
+        if (typeof rawSchema === "string") {
+            try {
+                const parsed = JSON.parse(rawSchema);
+                if (isRecord(parsed))
+                    schema = parsed;
+            }
+            catch {
+                this.log("warn", "getForm: form schema is not valid JSON", { key, formKey: input.formKey, formId: input.formId });
+            }
+        }
+        else if (isRecord(rawSchema)) {
+            schema = rawSchema;
+        }
+        if (!schema)
+            return null;
+        return {
+            schema,
+            ...(body.formKey != null && body.formKey !== "" ? { formKey: String(body.formKey) } : {}),
+            ...(typeof body.formId === "string" && body.formId !== "" ? { formId: body.formId } : {}),
+            ...(typeof body.version === "number" ? { version: body.version } : {}),
+        };
+    }
     async completeUserTask(userTaskKey, variables) {
         await this.client.completeUserTask({ userTaskKey, variables: variables ?? {} });
     }

package/dist/runtime/index.d.ts

@@ -1,7 +1,7 @@
 export { createUrbanApp } from "./core/runtime.ts";
 export type { CreateUrbanAppOptions, MountFlags, UrbanApp, } from "./core/runtime.ts";
-export { expandEnv, expandEnvString, loadManifest, parseManifest, workerJobType, } from "./core/manifest.ts";
-export type { ActionDecl, AppManifest, ChatSurface, DataSource, DomainField, DomainType, LlmBinding, PagesSurface, Surfaces, TaskInboxSurface, Trigger, Worker, } from "./core/manifest.ts";
+export { bindModeToHost, expandEnv, expandEnvString, isBindMode, loadManifest, parseManifest, resolveBindHost, resolveBindMode, workerJobType, ALL_INTERFACES_HOST, BIND_ENV_VAR, LOOPBACK_HOST, } from "./core/manifest.ts";
+export type { ActionDecl, AppManifest, BindMode, ChatSurface, DataSource, DomainField, DomainType, LlmBinding, NetworkConfig, PagesSurface, Surfaces, TaskInboxSurface, Trigger, Worker, } from "./core/manifest.ts";
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.ts";
 export type { ValidationIssue } from "./core/validate.ts";
 export type { EngineClient, EngineJob, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, SqliteDb, WatchHandle, WorkerSubscription, } from "./core/host.ts";
@@ -30,9 +30,7 @@ export { resolveHandler, sdkDecisionEvaluator } from "./core/modules/workers.ts"
 export { buildMessages, callLlm, resolveProvider, runLlmJob, } from "./core/modules/llm.ts";
 export type { ChatMessage, DecisionEvaluator, EnvLookup, LlmRuntime, LlmVars, ProviderConfig, } from "./core/modules/llm.ts";
 export { evalCorrelation } from "./core/modules/triggers.ts";
-export { deployModels } from "./core/modules/deploy.ts";
-export { applyTemplates, resolveTemplates } from "./core/modules/templates.ts";
-export type { TemplateApplication, TemplateSource } from "./core/modules/templates.ts";
+export { deployModels, RESOURCES_DIR } from "./core/modules/deploy.ts";
 export { defaultScheduler, MAX_TIMER_DELAY_MS } from "./core/modules/scheduler.ts";
 export type { SchedulerDeps } from "./core/modules/scheduler.ts";
 export { createNodeHost } from "./adapters/node.ts";

package/dist/runtime/index.js

@@ -2,7 +2,7 @@
 // Core runtime
 export { createUrbanApp } from "./core/runtime.js";
 // Manifest
-export { expandEnv, expandEnvString, loadManifest, parseManifest, workerJobType, } from "./core/manifest.js";
+export { bindModeToHost, expandEnv, expandEnvString, isBindMode, loadManifest, parseManifest, resolveBindHost, resolveBindMode, workerJobType, ALL_INTERFACES_HOST, BIND_ENV_VAR, LOOPBACK_HOST, } from "./core/manifest.js";
 // Validation
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.js";
 // Structured logging surface (see core/logger.ts): the shape of `AppApi.log`, plus `createLogger`
@@ -24,9 +24,8 @@ export { defineOperation, mountApi, resolveOperationHandler, NotImplemented } fr
 export { resolveHandler, sdkDecisionEvaluator } from "./core/modules/workers.js";
 export { buildMessages, callLlm, resolveProvider, runLlmJob, } from "./core/modules/llm.js";
 export { evalCorrelation } from "./core/modules/triggers.js";
-// Model deploy + `{{name}}` template substitution
-export { deployModels } from "./core/modules/deploy.js";
-export { applyTemplates, resolveTemplates } from "./core/modules/templates.js";
+// Model deploy (deploy-by-convention under `resources/`, ADR 0062)
+export { deployModels, RESOURCES_DIR } from "./core/modules/deploy.js";
 export { defaultScheduler, MAX_TIMER_DELAY_MS } from "./core/modules/scheduler.js";
 // Adapters + engine + run entrypoint
 export { createNodeHost } from "./adapters/node.js";

package/dist/runtime/run.js

@@ -27,7 +27,6 @@ export async function runFromEnv(opts = {}) {
         manifestPath: opts.manifestPath,
         port: opts.port,
         mount: opts.mount,
-        templates: opts.templates,
     });
     await app.start();
     if (opts.handleSignals !== false)

package/dist/toolkit/fsio.js

@@ -31,6 +31,15 @@ export function createNodeGenIO() {
                 return [];
             }
         },
+        async listSubdirs(path) {
+            try {
+                const entries = await readdir(path, { withFileTypes: true });
+                return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+            }
+            catch {
+                return [];
+            }
+        },
         async exists(path) {
             try {
                 await stat(path);

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

@@ -46,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. */

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.48.0",
+	"version": "0.49.1",
 	"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();
+  }
+});