@nanobpm/urban 0.47.0 → 0.49.0

package/src/runtime/core/runtime.ts

@@ -6,11 +6,10 @@
 import type { AppApi, Mounted } from "./context.ts";
 import type { EngineClient, HostContext, HttpServer } from "./host.ts";
 import type { EngineSdkClient } from "../engine/sdk.ts";
-import { loadManifest, type AppManifest } from "./manifest.ts";
+import { loadManifest, resolveBindMode, bindModeToHost, type AppManifest } from "./manifest.ts";
 import { validateManifest } from "./validate.ts";
 import { makeRouter, type Route } from "./router.ts";
 import { deployModels } from "./modules/deploy.ts";
-import type { TemplateSource } from "./modules/templates.ts";
 import { provisionData, DataLayer } from "./modules/datasource.ts";
 import { installExecStore, type JobExecContext } from "./execContext.ts";
 import { createLogger, type Logger } from "./logger.ts";
@@ -74,10 +73,6 @@ export interface CreateUrbanAppOptions {
   port?: number;
   /** Which modules to mount (all true by default). */
   mount?: MountFlags;
-  /** Programmatic `{{name}}` template source for deploy-time substitution (globs or a
-   *  `name → content` map). Merged over the manifest's `models.templates` (this wins on
-   *  collision). See `deployModels`. */
-  templates?: TemplateSource;
   /**
    * Injectable timer + clock seam driving every background loop (the cron trigger loops
    * and the instance-tracking reconciler). Defaults to the live scheduler (real timers,
@@ -135,7 +130,7 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
     security: opts.mount?.security ?? true,
     instanceTracking: opts.mount?.instanceTracking ?? true,
   };
-  const ctx = { manifest, host, engine, root, templates: opts.templates };
+  const ctx = { manifest, host, engine, root };
 
   // One app-level structured logger over the host sink, shared by the entrypoint (exposed as
   // `app.log`) and the per-invocation `AppApi.log` (workers/route delegates `child()` it with their
@@ -157,6 +152,13 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
 
   const port = resolvePort(opts.port, host.env("PORT"));
 
+  // Which interface the HTTP server binds to (issue #235). Secure by default: loopback unless
+  // the manifest's `network.bind` (or the `URBAN_BIND` env override) opts into all interfaces.
+  // Derive the host address from the already-resolved mode so the two can never diverge (and we
+  // consult the env exactly once) — a second `resolveBindHost` call would re-read the override.
+  const bindMode = resolveBindMode(manifest, (n) => host.env(n));
+  const bindHost = bindModeToHost(bindMode);
+
   // Release every mounted resource and reset internal state so a subsequent
   // start() begins clean. Used by stop() and by start()'s failure path.
   const teardown = async () => {
@@ -268,9 +270,26 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
               body: JSON.stringify({ ok: true, app: manifest.id }),
             }),
           });
-          server = await host.serveHttp(port, makeRouter(routes));
+          server = await host.serveHttp(port, makeRouter(routes), bindHost);
           httpPort = server.port;
-          host.log("info", "urban app serving surfaces/triggers", { port: httpPort, routes: routes.length });
+          host.log("info", "urban app serving surfaces/triggers", {
+            port: httpPort,
+            routes: routes.length,
+            bind: bindMode,
+            bindHost,
+          });
+          // Binding to all interfaces exposes the app (and its token-gated capability
+          // hooks) on the LAN. That is the explicit opt-in this setting exists for, but a
+          // non-loopback bind must not serve any LOCAL-mode "well-known localhost token"
+          // credential (issue #235) — consumers that mint one (e.g. the agentic channel's
+          // LOCAL mode) must gate it on a loopback bind. Surface the exposure so it is never
+          // silent.
+          if (bindMode === "all") {
+            host.log("warn", "urban app bound to all interfaces — reachable off-box on the LAN", {
+              port: httpPort,
+              bindHost,
+            });
+          }
           // ADR 0057 boot handshake: under a supervising host (the nano-bpm
           // Studio sets NANOBPMN_APP_HANDSHAKE), announce the port we actually
           // bound on a machine-readable stdout control line so the host can

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

@@ -1,6 +1,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { collectManifestIssues, validateManifest, ManifestValidationError } from "./validate.ts";
+import { BIND_MODES } from "./manifest.ts";
 
 const valid = {
   schemaVersion: 1,
@@ -45,6 +46,33 @@ test("a `ui` block is an accepted top-level key (Studio App View, ADR 0057 / nan
   assert.deepEqual(issues, []);
 });
 
+// Drift guard: the validator's accepted set is derived from `BIND_MODES` (via `isBindMode`),
+// so every declared mode must validate. If the validator ever re-hardcodes a divergent literal
+// set, or a mode is added to `BIND_MODES` without the validator following, this fails.
+test("a `network` block with a valid bind is accepted for every BIND_MODES value (issue #235)", () => {
+  for (const bind of BIND_MODES) {
+    assert.deepEqual(collectManifestIssues({ ...valid, network: { bind } }), []);
+  }
+  assert.deepEqual(collectManifestIssues({ ...valid, network: {} }), []);
+});
+
+test("a `network.bind` outside loopback|all is reported (issue #235)", () => {
+  const issues = collectManifestIssues({ ...valid, network: { bind: "lan" } });
+  assert.ok(issues.some((i) => i.path === "network.bind"));
+});
+
+test("a non-object `network` is reported (issue #235)", () => {
+  const issues = collectManifestIssues({ ...valid, network: "all" });
+  assert.ok(issues.some((i) => i.path === "network"));
+});
+
+test("an unknown key inside `network` is rejected (network additionalProperties:false, issue #235)", () => {
+  const issues = collectManifestIssues({ ...valid, network: { bind: "loopback", binn: "all" } });
+  assert.ok(issues.some((i) => i.path === "network.binn"));
+  // A valid `bind` alongside the typo must not itself be flagged.
+  assert.ok(!issues.some((i) => i.path === "network.bind"));
+});
+
 test("bad schemaVersion and bad slug id are reported", () => {
   const issues = collectManifestIssues({ ...valid, schemaVersion: 2, id: "Not A Slug" });
   assert.ok(issues.some((i) => i.path === "schemaVersion"));
@@ -169,6 +197,123 @@ test("instanceTracking activeStatuses with an empty-string statusField is flagge
   assert.ok(issues.some((i) => i.path === "instanceTracking[0].activeStatuses"));
 });
 
+test("instanceTracking terminalStatuses without statusField is flagged", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    instanceTracking: [
+      {
+        table: "plans",
+        keyField: "process_key",
+        terminalStatuses: ["abandoned"],
+        onTerminated: { set: { status: "abandoned" } },
+      },
+    ],
+  });
+  assert.ok(issues.some((i) => i.path === "instanceTracking[0].terminalStatuses"));
+});
+
+test("instanceTracking with statusField + terminalStatuses (no activeStatuses) has no issues", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    instanceTracking: [
+      {
+        table: "plans",
+        keyField: "process_key",
+        statusField: "status",
+        terminalStatuses: ["abandoned", "completed"],
+        onTerminated: { set: { status: "abandoned" } },
+      },
+    ],
+  });
+  assert.deepEqual(issues, []);
+});
+
+test("instanceTracking declaring both activeStatuses and terminalStatuses is flagged (mutually exclusive)", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    instanceTracking: [
+      {
+        table: "plans",
+        keyField: "process_key",
+        statusField: "status",
+        activeStatuses: ["planning"],
+        terminalStatuses: ["abandoned"],
+        onTerminated: { set: { status: "abandoned" } },
+      },
+    ],
+  });
+  assert.ok(
+    issues.some(
+      (i) =>
+        i.path === "instanceTracking[0].terminalStatuses" &&
+        /mutually exclusive/.test(i.message),
+    ),
+  );
+});
+
+test("instanceTracking treats an empty selector array as unset — both empty is NOT mutually-exclusive", () => {
+  // The runtime gates on a non-empty array (`isConfiguredStatusSelector`), so an empty array means
+  // "not configured". Validation must agree, or an equivalent manifest fails only at author time.
+  const issues = collectManifestIssues({
+    ...valid,
+    instanceTracking: [
+      {
+        table: "plans",
+        keyField: "process_key",
+        statusField: "status",
+        activeStatuses: [],
+        terminalStatuses: [],
+        onTerminated: { set: { status: "abandoned" } },
+      },
+    ],
+  });
+  assert.deepEqual(issues, []);
+});
+
+test("instanceTracking flags a non-array terminalStatuses (would become a Set of characters at runtime)", () => {
+  // A JSON manifest can supply a bare string; typed construction can't. Parse it so the fixture is
+  // genuinely runtime-invalid without an `as` cast.
+  const bad = JSON.parse(
+    '{"table":"plans","keyField":"process_key","statusField":"status","terminalStatuses":"abandoned","onTerminated":{"set":{"status":"abandoned"}}}',
+  );
+  const issues = collectManifestIssues({ ...valid, instanceTracking: [bad] });
+  assert.ok(
+    issues.some(
+      (i) =>
+        i.path === "instanceTracking[0].terminalStatuses" &&
+        /array of non-empty strings/.test(i.message),
+    ),
+  );
+});
+
+test("instanceTracking flags a non-array activeStatuses (would crash activeStatuses.map at runtime)", () => {
+  const bad = JSON.parse(
+    '{"table":"plans","keyField":"process_key","statusField":"status","activeStatuses":"planning","onTerminated":{"set":{"status":"abandoned"}}}',
+  );
+  const issues = collectManifestIssues({ ...valid, instanceTracking: [bad] });
+  assert.ok(
+    issues.some(
+      (i) =>
+        i.path === "instanceTracking[0].activeStatuses" &&
+        /array of non-empty strings/.test(i.message),
+    ),
+  );
+});
+
+test("instanceTracking flags a status selector array holding a non-string/empty entry", () => {
+  const bad = JSON.parse(
+    '{"table":"plans","keyField":"process_key","statusField":"status","terminalStatuses":["abandoned",""],"onTerminated":{"set":{"status":"abandoned"}}}',
+  );
+  const issues = collectManifestIssues({ ...valid, instanceTracking: [bad] });
+  assert.ok(
+    issues.some(
+      (i) =>
+        i.path === "instanceTracking[0].terminalStatuses" &&
+        /array of non-empty strings/.test(i.message),
+    ),
+  );
+});
+
 test("instanceTracking pollMs that is non-positive/NaN/non-number is flagged (would hot-loop the poll timer)", () => {
   for (const badPollMs of [0, -1, Number.NaN, Number.POSITIVE_INFINITY, "5000"]) {
     const issues = collectManifestIssues({

package/src/runtime/core/validate.ts

@@ -10,6 +10,7 @@
 
 import schema from "@nanobpm/nano-app-schema/schema" with { type: "json" };
 import { isRecord } from "./guards.ts";
+import { BIND_MODES, NETWORK_KEYS, isBindMode, isConfiguredStatusSelector } from "./manifest.ts";
 import type { AppManifest } from "./manifest.ts";
 
 export interface ValidationIssue {
@@ -51,6 +52,13 @@ export function collectManifestIssues(m: unknown): ValidationIssue[] {
     if (!(req in obj)) 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)) {
@@ -58,6 +66,27 @@ export function collectManifestIssues(m: unknown): ValidationIssue[] {
       }
     }
   }
+  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" });
   }
@@ -172,12 +201,46 @@ export function collectManifestIssues(m: unknown): ValidationIssue[] {
           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"] as const) {
+        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/src/runtime/engine/nanosdk.test.ts

@@ -75,6 +75,10 @@ function fakeSdkClient(overrides: Partial<NanoSdkClient> = {}): NanoSdkClient &
       calls.push("completeUserTask");
       return {};
     },
+    async getFormByKey() {
+      calls.push("getFormByKey");
+      return {};
+    },
     createJobWorker(cfg) {
       calls.push("createJobWorker");
       const rec = { cfg, started: 0, stopped: 0, dispatch: cfg.jobHandler };
@@ -194,6 +198,124 @@ test("searchUserTasks passes zero-wait consistency and maps items", async () =>
   ]);
 });
 
+test("searchUserTasks surfaces the resolved form linkage", async () => {
+  const client = fakeSdkClient({
+    searchUserTasks: async () => ({
+      items: [
+        { userTaskKey: 5, elementId: "approve", formKey: 42 },
+        { userTaskKey: 6, elementId: "review", externalFormReference: "https://x/form" },
+        { userTaskKey: 7, elementId: "plain", formKey: null, externalFormReference: null },
+      ],
+    }),
+  });
+  const engine = new SdkEngineClient(client);
+  const tasks = await engine.searchUserTasks();
+  assert.deepEqual(tasks, [
+    { userTaskKey: "5", elementId: "approve", variables: undefined, formKey: "42" },
+    { userTaskKey: "6", elementId: "review", variables: undefined, externalFormReference: "https://x/form" },
+    { userTaskKey: "7", elementId: "plain", variables: undefined },
+  ]);
+});
+
+test("getForm resolves by formKey and parses the serialized schema", async () => {
+  let seen: unknown;
+  const schema = { type: "default", schemaVersion: 18, components: [{ type: "textfield", key: "name" }] };
+  const client = fakeSdkClient({
+    getFormByKey: async (input, c) => {
+      seen = { input, c };
+      return { formKey: "42", formId: "myForm", version: 3, schema: JSON.stringify(schema) };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  const form = await engine.getForm({ formKey: "42" });
+  assert.deepEqual(seen, { input: { formKey: "42" }, c: { consistency: { waitUpToMs: 0 } } });
+  assert.deepEqual(form, { formKey: "42", formId: "myForm", version: 3, schema });
+});
+
+test("getForm falls back to formId as the key when no formKey is given", async () => {
+  let seen: unknown;
+  const client = fakeSdkClient({
+    getFormByKey: async (input) => {
+      seen = input;
+      return { schema: JSON.stringify({ type: "default", components: [] }) };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  const form = await engine.getForm({ formId: "myForm" });
+  assert.deepEqual(seen, { formKey: "myForm" });
+  assert.deepEqual(form?.schema, { type: "default", components: [] });
+});
+
+test("getForm falls back to formId when formKey is empty/whitespace, not just absent", async () => {
+  // Regression: `formKey ?? formId` treated an empty-string key as present and short-
+  // circuited to null, ignoring a valid formId fallback (→ a spurious 204). An empty or
+  // whitespace-only identifier must be resolved as *missing*.
+  for (const formKey of ["", "   "]) {
+    let seen: unknown;
+    const client = fakeSdkClient({
+      getFormByKey: async (input) => {
+        seen = input;
+        return { schema: JSON.stringify({ type: "default", components: [] }) };
+      },
+    });
+    const engine = new SdkEngineClient(client);
+    const form = await engine.getForm({ formKey, formId: "myForm" });
+    assert.deepEqual(seen, { formKey: "myForm" }, `formKey=${JSON.stringify(formKey)} must fall through to formId`);
+    assert.deepEqual(form?.schema, { type: "default", components: [] });
+  }
+});
+
+test("getForm trims a padded identifier before the engine lookup", async () => {
+  // Regression: the presence check trimmed only for the emptiness test but forwarded the
+  // *untrimmed* value, so a padded `" 42 "` was fetched with the spaces and 404'd.
+  let seen: unknown;
+  const client = fakeSdkClient({
+    getFormByKey: async (input) => {
+      seen = input;
+      return { schema: JSON.stringify({ type: "default", components: [] }) };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  const form = await engine.getForm({ formKey: "  42  " });
+  assert.deepEqual(seen, { formKey: "42" }, "the padded formKey is trimmed before lookup");
+  assert.deepEqual(form?.schema, { type: "default", components: [] });
+});
+
+test("getForm returns null when no identifier is given or the fetch fails", async () => {
+  const throwing = fakeSdkClient({
+    getFormByKey: async () => {
+      throw new Error("404 not found");
+    },
+  });
+  const engine = new SdkEngineClient(throwing);
+  assert.equal(await engine.getForm({}), null);
+  assert.equal(await engine.getForm({ formKey: "missing" }), null);
+});
+
+test("getForm returns null when the schema is not valid JSON", async () => {
+  const client = fakeSdkClient({
+    getFormByKey: async () => ({ formKey: "42", schema: "not json" }),
+  });
+  const engine = new SdkEngineClient(client);
+  assert.equal(await engine.getForm({ formKey: "42" }), null);
+});
+
+test("getForm's invalid-JSON warning records the formId when only formId is given", async () => {
+  const logs: { level: string; message: string; details?: unknown }[] = [];
+  const client = fakeSdkClient({
+    getFormByKey: async () => ({ formKey: "42", schema: "not json" }),
+  });
+  const engine = new SdkEngineClient(client, (level, message, details) => {
+    logs.push({ level, message, details });
+  });
+  assert.equal(await engine.getForm({ formId: "myForm" }), null);
+  const warn = logs.find((l) => l.message === "getForm: form schema is not valid JSON");
+  assert.ok(warn, "invalid-JSON schema is warned");
+  // A formId-only caller must not be logged as { formKey: undefined } — the
+  // resolved identifier that was actually used (`key`) has to be traceable.
+  assert.deepEqual(warn.details, { key: "myForm", formKey: undefined, formId: "myForm" });
+});
+
 test("completeUserTask routes through the SDK", async () => {
   let seen: unknown;
   const client = fakeSdkClient({

package/src/runtime/engine/nanosdk.ts

@@ -14,12 +14,14 @@
 import type {
   EngineClient,
   EngineJob,
+  FormSchema,
   JobHandler,
   ProcessInstanceSnapshot,
   ProcessInstanceState,
+  UserTaskSummary,
   WorkerSubscription,
 } from "../core/host.ts";
-import { isBpmnError } from "../core/host.ts";
+import { isBpmnError, presentFormIdentifier } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 import { isRecord } from "../core/guards.ts";
 
@@ -125,6 +127,11 @@ export interface NanoSdkClient {
     input: { 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> },
     consistency?: unknown,
@@ -214,7 +221,7 @@ export class SdkEngineClient implements EngineClient {
     processInstanceKey?: string;
     assignee?: string;
     candidateGroup?: string;
-  }): Promise<{ userTaskKey: string; elementId?: string; variables?: Record<string, unknown> }[]> {
+  }): Promise<UserTaskSummary[]> {
     // 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(
@@ -228,14 +235,77 @@ export class SdkEngineClient implements EngineClient {
         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: { formKey?: string; formId?: string }): Promise<FormSchema | null> {
+    // 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: Record<string, unknown>;
+    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: Record<string, unknown> | undefined;
+    if (typeof rawSchema === "string") {
+      try {
+        const parsed: unknown = 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: string, variables?: Record<string, unknown>): Promise<void> {
     await this.client.completeUserTask({ userTaskKey, variables: variables ?? {} });
   }

package/src/runtime/index.ts

@@ -10,20 +10,29 @@ export type {
 
 // Manifest
 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,
@@ -119,10 +128,8 @@ export type {
 } from "./core/modules/llm.ts";
 export { evalCorrelation } from "./core/modules/triggers.ts";
 
-// Model deploy + `{{name}}` template substitution
-export { deployModels } from "./core/modules/deploy.ts";
-export { applyTemplates, resolveTemplates } from "./core/modules/templates.ts";
-export type { TemplateApplication, TemplateSource } from "./core/modules/templates.ts";
+// Model deploy (deploy-by-convention under `resources/`, ADR 0062)
+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";
 

package/src/runtime/run.ts

@@ -50,7 +50,6 @@ export async function runFromEnv(opts: RunOptions = {}): Promise<UrbanApp> {
     manifestPath: opts.manifestPath,
     port: opts.port,
     mount: opts.mount,
-    templates: opts.templates,
   });
   await app.start();