@sapporta/server 0.0.1

package/src/api/meta-mutations.ts

@@ -0,0 +1,922 @@
+/**
+ * Schema Mutation API — HTTP endpoints for creating/modifying/deleting
+ * UI-managed tables and columns from the browser UI.
+ *
+ * Mounted as a Hono sub-app at ${prefix}/_meta. All endpoints enforce:
+ *
+ * 1. **File-managed tables are protected.** Any mutation attempt on a table
+ *    whose source is "file" is rejected with 409 Conflict and a message
+ *    directing the user to modify the TypeScript schema file instead.
+ *
+ * 2. **Transactional DDL.** SQLite supports DDL inside transactions. Every
+ *    mutation wraps metadata writes + DDL in a single sqlite.transaction()
+ *    call. If the DDL fails, the metadata change is rolled back — no partial
+ *    state in the in-memory registry.
+ *
+ * 3. **No CASCADE on drop.** Dropping a table that contains business data is
+ *    destructive, and CASCADE could silently destroy FK columns in other tables.
+ *    Instead, we check for FK dependents and require explicit confirmation.
+ *
+ * 4. **Literal defaults only.** default_value from user input is never
+ *    interpolated as raw SQL. Only literal values (strings, numbers, booleans,
+ *    null) are accepted. This prevents SQL injection via crafted default
+ *    expressions like "'); DROP TABLE users; --".
+ *
+ * 5. **Synchronous execution.** All SQLite operations via better-sqlite3 are
+ *    synchronous. Hono route handlers are still async (for body parsing), but
+ *    database operations within them are synchronous — no await needed for
+ *    sqlite.prepare(), .run(), .get(), .all(), .exec(), or .transaction().
+ */
+import { Hono } from "hono";
+import type Database from "better-sqlite3";
+import type { SchemaRegistry } from "../schema/registry.js";
+import { validateTableName, validateColumnName } from "../schema/reserved.js";
+import { buildSetClause, mergeUiHints, deserializeColumnRow, type RawMetadataColumnRow } from "../schema/metadata-io.js";
+
+import {
+  buildDrizzleTable,
+  generateCreateTableDDL,
+  generateAddColumnDDL,
+  VALID_COLUMN_TYPES,
+  type TableMeta,
+  type ColumnMetaRow,
+} from "../schema/dynamic-builder.js";
+import { inferSchema } from "../introspect/inference.js";
+
+// ─── Safe Type Transitions ──────────────────────────────────────────────────
+// Only type changes that can't lose data are allowed. For example, text → email
+// is safe (both are TEXT in SQLite), but text → integer would require a CAST that
+// could fail on non-numeric strings.
+
+const SAFE_TYPE_TRANSITIONS: Record<string, Set<string>> = {
+  // Text family — all map to TEXT in SQLite, only UI semantics change
+  text: new Set(["email", "url", "select"]),
+  email: new Set(["text", "url"]),
+  url: new Set(["text", "email"]),
+  select: new Set(["text"]),
+
+  // Numeric family — all map to TEXT or REAL in SQLite
+  numeric: new Set(["currency", "percentage"]),
+  currency: new Set(["numeric", "percentage"]),
+  percentage: new Set(["numeric", "currency"]),
+
+  // integer → numeric is widening (safe), but numeric → integer is narrowing (unsafe)
+  integer: new Set(["numeric", "currency", "percentage"]),
+};
+
+function isTypeSafe(fromType: string, toType: string): boolean {
+  return SAFE_TYPE_TRANSITIONS[fromType]?.has(toType) ?? false;
+}
+
+// ─── API Factory ────────────────────────────────────────────────────────────
+
+/**
+ * Create the metadata mutation API sub-app.
+ *
+ * The caller (runtime.ts → meta.ts) passes in the raw better-sqlite3 handle
+ * (for transactional DDL) and the SchemaRegistry (for in-memory updates).
+ *
+ * All SQL operations use sqlite.prepare().run/get/all() with parameterized
+ * queries, and sqlite.exec() for DDL statements. Transactions use
+ * sqlite.transaction() which returns a synchronous callable.
+ */
+export function metadataApi(
+  sqlite: Database.Database,
+  registry: SchemaRegistry,
+): Hono {
+  const app = new Hono();
+
+  // ── Guard: reject mutations on file-managed tables ──────────────────────
+  function assertUIManaged(tableName: string): Response | null {
+    const entry = registry.get(tableName);
+    if (!entry) return null; // Will be handled as 404 by the caller
+    if (entry.source === "file") {
+      return Response.json(
+        { error: `Table "${tableName}" is code-managed. Modify the TypeScript schema file instead.` },
+        { status: 409 },
+      );
+    }
+    return null;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Tables
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  // ── POST /tables — Create a new UI-managed table ────────────────────────
+  // Accepts an optional `columns` array for batch creation in a single transaction.
+  // This avoids N+1 API calls when creating a table with pre-defined columns
+  // (e.g., the "+" button creates a table with 10 text columns A-J).
+  app.post("/tables", async (c) => {
+    const body = await c.req.json<{
+      name: string;
+      label?: string;
+      columns?: Array<{
+        column_name: string;
+        column_type?: string;
+        not_null?: boolean;
+        is_unique?: boolean;
+        default_value?: string;
+        references_table?: string;
+        select_options?: string[];
+        ui_hints?: Record<string, unknown>;
+        position?: number;
+      }>;
+    }>();
+    const { name, label, columns: colDefs } = body;
+
+    // 1. Validate the table name
+    const validation = validateTableName(name);
+    if (!validation.valid) {
+      return c.json({ error: validation.reason }, 400);
+    }
+
+    // 2. Check collision with existing tables (file-managed or UI-managed)
+    if (registry.has(name)) {
+      return c.json(
+        { error: `Table "${name}" already exists` },
+        409,
+      );
+    }
+
+    // 3. Validate columns (if provided)
+    const columnMetas: ColumnMetaRow[] = [];
+    if (colDefs && colDefs.length > 0) {
+      for (let i = 0; i < colDefs.length; i++) {
+        const col = colDefs[i];
+        const nameCheck = validateColumnName(col.column_name);
+        if (!nameCheck.valid) {
+          return c.json({ error: `Column ${i}: ${nameCheck.reason}` }, 400);
+        }
+        const colType = col.column_type ?? "text";
+        if (!VALID_COLUMN_TYPES.has(colType)) {
+          return c.json({ error: `Column "${col.column_name}": invalid type "${colType}"` }, 400);
+        }
+        if (colType === "link" && !col.references_table) {
+          return c.json({ error: `Column "${col.column_name}": link columns require a references_table` }, 400);
+        }
+        if (colType === "link" && col.references_table && !registry.has(col.references_table)) {
+          return c.json({ error: `Column "${col.column_name}": FK target "${col.references_table}" does not exist` }, 400);
+        }
+        columnMetas.push({
+          column_name: col.column_name,
+          column_type: colType,
+          position: col.position ?? i,
+          not_null: col.not_null ?? false,
+          is_unique: col.is_unique ?? false,
+          default_value: col.default_value,
+          references_table: col.references_table,
+          select_options: col.select_options,
+          ui_hints: col.ui_hints ?? {},
+        });
+      }
+    }
+
+    // 4. Transactional: insert metadata + execute CREATE TABLE DDL + add columns.
+    //    If any DDL fails, everything is rolled back — no partial state.
+    //    SQLite transactions are synchronous — the callback is NOT async.
+    const ddl = generateCreateTableDDL(name);
+    const createTableTxn = sqlite.transaction(() => {
+      sqlite.prepare(
+        `INSERT INTO _sapporta_tables (name, label) VALUES (?, ?)`
+      ).run(name, label ?? name);
+
+      sqlite.exec(ddl);
+
+      for (const col of columnMetas) {
+        insertColumnMeta(sqlite, name, col);
+        for (const stmt of generateAddColumnDDL(name, col)) {
+          sqlite.exec(stmt);
+        }
+      }
+    });
+    createTableTxn();
+
+    // 5. Build the TableDef and register it.
+    //    Registry update happens AFTER the transaction commits — if we crash
+    //    between commit and register, the next boot will pick it up from metadata.
+    const tableMeta: TableMeta = { name, label: label ?? name };
+    const def = buildDrizzleTable(tableMeta, columnMetas, registry);
+    registry.register(def, "ui");
+
+    // 6. Return the new table's info
+    return c.json({ name, label: label ?? name, columns: columnMetas }, 201);
+  });
+
+  // ── PATCH /tables/:name — Update table properties ──────────────────────
+  // Supports renaming via optional `name` field in body.
+  app.patch("/tables/:name", async (c) => {
+    const name = c.req.param("name");
+
+    // Guard: reject mutations on file-managed tables
+    const guard = assertUIManaged(name);
+    if (guard) return guard;
+
+    if (!registry.has(name)) {
+      return c.json({ error: `Table "${name}" not found` }, 404);
+    }
+
+    const body = await c.req.json<{
+      name?: string;
+      label?: string;
+      display_column?: string;
+      immutable?: boolean;
+      position?: number;
+    }>();
+
+    // Handle rename: if `name` is present and differs, do a full rename
+    if (body.name !== undefined && body.name !== name) {
+      const newName = body.name;
+
+      // Validate new name
+      const validation = validateTableName(newName);
+      if (!validation.valid) {
+        return c.json({ error: validation.reason }, 400);
+      }
+
+      // Check collision
+      if (registry.has(newName)) {
+        return c.json({ error: `Table "${newName}" already exists` }, 409);
+      }
+
+      renameTable(sqlite, registry, name, newName, {
+        label: body.label,
+        display_column: body.display_column,
+        immutable: body.immutable,
+        position: body.position,
+      });
+
+      return c.json({ ok: true, renamed: { from: name, to: newName } });
+    }
+
+    // Non-rename update path (existing behavior)
+    const updates: Record<string, any> = {};
+    if (body.label !== undefined) updates.label = body.label;
+    if (body.display_column !== undefined) updates.display_column = body.display_column;
+    if (body.immutable !== undefined) updates.immutable = body.immutable;
+    if (body.position !== undefined) updates.position = body.position;
+
+    if (Object.keys(updates).length === 0) {
+      return c.json({ error: "No fields to update" }, 400);
+    }
+
+    // Update metadata using buildSetClause to construct the parameterized SET clause.
+    // This replaces the postgres.js `tx(updates)` dynamic SET pattern.
+    const { clause, values } = buildSetClause(updates);
+    sqlite.prepare(
+      `UPDATE _sapporta_tables SET ${clause}, updated_at = datetime('now') WHERE name = ?`
+    ).run(...values, name);
+
+    // Rebuild TableDef to pick up new metadata (label, displayColumn, etc.)
+    const tableDef = rebuildTableDef(sqlite, name, registry);
+    if (tableDef) {
+      registry.register(tableDef, "ui");
+    }
+
+    return c.json({ ok: true });
+  });
+
+  // ── DELETE /tables/:name — Drop a UI-managed table ─────────────────────
+  // No CASCADE. Dropping a table with business data is destructive and
+  // CASCADE could silently destroy FK columns in other tables.
+  app.delete("/tables/:name", async (c) => {
+    const name = c.req.param("name");
+
+    // Guard: reject mutations on file-managed tables
+    const guard = assertUIManaged(name);
+    if (guard) return guard;
+
+    if (!registry.has(name)) {
+      return c.json({ error: `Table "${name}" not found` }, 404);
+    }
+
+    // 1. Check FK dependents: reject if other tables have link columns to this one.
+    //    The user must remove the FK columns first — no silent cascade.
+    const dependents = sqlite.prepare(
+      `SELECT table_name, column_name FROM _sapporta_columns WHERE references_table = ?`
+    ).all(name) as { table_name: string; column_name: string }[];
+
+    if (dependents.length > 0) {
+      const refs = dependents.map((d) => `${d.table_name}.${d.column_name}`);
+      return c.json(
+        {
+          error: `Cannot drop "${name}": referenced by ${refs.join(", ")}. Remove the FK columns first.`,
+          dependents: refs,
+        },
+        409,
+      );
+    }
+
+    // 2. Check row count: require explicit confirmation for tables with data.
+    //    Without ?confirm=true, return 409 with the count and a message.
+    const countRow = sqlite.prepare(`SELECT COUNT(*) AS cnt FROM "${name}"`).get() as { cnt: number };
+    const rowCount = countRow?.cnt ?? 0;
+
+    if (rowCount > 0 && c.req.query("confirm") !== "true") {
+      return c.json(
+        {
+          error: `Table "${name}" has ${rowCount} row(s). Pass ?confirm=true to confirm deletion.`,
+          rowCount,
+        },
+        409,
+      );
+    }
+
+    // 3. Transactional: DROP TABLE + delete metadata.
+    //    _sapporta_columns rows cascade from the metadata FK (ON DELETE CASCADE).
+    const dropTxn = sqlite.transaction(() => {
+      sqlite.exec(`DROP TABLE "${name}"`);
+      sqlite.prepare(`DELETE FROM _sapporta_tables WHERE name = ?`).run(name);
+    });
+    dropTxn();
+
+    // 4. Remove from in-memory registry
+    registry.unregister(name);
+
+    return c.json({ ok: true, dropped: name });
+  });
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Columns
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  // ── POST /tables/:name/columns — Add a column ──────────────────────────
+  app.post("/tables/:name/columns", async (c) => {
+    const tableName = c.req.param("name");
+
+    // Guard: reject mutations on file-managed tables
+    const guard = assertUIManaged(tableName);
+    if (guard) return guard;
+
+    if (!registry.has(tableName)) {
+      return c.json({ error: `Table "${tableName}" not found` }, 404);
+    }
+
+    const body = await c.req.json<{
+      column_name: string;
+      column_type?: string;
+      not_null?: boolean;
+      is_unique?: boolean;
+      default_value?: string;
+      references_table?: string;
+      select_options?: string[];
+      ui_hints?: Record<string, unknown>;
+      position?: number;
+    }>();
+
+    // 1. Validate column name
+    const nameCheck = validateColumnName(body.column_name);
+    if (!nameCheck.valid) {
+      return c.json({ error: nameCheck.reason }, 400);
+    }
+
+    // 2. Validate column type
+    const colType = body.column_type ?? "text";
+    if (!VALID_COLUMN_TYPES.has(colType)) {
+      return c.json(
+        { error: `Invalid column type "${colType}". Valid types: ${[...VALID_COLUMN_TYPES].join(", ")}` },
+        400,
+      );
+    }
+
+    // 3. Validate link columns have a references_table
+    if (colType === "link" && !body.references_table) {
+      return c.json({ error: "Link columns require a references_table" }, 400);
+    }
+
+    // 4. Validate the FK target exists
+    if (colType === "link" && body.references_table && !registry.has(body.references_table)) {
+      return c.json(
+        { error: `FK target "${body.references_table}" does not exist` },
+        400,
+      );
+    }
+
+    // 5. If NOT NULL and the table has existing rows, require a default_value.
+    //    We don't guess type-appropriate zero values — the user must be explicit.
+    if (body.not_null) {
+      const countRow = sqlite.prepare(`SELECT COUNT(*) AS cnt FROM "${tableName}"`).get() as { cnt: number };
+      const rowCount = countRow?.cnt ?? 0;
+      if (rowCount > 0 && body.default_value === undefined) {
+        return c.json(
+          { error: `Cannot add NOT NULL column without a default_value — table has ${rowCount} existing row(s)` },
+          400,
+        );
+      }
+    }
+
+    // 6. Check for duplicate column name
+    const existing = sqlite.prepare(
+      `SELECT 1 FROM _sapporta_columns WHERE table_name = ? AND column_name = ?`
+    ).get(tableName, body.column_name);
+    if (existing) {
+      return c.json({ error: `Column "${body.column_name}" already exists on "${tableName}"` }, 409);
+    }
+
+    // 7. Determine position: default to max + 1
+    const maxPosRow = sqlite.prepare(
+      `SELECT COALESCE(MAX(position), -1) AS max_pos FROM _sapporta_columns WHERE table_name = ?`
+    ).get(tableName) as { max_pos: number };
+    const position = body.position ?? (maxPosRow.max_pos + 1);
+
+    // Build the column metadata row
+    const colMeta: ColumnMetaRow = {
+      column_name: body.column_name,
+      column_type: colType,
+      position,
+      not_null: body.not_null ?? false,
+      is_unique: body.is_unique ?? false,
+      default_value: body.default_value,
+      references_table: body.references_table,
+      select_options: body.select_options,
+      ui_hints: body.ui_hints ?? {},
+    };
+
+    // 8. Transactional: insert metadata + ALTER TABLE ADD COLUMN.
+    //    SQLite transactions are synchronous — the callback is NOT async.
+    const ddlStatements = generateAddColumnDDL(tableName, colMeta);
+    const addColTxn = sqlite.transaction(() => {
+      insertColumnMeta(sqlite, tableName, colMeta);
+      for (const stmt of ddlStatements) {
+        sqlite.exec(stmt);
+      }
+    });
+    addColTxn();
+
+    // 9. Rebuild TableDef with updated columns and re-register
+    const tableDef = rebuildTableDef(sqlite, tableName, registry);
+    if (tableDef) {
+      registry.register(tableDef, "ui");
+    }
+
+    return c.json({ ok: true, column: body.column_name }, 201);
+  });
+
+  // ── PATCH /tables/:name/columns/:col — Modify a column ─────────────────
+  //
+  // Allowed modifications:
+  // - label / ui_hints (no DDL needed)
+  // - not_null (DDL: ALTER COLUMN SET/DROP NOT NULL — not supported in SQLite, metadata-only)
+  // - default_value (DDL: ALTER COLUMN SET DEFAULT / DROP DEFAULT — not supported in SQLite, metadata-only)
+  // - select_options (no DDL — metadata only)
+  // - column_type — restricted to safe transitions (see SAFE_TYPE_TRANSITIONS)
+  //
+  // NOTE: SQLite's ALTER TABLE is limited — it cannot ALTER COLUMN constraints.
+  // For safe type transitions within the same SQLite storage type (e.g. text → email),
+  // only metadata changes. For transitions that change the underlying type, we
+  // update metadata only since SQLite is dynamically typed and the actual data
+  // is not affected by column type declarations.
+  app.patch("/tables/:name/columns/:col", async (c) => {
+    const tableName = c.req.param("name");
+    const colName = c.req.param("col");
+
+    // Guard
+    const guard = assertUIManaged(tableName);
+    if (guard) return guard;
+
+    if (!registry.has(tableName)) {
+      return c.json({ error: `Table "${tableName}" not found` }, 404);
+    }
+
+    // Verify column exists
+    const colRow = sqlite.prepare(
+      `SELECT column_type, not_null, default_value FROM _sapporta_columns
+       WHERE table_name = ? AND column_name = ?`
+    ).get(tableName, colName) as { column_type: string; not_null: number; default_value: string | null } | undefined;
+
+    if (!colRow) {
+      return c.json({ error: `Column "${colName}" not found on "${tableName}"` }, 404);
+    }
+
+    const body = await c.req.json<{
+      column_name?: string;     // rename column
+      column_type?: string;
+      not_null?: boolean;
+      default_value?: string | null;
+      select_options?: string[];
+      ui_hints?: Record<string, unknown>;
+      position?: number;
+    }>();
+
+    // Collect DDL statements needed (may be zero, one, or multiple)
+    const ddlStatements: string[] = [];
+
+    // Column rename validation
+    if (body.column_name !== undefined && body.column_name !== colName) {
+      const nameCheck = validateColumnName(body.column_name);
+      if (!nameCheck.valid) {
+        return c.json({ error: nameCheck.reason }, 400);
+      }
+      // Check for duplicate
+      const dup = sqlite.prepare(
+        `SELECT 1 FROM _sapporta_columns WHERE table_name = ? AND column_name = ?`
+      ).get(tableName, body.column_name);
+      if (dup) {
+        return c.json({ error: `Column "${body.column_name}" already exists on "${tableName}"` }, 409);
+      }
+      // SQLite supports ALTER TABLE RENAME COLUMN (since 3.25.0, better-sqlite3 ships 3.40+)
+      ddlStatements.push(
+        `ALTER TABLE "${tableName}" RENAME COLUMN "${colName}" TO "${body.column_name}"`
+      );
+    }
+
+    // Type change validation
+    if (body.column_type !== undefined && body.column_type !== colRow.column_type) {
+      if (!VALID_COLUMN_TYPES.has(body.column_type)) {
+        return c.json({ error: `Invalid column type "${body.column_type}"` }, 400);
+      }
+      if (!isTypeSafe(colRow.column_type, body.column_type)) {
+        return c.json(
+          {
+            error: `Cannot change type from "${colRow.column_type}" to "${body.column_type}". ` +
+              `Only safe transitions are allowed (no data loss).`,
+          },
+          400,
+        );
+      }
+
+      // SQLite is dynamically typed — changing the column type declaration
+      // does not require DDL. The actual stored data is unaffected.
+      // We only update the metadata to reflect the new logical type.
+      // No DDL statement needed for type changes in SQLite.
+    }
+
+    // NOT NULL and DEFAULT changes in SQLite:
+    // SQLite's ALTER TABLE cannot modify column constraints (SET NOT NULL,
+    // DROP NOT NULL, SET DEFAULT, DROP DEFAULT). These are metadata-only
+    // changes — the logical constraint is tracked in _sapporta_columns and
+    // enforced by the application layer, not by SQLite DDL.
+
+    // Build metadata updates
+    const metaUpdates: Record<string, any> = {};
+    if (body.column_name !== undefined && body.column_name !== colName) {
+      metaUpdates.column_name = body.column_name;
+    }
+    if (body.column_type !== undefined) metaUpdates.column_type = body.column_type;
+    if (body.not_null !== undefined) metaUpdates.not_null = body.not_null ? 1 : 0;
+    if (body.default_value !== undefined) metaUpdates.default_value = body.default_value;
+    if (body.select_options !== undefined) {
+      metaUpdates.select_options = body.select_options ? JSON.stringify(body.select_options) : null;
+    }
+    if (body.position !== undefined) metaUpdates.position = body.position;
+
+    const uiHintsMerge = body.ui_hints !== undefined ? body.ui_hints : null;
+
+    if (Object.keys(metaUpdates).length === 0 && ddlStatements.length === 0 && uiHintsMerge === null) {
+      return c.json({ error: "No fields to update" }, 400);
+    }
+
+    // Transactional: metadata update + DDL (if any).
+    // ui_hints merge runs BEFORE column_name rename so the WHERE clause
+    // still matches the original column name.
+    const patchColTxn = sqlite.transaction(() => {
+      if (uiHintsMerge !== null) {
+        mergeUiHints(sqlite, tableName, colName, uiHintsMerge);
+      }
+      if (Object.keys(metaUpdates).length > 0) {
+        const { clause, values } = buildSetClause(metaUpdates);
+        sqlite.prepare(
+          `UPDATE _sapporta_columns SET ${clause} WHERE table_name = ? AND column_name = ?`
+        ).run(...values, tableName, colName);
+      }
+      for (const ddl of ddlStatements) {
+        sqlite.exec(ddl);
+      }
+    });
+    patchColTxn();
+
+    // Rebuild + re-register
+    const tableDef = rebuildTableDef(sqlite, tableName, registry);
+    if (tableDef) {
+      registry.register(tableDef, "ui");
+    }
+
+    return c.json({ ok: true });
+  });
+
+  // ── DELETE /tables/:name/columns/:col — Drop a column ──────────────────
+  app.delete("/tables/:name/columns/:col", async (c) => {
+    const tableName = c.req.param("name");
+    const colName = c.req.param("col");
+
+    // Guard
+    const guard = assertUIManaged(tableName);
+    if (guard) return guard;
+
+    if (!registry.has(tableName)) {
+      return c.json({ error: `Table "${tableName}" not found` }, 404);
+    }
+
+    // Verify column exists
+    const colRow = sqlite.prepare(
+      `SELECT 1 FROM _sapporta_columns WHERE table_name = ? AND column_name = ?`
+    ).get(tableName, colName);
+    if (!colRow) {
+      return c.json({ error: `Column "${colName}" not found on "${tableName}"` }, 404);
+    }
+
+    // Transactional: ALTER TABLE DROP COLUMN + delete metadata.
+    // SQLite 3.35.0+ supports ALTER TABLE DROP COLUMN natively.
+    // better-sqlite3 ships with SQLite 3.40+ so this is safe.
+    const dropColTxn = sqlite.transaction(() => {
+      sqlite.exec(`ALTER TABLE "${tableName}" DROP COLUMN "${colName}"`);
+      sqlite.prepare(
+        `DELETE FROM _sapporta_columns WHERE table_name = ? AND column_name = ?`
+      ).run(tableName, colName);
+    });
+    dropColTxn();
+
+    // Rebuild + re-register
+    const tableDef = rebuildTableDef(sqlite, tableName, registry);
+    if (tableDef) {
+      registry.register(tableDef, "ui");
+    }
+
+    return c.json({ ok: true, dropped: colName });
+  });
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // LLM Inference
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  // ── POST /tables/:name/infer — Infer column names/types from sample data ─
+  app.post("/tables/:name/infer", async (c) => {
+    const tableName = c.req.param("name");
+
+    // Guard
+    const guard = assertUIManaged(tableName);
+    if (guard) return guard;
+
+    if (!registry.has(tableName)) {
+      return c.json({ error: `Table "${tableName}" not found` }, 404);
+    }
+
+    // Check if already inferred
+    const tableRow = sqlite.prepare(
+      `SELECT inferred FROM _sapporta_tables WHERE name = ?`
+    ).get(tableName) as { inferred: number } | undefined;
+    if (tableRow && tableRow.inferred) {
+      return c.json({ applied: false, reason: "Already inferred" });
+    }
+
+    const body = await c.req.json<{
+      rows: Record<string, unknown>[];
+    }>();
+
+    if (!body.rows || body.rows.length === 0) {
+      return c.json({ error: "At least one row is required for inference" }, 400);
+    }
+
+    // Get current column metadata
+    const colRows = sqlite.prepare(
+      `SELECT column_name, column_type, ui_hints
+       FROM _sapporta_columns WHERE table_name = ? ORDER BY position`
+    ).all(tableName) as { column_name: string; column_type: string; ui_hints: string }[];
+
+    const columnNames = colRows.map((r) => {
+      const hints = r.ui_hints ? JSON.parse(r.ui_hints) as Record<string, unknown> : null;
+      return hints?.header as string ?? r.column_name;
+    });
+
+    // Call LLM
+    const result = await inferSchema({
+      columns: columnNames,
+      rows: body.rows,
+    });
+
+    if (!result) {
+      return c.json({ applied: false, reason: "Inference returned no results (API key may not be set)" });
+    }
+
+    // Apply changes transactionally.
+    // The inference result contains column renames and type changes.
+    // We apply DDL (RENAME COLUMN) and metadata updates in a single transaction
+    // to ensure atomicity.
+    const inferTxn = sqlite.transaction(() => {
+      // Update table label and mark as inferred
+      sqlite.prepare(
+        `UPDATE _sapporta_tables SET label = ?, inferred = 1, updated_at = datetime('now') WHERE name = ?`
+      ).run(result.table_label, tableName);
+
+      // Apply column renames and type changes
+      for (const [oldName, inferred] of Object.entries(result.columns)) {
+        // Find matching column row
+        const colRow = colRows.find((r) => r.column_name === oldName);
+        if (!colRow) continue;
+
+        const oldColName = colRow.column_name;
+        const newColName = inferred.name;
+        const newType = inferred.type;
+        const newHeader = inferred.header;
+
+        const headerMerge = { header: newHeader };
+
+        if (newColName !== oldColName) {
+          // Check for collision — skip rename if target name already exists
+          const exists = colRows.some((r) =>
+            r.column_name !== oldColName && r.column_name === newColName
+          );
+          if (!exists) {
+            // Rename the actual column in the table
+            sqlite.exec(
+              `ALTER TABLE "${tableName}" RENAME COLUMN "${oldColName}" TO "${newColName}"`
+            );
+            // Update metadata: column_name, column_type, and merge ui_hints
+            mergeUiHints(sqlite, tableName, oldColName, headerMerge);
+            sqlite.prepare(
+              `UPDATE _sapporta_columns SET column_name = ?, column_type = ?
+               WHERE table_name = ? AND column_name = ?`
+            ).run(newColName, newType, tableName, oldColName);
+          }
+        } else {
+          // Just update type and header — no rename needed
+          mergeUiHints(sqlite, tableName, oldColName, headerMerge);
+          sqlite.prepare(
+            `UPDATE _sapporta_columns SET column_type = ?
+             WHERE table_name = ? AND column_name = ?`
+          ).run(newType, tableName, oldColName);
+        }
+
+        // SQLite is dynamically typed — changing column_type in metadata
+        // doesn't require DDL to alter the actual column type. The stored
+        // data is unaffected regardless of the declared type.
+      }
+    });
+    inferTxn();
+
+    // Rebuild TableDef
+    const tableDef = rebuildTableDef(sqlite, tableName, registry);
+    if (tableDef) {
+      registry.register(tableDef, "ui");
+    }
+
+    return c.json({
+      applied: true,
+      table_label: result.table_label,
+      columns: result.columns,
+    });
+  });
+
+  return app;
+}
+
+// ─── Domain Functions ────────────────────────────────────────────────────────
+
+/**
+ * Rename a UI-managed table, updating SQLite, metadata, FK references, and registry.
+ *
+ * Caller is responsible for validating the new name and checking for collisions
+ * before calling this function. All DDL + metadata changes happen in a single
+ * transaction. Registry updates happen only after the transaction commits.
+ *
+ * The rename operation is complex because it must update:
+ * 1. The actual SQLite table name (ALTER TABLE RENAME TO)
+ * 2. The _sapporta_tables metadata row (insert new, copy columns, delete old)
+ * 3. The _sapporta_columns rows (update table_name foreign key)
+ * 4. FK references from other tables pointing to the old name
+ */
+function renameTable(
+  sqlite: Database.Database,
+  registry: SchemaRegistry,
+  oldName: string,
+  newName: string,
+  opts?: { label?: string; display_column?: string; immutable?: boolean; position?: number },
+): void {
+  const renameTxn = sqlite.transaction(() => {
+    // Rename the actual SQLite table
+    sqlite.exec(`ALTER TABLE "${oldName}" RENAME TO "${newName}"`);
+
+    // Insert new metadata row (copy from old with new name/label)
+    if (opts?.label !== undefined) {
+      sqlite.prepare(
+        `INSERT INTO _sapporta_tables (name, label, display_column, immutable, inferred, position)
+         SELECT ?, ?, display_column, immutable, inferred, position
+         FROM _sapporta_tables WHERE name = ?`
+      ).run(newName, opts.label, oldName);
+    } else {
+      sqlite.prepare(
+        `INSERT INTO _sapporta_tables (name, label, display_column, immutable, inferred, position)
+         SELECT ?, label, display_column, immutable, inferred, position
+         FROM _sapporta_tables WHERE name = ?`
+      ).run(newName, oldName);
+    }
+
+    // Move columns to new table name
+    sqlite.prepare(
+      `UPDATE _sapporta_columns SET table_name = ? WHERE table_name = ?`
+    ).run(newName, oldName);
+
+    // Update FK references pointing to the old table
+    sqlite.prepare(
+      `UPDATE _sapporta_columns SET references_table = ? WHERE references_table = ?`
+    ).run(newName, oldName);
+
+    // Delete old metadata row
+    sqlite.prepare(
+      `DELETE FROM _sapporta_tables WHERE name = ?`
+    ).run(oldName);
+
+    // Apply non-rename updates (display_column, immutable, position) if present
+    const extraUpdates: Record<string, any> = {};
+    if (opts?.display_column !== undefined) extraUpdates.display_column = opts.display_column;
+    if (opts?.immutable !== undefined) extraUpdates.immutable = opts.immutable;
+    if (opts?.position !== undefined) extraUpdates.position = opts.position;
+    if (Object.keys(extraUpdates).length > 0) {
+      const { clause, values } = buildSetClause(extraUpdates);
+      sqlite.prepare(
+        `UPDATE _sapporta_tables SET ${clause}, updated_at = datetime('now') WHERE name = ?`
+      ).run(...values, newName);
+    }
+  });
+  renameTxn();
+
+  // Unregister old name, rebuild and register under new name.
+  // This happens AFTER the transaction commits — no partial registry state.
+  registry.unregister(oldName);
+  const tableDef = rebuildTableDef(sqlite, newName, registry);
+  if (tableDef) {
+    registry.register(tableDef, "ui");
+  }
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Insert a column metadata row into _sapporta_columns.
+ *
+ * Handles the JSON serialization of select_options and ui_hints, and the
+ * boolean → integer conversion for not_null and is_unique. Centralizes
+ * the INSERT pattern so all callers (create table, add column) use the
+ * same serialization logic.
+ */
+function insertColumnMeta(
+  sqlite: Database.Database,
+  tableName: string,
+  col: ColumnMetaRow,
+): void {
+  sqlite.prepare(
+    `INSERT INTO _sapporta_columns (
+       table_name, column_name, column_type, position,
+       not_null, is_unique, default_value, references_table,
+       select_options, ui_hints
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  ).run(
+    tableName,
+    col.column_name,
+    col.column_type,
+    col.position,
+    col.not_null ? 1 : 0,
+    col.is_unique ? 1 : 0,
+    col.default_value ?? null,
+    col.references_table ?? null,
+    col.select_options ? JSON.stringify(col.select_options) : null,
+    JSON.stringify(col.ui_hints ?? {}),
+  );
+}
+
+/**
+ * Rebuild a TableDef from current metadata state.
+ *
+ * Used after any mutation to ensure the in-memory TableDef matches the
+ * committed metadata. Reads fresh from the database so we don't accumulate
+ * stale state from incremental in-memory patches.
+ *
+ * The read uses deserializeColumnRow() from sqlite-metadata-io.ts to
+ * correctly parse JSON fields (select_options, ui_hints) and convert
+ * SQLite integers (not_null, is_unique) back to booleans.
+ */
+function rebuildTableDef(
+  sqlite: Database.Database,
+  tableName: string,
+  registry: SchemaRegistry,
+): import("../schema/table.js").TableDef | null {
+  const tableRow = sqlite.prepare(
+    `SELECT name, label, display_column, immutable, inferred, position
+     FROM _sapporta_tables WHERE name = ?`
+  ).get(tableName) as {
+    name: string; label: string; display_column: string | null;
+    immutable: number; inferred: number; position: number;
+  } | undefined;
+
+  if (!tableRow) return null;
+
+  const tableMeta: TableMeta = {
+    name: tableRow.name,
+    label: tableRow.label,
+    display_column: tableRow.display_column ?? undefined,
+    immutable: !!tableRow.immutable,
+    inferred: !!tableRow.inferred,
+    position: tableRow.position,
+  };
+
+  const rawColumns = sqlite.prepare(
+    `SELECT column_name, column_type, position, not_null, is_unique,
+            default_value, references_table, select_options, ui_hints
+     FROM _sapporta_columns WHERE table_name = ? ORDER BY position`
+  ).all(tableName) as RawMetadataColumnRow[];
+
+  // Deserialize each row: JSON parse select_options/ui_hints, convert 0/1 → boolean
+  const columns = rawColumns.map((raw) => deserializeColumnRow(raw));
+
+  return buildDrizzleTable(tableMeta, columns, registry);
+}