@sapporta/server 0.0.1

package/src/schema/metadata-tables.ts

@@ -0,0 +1,341 @@
+/**
+ * Metadata Tables — internal tables that store UI-managed table definitions.
+ *
+ * UI-managed tables are defined by non-programmers through the browser UI.
+ * Their definitions are stored in two internal tables:
+ *
+ *   _sapporta_tables  — one row per UI-managed table (name, label, options)
+ *   _sapporta_columns — one row per column in a UI-managed table
+ *
+ * These are separate from the file-managed schemas (TypeScript files loaded
+ * at boot). The runtime merges both sources: file schemas always win on
+ * collision, UI schemas fill in the rest. This split is why:
+ * - File schemas use pushSQLiteSchema() (Drizzle Kit diff) for migration
+ * - UI schemas use direct DDL from the mutation API
+ * - At boot we only *validate* UI schemas, never auto-migrate them
+ *
+ * The bootstrap function creates these tables idempotently, and the load
+ * function reads them to construct TableDef objects via buildDrizzleTable.
+ *
+ * SQLite differences from the old Postgres version:
+ *   - BOOLEAN → INTEGER (0/1) — SQLite has no native boolean type
+ *   - TIMESTAMPTZ DEFAULT now() → TEXT DEFAULT (datetime('now'))
+ *   - TEXT[] → TEXT (JSON-serialized array, deserialized on read)
+ *   - JSONB → TEXT (JSON string, parsed on read)
+ *   - information_schema → sqlite_master + PRAGMA table_info
+ *   - All operations are synchronous (better-sqlite3)
+ *
+ * Boot sequence invariant: ensureMetadataTables() runs after DB connection
+ * but before schema loading. loadUISchemas() runs after file schemas are
+ * registered in the registry (so FK targets can be resolved).
+ */
+import type Database from "better-sqlite3";
+import type { SchemaRegistry } from "./registry.js";
+import type { TableDef } from "./table.js";
+import {
+  buildDrizzleTable,
+  type TableMeta,
+  type ColumnMetaRow,
+} from "./dynamic-builder.js";
+import {
+  columnExists,
+} from "../introspect/db-helpers.js";
+import { logger } from "../db/logger.js";
+
+const log = logger.child({ module: "metadata" });
+
+// ─── Bootstrap ──────────────────────────────────────────────────────────────
+
+/**
+ * Create the internal metadata tables if they don't exist.
+ *
+ * Called during bootProject(), after DB connection but before schema loading.
+ * Uses sqlite_master to check existence (no information_schema in SQLite).
+ *
+ * All operations are synchronous — better-sqlite3 returns immediately.
+ */
+export function ensureMetadataTables(sqlite: Database.Database): void {
+  const existing = sqlite
+    .prepare(
+      `SELECT name FROM sqlite_master
+       WHERE type = 'table'
+         AND name IN ('_sapporta_tables', '_sapporta_columns')`,
+    )
+    .all() as { name: string }[];
+
+  const existingNames = new Set(existing.map((r) => r.name));
+
+  if (!existingNames.has("_sapporta_tables")) {
+    sqlite.exec(`
+      CREATE TABLE _sapporta_tables (
+        name            TEXT PRIMARY KEY,
+        label           TEXT,
+        display_column  TEXT,
+        immutable       INTEGER NOT NULL DEFAULT 0,
+        inferred        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'))
+      )
+    `);
+  } else {
+    // Migration: add inferred column if it doesn't exist yet.
+    // Same migration path as the old Postgres version for schema compatibility.
+    if (!columnExists(sqlite, "_sapporta_tables", "inferred")) {
+      sqlite.exec(
+        `ALTER TABLE _sapporta_tables ADD COLUMN inferred INTEGER NOT NULL DEFAULT 0`,
+      );
+    }
+  }
+
+  if (!existingNames.has("_sapporta_columns")) {
+    // select_options is TEXT (JSON-serialized array) — no native TEXT[] in SQLite
+    // ui_hints is TEXT (JSON string) — no native JSONB in SQLite
+    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)
+      )
+    `);
+  }
+}
+
+// ─── Load UI Schemas ────────────────────────────────────────────────────────
+
+/**
+ * Load UI-managed table definitions from the metadata tables.
+ *
+ * Reads _sapporta_tables + _sapporta_columns, deserializes JSON fields
+ * (select_options, ui_hints), then calls buildDrizzleTable() for each
+ * table to produce runtime TableDef objects.
+ *
+ * The registry is passed through for FK target resolution — by the time
+ * this runs, file-managed schemas are already registered (see boot
+ * sequence in runtime.ts).
+ *
+ * Critical JSON deserialization: select_options is stored as a JSON string
+ * in SQLite (not a native array like Postgres TEXT[]). Similarly, ui_hints
+ * is a JSON string, not native JSONB. Both are deserialized on read.
+ */
+export function loadUISchemas(
+  sqlite: Database.Database,
+  registry: SchemaRegistry,
+): TableDef[] {
+  const tableRows = sqlite
+    .prepare(
+      `SELECT name, label, display_column, immutable, inferred, position
+       FROM _sapporta_tables
+       ORDER BY position, created_at`,
+    )
+    .all() as {
+    name: string;
+    label: string | null;
+    display_column: string | null;
+    immutable: number;
+    inferred: number;
+    position: number;
+  }[];
+
+  if (tableRows.length === 0) return [];
+
+  // Load all columns in one query (N+1 prevention), then group by table.
+  const columnRows = sqlite
+    .prepare(
+      `SELECT table_name, column_name, column_type, position,
+              not_null, is_unique, default_value, references_table,
+              select_options, ui_hints
+       FROM _sapporta_columns
+       ORDER BY table_name, position`,
+    )
+    .all() as {
+    table_name: string;
+    column_name: string;
+    column_type: string;
+    position: number;
+    not_null: number;
+    is_unique: number;
+    default_value: string | null;
+    references_table: string | null;
+    select_options: string | null; // JSON string, not native array
+    ui_hints: string; // JSON string, not native JSONB
+  }[];
+
+  // Group columns by table name
+  const columnsByTable = new Map<string, ColumnMetaRow[]>();
+  for (const row of columnRows) {
+    if (!columnsByTable.has(row.table_name)) {
+      columnsByTable.set(row.table_name, []);
+    }
+
+    // Deserialize JSON fields: SQLite stores arrays and objects as TEXT,
+    // unlike Postgres which natively handles TEXT[] and JSONB.
+    columnsByTable.get(row.table_name)!.push({
+      column_name: row.column_name,
+      column_type: row.column_type,
+      position: row.position,
+      not_null: row.not_null === 1,       // INTEGER 0/1 → boolean
+      is_unique: row.is_unique === 1,     // INTEGER 0/1 → boolean
+      default_value: row.default_value ?? undefined,
+      references_table: row.references_table ?? undefined,
+      select_options: row.select_options
+        ? JSON.parse(row.select_options)   // TEXT → string[]
+        : undefined,
+      ui_hints: row.ui_hints ? JSON.parse(row.ui_hints) : {},  // TEXT → Record
+    });
+  }
+
+  // Build a TableDef for each metadata table
+  const defs: TableDef[] = [];
+  for (const row of tableRows) {
+    const tableMeta: TableMeta = {
+      name: row.name,
+      label: row.label ?? undefined,
+      display_column: row.display_column ?? undefined,
+      immutable: row.immutable === 1,     // INTEGER 0/1 → boolean
+      inferred: row.inferred === 1,       // INTEGER 0/1 → boolean
+      position: row.position,
+    };
+
+    const columns = columnsByTable.get(tableMeta.name) ?? [];
+    const def = buildDrizzleTable(tableMeta, columns, registry);
+    defs.push(def);
+  }
+
+  return defs;
+}
+
+// ─── Boot Validation ────────────────────────────────────────────────────────
+
+/**
+ * Validate UI-managed tables by comparing metadata against actual DB state.
+ *
+ * Uses sqlite_master instead of information_schema.tables, and PRAGMA
+ * table_info instead of information_schema.columns.
+ *
+ * Why validate instead of auto-migrate? File-managed tables use
+ * pushSQLiteSchema() (Drizzle Kit diff) because the developer controls
+ * the schema. UI-managed tables were created at runtime via direct DDL.
+ * Running pushSQLiteSchema() on them risks destructive ALTER statements
+ * if metadata drifts. Instead, we compare and warn — the user or admin
+ * can fix drift manually.
+ *
+ * Also checks for dangling FK references (link columns pointing to tables
+ * that don't exist in the registry).
+ */
+export function validateUISchemas(
+  sqlite: Database.Database,
+  registry: SchemaRegistry,
+  slug: string,
+): void {
+  const uiDefs = registry.uiManaged();
+  if (uiDefs.length === 0) return;
+
+  for (const def of uiDefs) {
+    // Check that the actual DB table exists via sqlite_master
+    const tableCheck = sqlite
+      .prepare(
+        `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?`,
+      )
+      .get(def.sqlName);
+
+    if (!tableCheck) {
+      log.warn(
+        `UI-managed table "${def.sqlName}" exists in metadata but not in database. ` +
+          `Removing from registry. Delete from _sapporta_tables to clean up metadata.`,
+        { project: slug, table: def.sqlName },
+      );
+      registry.unregister(def.sqlName);
+      continue;
+    }
+
+    // Compare expected columns (metadata) against actual columns (PRAGMA table_info)
+    const actualColumns = sqlite.pragma(
+      `table_info("${def.sqlName}")`,
+    ) as { name: string; type: string; notnull: number }[];
+
+    const actualColMap = new Map<
+      string,
+      { type: string; notnull: number }
+    >();
+    for (const col of actualColumns) {
+      actualColMap.set(col.name, {
+        type: col.type,
+        notnull: col.notnull,
+      });
+    }
+
+    // Load expected columns from metadata
+    const expectedColumns = sqlite
+      .prepare(
+        `SELECT column_name, column_type, not_null
+         FROM _sapporta_columns
+         WHERE table_name = ?`,
+      )
+      .all(def.sqlName) as {
+      column_name: string;
+      column_type: string;
+      not_null: number;
+    }[];
+
+    for (const expected of expectedColumns) {
+      const actual = actualColMap.get(expected.column_name);
+      if (!actual) {
+        log.warn("Column drift: exists in metadata but not in database", {
+          project: slug,
+          table: def.sqlName,
+          column: expected.column_name,
+        });
+      }
+    }
+
+    // Check actual columns not in metadata (excluding system columns)
+    const systemCols = new Set(["id", "created_at", "updated_at"]);
+    const expectedNames = new Set(
+      expectedColumns.map((c) => c.column_name),
+    );
+    for (const [colName] of actualColMap) {
+      if (!systemCols.has(colName) && !expectedNames.has(colName)) {
+        log.warn("Column drift: exists in database but not in metadata", {
+          project: slug,
+          table: def.sqlName,
+          column: colName,
+        });
+      }
+    }
+  }
+
+  // Check for dangling FK references across all UI-managed tables.
+  // A dangling FK is a "link" column whose references_table doesn't exist
+  // in the registry (neither as a file-managed nor UI-managed table).
+  const linkColumns = sqlite
+    .prepare(
+      `SELECT table_name, column_name, references_table
+       FROM _sapporta_columns
+       WHERE column_type = 'link' AND references_table IS NOT NULL`,
+    )
+    .all() as {
+    table_name: string;
+    column_name: string;
+    references_table: string;
+  }[];
+
+  for (const row of linkColumns) {
+    if (!registry.has(row.references_table)) {
+      log.warn("Dangling FK reference", {
+        project: slug,
+        table: row.table_name,
+        column: row.column_name,
+        referencesTable: row.references_table,
+      });
+    }
+  }
+}

package/src/schema/migrate.ts

@@ -0,0 +1,195 @@
+// ============================================================================
+// SQLite Schema Migration — push schema changes via drizzle-kit/api
+// ============================================================================
+//
+// drizzle-kit/api verification results (Step 1.2):
+//   - Export: pushSQLiteSchema (separate function from pushSchema)
+//   - Signature: pushSQLiteSchema(imports, drizzleInstance)
+//     - imports: Record<string, SQLiteTable> (flat object of table names → Drizzle objects)
+//     - drizzleInstance: BetterSQLite3Database (uses .all() and .run() internally)
+//   - Returns: { hasDataLoss, warnings, statementsToExecute: string[], apply() }
+//   - NO tablesFilter parameter (unlike Postgres pushSchema which has one)
+//   - apply() executes ALL statementsToExecute — we don't call it, we execute
+//     filtered statements manually to skip destructive DROPs
+//
+// Differences from the old Postgres migrate.ts:
+//   - No PgEnum parameter (SQLite has no native enums)
+//   - No db.execute(sql.raw()) proxy wrapper (SQLite Drizzle doesn't have
+//     the Postgres res.rows compatibility issue)
+//   - sqlite.exec(stmt) for direct DDL execution instead of db.execute()
+//   - DROP SEQUENCE/DROP TYPE patterns removed (SQLite doesn't have these)
+//   - No tablesFilter — pushSQLiteSchema introspects ALL tables in the DB,
+//     so the destructive DROP filter is the only defense against dropping
+//     UI-managed tables. This is adequate because:
+//       1. The statement filter catches DROP TABLE for UI tables
+//       2. SQLite has no sequences or custom types to produce spurious DROPs
+//
+// Same two-layer safety philosophy as the old Postgres version, but Layer 1
+// (tablesFilter) is unavailable, so Layer 2 (statement filter) is the
+// primary defense.
+
+import type Database from "better-sqlite3";
+import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+import { pushSQLiteSchema } from "drizzle-kit/api";
+import type { TableDef } from "./table.js";
+import { logger } from "../db/logger.js";
+
+const log = logger.child({ module: "schema" });
+
+/**
+ * Matches destructive DROP statements that should never be auto-executed.
+ *
+ * Only top-level DROP TABLE and DROP INDEX are relevant for SQLite.
+ * ALTER TABLE ... DROP COLUMN is intentionally NOT matched — dropping
+ * a column is a legitimate schema change when a developer removes it
+ * from a file-managed table definition.
+ */
+const DESTRUCTIVE_DROP = [/^DROP\s+TABLE\b/i, /^DROP\s+INDEX\b/i];
+
+function isDestructiveDrop(stmt: string): boolean {
+  return DESTRUCTIVE_DROP.some((re) => re.test(stmt.trimStart()));
+}
+
+/**
+ * Push file-managed schema changes to the SQLite database.
+ *
+ * ## Safety: no tablesFilter available
+ *
+ * Unlike Postgres's pushSchema which accepts a tablesFilter for positive
+ * inclusion, pushSQLiteSchema introspects ALL tables in the database.
+ * This means UI-managed tables appear as "extra" and generate DROP TABLE
+ * statements. The destructive statement filter is the sole defense:
+ * it strips all DROP TABLE/DROP INDEX before execution.
+ *
+ * This is safe because:
+ * 1. UI-managed tables are created via direct DDL, not schema push
+ * 2. The only way a DROP TABLE appears is if a table exists in DB but
+ *    not in the schema objects — which is exactly the UI-managed case
+ * 3. SQLite has no sequences or custom types that could cause spurious DROPs
+ *
+ * ## Caller invariant
+ *
+ * The `schemas` parameter must contain only file-managed tables.
+ * The caller passes registry.fileManaged(), not registry.all().
+ *
+ * @returns Object with applied and skipped statement lists for logging.
+ */
+export async function migrateSchemas(
+  schemas: TableDef[],
+  db: BetterSQLite3Database,
+  sqlite: Database.Database,
+): Promise<{ applied: string[]; skipped: string[] }> {
+  if (schemas.length === 0) {
+    log.info("Schema is up to date");
+    return { applied: [], skipped: [] };
+  }
+
+  // Build the imports record: flat object of { tableName: DrizzleTable }
+  const imports: Record<string, unknown> = {};
+  for (const schema of schemas) {
+    imports[schema.sqlName] = schema.drizzle;
+  }
+
+  // IMPORTANT: Temporarily remove non-schema tables from the database
+  // before calling pushSQLiteSchema.
+  //
+  // pushSQLiteSchema introspects ALL tables in the database. If it finds
+  // tables that aren't in the schema definition (like _sapporta_tables,
+  // _sapporta_columns, or UI-managed tables), it triggers an interactive
+  // prompt asking whether each new schema table should be created fresh or
+  // renamed from an existing table. This prompt hangs in non-interactive
+  // environments (tests, CI, automated deploys).
+  //
+  // The workaround: save the DDL + data for non-schema tables, drop them,
+  // run pushSQLiteSchema on a clean DB, then restore. SQLite makes this
+  // safe because all operations are synchronous and single-threaded — no
+  // concurrent access can observe the temporary state.
+  const schemaTableNames = new Set(Object.keys(imports));
+  const allTables = sqlite.prepare(
+    `SELECT name, sql FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'`
+  ).all() as { name: string; sql: string }[];
+
+  // Save state of tables that aren't part of the file-managed schema
+  const hiddenTables: { name: string; ddl: string; rows: unknown[] }[] = [];
+  for (const { name, sql: ddl } of allTables) {
+    if (!schemaTableNames.has(name)) {
+      // Save the CREATE TABLE DDL and all rows
+      const rows = sqlite.prepare(`SELECT * FROM "${name}"`).all();
+      hiddenTables.push({ name, ddl, rows });
+    }
+  }
+
+  // Drop non-schema tables so pushSQLiteSchema doesn't see them.
+  // Order matters: drop child tables (with FK references) before parents.
+  // Temporarily disable FK checks to avoid constraint violations during drop.
+  sqlite.pragma("foreign_keys = OFF");
+  for (const { name } of hiddenTables) {
+    sqlite.exec(`DROP TABLE "${name}"`);
+  }
+  sqlite.pragma("foreign_keys = ON");
+
+  let result;
+  try {
+    // Cast to any: drizzle-kit's type declarations expect LibSQLDatabase
+    // but the runtime implementation only uses .all() and .run() which
+    // BetterSQLite3Database provides. Verified working in Step 1.2 spike.
+    result = await pushSQLiteSchema(imports, db as any);
+  } finally {
+    // Restore hidden tables regardless of success/failure.
+    // Disable FK checks during restore to handle any FK ordering issues.
+    sqlite.pragma("foreign_keys = OFF");
+    for (const { name, ddl, rows } of hiddenTables) {
+      sqlite.exec(ddl);
+      if (rows.length > 0) {
+        // Rebuild INSERT from row data. Use the column names from the first row.
+        const cols = Object.keys(rows[0] as Record<string, unknown>);
+        const placeholders = cols.map(() => "?").join(", ");
+        const insertStmt = sqlite.prepare(
+          `INSERT INTO "${name}" (${cols.map(c => `"${c}"`).join(", ")}) VALUES (${placeholders})`
+        );
+        const insertAll = sqlite.transaction((data: unknown[]) => {
+          for (const row of data) {
+            const values = cols.map(c => (row as Record<string, unknown>)[c]);
+            insertStmt.run(...values);
+          }
+        });
+        insertAll(rows);
+      }
+    }
+    sqlite.pragma("foreign_keys = ON");
+  }
+
+  if (result.warnings.length > 0) {
+    log.warn("Schema migration warnings", { warnings: result.warnings });
+  }
+
+  // Filter destructive statements — primary defense since no tablesFilter
+  const safe: string[] = [];
+  const skipped: string[] = [];
+  for (const stmt of result.statementsToExecute) {
+    if (isDestructiveDrop(stmt)) {
+      skipped.push(stmt);
+    } else {
+      safe.push(stmt);
+    }
+  }
+
+  if (skipped.length > 0) {
+    log.warn("Skipped destructive statements", { statements: skipped });
+  }
+
+  if (safe.length > 0) {
+    log.info(`Applying ${safe.length} schema change(s)`);
+    // Execute each statement via better-sqlite3's synchronous exec().
+    // Unlike the old Postgres version which used db.execute(sql.raw()) for
+    // PGlite compatibility, SQLite always has exec() available.
+    for (const stmt of safe) {
+      sqlite.exec(stmt);
+    }
+    log.info("Schema migration complete");
+  } else {
+    log.info("Schema is up to date");
+  }
+
+  return { applied: safe, skipped };
+}

