@michaelthielemann/kestrel 1.2.1

package/layers/core/server/utils/page-slug.ts

@@ -0,0 +1,127 @@
+import { createError } from 'h3'
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
+import type { CollectionDef } from './defineCollection'
+import type { BuiltCollection } from './collection-types'
+import { slugify } from '../../app/utils/slugify'
+import { routeOf, findRouteConflict } from './page-route'
+
+/**
+ * The KEY of the text field Kestrel derives an auto-slug from: the `title` field if present, else the
+ * first text field (or `undefined` when the collection has no text field). Text fields keep their key as
+ * their column key (no `Id` suffix), so both the record value and a write target read directly by this key
+ * — which keeps this in `core` without importing the `fields` naming layer. Exported so the duplicate
+ * operation appends its `(copy)` suffix to the SAME field the slug derives from.
+ */
+export function slugSourceKey(def: CollectionDef): string | undefined {
+  const fields = Object.entries(def.fields)
+  const pick = fields.find(([k, f]) => k === 'title' && f.type === 'text') ?? fields.find(([, f]) => f.type === 'text')
+  return pick?.[0]
+}
+
+/** The trimmed string value of that slug-source field on a record (empty when absent / non-string). */
+export function slugSourceValue(def: CollectionDef, record: Record<string, unknown>): string {
+  const key = slugSourceKey(def)
+  if (!key) return ''
+  const v = record[key]
+  return typeof v === 'string' ? v.trim() : ''
+}
+
+// Canonicalise to exactly what the render-side resolver (resolvePublicRoute + the [...slug] segment
+// filter) looks up: lowercase, drop empty segments (leading/trailing/duplicate slashes). Otherwise a slug
+// typed with a trailing slash stores as `/blog/` but resolves as `/blog` → the page 404s and the sitemap
+// advertises a dead URL.
+const normalizePath = (p: string): string => `/${p.trim().toLowerCase().split('/').filter(Boolean).join('/')}`
+
+export interface SlugCtx {
+  /** The id of the record being saved (null on create), excluded from the uniqueness scan. */
+  id: number | null
+  /** The existing row (on update) — supplies the title for auto-gen + the locale when the body omits it. */
+  existing?: Record<string, unknown> | null
+  /** Every collection to scan for a route collision (the caller passes the registry). */
+  collections: BuiltCollection[]
+  primary: string
+  /** Whether the primary locale is prefixed in routes too — folded into the resolved route. */
+  prefixPrimary: boolean
+}
+
+/**
+ * Resolve and validate a pageLike record's slug, mutating `values.path` in place (no-op for non-pageLike):
+ *  - blank slug → auto-generate from the title field (slugify), de-duped (`-2`, `-3`, …) against the
+ *    GLOBAL resolved-route set; reject 400 only when there's no title to derive one from.
+ *  - explicit slug → normalize (single leading slash + lowercase) and reject 409 when its resolved route
+ *    is already taken by another pageLike record.
+ * Uniqueness is on the resolved route (`localePath`), GLOBAL across all pageLike collections — one route =
+ * one output file — so `/de/x` ≠ `/en/x` (different locale) but a bare `/x` in `pages` and `posts` collide.
+ */
+export function resolvePageSlug(db: BetterSQLite3Database, c: BuiltCollection, values: Record<string, unknown>, ctx: SlugCtx): void {
+  if (!c.def.pageLike) return
+  const raw = values.path
+  const explicit = typeof raw === 'string' && raw.trim() !== ''
+  const translatable = !!c.def.translatable
+  const locale = translatable
+    ? (typeof values.locale === 'string' && values.locale ? values.locale : (ctx.existing?.locale as string) ?? ctx.primary)
+    : ctx.primary
+  const exclude = { collection: c.name, id: ctx.id }
+  const routeFor = (p: string) => routeOf({ path: p, locale }, translatable, ctx.primary, ctx.prefixPrimary)!
+
+  if (explicit) {
+    const path = normalizePath(raw as string)
+    const conflict = findRouteConflict(db, routeFor(path), ctx.primary, ctx.collections, exclude, ctx.prefixPrimary)
+    if (conflict) throw createError({ statusCode: 409, statusMessage: 'Path already in use', data: { path, conflict } })
+    values.path = path
+    return
+  }
+
+  const slug = slugify(slugSourceValue(c.def, { ...(ctx.existing ?? {}), ...values }))
+  if (!slug) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Validation failed',
+      data: [{ path: ['path'], message: 'A slug is required (no title to derive one from).' }],
+    })
+  }
+  values.path = dedupeRoute(db, `/${slug}`, routeFor, ctx.primary, ctx.collections, exclude, ctx.prefixPrimary)
+}
+
+/**
+ * The ONE `-N` de-dup loop: return `base` when its resolved route is free, else `base-2`, `base-3`, … the
+ * first candidate not already claimed by another pageLike record. Extracted so BOTH the auto-generated-slug
+ * branch above AND the duplicate op (`dedupeSourcePath`) share a single route-uniqueness implementation.
+ */
+function dedupeRoute(
+  db: BetterSQLite3Database,
+  base: string,
+  routeFor: (path: string) => string,
+  primary: string,
+  collections: BuiltCollection[],
+  exclude: { collection: string; id: number | null },
+  prefixPrimary: boolean,
+): string {
+  let candidate = base
+  for (let n = 2; n < 1000 && findRouteConflict(db, routeFor(candidate), primary, collections, exclude, prefixPrimary); n++) {
+    candidate = `${base}-${n}`
+  }
+  return candidate
+}
+
+/**
+ * The free route a pageLike COPY should claim when its collection has NO slug-source text field for the
+ * auto-gen branch to derive from: the SOURCE row's own explicit `path`, de-duped (`-2`, `-3`, …) to the
+ * first free global route via the same `dedupeRoute` loop. Seeding this (instead of leaving `path` blank →
+ * a 400, or re-using the source's colliding path → a 409) lets `create()`'s explicit branch accept it.
+ * Mirrors resolvePageSlug's own locale/route derivation so a copy resolves under the source's locale.
+ * Returns null when the source has no usable path (the caller lets create()'s own 400 surface).
+ */
+export function dedupeSourcePath(
+  db: BetterSQLite3Database,
+  c: BuiltCollection,
+  sourceRow: Record<string, unknown>,
+  ctx: Pick<SlugCtx, 'collections' | 'primary' | 'prefixPrimary'>,
+): string | null {
+  const raw = sourceRow.path
+  if (typeof raw !== 'string' || raw.trim() === '') return null
+  const translatable = !!c.def.translatable
+  const locale = translatable && typeof sourceRow.locale === 'string' && sourceRow.locale ? sourceRow.locale : ctx.primary
+  const routeFor = (p: string) => routeOf({ path: p, locale }, translatable, ctx.primary, ctx.prefixPrimary)!
+  return dedupeRoute(db, normalizePath(raw), routeFor, ctx.primary, ctx.collections, { collection: c.name, id: null }, ctx.prefixPrimary)
+}

