@nanobpm/urban 0.47.0 → 0.49.0

package/src/toolkit/gen.ts

@@ -6,10 +6,11 @@
 import type { DerivedArtifact } from "./artifact.ts";
 import { GENERATED_DIR, isAbsolutePath, RUNTIME_MATERIALIZED_ARTIFACTS, sortArtifacts } from "./artifact.ts";
 import { deriveMigrations, type ToolkitManifest } from "./derivers/migrations.ts";
-import { deriveDomain } from "./derivers/domain.ts";
-import { deriveWorkerBindings, type ModelSource } from "./derivers/worker-io.ts";
+import { emitDomainModel, registryFromManifest, sourcesFromManifest } from "./derivers/domain.ts";
+import { byModelPath, deriveWorkerBindings, detectEnvelopeConflicts, DOMAIN_DTS, formatEnvelopeConflict, type ModelSource, scanModelWorkers } from "./derivers/worker-io.ts";
 import { deriveMeta } from "./derivers/meta.ts";
 import { deriveMessageBindings } from "./derivers/messages.ts";
+import { resolveShapes, scanModelShapes } from "./derivers/shapes.ts";
 import { deriveApi } from "./derivers/api.ts";
 import { parseSpec, sharedRequestBodySchemas } from "../openapi/spec.ts";
 import { deriveModels, type DerivedModels, type ModelError, MODEL_PROVENANCE } from "./models.ts";