package/src/schema/normalize-datatype.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest";
+import { normalizeDataType, isDateObjectMode } from "./normalize-datatype.js";
+
+describe("normalizeDataType", () => {
+  // Drizzle reports date/timestamp columns as dataType:"string", but
+  // the UI needs "date" for date pickers and formatters. These tests
+  // cover the override path; non-date types pass through unchanged.
+
+  it("Pg PgDateString → date (overrides Drizzle's 'string')", () => {
+    expect(normalizeDataType({ columnType: "PgDateString", dataType: "string" })).toBe("date");
+  });
+
+  it("Pg PgTimestampString → date (overrides Drizzle's 'string')", () => {
+    expect(normalizeDataType({ columnType: "PgTimestampString", dataType: "string" })).toBe("date");
+  });
+
+  it("Pg PgTimestamp (Date mode) → date", () => {
+    expect(normalizeDataType({ columnType: "PgTimestamp", dataType: "date" })).toBe("date");
+  });
+
+  it("Pg PgDate → date (overrides Drizzle's 'string')", () => {
+    expect(normalizeDataType({ columnType: "PgDate", dataType: "string" })).toBe("date");
+  });
+
+  it("SQLite timestamp → date (matched by columnType, not dataType)", () => {
+    expect(normalizeDataType({ columnType: "SQLiteTimestamp", dataType: "date" })).toBe("date");
+  });
+
+  // Non-date types fall through to Drizzle's dataType unchanged.
+
+  it("unknown columnType falls through to dataType", () => {
+    expect(normalizeDataType({ columnType: "SomeFutureType", dataType: "string" })).toBe("string");
+    expect(normalizeDataType({ columnType: "SomeFutureType", dataType: "number" })).toBe("number");
+    expect(normalizeDataType({ columnType: "SomeFutureType", dataType: "boolean" })).toBe("boolean");
+  });
+});
+
+describe("isDateObjectMode", () => {
+  it("PgTimestamp (default mode) returns Date objects", () => {
+    expect(isDateObjectMode({ columnType: "PgTimestamp" })).toBe(true);
+  });
+
+  it("PgTimestampString (string mode) does NOT return Date objects", () => {
+    expect(isDateObjectMode({ columnType: "PgTimestampString" })).toBe(false);
+  });
+
+  it("SQLiteTimestamp (mode: timestamp) returns Date objects", () => {
+    expect(isDateObjectMode({ columnType: "SQLiteTimestamp" })).toBe(true);
+  });
+
+  it("SQLiteText does NOT return Date objects", () => {
+    expect(isDateObjectMode({ columnType: "SQLiteText" })).toBe(false);
+  });
+
+  it("SQLiteInteger does NOT return Date objects", () => {
+    expect(isDateObjectMode({ columnType: "SQLiteInteger" })).toBe(false);
+  });
+});