package/layers/core/server/utils/picker.ts

@@ -0,0 +1,82 @@
+import { and, count, eq, getTableColumns, inArray, sql } from 'drizzle-orm'
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
+import type { AnySQLiteTable } from 'drizzle-orm/sqlite-core'
+import { MAX_BULK_IDS } from '../../app/utils/list-limits'
+import type { BuiltCollection } from './collection-types'
+import { resolveLocale } from './locale'
+import { escapeLike } from './sql'
+
+type DB = BetterSQLite3Database
+
+export interface PickerQuery {
+  search?: string
+  ids?: number[]
+  label?: string
+  page?: number
+  perPage?: number
+  locale?: string
+  /** Published-scope read (anonymous / SSG): hide draft rows + labels, like list()/getOne(). */
+  publishedOnly?: boolean
+}
+
+export interface PickerResult {
+  data: { id: number; label: string }[]
+  total: number
+  page: number
+  perPage: number
+}
+
+/** The field key used as the human label: an explicit text field, else the first text field, else 'id'. */
+function resolveLabelKey(c: BuiltCollection, requested?: string): string {
+  const fields = c.def.fields
+  if (requested && fields[requested]?.type === 'text') return requested
+  for (const [key, field] of Object.entries(fields)) if (field.type === 'text') return key
+  return 'id'
+}
+
+export function pickerOptions(db: DB, c: BuiltCollection, q: PickerQuery): PickerResult {
+  const cols = getTableColumns(c.table) as Record<string, never>
+  const t = c.table as AnySQLiteTable
+  const labelKey = resolveLabelKey(c, q.label)
+  const labelCol = cols[labelKey] ?? cols.id
+
+  // Validate the locale (consistent 400) up front; only apply it as a filter in search/list mode.
+  const localeCond = c.def.translatable ? eq(cols.locale, resolveLocale(q.locale)) : undefined
+
+  // A blank label must fall back too (not just nullish): the editor's combobox mirrors this label into
+  // its input text, and an empty label would leave a validly selected record looking unselected.
+  const toOption = (r: Record<string, unknown>) => {
+    const label = String(r[labelKey] ?? '').trim()
+    return { id: Number(r.id), label: label || `#${r.id}` }
+  }
+
+  // Published-scope read hides drafts (like list()/getOne()), so a picker on a public surface never leaks
+  // draft titles. Only applies when the collection has a status column.
+  const statusCond = q.publishedOnly && Object.hasOwn(cols, 'status') ? eq(cols.status, 'published') : undefined
+
+  // ids mode: resolve the picker's current value(s) to labels. A present-but-empty ids list
+  // (e.g. all non-numeric) is an explicit empty result, not a full list. The id is a globally
+  // unique PK (each locale is its own row), so the locale predicate is intentionally NOT applied
+  // here — it could only drop an already-valid selection across locales.
+  if (q.ids) {
+    if (!q.ids.length) return { data: [], total: 0, page: 1, perPage: 0 }
+    const rows = db.select().from(t).where(and(inArray(cols.id, q.ids.slice(0, MAX_BULK_IDS)), statusCond)).limit(MAX_BULK_IDS).all() as Record<string, unknown>[]
+    return { data: rows.map(toOption), total: rows.length, page: 1, perPage: rows.length }
+  }
+
+  // search / list mode.
+  const conds = []
+  if (localeCond) conds.push(localeCond)
+  if (statusCond) conds.push(statusCond)
+  if (q.search && labelKey !== 'id') conds.push(sql`${labelCol} like ${`%${escapeLike(q.search)}%`} escape '\\'`)
+  const where = conds.length ? and(...conds) : undefined
+
+  const num = (v: number | undefined, fallback: number) => (Number.isFinite(v) ? (v as number) : fallback)
+  const page = Math.max(1, Math.floor(num(q.page, 1)))
+  const perPage = Math.min(100, Math.max(1, Math.floor(num(q.perPage, 25))))
+
+  const rows = db.select().from(t).where(where)
+    .orderBy(labelCol).limit(perPage).offset((page - 1) * perPage).all() as Record<string, unknown>[]
+  const totalRow = db.select({ value: count() }).from(t).where(where).get() as { value: number } | undefined
+  return { data: rows.map(toOption), total: Number(totalRow?.value ?? 0), page, perPage }
+}

