@nanobpm/urban 0.74.0 → 0.75.0

package/dist/runtime/core/modules/gateway.d.ts

@@ -27,10 +27,17 @@ export interface ForeignKeyMeta {
     refColumn: string;
     onDelete: string;
 }
-/** One table: its columns, index names, and foreign keys. Powers domain-type projection and
- * the page runtime's list/detail binding. */
+/** One introspected datasource object: its columns, index names, and foreign keys. Powers
+ * domain-type projection and the page runtime's list/detail binding. `kind` distinguishes a
+ * base `table` (read/write) from a SQL `view` (read-only): a view is readable through the same
+ * `SELECT * FROM <name>` path as a table, but Urban treats every view as read-only (a plain
+ * SQLite view rejects writes unless someone attaches INSTEAD OF triggers, which Urban never
+ * does), so write surfaces (DB Manager, forms, the domain writer bindings) must not offer
+ * insert/update/delete against a view. */
 export interface TableMeta {
     name: string;
+    /** `table` for a base table (read/write); `view` for a read-only SQL VIEW. */
+    kind: "table" | "view";
     columns: ColumnMeta[];
     indexes: string[];
     foreignKeys: ForeignKeyMeta[];

package/dist/runtime/core/modules/gateway.js

@@ -149,19 +149,30 @@ class SqliteGateway {
         }
     }
     async schema() {
+        // Introspect base tables AND views (`type IN ('table','view')`): the datasource read path
+        // (`SELECT * FROM <name>`) works verbatim on a view, so a page datasource / domain read must
+        // be able to see one. A view is tagged `kind:'view'` below so write surfaces know not to
+        // offer insert/update/delete against it (Urban treats every view as read-only; a plain
+        // SQLite view rejects writes absent INSTEAD OF triggers, which Urban never attaches).
+        //
         // Exclude SQLite internals (`sqlite_%`) and Nano's own bookkeeping tables (`_urban_%` /
-        // `_nano_%`, e.g. the migrations ledger): neither is a user/domain table, so they must
-        // never surface in the domain model, DB Manager, or forms.
-        const tables = this.#db.all("SELECT name FROM sqlite_master WHERE type = 'table' " +
+        // `_nano_%`, e.g. the migrations ledger): neither is a user/domain object, so they must
+        // never surface in the domain model, DB Manager, or forms. The same exclusions apply to
+        // views.
+        const tables = this.#db.all("SELECT name, type FROM sqlite_master WHERE type IN ('table','view') " +
             "AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '\\_urban\\_%' ESCAPE '\\' " +
             "AND name NOT LIKE '\\_nano\\_%' ESCAPE '\\' ORDER BY name");
         const out = [];
         for (const t of tables) {
+            // `PRAGMA table_info(<view>)` returns the view's columns (pk/notnull report 0, which is
+            // correct — a view has no primary key); `PRAGMA index_list` / `foreign_key_list` return
+            // empty for a view (harmless).
             const cols = this.#db.all(`PRAGMA table_info(${quoteIdent(t.name)})`);
             const idx = this.#db.all(`PRAGMA index_list(${quoteIdent(t.name)})`);
             const fks = this.#db.all(`PRAGMA foreign_key_list(${quoteIdent(t.name)})`);
             out.push({
                 name: t.name,
+                kind: t.type === "view" ? "view" : "table",
                 columns: cols.map((c) => ({
                     name: c.name,
                     type: c.type,

package/dist/toolkit/derivers/domain.js

@@ -58,13 +58,17 @@ function fieldType(col) {
     // A NOT NULL column (or the INTEGER PRIMARY KEY rowid alias) is never null.
     return col.notNull || col.primaryKey ? base : `${base} | null`;
 }
-/** One `export interface` block for a table under an explicit interface name. */
+/** One `export interface` block for a table under an explicit interface name. Urban treats a
+ * VIEW as read-only (a plain SQLite view rejects writes absent INSTEAD OF triggers, which Urban
+ * never attaches), so its fields are emitted `readonly` — consumers get typed reads and the
+ * `readonly` modifier signals/guards against mutating the row through the generated type. */
 function tableInterfaceNamed(name, t) {
+    const ro = t.kind === "view" ? "readonly " : "";
     const fields = t.columns
         .map((c) => {
         const key = isIdent(c.name) ? c.name : JSON.stringify(c.name);
         const pk = c.primaryKey ? " (primary key)" : "";
-        return `  /** ${c.type || "?"}${pk} */\n  ${key}: ${fieldType(c)};`;
+        return `  /** ${c.type || "?"}${pk} */\n  ${ro}${key}: ${fieldType(c)};`;
     })
         .join("\n");
     return `export interface ${name} {\n${fields}\n}`;
@@ -206,6 +210,14 @@ const RESERVED_DOMAIN_MEMBERS = new Set(["raw", "close"]);
 function primaryKeyOf(t) {
     return t.columns.find((c) => c.primaryKey)?.name ?? "id";
 }
+/** Urban treats a view as read-only (a plain SQLite view rejects writes absent INSTEAD OF
+ * triggers, which Urban never attaches), so it must not get a `Table<T>` writer binding
+ * in the generated `domain.ts`; its typed row still lives in `domain-rows.d.ts` (read-only) and
+ * stays reachable for reads via `db.raw`. A reserved-named object is dropped too, so it can't
+ * clobber the `raw`/`close` escape hatch. */
+function isWriterBound(t) {
+    return t.kind !== "view" && !RESERVED_DOMAIN_MEMBERS.has(t.name);
+}
 /**
  * Emit `domain.ts`: a typed data-object accessor over the App's default datasource, so a worker
  * writes `db.orders.insert({...})` / `db.orders.get(id)` instead of hand-writing SQL (ADR 0029 §6).
@@ -228,7 +240,7 @@ export function emitDomainBindings(sources, defaultSource) {
         ? defaultSource
         : sources[0]?.source;
     const primary = sources.find((s) => s.source === def);
-    const tables = (primary?.tables ?? []).filter((t) => !RESERVED_DOMAIN_MEMBERS.has(t.name));
+    const tables = (primary?.tables ?? []).filter(isWriterBound);
     // Multi-source apps: emit a *keyed* accessor so `openDomain("analytics")` is typed against that
     // source's tables, not the default's. The row-type spine (`DomainSources`, keyed by alias then
     // wire table name) is already emitted in `domain-rows.d.ts`; here we bind a runtime
@@ -283,7 +295,7 @@ function emitKeyedDomainBindings(header, sources, def) {
     const tableDescriptors = sources
         .map((s) => {
         const rows = s.tables
-            .filter((t) => !RESERVED_DOMAIN_MEMBERS.has(t.name))
+            .filter(isWriterBound)
             .map((t) => `{ name: ${JSON.stringify(t.name)}, pk: ${JSON.stringify(primaryKeyOf(t))} }`)
             .join(", ");
         return `  ${JSON.stringify(s.source)}: [${rows}],`;
@@ -328,6 +340,7 @@ function tableMetaFromType(typeName, def) {
     const { table, columns } = tableSchemaForType(typeName, def);
     return {
         name: table,
+        kind: "table",
         columns: columns.map((c) => ({
             name: c.name,
             type: c.sqlType,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.74.0",
+	"version": "0.75.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",
@@ -101,7 +101,7 @@
 	"dependencies": {
 		"@nanobpm/nano-app-schema": "^0.9.0",
 		"@nanobpm/nano-sdk": "^1.2.5",
-		"@nanobpm/workflow": "^0.13.1",
+		"@nanobpm/workflow": "^0.14.0",
 		"bpmn-auto-layout": "^2.0.0-alpha.2",
 		"create-urban-app": "^0.15.0",
 		"yaml": "^2.9.0"

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

@@ -125,6 +125,99 @@ test("schema introspects columns/pk and excludes internal tables", async () => {
   });
 });
 
+test("schema introspects a VIEW tagged read-only; base tables stay writable", async () => {
+  await withGateway(async (src) => {
+    await src.exec(
+      "INSERT INTO orders (id, status, total) VALUES (1, 'new', 10), (2, 'paid', 20)",
+    );
+    // A derived rollup as a SQL VIEW — the exact "no drift surface" the issue enables.
+    await src.exec(
+      "CREATE VIEW paid_orders AS SELECT id, total FROM orders WHERE status = 'paid'",
+    );
+
+    const meta = await src.schema();
+    const byName = new Map(meta.map((t) => [t.name, t]));
+
+    // Both the base table and the view are introspected…
+    assert.deepEqual(
+      meta.map((t) => t.name),
+      ["orders", "paid_orders"],
+    );
+    // …and tagged so a write surface can tell them apart.
+    assert.equal(byName.get("orders")?.kind, "table");
+    assert.equal(byName.get("paid_orders")?.kind, "view");
+
+    // A view has columns (pk/notnull report 0 — a view has no primary key).
+    const view = byName.get("paid_orders");
+    assert.deepEqual(
+      view?.columns.map((c) => c.name),
+      ["id", "total"],
+    );
+    assert.equal(view?.columns.every((c) => c.primaryKey === false), true);
+  });
+});
+
+test("datasource reads rows from a VIEW with filter and order applied", async () => {
+  interface Paid {
+    id: number;
+    total: number;
+  }
+  await withGateway(async (src) => {
+    await src.exec(
+      "INSERT INTO orders (id, status, total) VALUES " +
+        "(1, 'new', 10), (2, 'paid', 20), (3, 'paid', 5)",
+    );
+    await src.exec(
+      "CREATE VIEW paid_orders AS SELECT id, total FROM orders WHERE status = 'paid'",
+    );
+
+    const view = src.table<Paid>("paid_orders");
+    // The Table read path (`SELECT * FROM <name> …`) works verbatim on a view.
+    const all = await view.all();
+    assert.deepEqual(
+      all.map((r) => r.id).sort(),
+      [2, 3],
+    );
+    // filter (WHERE) applies as normal.
+    const byTotal = await view.find({ total: 20 });
+    assert.deepEqual(byTotal.map((r) => r.id), [2]);
+    // ordered raw read (ORDER BY) applies as normal.
+    const ordered = await src.query<Paid>(
+      "SELECT * FROM paid_orders ORDER BY total ASC",
+    );
+    assert.deepEqual(ordered.map((r) => r.id), [3, 2]);
+  });
+});
+
+test("a base table is writable but a VIEW is not", async () => {
+  await withGateway(async (src) => {
+    await src.exec("INSERT INTO orders (id, status, total) VALUES (1, 'paid', 20)");
+    await src.exec(
+      "CREATE VIEW paid_orders AS SELECT id, total FROM orders WHERE status = 'paid'",
+    );
+
+    // The base table writes fine.
+    const orders = src.table<Order>("orders");
+    const id = await orders.insert({ status: "new", total: 3 });
+    assert.equal(typeof id === "number" || typeof id === "bigint", true);
+
+    // Urban treats every view as read-only (no INSTEAD OF trigger), so a plain view rejects
+    // the write — the write surface must never offer it.
+    const view = src.table<{ id: number; total: number }>("paid_orders");
+    await assert.rejects(() => view.insert({ id: 99, total: 1 }));
+  });
+});
+
+test("schema excludes internal tables AND internal views", async () => {
+  await withGateway(async (src) => {
+    await src.exec("CREATE VIEW _urban_hidden AS SELECT 1 AS x");
+    await src.exec("CREATE VIEW _nano_hidden AS SELECT 1 AS x");
+    await src.exec("CREATE VIEW visible AS SELECT id FROM orders");
+    const names = (await src.schema()).map((t) => t.name);
+    assert.deepEqual(names, ["orders", "visible"]);
+  });
+});
+
 test("query rejects (not throws synchronously) on invalid SQL", async () => {
   await withGateway(async (src) => {
     await assert.rejects(src.query("SELECT * FROM does_not_exist"));

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

@@ -47,10 +47,17 @@ export interface ForeignKeyMeta {
   onDelete: string;
 }
 
-/** One table: its columns, index names, and foreign keys. Powers domain-type projection and
- * the page runtime's list/detail binding. */
+/** One introspected datasource object: its columns, index names, and foreign keys. Powers
+ * domain-type projection and the page runtime's list/detail binding. `kind` distinguishes a
+ * base `table` (read/write) from a SQL `view` (read-only): a view is readable through the same
+ * `SELECT * FROM <name>` path as a table, but Urban treats every view as read-only (a plain
+ * SQLite view rejects writes unless someone attaches INSTEAD OF triggers, which Urban never
+ * does), so write surfaces (DB Manager, forms, the domain writer bindings) must not offer
+ * insert/update/delete against a view. */
 export interface TableMeta {
   name: string;
+  /** `table` for a base table (read/write); `view` for a read-only SQL VIEW. */
+  kind: "table" | "view";
   columns: ColumnMeta[];
   indexes: string[];
   foreignKeys: ForeignKeyMeta[];
@@ -248,16 +255,26 @@ class SqliteGateway implements DataSource {
   }
 
   async schema(): Promise<TableMeta[]> {
+    // Introspect base tables AND views (`type IN ('table','view')`): the datasource read path
+    // (`SELECT * FROM <name>`) works verbatim on a view, so a page datasource / domain read must
+    // be able to see one. A view is tagged `kind:'view'` below so write surfaces know not to
+    // offer insert/update/delete against it (Urban treats every view as read-only; a plain
+    // SQLite view rejects writes absent INSTEAD OF triggers, which Urban never attaches).
+    //
     // Exclude SQLite internals (`sqlite_%`) and Nano's own bookkeeping tables (`_urban_%` /
-    // `_nano_%`, e.g. the migrations ledger): neither is a user/domain table, so they must
-    // never surface in the domain model, DB Manager, or forms.
-    const tables = this.#db.all<{ name: string }>(
-      "SELECT name FROM sqlite_master WHERE type = 'table' " +
+    // `_nano_%`, e.g. the migrations ledger): neither is a user/domain object, so they must
+    // never surface in the domain model, DB Manager, or forms. The same exclusions apply to
+    // views.
+    const tables = this.#db.all<{ name: string; type: string }>(
+      "SELECT name, type FROM sqlite_master WHERE type IN ('table','view') " +
         "AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '\\_urban\\_%' ESCAPE '\\' " +
         "AND name NOT LIKE '\\_nano\\_%' ESCAPE '\\' ORDER BY name",
     );
     const out: TableMeta[] = [];
     for (const t of tables) {
+      // `PRAGMA table_info(<view>)` returns the view's columns (pk/notnull report 0, which is
+      // correct — a view has no primary key); `PRAGMA index_list` / `foreign_key_list` return
+      // empty for a view (harmless).
       const cols = this.#db.all<{ name: string; type: string; notnull: number; pk: number }>(
         `PRAGMA table_info(${quoteIdent(t.name)})`,
       );
@@ -270,6 +287,7 @@ class SqliteGateway implements DataSource {
       }>(`PRAGMA foreign_key_list(${quoteIdent(t.name)})`);
       out.push({
         name: t.name,
+        kind: t.type === "view" ? "view" : "table",
         columns: cols.map((c) => ({
           name: c.name,
           type: c.type,

package/src/toolkit/derivers/bindings-parity.test.ts

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { emitDomainBindings } from "./domain.ts";
+import { emitDomainBindings, type SourceSchema } from "./domain.ts";
 import { emitWorkerBindings, emitWorkerBindingsRuntime } from "./worker-io.ts";
 import { emitMessageBindings, emitMessageBindingsRuntime } from "./messages.ts";
 
@@ -9,12 +9,13 @@ import { emitMessageBindings, emitMessageBindingsRuntime } from "./messages.ts";
 // output to the console byte-for-byte so the two can never drift while both exist.
 const GOLDENS: Record<string, string> = JSON.parse("{\"bindings\":\"// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1/§6).\\n// The typed data-object layer: `openDomain()` → one `Table<T>` per table, so\\n// workers manipulate typed rows instead of hand-writing SQL. Do not edit —\\n// regenerated from the live tables. Erased to plain JS at `deno compile`.\\n// eslint-disable\\n\\nimport { openDataSource, type DataSource, type Table } from \\\"./data-sdk.ts\\\";\\nimport type { Customers, Orders } from \\\"./domain-rows.d.ts\\\";\\n\\nexport interface Domain {\\n  /** The underlying datasource handle — the raw-SQL escape hatch. */\\n  readonly raw: DataSource;\\n  readonly orders: Table<Orders>;\\n  readonly customers: Table<Customers>;\\n  /** Close the underlying connection. */\\n  close(): void;\\n}\\n\\n/**\\n * Open the App's datasource as a typed domain: each table is\\n * a `Table<T>` gateway (`db.orders.insert(...)`, `db.orders.get(id)`), with the\\n * raw `DataSource` at `db.raw` for anything the gateway doesn't cover.\\n */\\nexport async function openDomain(source?: string): Promise<Domain> {\\n  const raw = await openDataSource(source);\\n  return {\\n    raw,\\n    orders: raw.table<Orders>(\\\"orders\\\", \\\"id\\\"),\\n    customers: raw.table<Customers>(\\\"customers\\\", \\\"id\\\"),\\n    close: () => raw.close(),\\n  };\\n}\\n\\nexport type { Table };\\n\",\"workerRuntime\":\"// AUTO-GENERATED by nanobpmn (ADR 0033 §3): the typed `defineWorker`.\\n// Re-exports the worker SDK and overrides `defineWorker` with a taskType-keyed\\n// typed signature (job.variables, job.customHeaders + result typed from the\\n// worker's declared input/output/header contract). Erased to a pass-through at\\n// runtime. Do not edit.\\n// eslint-disable\\n\\nimport { defineWorker as defineWorkerRaw } from \\\"./worker-sdk.ts\\\";\\nimport type { WorkerOptions } from \\\"./worker-sdk.ts\\\";\\nimport type { WorkerInputs, WorkerOutputs, WorkerHeaders, WorkerTaskType, WorkerVars, WorkerHdrs } from \\\"./worker-io.d.ts\\\";\\n\\nexport * from \\\"./worker-sdk.ts\\\";\\n\\ntype InFor<K extends WorkerTaskType> = K extends keyof WorkerInputs ? WorkerInputs[K] : WorkerVars;\\ntype OutFor<K extends WorkerTaskType> = K extends keyof WorkerOutputs ? WorkerOutputs[K] : WorkerVars;\\ntype HdrFor<K extends WorkerTaskType> = K extends keyof WorkerHeaders ? WorkerHeaders[K] : WorkerHdrs;\\n\\n/**\\n * Typed `defineWorker`: `type` is constrained to the model's declared job types\\n * (`WorkerTaskType`, ADR 0033 §3) so it autocompletes and rejects unknown jobs,\\n * and the handler's `job.variables`, `job.customHeaders` + result are typed from\\n * the worker's declared `inputType`/`outputType`/header keys. A declared job type\\n * with no declared type falls back to WorkerVars / WorkerHdrs.\\n */\\nexport function defineWorker<K extends WorkerTaskType>(\\n  opts: { type: K } & WorkerOptions<InFor<K> & object, OutFor<K> & object, HdrFor<K> & object>,\\n): void {\\n  defineWorkerRaw(opts as unknown as WorkerOptions);\\n}\\n\",\"messageRuntime\":\"// AUTO-GENERATED by nanobpmn (ADR 0040 slice 2): the typed `publishMessage`.\\n// Re-exports the worker SDK's `publishMessage` and overrides it with a\\n// messageName-keyed typed signature (variables typed from the message's declared\\n// envelope). Erased to a pass-through at runtime. Do not edit.\\n// eslint-disable\\n\\nimport { publishMessage as publishMessageRaw } from \\\"./worker-sdk.ts\\\";\\nimport type { PublishMessageOptions, PublishMessageResult } from \\\"./worker-sdk.ts\\\";\\nimport type { MessageName, MessagePayloads, MessageVars } from \\\"./message-io.d.ts\\\";\\n\\nexport type { PublishMessageOptions, PublishMessageResult } from \\\"./worker-sdk.ts\\\";\\n\\ntype PayloadFor<K extends MessageName> = K extends keyof MessagePayloads ? MessagePayloads[K] : MessageVars;\\n\\n/**\\n * Typed `publishMessage`: `name` is constrained to the model's declared message\\n * names (`MessageName`, ADR 0040 slice 2) so it autocompletes and rejects unknown\\n * messages, and `variables` are typed from the message's declared envelope. A\\n * declared message with no domain type falls back to MessageVars.\\n */\\nexport function publishMessage<K extends MessageName>(\\n  name: K,\\n  opts?: PublishMessageOptions<PayloadFor<K> & object>,\\n): Promise<PublishMessageResult> {\\n  return publishMessageRaw(name, opts as unknown as PublishMessageOptions);\\n}\\n\",\"workerBindingsWithHeaders\":\"// AUTO-GENERATED by nanobpmn from the App manifest (ADR 0033 §3).\\n// The bridge from the process model to the worker type system: each declared\\n// worker's `taskType` maps to the TS type of its input payload (`job.variables`)\\n// and result, so the typed `defineWorker` types a handler by its job type. Do\\n// not edit — regenerated from the manifest. Erased to plain JS at compile.\\n// eslint-disable\\n\\nimport type { DomainTypes } from \\\"./domain-rows.d.ts\\\";\\n\\n/** Untyped fallback for a job whose worker declares no input/output type. */\\nexport type WorkerVars = Record<string, unknown>;\\n\\n/** Untyped fallback for a job whose worker declares no custom headers. */\\nexport type WorkerHdrs = Record<string, unknown>;\\n\\n/** Every declared worker `taskType` (ADR 0033 §3): the model-derived set the\\n * typed `defineWorker` accepts, so `type` autocompletes and rejects unknown jobs. */\\nexport type WorkerTaskType = \\\"review\\\";\\n\\n/** Input payload (`job.variables`) per declared worker, keyed by `taskType`. */\\nexport interface WorkerInputs {\\n  \\\"review\\\": DomainTypes[\\\"Order\\\"];\\n}\\n\\n/** Output payload (worker result) per declared worker, keyed by `taskType`. */\\nexport interface WorkerOutputs {\\n  \\\"review\\\": DomainTypes[\\\"Order\\\"];\\n}\\n\\n/** Custom headers (`job.customHeaders`) per declared worker, keyed by `taskType`.\\n * Header values are strings on the wire, so each declared key maps to `string`;\\n * the extra index signature keeps undeclared headers accessible (non-breaking). */\\nexport interface WorkerHeaders {\\n  \\\"review\\\": { \\\"priority\\\": string; \\\"x-flag\\\": string; [key: string]: string };\\n}\\n\",\"messageBindings\":\"// AUTO-GENERATED by nanobpmn from the process model (ADR 0040 slice 2).\\n// The bridge from a `bpmn:message`'s data envelope to the message type system:\\n// each named message maps to the TS type of its payload, so the typed\\n// `publishMessage` types a call by its message name. Do not edit — regenerated\\n// from the model. Erased to plain JS at compile.\\n// eslint-disable\\n\\nimport type { DomainTypes } from \\\"./domain-rows.d.ts\\\";\\n\\n/** Untyped fallback payload for a message that declares no envelope type. */\\nexport type MessageVars = Record<string, unknown>;\\n\\n/** Every declared message `name` (ADR 0040 slice 2): the model-derived set the\\n * typed `publishMessage` accepts, so `name` autocompletes and rejects unknown messages. */\\nexport type MessageName = \\\"approved\\\";\\n\\n/** Payload (`variables`) per declared message, keyed by `name`. */\\nexport interface MessagePayloads {\\n  \\\"approved\\\": DomainTypes[\\\"Order\\\"];\\n}\\n\"}\n");
 
-const sources = [
+const sources: SourceSchema[] = [
   {
     source: "app",
     tables: [
       {
         name: "orders",
+        kind: "table",
         columns: [
           { name: "id", type: "INTEGER", notNull: true, primaryKey: true },
           { name: "total", type: "INTEGER", notNull: true, primaryKey: false },
@@ -24,6 +25,7 @@ const sources = [
       },
       {
         name: "customers",
+        kind: "table",
         columns: [
           { name: "id", type: "INTEGER", notNull: true, primaryKey: true },
           { name: "name", type: "TEXT", notNull: true, primaryKey: false },

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

@@ -3,6 +3,7 @@ import assert from "node:assert/strict";
 import {
   emitDomainModel,
   emitDomain,
+  emitDomainBindings,
   deriveDomain,
   sourcesFromManifest,
   registryFromManifest,
@@ -20,7 +21,7 @@ const GOLDENS: Record<string, string> = JSON.parse("{\n  \"empty\": \"// AUTO-GE
 
 const col = (name: string, type: string, notNull: boolean, primaryKey: boolean) =>
   ({ name, type, notNull, primaryKey });
-const table = (name: string, cols: TableMeta["columns"]): TableMeta => ({ name, columns: cols, indexes: [], foreignKeys: [] });
+const table = (name: string, cols: TableMeta["columns"], kind: TableMeta["kind"] = "table"): TableMeta => ({ name, kind, columns: cols, indexes: [], foreignKeys: [] });
 
 test("emitDomainModel: empty app → bare DomainTables (byte-parity)", () => {
   assert.equal(emitDomainModel([], undefined, {}), GOLDENS.empty);
@@ -58,6 +59,37 @@ test("emitDomainModel: multi-source → DomainSources + DomainTables alias to de
   assert.equal(emitDomainModel(sources, "analytics", {}), GOLDENS.multi);
 });
 
+test("emitDomainModel: a VIEW yields a read-only row interface (readonly fields)", () => {
+  // The datasource read path works verbatim on a view, so consumers still get a typed row —
+  // but Urban treats every view as read-only (it never attaches INSTEAD OF triggers), so its
+  // fields are emitted `readonly`.
+  const sources: SourceSchema[] = [{ source: "app", tables: [
+    table("orders", [col("id","INTEGER",false,true), col("total","INTEGER",true,false)]),
+    table("paid_orders", [col("id","INTEGER",false,false), col("total","INTEGER",false,false)], "view"),
+  ]}];
+  const out = emitDomainModel(sources, "app", {});
+  // A base table stays writable (non-readonly fields).
+  assert.match(out, /export interface Orders \{\n {2}\/\*\* INTEGER \(primary key\) \*\/\n {2}id: number;/);
+  // The view's row interface is entirely read-only.
+  assert.match(out, /export interface PaidOrders \{\n {2}\/\*\* INTEGER \*\/\n {2}readonly id: number \| null;\n {2}\/\*\* INTEGER \*\/\n {2}readonly total: number \| null;\n\}/);
+  // Both appear in the DomainTables lookup — a view is a readable object.
+  assert.match(out, /"paid_orders": PaidOrders;/);
+});
+
+test("emitDomainBindings: a VIEW gets NO Table<T> writer binding; base tables do", () => {
+  const sources: SourceSchema[] = [{ source: "app", tables: [
+    table("orders", [col("id","INTEGER",false,true), col("total","INTEGER",true,false)]),
+    table("paid_orders", [col("id","INTEGER",false,false), col("total","INTEGER",false,false)], "view"),
+  ]}];
+  const bindings = emitDomainBindings(sources, "app");
+  // The base table gets a typed Table<T> gateway (insert/update/delete available).
+  assert.match(bindings, /readonly orders: Table<Orders>;/);
+  assert.match(bindings, /orders: raw\.table<Orders>\("orders", "id"\),/);
+  // The view is NOT offered a writer binding — it never appears as a Table<T> field or bind.
+  assert.equal(bindings.includes("paid_orders"), false);
+  assert.equal(bindings.includes("PaidOrders"), false);
+});
+
 // --- manifest bridge: code-first derivation reproduces the console output --------------------
 
 test("emitDomain: manifest types drive BOTH the table spine and the registry (byte-parity)", () => {

package/src/toolkit/derivers/domain.ts

@@ -76,13 +76,17 @@ function fieldType(col: ColumnMeta): string {
   return col.notNull || col.primaryKey ? base : `${base} | null`;
 }
 
-/** One `export interface` block for a table under an explicit interface name. */
+/** One `export interface` block for a table under an explicit interface name. Urban treats a
+ * VIEW as read-only (a plain SQLite view rejects writes absent INSTEAD OF triggers, which Urban
+ * never attaches), so its fields are emitted `readonly` — consumers get typed reads and the
+ * `readonly` modifier signals/guards against mutating the row through the generated type. */
 function tableInterfaceNamed(name: string, t: TableMeta): string {
+  const ro = t.kind === "view" ? "readonly " : "";
   const fields = t.columns
     .map((c) => {
       const key = isIdent(c.name) ? c.name : JSON.stringify(c.name);
       const pk = c.primaryKey ? " (primary key)" : "";
-      return `  /** ${c.type || "?"}${pk} */\n  ${key}: ${fieldType(c)};`;
+      return `  /** ${c.type || "?"}${pk} */\n  ${ro}${key}: ${fieldType(c)};`;
     })
     .join("\n");
   return `export interface ${name} {\n${fields}\n}`;
@@ -276,6 +280,15 @@ function primaryKeyOf(t: TableMeta): string {
   return t.columns.find((c) => c.primaryKey)?.name ?? "id";
 }
 
+/** Urban treats a view as read-only (a plain SQLite view rejects writes absent INSTEAD OF
+ * triggers, which Urban never attaches), so it must not get a `Table<T>` writer binding
+ * in the generated `domain.ts`; its typed row still lives in `domain-rows.d.ts` (read-only) and
+ * stays reachable for reads via `db.raw`. A reserved-named object is dropped too, so it can't
+ * clobber the `raw`/`close` escape hatch. */
+function isWriterBound(t: TableMeta): boolean {
+  return t.kind !== "view" && !RESERVED_DOMAIN_MEMBERS.has(t.name);
+}
+
 /**
  * Emit `domain.ts`: a typed data-object accessor over the App's default datasource, so a worker
  * writes `db.orders.insert({...})` / `db.orders.get(id)` instead of hand-writing SQL (ADR 0029 §6).
@@ -303,9 +316,7 @@ export function emitDomainBindings(
     ? defaultSource
     : sources[0]?.source;
   const primary = sources.find((s) => s.source === def);
-  const tables = (primary?.tables ?? []).filter(
-    (t) => !RESERVED_DOMAIN_MEMBERS.has(t.name),
-  );
+  const tables = (primary?.tables ?? []).filter(isWriterBound);
 
   // Multi-source apps: emit a *keyed* accessor so `openDomain("analytics")` is typed against that
   // source's tables, not the default's. The row-type spine (`DomainSources`, keyed by alias then
@@ -375,7 +386,7 @@ function emitKeyedDomainBindings(
   const tableDescriptors = sources
     .map((s) => {
       const rows = s.tables
-        .filter((t) => !RESERVED_DOMAIN_MEMBERS.has(t.name))
+        .filter(isWriterBound)
         .map((t) =>
           `{ name: ${JSON.stringify(t.name)}, pk: ${JSON.stringify(primaryKeyOf(t))} }`
         )
@@ -431,6 +442,7 @@ function tableMetaFromType(typeName: string, def: ToolkitType): TableMeta {
   const { table, columns } = tableSchemaForType(typeName, def);
   return {
     name: table,
+    kind: "table",
     columns: columns.map((c) => ({
       name: c.name,
       type: c.sqlType,

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

@@ -20,6 +20,7 @@ test("emitDomainModelJson fuses tables, manifest types, shapes, and metadata", (
         tables: [
           {
             name: "orders",
+            kind: "table",
             columns: [{ name: "id", type: "INTEGER", notNull: true, primaryKey: true }],
             indexes: [],
             foreignKeys: [],
@@ -121,6 +122,7 @@ test("resolveShapes treats a qualified-alias carry of the colliding leaf as comp
       tables: [
         {
           name: "orders",
+          kind: "table",
           columns: [{ name: "id", type: "INTEGER", notNull: true, primaryKey: true }],
           indexes: [],
           foreignKeys: [],