@nanobpm/urban 0.20.0 → 0.22.0

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

@@ -20,6 +20,7 @@
 // vLLM, …) or a hosted API both work unchanged. This module is host-agnostic: env and
 // fetch are injected (env always via the host seam), never read from a concrete runtime.
 import { expandEnvString } from "../manifest.js";
+import { isRecord } from "../guards.js";
 /**
  * Resolve an OpenAI-compatible endpoint for a binding. `provider: "env"` (the only
  * built-in today) reads:
@@ -57,7 +58,7 @@ export function buildMessages(vars) {
             throw new Error("llm worker: 'messages' must not be an empty array");
         }
         msgs = vars.messages.map((m, i) => {
-            const o = m;
+            const o = isRecord(m) ? m : {};
             if (typeof o.content !== "string" ||
                 (o.role !== "user" && o.role !== "assistant" && o.role !== "system")) {
                 throw new Error(`llm worker: messages[${i}] must be { role: user|assistant|system, content: string }`);
@@ -95,8 +96,11 @@ export async function callLlm(provider, messages, opts = {}) {
         const detail = await res.text().catch(() => "");
         throw new Error(`llm provider returned ${res.status}: ${detail.slice(0, 500)}`);
     }
-    const data = (await res.json());
-    const content = data.choices?.[0]?.message?.content;
+    const data = await res.json();
+    const choices = isRecord(data) && Array.isArray(data.choices) ? data.choices : [];
+    const firstChoice = choices[0];
+    const message = isRecord(firstChoice) && isRecord(firstChoice.message) ? firstChoice.message : undefined;
+    const content = message?.content;
     if (typeof content !== "string") {
         throw new Error("llm provider returned no message content");
     }
@@ -127,7 +131,7 @@ export async function runLlmJob(vars, binding, rt) {
     }
     // response_format asks for a JSON object, but a provider can still return a scalar, array,
     // or null — none of which is a valid variable map (nor valid decision-rails input).
-    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    if (!isRecord(parsed)) {
         throw new Error(`llm worker: expected a JSON object output but got: ${text.slice(0, 300)}`);
     }
     const obj = parsed;
@@ -138,9 +142,7 @@ export async function runLlmJob(vars, binding, rt) {
                 `evaluator is available (the engine SDK surface is required for decision rails)`);
         }
         const out = await rt.evaluateDecision(decisionId, obj);
-        return out !== null && typeof out === "object" && !Array.isArray(out)
-            ? out
-            : { result: out };
+        return isRecord(out) ? out : { result: out };
     }
     return obj;
 }

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

@@ -14,6 +14,7 @@
 //   POST /app/actions/start/<process>               → engine.createInstance
 //   POST /app/actions/cancel                        → engine.cancelInstance
 //   POST /app/actions/message                       → engine.publishMessage
+import { errorMessage, isRecord } from "../guards.js";
 import { html, json } from "../router.js";
 import { quoteIdent } from "./gateway.js";
 /** A JavaScript-body response (the renderer module served at /app/runtime.js). */
@@ -169,7 +170,7 @@ export function createPagesRoutes(opts, deps) {
                 return json({ rows });
             }
             catch (e) {
-                return json({ error: String(e?.message ?? e) }, 500);
+                return json({ error: errorMessage(e) }, 500);
             }
         },
     });
