@nanobpm/urban 0.20.0 → 0.22.0

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;

package/src/runtime/core/validate.ts

@@ -9,7 +9,8 @@
 // silently — the whole point of consuming the package rather than vendoring a copy.
 
 import schema from "@nanobpm/nano-app-schema/schema" with { type: "json" };
-import { workerJobType, type AppManifest } from "./manifest.ts";
+import { isRecord } from "./guards.ts";
+import type { AppManifest } from "./manifest.ts";
 
 export interface ValidationIssue {
   path: string;
@@ -35,15 +36,15 @@ interface JsonSchema {
   $defs?: { slug?: { pattern?: string } };
 }
 
-const S = schema as unknown as JsonSchema;
+const S: JsonSchema = schema;
 
 /** Validate a parsed manifest. Returns the list of issues (empty === valid). */
 export function collectManifestIssues(m: unknown): ValidationIssue[] {
   const issues: ValidationIssue[] = [];
-  if (m === null || typeof m !== "object" || Array.isArray(m)) {
+  if (!isRecord(m)) {
     return [{ path: "$", message: "manifest must be a JSON object" }];
   }
-  const obj = m as Record<string, unknown>;
+  const obj = m;
 
   // — Envelope, driven by the schema —
   for (const req of S.required ?? []) {
@@ -69,11 +70,11 @@ export function collectManifestIssues(m: unknown): ValidationIssue[] {
   }
 
   // — Runtime binding rules —
-  const man = obj as unknown as AppManifest;
-
-  if (Array.isArray(man.workers)) {
-    man.workers.forEach((w, i) => {
-      if (!workerJobType(w)) {
+  const workers = Array.isArray(obj.workers) ? obj.workers : undefined;
+  if (workers) {
+    workers.forEach((w, i) => {
+      const worker = isRecord(w) ? w : undefined;
+      if (typeof worker?.taskType !== "string" || worker.taskType.length === 0) {
         issues.push({ path: `workers[${i}]`, message: "missing taskType" });
       }
       // A worker is backed by exactly one of: a `handler` file, an `llm` binding,
@@ -82,9 +83,9 @@ export function collectManifestIssues(m: unknown): ValidationIssue[] {
       // `connector` actually resolves to an installed pack is a runtime seam check
       // (mountConnectors), not something this static manifest check can see.
       const backings: string[] = [];
-      if (typeof w?.handler === "string" && w.handler.length > 0) backings.push("handler");
-      if (typeof w?.llm === "string" && w.llm.length > 0) backings.push("llm");
-      if (typeof w?.connector === "string" && w.connector.length > 0) backings.push("connector");
+      if (typeof worker?.handler === "string" && worker.handler.length > 0) backings.push("handler");
+      if (typeof worker?.llm === "string" && worker.llm.length > 0) backings.push("llm");
+      if (typeof worker?.connector === "string" && worker.connector.length > 0) backings.push("connector");
       if (backings.length === 0) {
         issues.push({
           path: `workers[${i}]`,
@@ -97,37 +98,41 @@ export function collectManifestIssues(m: unknown): ValidationIssue[] {
         });
       }
       // A `connection` must reference a declared top-level `connections` entry.
-      if (typeof w?.connection === "string" && w.connection.length > 0) {
+      if (typeof worker?.connection === "string" && worker.connection.length > 0) {
         const conns =
-          man.connections && typeof man.connections === "object" && !Array.isArray(man.connections)
-            ? (man.connections as Record<string, unknown>)
+          isRecord(obj.connections)
+            ? obj.connections
             : undefined;
-        if (!conns || !(w.connection in conns)) {
+        if (!conns || !(worker.connection in conns)) {
           issues.push({
             path: `workers[${i}].connection`,
-            message: `no such connection "${w.connection}" (add it to connections)`,
+            message: `no such connection "${worker.connection}" (add it to connections)`,
           });
         }
       }
     });
   }
 
-  if (man.data?.sources) {
-    for (const [name, src] of Object.entries(man.data.sources)) {
-      if (!src || typeof src.driver !== "string") {
+  const data = isRecord(obj.data) ? obj.data : undefined;
+  const sources = isRecord(data?.sources) ? data.sources : undefined;
+  if (sources) {
+    for (const [name, src] of Object.entries(sources)) {
+      const source = isRecord(src) ? src : undefined;
+      if (!source || typeof source.driver !== "string") {
         issues.push({ path: `data.sources.${name}.driver`, message: "missing driver" });
       }
-      if (!src || typeof src.url !== "string") {
+      if (!source || typeof source.url !== "string") {
         issues.push({ path: `data.sources.${name}.url`, message: "missing url" });
       }
     }
-    if (man.data.default && !man.data.sources[man.data.default]) {
-      issues.push({ path: "data.default", message: `no such source "${man.data.default}"` });
+    if (typeof data?.default === "string" && !sources[data.default]) {
+      issues.push({ path: "data.default", message: `no such source "${data.default}"` });
     }
   }
 
-  if (man.types) {
-    for (const [name, t] of Object.entries(man.types)) {
+  const types = isRecord(obj.types) ? obj.types : undefined;
+  if (types) {
+    for (const [name, t] of Object.entries(types)) {
       // `table` is optional in the schema: a type may declare `fields` without a
       // `table` (a transient / non-persisted domain type). Don't require it.
       if (t && typeof t !== "object") {
@@ -136,19 +141,25 @@ export function collectManifestIssues(m: unknown): ValidationIssue[] {
     }
   }
 
-  if (Array.isArray(man.triggers)) {
-    man.triggers.forEach((t, i) => {
-      if (!t?.id) issues.push({ path: `triggers[${i}].id`, message: "missing id" });
-      if (!t?.type) issues.push({ path: `triggers[${i}].type`, message: "missing type" });
+  const triggers = Array.isArray(obj.triggers) ? obj.triggers : undefined;
+  if (triggers) {
+    triggers.forEach((t, i) => {
+      const trigger = isRecord(t) ? t : undefined;
+      if (!trigger?.id) issues.push({ path: `triggers[${i}].id`, message: "missing id" });
+      if (!trigger?.type) issues.push({ path: `triggers[${i}].type`, message: "missing type" });
     });
   }
 
   return issues;
 }
 
-/** Throw ManifestValidationError if the manifest is invalid; otherwise return it typed. */
-export function validateManifest(m: unknown): AppManifest {
+export function assertValidManifest(m: unknown): asserts m is AppManifest {
   const issues = collectManifestIssues(m);
   if (issues.length > 0) throw new ManifestValidationError(issues);
-  return m as AppManifest;
+}
+
+/** Throw ManifestValidationError if the manifest is invalid; otherwise return it typed. */
+export function validateManifest(m: unknown): AppManifest {
+  assertValidManifest(m);
+  return m;
 }

package/src/runtime/devserver.test.ts

@@ -92,13 +92,14 @@ test("stop() during an in-flight reload does not start a replacement app", async
       const id = `a${starts.length}`;
       starts.push(id);
       if (id === "a0") {
-        return {
+        const app: UrbanApp = {
           ...fakeApp(stops, id),
           async stop() {
             await stopGate; // block the first reload inside app.stop()
             stops.push(id);
           },
-        } as UrbanApp;
+        };
+        return app;
       }
       return fakeApp(stops, id);
     },
@@ -195,18 +196,30 @@ test("a change during an in-flight reload doesn't detach stop() from it", async
 function fakeHost(): { host: HostContext; fire: (p: string) => void; closed: () => boolean } {
   let cb: ((p: string) => void) | undefined;
   let closed = false;
-  const host = {
+  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 () => {} }),
     watch(onChange: (p: string) => void) {
       cb = onChange;
       return { close: () => (closed = true) };
     },
-  } as unknown as HostContext;
+    now: () => 0,
+    log: () => {},
+  };
   return { host, fire: (p) => cb?.(p), closed: () => closed };
 }
 
 function fakeApp(stops: string[], id: string): UrbanApp {
   return {
-    manifest: { id } as UrbanApp["manifest"],
+    manifest: { schemaVersion: 1, id, name: id },
     root: ".",
     async start() {},
     async stop() {

package/src/runtime/devserver.ts

@@ -13,6 +13,7 @@
 
 import { runFromEnv } from "./run.ts";
 import { selectHost } from "./adapters/detect.ts";
+import { errorMessage } from "./core/guards.ts";
 import type { HostContext, WatchHandle } from "./core/host.ts";
 import type { UrbanApp } from "./core/runtime.ts";
 import { createNodeGenIO, runGen } from "../toolkit/index.ts";
@@ -136,7 +137,7 @@ export async function runDev(opts: DevOptions = {}, deps?: Partial<DevDeps>): Pr
       log("✔ reloaded");
     } catch (err) {
       // Keep the dev server alive on a bad edit; the next save will retry.
-      log(`✖ reload failed: ${String((err as Error)?.message ?? err)}`);
+      log(`✖ reload failed: ${errorMessage(err)}`);
     } finally {
       reloading = false;
       if (queued && !stopped) {

package/src/runtime/engine/nanosdk.test.ts

@@ -224,7 +224,7 @@ test("registerWorker creates a worker the SDK auto-starts, and dispatches + comp
   assert.equal(rec.started, 1);
 
   let completedWith: Record<string, unknown> | undefined;
-  await rec.dispatch({
+  const job: NanoSdkActivatedJob = {
     jobKey: 12,
     processInstanceKey: 34,
     elementId: "e1",
@@ -236,7 +236,8 @@ test("registerWorker creates a worker the SDK auto-starts, and dispatches + comp
     async fail() {
       throw new Error("should not fail");
     },
-  } as unknown as NanoSdkActivatedJob);
+  };
+  await rec.dispatch(job);
   assert.deepEqual(handled, [{ n: 5 }]);
   assert.deepEqual(completedWith, { out: 5 });
 
@@ -252,7 +253,7 @@ test("registerWorker fails the job when the handler throws", async () => {
   });
   const rec = client.workers[0];
   let failBody: { errorMessage: string; retries?: number } | undefined;
-  await rec.dispatch({
+  const job: NanoSdkActivatedJob = {
     jobKey: "j1",
     variables: {},
     async complete() {
@@ -262,7 +263,8 @@ test("registerWorker fails the job when the handler throws", async () => {
       failBody = body;
       return "failed";
     },
-  } as unknown as NanoSdkActivatedJob);
+  };
+  await rec.dispatch(job);
   assert.equal(failBody?.errorMessage, "boom");
   assert.equal(failBody?.retries, 0);
 });
@@ -275,7 +277,7 @@ test("registerWorker routes a thrown BpmnError to the engine's error()", async (
   });
   const rec = client.workers[0];
   let errorBody: { errorCode: string; errorMessage?: string } | undefined;
-  await rec.dispatch({
+  const job: NanoSdkActivatedJob = {
     jobKey: "j1",
     variables: {},
     async complete() {
@@ -288,7 +290,8 @@ test("registerWorker routes a thrown BpmnError to the engine's error()", async (
       errorBody = body;
       return "raised";
     },
-  } as unknown as NanoSdkActivatedJob);
+  };
+  await rec.dispatch(job);
   assert.equal(errorBody?.errorCode, "NOT_FOUND");
   assert.equal(errorBody?.errorMessage, "no such record");
 });
@@ -301,7 +304,7 @@ test("registerWorker falls back to fail() for a BpmnError when the SDK has no er
   });
   const rec = client.workers[0];
   let failBody: { errorMessage: string } | undefined;
-  await rec.dispatch({
+  const job: NanoSdkActivatedJob = {
     jobKey: "j1",
     variables: {},
     async complete() {
@@ -312,7 +315,8 @@ test("registerWorker falls back to fail() for a BpmnError when the SDK has no er
       return "failed";
     },
     // no error() — older transport
-  } as unknown as NanoSdkActivatedJob);
+  };
+  await rec.dispatch(job);
   assert.equal(failBody?.errorMessage, "no such record");
 });
 
@@ -324,7 +328,7 @@ test("registerWorker falls back to fail() when the BPMN error report itself thro
   });
   const rec = client.workers[0];
   let failBody: { errorMessage: string } | undefined;
-  await rec.dispatch({
+  const job: NanoSdkActivatedJob = {
     jobKey: "j1",
     variables: {},
     async complete() {
@@ -337,7 +341,8 @@ test("registerWorker falls back to fail() when the BPMN error report itself thro
       failBody = body;
       return "failed";
     },
-  } as unknown as NanoSdkActivatedJob);
+  };
+  await rec.dispatch(job);
   // The job must still be acknowledged via fail() rather than silently dropped.
   assert.equal(failBody?.errorMessage, "no such record");
 });
@@ -371,7 +376,7 @@ test("close drains the REST-fallback worker via the SDK's stopAllWorkers", async
 
 test("close tolerates a client without stopAllWorkers", async () => {
   const client = fakeSdkClient();
-  delete (client as { stopAllWorkers?: unknown }).stopAllWorkers;
+  delete client.stopAllWorkers;
   const engine = new SdkEngineClient(client);
   await engine.registerWorker("a", async () => ({}));
   await engine.close();

package/src/runtime/engine/nanosdk.ts

@@ -19,6 +19,7 @@ import type {
 } from "../core/host.ts";
 import { isBpmnError } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
+import { isRecord } from "../core/guards.ts";
 
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
@@ -32,7 +33,7 @@ export function requireProcessInstanceKey(key: string | number | null | undefine
 /** A job as delivered to a nano-sdk job handler: the frame fields plus the
  *  acknowledgement actions the handler must call. */
 export interface NanoSdkActivatedJob {
-  jobKey: string;
+  jobKey: string | number;
   type?: string;
   processInstanceKey?: string | number;
   elementId?: string;
@@ -134,7 +135,8 @@ export class SdkEngineClient implements EngineClient {
    * the same connection. Surfaced to handlers as `AppApi.sdk`.
    */
   get sdk(): EngineSdkClient {
-    return this.client as unknown as EngineSdkClient;
+    // biome-ignore lint/plugin: `this.client` is the same `@nanobpm/nano-sdk` client at runtime; exposing its full EngineSdkClient surface is the adapter boundary (see EngineSdkClient in ./sdk.ts).
+    return this.client as NanoSdkClient & EngineSdkClient;
   }
 
   async deployResources(
@@ -155,12 +157,13 @@ export class SdkEngineClient implements EngineClient {
       variables: input.variables ?? {},
       awaitCompletion: input.awaitCompletion ?? false,
     });
+    const rawKey = body.processInstanceKey ?? body.key;
     const key =
-      (body.processInstanceKey as string | number | undefined) ??
-      (body.key as string | number | undefined);
+      typeof rawKey === "string" || typeof rawKey === "number" ? rawKey : undefined;
+    const variables = isRecord(body.variables) ? body.variables : undefined;
     return {
       processInstanceKey: requireProcessInstanceKey(key),
-      variables: (body.variables as Record<string, unknown> | undefined) ?? undefined,
+      variables,
     };
   }
 
@@ -188,10 +191,10 @@ export class SdkEngineClient implements EngineClient {
     // User tasks are an eventually consistent read; ask for zero-wait consistency so
     // the search reflects what is currently visible without blocking.
     const body = await this.client.searchUserTasks(
-      { filter: (filter ?? {}) as Record<string, unknown> },
+      { filter: { ...(filter ?? {}) } },
       { consistency: { waitUpToMs: 0 } },
     );
-    const items = (body.items as Record<string, unknown>[] | undefined) ?? [];
+    const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
     return items.flatMap((it) => {
       const userTaskKey = it.userTaskKey ?? it.key;
       if (userTaskKey == null || userTaskKey === "") {
@@ -200,8 +203,8 @@ export class SdkEngineClient implements EngineClient {
       }
       return [{
         userTaskKey: String(userTaskKey),
-        elementId: it.elementId as string | undefined,
-        variables: it.variables as Record<string, unknown> | undefined,
+        elementId: typeof it.elementId === "string" ? it.elementId : undefined,
+        variables: isRecord(it.variables) ? it.variables : undefined,
       }];
     });
   }
@@ -236,7 +239,7 @@ export class SdkEngineClient implements EngineClient {
         };
         try {
           const out = await handler(engineJob);
-          return await job.complete((out as Record<string, unknown> | undefined) ?? {});
+          return await job.complete(out ?? {});
         } catch (err) {
           // A handler-raised BPMN error is a modelled, non-retryable outcome:
           // report it as a BPMN error (routed to an error boundary/event) rather
@@ -246,7 +249,7 @@ export class SdkEngineClient implements EngineClient {
           if (isBpmnError(err) && typeof job.error === "function") {
             // `message` is typed loosely (the guard survives module duplication),
             // so coerce to a string before slicing to avoid a secondary crash.
-            const raw = (err as { message?: unknown }).message;
+            const raw = err.message;
             const message = typeof raw === "string" && raw.length > 0 ? raw : err.errorCode;
             this.log("info", `handler ${jobType} raised BPMN error`, {
               errorCode: err.errorCode,
@@ -339,15 +342,19 @@ async function importNanoSdk(): Promise<
   // Indirect the specifier so the (lazily loaded) module is not resolved at
   // typecheck time and stays out of the import graph for injected-client paths.
   const spec = "@nanobpm/nano-sdk";
-  const mod = (await import(spec)) as {
-    createCamundaClient?: (opts: Record<string, unknown>) => NanoSdkClient;
-  };
-  if (typeof mod.createCamundaClient !== "function") {
+  const mod: unknown = await import(spec);
+  if (!isNanoSdkModule(mod)) {
     throw new Error("@nanobpm/nano-sdk does not export createCamundaClient");
   }
   return mod.createCamundaClient;
 }
 
+function isNanoSdkModule(value: unknown): value is {
+  createCamundaClient: (opts: Record<string, unknown>) => NanoSdkClient;
+} {
+  return isRecord(value) && typeof value.createCamundaClient === "function";
+}
+
 /**
  * Build the Urban runtime's `EngineClient`, backed by a single `@nanobpm/nano-sdk`
  * client. Provide a `client`/`createClient` seam to inject a fake (tests, embedded

package/src/runtime/index.ts

@@ -70,6 +70,8 @@ export type { ConnectorsHandle } from "./core/modules/connectors.ts";
 // Data layer
 export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";
 export type { ProvisionedSource } from "./core/modules/datasource.ts";
+export { runDataOp } from "./core/modules/dataops.ts";
+export type { DataOp, DataRequest, ResolvedSource } from "./core/modules/dataops.ts";
 export { makeGateway, Table } from "./core/modules/gateway.ts";
 export type {
   ColumnMeta,
@@ -101,6 +103,11 @@ export type {
 } from "./core/modules/llm.ts";
 export { evalCorrelation } from "./core/modules/triggers.ts";
 
+// Model deploy + `{{name}}` template substitution
+export { deployModels } from "./core/modules/deploy.ts";
+export { applyTemplates, resolveTemplates } from "./core/modules/templates.ts";
+export type { TemplateApplication, TemplateSource } from "./core/modules/templates.ts";
+
 // Adapters + engine + run entrypoint
 export { createNodeHost } from "./adapters/node.ts";
 export { createDenoHost } from "./adapters/deno.ts";

package/src/runtime/run.ts

@@ -4,6 +4,7 @@
 
 import { createUrbanApp, type CreateUrbanAppOptions, type UrbanApp } from "./core/runtime.ts";
 import { selectHost } from "./adapters/detect.ts";
+import { denoGlobal, processGlobal } from "./adapters/globals.ts";
 import { createNanoSdkEngineClient } from "./engine/nanosdk.ts";
 import type { EngineClient } from "./core/host.ts";
 
@@ -49,6 +50,7 @@ export async function runFromEnv(opts: RunOptions = {}): Promise<UrbanApp> {
     manifestPath: opts.manifestPath,
     port: opts.port,
     mount: opts.mount,
+    templates: opts.templates,
   });
   await app.start();
 
@@ -74,19 +76,17 @@ export function installSignalHandlers(stop: () => Promise<void>): void {
         }
       });
   };
-  const g = globalThis as {
-    Deno?: { addSignalListener(sig: string, cb: () => void): void };
-    process?: { on(sig: string, cb: () => void): void };
-  };
-  if (g.Deno) {
+  const deno = denoGlobal();
+  const proc = processGlobal();
+  if (deno?.addSignalListener) {
     try {
-      g.Deno.addSignalListener("SIGINT", onSignal);
-      g.Deno.addSignalListener("SIGTERM", onSignal);
+      deno.addSignalListener("SIGINT", onSignal);
+      deno.addSignalListener("SIGTERM", onSignal);
     } catch {
       /* signal listeners may be unavailable (e.g. Windows) */
     }
-  } else if (g.process) {
-    g.process.on("SIGINT", onSignal);
-    g.process.on("SIGTERM", onSignal);
+  } else if (proc?.on) {
+    proc.on("SIGINT", onSignal);
+    proc.on("SIGTERM", onSignal);
   }
 }