package/layers/core/server/utils/populate.ts

@@ -0,0 +1,48 @@
+import type { CollectionDef, FieldDef } from './defineCollection'
+
+export interface PopulateCtx { depth: number; locale: string; def: CollectionDef }
+export type Populator = (row: Record<string, unknown>, ctx: PopulateCtx) => Record<string, unknown>
+
+// A composed list: each registered populator runs in turn over the row (e.g. media attaches `$media`,
+// links resolve internal hrefs). They are order-independent — each clones the slice it touches.
+const registered: Populator[] = []
+
+export function registerPopulator(fn: Populator): void { registered.push(fn) }
+export function clearPopulator(): void { registered.length = 0 }
+
+export function populateRow(row: Record<string, unknown>, ctx: PopulateCtx): Record<string, unknown> {
+  if (ctx.depth <= 0) return row
+  return registered.reduce((acc, fn) => fn(acc, ctx), row)
+}
+
+/**
+ * Key-mode captures the storage asymmetry a field populator must read around: a SINGLE relation/media is
+ * keyed `${name}Id` in TOP-LEVEL row COLUMNS but BARE `name` in block props / repeater entries (PROPS).
+ * Everything else (links, richtext, many-relation, multiple-media) is bare-keyed in both. Mirrors the
+ * `KeyMode` in `extract-refs.ts`.
+ */
+export type KeyMode = 'columns' | 'props'
+
+/**
+ * A per-field-type read populator (the Pruvious-style seam). Receives the containing — already cloned —
+ * value bag, the field's key, its def, the populate ctx, and the key-mode; MUTATES `bag` in place (attach
+ * `$media` / a `$<name>` relation sibling, resolve a link value, …). Runs only while `ctx.depth > 0`.
+ * SYNCHRONOUS — SQLite reads are synchronous, so the whole populate path stays sync.
+ */
+export type FieldPopulator = (
+  bag: Record<string, unknown>,
+  key: string,
+  field: FieldDef,
+  ctx: PopulateCtx,
+  keyMode: KeyMode,
+) => void
+
+// One populator per field-type name (last-wins, like the field-type registry). The shared field-tree
+// walker (`layers/fields`) dispatches into this; the owning layer registers its populator (media →
+// `media`, public → `link`/`richtext`, collections → `relation`) so no layer bakes another's read logic
+// into a lower-layer field-type descriptor.
+const fieldPopulators = new Map<string, FieldPopulator>()
+
+export function registerFieldPopulator(type: string, fn: FieldPopulator): void { fieldPopulators.set(type, fn) }
+export function getFieldPopulator(type: string): FieldPopulator | undefined { return fieldPopulators.get(type) }
+export function clearFieldPopulators(): void { fieldPopulators.clear() }