@@ -187,11 +188,11 @@ export function createPagesRoutes(opts, deps) {
             let variables = {};
             try {
                 const body = JSON.parse((await req.text()) || "{}");
-                if (body && typeof body === "object") {
+                if (isRecord(body)) {
                     const v = body.variables;
                     // Only a plain object is a valid variable map — reject arrays/scalars/null so a
                     // malformed body can't reach the engine as bad `variables`.
-                    if (v && typeof v === "object" && !Array.isArray(v)) {
+                    if (isRecord(v)) {
                         variables = v;
                     }
                 }
@@ -204,7 +205,7 @@ export function createPagesRoutes(opts, deps) {
                 return json({ processInstanceKey: res.processInstanceKey ?? null });
             }
             catch (e) {
-                return json({ error: String(e?.message ?? e) }, 502);
+                return json({ error: errorMessage(e) }, 502);
             }
         },
     });
@@ -217,7 +218,7 @@ export function createPagesRoutes(opts, deps) {
             let key;
             try {
                 const body = JSON.parse((await req.text()) || "{}");
-                const k = body?.processInstanceKey;
+                const k = isRecord(body) ? body.processInstanceKey : undefined;
                 if (typeof k === "string" || typeof k === "number")
                     key = k;
             }
@@ -231,7 +232,7 @@ export function createPagesRoutes(opts, deps) {
                 return json({ ok: true });
             }
             catch (e) {
-                return json({ error: String(e?.message ?? e) }, 502);
+                return json({ error: errorMessage(e) }, 502);
             }
         },
     });
@@ -245,14 +246,15 @@ export function createPagesRoutes(opts, deps) {
             let correlationKey = "";
             let variables = {};
             try {
-                const body = JSON.parse((await req.text()) || "{}");
+                const parsed = JSON.parse((await req.text()) || "{}");
+                const body = isRecord(parsed) ? parsed : {};
                 if (typeof body?.name === "string")
                     name = body.name;
                 if (typeof body?.correlationKey === "string" || typeof body?.correlationKey === "number") {
                     correlationKey = String(body.correlationKey);
                 }
                 const v = body?.variables;
-                if (v && typeof v === "object" && !Array.isArray(v)) {
+                if (isRecord(v)) {
                     variables = v;
                 }
             }
@@ -268,7 +270,7 @@ export function createPagesRoutes(opts, deps) {
                 return json({ ok: true });
             }
             catch (e) {
-                return json({ error: String(e?.message ?? e) }, 502);
+                return json({ error: errorMessage(e) }, 502);
             }
         },
     });
