@nanobpm/urban 0.5.1 → 0.6.0

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

@@ -1,6 +1,7 @@
 import type { RuntimeContext } from "../context.ts";
 import type { SqliteDb } from "../host.ts";
 import type { DomainType } from "../manifest.ts";
+import { Table, type DataSource as GatewayDataSource } from "./gateway.ts";
 /** A typed accessor over a table declared in manifest `types`. */
 export declare class TypeRepo {
     private readonly db;
@@ -20,6 +21,8 @@ export interface ProvisionedSource {
     readonly name: string;
     readonly driver: string;
     readonly db: SqliteDb;
+    /** The record-oriented gateway over this source — the RAD `Table<T>` surface (ADR 0055). */
+    readonly source: GatewayDataSource;
     readonly migrationsApplied: string[];
     close(): void;
 }
@@ -31,6 +34,12 @@ export declare class DataLayer {
     source(name?: string): ProvisionedSource;
     /** A typed accessor for a declared domain type (uses the default source). */
     repo(typeName: string, sourceName?: string): TypeRepo;
+    /** The record-oriented `DataSource` gateway for a source (the default when omitted) — the
+     * raw-SQL + `Table<T>` surface app handlers bind to (ADR 0055). */
+    open(sourceName?: string): GatewayDataSource;
+    /** A typed `Table<T>` gateway over one table on a source (the default when omitted). `pk` is
+     * the primary-key column (default "id"). */
+    table<T extends object = Record<string, unknown>>(name: string, pk?: string, sourceName?: string): Table<T>;
     describe(): Record<string, unknown>;
     closeAll(): void;
 }

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

@@ -2,6 +2,7 @@
 // `types` domain model. Only the `sqlite` driver is implemented; other drivers hit an
 // explicit seam (they are declared in the manifest but not yet provisioned). This is the
 // runtime side of ADR 0024 (datasource) + ADR 0040 (domain model), scoped to what an app needs.
+import { makeGateway } from "./gateway.js";
 function sqlitePathFromUrl(url) {
     // Accept "file:./x.db", "file:x.db", "sqlite:./x.db" or a bare path.
     return url.replace(/^(file|sqlite):(\/\/)?/, "");
@@ -93,6 +94,16 @@ export class DataLayer {
             throw new Error(`no such type "${typeName}"`);
         return new TypeRepo(this.source(sourceName).db, typeName, def);
     }
+    /** The record-oriented `DataSource` gateway for a source (the default when omitted) — the
+     * raw-SQL + `Table<T>` surface app handlers bind to (ADR 0055). */
+    open(sourceName) {
+        return this.source(sourceName).source;
+    }
+    /** A typed `Table<T>` gateway over one table on a source (the default when omitted). `pk` is
+     * the primary-key column (default "id"). */
+    table(name, pk, sourceName) {
+        return this.open(sourceName).table(name, pk);
+    }
     describe() {
         return {
             default: this.defaultSource,
@@ -153,6 +164,7 @@ async function provisionSqlite(ctx, name, src) {
         name,
         driver: "sqlite",
         db,
+        source: makeGateway(db),
         migrationsApplied,
         close: () => db.close(),
     };

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

@@ -0,0 +1,79 @@
+import type { SqliteDb } from "../host.ts";
+export type Row = Record<string, unknown>;
+export interface ExecResult {
+    /** Rows changed by an INSERT/UPDATE/DELETE. */
+    changed: number;
+    /** Rowid of the last inserted row, when the driver reports one. */
+    lastInsertId?: number | bigint;
+}
+/** One column of a table, from the datasource's introspected schema. */
+export interface ColumnMeta {
+    name: string;
+    type: string;
+    notNull: boolean;
+    primaryKey: boolean;
+}
+/** One foreign-key constraint: `column` references `refTable(refColumn)`. `refColumn` is empty
+ * when the FK targets the parent's primary key without naming a column; `onDelete` is the
+ * referential action (e.g. `CASCADE`), empty when none was declared. */
+export interface ForeignKeyMeta {
+    column: string;
+    refTable: string;
+    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. */
+export interface TableMeta {
+    name: string;
+    columns: ColumnMeta[];
+    indexes: string[];
+    foreignKeys: ForeignKeyMeta[];
+}
+/** The one thin, uniform interface behind every driver (ADR 0024 §2) — the `TDataSet`
+ * equivalent. Every consumer shares exactly this surface, so the driver underneath is
+ * interchangeable. */
+export interface DataSource {
+    /** Run a SELECT (or any row-returning statement) and collect the rows. */
+    query(sql: string, params?: unknown[]): Promise<Row[]>;
+    /** Run a non-row statement (INSERT/UPDATE/DELETE/DDL). */
+    exec(sql: string, params?: unknown[]): Promise<ExecResult>;
+    /** Run `fn` inside a transaction, committing on success and rolling back on throw. The
+     * handle passed to `fn` targets the same connection. */
+    tx<T>(fn: (t: DataSource) => Promise<T>): Promise<T>;
+    /** Introspect the datasource's tables/columns/indexes/foreign keys. */
+    schema(): Promise<TableMeta[]>;
+    /** A typed gateway over one table — the RAD "TTable". `pk` is the primary-key column
+     * (default "id"). */
+    table<T extends object = Row>(name: string, pk?: string): Table<T>;
+}
+/** A typed gateway over a single table — the record-oriented data object a handler binds to
+ * instead of hand-writing SQL (the Delphi `TTable`/data-module idea, ADR 0029 §6). It builds
+ * parameterised SQL from a typed row object's own keys, so callers manipulate rows as records.
+ * `T` comes from a generated row type; this class is generic *runtime* and knows nothing about
+ * any specific schema. `pk` is the primary-key column (default `id`). */
+export declare class Table<T extends object = Row> {
+    #private;
+    readonly name: string;
+    readonly pk: string;
+    constructor(src: DataSource, name: string, pk?: string);
+    /** Insert one row (only the present keys are written); returns the new primary-key value
+     * (the inserted rowid for an INTEGER PRIMARY KEY). */
+    insert(row: Partial<T>): Promise<number | bigint>;
+    /** Fetch the row with the given primary key, or `undefined`. */
+    get(id: unknown): Promise<T | undefined>;
+    /** Every row (optionally capped at `limit`). */
+    all(limit?: number): Promise<T[]>;
+    /** Rows matching an equality filter (keys ANDed). An empty filter matches all rows. */
+    find(where?: Partial<T>): Promise<T[]>;
+    /** The first row matching an equality filter, or `undefined`. */
+    findOne(where?: Partial<T>): Promise<T | undefined>;
+    /** Patch the row with the given primary key; returns rows changed. */
+    update(id: unknown, patch: Partial<T>): Promise<number>;
+    /** Delete the row with the given primary key; returns rows changed. */
+    delete(id: unknown): Promise<number>;
+    /** Count rows matching an equality filter (all rows when omitted). */
+    count(where?: Partial<T>): Promise<number>;
+}
+/** Wrap a provisioned `SqliteDb` as the record-oriented `DataSource` gateway. */
+export declare function makeGateway(db: SqliteDb): DataSource;

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

@@ -0,0 +1,169 @@
+// The record-oriented datasource gateway (ADR 0024 / ADR 0029 §6, ADR 0055 phase 1).
+//
+// This is the runtime port of the console-generated `data-sdk.ts` `DataSource` + `Table<T>`:
+// the RAD "TTable" a handler binds to instead of hand-writing SQL. It sits on the runtime's
+// synchronous `SqliteDb` host seam but keeps the *async* app-facing contract (every method
+// returns a Promise), so an app-hosted worker/action/surface handler reaches typed records the
+// same way regardless of which driver backs the source underneath.
+//
+//   const db = app.data.open();                 // the default source as a DataSource
+//   await db.exec("INSERT INTO orders(id) VALUES (?)", [id]);
+//   const orders = db.table<Order>("orders");   // a typed gateway over one table
+//   await orders.insert({ id, status: "new" });
+//   const o = await orders.get(id);
+function quoteIdent(name) {
+    return `"${name.replaceAll('"', '""')}"`;
+}
+/** Build a parameterised ` WHERE a = ? AND b = ?` clause from an equality map; an empty map
+ * yields an empty clause (matches all rows). Takes `object` (not `Row`) so a `Partial<T>` for a
+ * generated `interface` row type (which lacks a string index signature) is accepted. */
+function whereClause(where) {
+    const w = where;
+    const keys = Object.keys(w);
+    if (keys.length === 0)
+        return { clause: "", params: [] };
+    const clause = " WHERE " + keys.map((k) => `${quoteIdent(k)} = ?`).join(" AND ");
+    return { clause, params: keys.map((k) => w[k]) };
+}
+/** A typed gateway over a single table — the record-oriented data object a handler binds to
+ * instead of hand-writing SQL (the Delphi `TTable`/data-module idea, ADR 0029 §6). It builds
+ * parameterised SQL from a typed row object's own keys, so callers manipulate rows as records.
+ * `T` comes from a generated row type; this class is generic *runtime* and knows nothing about
+ * any specific schema. `pk` is the primary-key column (default `id`). */
+export class Table {
+    name;
+    pk;
+    #src;
+    constructor(src, name, pk = "id") {
+        this.#src = src;
+        this.name = name;
+        this.pk = pk;
+    }
+    /** Insert one row (only the present keys are written); returns the new primary-key value
+     * (the inserted rowid for an INTEGER PRIMARY KEY). */
+    async insert(row) {
+        const keys = Object.keys(row);
+        if (keys.length === 0) {
+            throw new Error(`Table(${this.name}).insert: no columns to insert`);
+        }
+        const cols = keys.map(quoteIdent).join(", ");
+        const ph = keys.map(() => "?").join(", ");
+        const r = await this.#src.exec(`INSERT INTO ${quoteIdent(this.name)} (${cols}) VALUES (${ph})`, keys.map((k) => row[k]));
+        if (r.lastInsertId == null) {
+            // The driver reported no rowid — treat as a failed/ambiguous insert rather than
+            // silently returning 0, which a caller could mistake for a real primary key.
+            throw new Error(`Table(${this.name}).insert: driver reported no lastInsertId`);
+        }
+        return r.lastInsertId;
+    }
+    /** Fetch the row with the given primary key, or `undefined`. */
+    async get(id) {
+        const rows = await this.#src.query(`SELECT * FROM ${quoteIdent(this.name)} WHERE ${quoteIdent(this.pk)} = ? LIMIT 1`, [id]);
+        return rows[0];
+    }
+    /** Every row (optionally capped at `limit`). */
+    async all(limit) {
+        const lim = typeof limit === "number" && Number.isFinite(limit)
+            ? ` LIMIT ${Math.max(0, Math.floor(limit))}`
+            : "";
+        return (await this.#src.query(`SELECT * FROM ${quoteIdent(this.name)}${lim}`));
+    }
+    /** Rows matching an equality filter (keys ANDed). An empty filter matches all rows. */
+    async find(where = {}) {
+        const { clause, params } = whereClause(where);
+        return (await this.#src.query(`SELECT * FROM ${quoteIdent(this.name)}${clause}`, params));
+    }
+    /** The first row matching an equality filter, or `undefined`. */
+    async findOne(where = {}) {
+        const { clause, params } = whereClause(where);
+        const rows = await this.#src.query(`SELECT * FROM ${quoteIdent(this.name)}${clause} LIMIT 1`, params);
+        return rows[0];
+    }
+    /** Patch the row with the given primary key; returns rows changed. */
+    async update(id, patch) {
+        const keys = Object.keys(patch);
+        if (keys.length === 0)
+            return 0;
+        const set = keys.map((k) => `${quoteIdent(k)} = ?`).join(", ");
+        const r = await this.#src.exec(`UPDATE ${quoteIdent(this.name)} SET ${set} WHERE ${quoteIdent(this.pk)} = ?`, [...keys.map((k) => patch[k]), id]);
+        return r.changed;
+    }
+    /** Delete the row with the given primary key; returns rows changed. */
+    async delete(id) {
+        const r = await this.#src.exec(`DELETE FROM ${quoteIdent(this.name)} WHERE ${quoteIdent(this.pk)} = ?`, [id]);
+        return r.changed;
+    }
+    /** Count rows matching an equality filter (all rows when omitted). */
+    async count(where = {}) {
+        const { clause, params } = whereClause(where);
+        const rows = await this.#src.query(`SELECT COUNT(*) AS n FROM ${quoteIdent(this.name)}${clause}`, params);
+        return Number(rows[0]?.n ?? 0);
+    }
+}
+/** A `DataSource` implemented over the runtime's synchronous `SqliteDb` host seam. The methods
+ * are async to hold the app-facing contract; the work underneath is synchronous. */
+class SqliteGateway {
+    #db;
+    constructor(db) {
+        this.#db = db;
+    }
+    async query(sql, params = []) {
+        return this.#db.all(sql, params);
+    }
+    async exec(sql, params = []) {
+        const r = this.#db.run(sql, params);
+        return { changed: Number(r.changes), lastInsertId: r.lastInsertRowid };
+    }
+    async tx(fn) {
+        this.#db.exec("BEGIN");
+        try {
+            const out = await fn(this);
+            this.#db.exec("COMMIT");
+            return out;
+        }
+        catch (e) {
+            this.#db.exec("ROLLBACK");
+            throw e;
+        }
+    }
+    async schema() {
+        // 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' " +
+            "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) {
+            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,
+                columns: cols.map((c) => ({
+                    name: c.name,
+                    type: c.type,
+                    notNull: !!c.notnull,
+                    primaryKey: !!c.pk,
+                })),
+                indexes: idx.map((i) => String(i.name)),
+                foreignKeys: fks.map((f) => ({
+                    column: f.from,
+                    refTable: f.table,
+                    refColumn: f.to ?? "",
+                    onDelete: f.on_delete && f.on_delete.toUpperCase() !== "NO ACTION"
+                        ? f.on_delete.toUpperCase()
+                        : "",
+                })),
+            });
+        }
+        return out;
+    }
+    table(name, pk = "id") {
+        return new Table(this, name, pk);
+    }
+}
+/** Wrap a provisioned `SqliteDb` as the record-oriented `DataSource` gateway. */
+export function makeGateway(db) {
+    return new SqliteGateway(db);
+}

package/dist/runtime/index.d.ts

@@ -8,6 +8,8 @@ export type { EngineClient, EngineJob, HostContext, HttpHandler, HttpRequest, Ht
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";
 export type { ProvisionedSource } from "./core/modules/datasource.ts";
+export { makeGateway, Table } from "./core/modules/gateway.ts";
+export type { ColumnMeta, DataSource as GatewayDataSource, ExecResult, ForeignKeyMeta, Row, TableMeta, } from "./core/modules/gateway.ts";
 export type { AppJobHandler } from "./core/modules/workers.ts";
 export { resolveHandler } from "./core/modules/workers.ts";
 export { evalCorrelation } from "./core/modules/triggers.ts";

package/dist/runtime/index.js

@@ -7,6 +7,7 @@ export { expandEnv, expandEnvString, loadManifest, parseManifest, workerJobType,
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.js";
 // Data layer
 export { DataLayer, TypeRepo } from "./core/modules/datasource.js";
+export { makeGateway, Table } from "./core/modules/gateway.js";
 export { resolveHandler } from "./core/modules/workers.js";
 export { evalCorrelation } from "./core/modules/triggers.js";
 // Adapters + engine + run entrypoint

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.5.1",
+  "version": "0.6.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",

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

@@ -6,6 +6,7 @@
 import type { RuntimeContext } from "../context.ts";
 import type { HostContext, SqliteDb } from "../host.ts";
 import type { AppManifest, DataSource, DomainType } from "../manifest.ts";
+import { makeGateway, Table, type DataSource as GatewayDataSource } from "./gateway.ts";
 
 function sqlitePathFromUrl(url: string): string {
   // Accept "file:./x.db", "file:x.db", "sqlite:./x.db" or a bare path.
@@ -89,6 +90,8 @@ export interface ProvisionedSource {
   readonly name: string;
   readonly driver: string;
   readonly db: SqliteDb;
+  /** The record-oriented gateway over this source — the RAD `Table<T>` surface (ADR 0055). */
+  readonly source: GatewayDataSource;
   readonly migrationsApplied: string[];
   close(): void;
 }
@@ -123,6 +126,22 @@ export class DataLayer {
     return new TypeRepo(this.source(sourceName).db, typeName, def);
   }
 
+  /** The record-oriented `DataSource` gateway for a source (the default when omitted) — the
+   * raw-SQL + `Table<T>` surface app handlers bind to (ADR 0055). */
+  open(sourceName?: string): GatewayDataSource {
+    return this.source(sourceName).source;
+  }
+
+  /** A typed `Table<T>` gateway over one table on a source (the default when omitted). `pk` is
+   * the primary-key column (default "id"). */
+  table<T extends object = Record<string, unknown>>(
+    name: string,
+    pk?: string,
+    sourceName?: string,
+  ): Table<T> {
+    return this.open(sourceName).table<T>(name, pk);
+  }
+
   describe(): Record<string, unknown> {
     return {
       default: this.defaultSource,
@@ -198,6 +217,7 @@ async function provisionSqlite(
     name,
     driver: "sqlite",
     db,
+    source: makeGateway(db),
     migrationsApplied,
     close: () => db.close(),
   };

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

@@ -0,0 +1,164 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createNodeHost } from "../../adapters/node.ts";
+import { makeGateway, Table, type DataSource } from "./gateway.ts";
+
+interface Order {
+  id: number;
+  status: string;
+  total: number;
+}
+
+async function withGateway(fn: (src: DataSource) => Promise<void>): Promise<void> {
+  const dir = await mkdtemp(join(tmpdir(), "urban-gateway-"));
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const db = host.openSqlite(join(dir, "test.db"));
+  db.exec(
+    "CREATE TABLE orders (id INTEGER PRIMARY KEY, status TEXT NOT NULL, total INTEGER NOT NULL DEFAULT 0)",
+  );
+  try {
+    await fn(makeGateway(db));
+  } finally {
+    db.close();
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+test("Table insert/get returns the row by primary key", async () => {
+  await withGateway(async (src) => {
+    const orders = src.table<Order>("orders");
+    const id = await orders.insert({ status: "new", total: 10 });
+    const row = await orders.get(id);
+    assert.equal(row?.status, "new");
+    assert.equal(row?.total, 10);
+    assert.equal(Number(row?.id), Number(id));
+  });
+});
+
+test("Table update patches and returns rows changed", async () => {
+  await withGateway(async (src) => {
+    const orders = src.table<Order>("orders");
+    const id = await orders.insert({ status: "new", total: 10 });
+    const changed = await orders.update(id, { status: "shipped" });
+    assert.equal(changed, 1);
+    assert.equal((await orders.get(id))?.status, "shipped");
+  });
+});
+
+test("Table find/findOne filter by equality", async () => {
+  await withGateway(async (src) => {
+    const orders = src.table<Order>("orders");
+    await orders.insert({ status: "new", total: 1 });
+    await orders.insert({ status: "new", total: 2 });
+    await orders.insert({ status: "done", total: 3 });
+    const news = await orders.find({ status: "new" });
+    assert.equal(news.length, 2);
+    const one = await orders.findOne({ status: "done" });
+    assert.equal(one?.total, 3);
+    assert.equal(await orders.findOne({ status: "missing" }), undefined);
+  });
+});
+
+test("Table count respects the filter", async () => {
+  await withGateway(async (src) => {
+    const orders = src.table<Order>("orders");
+    await orders.insert({ status: "new", total: 1 });
+    await orders.insert({ status: "done", total: 2 });
+    assert.equal(await orders.count(), 2);
+    assert.equal(await orders.count({ status: "new" }), 1);
+  });
+});
+
+test("Table all lists rows and honours limit", async () => {
+  await withGateway(async (src) => {
+    const orders = src.table<Order>("orders");
+    await orders.insert({ status: "a", total: 1 });
+    await orders.insert({ status: "b", total: 2 });
+    assert.equal((await orders.all()).length, 2);
+    assert.equal((await orders.all(1)).length, 1);
+  });
+});
+
+test("Table delete removes the row", async () => {
+  await withGateway(async (src) => {
+    const orders = src.table<Order>("orders");
+    const id = await orders.insert({ status: "new", total: 1 });
+    assert.equal(await orders.delete(id), 1);
+    assert.equal(await orders.get(id), undefined);
+  });
+});
+
+test("tx commits on success and rolls back on throw", async () => {
+  await withGateway(async (src) => {
+    const orders = src.table<Order>("orders");
+    await src.tx(async (t) => {
+      await t.exec("INSERT INTO orders (status, total) VALUES (?, ?)", ["tx", 5]);
+    });
+    assert.equal(await orders.count({ status: "tx" }), 1);
+
+    await assert.rejects(
+      src.tx(async (t) => {
+        await t.exec("INSERT INTO orders (status, total) VALUES (?, ?)", ["bad", 9]);
+        throw new Error("boom");
+      }),
+      /boom/,
+    );
+    assert.equal(await orders.count({ status: "bad" }), 0);
+  });
+});
+
+test("schema introspects columns/pk and excludes internal tables", async () => {
+  await withGateway(async (src) => {
+    await src.exec("CREATE TABLE _urban_migrations (id TEXT PRIMARY KEY)");
+    await src.exec("CREATE TABLE _nano_ledger (id TEXT PRIMARY KEY)");
+    const meta = await src.schema();
+    const names = meta.map((t) => t.name);
+    assert.deepEqual(names, ["orders"]);
+    const orders = meta[0];
+    const idCol = orders.columns.find((c) => c.name === "id");
+    assert.equal(idCol?.primaryKey, true);
+    const statusCol = orders.columns.find((c) => c.name === "status");
+    assert.equal(statusCol?.notNull, true);
+  });
+});
+
+test("query rejects (not throws synchronously) on invalid SQL", async () => {
+  await withGateway(async (src) => {
+    await assert.rejects(src.query("SELECT * FROM does_not_exist"));
+    await assert.rejects(src.exec("INSERT INTO does_not_exist (x) VALUES (1)"));
+  });
+});
+
+test("Table.insert throws when the driver reports no lastInsertId", async () => {
+  const fake: DataSource = {
+    query: async () => [],
+    exec: async () => ({ changed: 1 }),
+    tx: async (fn) => fn(fake),
+    schema: async () => [],
+    table: (name, pk) => new Table(fake, name, pk),
+  };
+  const t = fake.table("orders");
+  await assert.rejects(t.insert({ status: "x" } as Record<string, unknown>), /no lastInsertId/);
+});
+
+test("Table.all ignores a non-finite limit", async () => {
+  await withGateway(async (src) => {
+    const orders = src.table<Order>("orders");
+    await orders.insert({ status: "a", total: 1 });
+    await orders.insert({ status: "b", total: 2 });
+    assert.equal((await orders.all(Number.NaN)).length, 2);
+    assert.equal((await orders.all(Number.POSITIVE_INFINITY)).length, 2);
+  });
+});
+
+test("query/exec run raw parameterised SQL", async () => {
+  await withGateway(async (src) => {
+    const r = await src.exec("INSERT INTO orders (status, total) VALUES (?, ?)", ["raw", 42]);
+    assert.equal(r.changed, 1);
+    const rows = await src.query("SELECT total FROM orders WHERE status = ?", ["raw"]);
+    assert.equal(Number((rows[0] as { total: number }).total), 42);
+  });
+});

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

@@ -0,0 +1,273 @@
+// The record-oriented datasource gateway (ADR 0024 / ADR 0029 §6, ADR 0055 phase 1).
+//
+// This is the runtime port of the console-generated `data-sdk.ts` `DataSource` + `Table<T>`:
+// the RAD "TTable" a handler binds to instead of hand-writing SQL. It sits on the runtime's
+// synchronous `SqliteDb` host seam but keeps the *async* app-facing contract (every method
+// returns a Promise), so an app-hosted worker/action/surface handler reaches typed records the
+// same way regardless of which driver backs the source underneath.
+//
+//   const db = app.data.open();                 // the default source as a DataSource
+//   await db.exec("INSERT INTO orders(id) VALUES (?)", [id]);
+//   const orders = db.table<Order>("orders");   // a typed gateway over one table
+//   await orders.insert({ id, status: "new" });
+//   const o = await orders.get(id);
+
+import type { SqliteDb } from "../host.ts";
+
+export type Row = Record<string, unknown>;
+
+export interface ExecResult {
+  /** Rows changed by an INSERT/UPDATE/DELETE. */
+  changed: number;
+  /** Rowid of the last inserted row, when the driver reports one. */
+  lastInsertId?: number | bigint;
+}
+
+/** One column of a table, from the datasource's introspected schema. */
+export interface ColumnMeta {
+  name: string;
+  type: string;
+  notNull: boolean;
+  primaryKey: boolean;
+}
+
+/** One foreign-key constraint: `column` references `refTable(refColumn)`. `refColumn` is empty
+ * when the FK targets the parent's primary key without naming a column; `onDelete` is the
+ * referential action (e.g. `CASCADE`), empty when none was declared. */
+export interface ForeignKeyMeta {
+  column: string;
+  refTable: string;
+  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. */
+export interface TableMeta {
+  name: string;
+  columns: ColumnMeta[];
+  indexes: string[];
+  foreignKeys: ForeignKeyMeta[];
+}
+
+/** The one thin, uniform interface behind every driver (ADR 0024 §2) — the `TDataSet`
+ * equivalent. Every consumer shares exactly this surface, so the driver underneath is
+ * interchangeable. */
+export interface DataSource {
+  /** Run a SELECT (or any row-returning statement) and collect the rows. */
+  query(sql: string, params?: unknown[]): Promise<Row[]>;
+  /** Run a non-row statement (INSERT/UPDATE/DELETE/DDL). */
+  exec(sql: string, params?: unknown[]): Promise<ExecResult>;
+  /** Run `fn` inside a transaction, committing on success and rolling back on throw. The
+   * handle passed to `fn` targets the same connection. */
+  tx<T>(fn: (t: DataSource) => Promise<T>): Promise<T>;
+  /** Introspect the datasource's tables/columns/indexes/foreign keys. */
+  schema(): Promise<TableMeta[]>;
+  /** A typed gateway over one table — the RAD "TTable". `pk` is the primary-key column
+   * (default "id"). */
+  table<T extends object = Row>(name: string, pk?: string): Table<T>;
+}
+
+function quoteIdent(name: string): string {
+  return `"${name.replaceAll('"', '""')}"`;
+}
+
+/** Build a parameterised ` WHERE a = ? AND b = ?` clause from an equality map; an empty map
+ * yields an empty clause (matches all rows). Takes `object` (not `Row`) so a `Partial<T>` for a
+ * generated `interface` row type (which lacks a string index signature) is accepted. */
+function whereClause(where: object): { clause: string; params: unknown[] } {
+  const w = where as Row;
+  const keys = Object.keys(w);
+  if (keys.length === 0) return { clause: "", params: [] };
+  const clause = " WHERE " + keys.map((k) => `${quoteIdent(k)} = ?`).join(" AND ");
+  return { clause, params: keys.map((k) => w[k]) };
+}
+
+/** A typed gateway over a single table — the record-oriented data object a handler binds to
+ * instead of hand-writing SQL (the Delphi `TTable`/data-module idea, ADR 0029 §6). It builds
+ * parameterised SQL from a typed row object's own keys, so callers manipulate rows as records.
+ * `T` comes from a generated row type; this class is generic *runtime* and knows nothing about
+ * any specific schema. `pk` is the primary-key column (default `id`). */
+export class Table<T extends object = Row> {
+  readonly name: string;
+  readonly pk: string;
+  readonly #src: DataSource;
+
+  constructor(src: DataSource, name: string, pk = "id") {
+    this.#src = src;
+    this.name = name;
+    this.pk = pk;
+  }
+
+  /** Insert one row (only the present keys are written); returns the new primary-key value
+   * (the inserted rowid for an INTEGER PRIMARY KEY). */
+  async insert(row: Partial<T>): Promise<number | bigint> {
+    const keys = Object.keys(row);
+    if (keys.length === 0) {
+      throw new Error(`Table(${this.name}).insert: no columns to insert`);
+    }
+    const cols = keys.map(quoteIdent).join(", ");
+    const ph = keys.map(() => "?").join(", ");
+    const r = await this.#src.exec(
+      `INSERT INTO ${quoteIdent(this.name)} (${cols}) VALUES (${ph})`,
+      keys.map((k) => (row as Row)[k]),
+    );
+    if (r.lastInsertId == null) {
+      // The driver reported no rowid — treat as a failed/ambiguous insert rather than
+      // silently returning 0, which a caller could mistake for a real primary key.
+      throw new Error(`Table(${this.name}).insert: driver reported no lastInsertId`);
+    }
+    return r.lastInsertId;
+  }
+
+  /** Fetch the row with the given primary key, or `undefined`. */
+  async get(id: unknown): Promise<T | undefined> {
+    const rows = await this.#src.query(
+      `SELECT * FROM ${quoteIdent(this.name)} WHERE ${quoteIdent(this.pk)} = ? LIMIT 1`,
+      [id],
+    );
+    return rows[0] as T | undefined;
+  }
+
+  /** Every row (optionally capped at `limit`). */
+  async all(limit?: number): Promise<T[]> {
+    const lim =
+      typeof limit === "number" && Number.isFinite(limit)
+        ? ` LIMIT ${Math.max(0, Math.floor(limit))}`
+        : "";
+    return (await this.#src.query(`SELECT * FROM ${quoteIdent(this.name)}${lim}`)) as T[];
+  }
+
+  /** Rows matching an equality filter (keys ANDed). An empty filter matches all rows. */
+  async find(where: Partial<T> = {}): Promise<T[]> {
+    const { clause, params } = whereClause(where as Row);
+    return (await this.#src.query(
+      `SELECT * FROM ${quoteIdent(this.name)}${clause}`,
+      params,
+    )) as T[];
+  }
+
+  /** The first row matching an equality filter, or `undefined`. */
+  async findOne(where: Partial<T> = {}): Promise<T | undefined> {
+    const { clause, params } = whereClause(where as Row);
+    const rows = await this.#src.query(
+      `SELECT * FROM ${quoteIdent(this.name)}${clause} LIMIT 1`,
+      params,
+    );
+    return rows[0] as T | undefined;
+  }
+
+  /** Patch the row with the given primary key; returns rows changed. */
+  async update(id: unknown, patch: Partial<T>): Promise<number> {
+    const keys = Object.keys(patch);
+    if (keys.length === 0) return 0;
+    const set = keys.map((k) => `${quoteIdent(k)} = ?`).join(", ");
+    const r = await this.#src.exec(
+      `UPDATE ${quoteIdent(this.name)} SET ${set} WHERE ${quoteIdent(this.pk)} = ?`,
+      [...keys.map((k) => (patch as Row)[k]), id],
+    );
+    return r.changed;
+  }
+
+  /** Delete the row with the given primary key; returns rows changed. */
+  async delete(id: unknown): Promise<number> {
+    const r = await this.#src.exec(
+      `DELETE FROM ${quoteIdent(this.name)} WHERE ${quoteIdent(this.pk)} = ?`,
+      [id],
+    );
+    return r.changed;
+  }
+
+  /** Count rows matching an equality filter (all rows when omitted). */
+  async count(where: Partial<T> = {}): Promise<number> {
+    const { clause, params } = whereClause(where as Row);
+    const rows = await this.#src.query(
+      `SELECT COUNT(*) AS n FROM ${quoteIdent(this.name)}${clause}`,
+      params,
+    );
+    return Number((rows[0] as Row)?.n ?? 0);
+  }
+}
+
+/** A `DataSource` implemented over the runtime's synchronous `SqliteDb` host seam. The methods
+ * are async to hold the app-facing contract; the work underneath is synchronous. */
+class SqliteGateway implements DataSource {
+  readonly #db: SqliteDb;
+  constructor(db: SqliteDb) {
+    this.#db = db;
+  }
+
+  async query(sql: string, params: unknown[] = []): Promise<Row[]> {
+    return this.#db.all<Row>(sql, params);
+  }
+
+  async exec(sql: string, params: unknown[] = []): Promise<ExecResult> {
+    const r = this.#db.run(sql, params);
+    return { changed: Number(r.changes), lastInsertId: r.lastInsertRowid };
+  }
+
+  async tx<T>(fn: (t: DataSource) => Promise<T>): Promise<T> {
+    this.#db.exec("BEGIN");
+    try {
+      const out = await fn(this);
+      this.#db.exec("COMMIT");
+      return out;
+    } catch (e) {
+      this.#db.exec("ROLLBACK");
+      throw e;
+    }
+  }
+
+  async schema(): Promise<TableMeta[]> {
+    // 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' " +
+        "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) {
+      const cols = this.#db.all<{ name: string; type: string; notnull: number; pk: number }>(
+        `PRAGMA table_info(${quoteIdent(t.name)})`,
+      );
+      const idx = this.#db.all<{ name: string }>(`PRAGMA index_list(${quoteIdent(t.name)})`);
+      const fks = this.#db.all<{
+        from: string;
+        table: string;
+        to: string | null;
+        on_delete?: string;
+      }>(`PRAGMA foreign_key_list(${quoteIdent(t.name)})`);
+      out.push({
+        name: t.name,
+        columns: cols.map((c) => ({
+          name: c.name,
+          type: c.type,
+          notNull: !!c.notnull,
+          primaryKey: !!c.pk,
+        })),
+        indexes: idx.map((i) => String(i.name)),
+        foreignKeys: fks.map((f) => ({
+          column: f.from,
+          refTable: f.table,
+          refColumn: f.to ?? "",
+          onDelete:
+            f.on_delete && f.on_delete.toUpperCase() !== "NO ACTION"
+              ? f.on_delete.toUpperCase()
+              : "",
+        })),
+      });
+    }
+    return out;
+  }
+
+  table<T extends object = Row>(name: string, pk = "id"): Table<T> {
+    return new Table<T>(this, name, pk);
+  }
+}
+
+/** Wrap a provisioned `SqliteDb` as the record-oriented `DataSource` gateway. */
+export function makeGateway(db: SqliteDb): DataSource {
+  return new SqliteGateway(db);
+}

package/src/runtime/index.ts

@@ -52,6 +52,15 @@ export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 // Data layer
 export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";
 export type { ProvisionedSource } from "./core/modules/datasource.ts";
+export { makeGateway, Table } from "./core/modules/gateway.ts";
+export type {
+  ColumnMeta,
+  DataSource as GatewayDataSource,
+  ExecResult,
+  ForeignKeyMeta,
+  Row,
+  TableMeta,
+} from "./core/modules/gateway.ts";
 export type { AppJobHandler } from "./core/modules/workers.ts";
 export { resolveHandler } from "./core/modules/workers.ts";
 export { evalCorrelation } from "./core/modules/triggers.ts";