@michaelthielemann/kestrel 1.2.1

package/layers/core/server/schema/desired.ts

@@ -0,0 +1,99 @@
+import { getTableConfig, SQLiteSyncDialect, type SQLiteTable } from 'drizzle-orm/sqlite-core'
+import { SQL, is } from 'drizzle-orm'
+import { resolveColumnName, toSnakeCase } from '../../../fields/server/field-registry/naming'
+import type { CollectionDef } from '../utils/defineCollection'
+import { fieldIs } from '../utils/defineCollection'
+import type { ColumnShape, IndexShape, TableShape, SchemaSnapshot } from './model'
+
+// Build the *desired* schema snapshot from the Drizzle tables that collections compile to (the
+// counterpart to introspect's *actual* snapshot). Reads drizzle's table metadata via getTableConfig and
+// normalizes it into the same model `diffSchema` consumes (ADR-0002).
+
+const dialect = new SQLiteSyncDialect()
+const sqlText = (value: SQL) => dialect.sqlToQuery(value).sql
+
+/** Map a Drizzle column default to its raw DDL token: a `sql\`…\`` default renders verbatim, a JS literal is quoted. */
+export function defaultToken(value: unknown): string | null {
+  if (value === undefined || value === null) return null
+  if (is(value, SQL)) return sqlText(value)
+  if (typeof value === 'string') return `'${value.replace(/'/g, "''")}'`
+  if (typeof value === 'boolean') return value ? '1' : '0'
+  // Object / array default (a json-backed column — e.g. a custom field type): emit a quoted JSON string
+  // literal, matching how json/repeater columns default via sql`'{}'`. Else String({}) → "[object Object]".
+  if (typeof value === 'object') return `'${JSON.stringify(value).replace(/'/g, "''")}'`
+  return String(value)
+}
+
+export function desiredTable(table: SQLiteTable, def?: CollectionDef): TableShape {
+  const cfg = getTableConfig(table)
+
+  // new column name -> old column name (and any single↔multiple shape transform). Two sources:
+  //  - an explicit `renamedFrom` field hint (same field type → same naming rule for both keys);
+  //  - a relation/media field, which maps to its opposite-multiplicity column name (`<col>` ↔ `<col>_id`)
+  //    so toggling `multiple`/`many` renames + reshapes the data instead of dropping it. Inert unless the
+  //    opposite column actually exists in the live DB.
+  const renames = new Map<string, string>()
+  const transforms = new Map<string, 'wrap' | 'unwrap'>()
+  if (def) {
+    for (const [key, field] of Object.entries(def.fields)) {
+      if (field.renamedFrom) {
+        renames.set(resolveColumnName(key, field).dbName, resolveColumnName(field.renamedFrom, field).dbName)
+        continue
+      }
+      if (fieldIs(field, 'media') || fieldIs(field, 'relation')) {
+        const multiple = fieldIs(field, 'media') ? field.options?.multiple === true : field.relation.many === true
+        const base = toSnakeCase(key)
+        const col = multiple ? base : `${base}_id`
+        renames.set(col, multiple ? `${base}_id` : base)
+        transforms.set(col, multiple ? 'wrap' : 'unwrap')
+      }
+    }
+  }
+
+  const columns: ColumnShape[] = cfg.columns.map((c) => ({
+    name: c.name,
+    type: c.getSQLType(),
+    notNull: c.notNull,
+    primaryKey: c.primary,
+    autoIncrement: (c as unknown as { autoIncrement?: boolean }).autoIncrement === true,
+    default: defaultToken(c.default),
+    ...(renames.has(c.name) ? { renamedFrom: renames.get(c.name) } : {}),
+    ...(transforms.has(c.name) ? { renameTransform: transforms.get(c.name) } : {}),
+  }))
+
+  const indexes: IndexShape[] = cfg.indexes.map((i) => {
+    const cfgI = i.config as unknown as { name: string; unique: boolean; columns: { name: string }[]; where?: SQL }
+    return {
+      name: cfgI.name,
+      table: cfg.name,
+      columns: cfgI.columns.map((x) => x.name),
+      unique: cfgI.unique,
+      where: cfgI.where ? sqlText(cfgI.where) : null,
+    }
+  })
+
+  // A column-level `.unique()` is materialized by drizzle-kit as a named unique index
+  // (`<table>_<column>_unique`) — surface it the same way so introspect's view and ours agree.
+  for (const c of cfg.columns) {
+    const u = c as unknown as { isUnique?: boolean; uniqueName?: string }
+    if (u.isUnique) {
+      indexes.push({ name: u.uniqueName ?? `${cfg.name}_${c.name}_unique`, table: cfg.name, columns: [c.name], unique: true, where: null })
+    }
+  }
+
+  return { name: cfg.name, columns, indexes }
+}
+
+/**
+ * Build a full desired snapshot from a set of Drizzle tables (registered collections + standalone tables).
+ * `defsByName` supplies each collection's def so `renamedFrom` field hints become column renames; tables
+ * without a def (e.g. `folders`) simply carry no renames.
+ */
+export function desiredSchema(tables: SQLiteTable[], defsByName?: Map<string, CollectionDef>): SchemaSnapshot {
+  const snapshot: SchemaSnapshot = {}
+  for (const table of tables) {
+    const shape = desiredTable(table, defsByName?.get(getTableConfig(table).name))
+    snapshot[shape.name] = shape
+  }
+  return snapshot
+}

