@nanobpm/urban 0.48.0 → 0.49.0

package/src/runtime/core/router.ts

@@ -26,6 +26,16 @@ export function text(body: string, status = 200): HttpResponse {
   return { status, headers: { "content-type": "text/plain; charset=utf-8" }, body };
 }
 
+/**
+ * A `204 No Content` response: an empty body and no `content-type`. Use this
+ * instead of `json(null, 204)` — the latter emits a `"null"` body that both
+ * violates the no-body semantics of 204 and makes a client that parses the
+ * body throw. Any client that short-circuits 204 receives no payload here.
+ */
+export function noContent(): HttpResponse {
+  return { status: 204, headers: {}, body: "" };
+}
+
 /**
  * Normalize a manifest-supplied route path: collapse leading slashes to exactly
  * one, drop trailing slashes. Incoming request paths always start with "/", so a

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

@@ -41,6 +41,9 @@ class FakeEngine implements EngineClient {
   async searchUserTasks() {
     return this.userTasks;
   }
+  async getForm() {
+    return null;
+  }
   async completeUserTask(key: string, variables?: Record<string, unknown>) {
     this.completedTasks.push({ key, variables });
   }
@@ -70,7 +73,7 @@ function expectArray(value: unknown): unknown[] {
   return value;
 }
 
-async function makeFixture(): Promise<string> {
+async function makeFixture(extraManifest?: Record<string, unknown>): Promise<string> {
   const dir = await mkdtemp(join(tmpdir(), "urban-rt-"));
   await mkdir(join(dir, "processes"));
   await mkdir(join(dir, "decisions"));
@@ -103,6 +106,7 @@ async function makeFixture(): Promise<string> {
     workers: [{ taskType: "wf.claim", handler: "workers/handlers.ts" }],
     triggers: [{ id: "hook", type: "webhook", path: "/hooks/task", action: { message: "wf.requested", correlationKey: "= body.taskId" } }],
     surfaces: { taskInbox: { enabled: true, path: "/tasks" } },
+    ...extraManifest,
   };
   await writeFile(join(dir, "nano.app.json"), JSON.stringify(manifest, null, 2));
   return dir;
@@ -569,6 +573,68 @@ test("treats NANOBPMN_APP_HANDSHAKE other than \"1\" as opt-out", async () => {
   }
 });
 
+// Read the interface a started app's HTTP server actually bound to (issue #235).
+function appBoundAddress(app: { httpServer: object | undefined }): string {
+  const native = app.httpServer;
+  assert.ok(native instanceof http.Server, "app exposes a node http.Server");
+  const addr = native.address();
+  assert.ok(addr && typeof addr === "object", "server has a bound AddressInfo");
+  return addr.address;
+}
+
+test("defaults to a loopback bind when the manifest omits network (issue #235)", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  await app.start();
+  try {
+    assert.equal(appBoundAddress(app), "127.0.0.1");
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('manifest network.bind:"all" binds every interface (issue #235)', async () => {
+  const dir = await makeFixture({ network: { bind: "all" } });
+  const logs: Array<{ level: string; msg: string }> = [];
+  const host = createNodeHost({ cwd: dir, log: (level, msg) => logs.push({ level, msg }) });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  await app.start();
+  try {
+    assert.equal(appBoundAddress(app), "0.0.0.0");
+    // exposing the app off-box must never be silent
+    assert.ok(
+      logs.some((l) => l.level === "warn" && l.msg.includes("all interfaces")),
+      "a warning is logged when binding to all interfaces",
+    );
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("URBAN_BIND=all overrides a loopback manifest (issue #235)", async () => {
+  const dir = await makeFixture({ network: { bind: "loopback" } });
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const prev = process.env.URBAN_BIND;
+  process.env.URBAN_BIND = "all";
+  let app: Awaited<ReturnType<typeof createUrbanApp>> | undefined;
+  try {
+    app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+    await app.start();
+    assert.equal(appBoundAddress(app), "0.0.0.0");
+  } finally {
+    if (prev === undefined) delete process.env.URBAN_BIND;
+    else process.env.URBAN_BIND = prev;
+    await app?.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 // A minimal deterministic scheduler seam: records armed timers so a test can assert the
 // injected scheduler — not the live one — drives createUrbanApp's background loops.
 function countingScheduler(): SchedulerDeps & { armed: () => number } {

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({