@nanobpm/urban 0.47.0 → 0.49.0

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

@@ -1,6 +1,19 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { expandEnvString, expandEnv, parseManifest, workerJobType } from "./manifest.ts";
+import {
+  expandEnvString,
+  expandEnv,
+  parseManifest,
+  workerJobType,
+  resolveBindMode,
+  resolveBindHost,
+  isBindMode,
+  bindModeToHost,
+  LOOPBACK_HOST,
+  ALL_INTERFACES_HOST,
+  NETWORK_KEYS,
+  type NetworkConfig,
+} from "./manifest.ts";
 
 test("expandEnvString: var, default, and empty fallback", () => {
   const env: Record<string, string> = { FOO: "bar" };
@@ -28,3 +41,50 @@ test("workerJobType returns the taskType", () => {
   assert.equal(workerJobType({ taskType: "a", handler: "h" }), "a");
   assert.equal(workerJobType({ taskType: "llm-job", llm: "gpt" }), "llm-job");
 });
+
+test("bind mode defaults to loopback when the manifest omits network (issue #235)", () => {
+  assert.equal(resolveBindMode({}), "loopback");
+  assert.equal(resolveBindMode({ network: {} }), "loopback");
+  assert.equal(resolveBindHost({}), LOOPBACK_HOST);
+  assert.equal(resolveBindHost({}), "127.0.0.1");
+});
+
+test("manifest network.bind selects the interface", () => {
+  assert.equal(resolveBindMode({ network: { bind: "all" } }), "all");
+  assert.equal(resolveBindHost({ network: { bind: "all" } }), ALL_INTERFACES_HOST);
+  assert.equal(resolveBindHost({ network: { bind: "all" } }), "0.0.0.0");
+  assert.equal(resolveBindHost({ network: { bind: "loopback" } }), "127.0.0.1");
+});
+
+// Drift guard: NETWORK_KEYS is the validator's single source of truth for `network`'s allowed
+// keys. Keep it complete as NetworkConfig grows — every declared key must be listed, or the
+// validator would reject a legitimate field. The `satisfies` pins each entry to a real key.
+test("NETWORK_KEYS lists every NetworkConfig key (issue #235)", () => {
+  const sample = { bind: "loopback" } satisfies Required<NetworkConfig>;
+  for (const key of Object.keys(sample)) {
+    assert.ok(
+      NETWORK_KEYS.some((known) => known === key),
+      `NETWORK_KEYS is missing the '${key}' NetworkConfig key`,
+    );
+  }
+});
+
+test("URBAN_BIND env overrides the manifest, invalid values are ignored", () => {
+  const env = (v: string | undefined) => (n: string) => (n === "URBAN_BIND" ? v : undefined);
+  // env override wins over the manifest in both directions
+  assert.equal(resolveBindMode({ network: { bind: "loopback" } }, env("all")), "all");
+  assert.equal(resolveBindMode({ network: { bind: "all" } }, env("loopback")), "loopback");
+  assert.equal(resolveBindHost({ network: { bind: "loopback" } }, env("all")), "0.0.0.0");
+  // an invalid or empty env value falls through to the manifest/default
+  assert.equal(resolveBindMode({ network: { bind: "all" } }, env("bogus")), "all");
+  assert.equal(resolveBindMode({}, env("")), "loopback");
+});
+
+test("isBindMode / bindModeToHost", () => {
+  assert.equal(isBindMode("loopback"), true);
+  assert.equal(isBindMode("all"), true);
+  assert.equal(isBindMode("nope"), false);
+  assert.equal(isBindMode(undefined), false);
+  assert.equal(bindModeToHost("loopback"), "127.0.0.1");
+  assert.equal(bindModeToHost("all"), "0.0.0.0");
+});

package/src/runtime/core/manifest.ts

@@ -9,7 +9,12 @@
 // used to cause.
 
 import type { HostContext } from "./host.ts";
-import type { AppManifest, Worker } from "@nanobpm/nano-app-schema";
+import { isRecord } from "./guards.ts";
+import type {
+  AppManifest,
+  InstanceTracking as SchemaInstanceTracking,
+  Worker,
+} from "@nanobpm/nano-app-schema";
 
 export type {
   ActionDecl,
@@ -21,7 +26,6 @@ export type {
   DataSource,
   DomainField,
   DomainType,
-  InstanceTracking,
   LlmBinding,
   Models,
   PagesSurface,
@@ -34,11 +38,141 @@ export type {
   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 function isConfiguredStatusSelector(v: unknown): v is readonly string[] {
+  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: Worker): string | undefined {
   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"] as const;
+
+/**
+ * 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 const NETWORK_KEYS: readonly (keyof NetworkConfig)[] = ["bind"];
+
+/** 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 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: unknown): v is BindMode {
+  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: AppManifest | WithNetwork): BindMode | undefined {
+  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: AppManifest | WithNetwork,
+  lookup: (name: string) => string | undefined = () => undefined,
+): BindMode {
+  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: BindMode): string {
+  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: AppManifest | WithNetwork,
+  lookup: (name: string) => string | undefined = () => undefined,
+): string {
+  return bindModeToHost(resolveBindMode(manifest, lookup));
+}
+
 const ENV_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
 
 /**

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

@@ -29,6 +29,7 @@ const engine: EngineClient = {
   cancelInstance: async () => {},
   publishMessage: async () => {},
   searchUserTasks: async () => [],
+  getForm: async () => null,
   completeUserTask: async () => {},
   searchProcessInstances: async () => [],
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),

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

@@ -28,6 +28,7 @@ const engine: EngineClient = {
   cancelInstance: async () => {},
   publishMessage: async () => {},
   searchUserTasks: async () => [],
+  getForm: async () => null,
   searchProcessInstances: async () => [],
   completeUserTask: async () => {},
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),

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

@@ -73,6 +73,7 @@ function cancelEngine(opts: {
     createInstance: notUsed("createInstance"),
     publishMessage: notUsed("publishMessage"),
     searchUserTasks: notUsed("searchUserTasks"),
+    getForm: notUsed("getForm"),
     completeUserTask: notUsed("completeUserTask"),
     registerWorker: notUsed("registerWorker"),
     close: notUsed("close"),

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

@@ -17,6 +17,7 @@ class MiniEngine implements EngineClient {
   async cancelInstance(): Promise<void> {}
   async publishMessage(): Promise<void> {}
   async searchUserTasks(): Promise<[]> { return []; }
+  async getForm(): Promise<null> { return null; }
   async completeUserTask(): Promise<void> {}
   async searchProcessInstances(): Promise<[]> { return []; }
   async registerWorker(jobType: string, handler: JobHandler): Promise<WorkerSubscription> {

package/src/runtime/core/modules/datasource.migrations.test.ts

@@ -16,6 +16,7 @@ const noEngine: EngineClient = {
   cancelInstance: async () => {},
   publishMessage: async () => {},
   searchUserTasks: async () => [],
+  getForm: async () => null,
   completeUserTask: async () => {},
   searchProcessInstances: async () => [],
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),

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

@@ -4,7 +4,6 @@ import type { RuntimeContext } from "../context.ts";
 import type { HostContext } from "../host.ts";
 import type { AppManifest } from "../manifest.ts";
 import { deployModels } from "./deploy.ts";
-import { applyTemplates, resolveTemplates, type TemplateSource } from "./templates.ts";
 
 const ROOT = "/app";
 
@@ -25,14 +24,23 @@ interface Harness {
   deployed: DeployedResource[];
 }
 
-/** A virtual-filesystem host over `files` (keyed by absolute path) plus a recording engine. */
-function makeHarness(
-  files: Record<string, string>,
-  manifest: Partial<AppManifest>,
-  templates?: TemplateSource,
-): Harness {
+/** A virtual-filesystem host over `files` (keyed by absolute path) plus a recording engine. The
+ *  host implements `listDir` (files under a dir) and `listSubdirs` (immediate sub-directories), so
+ *  the convention walk (`resources/*` + `resources/<subdir>/*`) can be exercised. */
+function makeHarness(files: Record<string, string>, manifest: Partial<AppManifest>): Harness {
   const logs: Harness["logs"] = [];
   const deployed: DeployedResource[] = [];
+  const dirsUnder = (dir: string): Set<string> => {
+    const out = new Set<string>();
+    const prefix = `${dir.replace(/\/+$/, "")}/`;
+    for (const f of Object.keys(files)) {
+      if (!f.startsWith(prefix)) continue;
+      const rest = f.slice(prefix.length);
+      const slash = rest.indexOf("/");
+      if (slash > 0) out.add(rest.slice(0, slash));
+    }
+    return out;
+  };
   // biome-ignore lint/plugin: HostContext test double implementing only the fs/log members deployModels exercises; the rest are intentionally absent.
   const host: HostContext = {
     runtime: "node",
@@ -48,6 +56,7 @@ function makeHarness(
       Object.keys(files)
         .filter((f) => dirname(f) === dir)
         .map((f) => f.slice(f.lastIndexOf("/") + 1)),
+    listSubdirs: async (dir: string) => [...dirsUnder(dir)],
   } as unknown as HostContext;
   const engine = {
     deployResources: async (resources: DeployedResource[]) => {
@@ -63,196 +72,123 @@ function makeHarness(
     // biome-ignore lint/plugin: EngineClient test double implementing only deployResources (the sole method deployModels calls).
     engine: engine as unknown as RuntimeContext["engine"],
     host,
-    templates,
   } as unknown as RuntimeContext;
   return { ctx, logs, deployed };
 }
 
-// ── applyTemplates ─────────────────────────────────────────────────────────
-
-test("applyTemplates substitutes a named placeholder", () => {
-  const { content, unresolved } = applyTemplates("<a>{{greet}}</a>", "text/xml", {
-    greet: "hello",
-  });
-  assert.equal(content, "<a>hello</a>");
-  assert.deepEqual(unresolved, []);
-});
-
-test("applyTemplates tolerates inner whitespace in the placeholder", () => {
-  const { content } = applyTemplates("{{  greet  }}", "text/xml", { greet: "hi" });
-  assert.equal(content, "hi");
-});
-
-test("applyTemplates encodes newlines/tabs as XML character references (survives attr normalization)", () => {
-  const { content } = applyTemplates('value="{{p}}"', "text/xml", {
-    p: "line1\nline2\twith <b> & 'q'",
-  });
-  assert.equal(content, 'value="line1&#10;line2&#9;with &lt;b&gt; &amp; &apos;q&apos;"');
-  // Critically, no literal newline/tab remains (those would collapse to spaces in an attribute).
-  assert.ok(!/[\n\t]/.test(content));
-});
-
-test("applyTemplates escapes JSON-string content for .form resources", () => {
-  const { content } = applyTemplates('{"q":"{{p}}"}', "application/json", {
-    p: 'a\nb"c',
-  });
-  assert.equal(content, '{"q":"a\\nb\\"c"}');
-  assert.deepEqual(JSON.parse(content), { q: 'a\nb"c' });
-});
-
-test("applyTemplates leaves unknown placeholders verbatim and reports them once", () => {
-  const { content, unresolved } = applyTemplates("{{x}} {{y}} {{x}}", "text/xml", {});
-  assert.equal(content, "{{x}} {{y}} {{x}}");
-  assert.deepEqual(unresolved, ["x", "y"]);
-});
-
-test("applyTemplates is non-recursive: a template's own braces are not re-expanded", () => {
-  const { content, unresolved } = applyTemplates("{{a}}", "text/xml", {
-    a: "{{b}}",
-    b: "SHOULD-NOT-APPEAR",
-  });
-  assert.equal(content, "{{b}}");
-  assert.deepEqual(unresolved, []);
-});
-
-// ── resolveTemplates ─────────────────────────────────────────────────────────
+// ── models.* override (explicit globs, unchanged behavior) ───────────────────
 
-test("resolveTemplates reads a glob source, keying by file stem", async () => {
-  const { ctx } = makeHarness(
-    { "/app/prompts/review.md": "REVIEW", "/app/prompts/fix-ci.md": "FIXCI" },
-    {},
+test("deployModels uses the manifest models globs when declared, keyed by basename", async () => {
+  const { ctx, deployed } = makeHarness(
+    {
+      "/app/processes/agent.bpmn": "<x/>",
+      "/app/forms/greet.form": "{}",
+      "/app/resources/ignored.bpmn": "<should-not-deploy/>",
+    },
+    { models: { processes: ["processes/*.bpmn"], forms: ["forms/*.form"] } },
   );
-  const map = await resolveTemplates(ctx.host, ROOT, [["prompts/*.md"]]);
-  assert.deepEqual({ ...map }, { review: "REVIEW", "fix-ci": "FIXCI" });
+  const res = await deployModels(ctx);
+  assert.equal(res.deployed, 2);
+  const byName = Object.fromEntries(deployed.map((d) => [d.name, d]));
+  assert.equal(byName["agent.bpmn"].contentType, "text/xml");
+  assert.equal(byName["greet.form"].contentType, "application/json");
+  // With an explicit override, the convention `resources/` walk is skipped entirely.
+  assert.ok(!deployed.some((d) => d.name === "ignored.bpmn"));
 });
 
-test("resolveTemplates scans a bare directory entry", async () => {
-  const { ctx } = makeHarness(
-    { "/app/prompts/a.md": "A", "/app/prompts/b.md": "B" },
-    {},
+test("deployModels deploys content verbatim (no {{name}} substitution remains)", async () => {
+  const { ctx, deployed } = makeHarness(
+    { "/app/processes/agent.bpmn": '<x value="{{review}}" />' },
+    { models: { processes: ["processes/*.bpmn"] } },
   );
-  const map = await resolveTemplates(ctx.host, ROOT, [["prompts"]]);
-  assert.deepEqual({ ...map }, { a: "A", b: "B" });
-});
-
-test("resolveTemplates resolves a literal file entry", async () => {
-  const { ctx } = makeHarness({ "/app/prompts/one.md": "ONE" }, {});
-  const map = await resolveTemplates(ctx.host, ROOT, [["prompts/one.md"]]);
-  assert.deepEqual({ ...map }, { one: "ONE" });
-});
-
-test("resolveTemplates ignores a directory with no readable files without warning", async () => {
-  // A directory that exists (has nested content) but no files directly under it: previously the
-  // non-glob fallback treated it as a literal file and logged a misleading "unreadable entry" warn.
-  const { ctx, logs } = makeHarness({ "/app/prompts/nested/x.md": "X" }, {});
-  const map = await resolveTemplates(ctx.host, ROOT, [["prompts"]]);
-  assert.deepEqual({ ...map }, {});
-  assert.equal(logs.filter((l) => l.level === "warn").length, 0);
-});
-
-test("resolveTemplates merges a programmatic map, letting later sources win", async () => {
-  const { ctx } = makeHarness({ "/app/prompts/review.md": "FROM-FILE" }, {});
-  const map = await resolveTemplates(ctx.host, ROOT, [
-    ["prompts/*.md"],
-    { review: "FROM-MAP", extra: "X" },
-  ]);
-  assert.deepEqual({ ...map }, { review: "FROM-MAP", extra: "X" });
-});
-
-test("resolveTemplates returns a null-prototype map so `__proto__` keys can't pollute", async () => {
-  // A template file literally named `__proto__.md`, or a programmatic map keyed by `__proto__`,
-  // must set a plain own property rather than trip the magic prototype setter on `{}`.
-  const { ctx } = makeHarness({ "/app/prompts/__proto__.md": "PWN" }, {});
-  const map = await resolveTemplates(ctx.host, ROOT, [
-    ["prompts/__proto__.md"],
-    { extra: "X" },
-  ]);
-  assert.equal(Object.getPrototypeOf(map), null);
-  assert.equal(Object.getPrototypeOf({}), Object.prototype, "global prototype untouched");
-  assert.equal(map.extra, "X");
-  assert.equal(Object.prototype.hasOwnProperty.call(map, "__proto__"), true);
+  await deployModels(ctx);
+  assert.equal(deployed[0].content, '<x value="{{review}}" />');
 });
 
-test("resolveTemplates skips a file whose stem is not a valid placeholder name, with a warning", async () => {
-  // `spaced name.md` yields the stem `spaced name`, which the `{{…}}` placeholder charset (`[\w.-]`)
-  // can never match — so it would be unreferenceable and silently ignored. Fail loudly instead.
-  const { ctx, logs } = makeHarness(
-    { "/app/prompts/spaced name.md": "NOPE", "/app/prompts/ok.md": "YES" },
-    {},
+test("deployModels treats a declared-but-empty models block as an override, not convention", async () => {
+  // A present `models` block that resolves to zero files is an explicit override: it must NOT
+  // silently fall back to the `resources/` convention walk (would deploy resources the author
+  // never opted into). Keyed off the block's *presence*, not an empty pattern set.
+  const { ctx, deployed, logs } = makeHarness(
+    { "/app/resources/order.bpmn": "<should-not-deploy/>" },
+    { models: { processes: [] } },
   );
-  const map = await resolveTemplates(ctx.host, ROOT, [["prompts/*.md"]]);
-  assert.deepEqual({ ...map }, { ok: "YES" });
-  const warn = logs.find((l) => l.level === "warn" && l.msg === "template: skipped unsupported name");
-  assert.ok(warn, "expected an unsupported-name warning");
-  assert.equal(warn?.fields?.name, "spaced name");
+  const res = await deployModels(ctx);
+  assert.equal(res.deployed, 0);
+  assert.deepEqual(deployed, []);
+  // No-model-files log (override path), NOT the "no resources found by convention" log.
+  assert.ok(logs.some((l) => l.msg.includes("no model files matched")));
+  assert.ok(!logs.some((l) => l.msg.includes("no resources found by convention")));
 });
 
-// ── deployModels integration ─────────────────────────────────────────────────
+// ── deploy-by-convention (no models declared) ────────────────────────────────
 
-test("deployModels substitutes manifest templates into deployed model content", async () => {
-  const { ctx, deployed } = makeHarness(
+test("deployModels discovers resources/ by convention when no models are declared", async () => {
+  const { ctx, deployed, logs } = makeHarness(
     {
-      "/app/processes/agent.bpmn": '<x value="{{review}}" />',
-      "/app/prompts/review.md": "Do the review",
+      "/app/resources/order.bpmn": "<p/>",
+      "/app/resources/decide.dmn": "<d/>",
+      "/app/resources/prompts/review.md": "Do the review",
+      "/app/resources/forms/greet.form": "{}",
+      // Docs live OUTSIDE resources/ and must never deploy.
+      "/app/docs/guide.md": "# docs",
+      "/app/AGENTS.md": "# agents",
+      "/app/README.md": "# readme",
     },
-    { models: { processes: ["processes/*.bpmn"], templates: ["prompts/*.md"] } },
+    {},
   );
   const res = await deployModels(ctx);
-  assert.equal(res.deployed, 1);
-  assert.equal(deployed[0].name, "agent.bpmn");
-  assert.equal(deployed[0].content, '<x value="Do the review" />');
+  const names = deployed.map((d) => d.name).sort();
+  assert.deepEqual(names, ["decide.dmn", "greet.form", "order.bpmn", "review.md"]);
+  assert.equal(res.deployed, 4);
+  // A prompt (.md under resources/) is a GenericScript resource → octet-stream content type.
+  const prompt = deployed.find((d) => d.name === "review.md");
+  assert.equal(prompt?.contentType, "application/octet-stream");
+  assert.equal(prompt?.content, "Do the review");
+  assert.ok(logs.some((l) => l.fields?.byConvention === true));
 });
 
-test("deployModels lets the programmatic templates option win over the manifest", async () => {
+test("deployModels convention walk is shallow — one level deep only", async () => {
   const { ctx, deployed } = makeHarness(
     {
-      "/app/processes/agent.bpmn": '<x value="{{review}}" />',
-      "/app/prompts/review.md": "FROM-MANIFEST",
+      "/app/resources/top.bpmn": "<a/>",
+      "/app/resources/sub/one.bpmn": "<b/>",
+      // Two levels deep: NOT swept in (shallow-by-convention).
+      "/app/resources/sub/deeper/two.bpmn": "<c/>",
     },
-    { models: { processes: ["processes/*.bpmn"], templates: ["prompts/*.md"] } },
-    { review: "FROM-OPTION" },
+    {},
   );
   await deployModels(ctx);
-  assert.equal(deployed[0].content, '<x value="FROM-OPTION" />');
+  const names = deployed.map((d) => d.name).sort();
+  assert.deepEqual(names, ["one.bpmn", "top.bpmn"]);
 });
 
-test("deployModels warns on an unresolved placeholder but still deploys", async () => {
-  const { ctx, deployed, logs } = makeHarness(
+test("deployModels errors on a basename collision across resources/ subdirs", async () => {
+  const { ctx } = makeHarness(
     {
-      "/app/processes/agent.bpmn": '<x a="{{present}}" b="{{missing}}" />',
-      "/app/prompts/present.md": "HERE",
+      "/app/resources/a/order.bpmn": "<a/>",
+      "/app/resources/b/order.bpmn": "<b/>",
     },
-    { models: { processes: ["processes/*.bpmn"], templates: ["prompts/*.md"] } },
+    {},
   );
-  const res = await deployModels(ctx);
-  assert.equal(res.deployed, 1);
-  assert.equal(deployed[0].content, '<x a="HERE" b="{{missing}}" />');
-  const warn = logs.find((l) => l.msg.includes("unresolved template placeholders"));
-  assert.ok(warn, "expected an unresolved-placeholder warning");
-  assert.deepEqual(warn?.fields?.unresolved, ["missing"]);
+  await assert.rejects(deployModels(ctx), /basename collision/);
 });
 
-test("deployModels leaves unknown-extension resources untouched (no XML escaping)", async () => {
-  // Unknown extensions (application/octet-stream) have no safe escaper, so substitution must be
-  // skipped rather than run the default XML escaper and risk corrupting the resource.
-  const { ctx, deployed } = makeHarness(
+test("deployModels errors on a basename collision under an explicit override too", async () => {
+  const { ctx } = makeHarness(
     {
-      "/app/models/notes.txt": "raw {{review}} & <stuff>",
-      "/app/prompts/review.md": "R",
+      "/app/processes/order.bpmn": "<a/>",
+      "/app/extra/order.bpmn": "<b/>",
     },
-    { models: { processes: ["models/*.txt"], templates: ["prompts/*.md"] } },
+    { models: { processes: ["processes/*.bpmn", "extra/*.bpmn"] } },
   );
-  await deployModels(ctx);
-  assert.equal(deployed[0].contentType, "application/octet-stream");
-  assert.equal(deployed[0].content, "raw {{review}} & <stuff>");
+  await assert.rejects(deployModels(ctx), /basename collision/);
 });
 
-test("deployModels is a no-op on content when no templates are configured", async () => {
-  const { ctx, deployed } = makeHarness(
-    { "/app/processes/agent.bpmn": '<x value="{{review}}" />' },
-    { models: { processes: ["processes/*.bpmn"] } },
-  );
-  await deployModels(ctx);
-  // With no templates, placeholders are left untouched (no substitution pass runs).
-  assert.equal(deployed[0].content, '<x value="{{review}}" />');
+test("deployModels is a no-op when resources/ is empty and no models are declared", async () => {
+  const { ctx, deployed, logs } = makeHarness({ "/app/docs/x.md": "y" }, {});
+  const res = await deployModels(ctx);
+  assert.equal(res.deployed, 0);
+  assert.deepEqual(deployed, []);
+  assert.ok(logs.some((l) => l.msg.includes("no resources found by convention")));
 });