@nanobpm/urban 0.21.0 → 0.22.0

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

@@ -0,0 +1,153 @@
+// 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 };
+}

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

@@ -1,9 +1,10 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import type { AppApi, RuntimeContext } from "../context.ts";
-import type { HttpRequest } from "../host.ts";
+import type { EngineClient, HostContext, HttpRequest } from "../host.ts";
 import type { Trigger } from "../manifest.ts";
 import { makeRouter } from "../router.ts";
+import { DataLayer } from "./datasource.ts";
 import { evalCorrelation, mountTriggers, runTriggerAction, type SchedulerDeps } from "./triggers.ts";
 
 interface EngineCall {
@@ -13,33 +14,64 @@ interface EngineCall {
   correlationKey?: string;
 }
 
+class MiniEngine implements EngineClient {
+  private readonly calls: EngineCall[];
+  constructor(calls: EngineCall[]) {
+    this.calls = calls;
+  }
+  async deployResources(): Promise<{ deployed: number }> { return { deployed: 0 }; }
+  async createInstance(input: { processDefinitionId: string; variables?: Record<string, unknown> }): Promise<{ processInstanceKey: string }> {
+    this.calls.push({ kind: "start", target: input.processDefinitionId, variables: input.variables });
+    return { processInstanceKey: "pi-1" };
+  }
+  async cancelInstance(): Promise<void> {}
+  async publishMessage(input: { name: string; correlationKey?: string; variables?: Record<string, unknown> }): Promise<void> {
+    this.calls.push({ kind: "message", target: input.name, correlationKey: input.correlationKey, variables: input.variables });
+  }
+  async searchUserTasks(): Promise<[]> { return []; }
+  async completeUserTask(): Promise<void> {}
+  async registerWorker(jobType: string): Promise<{ jobType: string; unsubscribe(): Promise<void> }> {
+    return { jobType, unsubscribe: async () => {} };
+  }
+  async close(): Promise<void> {}
+}
+
 function fakeApp(): { app: AppApi; calls: EngineCall[]; logs: Array<{ level: string; msg: string }> } {
   const calls: EngineCall[] = [];
   const logs: Array<{ level: string; msg: string }> = [];
-  const app = {
+  const engine = new MiniEngine(calls);
+  const app: AppApi = {
+    manifest: { schemaVersion: 1, id: "t", name: "T" },
+    data: new DataLayer(new Map(), undefined, {}),
+    engine,
     env: () => undefined,
     log: (level: string, msg: string) => logs.push({ level, msg }),
-    engine: {
-      createInstance: (input: { processDefinitionId: string; variables?: Record<string, unknown> }) => {
-        calls.push({ kind: "start", target: input.processDefinitionId, variables: input.variables });
-        return Promise.resolve({ processInstanceKey: "pi-1" });
-      },
-      publishMessage: (input: { name: string; correlationKey?: string; variables?: Record<string, unknown> }) => {
-        calls.push({ kind: "message", target: input.name, correlationKey: input.correlationKey, variables: input.variables });
-        return Promise.resolve();
-      },
-    },
-  } as unknown as AppApi;
+  };
   return { app, calls, logs };
 }
 
 function fakeCtx(triggers: Trigger[]): { ctx: RuntimeContext; hostLogs: Array<{ level: string; msg: string }> } {
   const hostLogs: Array<{ level: string; msg: string }> = [];
-  const ctx = {
+  const host: HostContext = {
+    runtime: "node",
+    env: () => undefined,
+    readTextFile: async () => "",
+    listDir: async () => [],
+    exists: async () => false,
+    openSqlite: () => {
+      throw new Error("sqlite not used in this test");
+    },
+    importModule: async () => ({}),
+    serveHttp: async () => ({ port: 0, stop: async () => {} }),
+    now: () => 0,
+    log: (level: string, msg: string) => hostLogs.push({ level, msg }),
+  };
+  const ctx: RuntimeContext = {
     root: "/app",
-    manifest: { schemaVersion: 1, id: "t", name: "T", triggers } as RuntimeContext["manifest"],
-    host: { log: (level: string, msg: string) => hostLogs.push({ level, msg }) },
-  } as unknown as RuntimeContext;
+    manifest: { schemaVersion: 1, id: "t", name: "T", triggers },
+    engine: new MiniEngine([]),
+    host,
+  };
   return { ctx, hostLogs };
 }
 
@@ -56,7 +88,7 @@ function fakeScheduler(startMs: number): SchedulerDeps & { advance: (ms: number)
       return id;
     },
     clearTimer: (h) => {
-      timers.delete(h as number);
+      if (typeof h === "number") timers.delete(h);
     },
     pending: () => timers.size,
     // Advance the clock, firing every timer whose deadline has passed (in order), letting
@@ -255,7 +287,7 @@ test("webhook trigger still routes and publishes", async () => {
     { id: "hook", type: "webhook", action: { message: "got-it", correlationKey: "= body.id" } },
   ]);
   const handle = mountTriggers(ctx, app);
-  const router = makeRouter(handle.routes) as unknown as (r: HttpRequest) => Promise<{ status?: number; body?: string }>;
+  const router = async (r: HttpRequest) => makeRouter(handle.routes)(r);
   const res = await router({
     method: "POST",
     path: "/hooks/hook",

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

@@ -4,6 +4,7 @@
 // Node 18+ and Deno), so this stays runtime-agnostic.
 
 import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
+import { isRecord } from "../guards.ts";
 import type { HttpRequest } from "../host.ts";
 import { json, normalizeRoutePath, type Route } from "../router.ts";
 import type { Trigger } from "../manifest.ts";
@@ -35,7 +36,7 @@ export function resolveExpr(expr: string, scope: Scope): unknown {
   let cur: unknown = scope;
   for (const seg of pathExpr.split(".")) {
     if (cur && typeof cur === "object" && Object.prototype.hasOwnProperty.call(cur, seg)) {
-      cur = (cur as Record<string, unknown>)[seg];
+      cur = Object.getOwnPropertyDescriptor(cur, seg)?.value;
     } else {
       return undefined;
     }
@@ -67,7 +68,7 @@ export function resolveActionVariables(
   scope: Scope,
 ): Record<string, unknown> {
   const asRecord = (v: unknown): Record<string, unknown> | undefined =>
-    v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;
+    isRecord(v) ? v : undefined;
 
   if (typeof expr === "string") {
     return asRecord(resolveExpr(expr, scope)) ?? asRecord(scope.body) ?? {};
@@ -146,7 +147,7 @@ export async function runTriggerAction(
   return { kind: "none" };
 }
 
-const emptyScope = { body: {}, headers: {} as Record<string, string>, query: {} as Record<string, string> };
+const emptyScope: Scope = { body: {}, headers: {}, query: {} };
 
 /** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
@@ -155,11 +156,17 @@ const MAX_TIMER_DELAY_MS = 2_147_483_647;
 function defaultScheduler(): SchedulerDeps {
   return {
     setTimer: (fn, ms) => globalThis.setTimeout(fn, ms),
-    clearTimer: (h) => globalThis.clearTimeout(h as ReturnType<typeof setTimeout>),
+    clearTimer: (h) => {
+      if (isTimerHandle(h)) globalThis.clearTimeout(h);
+    },
     now: () => Date.now(),
   };
 }
 
+function isTimerHandle(handle: unknown): handle is ReturnType<typeof setTimeout> {
+  return typeof handle === "number" || (typeof handle === "object" && handle !== null);
+}
+
 /** Mount webhook + cron triggers. Webhooks contribute HTTP routes; cron triggers arm
  *  background timers that fire their action on schedule. `stop()` clears every timer. */
 export function mountTriggers(
@@ -255,7 +262,7 @@ export function mountTriggers(
     arm();
   };
 
-  for (const trig of (ctx.manifest.triggers ?? []) as Trigger[]) {
+  for (const trig of ctx.manifest.triggers ?? []) {
     if (trig.type === "cron") {
       armCron(trig);
       continue;
@@ -295,7 +302,8 @@ export function mountTriggers(
           if (seenDeliveries.has(delivery)) return json({ ok: true, deduped: true });
           seenDeliveries.add(delivery);
           if (seenDeliveries.size > 10_000) {
-            seenDeliveries.delete(seenDeliveries.values().next().value as string);
+            const oldest = seenDeliveries.values().next().value;
+            if (oldest !== undefined) seenDeliveries.delete(oldest);
           }
         }
 

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

@@ -1,13 +1,21 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import type { AppApi, RuntimeContext } from "../context.ts";
-import type { EngineJob, JobHandler, WorkerSubscription } from "../host.ts";
+import type { EngineClient, EngineJob, HostContext, JobHandler, WorkerSubscription } from "../host.ts";
 import type { AppManifest } from "../manifest.ts";
+import { DataLayer } from "./datasource.ts";
 import { mountWorkers, sdkDecisionEvaluator, type AppJobHandler } from "./workers.ts";
 
 /** A tiny engine that records registrations and can deliver a job to a handler. */
-class MiniEngine {
+class MiniEngine implements EngineClient {
   workers = new Map<string, JobHandler>();
+  async deployResources(): Promise<{ deployed: number }> { return { deployed: 0 }; }
+  async createInstance(): Promise<{ processInstanceKey: string }> { return { processInstanceKey: "pi" }; }
+  async cancelInstance(): Promise<void> {}
+  async publishMessage(): Promise<void> {}
+  async searchUserTasks(): Promise<[]> { return []; }
+  async completeUserTask(): Promise<void> {}
+  async close(): Promise<void> {}
   async registerWorker(jobType: string, handler: JobHandler): Promise<WorkerSubscription> {
     this.workers.set(jobType, handler);
     return { jobType, unsubscribe: async () => void this.workers.delete(jobType) };
@@ -24,33 +32,46 @@ function makeCtx(
   engine: MiniEngine,
 ): { ctx: RuntimeContext; logs: Array<{ level: string; msg: string }> } {
   const logs: Array<{ level: string; msg: string }> = [];
-  const ctx = {
-    root: "/app",
-    manifest: { schemaVersion: 1, id: "t", name: "T", ...manifest } as AppManifest,
-    engine: engine as unknown as RuntimeContext["engine"],
-    host: {
-      log: (level: string, msg: string) => logs.push({ level, msg }),
-      importModule: () => Promise.reject(new Error("no modules in this test")),
+  const host: HostContext = {
+    runtime: "node",
+    env: () => undefined,
+    readTextFile: async () => "",
+    listDir: async () => [],
+    exists: async () => false,
+    openSqlite: () => {
+      throw new Error("sqlite not used in this test");
     },
-  } as unknown as RuntimeContext;
+    importModule: () => Promise.reject(new Error("no modules in this test")),
+    serveHttp: async () => ({ port: 0, stop: async () => {} }),
+    now: () => 0,
+    log: (level: string, msg: string) => logs.push({ level, msg }),
+  };
+  const ctx: RuntimeContext = {
+    root: "/app",
+    manifest: { schemaVersion: 1, id: "t", name: "T", ...manifest },
+    engine,
+    host,
+  };
   return { ctx, logs };
 }
 
 function makeApp(over: Partial<AppApi> = {}): AppApi {
+  const env: Record<string, string> = { NANO_APP_LLM_MODEL: "m" };
   return {
-    env: (n) => ({ NANO_APP_LLM_MODEL: "m" } as Record<string, string>)[n],
+    manifest: { schemaVersion: 1, id: "t", name: "T" },
+    data: new DataLayer(new Map(), undefined, {}),
+    engine: new MiniEngine(),
+    env: (n) => env[n],
     log: () => {},
     ...over,
-  } as AppApi;
+  };
 }
 
 function fakeFetch(content: string): typeof fetch {
-  return (async () => ({
-    ok: true,
-    status: 200,
-    json: async () => ({ choices: [{ message: { content } }] }),
-    text: async () => content,
-  })) as unknown as typeof fetch;
+  return async () => new Response(
+    JSON.stringify({ choices: [{ message: { content } }] }),
+    { status: 200, headers: { "content-type": "application/json" } },
+  );
 }
 
 const orig = globalThis.fetch;
@@ -118,7 +139,9 @@ test("an llm worker with decision rails uses app.sdk to evaluate the decision",
     },
     engine,
   );
-  await mountWorkers(ctx, makeApp({ sdk: sdk as unknown as AppApi["sdk"] }));
+  const app = makeApp();
+  Object.defineProperty(app, "sdk", { value: sdk });
+  await mountWorkers(ctx, app);
 
   await withFetch('{"amount":100}', async () => {
     const out = await engine.deliver("risk", {
@@ -214,7 +237,7 @@ test("AppJobHandler carries optional In/Out variable types", async () => {
     jobType: "pr.finalize",
     variables: { prKey: "p1", round: 2 },
   };
-  const app = {} as AppApi;
+  const app = makeApp();
 
   assert.deepEqual(await typed(job, app), { ok: true });
   assert.deepEqual(await inOnly(job, app), { echoed: "p1" });

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

@@ -3,6 +3,7 @@
 // with the app's runtime API (datasource + engine + host utils).
 
 import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
+import { isRecord } from "../guards.ts";
 import type { EngineJob, JobHandler, WorkerSubscription } from "../host.ts";
 import { workerJobType, type Worker } from "../manifest.ts";
 import { type DecisionEvaluator, type LlmRuntime, runLlmJob } from "./llm.ts";
@@ -21,15 +22,14 @@ interface DecisionCapableSdk {
  *  SDK shape and adds decision context to a parse failure rather than surfacing a raw
  *  "is not a function" / `JSON.parse` error. */
 export function sdkDecisionEvaluator(sdk: unknown): DecisionEvaluator {
-  const client = sdk as Partial<DecisionCapableSdk>;
   return async (decisionId, variables) => {
-    if (typeof client.evaluateDecision !== "function") {
+    if (!hasDecisionCapableSdk(sdk)) {
       throw new Error(
         `llm worker: the engine SDK does not support evaluateDecision ` +
           `(needed for decision rails "${decisionId}")`,
       );
     }
-    const res = await client.evaluateDecision({ decisionDefinitionId: decisionId, variables });
+    const res = await sdk.evaluateDecision({ decisionDefinitionId: decisionId, variables });
     const out = res?.output;
     if (typeof out !== "string") return out;
     try {
@@ -42,6 +42,10 @@ export function sdkDecisionEvaluator(sdk: unknown): DecisionEvaluator {
   };
 }
 
+function hasDecisionCapableSdk(sdk: unknown): sdk is DecisionCapableSdk {
+  return isRecord(sdk) && typeof sdk.evaluateDecision === "function";
+}
+
 /**
  * A handler as authored by an app: the job plus the injected app API.
  *
@@ -63,6 +67,10 @@ export type AppJobHandler<In extends object = Record<string, unknown>, Out exten
   app: AppApi,
 ) => Promise<Out | void> | Out | void;
 
+function isAppJobHandler(value: unknown): value is AppJobHandler {
+  return typeof value === "function";
+}
+
 /**
  * Resolve a handler for `jobType` from a loaded module, in priority order:
  *   1. `handlers[jobType]`            (a map keyed by job type — the multi-type module case)
@@ -73,13 +81,13 @@ export function resolveHandler(
   mod: Record<string, unknown>,
   jobType: string,
 ): AppJobHandler | undefined {
-  const map = mod.handlers as Record<string, unknown> | undefined;
-  if (map && typeof map[jobType] === "function") return map[jobType] as AppJobHandler;
+  const map = isRecord(mod.handlers) ? mod.handlers : undefined;
+  if (map && isAppJobHandler(map[jobType])) return map[jobType];
   const seg = jobType.includes(".") ? jobType.slice(jobType.lastIndexOf(".") + 1) : jobType;
-  if (typeof mod[jobType] === "function") return mod[jobType] as AppJobHandler;
-  if (map && typeof map[seg] === "function") return map[seg] as AppJobHandler;
-  if (typeof mod[seg] === "function") return mod[seg] as AppJobHandler;
-  if (typeof mod.default === "function") return mod.default as AppJobHandler;
+  if (isAppJobHandler(mod[jobType])) return mod[jobType];
+  if (map && isAppJobHandler(map[seg])) return map[seg];
+  if (isAppJobHandler(mod[seg])) return mod[seg];
+  if (isAppJobHandler(mod.default)) return mod.default;
   return undefined;
 }
 
@@ -106,7 +114,7 @@ export async function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<Wo
     return mod;
   };
 
-  for (const decl of decls as Worker[]) {
+  for (const decl of decls) {
     const jobType = workerJobType(decl);
     if (!jobType) continue;
     // Connector-backed workers (a `connector` field, no handler/llm) are mounted

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

@@ -6,6 +6,7 @@ import { join } from "node:path";
 import { createNodeHost } from "../adapters/node.ts";
 import { createUrbanApp, resolvePort } from "./runtime.ts";
 import { runFromEnv } from "../run.ts";
+import { isRecord } from "./guards.ts";
 import type {
   EngineClient,
   EngineJob,
@@ -54,6 +55,16 @@ class FakeEngine implements EngineClient {
   }
 }
 
+function expectRecord(value: unknown): Record<string, unknown> {
+  if (!isRecord(value)) throw new TypeError("expected record");
+  return value;
+}
+
+function expectArray(value: unknown): unknown[] {
+  if (!Array.isArray(value)) throw new TypeError("expected array");
+  return value;
+}
+
 async function makeFixture(): Promise<string> {
   const dir = await mkdtemp(join(tmpdir(), "urban-rt-"));
   await mkdir(join(dir, "processes"));
@@ -104,8 +115,10 @@ test("runtime materializes the manifest end-to-end against a fake engine", async
     assert.equal(engine.deployed, 3, "3 model files deployed");
 
     // migrations applied
-    const insp = app.inspect() as Record<string, any>;
-    assert.deepEqual(insp.data.sources[0].migrations, 1);
+    const insp = app.inspect();
+    const data = expectRecord(insp.data);
+    const sources = expectArray(data.sources).map(expectRecord);
+    assert.deepEqual(sources[0].migrations, 1);
 
     // workers registered + data injected: deliver a job and see a DB row
     await engine.deliver("wf.claim", {
@@ -124,7 +137,7 @@ test("runtime materializes the manifest end-to-end against a fake engine", async
 
     const tasksRes = await fetch(`http://localhost:${port}/tasks/api/tasks`);
     assert.equal(tasksRes.status, 200);
-    assert.equal((await tasksRes.json() as unknown[]).length, 1);
+    assert.equal(expectArray(await tasksRes.json()).length, 1);
 
     const hookRes = await fetch(`http://localhost:${port}/hooks/task`, {
       method: "POST",
@@ -148,7 +161,7 @@ test("runtime materializes the manifest end-to-end against a fake engine", async
 
     // healthz
     const health = await fetch(`http://localhost:${port}/healthz`);
-    assert.equal((await health.json() as { ok: boolean }).ok, true);
+    assert.equal(expectRecord(await health.json()).ok, true);
 
     // field-drift guard
     assert.throws(() => app.data!.repo("task").insert({ bogus: 1 }));
@@ -175,11 +188,11 @@ test("threads the engine SDK client onto app.sdk for handlers (SDK-backed engine
   await app.start();
 
   try {
-    const out = (await engine.deliver("wf.claim", {
+    const out = expectRecord(await engine.deliver("wf.claim", {
       jobKey: "j1",
       jobType: "wf.claim",
       variables: { title: "Fix bug" },
-    })) as Record<string, unknown>;
+    }));
     assert.equal(out.hasSdk, true, "handler saw app.sdk");
     assert.equal(out.sdkMarker, "engine-sdk", "app.sdk is the engine's own client");
   } finally {
@@ -196,11 +209,11 @@ test("app.sdk is undefined when the engine exposes no SDK client", async () => {
   await app.start();
 
   try {
-    const out = (await engine.deliver("wf.claim", {
+    const out = expectRecord(await engine.deliver("wf.claim", {
       jobKey: "j1",
       jobType: "wf.claim",
       variables: { title: "Fix bug" },
-    })) as Record<string, unknown>;
+    }));
     assert.equal(out.hasSdk, false, "no app.sdk for a non-SDK engine");
     assert.equal(out.sdkMarker, undefined);
   } finally {
@@ -222,7 +235,7 @@ test("stop() resets state so the app can be cleanly restarted", async () => {
     await app.stop();
 
     // after stop, inspect() no longer carries stale describe data / port
-    const stopped = app.inspect() as Record<string, unknown>;
+    const stopped = app.inspect();
     assert.equal(stopped.httpPort, undefined);
     assert.equal(stopped.workers, undefined);
 
@@ -255,7 +268,7 @@ test("a failed start() tears down and resets state (no 'already started' wedge)"
   try {
     await assert.rejects(() => app.start(), /boom during deploy/);
     // state reset: not wedged, no leaked port/describe
-    const s = app.inspect() as Record<string, unknown>;
+    const s = app.inspect();
     assert.equal(s.httpPort, undefined);
     assert.equal(s.workers, undefined);
     // a subsequent start() succeeds rather than throwing "app already started"

package/src/runtime/core/runtime.ts

@@ -10,6 +10,7 @@ import { loadManifest, 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 { mountWorkers } from "./modules/workers.ts";
 import { mountConnectors } from "./modules/connectors.ts";
@@ -32,8 +33,16 @@ export function resolvePort(explicit: number | undefined, envPort: string | unde
 /** Read the underlying nano-sdk client off an engine when it exposes one (the
  *  `SdkEngineClient` does). Non-SDK engines (e.g. an in-memory test double) have no
  *  `sdk`, so handlers get `undefined` and fall back to the transport-agnostic seam. */
+interface EngineWithSdk extends EngineClient {
+  sdk?: EngineSdkClient;
+}
+
+function hasEngineSdk(engine: EngineClient): engine is EngineWithSdk {
+  return "sdk" in engine;
+}
+
 function engineSdk(engine: EngineClient): EngineSdkClient | undefined {
-  return (engine as { sdk?: EngineSdkClient }).sdk;
+  return hasEngineSdk(engine) ? engine.sdk : undefined;
 }
 
 export interface MountFlags {
@@ -58,6 +67,10 @@ 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;
 }
 
 export interface UrbanApp {
@@ -92,7 +105,7 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
     triggers: opts.mount?.triggers ?? true,
     security: opts.mount?.security ?? true,
   };
-  const ctx = { manifest, host, engine, root };
+  const ctx = { manifest, host, engine, root, templates: opts.templates };
 
   let data: DataLayer | undefined;
   let security: SecurityPolicy | undefined;