package/src/schema/normalize-datatype.ts

@@ -0,0 +1,99 @@
+// ============================================================================
+// Database-agnostic column type normalization
+// ============================================================================
+//
+// Drizzle's internal columnType and dataType strings differ between
+// Postgres and SQLite:
+//
+//   Postgres:
+//     PgTimestampString  → dataType "string"  (mode: "string")
+//     PgTimestamp         → dataType "date"    (default mode, returns Date objects)
+//     PgDateString        → dataType "string"
+//     PgDate              → dataType "string"
+//     PgNumeric           → dataType "string"  (Postgres NUMERICs are strings in JS)
+//     PgBoolean           → dataType "boolean"
+//
+//   SQLite:
+//     SQLiteText          → dataType "string"
+//     SQLiteInteger       → dataType "number"
+//     SQLiteReal          → dataType "number"
+//     SQLiteBoolean       → dataType "boolean" (mode: "boolean")
+//     SQLiteTimestamp     → dataType "date"    (mode: "timestamp", returns Date objects)
+//
+// The UI needs stable, dialect-agnostic dataType values for formatting.
+// This module provides the single point of truth for that normalization.
+//
+// The current callers that do ad-hoc columnType checks:
+//   - extract.ts: PgDateString, PgDate, PgTimestampString → "date"
+//   - check.ts: PgTimestamp for Date-object-mode warning
+//   - validate.ts: PgTimestampString recognition
+//
+// This module centralizes those checks and extends them to SQLite types.
+
+/**
+ * Drizzle columnType values that represent date/timestamp columns.
+ *
+ * These are the columnType strings where the UI should use "date" formatting
+ * regardless of what Drizzle reports as dataType. The set covers:
+ *   - Postgres timestamp/date columns in string mode (dataType = "string")
+ *   - Postgres timestamp in Date mode (dataType = "date", but we normalize anyway)
+ *   - SQLite timestamp (already dataType = "date" via mode: "timestamp")
+ */
+const DATE_COLUMN_TYPES = new Set([
+  // Postgres — string-mode timestamps report dataType "string" in Drizzle,
+  // but the UI needs "date" for display formatting. See timestamp() in table.ts.
+  "PgDateString",
+  "PgDate",
+  "PgTimestampString",
+  "PgTimestamp",
+  // SQLite — already returns dataType "date", but included for completeness
+  "SQLiteTimestamp",
+]);
+
+/**
+ * Derive a stable, UI-facing dataType from Drizzle's column metadata.
+ *
+ * Priority order:
+ * 1. Known date/timestamp columnTypes (dialect-specific but harmless to check both)
+ * 2. Fall through to Drizzle's own dataType (works for most types)
+ *
+ * The returned string is one of: "string", "number", "boolean", "date"
+ * These map directly to UI formatting strategies.
+ */
+export function normalizeDataType(col: {
+  columnType: string;
+  dataType: string;
+}): string {
+  // Known date/timestamp types — overrides Drizzle's dataType which may be
+  // "string" for string-mode Pg timestamps, or already "date" for others
+  if (DATE_COLUMN_TYPES.has(col.columnType)) return "date";
+
+  // Fall through to Drizzle's reported dataType.
+  // This handles: "string", "number", "boolean", "date" (SQLiteTimestamp, PgTimestamp)
+  return col.dataType;
+}
+
+/**
+ * Detect if a column uses Date-object mode (not string mode).
+ *
+ * Used by schema checking to warn about non-JSON-safe timestamp modes.
+ * Sapporta is a JSON-over-HTTP framework — Date objects don't serialize
+ * cleanly across HTTP boundaries. The mode: "string" timestamp helper
+ * (table.ts) exists to avoid this, so finding Date-mode columns is a
+ * schema error that should be flagged.
+ *
+ * Date-object mode columns:
+ *   Postgres: PgTimestamp (default mode) returns Date objects
+ *   SQLite:   SQLiteTimestamp (mode: "timestamp") returns Date objects
+ */
+export function isDateObjectMode(col: {
+  columnType: string;
+}): boolean {
+  // PgTimestamp is the default-mode Postgres timestamp — returns Date objects.
+  // PgTimestampString is the string-mode variant — returns ISO strings (safe).
+  if (col.columnType === "PgTimestamp") return true;
+  // SQLiteTimestamp with mode: "timestamp" returns Date objects.
+  // (SQLite stores as integer epoch, Drizzle converts to Date on read.)
+  if (col.columnType === "SQLiteTimestamp") return true;
+  return false;
+}