@nanobpm/urban 0.5.1 → 0.7.0

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

@@ -3,6 +3,7 @@
 // linked `.form` and posts completion back. The `chat` surface is stubbed as a mount point
 // (LLM wiring is a separate concern). Surfaces contribute routes to the shared server.
 import { html, json, normalizeRoutePath } from "../router.js";
+import { mountPages } from "./pages.js";
 /** Escape HTML-significant characters before embedding a value in markup. */
 function escapeHtml(s) {
     return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
@@ -83,6 +84,12 @@ export function mountSurfaces(ctx, app) {
 <p>Chat surface mount point (agent: <code>${escapeHtml(chat.agent ?? "?")}</code>). LLM wiring pending.</p>`),
         });
     }
+    // The pages surface (the schema-driven page runtime) mounts its own routes.
+    const pages = mountPages(ctx, app);
+    if (pages.routes.length > 0) {
+        routes.push(...pages.routes);
+        enabled.push("pages@/");
+    }
     ctx.host.log("info", "surfaces mounted", { enabled });
     return { name: "surfaces", routes, describe: () => ({ enabled }) };
 }

package/dist/runtime/engine/nanosdk.d.ts

@@ -53,6 +53,9 @@ export interface NanoSdkClient {
         variables?: Record<string, unknown>;
         awaitCompletion?: boolean;
     }, options?: unknown): Promise<Record<string, unknown>>;
+    cancelProcessInstance(input: {
+        processInstanceKey: string | number;
+    }, options?: unknown): Promise<unknown>;
     publishMessage(input: {
         name: string;
         correlationKey?: string;
@@ -101,6 +104,9 @@ export declare class SdkEngineClient implements EngineClient {
         processInstanceKey: string;
         variables?: Record<string, unknown>;
     }>;
+    cancelInstance(input: {
+        processInstanceKey: string;
+    }): Promise<void>;
     publishMessage(input: {
         name: string;
         correlationKey?: string;

package/dist/runtime/engine/nanosdk.js

@@ -66,6 +66,9 @@ export class SdkEngineClient {
             variables: body.variables ?? undefined,
         };
     }
+    async cancelInstance(input) {
+        await this.client.cancelProcessInstance({ processInstanceKey: input.processInstanceKey });
+    }
     async publishMessage(input) {
         await this.client.publishMessage({
             name: input.name,

package/dist/runtime/index.d.ts

@@ -8,6 +8,10 @@ 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 { createPagesRoutes, mountPages } from "./core/modules/pages.ts";
+export type { PagesDataSource, PagesDeps, PagesHandle, PagesOptions } from "./core/modules/pages.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,8 @@ 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 { createPagesRoutes, mountPages } from "./core/modules/pages.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.7.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/host.ts

@@ -105,6 +105,8 @@ export interface EngineClient {
     variables?: Record<string, unknown>;
     awaitCompletion?: boolean;
   }): Promise<{ processInstanceKey: string; variables?: Record<string, unknown> }>;
+  /** Cancel a running process instance (the pages surface's row-cancel action). */
+  cancelInstance(input: { processInstanceKey: string }): Promise<void>;
   /** Publish a message for correlation. */
   publishMessage(input: {
     name: string;

package/src/runtime/core/manifest.ts

@@ -44,6 +44,14 @@ export interface SurfaceDecl {
   enabled?: boolean;
   path?: string;
   agent?: string;
+  /** pages surface: directory of `*.page.json` (relative to app root). Default `pages`. */
+  pagesDir?: string;
+  /** pages surface: the page served at `/`. Default `home`. */
+  homePage?: string;
+  /** pages surface: max rows a `dataGrid` fetch returns. Default 200. */
+  rowLimit?: number;
+  /** pages surface: the injected default datasource name. Default `app`. */
+  sourceName?: string;
 }
 
 export interface AppManifest {

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,274 @@
+// 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>;
+}
+
+/** Double-quote a SQL identifier (table/column), escaping embedded quotes. */
+export 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);
+}