package/layers/core/server/schema/dev-sync.ts

@@ -0,0 +1,23 @@
+import { syncSchema, describeOp, type SyncDb } from './sync'
+import { sqlite, type Dialect } from './dialect'
+import type { SchemaSnapshot } from './model'
+
+/**
+ * The body of the dev-only schema auto-sync plugin, isolated so a failure can NEVER take down the whole
+ * server. syncSchema throws by design on an infeasible migration (and on any transient DDL error); if
+ * that escaped the Nitro plugin it would 500 every route — including the admin UI needed to diagnose it.
+ * Here we log loudly and let the server keep running on the previous schema. The operator-triggered
+ * db:migrate task is one-shot and keeps failing hard; only this always-on plugin must isolate.
+ */
+export function runDevSchemaSync(client: SyncDb, desired: SchemaSnapshot, dialect: Dialect = sqlite): void {
+  try {
+    const { applied, skipped } = syncSchema(client, desired, {}, dialect)
+    if (applied.length) console.info(`[kestrel] dev schema auto-sync applied ${applied.length} statement(s)`)
+    // Destructive changes are never auto-applied — name them so the data loss is visible before opting in.
+    if (skipped.length) {
+      console.warn(`[kestrel] ${skipped.length} destructive schema change(s) detected — not auto-applied:\n  - ${skipped.map(describeOp).join('\n  - ')}\n  apply with the db:migrate task ({ force: true }) — dev: GET /_nitro/tasks/db:migrate, prod: runTask('db:migrate', { payload: { force: true } })`)
+    }
+  } catch (err) {
+    console.error('[kestrel] dev schema auto-sync FAILED — the server keeps running on the PREVIOUS schema; fix the collection or its data and restart:\n ', err instanceof Error ? err.message : err)
+  }
+}

package/layers/core/server/schema/dialect.ts