@@ -417,24 +419,49 @@ function renderActionForm(node) {
   const p = node.props;
   const card = el("section", { class: "pc-card" });
   if (p.title) card.append(el("h2", {}, p.title));
-  const inputs = {};
+  // Map/null-proto stores so a schema field keyed __proto__/constructor can't
+  // pollute Object.prototype or shadow inherited props (prototype-pollution class).
+  const inputs = new Map();
+  const fieldTypes = new Map();
   for (const f of p.fields || []) {
-    const input = el("input", { type: "text", placeholder: f.label || f.key });
-    inputs[f.key] = input;
+    const kind = f.type === "number" ? "number" : "text";
+    fieldTypes.set(f.key, kind);
+    const attrs = { type: kind, placeholder: f.label || f.key };
+    if (kind === "number") {
+      attrs.inputmode = "numeric";
+      if (f.min != null) attrs.min = String(f.min);
+      if (f.max != null) attrs.max = String(f.max);
+      attrs.step = f.step != null ? String(f.step) : "1";
+    }
+    const input = el("input", attrs);
+    inputs.set(f.key, input);
     card.append(el("div", { class: "pc-field" }, el("label", {}, f.label || f.key), input));
   }
   const msg = el("p", { class: "pc-msg" });
   const btn = el("button", { class: "pc-btn" }, p.submitLabel || "Submit");
   btn.addEventListener("click", async () => {
-    const variables = {};
-    for (const [k, input] of Object.entries(inputs)) variables[k] = input.value;
+    const variables = Object.create(null);
+    for (const [k, input] of inputs) {
+      if (fieldTypes.get(k) === "number") {
+        const t = String(input.value).trim();
+        // Blank → omit so the action-side default applies; a non-finite parse
+        // (NaN/Infinity) is also omitted rather than smuggling a raw string
+        // process variable through, which would defeat the numeric coercion.
+        if (t === "") continue;
+        const num = Number(t);
+        if (!Number.isFinite(num)) continue;
+        variables[k] = num;
+      } else {
+        variables[k] = input.value;
+      }
+    }
     btn.disabled = true; msg.className = "pc-msg"; msg.textContent = "Submitting…";
     try {
       const res = await getJSON("/app/actions/start/" + encodeURIComponent(p.action.process),
         { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ variables }) });
       msg.className = "pc-msg ok";
       msg.textContent = "Started (instance " + (res.processInstanceKey ?? "?") + ")";
-      for (const input of Object.values(inputs)) input.value = "";
+      for (const input of inputs.values()) input.value = "";
       document.dispatchEvent(new CustomEvent("pc:refresh"));
     } catch (e) {
       msg.className = "pc-msg err"; msg.textContent = String(e.message || e);
@@ -479,6 +506,23 @@ function renderDataGrid(node) {
   card.append(table);
   const span = String((cols.length || 1) + (hasExtra ? 1 : 0));
 
+  // Expansion state has to outlive the poll: refresh() rebuilds the whole tbody
+  // every refreshMs, so without this an open detail row (where you answer an
+  // escalation) would collapse on the next tick. We remember which rowKeys are
+  // open, and reuse the already-built detail <tr> for them across refreshes so a
+  // half-typed answer survives too. Keyed by p.rowKey; grids without one keep the
+  // old (collapse-on-refresh) behavior.
+  const expanded = new Set();
+  const detailNodes = new Map();
+  // A row only participates in expansion/detail-node caching if it has a real
+  // (non-null) rowKey. Coercing a missing key through String() would yield the
+  // literal "undefined"/"null" and collide unrelated rows, so treat it as keyless.
+  const rowKeyOf = (row) => {
+    if (!p.rowKey) return null;
+    const v = row[p.rowKey];
+    return v == null ? null : String(v);
+  };
+
   function dataUrl(source, tbl, filters, order) {
     let u = "/app/data/" + encodeURIComponent(source) + "/" + encodeURIComponent(tbl);
     const qs = [];
@@ -628,6 +672,7 @@ function renderDataGrid(node) {
 
   function renderRow(row) {
     const cells = cols.map((c) => gridCell(c, row));
+    const key = rowKeyOf(row);
     let toggle = null;
     if (hasExtra) {
       const actionCell = el("td", { class: "pc-row-actions" });
@@ -644,16 +689,29 @@ function renderDataGrid(node) {
     const tr = el("tr", {}, ...cells);
     tbody.append(tr);
     if (detail && toggle) {
-      const dtr = el("tr", { hidden: "" }, el("td", { colspan: span }));
-      let built = false;
+      const isOpen = key != null && expanded.has(key);
+      // Reuse an already-built detail row for an open PR across refreshes so its
+      // expanded state — and any half-typed escalation answer in the form — survives
+      // the poll. A closed (or keyless) row always gets a fresh, lazily-built panel.
+      let entry = key != null ? detailNodes.get(key) : null;
+      if (!(isOpen && entry && entry.built)) {
+        const dtr = el("tr", { hidden: isOpen ? null : "" }, el("td", { colspan: span }));
+        entry = { dtr, built: false };
+        if (key != null) detailNodes.set(key, entry);
+        if (isOpen) { entry.built = true; dtr.firstChild.append(detailPanel(row)); }
+      }
+      const dtr = entry.dtr;
+      toggle.textContent = dtr.hidden ? "▸" : "▾";
       toggle.addEventListener("click", (ev) => {
         ev.stopPropagation();
         const open = dtr.hidden;
         dtr.hidden = !open;
         toggle.textContent = open ? "▾" : "▸";
-        if (open && !built) {
-          built = true;
-          dtr.firstChild.append(detailPanel(row));
+        if (open) {
+          if (key != null) expanded.add(key);
+          if (!entry.built) { entry.built = true; dtr.firstChild.append(detailPanel(row)); }
+        } else if (key != null) {
+          expanded.delete(key);
         }
       });
       tbody.append(dtr);
@@ -663,6 +721,14 @@ function renderDataGrid(node) {
   async function refresh() {
     try {
       const { rows } = await getJSON(dataUrl(p.data.source, p.data.table, activeFilter, p.data.orderBy));
+      // Forget expansion / cached detail nodes for rows no longer present so the maps
+      // don't grow without bound and a stale answer can't resurface on a key reuse.
+      if (p.rowKey) {
+        const live = new Set();
+        for (const r of rows) { const k = rowKeyOf(r); if (k != null) live.add(k); }
+        for (const k of [...detailNodes.keys()]) if (!live.has(k)) detailNodes.delete(k);
+        for (const k of [...expanded]) if (!live.has(k)) expanded.delete(k);
+      }
       tbody.replaceChildren();
       for (const row of rows) renderRow(row);
       if (!rows.length) tbody.append(el("tr", {}, el("td", { colspan: span }, "No rows")));

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

@@ -16,11 +16,11 @@ function matchRule(rules, key) {
     return undefined;
 }
 export function mountSecurity(ctx) {
-    const sec = (ctx.manifest.security ?? {});
-    const mode = sec.mode ?? "local";
-    const roles = sec.roles ?? [];
-    const surfaces = sec.rules?.surfaces;
-    const actions = sec.rules?.actions;
+    const sec = ctx.manifest.security;
+    const mode = typeof sec?.mode === "string" ? sec.mode : "local";
+    const roles = Array.isArray(sec?.roles) ? sec.roles.filter((role) => typeof role === "string") : [];
+    const surfaces = sec?.rules?.surfaces;
+    const actions = sec?.rules?.actions;
     ctx.host.log("info", "security policy loaded", { mode, roles });
     return {
         mode,

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

@@ -0,0 +1,18 @@
+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

@@ -0,0 +1,133 @@
+// 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/dist/runtime/core/modules/triggers.js

@@ -2,6 +2,7 @@
 // into an HTTP route that verifies the request, maps the payload, and publishes the declared
 // message to the engine for correlation. HMAC verification uses Web Crypto (global in both
 // Node 18+ and Deno), so this stays runtime-agnostic.
+import { isRecord } from "../guards.js";
 import { json, normalizeRoutePath } from "../router.js";
 import { nextCronFire, parseCron } from "./cron.js";
 /**
@@ -17,7 +18,7 @@ export function resolveExpr(expr, scope) {
     let cur = scope;
     for (const seg of pathExpr.split(".")) {
         if (cur && typeof cur === "object" && Object.prototype.hasOwnProperty.call(cur, seg)) {
-            cur = cur[seg];
+            cur = Object.getOwnPropertyDescriptor(cur, seg)?.value;
         }
         else {
             return undefined;
@@ -45,7 +46,7 @@ export function evalCorrelation(expr, scope) {
  * else `{}`.
  */
 export function resolveActionVariables(expr, scope) {
-    const asRecord = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+    const asRecord = (v) => isRecord(v) ? v : undefined;
     if (typeof expr === "string") {
         return asRecord(resolveExpr(expr, scope)) ?? asRecord(scope.body) ?? {};
     }
@@ -97,10 +98,16 @@ const MAX_TIMER_DELAY_MS = 2_147_483_647;
 function defaultScheduler() {
     return {
         setTimer: (fn, ms) => globalThis.setTimeout(fn, ms),
-        clearTimer: (h) => globalThis.clearTimeout(h),
+        clearTimer: (h) => {
+            if (isTimerHandle(h))
+                globalThis.clearTimeout(h);
+        },
         now: () => Date.now(),
     };
 }
+function isTimerHandle(handle) {
+    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(ctx, app, sched = defaultScheduler()) {
@@ -194,7 +201,7 @@ export function mountTriggers(ctx, app, sched = defaultScheduler()) {
         };
         arm();
     };
-    for (const trig of (ctx.manifest.triggers ?? [])) {
+    for (const trig of ctx.manifest.triggers ?? []) {
         if (trig.type === "cron") {
             armCron(trig);
             continue;
@@ -232,7 +239,9 @@ export function mountTriggers(ctx, app, sched = defaultScheduler()) {
                         return json({ ok: true, deduped: true });
                     seenDeliveries.add(delivery);
                     if (seenDeliveries.size > 10_000) {
-                        seenDeliveries.delete(seenDeliveries.values().next().value);
+                        const oldest = seenDeliveries.values().next().value;
+                        if (oldest !== undefined)
+                            seenDeliveries.delete(oldest);
                     }
                 }
                 let body = {};

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

@@ -1,6 +1,7 @@
 // workers — load each declared worker's handler module and register it as a push worker
 // on the engine. Handlers are resolved by a small, documented contract and are injected
 // with the app's runtime API (datasource + engine + host utils).
+import { isRecord } from "../guards.js";
 import { workerJobType } from "../manifest.js";
 import { runLlmJob } from "./llm.js";
 /** Adapt an engine SDK client into the LLM module's `DecisionEvaluator`, parsing the
@@ -8,13 +9,12 @@ import { runLlmJob } from "./llm.js";
  *  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) {
-    const client = sdk;
     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;
@@ -26,6 +26,12 @@ export function sdkDecisionEvaluator(sdk) {
         }
     };
 }
+function hasDecisionCapableSdk(sdk) {
+    return isRecord(sdk) && typeof sdk.evaluateDecision === "function";
+}
+function isAppJobHandler(value) {
+    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)
@@ -33,17 +39,17 @@ export function sdkDecisionEvaluator(sdk) {
  *   3. `default` (when it is a function)
  */
 export function resolveHandler(mod, jobType) {
-    const map = mod.handlers;
-    if (map && typeof map[jobType] === "function")
+    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")
+    if (isAppJobHandler(mod[jobType]))
         return mod[jobType];
-    if (map && typeof map[seg] === "function")
+    if (map && isAppJobHandler(map[seg]))
         return map[seg];
-    if (typeof mod[seg] === "function")
+    if (isAppJobHandler(mod[seg]))
         return mod[seg];
-    if (typeof mod.default === "function")
+    if (isAppJobHandler(mod.default))
         return mod.default;
     return undefined;
 }

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

@@ -1,5 +1,6 @@
 import type { EngineClient, HostContext } from "./host.ts";
 import { type AppManifest } from "./manifest.ts";
+import type { TemplateSource } from "./modules/templates.ts";
 import { DataLayer } from "./modules/datasource.ts";
 import { type SecurityPolicy } from "./modules/security.ts";
 /** Resolve the HTTP port: explicit option, else $PORT, else 8090. Throws a clear
@@ -26,6 +27,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 {
     readonly manifest: AppManifest;

package/dist/runtime/core/runtime.js

@@ -25,11 +25,11 @@ export function resolvePort(explicit, envPort) {
     }
     return n;
 }
-/** 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. */
+function hasEngineSdk(engine) {
+    return "sdk" in engine;
+}
 function engineSdk(engine) {
-    return engine.sdk;
+    return hasEngineSdk(engine) ? engine.sdk : undefined;
 }
 export async function createUrbanApp(opts) {
     const host = opts.host;
@@ -44,7 +44,7 @@ export async function createUrbanApp(opts) {
         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;
     let security;
     let server;

package/dist/runtime/core/validate.d.ts

@@ -1,4 +1,4 @@
-import { type AppManifest } from "./manifest.ts";
+import type { AppManifest } from "./manifest.ts";
 export interface ValidationIssue {
     path: string;
     message: string;
@@ -9,5 +9,6 @@ export declare class ManifestValidationError extends Error {
 }
 /** Validate a parsed manifest. Returns the list of issues (empty === valid). */
 export declare function collectManifestIssues(m: unknown): ValidationIssue[];
+export declare function assertValidManifest(m: unknown): asserts m is AppManifest;
 /** Throw ManifestValidationError if the manifest is invalid; otherwise return it typed. */
 export declare function validateManifest(m: unknown): AppManifest;