@@ -20,6 +21,12 @@ export interface GenIO {
   writeText(path: string, content: string): Promise<void>;
   /** File names (not paths) in a directory; empty if it does not exist. */
   listDir(path: string): Promise<string[]>;
+  /**
+   * Sub-directory names (not files) in a directory; empty if it does not exist. Optional: the
+   * deploy-by-convention model scan uses it to descend one level into `resources/<subdir>/`. When
+   * absent, only files directly under `resources/` are scanned.
+   */
+  listSubdirs?(path: string): Promise<string[]>;
   exists(path: string): Promise<boolean>;
   /**
    * Import an app module and return its exports. Optional: only present when the caller runs on
@@ -98,19 +105,66 @@ export async function expandPattern(root: string, io: GenIO, pattern: string): P
     .sort();
 }
 
-/** Read + resolve the app's process models from the manifest's `models.processes` patterns. */
+/** The deploy-by-convention directory (ADR 0062): when the manifest declares no `models`, both the
+ *  runtime deploy and this codegen scan discover deployables/models under it — shallow, one level
+ *  deep (`resources/*` and `resources/<subdir>/*`). Deploy-only by convention. */
+export const RESOURCES_DIR = "resources";
+
+/** Model file extensions the `nano:shape`/code-first scan reads by convention (BPMN + DMN). */
+const MODEL_EXTS = [".bpmn", ".dmn"];
+
+/**
+ * Discover model files under `resources/` by convention — shallow, one level deep (`resources/*`
+ * and `resources/<subdir>/*`), never deeper — mirroring the runtime deploy walk so the codegen scan
+ * and the deploy see the same set. Returns root-relative paths, sorted. Descending one level needs
+ * `io.listSubdirs`; without it only the files directly under `resources/` are scanned.
+ */
+export async function discoverResourceModels(root: string, io: GenIO): Promise<string[]> {
+  const isModel = (n: string): boolean => MODEL_EXTS.some((e) => n.endsWith(e));
+  const out: string[] = [];
+  for (const n of await io.listDir(join(root, RESOURCES_DIR))) {
+    if (isModel(n)) out.push(`${RESOURCES_DIR}/${n}`);
+  }
+  const subdirs = io.listSubdirs ? await io.listSubdirs(join(root, RESOURCES_DIR)) : [];
+  for (const sub of subdirs.slice().sort()) {
+    for (const n of await io.listDir(join(root, `${RESOURCES_DIR}/${sub}`))) {
+      if (isModel(n)) out.push(`${RESOURCES_DIR}/${sub}/${n}`);
+    }
+  }
+  return out.sort();
+}
+
+/**
+ * Read + resolve the app's process models. Convention is keyed off the *absence* of the entire
+ * `models` block — mirroring the runtime deploy (ADR 0062): with no `models` block, models are
+ * discovered by convention under `resources/`; with a `models` block declared, `models.processes`
+ * is the explicit override (used verbatim, possibly empty). Keying off a missing `models.processes`
+ * alone would fall back to convention even when a `models` block is present for other overrides
+ * (e.g. forms), letting gen scan/derive process models the runtime deploy will never deploy —
+ * gen/runtime drift.
+ */
 export async function readModels(
   root: string,
   io: GenIO,
   manifest: { models?: { processes?: string[] } },
 ): Promise<ModelSource[]> {
-  const procPatterns = manifest.models?.processes ?? [];
-  const models: ModelSource[] = [];
-  for (const pat of procPatterns) {
-    for (const rel of await expandPattern(root, io, pat)) {
-      models.push({ path: rel, xml: await io.readText(join(root, rel)) });
+  const byConvention = manifest.models === undefined;
+  let rels: string[];
+  if (byConvention) {
+    rels = await discoverResourceModels(root, io);
+  } else {
+    rels = [];
+    for (const pat of manifest.models?.processes ?? []) {
+      rels.push(...(await expandPattern(root, io, pat)));
     }
   }
+  const models: ModelSource[] = [];
+  const seen = new Set<string>();
+  for (const rel of rels) {
+    if (seen.has(rel)) continue;
+    seen.add(rel);
+    models.push({ path: rel, xml: await io.readText(join(root, rel)) });
+  }
   return models;
 }
 
@@ -133,29 +187,62 @@ async function collectAll(opts: GenOptions): Promise<{ artifacts: DerivedArtifac
   const artifacts: DerivedArtifact[] = [];
   const warnings: string[] = [];
 
-  // 1. types → migrations + domain row types (DomainTables spine + DomainTypes registry)
+  // 1. Resolve the app's models first (code-first `workflows/*.ts` → BPMN, plus authored on-disk
+  //    `.bpmn`): the fused domain model (below) lifts `nano:shape` envelopes *from* the models, so
+  //    they must be in hand before the domain + worker/message type-contracts are derived.
+  const derived = await deriveModels(root, io, manifest);
+  //    The derived `.bpmn` are emitted only when `emitModels` (default), but always fed to the
+  //    type-contract derivers so worker I/O works for a code-first app even on a `--no-models` run.
+  if (emitModels) artifacts.push(...derived.artifacts);
+  const derivedPaths = new Set(derived.artifacts.map((a) => a.path));
+  const diskModels = (await readModels(root, io, manifest)).filter((m) => !derivedPaths.has(m.path));
+  const models = [...diskModels, ...derived.models];
+
+  // 2. Fused domain model (ADR 0040): the `DomainTypes` registry is the union of the manifest
+  //    `types` registry and the model-authored `nano:shape` envelopes, resolved through the same
+  //    fuse the console reifier (`envelope_scan.rs`) uses. Without this the standalone `urban gen`
+  //    would honour only `manifest.types` and silently ignore every model-authored data envelope,
+  //    so worker/message I/O against those envelopes would fall back to the untyped `WorkerVars`.
+  const manifestRegistry = registryFromManifest(manifest);
+  const sources = sourcesFromManifest(manifest);
+  const shapeDecls = models.flatMap((m) => scanModelShapes(m.xml));
+  const shapeResolution = resolveShapes(shapeDecls, manifestRegistry, sources);
+  const fusedTypes = { ...manifestRegistry, ...shapeResolution.types };
+  for (const d of shapeResolution.diagnostics) {
+    warnings.push(`data-envelope shape "${d.shape}" (${d.kind}): ${d.message}`);
+  }
+
+  // 3. types → migrations (persisted `manifest.types` only — shapes are transient wire envelopes,
+  //    never tables) + the fused domain row types (`DomainTables` spine + `DomainTypes` registry).
   if (!opts.modelsOnly && manifest.types && Object.keys(manifest.types).length > 0) {
     artifacts.push(...deriveMigrations(manifest));
-    artifacts.push(...deriveDomain(manifest));
+  }
+  if (!opts.modelsOnly && Object.keys(fusedTypes).length > 0) {
+    artifacts.push({
+      path: `${GENERATED_DIR}/${DOMAIN_DTS}`,
+      content: emitDomainModel(sources, manifest.data?.default ?? "app", fusedTypes),
+    });
   }
 
-  // 2. code-first models → derive BPMN from `workflows/*.ts` (executes the app's TS). The derived
-  //    `.bpmn` are emitted only when `emitModels` (default), but always fed to the type-contract
-  //    derivers below so worker I/O works for a code-first app even on a `--no-models` run.
-  const derived = await deriveModels(root, io, manifest);
-  if (emitModels) artifacts.push(...derived.artifacts);
-
-  // 3. models (authored on-disk + derived) → worker I/O index + meta accessor + message map.
-  //    Drop any on-disk model whose path a derived model already covers, to avoid double-counting.
+  // 4. models (authored on-disk + derived) → worker I/O index + meta accessor + message map. The
+  //    declared type ids include the fused shapes, so an envelope ref to a model-authored shape
+  //    resolves to its `DomainTypes[...]` entry instead of degrading to the untyped fallback.
   if (!opts.modelsOnly) {
-    const derivedPaths = new Set(derived.artifacts.map((a) => a.path));
-    const diskModels = (await readModels(root, io, manifest)).filter((m) => !derivedPaths.has(m.path));
-    const models = [...diskModels, ...derived.models];
     if (models.length > 0) {
-      const declaredTypeIds = Object.keys(manifest.types ?? {});
+      const declaredTypeIds = Object.keys(fusedTypes);
       artifacts.push(...deriveWorkerBindings(models, declaredTypeIds));
       artifacts.push(...deriveMeta(models));
       artifacts.push(...deriveMessageBindings(models, declaredTypeIds));
+      // Surface genuine data-envelope conflicts: a taskType whose variants disagree on a field's
+      // TYPE. The emitted contract is the union of the variants (sound for a shared handler), so a
+      // type clash would silently widen to `A | B` — warn instead so the author unifies the envelope.
+      const scannedWorkers = [...models]
+        .sort(byModelPath)
+        .flatMap((m) => scanModelWorkers(m.xml))
+        .map((w) => ({ taskType: w.taskType, inputType: w.in, outputType: w.out }));
+      for (const c of detectEnvelopeConflicts(scannedWorkers, fusedTypes)) {
+        warnings.push(formatEnvelopeConflict(c));
+      }
     }
   }
 

package/src/toolkit/models.test.ts

@@ -64,13 +64,13 @@ test("bpmnFilename sanitizes ids into safe .bpmn filenames", () => {
   assert.equal(bpmnFilename("a b:c"), "a-b-c.bpmn");
 });
 
-test("processesOutDir defaults to processes/, or the dir of a models.processes glob", () => {
-  assert.equal(processesOutDir({}), "processes");
+test("processesOutDir defaults to resources/processes/, or the dir of a models.processes glob", () => {
+  assert.equal(processesOutDir({}), "resources/processes");
   assert.equal(processesOutDir({ models: { processes: ["resources/processes/*.bpmn"] } }), "resources/processes");
   assert.equal(processesOutDir({ models: { processes: ["src/models/*.bpmn"] } }), "src/models");
 });
 
-test("deriveModels turns workflows/*.ts into a provenance-stamped processes/<id>.bpmn", async () => {
+test("deriveModels turns workflows/*.ts into a provenance-stamped resources/processes/<id>.bpmn", async () => {
   const io = memIO(
     { "/app/workflows/greet.ts": "// source" },
     { "workflows/greet.ts": { greet } },
@@ -81,12 +81,12 @@ test("deriveModels turns workflows/*.ts into a provenance-stamped processes/<id>
   assert.equal(d.incomplete, false);
   assert.deepEqual(d.ids, ["greet"]);
   assert.equal(d.artifacts.length, 1);
-  assert.equal(d.artifacts[0].path, "processes/greet.bpmn");
+  assert.equal(d.artifacts[0].path, "resources/processes/greet.bpmn");
   assert.match(d.artifacts[0].content, /<!--.*@nanobpm\/urban/);
   assert.ok(d.artifacts[0].content.includes(MODEL_PROVENANCE));
   assert.match(d.artifacts[0].content, /greet/);
   // the in-memory ModelSource is fed to the type-contract derivers
-  assert.deepEqual(d.models.map((m) => m.path), ["processes/greet.bpmn"]);
+  assert.deepEqual(d.models.map((m) => m.path), ["resources/processes/greet.bpmn"]);
   assert.equal(d.list[0].id, "greet");
   assert.equal(d.list[0].kind, "declarative");
 });

package/src/toolkit/models.ts

@@ -2,7 +2,8 @@
 //
 // Unlike the pure derivers (migrations, domain, worker I/O), which transform strings, this
 // imports the app's `workflows/*.ts`, turns each `defineFlow` into executable BPMN via
-// `@nanobpm/workflow` (`toBpmn` + `bpmn-auto-layout` DI), and writes `processes/<id>.bpmn`.
+// `@nanobpm/workflow` (`toBpmn` + `bpmn-auto-layout` DI), and writes `resources/processes/<id>.bpmn`
+// (the deploy-by-convention `resources/` tree, ADR 0062 — see `PROCESSES_DIR`).
 // Executing the app's TypeScript needs a runtime module loader, so this is gated on the
 // optional `GenIO.importModule` (present on Node with type-stripping, and on Deno). When the
 // loader is absent — or the app authors its models directly (model-first) — derivation is a
@@ -19,9 +20,11 @@ import { isRecord } from "../runtime/core/guards.ts";
 /** Default source glob for code-first flows (matches the code-first scaffold layout). */
 export const DEFAULT_WORKFLOW_PATTERNS = ["workflows/*.ts"];
 
-/** Default output dir for derived models (matches the model-first scaffold, so a derived
- * model is ejectable to model-first and picked up by `models.processes: ["processes/*.bpmn"]`). */
-export const PROCESSES_DIR = "processes";
+/** Default output dir for derived models when the manifest declares no `models.processes`: under
+ * the deploy-by-convention `resources/` tree (ADR 0062), one level deep, so a derived model lands
+ * exactly where the convention deploy + codegen scan look for it. When `models.processes` IS set,
+ * `processesOutDir` derives the dir from that glob instead (the model-first override). */
+export const PROCESSES_DIR = "resources/processes";
 
 /** Marker stamped into every derived `.bpmn` (an XML comment) so re-gen overwrites and the
  * stale sweep deletes ONLY derived output — never an authored, human-owned model. */
@@ -68,7 +71,7 @@ export interface ModelError {
 }
 
 export interface DerivedModels {
-  /** `processes/<id>.bpmn` artifacts (path + provenance-stamped content). */
+  /** `resources/processes/<id>.bpmn` artifacts (path + provenance-stamped content). */
   artifacts: DerivedArtifact[];
   /** The same models, in-memory, for feeding the type-contract derivers (worker I/O, meta, messages). */
   models: ModelSource[];

package/dist/runtime/core/modules/templates.d.ts

@@ -1,18 +0,0 @@
-import type { HostContext } from "../host.ts";
-/** A template source: a list of globs/directories/files (name = file stem), or an explicit
- *  `name → content` map. */
-export type TemplateSource = string[] | Record<string, string>;
-/** Build the `name → content` template map from the given sources in order (later sources win on
- *  a name collision). Array sources are resolved to files (stem = name) and read; map sources are
- *  merged verbatim. */
-export declare function resolveTemplates(host: HostContext, root: string, sources: ReadonlyArray<TemplateSource | undefined>): Promise<Record<string, string>>;
-export interface TemplateApplication {
-    content: string;
-    /** Distinct placeholder names with no matching template (left in place, surfaced by the caller). */
-    unresolved: string[];
-}
-/** Replace every `{{ name }}` placeholder in `content` with the named template's content, escaped
- *  for `contentType`. Single-pass and non-recursive: a template that itself contains `{{…}}` is
- *  not re-expanded. Unknown placeholders are left verbatim (so the miss is visible, not silently
- *  dropped) and reported in `unresolved`. */
-export declare function applyTemplates(content: string, contentType: string, templates: Record<string, string>): TemplateApplication;

package/dist/runtime/core/modules/templates.js

@@ -1,133 +0,0 @@
-// Template substitution for deployed model resources. A model file (`.bpmn`/`.dmn`/`.form`) may
-// carry `{{ name }}` placeholders — e.g. an agent service task whose prompt lives in a
-// `zeebe:header` value. Before deploy we replace each placeholder with the named template's
-// content, escaped for the resource's content-type, so a large asset (a prompt) is authored once
-// in a file and inlined into the model at deploy time rather than hand-pasted into XML or shipped
-// as a bulky per-instance process variable.
-//
-// Templates come from two sources, merged in order (later wins on a name collision):
-//   1. the manifest `models.templates` (globs, or a bare directory that is scanned), and
-//   2. a programmatic `templates` deploy option (globs, or an explicit `name → content` map).
-// A template's name is its file's stem (basename without extension): `prompts/review-round.md`
-// resolves the placeholder `{{review-round}}`.
-import { expandPatterns } from "../glob.js";
-/** A file's stem: basename without its final extension (`a/b/review-round.md` → `review-round`). */
-function stem(path) {
-    const base = path.slice(path.lastIndexOf("/") + 1);
-    const dot = base.lastIndexOf(".");
-    return dot > 0 ? base.slice(0, dot) : base;
-}
-// A template name is referenceable only if it matches the placeholder charset (`[\w.-]`, see
-// `PLACEHOLDER`). A file stem outside that set (e.g. containing spaces) could be loaded but never
-// referenced, and its `{{…}}` would not even be detected as unresolved — so we reject it loudly.
-const VALID_NAME = /^[\w.-]+$/;
-/** Files contributed by one entry: a glob (`prompts/*.md`), a bare directory (scanned, non-glob),
- *  or a literal file. Returns root-prefixed paths, matching `expandPatterns`. */
-async function filesFor(host, root, entry) {
-    if (entry.includes("*"))
-        return expandPatterns(host, root, [entry]);
-    const trimmed = entry.replace(/\/+$/, "");
-    // A non-glob entry is either a directory (scan it) or a literal file. Scan as a directory first;
-    // a non-empty directory resolves here.
-    const scanned = await expandPatterns(host, root, [`${trimmed}/*`]);
-    if (scanned.length > 0)
-        return scanned;
-    // No children matched: the entry is an empty (or subdir-only) directory, a literal file, or
-    // missing. A directory never appears in its parent's `listDir` (which yields file names only),
-    // so if the parent lists this basename it is a real file to read; otherwise treat the entry as an
-    // empty template directory that contributes nothing — and, crucially, emit no misleading
-    // "unreadable entry" warning for a valid-but-empty directory (readTextFile on it would EISDIR).
-    const slash = trimmed.lastIndexOf("/");
-    const base = trimmed.slice(slash + 1);
-    const parent = slash > 0 ? trimmed.slice(0, slash) : "";
-    const parentDir = parent ? `${root.replace(/\/+$/, "")}/${parent}` : root;
-    const siblings = await host.listDir(parentDir);
-    return siblings.includes(base) ? expandPatterns(host, root, [trimmed]) : [];
-}
-/** Build the `name → content` template map from the given sources in order (later sources win on
- *  a name collision). Array sources are resolved to files (stem = name) and read; map sources are
- *  merged verbatim. */
-export async function resolveTemplates(host, root, sources) {
-    // A null-prototype dictionary: template names (file stems or caller-supplied map keys) are
-    // untrusted, so a name like `__proto__` must set a plain own property rather than trip the
-    // magic prototype setter that a normal `{}` inherits from `Object.prototype`.
-    const map = Object.create(null);
-    for (const source of sources) {
-        if (!source)
-            continue;
-        if (Array.isArray(source)) {
-            const seen = new Set();
-            for (const entry of source) {
-                for (const file of await filesFor(host, root, entry)) {
-                    if (seen.has(file))
-                        continue;
-                    seen.add(file);
-                    const name = stem(file);
-                    if (!VALID_NAME.test(name)) {
-                        // Loud failure for a misnamed template file rather than a silently unreferenceable entry.
-                        host.log("warn", "template: skipped unsupported name", { file, name });
-                        continue;
-                    }
-                    try {
-                        map[name] = await host.readTextFile(file);
-                    }
-                    catch (err) {
-                        // A directory path that slipped through the file fallback, or an unreadable file.
-                        host.log("warn", "template: skipped unreadable entry", { file, error: String(err) });
-                    }
-                }
-            }
-        }
-        else {
-            Object.assign(map, source);
-        }
-    }
-    return map;
-}
-// `{{ name }}` — a double-brace placeholder around a template name. Double braces avoid clashing
-// with FEEL's single-brace context syntax used elsewhere in BPMN.
-const PLACEHOLDER = /\{\{\s*([\w.-]+)\s*\}\}/g;
-/** Escape template content for an XML attribute value (e.g. a `zeebe:header` `value="…"`). Beyond
- *  the markup-significant characters, newlines and tabs MUST become character references:
- *  XML attribute-value normalization collapses literal newlines/tabs to spaces, which would
- *  destroy a multi-line prompt. Character references are exempt from that normalization, so
- *  `
` round-trips as a newline. This escaping is also valid for XML element text, so it is
- *  the safe default for any `.bpmn`/`.dmn` placeholder position. */
-function xmlAttrEscape(s) {
-    return s
-        .replace(/&/g, "&")
-        .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;")
-        .replace(/"/g, "&quot;")
-        .replace(/'/g, "&apos;")
-        .replace(/\r/g, "&#13;")
-        .replace(/\n/g, "&#10;")
-        .replace(/\t/g, "&#9;");
-}
-/** Escape template content for embedding inside a JSON string literal (a `.form` value). */
-function jsonStringEscape(s) {
-    // Stringify to a valid JSON string, then drop the surrounding quotes → an inner-string fragment.
-    const quoted = JSON.stringify(s);
-    return quoted.slice(1, quoted.length - 1);
-}
-function escaperFor(contentType) {
-    if (contentType === "application/json")
-        return jsonStringEscape;
-    return xmlAttrEscape; // text/xml (.bpmn/.dmn) and any other markup
-}
-/** Replace every `{{ name }}` placeholder in `content` with the named template's content, escaped
- *  for `contentType`. Single-pass and non-recursive: a template that itself contains `{{…}}` is
- *  not re-expanded. Unknown placeholders are left verbatim (so the miss is visible, not silently
- *  dropped) and reported in `unresolved`. */
-export function applyTemplates(content, contentType, templates) {
-    const escape = escaperFor(contentType);
-    const unresolved = [];
-    const out = content.replace(PLACEHOLDER, (whole, name) => {
-        if (Object.prototype.hasOwnProperty.call(templates, name))
-            return escape(templates[name]);
-        if (!unresolved.includes(name))
-            unresolved.push(name);
-        return whole;
-    });
-    return { content: out, unresolved };
-}

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

@@ -1,153 +0,0 @@
-// Template substitution for deployed model resources. A model file (`.bpmn`/`.dmn`/`.form`) may
-// carry `{{ name }}` placeholders — e.g. an agent service task whose prompt lives in a
-// `zeebe:header` value. Before deploy we replace each placeholder with the named template's
-// content, escaped for the resource's content-type, so a large asset (a prompt) is authored once
-// in a file and inlined into the model at deploy time rather than hand-pasted into XML or shipped
-// as a bulky per-instance process variable.
-//
-// Templates come from two sources, merged in order (later wins on a name collision):
-//   1. the manifest `models.templates` (globs, or a bare directory that is scanned), and
-//   2. a programmatic `templates` deploy option (globs, or an explicit `name → content` map).
-// A template's name is its file's stem (basename without extension): `prompts/review-round.md`
-// resolves the placeholder `{{review-round}}`.
-
-import type { HostContext } from "../host.ts";
-import { expandPatterns } from "../glob.ts";
-
-/** A template source: a list of globs/directories/files (name = file stem), or an explicit
- *  `name → content` map. */
-export type TemplateSource = string[] | Record<string, string>;
-
-/** A file's stem: basename without its final extension (`a/b/review-round.md` → `review-round`). */
-function stem(path: string): string {
-  const base = path.slice(path.lastIndexOf("/") + 1);
-  const dot = base.lastIndexOf(".");
-  return dot > 0 ? base.slice(0, dot) : base;
-}
-
-// A template name is referenceable only if it matches the placeholder charset (`[\w.-]`, see
-// `PLACEHOLDER`). A file stem outside that set (e.g. containing spaces) could be loaded but never
-// referenced, and its `{{…}}` would not even be detected as unresolved — so we reject it loudly.
-const VALID_NAME = /^[\w.-]+$/;
-
-/** Files contributed by one entry: a glob (`prompts/*.md`), a bare directory (scanned, non-glob),
- *  or a literal file. Returns root-prefixed paths, matching `expandPatterns`. */
-async function filesFor(host: HostContext, root: string, entry: string): Promise<string[]> {
-  if (entry.includes("*")) return expandPatterns(host, root, [entry]);
-  const trimmed = entry.replace(/\/+$/, "");
-  // A non-glob entry is either a directory (scan it) or a literal file. Scan as a directory first;
-  // a non-empty directory resolves here.
-  const scanned = await expandPatterns(host, root, [`${trimmed}/*`]);
-  if (scanned.length > 0) return scanned;
-  // No children matched: the entry is an empty (or subdir-only) directory, a literal file, or
-  // missing. A directory never appears in its parent's `listDir` (which yields file names only),
-  // so if the parent lists this basename it is a real file to read; otherwise treat the entry as an
-  // empty template directory that contributes nothing — and, crucially, emit no misleading
-  // "unreadable entry" warning for a valid-but-empty directory (readTextFile on it would EISDIR).
-  const slash = trimmed.lastIndexOf("/");
-  const base = trimmed.slice(slash + 1);
-  const parent = slash > 0 ? trimmed.slice(0, slash) : "";
-  const parentDir = parent ? `${root.replace(/\/+$/, "")}/${parent}` : root;
-  const siblings = await host.listDir(parentDir);
-  return siblings.includes(base) ? expandPatterns(host, root, [trimmed]) : [];
-}
-
-/** Build the `name → content` template map from the given sources in order (later sources win on
- *  a name collision). Array sources are resolved to files (stem = name) and read; map sources are
- *  merged verbatim. */
-export async function resolveTemplates(
-  host: HostContext,
-  root: string,
-  sources: ReadonlyArray<TemplateSource | undefined>,
-): Promise<Record<string, string>> {
-  // A null-prototype dictionary: template names (file stems or caller-supplied map keys) are
-  // untrusted, so a name like `__proto__` must set a plain own property rather than trip the
-  // magic prototype setter that a normal `{}` inherits from `Object.prototype`.
-  const map: Record<string, string> = Object.create(null);
-  for (const source of sources) {
-    if (!source) continue;
-    if (Array.isArray(source)) {
-      const seen = new Set<string>();
-      for (const entry of source) {
-        for (const file of await filesFor(host, root, entry)) {
-          if (seen.has(file)) continue;
-          seen.add(file);
-          const name = stem(file);
-          if (!VALID_NAME.test(name)) {
-            // Loud failure for a misnamed template file rather than a silently unreferenceable entry.
-            host.log("warn", "template: skipped unsupported name", { file, name });
-            continue;
-          }
-          try {
-            map[name] = await host.readTextFile(file);
-          } catch (err) {
-            // A directory path that slipped through the file fallback, or an unreadable file.
-            host.log("warn", "template: skipped unreadable entry", { file, error: String(err) });
-          }
-        }
-      }
-    } else {
-      Object.assign(map, source);
-    }
-  }
-  return map;
-}
-
-// `{{ name }}` — a double-brace placeholder around a template name. Double braces avoid clashing
-// with FEEL's single-brace context syntax used elsewhere in BPMN.
-const PLACEHOLDER = /\{\{\s*([\w.-]+)\s*\}\}/g;
-
-/** Escape template content for an XML attribute value (e.g. a `zeebe:header` `value="…"`). Beyond
- *  the markup-significant characters, newlines and tabs MUST become character references:
- *  XML attribute-value normalization collapses literal newlines/tabs to spaces, which would
- *  destroy a multi-line prompt. Character references are exempt from that normalization, so
- *  `&#10;` round-trips as a newline. This escaping is also valid for XML element text, so it is
- *  the safe default for any `.bpmn`/`.dmn` placeholder position. */
-function xmlAttrEscape(s: string): string {
-  return s
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&apos;")
-    .replace(/\r/g, "&#13;")
-    .replace(/\n/g, "&#10;")
-    .replace(/\t/g, "&#9;");
-}
-
-/** Escape template content for embedding inside a JSON string literal (a `.form` value). */
-function jsonStringEscape(s: string): string {
-  // Stringify to a valid JSON string, then drop the surrounding quotes → an inner-string fragment.
-  const quoted = JSON.stringify(s);
-  return quoted.slice(1, quoted.length - 1);
-}
-
-function escaperFor(contentType: string): (s: string) => string {
-  if (contentType === "application/json") return jsonStringEscape;
-  return xmlAttrEscape; // text/xml (.bpmn/.dmn) and any other markup
-}
-
-export interface TemplateApplication {
-  content: string;
-  /** Distinct placeholder names with no matching template (left in place, surfaced by the caller). */
-  unresolved: string[];
-}
-
-/** Replace every `{{ name }}` placeholder in `content` with the named template's content, escaped
- *  for `contentType`. Single-pass and non-recursive: a template that itself contains `{{…}}` is
- *  not re-expanded. Unknown placeholders are left verbatim (so the miss is visible, not silently
- *  dropped) and reported in `unresolved`. */
-export function applyTemplates(
-  content: string,
-  contentType: string,
-  templates: Record<string, string>,
-): TemplateApplication {
-  const escape = escaperFor(contentType);
-  const unresolved: string[] = [];
-  const out = content.replace(PLACEHOLDER, (whole: string, name: string) => {
-    if (Object.prototype.hasOwnProperty.call(templates, name)) return escape(templates[name]);
-    if (!unresolved.includes(name)) unresolved.push(name);
-    return whole;
-  });
-  return { content: out, unresolved };
-}