@michaelthielemann/kestrel 1.2.1

package/layers/core/modules/auto-discovery/scan.ts

@@ -0,0 +1,78 @@
+import { readdirSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { blockNameFromFile } from './extract-block'
+
+type Lister = (dir: string) => string[]
+
+const isDefinition = (name: string) =>
+  name.endsWith('.ts') && !name.endsWith('.test.ts') && !name.endsWith('.d.ts')
+
+export function listDefinitionFiles(dir: string, list: Lister = readdirSync): string[] {
+  let entries: string[]
+  try {
+    entries = list(dir)
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return []
+    throw err
+  }
+  return entries
+    .filter(isDefinition)
+    .sort()
+    .map((name) => join(dir, name))
+}
+
+/**
+ * Definition files across every layer's `subdir`, deduped by BASENAME with LAYER PRIORITY: `layerRoots` is
+ * Nuxt's `_layers` order (consumer/highest-priority first), so a consumer's `collections/pages.ts` (or
+ * `field-types/color.ts`) SHADOWS the same-named lower-layer file — a deterministic override, instead of
+ * importing both and relying on the registry's last-write-wins under an alphabetical path sort (which made
+ * "who wins" a coincidence of the node_modules path). Mirrors `collectBlockSfcs`'s name-first dedup.
+ */
+export function collectDefinitions(layerRoots: string[], subdir: string, list?: Lister): string[] {
+  const byBasename = new Map<string, string>()
+  for (const root of layerRoots) {
+    for (const file of listDefinitionFiles(join(root, subdir), list)) {
+      const name = basename(file)
+      if (!byBasename.has(name)) byBasename.set(name, file) // first (highest-priority layer) wins
+    }
+  }
+  return [...byBasename.values()].sort()
+}
+
+const isVue = (name: string) => name.endsWith('.vue') && !name.endsWith('.test.vue')
+
+/** `.vue` files in `dir`, sorted; `[]` when the dir is absent. Mirrors `listDefinitionFiles` for blocks. */
+export function listVueFiles(dir: string, list: Lister = readdirSync): string[] {
+  let entries: string[]
+  try {
+    entries = list(dir)
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return []
+    throw err
+  }
+  return entries.filter(isVue).sort().map((name) => join(dir, name))
+}
+
+/** Block SFCs across every layer's `app/blocks/` dir, deduped by BLOCK NAME with LAYER PRIORITY: `layerRoots`
+ *  is Nuxt's `_layers` order (consumer/highest-priority first), so the first file seen for a given block name
+ *  wins. This matches how the display component is resolved (project-first), so a same-named override takes
+ *  its schema AND its template from the same layer — a plain alphabetical path sort handed the schema to
+ *  whichever path sorted last (typically the node_modules layer), silently splitting the two. */
+export function collectBlockSfcs(layerRoots: string[], subdir = 'app/blocks', list?: Lister): string[] {
+  const byName = new Map<string, string>()
+  for (const root of layerRoots) {
+    for (const file of listVueFiles(join(root, subdir), list)) {
+      const name = blockNameFromFile(basename(file))
+      if (!byName.has(name)) byName.set(name, file) // first (highest-priority layer) wins
+    }
+  }
+  // Name-unique now, so the final sort is only for a deterministic, stable import order.
+  return [...byName.values()].sort()
+}
+
+export function renderRegistry(absPaths: string[]): string {
+  if (!absPaths.length) return 'export default []'
+  const imports = absPaths.map((p, i) => `import _${i} from ${JSON.stringify(p)}`)
+  const arr = absPaths.map((_, i) => `_${i}`).join(', ')
+  return `${imports.join('\n')}\nexport default [${arr}]`
+}

package/layers/core/modules/auto-discovery/virtual.d.ts

@@ -0,0 +1,12 @@
+declare module '#kestrel/collections' {
+  const collections: unknown[]
+  export default collections
+}
+declare module '#kestrel/blocks' {
+  const blocks: unknown[]
+  export default blocks
+}
+declare module '#kestrel/schema-tables' {
+  const tables: unknown[]
+  export default tables
+}

package/layers/core/modules/kestrel/index.ts

@@ -0,0 +1,86 @@
+import { defineNuxtModule } from '@nuxt/kit'
+import { resolveKestrel, type KestrelConfig } from '../../server/utils/kestrel-config'
+
+/**
+ * The `kestrel` config namespace (`kestrel: { … }` in nuxt.config, sourced from `kestrel.config.ts`).
+ * Lives in `core` so it runs before the `media`/`public` layer modules and populates runtimeConfig
+ * first. It bridges the resolved config to what the CLIENT + Nitro need: `runtimeConfig.media.*`,
+ * `runtimeConfig.public.{locales,primaryLocale}`, and the `/uploads` static serving. Server runtime
+ * utils (db/locale/site-url) read the same resolved values directly via `server/utils/kestrel-config.ts`.
+ */
+export default defineNuxtModule<KestrelConfig>({
+  meta: { name: 'kestrel', configKey: 'kestrel' },
+  setup(options, nuxt) {
+    const c = resolveKestrel(options, process.env, nuxt.options.rootDir)
+
+    const rc = nuxt.options.runtimeConfig
+    rc.media = {
+      driver: c.media.driver,
+      maxUploadBytes: c.media.maxUploadBytes,
+      allowedMimes: c.media.allowedMimes,
+      imagePolicy: c.media.imagePolicy,
+      local: { dir: c.media.dir, baseUrl: c.media.baseUrl },
+      // Non-secret S3 settings come from the resolved config; the credentials are env-only (never
+      // committed) and merged in here so the server driver gets everything from runtimeConfig.
+      s3: {
+        ...c.media.s3,
+        accessKeyId: process.env.KESTREL_S3_ACCESS_KEY_ID ?? '',
+        secretAccessKey: process.env.KESTREL_S3_SECRET_ACCESS_KEY ?? '',
+        sessionToken: process.env.KESTREL_S3_SESSION_TOKEN ?? '',
+      },
+    }
+    const pub = (rc.public ??= {} as never) as Record<string, unknown>
+    pub.locales = c.supportedLocales
+    pub.primaryLocale = c.primaryLocale
+    pub.prefixPrimary = c.prefixPrimary
+    // The public head (canonical/og:url/hreflang) needs the absolute origin CLIENT-side too (SPA navs
+    // update the head after hydration). Not a secret — it is the site's own public address.
+    pub.siteUrl = c.siteUrl ?? ''
+    pub.siteName = c.siteName ?? ''
+    // Reference desktop width (px) for the admin page-builder preset; the editor's scale-to-fit shrinks it.
+    pub.previewDesktopWidth = c.preview.desktopWidth
+
+    // Server-only resolved settings, so server utils read the CONSUMER's `kestrel: {}` (via this module)
+    // rather than importing Kestrel's own `kestrel.config.ts` file. Essential when Kestrel is consumed as
+    // a layer: the package's config file is empty, the real config lives in the consumer's nuxt.config.
+    const srv = (rc.kestrel ??= {} as never) as Record<string, unknown>
+    srv.dbPath = c.dbPath
+    srv.siteUrl = c.siteUrl
+    srv.siteName = c.siteName
+    srv.siteDescription = c.siteDescription
+    // Built-in collection toggles (pages/media) — read by the register plugin to gate built-ins.
+    srv.collections = c.collections
+    // Static-publish target for the runtime publisher (server-only). S3 creds are env-only; prefer the
+    // output-specific creds, fall back to the shared media creds so a single S3 account "just works".
+    srv.output = {
+      driver: c.output.driver,
+      dir: c.output.dir,
+      publicDir: c.output.publicDir,
+      auto: c.output.auto,
+      reconcileMinutes: c.output.reconcileMinutes,
+      verbose: c.output.verbose,
+      s3: {
+        ...c.output.s3,
+        accessKeyId: process.env.KESTREL_OUTPUT_S3_ACCESS_KEY_ID ?? process.env.KESTREL_S3_ACCESS_KEY_ID ?? '',
+        secretAccessKey: process.env.KESTREL_OUTPUT_S3_SECRET_ACCESS_KEY ?? process.env.KESTREL_S3_SECRET_ACCESS_KEY ?? '',
+        sessionToken: process.env.KESTREL_OUTPUT_S3_SESSION_TOKEN ?? process.env.KESTREL_S3_SESSION_TOKEN ?? '',
+      },
+    }
+
+    nuxt.options.nitro ??= {}
+    // Only the local driver serves uploads off disk from the app origin (dev + baked into `nuxt
+    // generate`). On S3 the bucket/CDN serves them, so we must not register a publicAssets entry for
+    // a directory that isn't the store (it would 404 or shadow real keys).
+    if (c.media.driver === 'local') {
+      nuxt.options.nitro.publicAssets = [
+        ...(nuxt.options.nitro.publicAssets ?? []),
+        { baseURL: c.media.baseUrl, dir: c.media.dir, maxAge: 0 },
+      ]
+      // Uploads are served from the app origin; never let the browser content-sniff past the declared type.
+      nuxt.options.nitro.routeRules = {
+        ...(nuxt.options.nitro.routeRules ?? {}),
+        [`${c.media.baseUrl}/**`]: { headers: { 'X-Content-Type-Options': 'nosniff' } },
+      }
+    }
+  },
+})

package/layers/core/nuxt.config.ts

@@ -0,0 +1,8 @@
+import { fileURLToPath } from 'node:url'
+
+export default defineNuxtConfig({
+  modules: [
+    fileURLToPath(new URL('./modules/auto-discovery/index.ts', import.meta.url)),
+    fileURLToPath(new URL('./modules/kestrel/index.ts', import.meta.url)),
+  ],
+})

package/layers/core/server/api/[collection]/[id]/dead-refs.get.ts

@@ -0,0 +1,8 @@
+// Per-record stale-reference map for the editor: every reference this record holds that now points at a
+// deleted or unpublished target, with its field/block location + reason. Derived on read (auto-clears when
+// the link is fixed or the target restored). Fetched non-blocking alongside the editor load, like the
+// translations map.
+export default defineEventHandler((event) => {
+  const collection = requireCollection(event)
+  return recordDeadRefs(useDb(), collection, requireId(event))
+})

package/layers/core/server/api/[collection]/[id]/translations.get.ts

@@ -0,0 +1,4 @@
+export default defineEventHandler((event) => {
+  const collection = requireCollection(event)
+  return resolveTranslations(useDb(), collection, requireId(event))
+})

package/layers/core/server/api/[collection]/[id].delete.ts

@@ -0,0 +1,5 @@
+export default defineEventHandler((event) => {
+  requireAdmin(event) // write-authorization backstop (defense-in-depth; see require-admin.ts)
+  const collection = requireCollection(event)
+  return remove(useDb(), collection, requireId(event))
+})

package/layers/core/server/api/[collection]/[id].get.ts

@@ -0,0 +1,8 @@
+export default defineEventHandler((event) => {
+  const collection = requireCollection(event)
+  const query = getQuery(event)
+  const depth = Number(query.depth ?? 0)
+  const locale = query.locale as string | undefined
+  const publishedOnly = publishedOnlyForScope(event.context.readScope)
+  return getOne(useDb(), collection, requireId(event), depth, locale, publishedOnly)
+})

package/layers/core/server/api/[collection]/[id].patch.ts

@@ -0,0 +1,8 @@
+export default defineEventHandler(async (event) => {
+  requireAdmin(event) // write-authorization backstop (defense-in-depth; see require-admin.ts)
+  const collection = requireCollection(event)
+  const id = requireId(event)
+  const body = await readBody(event)
+  // Optimistic concurrency: the editor sends the baseline it loaded; a stale save is refused with 409.
+  return update(useDb(), collection, id, body, { expectedUpdatedAt: readIfUnmodifiedSince(event) })
+})

package/layers/core/server/api/[collection]/bulk.post.ts

@@ -0,0 +1,37 @@
+import { MAX_BULK_IDS } from '../../../app/utils/list-limits'
+import { BULK_ACTIONS, isBulkAction, type BulkAction } from '../../../app/utils/bulk-actions'
+
+// The ONE command endpoint for collection batch operations — the single wire surface behind both the
+// per-row Quick Actions and the selection Bulk bar (a row action IS a bulk action with one id). POST is
+// classified 'write' on the `{collection}` resource by the access guard (resourceForPath('/api/{c}/bulk')
+// === '{c}'), so CSRF + per-collection policy apply exactly as for a single-record write — no bypass.
+// A literal `bulk.post.ts` segment beats the dynamic `[id]` route (no `[id].post.ts` exists), so no clash.
+//
+//   body:  { action: 'delete' | 'publish' | 'unpublish' | 'duplicate', ids: number[] }
+//   200:   { action, count, ids }        (for 'duplicate', `ids` are the CREATED ids)
+//
+// delete + publish/unpublish are all-or-nothing (an unknown id 404s before any write); duplicate is a
+// sequential row action. All batching lives in crud.ts — this handler is a thin parse-and-dispatch.
+
+function parseBulkBody(body: unknown): { action: BulkAction; ids: number[] } {
+  const action = (body as { action?: unknown })?.action
+  if (!isBulkAction(action)) {
+    throw createError({ statusCode: 400, statusMessage: `Invalid bulk action: ${String(action)} (expected one of ${BULK_ACTIONS.join(', ')})` })
+  }
+  const ids = parseIdList((body as { ids?: unknown })?.ids, MAX_BULK_IDS)
+  return { action, ids }
+}
+
+export default defineEventHandler(async (event) => {
+  requireAdmin(event) // write-authorization backstop (defense-in-depth; see require-admin.ts)
+  const collection = requireCollection(event)
+  const { action, ids } = parseBulkBody(await readBody(event))
+  const db = useDb()
+
+  if (action === 'delete') return { action, ...removeMany(db, collection, ids) }
+  if (action === 'duplicate') {
+    const created = await duplicateMany(db, collection, ids)
+    return { action, count: created.length, ids: created.map((r) => r.id as number) }
+  }
+  return { action, ...setStatusMany(db, collection, ids, action === 'publish' ? 'published' : 'draft') }
+})

package/layers/core/server/api/[collection]/index.get.ts

@@ -0,0 +1,19 @@
+export default defineEventHandler((event) => {
+  const collection = requireCollection(event)
+  const query = getQuery(event)
+  const db = useDb()
+  const publishedOnly = publishedOnlyForScope(event.context.readScope)
+
+  if (collection.def.mode === 'single') {
+    return getSingleton(db, collection, query.locale as string | undefined, publishedOnly, query.depth ? Number(query.depth) : 0)
+  }
+
+  return list(db, collection, {
+    locale: query.locale as string | undefined,
+    sort: query.sort as string | undefined,
+    page: query.page ? Number(query.page) : undefined,
+    perPage: query.perPage ? Number(query.perPage) : undefined,
+    filter: parseFilter(query as Record<string, unknown>),
+    depth: query.depth ? Number(query.depth) : 0,
+  }, publishedOnly)
+})

package/layers/core/server/api/[collection]/index.post.ts

@@ -0,0 +1,8 @@
+export default defineEventHandler(async (event) => {
+  requireAdmin(event) // write-authorization backstop (defense-in-depth; see require-admin.ts)
+  const collection = requireCollection(event)
+  const body = await readBody(event)
+  const row = create(useDb(), collection, body)
+  setResponseStatus(event, 201)
+  return row
+})

package/layers/core/server/api/[collection]/index.put.ts

@@ -0,0 +1,7 @@
+export default defineEventHandler(async (event) => {
+  requireAdmin(event) // write-authorization backstop (defense-in-depth; see require-admin.ts)
+  const collection = requireCollection(event)
+  const query = getQuery(event)
+  const body = await readBody(event)
+  return putSingleton(useDb(), collection, query.locale as string | undefined, body, { expectedUpdatedAt: readIfUnmodifiedSince(event) })
+})

package/layers/core/server/api/[collection]/options.get.ts

@@ -0,0 +1,18 @@
+import { MAX_BULK_IDS } from '../../../app/utils/list-limits'
+
+export default defineEventHandler((event) => {
+  const collection = requireCollection(event)
+  const query = getQuery(event)
+  const db = useDb()
+
+  return pickerOptions(db, collection, {
+    search: query.search ? String(query.search) : undefined,
+    ids: query.ids ? parseIdList(query.ids, MAX_BULK_IDS) : undefined,
+    label: query.label ? String(query.label) : undefined,
+    page: query.page ? Number(query.page) : undefined,
+    perPage: query.perPage ? Number(query.perPage) : undefined,
+    locale: query.locale ? String(query.locale) : undefined,
+    // Match list()/getOne(): a published-scope read (anonymous / SSG) must not surface draft labels.
+    publishedOnly: publishedOnlyForScope(event.context.readScope),
+  })
+})

package/layers/core/server/api/[collection]/translations.get.ts

@@ -0,0 +1,25 @@
+import { eq, getTableColumns } from 'drizzle-orm'
+import type { AnySQLiteColumn } from 'drizzle-orm/sqlite-core'
+
+// The sibling map keyed by translation GROUP — the twin of `/:id/translations` for the editor of a record
+// that does not exist yet (`/admin/pages/new?locale=de&group=…`), which knows its group but has no id. It
+// resolves one member of the group and hands off to the per-id map builder, so both entry points can never
+// answer differently. The literal `translations` segment beats the dynamic `[id]` route (as `options.get.ts`
+// already relies on). Admin-only: `resourceForPath` maps it to the `<collection>/translations` resource, the
+// same gate as the per-record route (the map enumerates draft ids).
+export default defineEventHandler((event) => {
+  const collection = requireCollection(event)
+  // Checked here, not left to resolveTranslations: a collection without translations has no
+  // translationGroup column, so the member lookup below would blow up on an undefined column.
+  if (collection.def.mode === 'single' || !collection.def.translatable) {
+    throw createError({ statusCode: 400, statusMessage: 'Translations are not enabled for this collection' })
+  }
+  const group = String(getQuery(event).group ?? '').trim()
+  if (!group) throw createError({ statusCode: 400, statusMessage: 'A translation group is required' })
+
+  const db = useDb()
+  const cols = getTableColumns(collection.table) as Record<string, AnySQLiteColumn>
+  const member = db.select({ id: cols.id }).from(collection.table).where(eq(cols.translationGroup, group)).get() as { id: number } | undefined
+  if (!member) throw createError({ statusCode: 404, statusMessage: `Unknown translation group: ${group}` })
+  return resolveTranslations(db, collection, member.id)
+})

package/layers/core/server/api/collections/[name].get.ts

@@ -0,0 +1,4 @@
+export default defineEventHandler((event) => {
+  const collection = getCollectionOr404(getRouterParam(event, 'name') as string)
+  return serializeCollection(collection.def)
+})

package/layers/core/server/api/collections/index.get.ts

@@ -0,0 +1,3 @@
+export default defineEventHandler(() => {
+  return { data: allCollections().map((c) => serializeCollection(c.def)) }
+})

package/layers/core/server/api/references/broken.get.ts

@@ -0,0 +1,3 @@
+// Every reference in the index whose target is currently deleted or unpublished — the global broken-
+// references report. Admin-only (the `references` resource is not in the public set). Derived on read.
+export default defineEventHandler(() => findBrokenRefs(useDb()) ?? [])

package/layers/core/server/api/references/referrers.get.ts

@@ -0,0 +1,24 @@
+import { MAX_BULK_IDS } from '../../../app/utils/list-limits'
+
+// The distinct records that reference a given target — the reverse "what links here" lookup. Admin-only
+// (the `references` resource is not in the public set). Powers the editor's pre-delete referrer warning.
+// Two arms:
+//   ?collection=X&id=1        -> FieldRef[]                    (single target; the editor's warning)
+//   ?collection=X&ids=1,2,3   -> { counts: Record<id, count>, checked: boolean }  (a selection; the bulk-delete warning)
+// `checked` is false when the lookup itself failed (e.g. record_refs not migrated yet) — an empty `counts`
+// then means "could not check", NOT "no referrers", so a caller must not read it as a green light to delete.
+export default defineEventHandler((event) => {
+  const q = getQuery(event)
+  const collection = String(q.collection ?? '')
+  if (q.ids != null) {
+    if (!collection) throw createError({ statusCode: 400, statusMessage: 'collection and ids query params are required' })
+    const ids = parseIdList(q.ids, MAX_BULK_IDS)
+    const counts = findReferrersForMany(useDb(), collection, ids)
+    return { counts: counts ?? {}, checked: counts !== null }
+  }
+  const id = Number(q.id)
+  if (!collection || !Number.isInteger(id) || id <= 0) {
+    throw createError({ statusCode: 400, statusMessage: 'collection and id query params are required' })
+  }
+  return findReferrers(useDb(), collection, id) ?? []
+})

package/layers/core/server/database/record-refs.ts

@@ -0,0 +1,20 @@
+import { sqliteTable, integer, text, index } from 'drizzle-orm/sqlite-core'
+
+// Durable reference index: one row per `(source record) → (target record)` edge, over ALL reference
+// types (relation / media / internal link / richtext links / link fields). Maintained on every content
+// write (see `maintainRecordRefs`) and queried on read to DERIVE stale-reference warnings — never stores
+// a warning message (a stored "X deleted" goes stale when X is restored). A non-collection system table,
+// so it lives here (not `server/collections`, which would wire it into the CRUD API/admin). Indexed both
+// forward (what a record references) and reverse (what references a record). `createdAt` via `$defaultFn`
+// (no SQL default → it won't perpetually diff as a rebuild).
+export const recordRefs = sqliteTable('record_refs', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  sourceColl: text('source_coll').notNull(),
+  sourceId: integer('source_id').notNull(),
+  targetColl: text('target_coll').notNull(),
+  targetId: integer('target_id').notNull(),
+  createdAt: integer('created_at', { mode: 'timestamp' }).notNull().$defaultFn(() => new Date()),
+}, (t) => [
+  index('record_refs_source').on(t.sourceColl, t.sourceId),
+  index('record_refs_target').on(t.targetColl, t.targetId),
+])

