@nanobpm/urban 0.52.0 → 0.53.0

package/src/runtime/core/glob.ts

@@ -63,12 +63,13 @@ export async function expandPatterns(
 }
 
 /**
- * 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.
+ * Discover deployables under a convention directory (`resources/`), **recursively** — every file
+ * directly under `dir` and under every sub-directory at any depth (issue #231). Recursive descent
+ * is safe because deploy now keys a convention resource by its path *relative to* `resources/`
+ * (POSIX), not its bare basename, so two files sharing a filename in different sub-dirs
+ * (`a/x.md`, `b/x.md`) resolve to distinct `resourceId`s and can never collide. 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: HostContext,
@@ -77,11 +78,13 @@ export async function discoverResources(
 ): Promise<string[]> {
   const base = joinPath(root, dir);
   const out: string[] = [];
-  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));
-  }
+  const walk = async (current: string): Promise<void> => {
+    for (const name of await host.listDir(current)) out.push(joinPath(current, name));
+    const subdirs = host.listSubdirs ? await host.listSubdirs(current) : [];
+    for (const sub of subdirs.slice().sort()) {
+      await walk(joinPath(current, sub));
+    }
+  };
+  await walk(base);
   return out.sort();
 }

package/src/runtime/core/host.ts

@@ -267,7 +267,10 @@ export interface FormSchema {
  * it against a live engine; tests implement it in-memory. Core modules depend only on this.
  */
 export interface EngineClient {
-  /** Deploy model resources (BPMN/DMN/forms). Returns the number deployed. */
+  /** Deploy model resources (BPMN/DMN/forms) and generic resources (prompts, scripts, and other
+   *  arbitrary files, content-typed e.g. `text/markdown`/`application/octet-stream`; the engine
+   *  versions each generic resource per its `resourceId` — carried on `name`). Returns the number
+   *  deployed. */
   deployResources(
     resources: { name: string; content: string; contentType: string }[],
   ): Promise<{ deployed: number }>;

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

@@ -0,0 +1,104 @@
+// Tests for the app-scoped institutional-memory brief surface (ADR 0060 §2): `/app/agent` +
+// `/app/agent.json` read through to the `urban gen`-derived `nano-generated/system-brief.*`.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mountAgent } from "./agent.ts";
+import type { RuntimeContext } from "../context.ts";
+import type { EngineClient, HostContext, HttpRequest, HttpResponse } from "../host.ts";
+
+const fakeEngine: EngineClient = {
+  deployResources: async () => ({ deployed: 0 }),
+  createInstance: async () => ({ processInstanceKey: "pi" }),
+  cancelInstance: async () => {},
+  publishMessage: async () => {},
+  searchUserTasks: async () => [],
+  getForm: async () => null,
+  completeUserTask: async () => {},
+  searchProcessInstances: async () => [],
+  registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
+  close: async () => {},
+};
+
+/** A RuntimeContext whose host resolves a fixed set of files (a missing path throws, like a real
+ *  file port). Only the fields `mountAgent` touches are populated. */
+function ctxWithFiles(files: Record<string, string>): RuntimeContext {
+  const host: HostContext = {
+    runtime: "node",
+    env: () => undefined,
+    readTextFile: async (p: string) => {
+      if (!(p in files)) throw new Error(`ENOENT ${p}`);
+      return files[p];
+    },
+    listDir: async () => [],
+    exists: async (p: string) => p in files,
+    openSqlite: () => {
+      throw new Error("sqlite not used in this test");
+    },
+    importModule: async () => ({}),
+    serveHttp: async () => ({ port: 0, stop: async () => {} }),
+    now: () => 0,
+    log: () => {},
+  };
+  return { root: ".", manifest: { schemaVersion: 1, id: "app", name: "App" }, host, engine: fakeEngine };
+}
+
+async function call(route: { handler: (req: HttpRequest) => HttpResponse | Promise<HttpResponse> }): Promise<HttpResponse> {
+  return route.handler({
+    method: "GET",
+    path: "/",
+    query: new URLSearchParams(),
+    headers: new Headers(),
+    text: async () => "",
+  });
+}
+
+const routeAt = (ctx: RuntimeContext, path: string) => {
+  const r = mountAgent(ctx).routes.find((x) => x.path === path);
+  assert.ok(r, `expected an ${path} route`);
+  return r;
+};
+
+test("GET /app/agent serves the derived system-brief.md as markdown", async () => {
+  const ctx = ctxWithFiles({ "./nano-generated/system-brief.md": "# App — system brief\n" });
+  const res = await call(routeAt(ctx, "/app/agent"));
+  assert.equal(res.status, 200);
+  assert.match(res.headers?.["content-type"] ?? "", /text\/markdown/);
+  assert.equal(res.body, "# App — system brief\n");
+});
+
+test("GET /app/agent.json serves the derived system-brief.json verbatim", async () => {
+  const payload = '{\n  "app": "App",\n  "processes": ["p"]\n}\n';
+  const ctx = ctxWithFiles({ "./nano-generated/system-brief.json": payload });
+  const res = await call(routeAt(ctx, "/app/agent.json"));
+  assert.equal(res.status, 200);
+  assert.match(res.headers?.["content-type"] ?? "", /application\/json/);
+  assert.equal(res.body, payload);
+  assert.deepEqual(JSON.parse(res.body).processes, ["p"]);
+});
+
+test("brief artifacts resolve under ctx.root (rooted host keys), not the raw cwd-relative path", async () => {
+  const ctx = ctxWithFiles({ "/srv/app/nano-generated/system-brief.md": "# rooted\n" });
+  ctx.root = "/srv/app";
+  const res = await call(routeAt(ctx, "/app/agent"));
+  assert.equal(res.status, 200);
+  assert.equal(res.body, "# rooted\n");
+});
+
+test("a missing brief (gen never ran) is a 404, not a crash", async () => {
+  const ctx = ctxWithFiles({});
+  const md = await call(routeAt(ctx, "/app/agent"));
+  const jsonRes = await call(routeAt(ctx, "/app/agent.json"));
+  assert.equal(md.status, 404);
+  assert.equal(jsonRes.status, 404);
+});
+
+test("a non-ENOENT read error surfaces (500 via the host) instead of being masked as a 404", async () => {
+  const ctx = ctxWithFiles({ "./nano-generated/system-brief.md": "unused" });
+  ctx.host.readTextFile = async () => {
+    throw new Error("EACCES: permission denied");
+  };
+  // exists() still reports the artifact present, so the handler must not swallow the read error
+  // into a 404 — it lets it propagate, which the host server turns into a 500.
+  await assert.rejects(call(routeAt(ctx, "/app/agent")), /EACCES/);
+});

package/src/runtime/core/modules/agent.ts

@@ -0,0 +1,76 @@
+// agent — the app-scoped institutional-memory brief surface (ADR 0060 §2). The app-level mirror
+// of the node `/agent` brief (ADR 0051): where the node brief describes the whole runtime, this
+// serves ONE app's derived `system-brief.md` / `system-brief.json` so an agent (or human) opening
+// work on the app starts grounded in the app's own system model — its processes, service-task call
+// graph, decisions, and ownership.
+//
+//   GET /app/agent       → nano-generated/system-brief.md   (text/markdown)
+//   GET /app/agent.json  → nano-generated/system-brief.json (application/json)
+//
+// The brief is derived by `urban gen` (systemBriefDeriver, wired in gen.ts) into the app's
+// `nano-generated/` dir, so this route is a thin read-through of that artifact — no re-derivation
+// at request time (the derived file is the single source of truth, kept honest by
+// `urban gen --check`). Mounted unconditionally: the brief is a property of the app's models, not
+// of any opt-in surface, so it is always addressable when a brief has been generated. An app whose
+// models produced no brief (never ran gen) returns 404.
+
+import { GENERATED_DIR } from "../../../toolkit/artifact.ts";
+import { SYSTEM_BRIEF_JSON, SYSTEM_BRIEF_MD } from "../../../toolkit/derivers/system-brief.ts";
+import type { RuntimeContext } from "../context.ts";
+import type { HttpResponse } from "../host.ts";
+import { json, type Route } from "../router.ts";
+import { resolveAppPath } from "./datasource.ts";
+
+/** The app-relative path of a generated brief artifact. */
+const briefPath = (name: string): string => `${GENERATED_DIR}/${name}`;
+
+export interface AgentHandle {
+  readonly name: string;
+  routes: Route[];
+  describe(): Record<string, unknown>;
+}
+
+function markdown(body: string): HttpResponse {
+  return { status: 200, headers: { "content-type": "text/markdown; charset=utf-8" }, body };
+}
+
+/**
+ * Mount the `/app/agent` (+ `/app/agent.json`) institutional-memory brief routes. Reads the
+ * `urban gen`-derived artifacts through the host file port, resolving each under `ctx.root` via
+ * the shared `resolveAppPath` (like every other runtime module) so serving never depends on the
+ * host's current working directory. A genuinely absent artifact — checked with `host.exists`
+ * rather than a blanket catch — yields a 404 (gen never ran, or the app has no models); any other
+ * read failure (permissions, transient I/O) is left to surface as a 500 rather than being masked
+ * as "not generated".
+ */
+export function mountAgent(ctx: RuntimeContext): AgentHandle {
+  const artifactPath = (name: string): string => resolveAppPath(ctx.root, briefPath(name));
+  const notGenerated = (): HttpResponse =>
+    json({ error: "system brief not generated — run `urban gen`" }, 404);
+  const serve = async (name: string, toResponse: (body: string) => HttpResponse): Promise<HttpResponse> => {
+    const path = artifactPath(name);
+    if (!(await ctx.host.exists(path))) return notGenerated();
+    return toResponse(await ctx.host.readTextFile(path));
+  };
+  const routes: Route[] = [
+    {
+      method: "GET",
+      path: "/app/agent",
+      source: "surface:agent",
+      handler: () => serve(SYSTEM_BRIEF_MD, markdown),
+    },
+    {
+      method: "GET",
+      path: "/app/agent.json",
+      source: "surface:agent",
+      handler: () =>
+        serve(SYSTEM_BRIEF_JSON, (body) => ({
+          status: 200,
+          headers: { "content-type": "application/json" },
+          body,
+        })),
+    },
+  ];
+  ctx.host.log("info", "agent brief surface mounted", { routes: routes.length });
+  return { name: "agent", routes, describe: () => ({ routes: routes.map((r) => r.path) }) };
+}

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

@@ -26,8 +26,12 @@ interface 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 {
+ *  the recursive convention walk (every file under `resources/` at any depth) can be exercised. */
+function makeHarness(
+  files: Record<string, string>,
+  manifest: Partial<AppManifest>,
+  engineOverride?: { deployResources: (r: DeployedResource[]) => Promise<{ deployed: number }> },
+): Harness {
   const logs: Harness["logs"] = [];
   const deployed: DeployedResource[] = [];
   const dirsUnder = (dir: string): Set<string> => {
@@ -58,7 +62,7 @@ function makeHarness(files: Record<string, string>, manifest: Partial<AppManifes
         .map((f) => f.slice(f.lastIndexOf("/") + 1)),
     listSubdirs: async (dir: string) => [...dirsUnder(dir)],
   } as unknown as HostContext;
-  const engine = {
+  const engine = engineOverride ?? {
     deployResources: async (resources: DeployedResource[]) => {
       deployed.push(...resources);
       return { deployed: resources.length };
@@ -138,43 +142,107 @@ test("deployModels discovers resources/ by convention when no models are declare
     {},
   );
   const res = await deployModels(ctx);
+  // Convention resources are keyed by their path RELATIVE to resources/ (POSIX), not the basename.
   const names = deployed.map((d) => d.name).sort();
-  assert.deepEqual(names, ["decide.dmn", "greet.form", "order.bpmn", "review.md"]);
+  assert.deepEqual(names, ["decide.dmn", "forms/greet.form", "order.bpmn", "prompts/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");
+  // A prompt (.md under resources/) is a generic resource content-typed text/markdown, deployed
+  // verbatim and keyed by its relative-path resourceId.
+  const prompt = deployed.find((d) => d.name === "prompts/review.md");
+  assert.equal(prompt?.contentType, "text/markdown");
   assert.equal(prompt?.content, "Do the review");
   assert.ok(logs.some((l) => l.fields?.byConvention === true));
 });
 
-test("deployModels convention walk is shallow — one level deep only", async () => {
+test("deployModels convention walk is recursive — every file at any depth", async () => {
   const { ctx, deployed } = makeHarness(
     {
       "/app/resources/top.bpmn": "<a/>",
       "/app/resources/sub/one.bpmn": "<b/>",
-      // Two levels deep: NOT swept in (shallow-by-convention).
+      // Two levels deep: now swept in (recursive-by-convention, issue #231).
       "/app/resources/sub/deeper/two.bpmn": "<c/>",
     },
     {},
   );
   await deployModels(ctx);
   const names = deployed.map((d) => d.name).sort();
-  assert.deepEqual(names, ["one.bpmn", "top.bpmn"]);
+  assert.deepEqual(names, ["sub/deeper/two.bpmn", "sub/one.bpmn", "top.bpmn"]);
 });
 
-test("deployModels errors on a basename collision across resources/ subdirs", async () => {
-  const { ctx } = makeHarness(
+test("deployModels keys same-named files in different subdirs as distinct relative-path resources", async () => {
+  // resources/a/x.md and resources/b/x.md share a basename but deploy as distinct resourceIds —
+  // no collision (issue #231).
+  const { ctx, deployed } = makeHarness(
     {
-      "/app/resources/a/order.bpmn": "<a/>",
-      "/app/resources/b/order.bpmn": "<b/>",
+      "/app/resources/a/order.md": "<a/>",
+      "/app/resources/b/order.md": "<b/>",
     },
     {},
   );
-  await assert.rejects(deployModels(ctx), /basename collision/);
+  const res = await deployModels(ctx);
+  assert.equal(res.deployed, 2);
+  const byName = Object.fromEntries(deployed.map((d) => [d.name, d]));
+  assert.equal(byName["a/order.md"].content, "<a/>");
+  assert.equal(byName["b/order.md"].content, "<b/>");
+});
+
+test("deployModels infers a content type per extension for generic resources", async () => {
+  const { ctx, deployed } = makeHarness(
+    {
+      "/app/resources/prompts/plan.md": "# plan",
+      "/app/resources/data/config.json": "{}",
+      "/app/resources/notes/readme.txt": "hi",
+      "/app/resources/bin/blob.rpa": "\u0000binary",
+    },
+    {},
+  );
+  await deployModels(ctx);
+  const byName = Object.fromEntries(deployed.map((d) => [d.name, d]));
+  assert.equal(byName["prompts/plan.md"].contentType, "text/markdown");
+  assert.equal(byName["data/config.json"].contentType, "application/json");
+  assert.equal(byName["notes/readme.txt"].contentType, "text/plain");
+  // Unknown extension → octet-stream, deployed verbatim (never mislabelled/mangled).
+  assert.equal(byName["bin/blob.rpa"].contentType, "application/octet-stream");
+  assert.equal(byName["bin/blob.rpa"].content, "\u0000binary");
+});
+
+test("deployModels deploys a generic resource verbatim (no {{token}} substitution)", async () => {
+  const { ctx, deployed } = makeHarness(
+    { "/app/resources/prompts/review.md": "Review {{pr}} carefully" },
+    {},
+  );
+  await deployModels(ctx);
+  assert.equal(deployed[0].content, "Review {{pr}} carefully");
+});
+
+test("deployModels redeploy is idempotent per resourceId+content, new content bumps the version", async () => {
+  // Model the engine's name+checksum duplicate rule: identical resourceId+content is skipped (no
+  // version bump); changed content advances the latest pointer (issue #231 acceptance).
+  const versions = new Map<string, string[]>();
+  const engine = {
+    deployResources: async (resources: DeployedResource[]) => {
+      let deployed = 0;
+      for (const r of resources) {
+        const history = versions.get(r.name) ?? [];
+        if (history[history.length - 1] !== r.content) {
+          history.push(r.content);
+          versions.set(r.name, history);
+          deployed++;
+        }
+      }
+      return { deployed };
+    },
+  };
+  const files: Record<string, string> = { "/app/resources/prompts/plan.md": "v1" };
+  const mk = () => makeHarness(files, {}, engine).ctx;
+  assert.equal((await deployModels(mk())).deployed, 1); // first deploy → v1
+  assert.equal((await deployModels(mk())).deployed, 0); // unchanged → no-op
+  files["/app/resources/prompts/plan.md"] = "v2";
+  assert.equal((await deployModels(mk())).deployed, 1); // changed → new version
+  assert.deepEqual(versions.get("prompts/plan.md"), ["v1", "v2"]);
 });
 
-test("deployModels errors on a basename collision under an explicit override too", async () => {
+test("deployModels errors on a basename collision under an explicit override", async () => {
   const { ctx } = makeHarness(
     {
       "/app/processes/order.bpmn": "<a/>",

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

@@ -2,26 +2,53 @@
 //
 // Resources are found by ONE of two paths:
 //   1. Convention (the default, ADR 0062): when the manifest declares no `models`, deployables are
-//      discovered by walking `resources/` — shallow, one level deep. `resources/` is deploy-only:
-//      everything under it (and nothing outside it) is deployed. Docs (`docs/`, `AGENTS.md`,
-//      top-level `*.md`) live outside `resources/` and are never swept in.
+//      discovered by walking `resources/` **recursively** — every file under it, at any depth
+//      (issue #231). `resources/` is deploy-only: everything under it (and nothing outside it) is
+//      deployed. Docs (`docs/`, `AGENTS.md`, top-level `*.md`) live outside `resources/` and are
+//      never swept in. A convention resource's deploy key (`resourceId`) is its path **relative to
+//      `resources/`** (POSIX-normalised), e.g. `resources/prompts/plan.md` → `prompts/plan.md`, so
+//      a linked service task references it with `zeebe:linkedResource resourceId="prompts/plan.md"`.
+//      The relative path (not the bare basename) preserves sub-directory structure and lets two
+//      files sharing a filename in different sub-dirs (`a/x.md`, `b/x.md`) deploy as distinct
+//      resources — there is no basename-collision hazard.
 //   2. Explicit override: when the manifest declares `models` globs, those are used exactly (the
-//      convention walk is skipped) — the escape hatch for a non-convention layout.
+//      convention walk is skipped) — the escape hatch for a non-convention layout. Override
+//      resources are keyed by basename (filename only), so a basename collision across the declared
+//      globs is a hard error, detected up front.
 //
-// Either way the deploy dedupe key is the resource's basename (filename only), so a basename
-// collision — two files with the same name in different directories — would silently clobber one
-// resource with another at the engine. We detect that up front and fail loudly instead.
+// Content is deployed **verbatim** — there is no deploy-time `{{token}}` substitution (removed in
+// ADR 0062) — so a generic resource (a prompt `.md`, an RPA/script file) is deployed as-is.
+// The deploy pipeline is **UTF-8 text only**, end-to-end: `host.readTextFile()` yields a `string`
+// and the engine's `deployResources` takes `content: string`, so there is no byte channel and
+// arbitrary binary is out of scope by design. "Verbatim" therefore means the UTF-8 text is passed
+// through unchanged; a non-UTF-8/binary file swept into `resources/` is not a supported input (see
+// `contentTypeFor`'s `application/octet-stream` note).
 
 import type { RuntimeContext } from "../context.ts";
 import { discoverResources, expandPatterns } from "../glob.ts";
 
-/** The convention directory: deploy-only, walked one level deep when no `models` are declared. */
+/** The convention directory: deploy-only, walked recursively when no `models` are declared. */
 export const RESOURCES_DIR = "resources";
 
+/**
+ * Classify a file into an engine content type by extension. Models get their real XML/JSON types;
+ * generic resources get a real text content type where the extension is known (`.md`, `.json`,
+ * `.txt`), falling back to `application/octet-stream` for anything unrecognised (so an unknown
+ * extension is never mislabelled as a specific text type). Note the deploy pipeline is UTF-8 text
+ * only (`readTextFile` → engine `content: string`): the `octet-stream` fallback is a conservative
+ * MIME label for an unrecognised *text* resource (e.g. a script with an uncommon extension), not a
+ * promise of binary fidelity — a genuinely binary file cannot be preserved byte-for-byte and is
+ * out of scope. The engine deploys a non-model content type as a generic resource
+ * (versioned per `resourceId`); a service task resolves it via
+ * `zeebe:linkedResource resourceId="<id>" bindingType:latest`.
+ */
 function contentTypeFor(path: string): string {
   if (path.endsWith(".bpmn")) return "text/xml";
   if (path.endsWith(".dmn")) return "text/xml";
   if (path.endsWith(".form")) return "application/json";
+  if (path.endsWith(".md")) return "text/markdown";
+  if (path.endsWith(".json")) return "application/json";
+  if (path.endsWith(".txt")) return "text/plain";
   return "application/octet-stream";
 }
 
@@ -30,8 +57,19 @@ function baseName(path: string): string {
   return i >= 0 ? path.slice(i + 1) : path;
 }
 
-/** Fail loudly when two resolved files share a basename (the deploy dedupe key), naming the
- *  colliding paths so the author can rename or relocate one. */
+/**
+ * A convention resource's `resourceId`: its path relative to `<root>/resources/` (POSIX). Given a
+ * root-prefixed discovered path (`/app/resources/prompts/plan.md`) it returns `prompts/plan.md`.
+ * Falls back to the basename if — defensively — the path is not under the resources prefix.
+ */
+function relativeResourceId(path: string, root: string): string {
+  const prefix = `${root.replace(/\/+$/, "")}/${RESOURCES_DIR}/`;
+  return path.startsWith(prefix) ? path.slice(prefix.length) : baseName(path);
+}
+
+/** Fail loudly when two resolved files share a basename (the override dedupe key), naming the
+ *  colliding paths so the author can rename or relocate one. Only relevant for the `models`
+ *  override path; convention resources are keyed by relative path and cannot collide. */
 function assertNoBasenameCollisions(files: string[]): void {
   const byName = new Map<string, string[]>();
   for (const path of files) {
@@ -52,11 +90,14 @@ function assertNoBasenameCollisions(files: string[]): void {
 }
 
 /**
- * Deploy the app's processes, decisions and forms.
+ * Deploy the app's resources.
  *
- * With no manifest `models`, deployables are discovered by convention under `resources/` (shallow,
- * one level deep). With `models` globs declared, those are used verbatim. Basename collisions are a
- * hard error in either mode.
+ * With no manifest `models`, deployables are discovered by convention under `resources/`
+ * (recursively — every file at any depth) and each is keyed by its path relative to `resources/`
+ * (POSIX). With `models` globs declared, those are used verbatim and keyed by basename (a basename
+ * collision is a hard error). Content is deployed verbatim (no template substitution); each file is
+ * content-typed by extension so a generic resource (e.g. a prompt `.md`) deploys as a versioned
+ * generic resource the engine resolves via `zeebe:linkedResource bindingType:latest`.
  */
 export async function deployModels(ctx: RuntimeContext): Promise<{ deployed: number; files: string[] }> {
   const models = ctx.manifest.models;
@@ -81,10 +122,12 @@ export async function deployModels(ctx: RuntimeContext): Promise<{ deployed: num
     }
     return { deployed: 0, files: [] };
   }
-  assertNoBasenameCollisions(files);
+  // Convention resources are keyed by their (unique) relative path; only the override path, whose
+  // basename key can collide across globs, needs the collision guard.
+  if (!byConvention) assertNoBasenameCollisions(files);
   const resources = await Promise.all(
     files.map(async (path) => ({
-      name: baseName(path),
+      name: byConvention ? relativeResourceId(path, ctx.root) : baseName(path),
       content: await ctx.host.readTextFile(path),
       contentType: contentTypeFor(path),
     })),