@nanobpm/urban 0.48.0 → 0.49.1

package/README.md

@@ -52,6 +52,38 @@ The engine address comes from `$CAMUNDA_REST_ADDRESS` (default
 serving to Falcon on a Nano server and falls back to REST elsewhere. Set it to
 `rest`, `falcon`, or `embedded` to pin a specific transport.
 
+### Network bind interface
+
+By default an app's HTTP server binds to **loopback only** (`127.0.0.1`) — secure
+by default, so surfaces, triggers and capability hooks are unreachable from other
+machines. To make the app reachable from other hosts on the LAN (e.g. a
+distributed worker fleet), opt in with the app-level `network.bind` manifest
+setting:
+
+```jsonc
+// nano.app.json
+{
+  "network": { "bind": "loopback" }  // default — 127.0.0.1, refuses off-box connections
+  // "network": { "bind": "all" }    // 0.0.0.0 — reachable across the LAN
+}
+```
+
+| `network.bind` | Bind address | Reachability |
+|---|---|---|
+| `"loopback"` (default) | `127.0.0.1` | this machine only |
+| `"all"` | `0.0.0.0` | every interface / the LAN |
+
+Ops can override the manifest at deploy time with the `URBAN_BIND` environment
+variable (`URBAN_BIND=all` or `URBAN_BIND=loopback`); a valid value wins over the
+manifest, the manifest stays the declarative default. Binding to all interfaces
+emits a startup `warn` log because it exposes the app off-box.
+
+> **Security:** binding to all interfaces exposes the app's token-gated capability
+> hooks on the LAN. Any LOCAL-mode "well-known localhost" credential (e.g. the
+> agentic channel's LOCAL mode) must **not** be served on a non-loopback bind — a
+> consumer that mints one must gate it on a loopback bind.
+
+
 ### A typical session
 
 ```bash
@@ -178,40 +210,67 @@ wiring; `WorkflowClient` deploys and starts, `Worker` hosts your `run` steps.
 inspectable in a modeller/Operate — `@nanobpm/urban` bundles `bpmn-auto-layout`
 so this works out of the box.
 
-### Deploy-time model templates (`{{name}}`)
+### Deploy by convention (`resources/`)
+
+Deployables are discovered by convention: with **no `models`** block in the
+manifest, `@nanobpm/urban` deploys everything under `resources/` — walked
+**shallow, one level deep** (`resources/*` and `resources/<subdir>/*`, never
+deeper). Content type is by extension: `.bpmn`/`.dmn` → BPMN/DMN, `.form` →
+form-js form, anything else → a `GenericScript` resource (this is how agent
+prompts are deployed — see below).
+
+```
+resources/
+  processes/  order.bpmn        ← deployed as a BPMN process
+  decisions/  route.dmn         ← deployed as a DMN decision
+  forms/      approve.form      ← deployed as a form
+  prompts/    review.md         ← deployed as a GenericScript (an agent prompt)
+```
+
+`resources/` is **deploy-only**: everything under it deploys, and nothing outside
+it ever does — so docs (`docs/`, `AGENTS.md`, top-level `*.md`) live **outside**
+`resources/` and are never swept into a deployment. Resources are keyed by their
+**basename** (filename), so two files with the same name in different sub-dirs are
+a **hard error** — rename or relocate one. `urban gen` follows the same
+convention: with no `models`, its `nano:shape`/code-first model scan defaults to a
+**shallow** `resources/` walk — `.bpmn`/`.dmn` directly under `resources/` and one
+level down in `resources/<subdir>/`, never deeper — and derived models are written to
+`resources/processes/`, exactly where the convention deploy then finds them.
 
-A model file can carry `{{name}}` placeholders that are substituted at deploy
-time — handy for inlining a large asset (e.g. an agent prompt authored as its own
-file) into a `zeebe:header` value instead of hand-pasting it into XML or shipping
-it as a bulky per-instance process variable. Declare the template sources under
-`models.templates` (globs, a bare directory that is scanned, or literal files); a
-template's name is its file **stem**, so `prompts/review.md` fills `{{review}}`:
+To opt out of the convention, declare `models` globs — they are used verbatim and
+the `resources/` walk is skipped:
 
 ```jsonc
 {
   "models": {
-    "processes": ["processes/*.bpmn"],
-    "templates": ["prompts/*.md"]
+    "processes": ["src/models/*.bpmn"],
+    "forms": ["src/forms/*.form"]
   }
 }
 ```
 
+### Modular prompts — the blessed path (`zeebe:linkedResource`)
+
+To keep a large agent prompt out of a model's XML, author it as its own file under
+`resources/prompts/` (deployed as a `GenericScript`) and **link** it into the
+service task with a `zeebe:linkedResource` bound to the latest deployed version;
+the runtime resolves it with the `appendPrompt` FEEL helper at execution time:
+
 ```xml
-<!-- processes/agent.bpmn -->
-<zeebe:header key="io.nanobpm.agentTask.task.prompt" value="{{review}}" />
+<!-- resources/processes/agent.bpmn -->
+<zeebe:linkedResource linkName="prompt" resourceType="GenericScript"
+                      bindingType="latest" resourceId="review" />
 ```
 
-Content is escaped for the resource's type: XML for `.bpmn`/`.dmn` (newlines/tabs
-become character references so a multi-line prompt survives XML attribute-value
-normalization), JSON for `.form`. Substitution is single-pass (a template's own
-`{{…}}` is not re-expanded); an unknown placeholder is left verbatim and logged as
-a warning. Templates can also be supplied programmatically via the `templates`
-run option (globs or an explicit `name → content` map), which wins over the
-manifest on a name collision:
+This is the **only** supported prompt-modularity mechanism — there is no
+deploy-time string substitution (`{{name}}` templating has been removed).
 
-```ts
-await runFromEnv({ templates: { review: await readPrompt("review.md") } });
-```
+> **Value-injection caveat.** Injecting a *value* into a model at deploy time (a
+> URL, a feature flag, an environment-specific constant) must use **runtime
+> variables / FEEL**, never string substitution baked into the model. A model is
+> deployed once and shared across environments; bake a value in and you fork the
+> model per environment. Pass the value as a process variable and reference it
+> with FEEL instead.
 
 ### Triggers — the inbound I/O edge
 

package/dist/runtime/adapters/deno.js

@@ -16,6 +16,7 @@ import { existsSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { resolveModulePath } from "../core/module-path.js";
+import { LOOPBACK_HOST } from "../core/manifest.js";
 import { formatLogRecord, levelEnabled, parseLogLevel } from "../core/logger.js";
 function sqliteParams(params) {
     return params.map((param) => {
@@ -71,6 +72,19 @@ export function createDenoHost(opts = {}) {
                 return [];
             }
         },
+        async listSubdirs(dir) {
+            try {
+                const names = [];
+                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));
@@ -90,8 +104,8 @@ export function createDenoHost(opts = {}) {
             const mod = import(__rewriteRelativeImportExtension(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 });
@@ -146,9 +160,13 @@ function wrapSqlite(db) {
         close: () => db.close(),
     };
 }
-function startDenoServer(port, handler) {
+function startDenoServer(port, handler, bindHost) {
     return new Promise((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/dist/runtime/adapters/node.js

@@ -18,6 +18,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { resolveModulePath } from "../core/module-path.js";
+import { LOOPBACK_HOST } from "../core/manifest.js";
 import { formatLogLine, levelEnabled, parseLogLevel } from "../core/logger.js";
 /**
  * The default host log sink: NDJSON to stdout (`debug`/`info`) and stderr (`warn`/`error`), gated by
@@ -114,6 +115,15 @@ export function createNodeHost(opts = {}) {
                 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));
@@ -142,8 +152,8 @@ export function createNodeHost(opts = {}) {
             const href = pathToFileURL(abs(entry)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
             await import(__rewriteRelativeImportExtension(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, filename) => {
@@ -192,7 +202,7 @@ function wrapNodeSqlite(db) {
         close: () => db.close(),
     };
 }
-async function startNodeServer(port, handler) {
+async function startNodeServer(port, handler, bindHost) {
     const server = createServer(async (nreq, nres) => {
         const chunks = [];
         for await (const c of nreq) {
@@ -245,7 +255,27 @@ async function startNodeServer(port, handler) {
         sockets.add(socket);
         socket.once("close", () => sockets.delete(socket));
     });
-    await new Promise((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((res, rej) => {
+        const onError = (err) => {
+            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/dist/runtime/core/context.d.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 {
     manifest: AppManifest;
@@ -9,9 +8,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. */
 export interface Mounted {

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

@@ -3,3 +3,12 @@ import type { HostContext } from "./host.ts";
 export declare function expandPattern(host: HostContext, root: string, pattern: string): Promise<string[]>;
 /** Expand many patterns, de-duplicating while preserving first-seen order. */
 export declare function expandPatterns(host: HostContext, root: string, patterns: string[] | undefined): Promise<string[]>;
+/**
+ * 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 declare function discoverResources(host: HostContext, root: string, dir: string): Promise<string[]>;

package/dist/runtime/core/glob.js

@@ -49,3 +49,24 @@ export async function expandPatterns(host, root, patterns) {
     }
     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, root, dir) {
+    const base = joinPath(root, dir);
+    const out = [];
+    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/dist/runtime/core/host.d.ts

@@ -71,6 +71,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. */
@@ -90,8 +96,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:
@@ -150,6 +164,16 @@ export declare function isBpmnError(err: unknown): err is {
     errorCode: string;
     message?: string;
 };
+/**
+ * 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 declare function presentFormIdentifier(value: string | undefined): string | undefined;
 /** A registered worker subscription. */
 export interface WorkerSubscription {
     readonly jobType: string;
@@ -163,11 +187,47 @@ export interface WorkerSubscription {
  * element-instance state set (which adds SKIPPED/CANCELED/FAILED for tokens).
  */
 export type ProcessInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED";
+/**
+ * A user task's lifecycle state, as the engine reports it on a `/v2/user-tasks/search`
+ * result. `CREATED` is the only *open* (answerable) state — a task in any other state has
+ * already been answered (`COMPLETED`), withdrawn (`CANCELED`), or errored (`FAILED`) and must
+ * never surface in the `taskInbox` as if it were actionable.
+ */
+export type UserTaskState = "CREATED" | "COMPLETED" | "CANCELED" | "FAILED";
 /** A single process instance's lifecycle snapshot returned by {@link EngineClient.searchProcessInstances}. */
 export interface ProcessInstanceSnapshot {
     readonly processInstanceKey: string;
     readonly state: ProcessInstanceState;
 }
+/**
+ * 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.
@@ -200,16 +260,30 @@ export interface EngineClient {
         correlationKey?: string;
         variables?: Record<string, unknown>;
     }): Promise<void>;
-    /** Search open user tasks (optionally by process instance). */
+    /** Search user tasks (optionally by process instance, assignee, or candidate group).
+     *  By default this is unfiltered by lifecycle state and may return tasks in any state
+     *  (e.g. completed/canceled); pass `state: "CREATED"` to constrain the search to open
+     *  (answerable) tasks. 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>;
-    }[]>;
+        state?: UserTaskState;
+    }): 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>;
     /**

package/dist/runtime/core/host.js

@@ -29,3 +29,16 @@ export function isBpmnError(err) {
     return (typeof errorCode === "string" &&
         errorCode.length > 0);
 }
+/**
+ * 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) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}

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

@@ -1,8 +1,95 @@
 import type { HostContext } from "./host.ts";
-import type { AppManifest, Worker } from "@nanobpm/nano-app-schema";
-export type { ActionDecl, AppManifest, AppUi, ChatSurface, Connection, Data, DataSource, DomainField, DomainType, InstanceTracking, LlmBinding, Models, PagesSurface, Runtime, Security, Surfaces, TaskInboxSurface, Trigger, TriggerAction, Worker, } from "@nanobpm/nano-app-schema";
+import type { AppManifest, InstanceTracking as SchemaInstanceTracking, Worker } from "@nanobpm/nano-app-schema";
+export type { ActionDecl, AppManifest, AppUi, ChatSurface, Connection, Data, DataSource, DomainField, DomainType, LlmBinding, Models, PagesSurface, Runtime, Security, Surfaces, TaskInboxSurface, Trigger, TriggerAction, Worker, } from "@nanobpm/nano-app-schema";
+/**
+ * `instanceTracking` binding, bridged to add the fail-open `terminalStatuses` selector.
+ *
+ * `terminalStatuses` is landing in the canonical schema (`@nanobpm/nano-app-schema`,
+ * Magikcraft/nano-bpm#769): an exclusion list — the runtime polls every row whose
+ * `statusField` is NOT in it — so a newly-added non-terminal status is reconciled by
+ * default instead of silently dropping out of an allow-list. Until that publishes and this
+ * package's dep is bumped, extend the schema type here so the reconciler can consume the
+ * field. Drop this augmentation and re-export `InstanceTracking` from the schema once the
+ * dep bump lands (No Drift Surfaces).
+ */
+export type InstanceTracking = SchemaInstanceTracking & {
+    /** Values of `statusField` considered finished. When set, every row NOT in one of these
+     *  is polled (fail-open). Requires `statusField`; mutually exclusive with `activeStatuses`. */
+    readonly terminalStatuses?: readonly string[];
+};
+/**
+ * A status selector (`activeStatuses`/`terminalStatuses`) counts as *configured* only when it is
+ * a non-empty array of non-empty strings. Both the reconciler's row selection and the manifest
+ * validator gate on this one predicate, so "is this selector active?" has a single definition and
+ * the two can't drift (No Drift Surfaces). Anything else — `undefined`, an empty array, a bare
+ * string, or an array holding a non-string/empty entry — is treated as *not configured*: the
+ * reconciler falls through to the fail-open poll-all path and the validator flags the malformed
+ * shape at author time (rather than letting e.g. `new Set("abandoned")` silently become a set of
+ * characters, or `activeStatuses.map(...)` crash on a non-array).
+ */
+export declare function isConfiguredStatusSelector(v: unknown): v is readonly string[];
 /** The job type a worker subscribes to (schema key: `taskType`). */
 export declare function workerJobType(w: Worker): string | undefined;
+/**
+ * The valid HTTP bind modes, in declaration order. This is the single runtime source of
+ * truth for the set: {@link BindMode}, {@link isBindMode}, and the manifest validator
+ * (`collectManifestIssues`) all derive from it, so the allowed values live in one place.
+ */
+export declare const BIND_MODES: readonly ["loopback", "all"];
+/**
+ * Which interface the app's embedded HTTP server binds to (issue #235):
+ *  - `"loopback"` (default): `127.0.0.1` — secure-by-default; refuses off-box connections.
+ *  - `"all"`: `0.0.0.0` — reachable from other hosts on the LAN (distributed worker fleet).
+ */
+export type BindMode = (typeof BIND_MODES)[number];
+/**
+ * App-level network settings (issue #235). Absent ⇒ loopback.
+ *
+ * Mirrored locally — like the `api` binding (ADR 0058) — until `@nanobpm/nano-app-schema`
+ * folds `network` into `AppManifest` (the schema PR lands first). The manifest shape is
+ * owned by that package (ADR 0027), so we deliberately do NOT augment `AppManifest` via
+ * `declare module` (CI bans it): the field is threaded through the runtime-side helpers
+ * that take a `{ network?: NetworkConfig }` view and is read off the raw manifest object.
+ * Once the schema ships `network`, this local type (and the allow-list entry in
+ * validate.ts) can be deleted and the field flows from the schema like every other block.
+ */
+export interface NetworkConfig {
+    /** HTTP bind interface. Default `"loopback"`. */
+    bind?: BindMode;
+}
+/**
+ * The keys the runtime-side `network` block understands, as the single source of truth for
+ * the validator's `additionalProperties: false` check under `network`. Typed as
+ * `(keyof NetworkConfig)[]` so it can only ever list real {@link NetworkConfig} keys — a
+ * drift test (`manifest.test.ts`) asserts it stays complete as the block grows.
+ */
+export declare const NETWORK_KEYS: readonly (keyof NetworkConfig)[];
+/** A runtime-side view of a manifest carrying the pending-schema `network` block. */
+export interface WithNetwork {
+    network?: NetworkConfig;
+}
+/** Loopback bind address — secure/local default. */
+export declare const LOOPBACK_HOST = "127.0.0.1";
+/** All-interfaces IPv4 bind address — LAN / distributed fleet. */
+export declare const ALL_INTERFACES_HOST = "0.0.0.0";
+/** Environment variable that overrides the manifest bind mode for ops. */
+export declare const BIND_ENV_VAR = "URBAN_BIND";
+/** True when `v` is a valid {@link BindMode}. */
+export declare function isBindMode(v: unknown): v is BindMode;
+/**
+ * Resolve the effective HTTP bind mode: the `URBAN_BIND` env override wins when set to a
+ * valid value, else the manifest's `network.bind`, else `"loopback"` (secure by default).
+ * An env value that is present but invalid is ignored (falls through to the manifest/default);
+ * callers that want to surface that can check {@link isBindMode} on the raw env value.
+ */
+export declare function resolveBindMode(manifest: AppManifest | WithNetwork, lookup?: (name: string) => string | undefined): BindMode;
+/** Map a {@link BindMode} to the concrete host address passed to the HTTP adapter. */
+export declare function bindModeToHost(mode: BindMode): string;
+/**
+ * Resolve the concrete bind host address from the manifest + environment.
+ * `"loopback"` ⇒ `127.0.0.1` (default), `"all"` ⇒ `0.0.0.0`.
+ */
+export declare function resolveBindHost(manifest: AppManifest | WithNetwork, lookup?: (name: string) => string | undefined): string;
 /**
  * Expand `${VAR}` and `${VAR:-default}` placeholders in a string using `lookup`.
  * Unset vars with no default expand to "" (matching common shell semantics).

package/dist/runtime/core/manifest.js

@@ -7,10 +7,82 @@
 // bundle) and adds the runtime-side helpers the App loader needs. No shape is
 // hand-mirrored here — that eliminated the schema/type drift the vendored copies
 // used to cause.
+import { isRecord } from "./guards.js";
+/**
+ * A status selector (`activeStatuses`/`terminalStatuses`) counts as *configured* only when it is
+ * a non-empty array of non-empty strings. Both the reconciler's row selection and the manifest
+ * validator gate on this one predicate, so "is this selector active?" has a single definition and
+ * the two can't drift (No Drift Surfaces). Anything else — `undefined`, an empty array, a bare
+ * string, or an array holding a non-string/empty entry — is treated as *not configured*: the
+ * reconciler falls through to the fail-open poll-all path and the validator flags the malformed
+ * shape at author time (rather than letting e.g. `new Set("abandoned")` silently become a set of
+ * characters, or `activeStatuses.map(...)` crash on a non-array).
+ */
+export function isConfiguredStatusSelector(v) {
+    return Array.isArray(v) && v.length > 0 && v.every((s) => typeof s === "string" && s.length > 0);
+}
 /** The job type a worker subscribes to (schema key: `taskType`). */
 export function workerJobType(w) {
     return w.taskType;
 }
+/**
+ * The valid HTTP bind modes, in declaration order. This is the single runtime source of
+ * truth for the set: {@link BindMode}, {@link isBindMode}, and the manifest validator
+ * (`collectManifestIssues`) all derive from it, so the allowed values live in one place.
+ */
+export const BIND_MODES = ["loopback", "all"];
+/**
+ * The keys the runtime-side `network` block understands, as the single source of truth for
+ * the validator's `additionalProperties: false` check under `network`. Typed as
+ * `(keyof NetworkConfig)[]` so it can only ever list real {@link NetworkConfig} keys — a
+ * drift test (`manifest.test.ts`) asserts it stays complete as the block grows.
+ */
+export const NETWORK_KEYS = ["bind"];
+/** Loopback bind address — secure/local default. */
+export const LOOPBACK_HOST = "127.0.0.1";
+/** All-interfaces IPv4 bind address — LAN / distributed fleet. */
+export const ALL_INTERFACES_HOST = "0.0.0.0";
+/** Environment variable that overrides the manifest bind mode for ops. */
+export const BIND_ENV_VAR = "URBAN_BIND";
+/** True when `v` is a valid {@link BindMode}. */
+export function isBindMode(v) {
+    return BIND_MODES.some((mode) => mode === v);
+}
+/**
+ * Read the pending-schema `network.bind` off a raw manifest object. Because `network` is
+ * mirrored locally (not yet in `AppManifest`'s static shape), it is read reflectively —
+ * the same way the `api` binding is threaded (ADR 0058) — and validated with
+ * {@link isBindMode} so this always returns a real {@link BindMode} or `undefined`.
+ */
+function manifestBind(manifest) {
+    const network = Reflect.get(manifest, "network");
+    if (!isRecord(network))
+        return undefined;
+    return isBindMode(network.bind) ? network.bind : undefined;
+}
+/**
+ * Resolve the effective HTTP bind mode: the `URBAN_BIND` env override wins when set to a
+ * valid value, else the manifest's `network.bind`, else `"loopback"` (secure by default).
+ * An env value that is present but invalid is ignored (falls through to the manifest/default);
+ * callers that want to surface that can check {@link isBindMode} on the raw env value.
+ */
+export function resolveBindMode(manifest, lookup = () => undefined) {
+    const envRaw = lookup(BIND_ENV_VAR);
+    if (isBindMode(envRaw))
+        return envRaw;
+    return manifestBind(manifest) ?? "loopback";
+}
+/** Map a {@link BindMode} to the concrete host address passed to the HTTP adapter. */
+export function bindModeToHost(mode) {
+    return mode === "all" ? ALL_INTERFACES_HOST : LOOPBACK_HOST;
+}
+/**
+ * Resolve the concrete bind host address from the manifest + environment.
+ * `"loopback"` ⇒ `127.0.0.1` (default), `"all"` ⇒ `0.0.0.0`.
+ */
+export function resolveBindHost(manifest, lookup = () => undefined) {
+    return bindModeToHost(resolveBindMode(manifest, lookup));
+}
 const ENV_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
 /**
  * Expand `${VAR}` and `${VAR:-default}` placeholders in a string using `lookup`.