package/layers/core/server/plugins/00.migrate.ts

@@ -0,0 +1,11 @@
+import { resolve } from 'node:path'
+import { existsSync } from 'node:fs'
+import { migrate } from 'drizzle-orm/better-sqlite3/migrator'
+
+export default defineNitroPlugin(() => {
+  // The committed drizzle-kit migrations only exist in Kestrel's own repo. When Kestrel is consumed as
+  // a layer, this folder is absent — there the schema-sync engine (02.schema-sync in dev, the db:migrate
+  // task in prod) owns the schema instead (ADR-0002), so skip rather than throw.
+  const migrationsFolder = resolve(process.cwd(), 'server/database/migrations')
+  if (existsSync(migrationsFolder)) migrate(useDb(), { migrationsFolder })
+})

package/layers/core/server/plugins/02.schema-sync.ts

@@ -0,0 +1,63 @@
+import collections from '#kestrel/collections'
+import schemaTables from '#kestrel/schema-tables'
+import type { AnySQLiteTable } from 'drizzle-orm/sqlite-core'
+import type { BuiltCollection } from '../utils/collection-types'
+import type { CollectionDef } from '../utils/defineCollection'
+import { resolveServerKestrel, serverRuntimeConfig } from '../utils/server-config'
+import { desiredFromCollections } from '../schema/bootstrap'
+import { planOps, describeOp, isDestructive, type SyncDb } from '../schema/sync'
+import { sqlite } from '../schema/dialect'
+import { runDevSchemaSync } from '../schema/dev-sync'
+
+// Dev-only schema auto-sync (ADR-0002). Runs after 00.migrate, so built-in collections are already
+// migrated and this is a no-op on them; it additively reconciles the live DB to whatever the registered
+// collections (+ the discovered standalone tables) now compile to — so adding a collection or a field
+// shows up without a hand-written migration. NEVER auto-DDLs in production or during prerender (`nuxt
+// generate`), where schema changes go through committed migrations / an explicit migrate step instead —
+// but production DOES a read-only DRIFT CHECK and warns loudly, so an upgraded consumer that forgot to
+// run `db:migrate` sees a clear boot warning instead of scattered runtime errors.
+export default defineNitroPlugin(() => {
+  if (import.meta.prerender) return
+
+  const desired = desiredFromCollections(collections as (CollectionDef | BuiltCollection)[], {
+    // Same toggle source as the registry plugin (01.register), so a disabled built-in is dropped from
+    // the desired schema exactly as it is dropped from the runtime surface.
+    toggles: (serverRuntimeConfig()?.kestrel?.collections ?? resolveServerKestrel().collections) as Record<string, boolean>,
+    extraTables: schemaTables as AnySQLiteTable[],
+  })
+  const client = (useDb() as unknown as { $client: SyncDb }).$client
+
+  if (process.env.NODE_ENV === 'production') {
+    // Read-only: never DDL in prod. Detect + surface drift so the operator runs db:migrate. Split by kind:
+    // ADDITIVE gaps (missing table/column/index) can make the app error → a real "run db:migrate" warning.
+    // DESTRUCTIVE ops (a drop for a disabled built-in, or an unmanaged extra table) are NOT app-breaking and
+    // are withheld by db:migrate anyway → report them informationally so a permanent, unactionable
+    // "app may error" warning doesn't fire on every boot after the operator has done what it asked.
+    try {
+      const pending = planOps(client, desired)
+      const additive = pending.filter((op) => !isDestructive(op))
+      const destructive = pending.filter(isDestructive)
+      if (additive.length) {
+        console.warn(
+          `[kestrel] SCHEMA DRIFT: the live DB is missing ${additive.length} change(s) the collections expect — ` +
+          `the app may error until you run the db:migrate task. Pending:\n  - ${additive.map(describeOp).join('\n  - ')}`,
+        )
+      }
+      if (destructive.length) {
+        console.info(
+          `[kestrel] schema note: ${destructive.length} table(s)/column(s) exist that the current collections no longer ` +
+          `define (e.g. a disabled built-in or an unmanaged table). Not app-breaking; db:migrate withholds these unless ` +
+          `you opt in ({force} / {drop:[…]}):\n  - ${destructive.map(describeOp).join('\n  - ')}`,
+        )
+      }
+    } catch (error) {
+      console.warn('[kestrel] could not check schema drift at boot:', (error as Error)?.message ?? error)
+    }
+    return
+  }
+
+  // SQLite is the only backend today; this is the seam where a config-driven `resolveDialect()` would go.
+  // runDevSchemaSync isolates failures (logs loudly, keeps the server up) — an infeasible auto-sync must
+  // not 500 every route, including the admin UI needed to fix it.
+  runDevSchemaSync(client, desired, sqlite)
+})