@@ -0,0 +1,59 @@
+import type { SchemaSnapshot, SchemaOp } from './model'
+import type { IntrospectDb } from './introspect'
+import { introspect } from './introspect'
+import { renderSqlite } from './render-sqlite'
+
+// The dialect seam (ADR-0002). `model.ts` + `diffSchema` are dialect-agnostic: a diff is computed as a
+// `SchemaOp[]` over the normalized model, independent of any database. A `Dialect` is what binds that
+// core to a concrete backend — it knows how to read the backend's live schema back into the model
+// (`introspect`), how to turn ops into the backend's DDL (`render`), and how to quote an identifier.
+// `sync.ts` is threaded with a Dialect (defaulting to `sqlite`), so adding a second backend means writing
+// one new Dialect — not touching diff/sync. SQLite is the only implementation today; `postgres` is a
+// reserved, fail-loud slot.
+export interface Dialect {
+  /** Stable identifier, e.g. `sqlite` | `postgres`. */
+  readonly name: string
+  /** Read the live database's actual schema into the normalized model, for `diffSchema` to compare. */
+  introspect(db: IntrospectDb): SchemaSnapshot
+  /** Render structured ops into this backend's DDL statements, preserving the apply-safe order. */
+  render(ops: SchemaOp[]): string[]
+  /** Quote an identifier for this backend (backticks for SQLite, double-quotes for Postgres). */
+  quote(id: string): string
+}
+
+/** The SQLite dialect: the current engine, now behind the seam. `render`/`introspect` are the existing
+ *  pure functions; `quote` is SQLite's backtick quoting (matching `render-sqlite`'s own internal escape). */
+export const sqlite: Dialect = {
+  name: 'sqlite',
+  introspect,
+  render: renderSqlite,
+  quote: (id) => `\`${id.replace(/`/g, '``')}\``,
+}
+
+const pgNotImplemented = (op: string) =>
+  new Error(
+    `kestrel: the postgres dialect is not implemented yet (Dialect.${op}). It is a reserved slot ` +
+      `(ADR-0002) — a Postgres backend needs its own DDL renderer (real ALTER/DROP COLUMN, not SQLite's ` +
+      `table rebuild), information_schema introspection, and a pg-typed desired snapshot. Use \`sqlite\`.`,
+  )
+
+/** Reserved Postgres slot. Every substantive entry point fails loud so a misconfiguration can never
+ *  silently fall back to emitting SQLite DDL against a non-SQLite database. `quote` is the one piece that
+ *  is trivially correct (standard double-quote escaping), so it is implemented rather than thrown. */
+export const postgres: Dialect = {
+  name: 'postgres',
+  introspect() { throw pgNotImplemented('introspect') },
+  render() { throw pgNotImplemented('render') },
+  quote: (id) => `"${id.replace(/"/g, '""')}"`,
+}
+
+const dialects: Record<string, Dialect> = { sqlite, postgres }
+
+/** Resolve a dialect by name (the config-driven selection point for the migration engine). Throws a
+ *  clear error naming the supported dialects rather than silently defaulting, so a typo'd or unsupported
+ *  backend fails at startup instead of mis-migrating. */
+export function resolveDialect(name: string): Dialect {
+  const d = dialects[name]
+  if (!d) throw new Error(`kestrel: unknown database dialect "${name}" — supported: ${Object.keys(dialects).join(', ')}`)
+  return d
+}

package/layers/core/server/schema/diff.ts

