@nanobpm/urban 0.21.0 → 0.22.0

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);
   }
 }

package/src/toolkit/addConnector.ts

@@ -13,6 +13,7 @@
 // unit-testable.
 
 import type { GenIO } from "./gen.ts";
+import { errorMessage, isRecord } from "../runtime/core/guards.ts";
 
 /** A config field a pack declares (subset of ext-types `ConfigField`). */
 interface PackConfigField {
@@ -90,9 +91,9 @@ export async function addConnector(opts: AddConnectorOptions): Promise<AddConnec
   }
   let pack: PackManifest;
   try {
-    pack = JSON.parse(await io.readText(packManifestPath)) as PackManifest;
+    pack = JSON.parse(await io.readText(packManifestPath));
   } catch (err) {
-    throw new Error(`failed to parse ${packManifestPath}: ${(err as Error).message}`);
+    throw new Error(`failed to parse ${packManifestPath}: ${errorMessage(err)}`);
   }
   if (typeof pack.id !== "string" || !pack.id) {
     throw new Error(`${packManifestPath} has no string "id" (a pack must declare its id).`);
@@ -123,7 +124,7 @@ export async function addConnector(opts: AddConnectorOptions): Promise<AddConnec
   try {
     app = JSON.parse(await io.readText(appManifestPath));
   } catch (err) {
-    throw new Error(`failed to parse ${appManifestPath}: ${(err as Error).message}`);
+    throw new Error(`failed to parse ${appManifestPath}: ${errorMessage(err)}`);
   }
   if (app === null || typeof app !== "object" || Array.isArray(app)) {
     throw new Error(`${appManifestPath} is not a JSON object.`);
@@ -168,10 +169,10 @@ export async function addConnector(opts: AddConnectorOptions): Promise<AddConnec
       // A pre-existing connection of this name must be a compatible object of the
       // same pack `type`; otherwise wiring workers to it would produce an invalid
       // or misleading manifest. Fail loudly instead of silently reusing it.
-      if (existing === null || typeof existing !== "object" || Array.isArray(existing)) {
+      if (!isRecord(existing)) {
         throw new Error(`connection "${connection}" already exists and is not an object.`);
       }
-      const conn = existing as Record<string, unknown>;
+      const conn = existing;
       if (conn.type !== undefined && conn.type !== pack.id) {
         throw new Error(
           `connection "${connection}" already exists with type "${String(conn.type)}", ` +

package/src/toolkit/derivers/messages.test.ts

@@ -134,10 +134,12 @@ const XML = `<?xml version="1.0"?>
 
 test("scanModelMessages extracts message name + envelope; a self-closing message is name-only", () => {
   const m = scanModelMessages(XML);
-  const placed = m.find((x) => x.messageName === "OrderPlaced") as MessageIo;
+  const placed = m.find((x) => x.messageName === "OrderPlaced");
+  assert.ok(placed);
   assert.ok(placed);
   assert.equal(placed.inputType, "Order");
-  const ping = m.find((x) => x.messageName === "Ping") as MessageIo;
+  const ping = m.find((x) => x.messageName === "Ping");
+  assert.ok(ping);
   assert.ok(ping);
   assert.equal(ping.inputType, undefined);
 });

package/src/toolkit/derivers/worker-io.test.ts

@@ -40,13 +40,15 @@ const XML = `<?xml version="1.0"?>
 
 test("scanModelWorkers extracts task type, element id, process, and envelope io", () => {
   const w = scanModelWorkers(XML);
-  const charge = w.find((x) => x.taskType === "orders.charge") as WorkerIo;
+  const charge = w.find((x) => x.taskType === "orders.charge");
+  assert.ok(charge);
   assert.ok(charge);
   assert.equal(charge.elementId, "Charge");
   assert.equal(charge.process, "orders");
   assert.equal(charge.in, "Payment");
   assert.equal(charge.out, "Receipt");
-  const notify = w.find((x) => x.taskType === "orders.notify") as WorkerIo;
+  const notify = w.find((x) => x.taskType === "orders.notify");
+  assert.ok(notify);
   assert.equal(notify.in, undefined);
   assert.equal(notify.out, undefined);
 });

package/src/toolkit/fsio.ts

@@ -50,7 +50,8 @@ export function createNodeGenIO(): GenIO {
         // stat failed (e.g. a virtual path); fall back to no cache key and let import() surface it.
       }
       const href = `${pathToFileURL(abs).href}${version}`;
-      return import(href) as Promise<Record<string, unknown>>;
+      const mod: Promise<Record<string, unknown>> = import(href);
+      return mod;
     },
   };
 }

package/src/toolkit/gen.ts

@@ -110,9 +110,9 @@ async function collectAll(opts: GenOptions): Promise<{ artifacts: DerivedArtifac
   const { root, io } = opts;
   const emitModels = opts.emitModels ?? true;
   const manifestPath = join(root, opts.manifestFile ?? "nano.app.json");
-  const manifest = JSON.parse(await io.readText(manifestPath)) as ToolkitManifest & {
+  const manifest: ToolkitManifest & {
     models?: { processes?: string[]; workflows?: string[] };
-  };
+  } = JSON.parse(await io.readText(manifestPath));
 
   const artifacts: DerivedArtifact[] = [];
 
@@ -186,8 +186,8 @@ export { dirOf, join as joinPath };
 export async function previewModels(opts: GenOptions): Promise<DerivedModels> {
   const { root, io } = opts;
   const manifestPath = join(root, opts.manifestFile ?? "nano.app.json");
-  const manifest = JSON.parse(await io.readText(manifestPath)) as {
+  const manifest: {
     models?: { processes?: string[]; workflows?: string[] };
-  };
+  } = JSON.parse(await io.readText(manifestPath));
   return deriveModels(root, io, manifest);
 }

package/src/toolkit/models.test.ts

@@ -93,7 +93,7 @@ test("deriveModels turns workflows/*.ts into a provenance-stamped processes/<id>
 
 test("deriveModels is a no-op without a module loader (pure/IDE callers)", async () => {
   const io = memIO({ "/app/workflows/greet.ts": "// source" });
-  delete (io as { importModule?: unknown }).importModule;
+  delete io.importModule;
   const d = await deriveModels("/app", io, CODE_FIRST_MANIFEST);
   assert.equal(d.attempted, false);
   assert.equal(d.artifacts.length, 0);

package/src/toolkit/models.ts

@@ -14,6 +14,7 @@ import type { DerivedArtifact } from "./artifact.ts";
 import type { GenIO } from "./gen.ts";
 import { expandPattern, joinPath } from "./gen.ts";
 import type { ModelSource } from "./derivers/worker-io.ts";
+import { isRecord } from "../runtime/core/guards.ts";
 
 /** Default source glob for code-first flows (matches the code-first scaffold layout). */
 export const DEFAULT_WORKFLOW_PATTERNS = ["workflows/*.ts"];
@@ -34,9 +35,7 @@ export interface ModelsManifest {
 
 /** A `defineFlow` export: has a string `id` and an `imperative`/`declarative` `kind`. */
 export function isWorkflow(v: unknown): v is Workflow {
-  if (!v || typeof v !== "object") return false;
-  const o = v as { id?: unknown; kind?: unknown };
-  return typeof o.id === "string" && (o.kind === "imperative" || o.kind === "declarative");
+  return isRecord(v) && typeof v.id === "string" && (v.kind === "imperative" || v.kind === "declarative");
 }
 
 /** Sanitize a flow id into a safe `.bpmn` filename (mirrors the host generator). */
@@ -113,7 +112,7 @@ function messageOf(e: unknown): string {
 /** Append an actionable hint when a `.ts` import fails because the runtime can't strip types. */
 function importHint(rel: string, e: unknown): string {
   const base = messageOf(e);
-  const code = (e as { code?: string })?.code ?? "";
+  const code = isRecord(e) && typeof e.code === "string" ? e.code : "";
   const looksLikeNoTsLoader =
     rel.endsWith(".ts") &&
     (code === "ERR_UNKNOWN_FILE_EXTENSION" || /Unknown file extension "\.ts"/.test(base));

package/src/toolkit/scaffold.ts

@@ -57,7 +57,7 @@ export async function scaffoldWorkers(opts: ScaffoldOptions): Promise<ScaffoldRu
   const manifestFile = opts.manifestFile ?? "nano.app.json";
   const manifestPath = joinPath(root, manifestFile);
 
-  const manifest = JSON.parse(await io.readText(manifestPath)) as ScaffoldManifest;
+  const manifest: ScaffoldManifest = JSON.parse(await io.readText(manifestPath));
   const models = await readModels(root, io, manifest);
   const declaredTypeIds = Object.keys(manifest.types ?? {});