package/layers/core/server/plugins/03.record-refs.ts

@@ -0,0 +1,12 @@
+import { registerWriteListener } from '../utils/write-events'
+import { maintainRecordRefs } from '../utils/record-ref-index'
+
+/**
+ * Keep the durable `record_refs` index current on every content write — in ALL environments (the dead-
+ * reference warnings it powers are an editor feature, not gated on publishing, so unlike the publish
+ * plugin this is never skipped in dev). Its own listener, so it coexists with the publish listener; the
+ * bus try/catch-isolates each, so an index-maintenance failure never breaks the content write.
+ */
+export default defineNitroPlugin(() => {
+  registerWriteListener((event) => maintainRecordRefs(useDb(), event))
+})

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

@@ -0,0 +1,41 @@
+import type { AnySQLiteTable } from 'drizzle-orm/sqlite-core'
+import type { BuiltCollection } from '../utils/collection-types'
+import type { CollectionDef } from '../utils/defineCollection'
+import { ensureBuilt } from '../../../fields/server/utils/buildCollection'
+import { recordRefs } from '../database/record-refs'
+import { desiredSchema } from './desired'
+import type { SchemaSnapshot } from './model'
+
+/** The ONE rule for whether a discovered collection is active: built-ins (`pages`, `media`, …) can be
+ *  disabled per consumer via `kestrel: { collections: { <name>: false } }`. Shared by the registry
+ *  plugin AND the schema engine, so the runtime surface and the desired schema can never diverge —
+ *  a disabled built-in neither registers routes nor keeps (or creates) its table. */
+export function collectionEnabled(def: CollectionDef, toggles?: Record<string, boolean>): boolean {
+  return !(def.builtin && toggles?.[def.name] === false)
+}
+
+export interface DesiredOptions {
+  /** Built-in collection toggles (see `collectionEnabled`). Omitted → everything discovered is desired. */
+  toggles?: Record<string, boolean>
+  /** Standalone (non-collection) tables owned by upper layers — discovered via `#kestrel/schema-tables`
+   *  (each layer's `server/schema-tables/*.ts` default-exports one table) and passed in by the Nitro
+   *  callers, so core hardcodes no upper-layer schema. `record_refs` is core-owned and always included. */
+  extraTables?: AnySQLiteTable[]
+}
+
+/**
+ * The desired DB schema for the discovered collections (the `#kestrel/collections` virtual, passed in
+ * so this stays pure and unit-testable): every ENABLED collection's table plus core's `record_refs` and
+ * the callers' discovered standalone tables. The single definition of "what the live DB should look
+ * like", shared by the dev auto-sync plugin (02.schema-sync) and the `db:migrate` task so the two can
+ * never disagree on the target schema. Discovered files may default-export a plain def (consumer form)
+ * or an already-built collection.
+ */
+export function desiredFromCollections(
+  collections: (CollectionDef | BuiltCollection)[],
+  opts: DesiredOptions = {},
+): SchemaSnapshot {
+  const built = collections.map(ensureBuilt).filter((c) => collectionEnabled(c.def, opts.toggles))
+  const tables = [...built.map((c) => c.table), recordRefs, ...(opts.extraTables ?? [])]
+  return desiredSchema(tables, new Map(built.map((c) => [c.def.name, c.def])))
+}