package/layers/core/server/utils/prerender-memo.ts

@@ -0,0 +1,23 @@
+/** Memoize a resolver by a string key. The cache lives for the returned function's lifetime, so only
+ *  use it where the underlying data is immutable for that lifetime. Caches misses (null/undefined) too. */
+export function memoize<A extends unknown[], R>(fn: (...args: A) => R, key: (...args: A) => string): (...args: A) => R {
+  const cache = new Map<string, R>()
+  return (...args: A): R => {
+    const k = key(...args)
+    if (cache.has(k)) return cache.get(k) as R
+    const value = fn(...args)
+    cache.set(k, value)
+    return value
+  }
+}
+
+/**
+ * Like `memoize`, but active ONLY during a `nuxt generate` prerender run (`import.meta.prerender`), where
+ * the DB is read-only for the whole build and a referenced media asset / link target is identical across
+ * every page that embeds it — so a shared header image reused on 100 pages is resolved once, not 100×.
+ * Outside prerender (dev SSR, tests) it returns the resolver untouched, so a live edit is never served
+ * stale and there is no cross-request cache to invalidate.
+ */
+export function memoDuringPrerender<A extends unknown[], R>(fn: (...args: A) => R, key: (...args: A) => string): (...args: A) => R {
+  return (import.meta as { prerender?: boolean }).prerender ? memoize(fn, key) : fn
+}

package/layers/core/server/utils/read-capture.ts

@@ -0,0 +1,37 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+// Records which collections/records a render reads, so the publisher can map a content write back to
+// exactly the routes that embed it (precise incremental invalidation). The CRUD read seams call
+// `captureRead`; the publisher wraps each route render in `withReadCapture`. Outside a capture run
+// `captureRead` is a cheap no-op, so normal request/CRUD traffic is unaffected.
+const storage = new AsyncLocalStorage<{ tags: Set<string> }>()
+
+/** Tag that the current render read collection `coll` (a `list`/singleton) or record `coll:id` (a `getOne`). */
+export function captureRead(coll: string, id?: number | null): void {
+  const store = storage.getStore()
+  if (!store) return
+  store.tags.add(typeof id === 'number' ? `${coll}:${id}` : coll)
+}
+
+/** Run `fn` while collecting the data tags its reads touch; returns the result + the captured tags.
+ *  Async-safe: AsyncLocalStorage propagates through the awaits of an SSR render. */
+export async function withReadCapture<T>(fn: () => Promise<T> | T): Promise<{ result: T; tags: string[] }> {
+  const store = { tags: new Set<string>() }
+  const result = await storage.run(store, fn)
+  return { result, tags: [...store.tags] }
+}
+
+/** Sync variant for the synchronous populate path: collects `fn`'s tags into a FRESH set (the enclosing
+ *  capture does NOT see them — the caller re-emits, e.g. the resolve-scope memo replaying tags on hits). */
+export function withReadCaptureSync<T>(fn: () => T): { result: T; tags: string[] } {
+  const store = { tags: new Set<string>() }
+  const result = storage.run(store, fn)
+  return { result, tags: [...store.tags] }
+}
+
+/** Re-emit previously captured tags into the CURRENT capture context (no-op outside one). */
+export function replayReadTags(tags: readonly string[]): void {
+  const store = storage.getStore()
+  if (!store) return
+  for (const t of tags) store.tags.add(t)
+}

