@nanobpm/urban 0.17.0 → 0.18.0

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

@@ -0,0 +1,140 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { deriveMeta, emitMeta, foldMeta, scanModelMeta, type MetaDecl } from "./meta.ts";
+
+// Goldens captured byte-for-byte from the console's canonical `emitMeta`
+// (server/src/console/domain_types.ts) so this port is provably a drop-in (ADR 0053).
+const HEADER =
+  "// AUTO-GENERATED by nanobpmn from the process model (ADR 0040 §5): the typed\n" +
+  "// model-metadata accessor. Each `nano:meta` key/value the models declare becomes\n" +
+  "// a checked `AppMeta` property, so `meta(key)` is typed and app-wide queryable\n" +
+  "// without a second store. Do not edit — regenerated from the model.\n" +
+  "// eslint-disable\n\n" +
+  "/** Every model-level metadata key the App's models declare (ADR 0040 §5). */\n";
+const ACCESSOR =
+  "\n/** Read a model-level metadata value. A declared key is typed; a dynamic key\n" +
+  " * returns `string | undefined`. */\n" +
+  "export function meta<K extends keyof AppMeta>(key: K): AppMeta[K];\n" +
+  "export function meta(key: string): string | undefined;\n" +
+  "export function meta(key: string): string | undefined {\n" +
+  "  return (appMeta as Record<string, string>)[key];\n" +
+  "}\n";
+
+const GOLDEN_EMPTY = HEADER +
+  "export interface AppMeta {}\n\n" +
+  "export const appMeta: AppMeta = Object.create(null) as AppMeta;\n" +
+  ACCESSOR;
+
+const GOLDEN_MULTI = HEADER +
+  "export interface AppMeta {\n  classification: string;\n  owner: string;\n}\n\n" +
+  "export const appMeta: AppMeta = (() => {\n" +
+  "  const m: Record<string, string> = Object.create(null);\n" +
+  '  m["classification"] = "internal";\n' +
+  '  m["owner"] = "ops";\n' +
+  "  return m as AppMeta;\n})();\n" +
+  ACCESSOR;
+
+const GOLDEN_NONIDENT = HEADER +
+  'export interface AppMeta {\n  "data-classification": string;\n}\n\n' +
+  "export const appMeta: AppMeta = (() => {\n" +
+  "  const m: Record<string, string> = Object.create(null);\n" +
+  '  m["data-classification"] = "pii";\n' +
+  "  return m as AppMeta;\n})();\n" +
+  ACCESSOR;
+
+const GOLDEN_PROTO = HEADER +
+  "export interface AppMeta {\n  __proto__: string;\n}\n\n" +
+  "export const appMeta: AppMeta = (() => {\n" +
+  "  const m: Record<string, string> = Object.create(null);\n" +
+  '  m["__proto__"] = "danger";\n' +
+  "  return m as AppMeta;\n})();\n" +
+  ACCESSOR;
+
+test("emitMeta emits the empty accessor byte-for-byte (matches console)", () => {
+  assert.equal(emitMeta([]), GOLDEN_EMPTY);
+});
+
+test("emitMeta emits declared keys in scan order byte-for-byte (matches console)", () => {
+  const metas: MetaDecl[] = [
+    { process: "Proc_a", key: "classification", value: "internal" },
+    { process: "Proc_a", key: "owner", value: "ops" },
+  ];
+  assert.equal(emitMeta(metas), GOLDEN_MULTI);
+});
+
+test("emitMeta quotes non-identifier keys byte-for-byte (matches console)", () => {
+  assert.equal(emitMeta([{ key: "data-classification", value: "pii" }]), GOLDEN_NONIDENT);
+});
+
+test("emitMeta handles a literal __proto__ key via a null-prototype dict (matches console)", () => {
+  assert.equal(emitMeta([{ key: "__proto__", value: "danger" }]), GOLDEN_PROTO);
+});
+
+test("foldMeta: last declaration of a key wins; empty keys are dropped", () => {
+  const folded = foldMeta([
+    { key: "env", value: "staging" },
+    { key: "  ", value: "ignored" },
+    { key: "env", value: "prod" },
+  ]);
+  assert.equal(folded.env, "prod");
+  assert.deepEqual(Object.keys(folded), ["env"]);
+});
+
+const XML = `<?xml version="1.0"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
+                  xmlns:nano="https://nanobpm.io/schema/shapes/1.0">
+  <bpmn:process id="orders" isExecutable="true">
+    <bpmn:extensionElements>
+      <nano:shapes><nano:shape id="S"><nano:carry ref="Order" /></nano:shape></nano:shapes>
+      <nano:meta key="classification" value="internal" />
+      <nano:meta key="owner" value="ops" />
+    </bpmn:extensionElements>
+  </bpmn:process>
+</bpmn:definitions>`;
+
+test("scanModelMeta lifts nano:meta siblings in document order, tagged with the process", () => {
+  assert.deepEqual(scanModelMeta(XML), [
+    { process: "orders", key: "classification", value: "internal" },
+    { process: "orders", key: "owner", value: "ops" },
+  ]);
+});
+
+test("scanModelMeta does not mistake a shape's op children for model meta", () => {
+  const xml = `<bpmn:process id="p"><bpmn:extensionElements>
+    <nano:shapes><nano:shape id="S">
+      <nano:carry ref="Order" />
+      <nano:extend name="approved" type="boolean" />
+    </nano:shape></nano:shapes>
+  </bpmn:extensionElements></bpmn:process>`;
+  assert.deepEqual(scanModelMeta(xml), []);
+});
+
+test("scanModelMeta ignores a meta with no key; a missing value folds to empty string", () => {
+  const xml = `<bpmn:process id="p"><bpmn:extensionElements>
+    <nano:meta value="orphan" />
+    <nano:meta key="flag" />
+  </bpmn:extensionElements></bpmn:process>`;
+  assert.deepEqual(scanModelMeta(xml), [{ process: "p", key: "flag", value: "" }]);
+});
+
+test("deriveMeta is deterministic and emits nano-generated/meta.ts", () => {
+  const models = [{ path: "processes/orders.bpmn", xml: XML }];
+  const a1 = deriveMeta(models);
+  const a2 = deriveMeta(models);
+  assert.deepEqual(a1, a2);
+  assert.equal(a1[0].path, "nano-generated/meta.ts");
+  assert.equal(a1[0].content, GOLDEN_MULTI);
+});
+
+test("deriveMeta folds across models in path order (last write wins)", () => {
+  const mk = (id: string, v: string) =>
+    `<bpmn:process id="${id}"><bpmn:extensionElements><nano:meta key="env" value="${v}" /></bpmn:extensionElements></bpmn:process>`;
+  // Provided out of path order; the deriver sorts by path so `b.bpmn` (prod) wins.
+  const models = [
+    { path: "processes/b.bpmn", xml: mk("b", "prod") },
+    { path: "processes/a.bpmn", xml: mk("a", "staging") },
+  ];
+  const content = deriveMeta(models)[0].content;
+  assert.match(content, /m\["env"\] = "prod";/);
+  assert.doesNotMatch(content, /"staging"/);
+});