@@ -0,0 +1,110 @@
+import type { SchemaSnapshot, SchemaOp, IndexShape, ColumnShape } from './model'
+
+/** Two indexes are equivalent when uniqueness, partial predicate, and ordered columns all match. */
+function sameIndex(a: IndexShape, b: IndexShape): boolean {
+  return a.unique === b.unique
+    && a.where === b.where
+    && a.columns.length === b.columns.length
+    && a.columns.every((c, i) => c === b.columns[i])
+}
+
+/** A column's definition drifted (same name, different shape) — only fixable by a table rebuild in SQLite. */
+function columnDiffers(a: ColumnShape, b: ColumnShape): boolean {
+  return a.type !== b.type || a.notNull !== b.notNull || a.primaryKey !== b.primaryKey
+    || a.autoIncrement !== b.autoIncrement || a.default !== b.default
+}
+
+/**
+ * Schema diff (ADR-0002). Additive changes (create table/column/index, drop_index) are always emitted.
+ * Destructive changes are emitted too but kept distinct: a table only in `actual` becomes `drop_table`;
+ * a table whose columns were dropped or whose definitions drifted becomes a `rebuild_table` (SQLite has
+ * no in-place ALTER COLUMN). A table needing a rebuild takes the rebuild path WHOLE — its added columns
+ * and indexes are recreated by the rebuild, not emitted separately.
+ *
+ * Returned in an apply-safe order: additive first (create_table → add_column → drop_index →
+ * create_index), destructive last (rebuild_table → drop_table). The additive/destructive split lets the
+ * apply layer gate destructive ops behind an explicit opt-in (see `isDestructive`).
+ */
+export function diffSchema(desired: SchemaSnapshot, actual: SchemaSnapshot): SchemaOp[] {
+  const createTables: SchemaOp[] = []
+  const renames: SchemaOp[] = []
+  const addColumns: SchemaOp[] = []
+  const dropIndexes: SchemaOp[] = []
+  const createIndexes: SchemaOp[] = []
+  const rebuilds: SchemaOp[] = []
+  const dropTables: SchemaOp[] = []
+
+  for (const name of Object.keys(desired)) {
+    const want = desired[name]
+    const have = actual[name]
+
+    if (!have) {
+      createTables.push({ type: 'create_table', table: want })
+      for (const index of want.indexes) createIndexes.push({ type: 'create_index', index })
+      continue
+    }
+
+    const haveByName = new Map(have.columns.map((c) => [c.name, c]))
+    const wantNames = new Set(want.columns.map((c) => c.name))
+
+    // Resolve renames: a desired column whose `renamedFrom` exists in actual while its own name does not.
+    // `rename_column` is additive and ordered before any rebuild, so the rest of the diff can treat the
+    // column as already present under its NEW name (the "effective" actual view).
+    const renameMap = new Map<string, string>() // newName -> oldName
+    const transformMap = new Map<string, { from: string; type: 'wrap' | 'unwrap' }>() // single↔multiple toggles
+    for (const c of want.columns) {
+      if (c.renamedFrom && haveByName.has(c.renamedFrom) && !haveByName.has(c.name)) {
+        renameMap.set(c.name, c.renamedFrom)
+        if (c.renameTransform) transformMap.set(c.name, { from: c.renamedFrom, type: c.renameTransform })
+      }
+    }
+    const renamedOld = new Set(renameMap.values())
+    // A name vacated by a rename (renamedOld) reads as absent unless something else renamed INTO it —
+    // otherwise a field re-using a just-freed name is mistaken for the column that just moved away.
+    const effectiveHas = (n: string) => (haveByName.has(n) && !renamedOld.has(n)) || renameMap.has(n)
+    const actualColOf = (n: string) => (renameMap.has(n) || !renamedOld.has(n)) ? haveByName.get(renameMap.get(n) ?? n) : undefined
+
+    const dropped = have.columns.some((c) => !wantNames.has(c.name) && !renamedOld.has(c.name))
+    const changed = want.columns.some((c) => { const a = actualColOf(c.name); return a !== undefined && columnDiffers(a, c) })
+
+    // Plain renames are an in-place ALTER RENAME; a single↔multiple toggle reshapes the data, so it is
+    // handled by the rebuild's transformed copy below (NO rename_column for those).
+    for (const [to, from] of renameMap) {
+      if (!transformMap.has(to)) renames.push({ type: 'rename_column', table: name, from, to })
+    }
+
+    if (dropped || changed || transformMap.size > 0) {
+      // Rebuild recreates the table at `want`, copying columns present in both (by effective/new name —
+      // plain renames already ran). A toggled column is copied from its old, differently-named source via
+      // a shape transform. Columns dropped without a rename hint are not copied: the data loss line.
+      const copy = want.columns.filter((c) => effectiveHas(c.name)).map((c) => c.name)
+      const transforms = Object.fromEntries(copy.filter((c) => transformMap.has(c)).map((c) => [c, transformMap.get(c)!]))
+      rebuilds.push({ type: 'rebuild_table', table: want, copy, ...(Object.keys(transforms).length ? { transforms } : {}) })
+      continue
+    }
+
+    // Purely additive for this table (renames already queued above).
+    for (const column of want.columns) {
+      if (!effectiveHas(column.name)) addColumns.push({ type: 'add_column', table: name, column })
+    }
+    const haveIdx = new Map(have.indexes.map((i) => [i.name, i]))
+    const wantIdx = new Map(want.indexes.map((i) => [i.name, i]))
+    for (const index of want.indexes) {
+      const existing = haveIdx.get(index.name)
+      if (!existing) { createIndexes.push({ type: 'create_index', index }); continue }
+      if (!sameIndex(existing, index)) {
+        dropIndexes.push({ type: 'drop_index', index: existing })
+        createIndexes.push({ type: 'create_index', index })
+      }
+    }
+    for (const index of have.indexes) {
+      if (!wantIdx.has(index.name)) dropIndexes.push({ type: 'drop_index', index })
+    }
+  }
+
+  for (const name of Object.keys(actual)) {
+    if (!desired[name]) dropTables.push({ type: 'drop_table', name })
+  }
+
+  return [...createTables, ...renames, ...addColumns, ...dropIndexes, ...createIndexes, ...rebuilds, ...dropTables]
+}

package/layers/core/server/schema/introspect.ts