package/layers/core/server/utils/record-ref-index.ts

@@ -0,0 +1,200 @@
+import { and, eq, getTableColumns, inArray } from 'drizzle-orm'
+import type { AnySQLiteColumn } from 'drizzle-orm/sqlite-core'
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
+import { recordRefs } from '../database/record-refs'
+import { extractRecordRefs, extractLocatedRecordRefs, type FieldRef, type LocatedRef } from '../../../fields/server/utils/extract-refs'
+import type { CollectionDef, FieldDef } from './defineCollection'
+import { fieldIs } from './defineCollection'
+import type { BuiltCollection } from './collection-types'
+import { getCollection } from './registry'
+import type { WriteEvent } from './write-events'
+
+type DB = BetterSQLite3Database
+
+/**
+ * Maintain the `record_refs` edges for one content write (the write-events listener calls this).
+ * Replace-on-write: a create / update / singleton PUT clears the source's existing edges and inserts the
+ * freshly extracted set; a delete just clears them. Touches only the written source row's edges, so other
+ * records' edges are untouched. Best-effort — the bus isolates a throwing listener, so a failure to keep
+ * the index current never breaks the content write itself. The `before`/`after` rows are read, never mutated.
+ */
+export function maintainRecordRefs(db: DB, event: WriteEvent): void {
+  const { def, before, after } = event
+  const source = after ?? before
+  const sourceId = source?.id
+  if (typeof sourceId !== 'number') return
+
+  // Clear the source's edges first — both the delete path and the create/update replace path need this.
+  db.delete(recordRefs).where(and(eq(recordRefs.sourceColl, def.name), eq(recordRefs.sourceId, sourceId))).run()
+  if (!after) return // delete: edges removed, nothing to re-insert.
+
+  const refs = extractRecordRefs(def, after)
+  if (!refs.length) return
+  db.insert(recordRefs)
+    .values(refs.map((r) => ({ sourceColl: def.name, sourceId, targetColl: r.collection, targetId: r.id })))
+    .run()
+}
+
+/** Why a reference is stale: its target row is gone, or present but not published. */
+export type DeadReason = 'missing' | 'unpublished'
+
+/** A reference plus its dead-ness reason, with field/block location for the editor's per-field warnings. */
+export interface LocatedDeadRef extends LocatedRef {
+  reason: DeadReason
+}
+
+/** Whether a collection has any field/block that can hold a reference — used to skip the derivation (and
+ *  to decide whether to offer the dead-reference column) for collections that can never have stale refs. */
+export function collectionMayReference(def: CollectionDef): boolean {
+  if (def.blocks?.enabled) return true
+  if (def.seo) return true // the `seo` system column carries a media ref (the social image), tracked like any
+  return Object.values(def.fields).some(fieldMayReference)
+}
+function fieldMayReference(field: FieldDef): boolean {
+  // `fieldIs` not `switch`: the open consumer arm makes `type` a non-discriminant (no switch narrowing).
+  if (fieldIs(field, 'repeater')) return Object.values(field.options.fields).some(fieldMayReference)
+  return field.type === 'relation' || field.type === 'media' || field.type === 'link' || field.type === 'richtext'
+}
+
+/**
+ * Classify a batch of reference targets as dead, in ONE query per target collection (no N+1). A target is
+ * dead when its row is GONE, or — if its collection's table has a `status` column — present but not
+ * `'published'` (so a consumer-added status on any collection is honoured automatically). An
+ * unknown/unregistered target collection counts as missing. A not-yet-migrated target table (e.g. a bare
+ * prerender DB) is treated as indeterminate (not dead), mirroring the link resolver's tolerance. Returns a
+ * map keyed `"collection:id"` → reason, holding ONLY the dead targets.
+ */
+export function deadTargets(db: DB, targets: FieldRef[]): Map<string, DeadReason> {
+  const dead = new Map<string, DeadReason>()
+  const byCollection = new Map<string, Set<number>>()
+  for (const t of targets) {
+    let ids = byCollection.get(t.collection)
+    if (!ids) byCollection.set(t.collection, (ids = new Set()))
+    ids.add(t.id)
+  }
+  for (const [collection, ids] of byCollection) {
+    const c = getCollection(collection)
+    if (!c) {
+      for (const id of ids) dead.set(`${collection}:${id}`, 'missing')
+      continue
+    }
+    const cols = getTableColumns(c.table) as Record<string, AnySQLiteColumn>
+    const hasStatus = Object.hasOwn(cols, 'status')
+    let rows: { id: number; status?: unknown }[]
+    try {
+      rows = db.select({ id: cols.id, ...(hasStatus ? { status: cols.status } : {}) })
+        .from(c.table as never).where(inArray(cols.id, [...ids])).all() as { id: number; status?: unknown }[]
+    } catch {
+      continue // table not migrated yet — don't false-flag.
+    }
+    const byId = new Map(rows.map((r) => [r.id, r]))
+    for (const id of ids) {
+      const row = byId.get(id)
+      if (!row) dead.set(`${collection}:${id}`, 'missing')
+      else if (hasStatus && row.status !== 'published') dead.set(`${collection}:${id}`, 'unpublished')
+    }
+  }
+  return dead
+}
+
+/** Every stale reference a record currently holds, with its field/block location and reason — derived
+ *  freshly from the record's value (so it auto-clears when the link is removed or the target restored). */
+export function deriveLocatedDeadRefs(db: DB, def: CollectionDef, row: Record<string, unknown>): LocatedDeadRef[] {
+  const located = extractLocatedRecordRefs(def, row)
+  if (!located.length) return []
+  const dead = deadTargets(db, located)
+  if (!dead.size) return []
+  const out: LocatedDeadRef[] = []
+  for (const ref of located) {
+    const reason = dead.get(`${ref.collection}:${ref.id}`)
+    if (reason) out.push({ ...ref, reason })
+  }
+  return out
+}
+
+/** Load a record by id and derive its stale references (for the editor's `/dead-refs` endpoint). */
+export function recordDeadRefs(db: DB, c: BuiltCollection, id: number): LocatedDeadRef[] {
+  const cols = getTableColumns(c.table) as Record<string, never>
+  let row: Record<string, unknown> | undefined
+  try {
+    row = db.select().from(c.table as never).where(eq(cols.id, id)).get() as Record<string, unknown> | undefined
+  } catch {
+    return []
+  }
+  return row ? deriveLocatedDeadRefs(db, c.def, row) : []
+}
+
+/** The distinct records that reference a given target — the reverse "what links here" lookup (powers the
+ *  pre-delete/unpublish warning). Read-only; tolerant of a not-yet-migrated index — returns `null` rather
+ *  than `[]` on failure, so a caller can tell "checked, no referrers" from "could not check" and must not
+ *  treat the latter as a green light to delete unwarned. */
+export function findReferrers(db: DB, targetColl: string, targetId: number): FieldRef[] | null {
+  try {
+    return db.selectDistinct({ sourceColl: recordRefs.sourceColl, sourceId: recordRefs.sourceId })
+      .from(recordRefs)
+      .where(and(eq(recordRefs.targetColl, targetColl), eq(recordRefs.targetId, targetId)))
+      .all()
+      .map((r) => ({ collection: r.sourceColl, id: r.sourceId }))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Referrer COUNTS for a whole selection of targets in ONE query — the batched reverse lookup powering the
+ * bulk-delete "what links here" warning. Returns `targetId -> number of distinct referrers`; a target with
+ * no referrers is simply omitted. A referrer that is ITSELF in the selection is excluded, so deleting a
+ * linked pair together raises no false warning. Read-only; tolerant of a not-yet-migrated index — returns
+ * `null` (not `{}`) on failure, mirroring `findReferrers`'s indeterminate-vs-empty distinction.
+ */
+export function findReferrersForMany(db: DB, targetColl: string, ids: number[]): Record<number, number> | null {
+  if (!ids.length) return {}
+  try {
+    const rows = db.selectDistinct({ sourceColl: recordRefs.sourceColl, sourceId: recordRefs.sourceId, targetId: recordRefs.targetId })
+      .from(recordRefs)
+      .where(and(eq(recordRefs.targetColl, targetColl), inArray(recordRefs.targetId, ids)))
+      .all()
+    const selected = new Set(ids)
+    const counts: Record<number, number> = {}
+    for (const r of rows) {
+      if (r.sourceColl === targetColl && selected.has(r.sourceId)) continue // in-selection referrer → not counted
+      counts[r.targetId] = (counts[r.targetId] ?? 0) + 1
+    }
+    return counts
+  } catch {
+    return null
+  }
+}
+
+/** A referrer → dead-target edge, for the global broken-references report. */
+export interface BrokenRef {
+  source: FieldRef
+  target: FieldRef
+  reason: DeadReason
+}
+
+/** Every edge in the index whose target is currently dead — the global broken-references report. Scans the
+ *  whole index (an admin maintenance view, not a hot path) and classifies all targets in one batch. Returns
+ *  `null` (not `[]`) when the index itself could not be read, mirroring `findReferrers`. */
+export function findBrokenRefs(db: DB): BrokenRef[] | null {
+  let edges: { sourceColl: string; sourceId: number; targetColl: string; targetId: number }[]
+  try {
+    edges = db.select({
+      sourceColl: recordRefs.sourceColl,
+      sourceId: recordRefs.sourceId,
+      targetColl: recordRefs.targetColl,
+      targetId: recordRefs.targetId,
+    }).from(recordRefs).all()
+  } catch {
+    return null
+  }
+  if (!edges.length) return []
+  const dead = deadTargets(db, edges.map((e) => ({ collection: e.targetColl, id: e.targetId })))
+  if (!dead.size) return []
+  const out: BrokenRef[] = []
+  for (const e of edges) {
+    const reason = dead.get(`${e.targetColl}:${e.targetId}`)
+    if (reason) out.push({ source: { collection: e.sourceColl, id: e.sourceId }, target: { collection: e.targetColl, id: e.targetId }, reason })
+  }
+  return out
+}

package/layers/core/server/utils/registry.ts

@@ -0,0 +1,24 @@
+import type { BuiltCollection } from './collection-types'
+
+const registry = new Map<string, BuiltCollection>()
+
+export function registerCollection(collection: BuiltCollection): void {
+  // A consumer collection sharing a name with a built-in (or another) silently overwrites it in the Map.
+  // Warn so an accidental clash is visible, while still allowing a deliberate override (last one wins).
+  if (registry.has(collection.name)) {
+    console.warn(`[kestrel] collection "${collection.name}" is registered more than once — the later definition wins`)
+  }
+  registry.set(collection.name, collection)
+}
+
+export function getCollection(name: string): BuiltCollection | undefined {
+  return registry.get(name)
+}
+
+export function allCollections(): BuiltCollection[] {
+  return [...registry.values()]
+}
+
+export function clearRegistry(): void {
+  registry.clear()
+}

package/layers/core/server/utils/resolve-scope.ts

@@ -0,0 +1,79 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { withReadCaptureSync, replayReadTags } from './read-capture'
+
+/**
+ * Per-request/per-run resolver memoization + fan-out budget. `memoDuringPrerender` only dedupes during a
+ * `nuxt generate` build; a LIVE request re-resolved every repeated reference, so an anonymous
+ * `?depth=10&perPage=500` read could multiply into a huge number of synchronous DB reads (each blocking
+ * the single event-loop thread). A scope gives the populate resolvers (relation/media/link):
+ *   - a shared cache: each distinct target is resolved ONCE per scope (repeated refs are free), and
+ *   - a budget on DISTINCT resolves: past it, further NEW targets resolve to null — the same degrade
+ *     path as a stale reference — bounding the worst-case work of one request.
+ * Nested scopes reuse the outermost one (a relation's recursive getOne inherits the request's scope; the
+ * runtime publisher wraps a whole run in an UNBUDGETED scope, giving it the per-run dedup a generate
+ * build gets from `memoDuringPrerender`). Outside any scope a resolver runs raw — no cross-request cache.
+ */
+interface CacheEntry {
+  value: unknown
+  /** The read-tags the resolver captured while producing `value` — replayed on every hit, so a page
+   *  served from the memo still records the SAME publish deps as the page that resolved it. */
+  tags: string[]
+}
+
+interface ResolveScope {
+  cache: Map<string, CacheEntry>
+  max: number
+  used: number
+  tripped: boolean
+  label: string
+}
+
+const storage = new AsyncLocalStorage<ResolveScope>()
+
+/** Per-request distinct-resolve ceiling. Sized so a LEGITIMATE full page never trips it — the dominant
+ *  protection is the per-scope dedup (distinct resolves are bounded by the referenced record set, not the
+ *  breadth^depth fan-out), so this is only a backstop against a pathologically dense reference graph.
+ *  `resolveBudgetFor(perPage)` scales it with the page size so a `perPage=500, depth≥1` read of richly-
+ *  referenced rows still populates every row. */
+export const REQUEST_RESOLVE_BUDGET = 20_000
+export function resolveBudgetFor(perPage?: number): number {
+  const scaled = (perPage && perPage > 0 ? perPage : 1) * 200 // ~200 distinct refs/row headroom
+  return Math.max(REQUEST_RESOLVE_BUDGET, scaled)
+}
+
+export function withResolveScope<T>(fn: () => T, max = Number.POSITIVE_INFINITY, label = 'read'): T {
+  if (storage.getStore()) return fn() // nested — the outermost scope owns cache + budget
+  return storage.run({ cache: new Map(), max, used: 0, tripped: false, label }, fn)
+}
+
+/** Wrap a resolver: inside a scope it memoizes by `key` and enforces the scope's budget (over-budget new
+ *  targets → null); outside a scope it calls through untouched. */
+export function memoResolver<A extends unknown[], R>(
+  fn: (...args: A) => R,
+  key: (...args: A) => string,
+): (...args: A) => R | null {
+  return (...args: A): R | null => {
+    const scope = storage.getStore()
+    if (!scope) return fn(...args)
+    const k = key(...args)
+    const hit = scope.cache.get(k)
+    if (hit) {
+      replayReadTags(hit.tags)
+      return hit.value as R
+    }
+    if (scope.used >= scope.max) {
+      // Over budget: skip (like a stale ref) but make it OBSERVABLE — a legitimate large read silently
+      // dropping `$media`/`$relation` would otherwise be invisible. Warn ONCE per scope.
+      if (!scope.tripped) {
+        scope.tripped = true
+        console.warn(`[kestrel] resolve budget (${scope.max}) exceeded during "${scope.label}" — some references were left unpopulated. Reduce perPage/depth or raise the budget.`)
+      }
+      return null
+    }
+    scope.used++
+    const { result, tags } = withReadCaptureSync(() => fn(...args))
+    replayReadTags(tags) // the miss's own render must record them too (the sync capture is isolating)
+    scope.cache.set(k, { value: result, tags })
+    return result
+  }
+}

package/layers/core/server/utils/seo.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod'
+import type { FieldDef } from './defineCollection'
+
+export interface SeoMeta {
+  title?: string
+  description?: string
+  noindex?: boolean
+  /** Media id of the social-share image (og:image / twitter card); resolved under `seo.$media.image`. */
+  image?: number | null
+}
+
+export const seoSchema = z.object({
+  title: z.string().optional(),
+  description: z.string().optional(),
+  noindex: z.boolean().optional(),
+  image: z.number().int().positive().nullish(),
+})
+
+// The synthetic field set the row populator walks over the `seo` system column (PROPS key-mode), so the
+// social image resolves through the registered media populator — same `$media` bag, same read-capture
+// (a media change re-publishes every page whose og:image embeds it) as any real media field.
+export const seoPopulateFields: Record<string, FieldDef> = {
+  image: { type: 'media', options: { accept: 'image' } } as FieldDef,
+}