@sapporta/server 0.0.1

package/src/schema/metadata-tables.test.ts

@@ -0,0 +1,737 @@
+/**
+ * Integration tests for the UI-managed tables system (Plan 1b).
+ *
+ * Tests the full lifecycle: dynamic table builder, metadata tables bootstrap,
+ * schema mutation API, schema API extensions, and boot sequence integration.
+ *
+ * Uses in-memory SQLite — no external DB needed.
+ * We use the raw better-sqlite3 handle for DDL; ORM queries go through
+ * Drizzle's BetterSQLite3Database.
+ */
+import { describe, it, expect, beforeEach } from "vitest";
+import { Hono } from "hono";
+import {
+  sqliteTable,
+  text,
+  integer,
+  getTableConfig,
+} from "drizzle-orm/sqlite-core";
+import { table } from "./table.js";
+import { SchemaRegistry } from "./registry.js";
+import { extractSchemas } from "./extract.js";
+import { crud } from "../data/crud.js";
+import {
+  buildDrizzleTable,
+  planTable,
+  generateCreateTableDDL,
+  generateAddColumnDDL,
+  type ColumnMetaRow,
+} from "./dynamic-builder.js";
+import { validateTableName, validateColumnName } from "./reserved.js";
+import { createTestDb } from "../testing/test-utils.js";
+import { ensureMetadataTables, loadUISchemas } from "./metadata-tables.js";
+import Database from "better-sqlite3";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 1. Dynamic Table Builder
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("buildDrizzleTable", () => {
+  let registry: SchemaRegistry;
+
+  beforeEach(() => {
+    registry = new SchemaRegistry();
+  });
+
+  it("creates a table with system columns (id, created_at, updated_at)", () => {
+    const def = buildDrizzleTable(
+      { name: "expenses" },
+      [],
+      registry,
+    );
+
+    expect(def.sqlName).toBe("expenses");
+    const config = getTableConfig(def.drizzle);
+    expect(config.name).toBe("expenses");
+
+    // System columns are always present
+    const colNames = config.columns.map((c) => c.name);
+    expect(colNames).toContain("id");
+    expect(colNames).toContain("created_at");
+    expect(colNames).toContain("updated_at");
+
+    // id is primary key
+    const idCol = config.columns.find((c) => c.name === "id")!;
+    expect(idCol.primary).toBe(true);
+    expect(idCol.hasDefault).toBe(true);
+  });
+
+  it("adds user-defined columns from metadata", () => {
+    const columns: ColumnMetaRow[] = [
+      { column_name: "description", column_type: "text", position: 0, not_null: true },
+      { column_name: "amount", column_type: "numeric", position: 1 },
+      { column_name: "is_active", column_type: "boolean", position: 2, default_value: "true" },
+    ];
+
+    const def = buildDrizzleTable({ name: "expenses" }, columns, registry);
+    const config = getTableConfig(def.drizzle);
+
+    const descCol = config.columns.find((c) => c.name === "description")!;
+    expect(descCol.notNull).toBe(true);
+    expect(descCol.dataType).toBe("string"); // text → string in Drizzle
+
+    const amountCol = config.columns.find((c) => c.name === "amount")!;
+    expect(amountCol.dataType).toBe("number"); // numeric → real() → number in Drizzle SQLite
+
+    const activeCol = config.columns.find((c) => c.name === "is_active")!;
+    expect(activeCol.dataType).toBe("boolean");
+    expect(activeCol.hasDefault).toBe(true);
+  });
+
+  it("maps all column types to correct Drizzle builders", () => {
+    const columns: ColumnMetaRow[] = [
+      { column_name: "col_text", column_type: "text", position: 0 },
+      { column_name: "col_integer", column_type: "integer", position: 1 },
+      { column_name: "col_numeric", column_type: "numeric", position: 2 },
+      { column_name: "col_boolean", column_type: "boolean", position: 3 },
+      { column_name: "col_date", column_type: "date", position: 4 },
+      { column_name: "col_timestamp", column_type: "timestamp", position: 5 },
+      { column_name: "col_select", column_type: "select", position: 6, select_options: ["a", "b"] },
+      { column_name: "col_currency", column_type: "currency", position: 7 },
+      { column_name: "col_percentage", column_type: "percentage", position: 8 },
+      { column_name: "col_email", column_type: "email", position: 9 },
+      { column_name: "col_url", column_type: "url", position: 10 },
+    ];
+
+    const def = buildDrizzleTable({ name: "test_types" }, columns, registry);
+    const config = getTableConfig(def.drizzle);
+
+    // All columns should exist (11 user + 3 system)
+    expect(config.columns).toHaveLength(14);
+  });
+
+  it("applies UNIQUE constraint", () => {
+    const columns: ColumnMetaRow[] = [
+      { column_name: "email", column_type: "email", position: 0, is_unique: true },
+    ];
+
+    const def = buildDrizzleTable({ name: "users" }, columns, registry);
+    const config = getTableConfig(def.drizzle);
+    const emailCol = config.columns.find((c) => c.name === "email")!;
+    expect(emailCol.isUnique).toBe(true);
+  });
+
+  it("creates FK references for link columns when target exists in registry", () => {
+    // Register a target table first
+    const categoriesTable = sqliteTable("categories", {
+      id: integer("id").primaryKey({ autoIncrement: true }),
+      name: text("name").notNull(),
+    });
+    const catDef = table({ drizzle: categoriesTable, meta: { label: "Categories" } });
+    registry.register(catDef, "file");
+
+    // Build a table with a link column to categories
+    const columns: ColumnMetaRow[] = [
+      { column_name: "category_id", column_type: "link", position: 0, references_table: "categories" },
+    ];
+
+    const def = buildDrizzleTable({ name: "expenses" }, columns, registry);
+    const config = getTableConfig(def.drizzle);
+
+    // Should have FK metadata
+    expect(config.foreignKeys).toHaveLength(1);
+    const fkRef = config.foreignKeys[0].reference();
+    const targetConfig = getTableConfig(fkRef.foreignColumns[0].table);
+    expect(targetConfig.name).toBe("categories");
+  });
+
+  it("skips FK reference when target is not in registry (dangling link)", () => {
+    const columns: ColumnMetaRow[] = [
+      { column_name: "category_id", column_type: "link", position: 0, references_table: "nonexistent" },
+    ];
+
+    const def = buildDrizzleTable({ name: "expenses" }, columns, registry);
+    const config = getTableConfig(def.drizzle);
+
+    // Column exists as integer but without FK
+    const col = config.columns.find((c) => c.name === "category_id")!;
+    expect(col.dataType).toBe("number");
+    expect(config.foreignKeys).toHaveLength(0);
+  });
+
+  it("builds SapportaMeta with label, displayColumn, and selects", () => {
+    const columns: ColumnMetaRow[] = [
+      { column_name: "status", column_type: "select", position: 0, select_options: ["open", "closed"] },
+      { column_name: "total", column_type: "currency", position: 1 },
+    ];
+
+    const def = buildDrizzleTable(
+      { name: "orders", label: "Orders", display_column: "status" },
+      columns,
+      registry,
+    );
+
+    expect(def.meta.label).toBe("Orders");
+    expect(def.meta.displayColumn).toBe("status");
+    expect(def.meta.selects).toHaveLength(1);
+    expect(def.meta.selects![0].column).toBe("status");
+    expect(def.meta.selects![0].options).toEqual(["open", "closed"]);
+
+    // Currency columns get "money" type for formatting
+    expect(def.meta.columns?.total?.type).toBe("money");
+  });
+
+  it("builds SapportaMeta with immutable flag", () => {
+    const def = buildDrizzleTable(
+      { name: "audit_log", immutable: true },
+      [],
+      registry,
+    );
+
+    expect(def.meta.immutable).toBe(true);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 1b. planTable (pure layer)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("planTable", () => {
+  it("empty columns → empty spec", () => {
+    const spec = planTable({ name: "empty" }, []);
+    expect(spec.sqlName).toBe("empty");
+    expect(spec.columns).toEqual([]);
+  });
+
+  it("maps column metadata to correct ColumnSpec fields", () => {
+    const columns: ColumnMetaRow[] = [
+      { column_name: "title", column_type: "text", position: 0, not_null: true, is_unique: true, default_value: "untitled" },
+      { column_name: "amount", column_type: "numeric", position: 1 },
+    ];
+    const spec = planTable({ name: "items" }, columns);
+
+    expect(spec.columns).toHaveLength(2);
+
+    const title = spec.columns[0];
+    expect(title.name).toBe("title");
+    expect(title.builderType).toBe("text");
+    expect(title.notNull).toBe(true);
+    expect(title.isUnique).toBe(true);
+    expect(title.defaultValue).toBe("untitled");
+    expect(title.fkTarget).toBeNull();
+
+    const amount = spec.columns[1];
+    expect(amount.name).toBe("amount");
+    expect(amount.builderType).toBe("numeric");
+    expect(amount.notNull).toBe(false);
+    expect(amount.isUnique).toBe(false);
+    expect(amount.defaultValue).toBeUndefined();
+    expect(amount.fkTarget).toBeNull();
+  });
+
+  it("link column → fkTarget set to table name", () => {
+    const columns: ColumnMetaRow[] = [
+      { column_name: "category_id", column_type: "link", position: 0, references_table: "categories" },
+    ];
+    const spec = planTable({ name: "expenses" }, columns);
+
+    expect(spec.columns[0].builderType).toBe("link");
+    expect(spec.columns[0].fkTarget).toBe("categories");
+  });
+
+  it("unknown column type → skipped", () => {
+    const columns: ColumnMetaRow[] = [
+      { column_name: "good", column_type: "text", position: 0 },
+      { column_name: "bad", column_type: "imaginary_type", position: 1 },
+    ];
+    const spec = planTable({ name: "test" }, columns);
+
+    expect(spec.columns).toHaveLength(1);
+    expect(spec.columns[0].name).toBe("good");
+  });
+
+  it("builds SapportaMeta with selects, currency→money, label, displayColumn, immutable, inferred", () => {
+    const columns: ColumnMetaRow[] = [
+      { column_name: "status", column_type: "select", position: 0, select_options: ["active", "inactive"] },
+      { column_name: "total", column_type: "currency", position: 1 },
+    ];
+    const spec = planTable(
+      { name: "orders", label: "Orders", display_column: "status", immutable: true, inferred: true },
+      columns,
+    );
+
+    expect(spec.meta.label).toBe("Orders");
+    expect(spec.meta.displayColumn).toBe("status");
+    expect(spec.meta.immutable).toBe(true);
+    expect(spec.meta.inferred).toBe(true);
+    expect(spec.meta.selects).toHaveLength(1);
+    expect(spec.meta.selects![0]).toEqual({ type: "select", column: "status", options: ["active", "inactive"] });
+    expect(spec.meta.columns?.total?.type).toBe("money");
+  });
+
+  it("includes ui_hints in column metadata", () => {
+    const columns: ColumnMetaRow[] = [
+      { column_name: "notes", column_type: "text", position: 0, ui_hints: { header: "Notes", hidden: true, width: 200 } },
+    ];
+    const spec = planTable({ name: "tasks" }, columns);
+
+    expect(spec.meta.columns?.notes?.header).toBe("Notes");
+    expect(spec.meta.columns?.notes?.hidden).toBe(true);
+    expect(spec.meta.columns?.notes?.width).toBe(200);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 3. Dynamic Table Builder + SQLite Integration
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("buildDrizzleTable + SQLite integration", () => {
+  let db: any;
+  let sqlite: any;
+  let registry: SchemaRegistry;
+
+  beforeEach(() => {
+    ({ db, sqlite } = createTestDb());
+    registry = new SchemaRegistry();
+  });
+
+  it("creates table via DDL, inserts data via Drizzle, queries back", async () => {
+    // Create the table using generated DDL
+    const ddl = generateCreateTableDDL("expenses");
+    sqlite.exec(ddl);
+
+    for (const stmt of generateAddColumnDDL("expenses", {
+      column_name: "description",
+      column_type: "text",
+      position: 0,
+      not_null: true,
+    })) sqlite.exec(stmt);
+
+    for (const stmt of generateAddColumnDDL("expenses", {
+      column_name: "amount",
+      column_type: "numeric",
+      position: 1,
+    })) sqlite.exec(stmt);
+
+    // Build the dynamic table
+    const def = buildDrizzleTable(
+      { name: "expenses", label: "Expenses" },
+      [
+        { column_name: "description", column_type: "text", position: 0, not_null: true },
+        { column_name: "amount", column_type: "numeric", position: 1 },
+      ],
+      registry,
+    );
+
+    // Insert via Drizzle
+    await db.insert(def.drizzle as any).values({ description: "Lunch", amount: "15.50" });
+    const rows = await db.select().from(def.drizzle as any);
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0].description).toBe("Lunch");
+    // SQLite REAL stores as a float — "15.50" becomes 15.5
+    expect(rows[0].amount).toBe(15.5);
+    expect(rows[0].id).toBe(1);
+    expect(typeof rows[0].created_at).toBe("string");
+  });
+
+  it("CRUD sub-app works with dynamically built table", async () => {
+    sqlite.exec(generateCreateTableDDL("tasks"));
+    for (const stmt of generateAddColumnDDL("tasks", {
+      column_name: "title",
+      column_type: "text",
+      position: 0,
+      not_null: true,
+    })) sqlite.exec(stmt);
+
+    const def = buildDrizzleTable(
+      { name: "tasks" },
+      [{ column_name: "title", column_type: "text", position: 0, not_null: true }],
+      registry,
+    );
+
+    const app = new Hono();
+    app.route("/tasks", crud(def, db));
+
+    // POST
+    const createRes = await app.request("/tasks", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ title: "Buy groceries" }),
+    });
+    expect(createRes.status).toBe(201);
+    const created = await createRes.json();
+    expect(created.data.title).toBe("Buy groceries");
+
+    // GET
+    const listRes = await app.request("/tasks");
+    const list = await listRes.json();
+    expect(list.data).toHaveLength(1);
+
+    // GET /:id
+    const getRes = await app.request("/tasks/1");
+    const record = await getRes.json();
+    expect(record.data.title).toBe("Buy groceries");
+
+    // PUT
+    const updateRes = await app.request("/tasks/1", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ title: "Updated title" }),
+    });
+    expect(updateRes.status).toBe(200);
+    const updated = await updateRes.json();
+    expect(updated.data.title).toBe("Updated title");
+
+    // DELETE
+    const deleteRes = await app.request("/tasks/1", { method: "DELETE" });
+    expect(deleteRes.status).toBe(200);
+
+    const check = await app.request("/tasks/1");
+    expect(check.status).toBe(404);
+  });
+
+  it("extractSchemas works with dynamically built tables", () => {
+    const def = buildDrizzleTable(
+      { name: "expenses", label: "Expenses" },
+      [
+        { column_name: "description", column_type: "text", position: 0, not_null: true },
+        { column_name: "status", column_type: "select", position: 1, select_options: ["open", "closed"] },
+        { column_name: "amount", column_type: "currency", position: 2 },
+      ],
+      registry,
+    );
+
+    const schemas = extractSchemas([def]);
+    expect(schemas).toHaveLength(1);
+
+    const s = schemas[0];
+    expect(s.name).toBe("expenses");
+    expect(s.label).toBe("Expenses");
+    expect(s.source).toBe("file"); // Default when using plain array
+
+    // Select column
+    const statusCol = s.columns.find((c) => c.name === "status")!;
+    expect(statusCol.select).toEqual({ options: ["open", "closed"] });
+    expect(statusCol.selectOptions).toEqual(["open", "closed"]);
+
+    // Currency column
+    const amountCol = s.columns.find((c) => c.name === "amount")!;
+    expect(amountCol.money).toBe(true);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 4. Schema API Extensions (source, shadowedByFile, displayColumn)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("extractSchemas with registry (source + shadow tracking)", () => {
+  it("includes source: 'file' for file-managed tables", () => {
+    const registry = new SchemaRegistry();
+    const drizzleTable = sqliteTable("accounts", {
+      id: integer("id").primaryKey({ autoIncrement: true }),
+      name: text("name").notNull(),
+    });
+    const def = table({ drizzle: drizzleTable, meta: { label: "Accounts" } });
+    registry.register(def, "file");
+
+    const schemas = extractSchemas(registry);
+    expect(schemas[0].source).toBe("file");
+    expect(schemas[0].shadowedByFile).toBeUndefined();
+  });
+
+  it("includes source: 'ui' for UI-managed tables", () => {
+    const registry = new SchemaRegistry();
+    const def = buildDrizzleTable(
+      { name: "expenses", label: "Expenses" },
+      [],
+      registry,
+    );
+    registry.register(def, "ui");
+
+    const schemas = extractSchemas(registry);
+    expect(schemas[0].source).toBe("ui");
+  });
+
+  it("marks shadowed tables", () => {
+    const registry = new SchemaRegistry();
+
+    // Register a file-managed table
+    const drizzleTable = sqliteTable("accounts", {
+      id: integer("id").primaryKey({ autoIncrement: true }),
+      name: text("name").notNull(),
+    });
+    const fileDef = table({ drizzle: drizzleTable, meta: { label: "Accounts" } });
+    registry.register(fileDef, "file");
+
+    // Try to register a UI-managed table with the same name — it gets shadowed
+    const uiDef = buildDrizzleTable({ name: "accounts", label: "Accounts UI" }, [], registry);
+    registry.register(uiDef, "ui");
+
+    // The file version should be active, but isShadowed returns true
+    // because a UI definition exists for this name
+    expect(registry.isShadowed("accounts")).toBe(true);
+
+    const schemas = extractSchemas(registry);
+    expect(schemas).toHaveLength(1); // Only one active entry
+    expect(schemas[0].source).toBe("file"); // File wins
+    expect(schemas[0].shadowedByFile).toBe(true);
+  });
+
+  it("includes displayColumn from meta", () => {
+    const registry = new SchemaRegistry();
+    const drizzleTable = sqliteTable("accounts", {
+      id: integer("id").primaryKey({ autoIncrement: true }),
+      name: text("name").notNull(),
+    });
+    const def = table({
+      drizzle: drizzleTable,
+      meta: { label: "Accounts", displayColumn: "name" },
+    });
+    registry.register(def, "file");
+
+    const schemas = extractSchemas(registry);
+    expect(schemas[0].displayColumn).toBe("name");
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 5. ensureMetadataTables — DDL bootstrap and migration
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("ensureMetadataTables", () => {
+  it("creates both metadata tables from scratch", () => {
+    const sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+
+    ensureMetadataTables(sqlite);
+
+    const tables = sqlite
+      .prepare(
+        `SELECT name FROM sqlite_master WHERE type = 'table' AND name LIKE '_sapporta_%'`,
+      )
+      .all() as { name: string }[];
+
+    const names = tables.map((t) => t.name).sort();
+    expect(names).toEqual(["_sapporta_columns", "_sapporta_tables"]);
+    sqlite.close();
+  });
+
+  it("is idempotent — calling twice does not throw", () => {
+    const sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+
+    ensureMetadataTables(sqlite);
+    expect(() => ensureMetadataTables(sqlite)).not.toThrow();
+    sqlite.close();
+  });
+
+  it("migrates old schema: adds inferred column if missing", () => {
+    // Simulate a database from before the inferred column was added.
+    const sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+
+    // Create _sapporta_tables WITHOUT the inferred column (old schema)
+    sqlite.exec(`
+      CREATE TABLE _sapporta_tables (
+        name            TEXT PRIMARY KEY,
+        label           TEXT,
+        display_column  TEXT,
+        immutable       INTEGER NOT NULL DEFAULT 0,
+        position        INTEGER NOT NULL DEFAULT 0,
+        created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at      TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `);
+    sqlite.exec(`
+      CREATE TABLE _sapporta_columns (
+        table_name      TEXT NOT NULL REFERENCES _sapporta_tables(name) ON DELETE CASCADE,
+        column_name     TEXT NOT NULL,
+        column_type     TEXT NOT NULL DEFAULT 'text',
+        position        INTEGER NOT NULL DEFAULT 0,
+        not_null        INTEGER NOT NULL DEFAULT 0,
+        is_unique       INTEGER NOT NULL DEFAULT 0,
+        default_value   TEXT,
+        references_table TEXT,
+        select_options  TEXT,
+        ui_hints        TEXT NOT NULL DEFAULT '{}',
+        PRIMARY KEY (table_name, column_name)
+      )
+    `);
+
+    // Verify inferred column does NOT exist yet
+    const colsBefore = sqlite.pragma('table_info("_sapporta_tables")') as { name: string }[];
+    expect(colsBefore.map((c) => c.name)).not.toContain("inferred");
+
+    // Run ensureMetadataTables — should migrate without error
+    ensureMetadataTables(sqlite);
+
+    // Verify inferred column now exists
+    const colsAfter = sqlite.pragma('table_info("_sapporta_tables")') as { name: string }[];
+    expect(colsAfter.map((c) => c.name)).toContain("inferred");
+
+    // Verify default value works: inserting a row without inferred should default to 0
+    sqlite.prepare(`INSERT INTO _sapporta_tables (name) VALUES (?)`).run("test");
+    const row = sqlite.prepare(`SELECT inferred FROM _sapporta_tables WHERE name = ?`).get("test") as { inferred: number };
+    expect(row.inferred).toBe(0);
+
+    sqlite.close();
+  });
+
+  it("cascades column deletes when table row is deleted", () => {
+    const sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+    ensureMetadataTables(sqlite);
+
+    sqlite.prepare(`INSERT INTO _sapporta_tables (name, label) VALUES (?, ?)`).run("test_table", "Test");
+    sqlite.prepare(`INSERT INTO _sapporta_columns (table_name, column_name, column_type) VALUES (?, ?, ?)`).run("test_table", "col1", "text");
+
+    sqlite.prepare(`DELETE FROM _sapporta_tables WHERE name = ?`).run("test_table");
+
+    const cols = sqlite.prepare(`SELECT * FROM _sapporta_columns WHERE table_name = ?`).all("test_table");
+    expect(cols).toHaveLength(0);
+
+    sqlite.close();
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 6. loadUISchemas — reading metadata into live TableDefs
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("loadUISchemas", () => {
+  it("returns empty array for fresh database", () => {
+    const sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+    ensureMetadataTables(sqlite);
+
+    const registry = new SchemaRegistry();
+    const defs = loadUISchemas(sqlite, registry);
+    expect(defs).toEqual([]);
+
+    sqlite.close();
+  });
+
+  it("loads a table with columns into live TableDefs", () => {
+    const sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+    ensureMetadataTables(sqlite);
+
+    sqlite.prepare(`INSERT INTO _sapporta_tables (name, label, position) VALUES (?, ?, ?)`).run("contacts", "Contacts", 0);
+    sqlite.prepare(`INSERT INTO _sapporta_columns (table_name, column_name, column_type, position, not_null) VALUES (?, ?, ?, ?, ?)`).run("contacts", "name", "text", 0, 1);
+    sqlite.prepare(`INSERT INTO _sapporta_columns (table_name, column_name, column_type, position) VALUES (?, ?, ?, ?)`).run("contacts", "email", "email", 1);
+
+    const registry = new SchemaRegistry();
+    const defs = loadUISchemas(sqlite, registry);
+
+    expect(defs).toHaveLength(1);
+    expect(defs[0].sqlName).toBe("contacts");
+    expect(defs[0].meta.label).toBe("Contacts");
+
+    sqlite.close();
+  });
+
+  it("deserializes JSON select_options and ui_hints", () => {
+    const sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+    ensureMetadataTables(sqlite);
+
+    sqlite.prepare(`INSERT INTO _sapporta_tables (name) VALUES (?)`).run("items");
+    sqlite.prepare(
+      `INSERT INTO _sapporta_columns (table_name, column_name, column_type, select_options, ui_hints) VALUES (?, ?, ?, ?, ?)`,
+    ).run("items", "status", "select", JSON.stringify(["active", "inactive"]), JSON.stringify({ width: 40 }));
+
+    const registry = new SchemaRegistry();
+    const defs = loadUISchemas(sqlite, registry);
+
+    expect(defs[0].meta.selects).toBeDefined();
+    expect(defs[0].meta.selects![0].options).toEqual(["active", "inactive"]);
+    expect(defs[0].meta.columns?.status?.width).toBe(40);
+
+    sqlite.close();
+  });
+
+  it("converts immutable and inferred flags (SQLite 0/1 → boolean)", () => {
+    const sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+    ensureMetadataTables(sqlite);
+
+    sqlite.prepare(`INSERT INTO _sapporta_tables (name, immutable, inferred) VALUES (?, ?, ?)`).run("audit_log", 1, 1);
+
+    const registry = new SchemaRegistry();
+    const defs = loadUISchemas(sqlite, registry);
+
+    expect(defs[0].meta.immutable).toBe(true);
+    expect(defs[0].meta.inferred).toBe(true);
+
+    sqlite.close();
+  });
+});
+
+describe("file vs UI table shadowing", () => {
+  it("file-managed tables shadow UI-managed tables", async () => {
+    const registry = new SchemaRegistry();
+
+    // Register a file-managed table first
+    const drizzleTable = sqliteTable("accounts", {
+      id: integer("id").primaryKey({ autoIncrement: true }),
+      name: text("name").notNull(),
+      balance: integer("balance"),
+    });
+    const fileDef = table({ drizzle: drizzleTable, meta: { label: "Accounts (File)" } });
+    registry.register(fileDef, "file");
+
+    // Now register a UI-managed table with the same name
+    const uiDef = buildDrizzleTable(
+      { name: "accounts", label: "Accounts (UI)" },
+      [{ column_name: "description", column_type: "text", position: 0 }],
+      registry,
+    );
+    registry.register(uiDef, "ui");
+
+    // File should win
+    expect(registry.all()).toHaveLength(1);
+    expect(registry.get("accounts")?.source).toBe("file");
+    expect(registry.get("accounts")?.def.meta.label).toBe("Accounts (File)");
+
+    // UI def should be in the shadow map
+    expect(registry.isShadowed("accounts")).toBe(true);
+    expect(registry.shadowedEntries().get("accounts")?.meta.label).toBe("Accounts (UI)");
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 6. Validation Helpers
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("validateTableName / validateColumnName", () => {
+
+  it("accepts valid table names", () => {
+    expect(validateTableName("expenses").valid).toBe(true);
+    expect(validateTableName("order_items").valid).toBe(true);
+    expect(validateTableName("a123").valid).toBe(true);
+  });
+
+  it("rejects invalid table names", () => {
+    expect(validateTableName("123abc").valid).toBe(false);  // starts with number
+    expect(validateTableName("My Table").valid).toBe(false); // spaces
+    expect(validateTableName("UPPER").valid).toBe(false);    // uppercase
+    expect(validateTableName("").valid).toBe(false);          // empty
+    expect(validateTableName("_sapporta_meta").valid).toBe(false); // reserved prefix
+    expect(validateTableName("_schema").valid).toBe(false);  // reserved name
+    expect(validateTableName("_meta").valid).toBe(false);    // reserved name
+    expect(validateTableName("select").valid).toBe(false);   // PG reserved word
+    expect(validateTableName("table").valid).toBe(false);    // PG reserved word
+  });
+
+  it("accepts valid column names", () => {
+    expect(validateColumnName("amount").valid).toBe(true);
+    expect(validateColumnName("first_name").valid).toBe(true);
+  });
+
+  it("rejects auto-managed column names", () => {
+    expect(validateColumnName("id").valid).toBe(false);
+    expect(validateColumnName("created_at").valid).toBe(false);
+    expect(validateColumnName("updated_at").valid).toBe(false);
+  });
+});