@@ -0,0 +1,67 @@
+import type { ColumnShape, IndexShape, TableShape, SchemaSnapshot } from './model'
+
+// Read the *actual* schema of a live SQLite database into the normalized model, so `diffSchema` can
+// compare it against the desired schema (ADR-0002). Typed structurally (prepare + pragma) so it accepts
+// any better-sqlite3 connection without importing the native module here.
+
+interface Row { [key: string]: unknown }
+export interface IntrospectDb {
+  prepare(sql: string): { all(...params: unknown[]): Row[] }
+  pragma(source: string): Row[]
+}
+
+/** Double-quote an identifier for a PRAGMA argument (names come from sqlite_master, but quote defensively). */
+const dq = (id: string) => `"${id.replace(/"/g, '""')}"`
+
+export function introspect(db: IntrospectDb): SchemaSnapshot {
+  // Exclude sqlite internals, the drizzle migrations ledger, and any `__kestrel_new_*` rebuild temp
+  // table left by an interrupted rebuild — so an orphan is never mistaken for a real (droppable) table.
+  const tables = db.prepare(
+    "SELECT name, sql FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '__kestrel_new_%' AND name <> '__drizzle_migrations'",
+  ).all() as { name: string; sql: string | null }[]
+
+  const snapshot: SchemaSnapshot = {}
+  for (const { name, sql } of tables) {
+    snapshot[name] = { name, columns: columnsOf(db, name, sql ?? ''), indexes: indexesOf(db, name) }
+  }
+  return snapshot
+}
+
+function columnsOf(db: IntrospectDb, table: string, tableSql: string): ColumnShape[] {
+  // PRAGMA exposes no AUTOINCREMENT flag — it only ever applies to the INTEGER PRIMARY KEY, so detect
+  // it from the table's stored CREATE statement.
+  const hasAutoInc = /\bAUTOINCREMENT\b/i.test(tableSql)
+  const rows = db.pragma(`table_info(${dq(table)})`) as
+    { name: string; type: string; notnull: number; dflt_value: unknown; pk: number }[]
+  return rows.map((r) => ({
+    name: r.name,
+    type: r.type.toLowerCase(),
+    notNull: r.notnull === 1,
+    primaryKey: r.pk > 0,
+    autoIncrement: r.pk > 0 && hasAutoInc,
+    default: r.dflt_value == null ? null : String(r.dflt_value),
+  }))
+}
+
+function indexesOf(db: IntrospectDb, table: string): IndexShape[] {
+  const uniqueByName = new Map(
+    (db.pragma(`index_list(${dq(table)})`) as { name: string; unique: number }[]).map((m) => [m.name, m.unique === 1]),
+  )
+  // Only explicitly-created indexes carry a non-null `sql`; auto-indexes from UNIQUE/PK constraints are
+  // null-sql and excluded (they mirror column constraints, not declared indexes).
+  const rows = db.prepare(
+    "SELECT name, sql FROM sqlite_master WHERE type = 'index' AND tbl_name = ? AND sql IS NOT NULL",
+  ).all(table) as { name: string; sql: string }[]
+
+  return rows.map(({ name, sql }) => {
+    const columns = (db.pragma(`index_info(${dq(name)})`) as { name: string }[]).map((c) => c.name)
+    const where = sql.match(/\bWHERE\b\s+(.+)$/is)
+    return {
+      name,
+      table,
+      columns,
+      unique: uniqueByName.get(name) ?? /\bCREATE\s+UNIQUE\b/i.test(sql),
+      where: where ? where[1].trim() : null,
+    }
+  })
+}

package/layers/core/server/schema/model.ts