package/src/toolkit/derivers/meta.ts

@@ -0,0 +1,128 @@
+// Deriver: BPMN models → `meta.ts`, the typed model-metadata accessor (`@nanobpm/meta`,
+// ADR 0040 §5). Scans each process for `nano:meta` key/value siblings of the `nano:shapes`
+// container and folds them into a single app-wide record. It emits the SAME `meta.ts` the
+// console generates (a faithful port of `foldMeta`/`emitMeta` in the server's domain_types.ts),
+// so the toolkit is a drop-in for the IDE's codegen (ADR 0053).
+
+import type { DerivedArtifact, Deriver } from "../artifact.ts";
+import { GENERATED_DIR } from "../artifact.ts";
+import { byModelPath, type ModelSource } from "./worker-io.ts";
+
+/** Basename the console uses for the generated accessor; kept identical (drop-in). */
+export const META_TS = "meta.ts";
+
+/** One model-level metadata entry (`nano:meta`), tagged with its defining process for
+ * the `model:<processId>` provenance (ADR 0040 §5). `process` is carried for the fuse;
+ * the emitted `meta.ts` folds on key/value only. */
+export interface MetaDecl {
+  process?: string;
+  key: string;
+  value: string;
+}
+
+function attr(tag: string, name: string): string | undefined {
+  const m = tag.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`));
+  return m ? m[1] : undefined;
+}
+
+function processId(xml: string): string | undefined {
+  const m = xml.match(/<[\w.-]*:?process\b[^>]*>/);
+  return m ? attr(m[0], "id") : undefined;
+}
+
+// A `nano:shape` carrier (`<...:shape>…</...:shape>`, and self-closing) — meta is only
+// recognised *outside* a shape carrier (its op children, e.g. `extend`, are a different
+// vocabulary), so strip carriers before matching `nano:meta` (mirrors envelope_scan.rs).
+const SHAPE_BLOCK_RE = /<([\w.-]*:)?shape\b[^>]*(?:\/>|>[\s\S]*?<\/\1?shape\s*>)/g;
+// A `nano:meta` element (any namespace prefix; matches the Rust local-name scan).
+const META_RE = /<([\w.-]*:)?meta\b([^>]*?)\/?>/g;
+
+/** Scan one BPMN document for model-level `nano:meta` key/value entries, in document
+ * order, tagged with the enclosing process. A meta with no `key` attribute is ignored;
+ * a missing `value` folds to the empty string (matches envelope_scan.rs). */
+export function scanModelMeta(xml: string): MetaDecl[] {
+  const proc = processId(xml);
+  const withoutShapes = xml.replace(SHAPE_BLOCK_RE, "");
+  const out: MetaDecl[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = META_RE.exec(withoutShapes)) !== null) {
+    const key = attr(`<x ${m[2]}>`, "key");
+    if (key == null) continue;
+    out.push({ process: proc, key, value: attr(`<x ${m[2]}>`, "value") ?? "" });
+  }
+  return out;
+}
+
+// --- Faithful port of the console's foldMeta/emitMeta (domain_types.ts) so the emitted
+//     meta.ts is byte-compatible with the IDE's own codegen. ---
+
+function isIdent(name: string): boolean {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name);
+}
+
+/** Fold the scanned model-level metadata into a single key→value record. When two models
+ * declare the same key the last (scan order) wins. Empty keys are ignored. The accumulator
+ * is a **null-prototype** dict so user-authored keys (including `__proto__`) round-trip
+ * deterministically as own data properties. */
+export function foldMeta(metas: MetaDecl[]): Record<string, string> {
+  const out: Record<string, string> = Object.create(null);
+  for (const m of metas) {
+    const key = (m?.key ?? "").trim();
+    if (!key) continue;
+    out[key] = m.value ?? "";
+  }
+  return out;
+}
+
+/** Emit `meta.ts`: the typed model-metadata accessor (`@nanobpm/meta`, ADR 0040 §5).
+ * `AppMeta` keys the declared metadata as string-literal properties; `appMeta` is the
+ * concrete null-prototype record; the overloaded `meta()` returns the typed value for a
+ * known key and `string | undefined` for a dynamic one. Strip-safe (ADR 0036). */
+export function emitMeta(metas: MetaDecl[]): string {
+  const folded = foldMeta(metas);
+  const keys = Object.keys(folded);
+  const propKey = (k: string) => (isIdent(k) ? k : JSON.stringify(k));
+  const header =
+    "// AUTO-GENERATED by nanobpmn from the process model (ADR 0040 §5): the typed\n" +
+    "// model-metadata accessor. Each `nano:meta` key/value the models declare becomes\n" +
+    "// a checked `AppMeta` property, so `meta(key)` is typed and app-wide queryable\n" +
+    "// without a second store. Do not edit — regenerated from the model.\n" +
+    "// eslint-disable\n\n";
+  const iface = keys.length > 0
+    ? `export interface AppMeta {\n${keys.map((k) => `  ${propKey(k)}: string;`).join("\n")}\n}\n`
+    : `export interface AppMeta {}\n`;
+  const constDecl = keys.length > 0
+    ? `export const appMeta: AppMeta = (() => {\n` +
+      `  const m: Record<string, string> = Object.create(null);\n` +
+      keys.map((k) => `  m[${JSON.stringify(k)}] = ${JSON.stringify(folded[k])};`).join("\n") +
+      `\n  return m as AppMeta;\n})();\n`
+    : `export const appMeta: AppMeta = Object.create(null) as AppMeta;\n`;
+  const accessor =
+    `\n/** Read a model-level metadata value. A declared key is typed; a dynamic key\n` +
+    ` * returns \`string | undefined\`. */\n` +
+    `export function meta<K extends keyof AppMeta>(key: K): AppMeta[K];\n` +
+    `export function meta(key: string): string | undefined;\n` +
+    `export function meta(key: string): string | undefined {\n` +
+    `  return (appMeta as Record<string, string>)[key];\n` +
+    `}\n`;
+  return `${header}/** Every model-level metadata key the App's models declare (ADR 0040 §5). */\n` +
+    iface + "\n" + constDecl + accessor;
+}
+
+/**
+ * Derive `nano-generated/meta.ts` from BPMN models. Deterministic: models are scanned in
+ * path order, then their `nano:meta` entries folded (last write wins) into the accessor.
+ */
+export function deriveMeta(models: ModelSource[]): DerivedArtifact[] {
+  const metas: MetaDecl[] = [];
+  for (const model of [...models].sort(byModelPath)) {
+    metas.push(...scanModelMeta(model.xml));
+  }
+  return [{ path: `${GENERATED_DIR}/${META_TS}`, content: emitMeta(metas) }];
+}
+
+export const metaDeriver: Deriver<{ models: ModelSource[] }> = {
+  id: "model->meta",
+  describe: "Derive meta.ts (the typed @nanobpm/meta accessor) from BPMN nano:meta entries.",
+  derive: ({ models }) => deriveMeta(models),
+};

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

@@ -1,6 +1,8 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
+import { DatabaseSync } from "node:sqlite";
 import { createTableSql, deriveMigrations, sqlType } from "./migrations.ts";
+import { deriveDomain } from "./domain.ts";
 
 test("sqlType maps domain types to SQLite affinities", () => {
   assert.equal(sqlType("string"), "TEXT");
@@ -17,10 +19,10 @@ test("createTableSql emits id PK, NOT NULL by default, nullable when optional",
     table: "greetings",
     fields: { who: { type: "string" }, when: { type: "datetime", optional: true } },
   });
-  assert.match(sql, /CREATE TABLE IF NOT EXISTS greetings/);
-  assert.match(sql, /id INTEGER PRIMARY KEY AUTOINCREMENT/);
-  assert.match(sql, /who TEXT NOT NULL/);
-  assert.match(sql, /when TEXT(?! NOT NULL)/);
+  assert.match(sql, /CREATE TABLE IF NOT EXISTS "greetings"/);
+  assert.match(sql, /"id" INTEGER PRIMARY KEY AUTOINCREMENT/);
+  assert.match(sql, /"who" TEXT NOT NULL/);
+  assert.match(sql, /"when" TEXT(?! NOT NULL)/);
 });
 
 test("createTableSql rejects a reserved 'id' field and non-identifier names", () => {
@@ -48,3 +50,39 @@ test("deriveMigrations groups by datasource and is deterministic", () => {
   const paths = a1.map((x) => x.path).sort();
   assert.deepEqual(paths, ["nano-generated/app.schema.sql", "nano-generated/audit.schema.sql"]);
 });
+
+// #88: reserved-word table/column names (e.g. `order`, `group`) are valid SQL identifiers
+// only when quoted. Guard the defect class — not just `order` — by executing the derived DDL
+// against a real SQLite engine, so any unquoted reserved identifier fails here, not at runtime.
+test("createTableSql quotes identifiers so reserved-word names produce executable DDL", () => {
+  const sql = createTableSql("order", {
+    fields: { group: { type: "string" }, select: { type: "int", optional: true } },
+  });
+  // Identifiers are double-quoted.
+  assert.match(sql, /CREATE TABLE IF NOT EXISTS "order"/);
+  assert.match(sql, /"group" TEXT NOT NULL/);
+  assert.match(sql, /"select" INTEGER(?! NOT NULL)/);
+  // And the DDL actually executes against a real SQLite engine.
+  const db = new DatabaseSync(":memory:");
+  try {
+    assert.doesNotThrow(() => db.exec(sql), "derived DDL must execute against node:sqlite");
+  } finally {
+    db.close();
+  }
+});
+
+// #88 companion: the domain deriver keys `DomainTables` off the raw wire name via
+// JSON.stringify, so a reserved-word type name still resolves as a string-literal key.
+test("deriveDomain keeps reserved-word table names addressable in DomainTables", () => {
+  const [artifact] = deriveDomain({
+    data: { default: "app" },
+    types: { order: { fields: { group: { type: "string" } } } },
+  });
+  // Anchor to the DomainTables interface specifically — DomainTypes also emits an
+  // "order" key, so a bare /"order":/ would pass even if the DomainTables spine regressed.
+  assert.match(
+    artifact.content,
+    /export interface DomainTables \{\s*"order":/,
+    'DomainTables["order"] must resolve',
+  );
+});

package/src/toolkit/derivers/migrations.ts

@@ -8,6 +8,8 @@ import { GENERATED_DIR } from "../artifact.ts";
 export interface ToolkitField {
   type?: string;
   optional?: boolean;
+  /** Marks a repeated field: the domain row-type projects it as `T[]` in the `DomainTypes` registry. */
+  list?: boolean;
 }
 export interface ToolkitType {
   table?: string;
@@ -52,27 +54,59 @@ export function assertSqlIdent(kind: string, name: string): string {
   return name;
 }
 
-/** Build the CREATE TABLE statement for one type. */
-export function createTableSql(typeName: string, def: ToolkitType): string {
+/** Double-quote an identifier for DDL. `assertSqlIdent` already rejects non-identifier
+ * chars (the injection guard), but quoting is what makes valid-but-reserved words
+ * (`order`, `group`, `select`, …) legal SQL — no reserved-word denylist to maintain.
+ * Embedded double quotes are doubled per the SQL standard (defensive; can't occur here). */
+export function quoteSqlIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+/** A column in a manifest type's canonical table schema. `sqlType` is the SQLite
+ * declared type (the affinity source for both the CREATE TABLE and the row types). */
+export interface DerivedColumn {
+  name: string;
+  sqlType: string;
+  notNull: boolean;
+  primaryKey: boolean;
+}
+
+/** The canonical table schema for one manifest type. */
+export interface DerivedTable {
+  table: string;
+  columns: DerivedColumn[];
+}
+
+/**
+ * Derive the canonical table schema for one manifest type: an implicit
+ * autoincrement `id` primary key plus one column per declared field. This is the
+ * single source of truth both the SQL migration (`createTableSql`) and the domain
+ * row-types (`domain.ts`) derive from, so the schema can never drift between them.
+ */
+export function tableSchemaForType(typeName: string, def: ToolkitType): DerivedTable {
   const table = assertSqlIdent("table name", def.table ?? typeName);
-  const cols: string[] = ["  id INTEGER PRIMARY KEY AUTOINCREMENT"];
+  const columns: DerivedColumn[] = [
+    { name: "id", sqlType: "INTEGER", notNull: false, primaryKey: true },
+  ];
   const fields = def.fields ?? {};
   for (const [name, f] of Object.entries(fields)) {
     assertSqlIdent("field name", name);
     if (name === "id") {
       throw new Error(`type "${typeName}": field "id" is reserved (the table's implicit primary key)`);
     }
-    const notNull = f.optional ? "" : " NOT NULL";
-    cols.push(`  ${name} ${sqlType(f.type)}${notNull}`);
+    columns.push({ name, sqlType: sqlType(f.type), notNull: !f.optional, primaryKey: false });
   }
