@nanobpm/urban 0.35.0 → 0.37.0

package/src/cli.ts

@@ -25,7 +25,7 @@ import { denoGlobal, processGlobal } from "./runtime/adapters/globals.ts";
 import { errorMessage, isRecord } from "./runtime/core/guards.ts";
 import { scaffold, slugify } from "create-urban-app";
 import type { DataRequest } from "./runtime/index.ts";
-import { addConnector, createNodeGenIO, previewModels, runGen, scaffoldWorkers } from "./toolkit/index.ts";
+import { addConnector, createNodeGenIO, previewModels, generate, runGen } from "./toolkit/index.ts";
 import { pathToFileURL } from "node:url";
 import { readFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
@@ -50,7 +50,6 @@ interface Flags {
   manifest: string;
   port?: number;
   check: boolean;
-  write: boolean;
   deno: boolean;
   models: boolean;
   stdout: boolean;
@@ -62,7 +61,7 @@ interface Flags {
 }
 
 function parse(argv: string[]): Flags {
-  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, models: true, stdout: false, install: true, help: false, version: false, _: [] };
+  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, deno: false, models: true, stdout: false, install: true, help: false, version: false, _: [] };
   const need = (i: number, flag: string): string => {
     const v = argv[i];
     if (v === undefined || v.startsWith("-")) throw new Error(`flag ${flag} requires a value`);
@@ -73,7 +72,6 @@ function parse(argv: string[]): Flags {
     if (a === "-h" || a === "--help") f.help = true;
     else if (a === "-v" || a === "--version") f.version = true;
     else if (a === "--check") f.check = true;
-    else if (a === "--write") f.write = true;
     else if (a === "--deno") f.deno = true;
     else if (a === "--no-models") f.models = false;
     else if (a === "--models") f.models = true;
@@ -108,11 +106,12 @@ Usage:
   urban new <name> [--root <path>] [--deno] [--style model|code]    scaffold a new Urban app
                                     (--code-first is shorthand for --style code)
   urban check                       validate the manifest
-  urban gen [--check] [--no-models] derive artifacts (migrations, worker-io, + code-first models)
+  urban gen [--check] [--no-models] derive artifacts + scaffold write-once handler stubs
+                                    (--check: verify up-to-date without writing; a missing stub or
+                                    drifted artifact fails — run \`urban gen\`)
                                     (--no-models: skip writing derived .bpmn; type-contracts only)
   urban derive [--check|--stdout]   derive code-first models only (workflows/*.ts → processes/*.bpmn)
                                     (--stdout: print {models,incomplete} JSON without writing)
-  urban stubs [--write]             scaffold write-once handler stubs from the model
   urban add <pkg> [--no-install]    install a connector pack + wire it into nano.app.json
   urban run                         materialize + serve the app
   urban dev                         run + watch sources, hot-reload on change
@@ -148,23 +147,43 @@ async function cmdCheck(f: Flags): Promise<number> {
 
 async function cmdGen(f: Flags): Promise<number> {
   const io = createNodeGenIO();
-  const res = await runGen({ root: f.root, io, manifestFile: f.manifest, check: f.check, emitModels: f.models });
+  const res = await generate({ root: f.root, io, manifestFile: f.manifest, check: f.check, emitModels: f.models });
   if (res.incomplete) {
     console.error(`✖ ${res.modelErrors.length} workflow(s) failed to derive:`);
     for (const e of res.modelErrors) console.error(`  • ${e.path}: ${e.message}`);
     return 1;
   }
   if (f.check) {
-    if (res.drift.length === 0) {
-      console.log(`✔ generated artifacts are up to date (${res.artifacts.length} checked)`);
+    if (res.drift.length === 0 && res.missingStubs.length === 0) {
+      console.log(`✔ generated artifacts + handler stubs are up to date (${res.artifacts.length} checked)`);
       return 0;
     }
-    console.error(`✖ ${res.drift.length} generated artifact(s) are out of date — run \`urban gen\`:`);
-    for (const p of res.drift) console.error(`  • ${p}`);
+    if (res.drift.length > 0) {
+      console.error(`✖ ${res.drift.length} generated artifact(s) are out of date — run \`urban gen\`:`);
+      for (const p of res.drift) console.error(`  • ${p}`);
+    }
+    if (res.missingStubs.length > 0) {
+      console.error(`✖ ${res.missingStubs.length} handler stub(s) missing — run \`urban gen\`:`);
+      for (const p of res.missingStubs) console.error(`  • ${p}`);
+    }
     return 1;
   }
   console.log(`✔ generated ${res.artifacts.length} artifact(s):`);
   for (const a of res.artifacts) console.log(`  • ${a.path}`);
+
+  // Write-once handler stubs scaffolded as part of generation (workers from the model, operation
+  // delegates from the OpenAPI spec). Existing, human-owned stubs are kept verbatim.
+  const created = [
+    ...res.workerStubs.filter((o) => o.status === "created").map((o) => o.handlerPath),
+    ...res.operationStubs.filter((o) => o.status === "created").map((o) => o.handlerPath),
+  ];
+  if (created.length > 0) {
+    console.log(`✔ scaffolded ${created.length} handler stub(s):`);
+    for (const p of created) console.log(`  + ${p}`);
+  }
+  if (res.manifestPatched) {
+    console.log(`✔ wired ${res.wiredWorkers.length} worker(s) into ${f.manifest}`);
+  }
   return 0;
 }
 
@@ -217,38 +236,6 @@ async function cmdDerive(f: Flags): Promise<number> {
   return 0;
 }
 
-async function cmdStubs(f: Flags): Promise<number> {
-  const io = createNodeGenIO();
-  const run = await scaffoldWorkers({ root: f.root, io, manifestFile: f.manifest, write: f.write });
-
-  const created = run.outcomes.filter((o) => o.status === "created");
-  const would = run.outcomes.filter((o) => o.status === "would-create");
-  const kept = run.outcomes.filter((o) => o.status === "kept");
-  const typing = (o: { typedIn: boolean; typedOut: boolean }) =>
-    o.typedIn || o.typedOut ? ` (typed${o.typedIn ? " in" : ""}${o.typedOut ? " out" : ""})` : "";
-
-  if (run.write) {
-    console.log(`✔ scaffolded ${created.length} worker stub(s):`);
-    for (const o of created) console.log(`  + ${o.handlerPath}${typing(o)}`);
-    if (run.manifestPatched) {
-      console.log(`✔ wired ${run.wired.length} worker(s) into ${f.manifest}`);
-    }
-  } else {
-    if (would.length === 0) {
-      console.log(`✔ no new worker stubs to scaffold`);
-    } else {
-      console.log(`Would scaffold ${would.length} worker stub(s) — run with --write to apply:`);
-      for (const o of would) console.log(`  + ${o.handlerPath}${typing(o)}`);
-    }
-  }
-  for (const o of kept) console.log(`  = ${o.handlerPath} (kept — already exists)`);
-  if (run.skipped.length > 0) {
-    console.log(`  skipped ${run.skipped.length}: ` +
-      run.skipped.map((s) => `${s.taskType} (${s.reason})`).join(", "));
-  }
-  return 0;
-}
-
 async function cmdRun(f: Flags, mount?: Record<string, boolean>): Promise<number> {
   const app = await runFromEnv({
     root: f.root,
@@ -430,8 +417,6 @@ export async function main(argv: string[]): Promise<number> {
       return cmdGen(f);
     case "derive":
       return cmdDerive(f);
-    case "stubs":
-      return cmdStubs(f);
     case "add":
       return cmdAdd(f);
     case "data":

package/src/openapi/spec.ts

@@ -265,6 +265,30 @@ export function collectOperations(doc: OpenApiDoc): OperationInfo[] {
   return out;
 }
 
+/**
+ * Throw if the document declares the same `operationId` on more than one operation. An operationId
+ * must be unique across the whole OpenAPI document (it names the delegate module `<dir>/<operationId>`
+ * AND the generated controller registry key), so a duplicate would silently overwrite an earlier
+ * entry in the emitted object literal — dispatching the wrong delegate while still type-checking — and
+ * make the scaffolder plan the same stub twice. Called by the gen/scaffold path so `urban gen`
+ * fails loudly on an incoherent spec instead of shipping a mis-dispatching registry.
+ */
+export function assertUniqueOperationIds(doc: OpenApiDoc): void {
+  const seen = new Set<string>();
+  const duplicates = new Set<string>();
+  for (const op of collectOperations(doc)) {
+    if (seen.has(op.operationId)) duplicates.add(op.operationId);
+    seen.add(op.operationId);
+  }
+  if (duplicates.size > 0) {
+    const list = [...duplicates].sort().join(", ");
+    throw new Error(
+      `OpenAPI spec declares duplicate operationId(s): ${list}. Each operationId must be unique — ` +
+        "it names the delegate module and the generated controller registry key.",
+    );
+  }
+}
+
 /** "method path" pointers for every operation that declares no `operationId`. Such operations are
  *  unroutable (no delegate to bind), so the runtime mount logs them at `warn` and skips them. */
 export function operationsWithoutId(doc: OpenApiDoc): string[] {

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

@@ -5,7 +5,7 @@ import type { AppManifest } from "../manifest.ts";
 import type { EngineClient, HostContext, HttpRequest } from "../host.ts";
 import { makeRouter } from "../router.ts";
 import { DataLayer } from "./datasource.ts";
-import { mountApi, resolveOperationHandler, apiDocsPath, type ApiHandle, type OperationHandler } from "./api.ts";
+import { mountApi, resolveOperationHandler, apiDocsPath, NotImplemented, type ApiHandle, type OperationHandler } from "./api.ts";
 
 function req(
   method: string,
@@ -87,15 +87,17 @@ function build(
   modules: Record<string, Record<string, unknown>>,
   specText = spec,
   env: (v: string) => string | undefined = () => undefined,
+  existsPaths: string[] = [],
 ): Built {
   const imported: string[] = [];
   const logs: Array<{ level: string; msg: string }> = [];
+  const existsSet = new Set(existsPaths);
   const host: HostContext = {
     runtime: "node",
     env,
     readTextFile: async () => specText,
     listDir: async () => [],
-    exists: async () => false,
+    exists: async (p: string) => existsSet.has(p),
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },
@@ -597,3 +599,103 @@ test("secured operation: an unset secret env fails closed with 500 (misconfigura
   assert.equal(res.status, 500);
   assert.ok(logs.some((l) => l.level === "error" && /security is misconfigured/.test(l.msg)));
 });
+
+// ── Generated controller registry (ADR 0059) ────────────────────────────────────────────────────
+// When `nano-generated/controller.ts` is present, dispatch resolves delegates from its exported
+// `operations` map (deterministic, drift-checked) instead of per-op path imports.
+
+test("controller present: dispatch uses the registry, not a per-op import", async () => {
+  const seen: unknown[] = [];
+  const handler: OperationHandler = (input) => {
+    seen.push(input.params);
+    return { status: 200, body: { ok: true } };
+  };
+  const { router, imported } = build(
+    { spec: "openapi.json" },
+    {
+      "/app/nano-generated/controller": { operations: { getInvoice: handler } },
+    },
+    spec,
+    () => undefined,
+    ["/app/nano-generated/controller.ts"],
+  );
+  const res = await router(req("GET", "/app/api/invoices/7"));
+  assert.equal(res.status, 200);
+  assert.deepEqual(seen, [{ id: "7" }]);
+  // Only the controller barrel is imported — never a per-operation delegate path.
+  assert.deepEqual(imported, ["/app/nano-generated/controller"]);
+});
+
+test("controller present: request validation still runs before the registry delegate", async () => {
+  const handler: OperationHandler = () => ({ status: 201, body: { id: "i", amount: 1 } });
+  const { router } = build(
+    { spec: "openapi.json" },
+    { "/app/nano-generated/controller": { operations: { createInvoice: handler } } },
+    spec,
+    () => undefined,
+    ["/app/nano-generated/controller.ts"],
+  );
+  // amount:0 violates minimum:1 → a 400 from validation, before the delegate.
+  const res = await router(req("POST", "/app/api/invoices", { body: JSON.stringify({ id: "i", amount: 0 }) }));
+  assert.equal(res.status, 400);
+  assert.match(JSON.parse(res.body!).error, /request validation failed/);
+});
+
+test("controller present but missing a delegate key → 500 with a run-`urban gen` hint", async () => {
+  const { router, logs } = build(
+    { spec: "openapi.json" },
+    { "/app/nano-generated/controller": { operations: {} } }, // stale: getInvoice not registered
+    spec,
+    () => undefined,
+    ["/app/nano-generated/controller.ts"],
+  );
+  const res = await router(req("GET", "/app/api/invoices/7"));
+  assert.equal(res.status, 500);
+  assert.match(JSON.parse(res.body!).error, /is not registered/);
+  assert.ok(logs.some((l) => l.level === "error" && /not registered in the generated controller/.test(l.msg)));
+});
+
+test("a NotImplemented throw from a delegate maps to HTTP 501", async () => {
+  const stub: OperationHandler = () => {
+    throw new NotImplemented("getInvoice");
+  };
+  const { router } = build(
+    { spec: "openapi.json" },
+    { "/app/nano-generated/controller": { operations: { getInvoice: stub } } },
+    spec,
+    () => undefined,
+    ["/app/nano-generated/controller.ts"],
+  );
+  const res = await router(req("GET", "/app/api/invoices/7"));
+  assert.equal(res.status, 501);
+  const bodyJson = JSON.parse(res.body!);
+  assert.equal(bodyJson.operationId, "getInvoice");
+  assert.match(bodyJson.error, /not implemented/);
+});
+
+test("no controller present → back-compat per-op import path still works", async () => {
+  const { router, imported } = build(
+    { spec: "openapi.json" },
+    { "/app/operations/getInvoice": { default: () => ({ body: { ok: true } }) } },
+    // no exists paths → controller absent
+  );
+  const res = await router(req("GET", "/app/api/invoices/9"));
+  assert.equal(res.status, 200);
+  assert.deepEqual(imported, ["/app/operations/getInvoice"]);
+});
+
+test("compiled app: controller.js present (no .ts) → still uses the registry", async () => {
+  // A published / `urban run` build ships controller.js with TS sources absent. Probing only .ts
+  // would wrongly report the registry missing and fall back to per-op imports; probe all extensions.
+  const handler: OperationHandler = () => ({ status: 200, body: { ok: true } });
+  const { router, imported } = build(
+    { spec: "openapi.json" },
+    { "/app/nano-generated/controller": { operations: { getInvoice: handler } } },
+    spec,
+    () => undefined,
+    ["/app/nano-generated/controller.js"], // only the compiled artifact exists on disk
+  );
+  const res = await router(req("GET", "/app/api/invoices/7"));
+  assert.equal(res.status, 200);
+  assert.deepEqual(imported, ["/app/nano-generated/controller"]);
+});

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

@@ -15,6 +15,7 @@
 import type { AppApi, RuntimeContext } from "../context.ts";
 import { errorMessage } from "../guards.ts";
 import type { HttpRequest, HttpResponse } from "../host.ts";
+import { MODULE_EXTENSION_CANDIDATES } from "../module-path.ts";
 import { html, json, normalizeRoutePath, type Route } from "../router.ts";
 import { resolveAppPath } from "./datasource.ts";
 import {
@@ -91,18 +92,24 @@ window.ui = SwaggerUIBundle({ url: ${JSON.stringify(specUrl)}, dom_id: '#swagger
 </html>`;
 }
 
-/** The `{ params, query, body }` contract a typed operation is generic over. */
+/** The `{ params, query, body }` contract a typed operation is generic over. `body` is optional so
+ *  a generated request type for an operation without a required requestBody (its `body?` is
+ *  optional/`undefined`) still satisfies the constraint — see the generated `operations.ts` /
+ *  `controller.ts`, which parameterise `OperationHandler` over the per-op request type. */
 export interface OperationContract {
   params: unknown;
   query: unknown;
-  body: unknown;
+  body?: unknown;
 }
 
-/** The loose contract an untyped delegate sees (strings on the wire; unknown JSON body). */
+/** The loose contract an untyped delegate sees (strings on the wire; unknown JSON body). `body` is
+ *  optional so a raw (untyped) delegate typed `OperationHandler<DefaultContract>` still satisfies the
+ *  generated registry's per-operation `OperationHandler<ReqFor<K>>` slot — an op whose request body
+ *  is optional/absent must be a subtype of the default contract (handler args are contravariant). */
 export interface DefaultContract {
   params: Record<string, string>;
   query: Record<string, string | string[] | undefined>;
-  body: unknown;
+  body?: unknown;
 }
 
 /** The input handed to an operation delegate: the raw request plus the parsed (and, unless ejected,
@@ -127,6 +134,27 @@ export type OperationHandler<Req extends OperationContract = DefaultContract, Re
   app: AppApi,
 ) => Promise<OperationResult<Res> | void> | OperationResult<Res> | void;
 
+/**
+ * Thrown by a write-once operation stub to signal the endpoint exists but has no implementation
+ * yet; the dispatcher maps it to HTTP `501 Not Implemented` (ADR 0059). Delete the throw once you
+ * implement the handler body. A brand property makes the check robust across module realms.
+ */
+export class NotImplemented extends Error {
+  readonly urbanNotImplemented = true as const;
+  constructor(operationId: string) {
+    super(`operation not implemented: ${operationId}`);
+    this.name = "NotImplemented";
+  }
+}
+
+/** True for a `NotImplemented` throw (instanceof, or the brand — resilient to realm/dup-copy). */
+function isNotImplemented(e: unknown): boolean {
+  return (
+    e instanceof NotImplemented ||
+    (typeof e === "object" && e !== null && Reflect.get(e, "urbanNotImplemented") === true)
+  );
+}
+
 /**
  * Typed-identity helper the generated `operations.ts` wrapper re-types per operationId. Authoring:
  * `export default defineOperation("createInvoice", async ({ params, query, body }, app) => { ... })`
@@ -145,6 +173,10 @@ function isFunction(v: unknown): v is OperationHandler {
   return typeof v === "function";
 }
 
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
 /** Resolve an operation delegate from a loaded module: `default` (when a function) else `handler`. */
 export function resolveOperationHandler(mod: Record<string, unknown>): OperationHandler | undefined {
   if (isFunction(mod.default)) return mod.default;
@@ -290,7 +322,8 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
     return docPromise;
   };
 
-  // Lazily import + cache each delegate module, mirroring mountActions.
+  // Lazily import + cache each delegate module, mirroring mountActions. This is the back-compat
+  // fallback for apps without a generated controller registry (see loadController below).
   const moduleCache = new Map<string, Promise<Record<string, unknown>>>();
   const loadModule = (operationId: string): Promise<Record<string, unknown>> => {
     // Defense-in-depth at the import sink: collectOperations already skips unsafe ids, but never
@@ -310,6 +343,43 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
     return pending;
   };
 
+  // Prefer the generated delegate registry (ADR 0059): one statically-typed barrel the toolkit
+  // emits from the spec, so a missing/mismatched/orphan delegate is a `tsc` error, and dispatch is
+  // a deterministic map lookup rather than a per-request path import. Imported ONCE and cached.
+  // Absent (an app that hasn't re-genned) → `null`, and dispatch falls back to `loadModule`. A
+  // present-but-broken controller (a delegate that throws at import) is NOT swallowed — it retries
+  // and surfaces as a 500 with the reason, exactly like a bad delegate does today.
+  let controllerPromise: Promise<Record<string, unknown> | null> | undefined;
+  const loadController = (): Promise<Record<string, unknown> | null> => {
+    if (!controllerPromise) {
+      const rel = "nano-generated/controller";
+      controllerPromise = (async () => {
+        // Probe every supported module extension (compiled .js first, mirroring resolveModulePath),
+        // NOT just `.ts`: a published / `urban run` app ships `controller.js` with the TS sources
+        // absent, and probing only `.ts` there would wrongly report the registry missing and fall
+        // back to per-op dynamic imports — defeating deterministic dispatch in production.
+        let present = false;
+        for (const ext of MODULE_EXTENSION_CANDIDATES) {
+          if (await ctx.host.exists(resolveAppPath(ctx.root, rel + ext))) {
+            present = true;
+            break;
+          }
+        }
+        if (!present) return null;
+        const mod = await ctx.host.importModule(resolveAppPath(ctx.root, rel));
+        const ops = mod.operations;
+        if (!isRecord(ops)) {
+          throw new Error("nano-generated/controller must export an `operations` registry");
+        }
+        return ops;
+      })().catch((e) => {
+        controllerPromise = undefined; // don't cache the failure — let a later request retry
+        throw e;
+      });
+    }
+    return controllerPromise;
+  };
+
   // Build the operation table lazily from the loaded doc (cached).
   let opsPromise: Promise<MountedOp[]> | undefined;
   const loadOps = (): Promise<MountedOp[]> => {
@@ -496,7 +566,21 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
 
     let handler: OperationHandler | undefined;
     try {
-      handler = resolveOperationHandler(await loadModule(op.operationId));
+      const controller = await loadController();
+      if (controller) {
+        // Deterministic dispatch: the generated registry guarantees (at `tsc` time) one delegate
+        // per operationId. A missing/non-function key here means the controller is stale vs the spec.
+        const candidate = controller[op.operationId];
+        if (!isFunction(candidate)) {
+          ctx.host.log("error", "operation not registered in the generated controller (run `urban gen`)", {
+            operationId: op.operationId,
+          });
+          return json({ error: `operation ${op.operationId} is not registered — run \`urban gen\`` }, 500);
+        }
+        handler = candidate;
+      } else {
+        handler = resolveOperationHandler(await loadModule(op.operationId));
+      }
     } catch (e) {
       ctx.host.log("error", "operation delegate failed to load", {
         operationId: op.operationId,
@@ -541,11 +625,14 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
         body: result.body === undefined ? undefined : JSON.stringify(result.body),
       };
     } catch (e) {
+      // A write-once stub (or any delegate) can signal "endpoint exists, not implemented yet" with
+      // a NotImplemented throw → 501, distinct from an unexpected fault (500).
+      if (isNotImplemented(e)) {
+        return json({ error: errorMessage(e), operationId: op.operationId }, 501);
+      }
       return json({ error: errorMessage(e) }, 500);
     }
   };
-
-  // Categorical safety net: any unexpected throw during dispatch — e.g. a malformed spec
   // `pattern` surfacing from validation — becomes a controlled 500 rather than escaping into
   // the host request handler, which has no top-level catch of its own.
   const dispatch = async (req: HttpRequest): Promise<HttpResponse> => {

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

@@ -1,10 +1,11 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { mkdtemp, mkdir, writeFile, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { createNodeHost } from "../adapters/node.ts";
 import { createUrbanApp, resolvePort } from "./runtime.ts";
+import type { SchedulerDeps } from "./modules/scheduler.ts";
 import { runFromEnv } from "../run.ts";
 import { isRecord } from "./guards.ts";
 import type {
@@ -405,3 +406,54 @@ test("treats NANOBPMN_APP_HANDSHAKE other than \"1\" as opt-out", async () => {
     await rm(dir, { recursive: true, force: true });
   }
 });
+
+// A minimal deterministic scheduler seam: records armed timers so a test can assert the
+// injected scheduler — not the live one — drives createUrbanApp's background loops.
+function countingScheduler(): SchedulerDeps & { armed: () => number } {
+  let clock = 0;
+  let armed = 0;
+  return {
+    now: () => clock,
+    setTimer: (_fn, _ms) => {
+      armed += 1;
+      return armed;
+    },
+    clearTimer: () => {},
+    armed: () => armed,
+  };
+}
+
+async function makeTrackingFixture(): Promise<string> {
+  const dir = await makeFixture();
+  const manifestPath = join(dir, "nano.app.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  manifest.instanceTracking = [
+    {
+      table: "crew_tasks",
+      keyField: "id",
+      statusField: "status",
+      activeStatuses: ["claimed"],
+      onTerminated: { set: { status: "abandoned" } },
+      pollMs: 1000,
+    },
+  ];
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+  return dir;
+}
+
+test("threads an injected scheduler into the instance-tracking reconciler loop", async () => {
+  const dir = await makeTrackingFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const sched = countingScheduler();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0, scheduler: sched });
+  try {
+    await app.start();
+    // The reconciler arms its first poll on the injected scheduler, not the live one — so the
+    // whole-app settle loop can drive it deterministically over a virtual clock.
+    assert.ok(sched.armed() >= 1, "injected scheduler armed the reconciler poll");
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/runtime/core/runtime.ts

@@ -18,6 +18,7 @@ import { mountConnectors } from "./modules/connectors.ts";
 import { mountSurfaces } from "./modules/surfaces.ts";
 import { mountTriggers } from "./modules/triggers.ts";
 import { mountInstanceTracking } from "./modules/instance-tracking.ts";
+import type { SchedulerDeps } from "./modules/scheduler.ts";
 import { mountSecurity, type SecurityPolicy } from "./modules/security.ts";
 
 /** Resolve the HTTP port: explicit option, else $PORT, else 8090. Throws a clear
@@ -76,6 +77,15 @@ export interface CreateUrbanAppOptions {
    *  `name → content` map). Merged over the manifest's `models.templates` (this wins on
    *  collision). See `deployModels`. */
   templates?: TemplateSource;
+  /**
+   * Injectable timer + clock seam driving every background loop (the cron trigger loops
+   * and the instance-tracking reconciler). Defaults to the live scheduler (real timers,
+   * wall clock). The e2e test kit injects a manual scheduler so those loops advance
+   * deterministically over a virtual clock — the single seam that makes a whole-app
+   * `settle()` possible. Threaded verbatim into `mountTriggers` and `mountInstanceTracking`
+   * so one injected scheduler drives them both (no per-module wiring, no drift).
+   */
+  scheduler?: SchedulerDeps;
 }
 
 export interface UrbanApp {
@@ -210,13 +220,13 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
           describe.surfaces = s.describe();
         }
         if (flags.triggers) {
-          const t = mountTriggers(ctx, api);
+          const t = mountTriggers(ctx, api, opts.scheduler);
           routes.push(...t.routes);
           mounted.push(t);
           describe.triggers = t.describe?.();
         }
         if (flags.instanceTracking && (manifest.instanceTracking?.length ?? 0) > 0) {
-          const it = mountInstanceTracking(ctx, api);
+          const it = mountInstanceTracking(ctx, api, opts.scheduler);
           mounted.push(it);
           describe.instanceTracking = it.describe?.();
         }

package/src/runtime/index.ts

@@ -87,7 +87,7 @@ export { cancelInstanceReconciling } from "./core/modules/cancel.ts";
 export type { CancelInstanceResult, CancelInstanceState } from "./core/modules/cancel.ts";
 export { mountActions, resolveActionHandler } from "./core/modules/actions.ts";
 export type { ActionHandler, ActionRequest, ActionResult, ActionsHandle } from "./core/modules/actions.ts";
-export { defineOperation, mountApi, resolveOperationHandler } from "./core/modules/api.ts";
+export { defineOperation, mountApi, resolveOperationHandler, NotImplemented } from "./core/modules/api.ts";
 export type {
   ApiBinding,
   ApiHandle,
@@ -119,6 +119,8 @@ export { evalCorrelation } from "./core/modules/triggers.ts";
 export { deployModels } from "./core/modules/deploy.ts";
 export { applyTemplates, resolveTemplates } from "./core/modules/templates.ts";
 export type { TemplateApplication, TemplateSource } from "./core/modules/templates.ts";
+export { defaultScheduler, MAX_TIMER_DELAY_MS } from "./core/modules/scheduler.ts";
+export type { SchedulerDeps } from "./core/modules/scheduler.ts";
 
 // Adapters + engine + run entrypoint
 export { createNodeHost } from "./adapters/node.ts";

package/src/toolkit/api-dir.test.ts

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { DEFAULT_OPERATIONS_DIR, normalizeApiDir } from "./api-dir.ts";
+
+test("normalizeApiDir: empty/whitespace falls back to the default", () => {
+  assert.equal(normalizeApiDir(""), DEFAULT_OPERATIONS_DIR);
+  assert.equal(normalizeApiDir("   "), DEFAULT_OPERATIONS_DIR);
+});
+
+test("normalizeApiDir: strips leading ./ and surrounding slashes, folds backslashes", () => {
+  assert.equal(normalizeApiDir("ops"), "ops");
+  assert.equal(normalizeApiDir("./ops/"), "ops");
+  assert.equal(normalizeApiDir("api\\ops"), "api/ops");
+  assert.equal(normalizeApiDir("nested/ops/"), "nested/ops");
+});
+
+test("normalizeApiDir: rejects absolute POSIX paths", () => {
+  assert.throws(() => normalizeApiDir("/ops"), /app-relative/);
+});
+
+test("normalizeApiDir: rejects absolute Windows paths", () => {
+  assert.throws(() => normalizeApiDir("C:\\ops"), /app-relative/);
+  assert.throws(() => normalizeApiDir("C:/ops"), /app-relative/);
+  assert.throws(() => normalizeApiDir("\\ops"), /app-relative/);
+});
+
+test("normalizeApiDir: rejects .. traversal segments", () => {
+  assert.throws(() => normalizeApiDir("../ops"), /\.\./);
+  assert.throws(() => normalizeApiDir("ops/../escape"), /\.\./);
+  assert.throws(() => normalizeApiDir("a/../../b"), /\.\./);
+});