@nanobpm/urban 0.21.0 → 0.23.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);
             }
         },
     });
@@ -359,6 +361,9 @@ table.pc-grid th { font-weight:600; opacity:.75; }
 .pc-subform-title { font-weight:600; font-size:.85rem; margin-bottom:.4rem; }
 .pc-prompt { font-size:.85rem; opacity:.8; margin-bottom:.4rem; white-space:pre-wrap; }
 .pc-textarea { width:100%; min-height:4rem; padding:.5rem; border:1px solid var(--pc-edge); border-radius:.4rem; font:inherit; }
+.pc-collapse-header { display:flex; align-items:center; gap:.5rem; width:100%; margin:0 0 .75rem; padding:0; background:transparent; border:0; color:inherit; font:inherit; font-size:1rem; font-weight:600; cursor:pointer; text-align:left; }
+.pc-chevron-inline { opacity:.6; font-size:.75rem; width:1em; }
+.pc-card-body[hidden] { display:none; }
 `;
 // The schema-driven browser renderer (ADR 0042 §3). Plain ES module string served at
 // /app/runtime.js — it does NOT ship Craft.js (authoring is console-side only). It
@@ -417,24 +422,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);
@@ -717,11 +747,83 @@ function renderDataGrid(node) {
 
 const RENDERERS = { text: renderText, actionForm: renderActionForm, dataGrid: renderDataGrid };
 
+// Durable per-node UI state. localStorage is keyed by the home page id + node
+// id so two grids on the same page (or the same grid across pages) don't clash,
+// and the collapsed state survives a full reload / new session — not just the
+// refresh poll. Every access is guarded: private-mode or storage-disabled
+// browsers throw on localStorage, and a UI preference must never break render.
+function readCollapsed(key, dflt) {
+  try {
+    const v = localStorage.getItem(key);
+    return v === null ? dflt : v === "1";
+  } catch (e) {
+    return dflt;
+  }
+}
+function writeCollapsed(key, val) {
+  try {
+    localStorage.setItem(key, val ? "1" : "0");
+  } catch (e) {
+    // Preference is best-effort; ignore storage failures.
+  }
+}
+
+// Wrap a rendered node so its card can be collapsed from a clickable header.
+// Opt-in via the node's "collapsible" prop; "defaultCollapsed" seeds the state
+// the first time (before the user has toggled it). Generic across node types —
+// the body (everything the renderer produced, minus its own <h2> title, which
+// becomes the header label) is hidden as one unit.
+function makeCollapsible(node, card) {
+  const props = node.props || {};
+  if (!props.collapsible) return card;
+  // Normalize to a card container. Card renderers already return
+  // <section class="pc-card"> — we unwrap those in place (lift out the <h2>
+  // title, reparent the rest into the body). A non-card renderer (e.g. text
+  // returning <p>/<h1>) is nested whole inside a fresh section instead:
+  // appending a <button>/<div> directly into a <p> is invalid markup the
+  // browser silently re-parents, breaking layout and click handling.
+  const isCard = card.tagName === "SECTION";
+  const container = isCard ? card : el("section", { class: "pc-card" });
+  const h2 = isCard && card.querySelector ? card.querySelector("h2") : null;
+  const titleText = props.title || (h2 ? h2.textContent : "") || "Section";
+  if (h2) h2.remove();
+  const body = el("div", { class: "pc-card-body" });
+  if (isCard) {
+    while (card.firstChild) body.append(card.firstChild);
+  } else {
+    body.append(card);
+  }
+  const chevron = el("span", { class: "pc-chevron-inline" }, "▾");
+  const header = el(
+    "button",
+    { class: "pc-collapse-header", type: "button" },
+    chevron,
+    el("span", { class: "pc-collapse-title" }, titleText),
+  );
+  const storageKey = "pc:collapsed:" + HOME + ":" + (node.id || titleText);
+  let collapsed = readCollapsed(storageKey, !!props.defaultCollapsed);
+  function apply() {
+    body.hidden = collapsed;
+    chevron.textContent = collapsed ? "▸" : "▾";
+    header.setAttribute("aria-expanded", String(!collapsed));
+  }
+  header.addEventListener("click", () => {
+    collapsed = !collapsed;
+    writeCollapsed(storageKey, collapsed);
+    apply();
+  });
+  apply();
+  container.append(header, body);
+  return container;
+}
+
 async function main() {
   try {
     const doc = await getJSON("/app/pages/" + encodeURIComponent(HOME));
     if (doc.title) document.title = doc.title;
-    root.replaceChildren(...(doc.nodes || []).map((n) => (RENDERERS[n.type] || (() => el("div")))(n)));
+    root.replaceChildren(
+      ...(doc.nodes || []).map((n) => makeCollapsible(n, (RENDERERS[n.type] || (() => el("div")))(n))),
+    );
   } catch (e) {
     root.replaceChildren(el("p", { class: "pc-msg err" }, "Failed to load page: " + String(e.message || e)));
   }

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;