@@ -0,0 +1,61 @@
+// Normalized, dialect-agnostic schema model for the migration engine (ADR-0002). Both sides of a diff
+// are expressed in this shape: the *desired* snapshot (built from collection tables via getTableConfig)
+// and the *actual* snapshot (introspected from the live DB). `diffSchema` compares them; a dialect
+// renderer turns the resulting ops into DDL. SQLite is the first dialect.
+
+export interface ColumnShape {
+  name: string
+  /** SQLite storage type as it appears in DDL: `integer` | `text` | `real` | `blob`. */
+  type: string
+  notNull: boolean
+  primaryKey: boolean
+  autoIncrement: boolean
+  /** Raw SQL default token, exactly as it follows `DEFAULT` (e.g. `'draft'`, `0`), or null for none. */
+  default: string | null
+  /** The column's previous name (from a `renamedFrom` field hint) — the diff renames in place rather
+   *  than dropping the old column and losing its data. */
+  renamedFrom?: string
+  /** A relation/media `single↔multiple` toggle: the column moved between `<col>_id` (scalar) and `<col>`
+   *  (json array), so the rename needs a data shape transform. `wrap` = scalar→array, `unwrap` = array→scalar. */
+  renameTransform?: 'wrap' | 'unwrap'
+}
+
+export interface IndexShape {
+  name: string
+  table: string
+  columns: string[]
+  unique: boolean
+  /** Partial-index predicate (the text after `WHERE`), or null for a full index. */
+  where: string | null
+}
+
+export interface TableShape {
+  name: string
+  columns: ColumnShape[]
+  indexes: IndexShape[]
+}
+
+/** A whole schema, keyed by table name. */
+export type SchemaSnapshot = Record<string, TableShape>
+
+/**
+ * One structured, dialect-agnostic schema change. The first four variants are **additive** (no data
+ * loss): create table/column/index, and drop_index (indexes hold no row data, so dropping one is
+ * reversible). The last two are **destructive** (see `isDestructive`):
+ *  - `drop_table` — a collection was removed.
+ *  - `rebuild_table` — a column was dropped or its definition changed; since SQLite has no in-place
+ *    ALTER COLUMN, the table is recreated and the surviving columns (`copy`) are carried over.
+ * Destructive ops are never auto-applied; they require an explicit opt-in (ADR-0002).
+ */
+export type SchemaOp =
+  | { type: 'create_table'; table: TableShape }
+  | { type: 'add_column'; table: string; column: ColumnShape }
+  | { type: 'create_index'; index: IndexShape }
+  | { type: 'drop_index'; index: IndexShape }
+  // `rename_column` is additive (data-preserving, `ALTER TABLE … RENAME COLUMN`); it runs before any
+  // rebuild, so a rebuilt table sees the column under its new name.
+  | { type: 'rename_column'; table: string; from: string; to: string }
+  | { type: 'drop_table'; name: string }
+  // `transforms` maps a copied column to a shape transform of a differently-named source column (a
+  // relation/media single↔multiple toggle); plain copies just use the column's own (new) name.
+  | { type: 'rebuild_table'; table: TableShape; copy: string[]; transforms?: Record<string, { from: string; type: 'wrap' | 'unwrap' }> }

package/layers/core/server/schema/render-sqlite.ts