-  return `CREATE TABLE IF NOT EXISTS ${table} (\n${cols.join(",\n")}\n);`;
+  return { table, columns };
 }
 
-export function deriveMigrations(manifest: ToolkitManifest): DerivedArtifact[] {
+/** Group manifest types by their datasource, preserving declaration order within each
+ * source. Shared by the migrations and domain derivers so both partition and order
+ * sources identically (a single source of truth for the source spine). */
+export function groupTypesBySource(
+  manifest: ToolkitManifest,
+): Map<string, Array<[string, ToolkitType]>> {
   const types = manifest.types ?? {};
   const defaultSource = manifest.data?.default ?? "app";
-
-  // Group types by their datasource.
   const bySource = new Map<string, Array<[string, ToolkitType]>>();
   for (const [name, def] of Object.entries(types)) {
     const src = def.source ?? defaultSource;
@@ -80,6 +114,24 @@ export function deriveMigrations(manifest: ToolkitManifest): DerivedArtifact[] {
     list.push([name, def]);
     bySource.set(src, list);
   }
+  return bySource;
+}
+
+/** Build the CREATE TABLE statement for one type, from its canonical schema. Table and
+ * column identifiers are quoted so valid-but-reserved names (`order`, `group`, …) emit
+ * legal SQL. */
+export function createTableSql(typeName: string, def: ToolkitType): string {
+  const { table, columns } = tableSchemaForType(typeName, def);
+  const cols = columns.map((c) =>
+    c.primaryKey
+      ? `  ${quoteSqlIdent(c.name)} ${c.sqlType} PRIMARY KEY AUTOINCREMENT`
+      : `  ${quoteSqlIdent(c.name)} ${c.sqlType}${c.notNull ? " NOT NULL" : ""}`
+  );
+  return `CREATE TABLE IF NOT EXISTS ${quoteSqlIdent(table)} (\n${cols.join(",\n")}\n);`;
+}
+
+export function deriveMigrations(manifest: ToolkitManifest): DerivedArtifact[] {
+  const bySource = groupTypesBySource(manifest);
 
   const artifacts: DerivedArtifact[] = [];
   for (const [src, list] of bySource) {

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

@@ -4,9 +4,19 @@ import {
   deriveWorkerBindings,
   emitWorkerBindings,
   scanModelWorkers,
+  byModelPath,
   type WorkerIo,
 } from "./worker-io.ts";
 
+test("byModelPath is a spec-compliant comparator: returns 0 for equal paths", () => {
+  assert.equal(byModelPath({ path: "a" }, { path: "a" }), 0);
+  assert.equal(byModelPath({ path: "a" }, { path: "b" }), -1);
+  assert.equal(byModelPath({ path: "b" }, { path: "a" }), 1);
+  // Antisymmetry (the property the old `? -1 : 1` form violated for equal paths).
+  const eq = [{ path: "x" }, { path: "x" }];
+  assert.equal(byModelPath(eq[0], eq[1]) + byModelPath(eq[1], eq[0]), 0);
+});
+
 const XML = `<?xml version="1.0"?>
 <bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
                   xmlns:zeebe="http://camunda.org/schema/zeebe/1.0">

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

@@ -13,6 +13,15 @@ export interface ModelSource {
   xml: string;
 }
 
+/** Deterministic comparator for ordering `ModelSource` lists by path. Returns 0 on equal
+ * paths so it satisfies the JS sort contract (a comparator that reports both `a>b` and
+ * `b>a` can reorder equal elements unpredictably) — keeping the derivers' cross-model
+ * fold order stable even if a manifest pattern yields duplicate paths. Shared by every
+ * model-scanning deriver so there is one canonical ordering. */
+export function byModelPath(a: { path: string }, b: { path: string }): number {
+  return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+}
+
 export interface WorkerIo {
   taskType: string;
   elementId?: string;
@@ -73,7 +82,10 @@ export function scanModelWorkers(xml: string): WorkerIo[] {
 // --- Faithful port of the console's emitWorkerBindings (domain_types.ts) so the emitted
 //     worker-io.d.ts is byte-compatible with the IDE's own codegen. ---
 
-function typeRefFor(id: string | undefined, declared: Set<string>): string | undefined {
+/** A `DomainTypes[...]` ref for a declared type id (else undefined). The one canonical
+ * ref helper shared by the worker- and message-IO emitters (matches the console's single
+ * `typeRefFor` in domain_types.ts), so both stay identical to the host codegen. */
+export function typeRefFor(id: string | undefined, declared: Set<string>): string | undefined {
   return id != null && declared.has(id) ? `DomainTypes[${JSON.stringify(id)}]` : undefined;
 }
 
@@ -160,7 +172,7 @@ export function deriveWorkerBindings(
   declaredTypeIds: Iterable<string> = [],
 ): DerivedArtifact[] {
   const workers: WorkerBindingDecl[] = [];
-  for (const model of [...models].sort((a, b) => (a.path < b.path ? -1 : 1))) {
+  for (const model of [...models].sort(byModelPath)) {
     for (const w of scanModelWorkers(model.xml)) {
       workers.push({ taskType: w.taskType, inputType: w.in, outputType: w.out });
     }

package/src/toolkit/fsio.test.ts

@@ -19,3 +19,26 @@ test("listDir returns empty for a missing directory", async () => {
   const io = createNodeGenIO();
   assert.deepEqual(await io.listDir(join(tmpdir(), "urban-fsio-does-not-exist-xyz")), []);
 });
+
+test("importModule caches on mtime: unchanged reuses, edit reloads", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "urban-fsio-imp-"));
+  const file = join(dir, "mod.mjs");
+  await writeFile(file, "export const v = 1;");
+  const io = createNodeGenIO();
+
+  const first = await io.importModule!(file);
+  assert.equal(first.v, 1);
+  // Same mtime → same module URL → cached instance (same object identity).
+  const again = await io.importModule!(file);
+  assert.equal(again, first);
+
+  // Edit with a strictly newer mtime → new URL → fresh module with the new value.
+  await new Promise((r) => setTimeout(r, 10));
+  await writeFile(file, "export const v = 2;");
+  const utimes = (await import("node:fs/promises")).utimes;
+  const t = Date.now() / 1000 + 5;
+  await utimes(file, t, t);
+  const edited = await io.importModule!(file);
+  assert.equal(edited.v, 2);
+  assert.notEqual(edited, first);
+});

package/src/toolkit/fsio.ts

@@ -1,8 +1,9 @@
 // Node/Deno filesystem implementation of the GenIO port. Uses node:fs/promises, which both
 // Node and Deno provide, so a single implementation serves both runtimes.
 
-import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import type { GenIO } from "./gen.ts";
 
 export function createNodeGenIO(): GenIO {
@@ -32,5 +33,24 @@ export function createNodeGenIO(): GenIO {
         return false;
       }
     },
+    async remove(path: string): Promise<void> {
+      await rm(path, { force: true });
+    },
+    // Import an app module for code-first model derivation. `import()` of a file URL loads TS on
+    // Deno natively and on Node with type-stripping (≥22.18 default, or `--experimental-strip-types`).
+    // The cache key is the file's mtime, not a monotonic clock: an unchanged workflow reuses the
+    // cached module instance (bounding the ESM module map in long-lived processes like `urban dev`)
+    // while an edited one still reloads.
+    async importModule(path: string): Promise<Record<string, unknown>> {
+      const abs = resolve(path);
+      let version = "";
+      try {
+        version = `?v=${(await stat(abs)).mtimeMs}`;
+      } catch {
+        // 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>>;
+    },
   };
 }