@@ -0,0 +1,89 @@
+import type { ColumnShape, IndexShape, TableShape, SchemaOp } from './model'
+
+// SQLite dialect renderer: structured ops → DDL strings. Kept separate from `diffSchema` (which is
+// dialect-agnostic) so a future Postgres renderer can sit behind the same op interface (ADR-0002).
+
+const q = (id: string) => `\`${id.replace(/`/g, '``')}\``
+const lit = (s: string) => `'${s.replace(/'/g, "''")}'`
+
+/**
+ * A column definition, shared by CREATE TABLE and ALTER TABLE ADD COLUMN. Clause order matches the
+ * committed drizzle-kit migrations: `<type> [PRIMARY KEY [AUTOINCREMENT]] [DEFAULT <x>] [NOT NULL]`.
+ * (SQLite rejects a NOT-NULL ADD COLUMN without a default on a non-empty table — that guard belongs to
+ * the apply/validation layer, not here.)
+ */
+function columnClause(c: ColumnShape): string {
+  let s = `${q(c.name)} ${c.type}`
+  if (c.primaryKey) s += c.autoIncrement ? ' PRIMARY KEY AUTOINCREMENT' : ' PRIMARY KEY'
+  if (c.default !== null) s += ` DEFAULT ${c.default}`
+  if (c.notNull) s += ' NOT NULL'
+  return s
+}
+
+// Indexes are emitted as separate create_index ops, so CREATE TABLE renders columns only.
+function createTableSql(name: string, columns: ColumnShape[]): string {
+  const cols = columns.map((c) => `  ${columnClause(c)}`).join(',\n')
+  return `CREATE TABLE ${q(name)} (\n${cols}\n);`
+}
+
+/**
+ * SQLite has no ALTER COLUMN / safe DROP COLUMN, so a destructive column change is a table rebuild:
+ * create a new table at the desired shape, copy the surviving columns' data, drop the old, rename the
+ * new into place, then recreate the indexes. (No foreign keys exist in this schema, so the usual
+ * `PRAGMA foreign_keys` dance is unnecessary.)
+ */
+/** SELECT source for a copied column: itself, or a single↔multiple shape transform of a differently-named source. */
+function copySource(col: string, transforms?: Record<string, { from: string; type: 'wrap' | 'unwrap' }>): string {
+  const t = transforms?.[col]
+  if (!t) return q(col)
+  return t.type === 'wrap'
+    ? `CASE WHEN ${q(t.from)} IS NULL THEN '[]' ELSE json_array(${q(t.from)}) END`
+    : `json_extract(${q(t.from)}, '$[0]')`
+}
+
+function rebuildTable(table: TableShape, copy: string[], transforms?: Record<string, { from: string; type: 'wrap' | 'unwrap' }>): string[] {
+  const tmp = `__kestrel_new_${table.name}`
+  // `DROP TABLE IF EXISTS` first so an orphan temp from an interrupted earlier rebuild self-heals
+  // instead of colliding on CREATE and wedging the migration.
+  const stmts = [`DROP TABLE IF EXISTS ${q(tmp)};`, createTableSql(tmp, table.columns)]
+  if (copy.length) {
+    const into = copy.map(q).join(', ')
+    const select = copy.map((c) => copySource(c, transforms)).join(', ')
+    stmts.push(`INSERT INTO ${q(tmp)} (${into}) SELECT ${select} FROM ${q(table.name)};`)
+  }
+  // Preserve the AUTOINCREMENT high-water mark across the rebuild so ids are never reused (a reused id
+  // could silently repoint a stale internal-link / relation reference). `sqlite_sequence` has no UNIQUE
+  // on `name`, so INSERT-OR-REPLACE won't work — ensure the temp row exists, then bump it to the old
+  // table's mark. Must run while the old table's seq row still exists (before its DROP); the RENAME then
+  // carries the row's name across.
+  if (table.columns.some((c) => c.autoIncrement)) {
+    stmts.push(`INSERT INTO sqlite_sequence (name, seq) SELECT ${lit(tmp)}, 0 WHERE NOT EXISTS (SELECT 1 FROM sqlite_sequence WHERE name = ${lit(tmp)});`)
+    stmts.push(`UPDATE sqlite_sequence SET seq = MAX(seq, COALESCE((SELECT seq FROM sqlite_sequence WHERE name = ${lit(table.name)}), 0)) WHERE name = ${lit(tmp)};`)
+  }
+  stmts.push(`DROP TABLE ${q(table.name)};`)
+  stmts.push(`ALTER TABLE ${q(tmp)} RENAME TO ${q(table.name)};`)
+  for (const index of table.indexes) stmts.push(createIndex(index))
+  return stmts
+}
+
+function createIndex(i: IndexShape): string {
+  const unique = i.unique ? 'UNIQUE ' : ''
+  const cols = i.columns.map(q).join(',')
+  const where = i.where ? ` WHERE ${i.where}` : ''
+  return `CREATE ${unique}INDEX ${q(i.name)} ON ${q(i.table)} (${cols})${where};`
+}
+
+/** Render structured ops into SQLite DDL, preserving order. Most ops are one statement; a rebuild is several. */
+export function renderSqlite(ops: SchemaOp[]): string[] {
+  return ops.flatMap((op): string[] => {
+    switch (op.type) {
+      case 'create_table': return [createTableSql(op.table.name, op.table.columns)]
+      case 'add_column': return [`ALTER TABLE ${q(op.table)} ADD COLUMN ${columnClause(op.column)};`]
+      case 'create_index': return [createIndex(op.index)]
+      case 'drop_index': return [`DROP INDEX IF EXISTS ${q(op.index.name)};`]
+      case 'rename_column': return [`ALTER TABLE ${q(op.table)} RENAME COLUMN ${q(op.from)} TO ${q(op.to)};`]
+      case 'drop_table': return [`DROP TABLE ${q(op.name)};`]
+      case 'rebuild_table': return rebuildTable(op.table, op.copy, op.transforms)
+    }
+  })
+}