@michaelthielemann/kestrel 1.2.1

package/layers/fields/server/field-registry/index.ts

@@ -0,0 +1,248 @@
+import { integer, real, text } from 'drizzle-orm/sqlite-core'
+import type { SQLiteColumnBuilder } from 'drizzle-orm/sqlite-core'
+import { sql } from 'drizzle-orm'
+import { z } from 'zod'
+import type { FieldDef, FieldType, LinkValue } from '../../../core/server/utils/defineCollection'
+import { fieldIs } from '../../../core/server/utils/defineCollection'
+import type { FieldTypeDescriptor } from './types'
+import { sanitizeRichtext } from './sanitize'
+import { choiceValues, numberIsInteger } from '../../app/utils/field-constraints'
+import { slugify } from '../../../core/app/utils/slugify'
+import { refineConditionalRequired } from '../utils/conditional-required'
+
+// A conditional field is only `required` when its condition is met — which the per-column / per-field
+// schema can't see (no sibling access). So it is never enforced HERE: the column stays nullable and the
+// validator stays optional; the whole-record `applyConditions` hook re-enforces required-when-visible.
+export function isHardRequired(field: FieldDef): boolean {
+  return !!field.required && !field.condition
+}
+
+export function constrain<T extends SQLiteColumnBuilder>(col: T, field: FieldDef): T {
+  let c = col
+  if (isHardRequired(field)) c = c.notNull() as T
+  if (field.unique) c = c.unique() as T
+  if (field.default !== undefined) c = c.default(field.default as never) as T
+  return c
+}
+
+export const opt = (s: z.ZodType, field: FieldDef): z.ZodType => (isHardRequired(field) ? s : s.nullish())
+export const optArr = (s: z.ZodType, field?: FieldDef): z.ZodType =>
+  field && isHardRequired(field)
+    ? s.refine((v) => Array.isArray(v) && v.length > 0, { message: 'At least one value is required' })
+    // Non-required: an EXPLICIT null is a clear → the empty array [] (so a PATCH `field: null` actually
+    // resets it, consistent with the .nullish() scalar fields, rather than mapping to undefined which
+    // drizzle's .set() silently skips). An absent (undefined) value stays undefined so the column default
+    // ([]) applies on insert.
+    : z.preprocess((v) => (v === null ? [] : v), s.optional())
+
+// Array-backed column (multiple choice/media, many-relation, repeater). Honours a declared `default` (a
+// default multi-selection / seed rows), serialized as a JSON literal by the schema renderer; else '[]'.
+// (`unique` is intentionally not applied — a UNIQUE index over a JSON blob is not meaningful.)
+const jsonArray = (dbName: string, field?: FieldDef) =>
+  text(dbName, { mode: 'json' }).$type<unknown[]>().notNull()
+    .default(field?.default !== undefined ? (field.default as never) : sql`'[]'`)
+
+/** Type a built-in descriptor against its SPECIFIC arm (`FieldOf<T>`) so its body narrows correctly, then
+ *  widen to the registry's general `FieldTypeDescriptor` for storage. */
+const fieldType = <T extends FieldType>(d: FieldTypeDescriptor<T>): FieldTypeDescriptor =>
+  d as unknown as FieldTypeDescriptor
+
+/** Whether `field.unique` actually reaches a DB constraint for THIS field (options-dependent, not just
+ *  type-dependent — a `choice`/`media` field is only json-backed when `multiple`, a `relation` only when
+ *  `many`). Mirrors the `column()` arms above exactly: the json/array-backed arms (`jsonArray`, the plain
+ *  `json` type) never call `constrain()`, so `.unique()` is never invoked — `unique: true` there is a silent
+ *  no-op, not a soft hint. `buildTable` uses this to fail loud at collection-build time instead. */
+export function fieldCanEnforceUnique(field: FieldDef): boolean {
+  // `fieldIs` not `switch`: the open consumer arm makes `type` a non-discriminant (no switch narrowing).
+  if (fieldIs(field, 'choice')) return !field.options.multiple
+  if (fieldIs(field, 'media')) return !field.options?.multiple
+  if (fieldIs(field, 'relation')) return !field.relation.many
+  if (fieldIs(field, 'repeater')) return false
+  if (fieldIs(field, 'json')) return false
+  return true
+}
+
+export const fieldTypes: Record<string, FieldTypeDescriptor> = {
+  text: fieldType<'text'>({
+    column: (n, f) => constrain(text(n), f),
+    // Plain text is stored verbatim (trimmed): the column is not HTML and every consumer
+    // escapes on output, so tag-stripping here would only corrupt legitimate input (e.g. "a < b").
+    validator: (f) => {
+      let s = z.string().trim()
+      if (f.type === 'text') {
+        if (f.options?.minLength !== undefined) s = s.min(f.options.minLength)
+        if (f.options?.maxLength !== undefined) s = s.max(f.options.maxLength)
+      }
+      // A hard-required string must be non-empty — '' / whitespace is "missing" to the client validator
+      // and the conditional-required check, so the server (sole authority) must agree. Only add the
+      // implicit min(1) when no explicit minLength already enforces a lower bound.
+      if (isHardRequired(f) && (f.type !== 'text' || f.options?.minLength === undefined)) s = s.min(1)
+      return opt(s, f)
+    },
+  }),
+  // A url-safe slug, stored as text. Optionality-aware like text, but typically left non-required so it can
+  // be omitted and auto-generated from another field. `transform` derives it on write: an explicit value is
+  // slugified (normalised); a blank value falls back to slugify(record[options.from]) (e.g. the title). The
+  // `options.from`/`options.prefix` are read by the client widget too (prefix is display-only). A `unique`
+  // slug collision is a HARD, field-scoped error (`assertUniqueSlugs` in crud — no silent dedup; the editor
+  // must pick a different slug), needing the DB the pure `transform` hook can't touch, so it lives in crud.
+  slug: fieldType<'slug'>({
+    column: (n, f) => constrain(text(n), f),
+    validator: (f) => opt(isHardRequired(f) ? z.string().trim().min(1) : z.string().trim(), f),
+    transform: (value, record, field) => {
+      const explicit = typeof value === 'string' ? value.trim() : ''
+      if (explicit) return slugify(explicit)
+      const from = field.options?.from
+      const source = from ? record[from] : undefined
+      return typeof source === 'string' ? (slugify(source) || value) : value
+    },
+  }),
+  richtext: {
+    column: (n, f) => constrain(text(n), f),
+    // Required richtext must carry content: sanitize first, then reject a sanitized-empty result
+    // (e.g. '' or markup that strips to nothing), mirroring the non-empty rule for plain text.
+    validator: (f) => {
+      const base = z.string().transform(sanitizeRichtext)
+      if (!isHardRequired(f)) return base.nullish()
+      return base.refine((v) => v.trim().length > 0, { message: 'This field is required' })
+    },
+  },
+  number: fieldType<'number'>({
+    column: (n, f) =>
+      constrain(!numberIsInteger(f.options) ? real(n) : integer(n), f),
+    validator: (f) => {
+      let n = z.number()
+      if (numberIsInteger(f.options)) n = n.int()
+      if (f.options?.min !== undefined) n = n.min(f.options.min)
+      if (f.options?.max !== undefined) n = n.max(f.options.max)
+      return opt(n, f)
+    },
+  }),
+  boolean: {
+    column: (n, f) => constrain(integer(n, { mode: 'boolean' }), f),
+    validator: (f) => opt(z.boolean(), f),
+  },
+  datetime: fieldType<'datetime'>({
+    column: (n, f) =>
+      f.options?.range
+        ? constrain(text(n, { mode: 'json' }).$type<{ start: string; end: string }>(), f)
+        : constrain(text(n), f),
+    validator: (f) => {
+      const p = f.options?.precision ?? 'datetime'
+      const base = p === 'date' ? z.iso.date() : p === 'time' ? z.iso.time() : z.iso.datetime({ local: true })
+      if (f.options?.range) {
+        const r = z.object({ start: base, end: base }).refine((v) => v.start <= v.end, { message: 'start must be before or equal to end' })
+        return isHardRequired(f) ? r : r.nullish()
+      }
+      return opt(base, f)
+    },
+  }),
+  choice: fieldType<'choice'>({
+    column: (n, f) => (f.options.multiple ? jsonArray(n, f) : constrain(text(n), f)),
+    validator: (f) => {
+      const values = choiceValues(f.options)
+      const e = z.enum(values)
+      return f.options.multiple ? optArr(z.array(e), f) : opt(e, f)
+    },
+  }),
+  link: {
+    column: (n, f) => constrain(text(n, { mode: 'json' }).$type<LinkValue>(), f),
+    // The validator is type-agnostic; options.types/collections only constrain the editor widget.
+    validator: (f) => {
+      const label = z.string().trim().optional()
+      // Optional URL fragment for internal links (e.g. link to a page's section). Stored WITHOUT the
+      // leading '#' (a lenient leading '#' is stripped); restricted to an id-safe charset since it ends
+      // up verbatim in a static <a href>. `linkToHref` appends it as `<path>#<hash>` at render.
+      const hash = z.string().trim().transform((s) => s.replace(/^#+/, '')).pipe(z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]*$/, 'Invalid anchor')).optional()
+      return opt(
+        z.discriminatedUnion('type', [
+          z.object({ type: z.literal('internal'), collection: z.string().min(1), id: z.number().int(), hash, label }),
+          z.object({
+            type: z.literal('external'),
+            // http(s) only, no control chars, no embedded credentials — the value ends up in a static <a href>.
+            url: z.string().trim().pipe(z.url({ protocol: /^https?$/ })).refine((v) => {
+              if (/[\u0000-\u001f]/.test(v)) return false
+              const u = new URL(v)
+              return !u.username && !u.password
+            }, 'URL must not contain control characters or embedded credentials'),
+            label,
+          }),
+          z.object({ type: z.literal('email'), email: z.string().trim().pipe(z.email()), label }),
+          z.object({ type: z.literal('tel'), tel: z.string().trim().min(1).regex(/^[+0-9 ()\-.\/]+$/).refine((v) => /[0-9]/.test(v), 'Tel must contain at least one digit'), label }),
+        ]),
+        f,
+      )
+    },
+  },
+  media: fieldType<'media'>({
+    column: (n, f) => (f.options?.multiple ? jsonArray(n, f) : constrain(integer(n), f)),
+    validator: (f) =>
+      f.options?.multiple ? optArr(z.array(z.number().int()), f) : opt(z.number().int(), f),
+  }),
+  relation: fieldType<'relation'>({
+    column: (n, f) => (f.relation.many ? jsonArray(n, f) : constrain(integer(n), f)),
+    validator: (f) =>
+      f.relation.many ? optArr(z.array(z.number().int()), f) : opt(z.number().int(), f),
+  }),
+  repeater: fieldType<'repeater'>({
+    column: (n, f) => jsonArray(n, f),
+    validator: (f) => {
+      const shape = Object.fromEntries(
+        Object.entries(f.options.fields).map(([k, sub]) => [k, getFieldType(sub.type).validator(sub)]),
+      )
+      // Re-enforce conditional-required sub-fields per entry (the entry object is where siblings are visible).
+      return optArr(z.array(refineConditionalRequired(z.object(shape), f.options.fields)), f)
+    },
+  }),
+  json: {
+    column: (n, f) => text(n, { mode: 'json' }).$type<unknown>().notNull().default(f?.default !== undefined ? (f.default as never) : sql`'{}'`),
+    // Optionality-aware like every other arm. The column is NOT NULL with a '{}' default, so a non-required
+    // null/undefined must become `undefined` (→ default applies) rather than reaching the column as null (an
+    // unmapped NOT NULL 500); a required json must be present (a clean 400, not a 500).
+    validator: (f) =>
+      isHardRequired(f)
+        ? z.unknown().refine((v) => v !== null && v !== undefined, { message: 'This field is required' })
+        // Explicit null clears to {} (a PATCH reset); undefined stays absent so the column default ({}) applies.
+        : z.preprocess((v) => (v === null ? {} : v), z.unknown().optional()),
+  },
+}
+
+/** The names Kestrel ships built-in (captured before any consumer registration). */
+const BUILTIN_FIELD_TYPES = new Set(Object.keys(fieldTypes))
+
+/** Register a consumer-defined field type (via `defineFieldType`). Later registration wins, but never
+ *  silently: a bad descriptor throws a clear error at registration (not a cryptic TypeError when a table is
+ *  later built), and ANY re-registration of an existing name warns — overriding a built-in, or one extension
+ *  clobbering another's same-named type. */
+export function registerFieldType(name: string, descriptor: FieldTypeDescriptor): void {
+  if (typeof name !== 'string' || !name.trim()) {
+    throw new Error('[kestrel] registerFieldType: name must be a non-empty string')
+  }
+  if (typeof descriptor?.column !== 'function') {
+    throw new Error(`[kestrel] registerFieldType("${name}"): descriptor.column must be a function`)
+  }
+  if (typeof descriptor?.validator !== 'function') {
+    throw new Error(`[kestrel] registerFieldType("${name}"): descriptor.validator must be a function`)
+  }
+  if (descriptor.transform !== undefined && typeof descriptor.transform !== 'function') {
+    throw new Error(`[kestrel] registerFieldType("${name}"): descriptor.transform must be a function if provided`)
+  }
+  // Object.hasOwn, not `in`: a field type named 'constructor'/'toString'/… would otherwise match an
+  // inherited Object.prototype member (a spurious "re-registered" warning, and below a truthy lookup).
+  if (Object.hasOwn(fieldTypes, name)) {
+    console.warn(BUILTIN_FIELD_TYPES.has(name)
+      ? `[kestrel] field type "${name}" overrides a built-in`
+      : `[kestrel] field type "${name}" re-registered — the previous definition was overwritten`)
+  }
+  fieldTypes[name] = descriptor
+}
+
+/** Look up a field-type descriptor, with a clear error for an unknown / unregistered type. */
+export function getFieldType(type: string): FieldTypeDescriptor {
+  // Object.hasOwn guards the prototype chain: getFieldType('constructor') must throw the clear error, not
+  // return Object.prototype.constructor and then crash with `.column is not a function` at table build.
+  if (!Object.hasOwn(fieldTypes, type)) {
+    throw new Error(`[kestrel] unknown field type "${type}" — register it with defineFieldType in server/field-types/`)
+  }
+  return fieldTypes[type]
+}

package/layers/fields/server/field-registry/naming.ts

@@ -0,0 +1,10 @@
+import { isSingleRefColumn, type FieldDef } from '../../../core/server/utils/defineCollection'
+
+export function toSnakeCase(key: string): string {
+  return key.replace(/[A-Z]/g, (m) => `_${m.toLowerCase()}`)
+}
+
+export function resolveColumnName(key: string, field: FieldDef): { jsKey: string; dbName: string } {
+  if (isSingleRefColumn(field)) return { jsKey: `${key}Id`, dbName: `${toSnakeCase(key)}_id` }
+  return { jsKey: key, dbName: toSnakeCase(key) }
+}

package/layers/fields/server/field-registry/sanitize.ts

@@ -0,0 +1,40 @@
+import sanitizeHtml from 'sanitize-html'
+import { RICHTEXT_LINK_SCHEME } from '../../app/utils/richtext-links'
+
+export const RICHTEXT_ALLOWLIST: sanitizeHtml.IOptions = {
+  allowedTags: [
+    'p', 'br', 'span', 'strong', 'b', 'em', 'i', 'u', 's', 'sub', 'sup', 'mark',
+    'blockquote', 'pre', 'code', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+    'ul', 'ol', 'li', 'a', 'img', 'figure', 'figcaption', 'hr',
+    'table', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td',
+  ],
+  allowedAttributes: {
+    a: ['href', 'title', 'target', 'rel'],
+    img: ['src', 'alt', 'title', 'width', 'height', 'loading'],
+    '*': ['class', 'style'],
+  },
+  allowedStyles: {
+    '*': { 'text-align': [/^(left|right|center|justify)$/] },
+  },
+  // `kestrel:` is the internal-link marker (`kestrel:<collection>:<id>`), resolved to a real localized
+  // path at read time; it must survive sanitisation so the resolver can rewrite it.
+  allowedSchemes: ['http', 'https', 'mailto', 'tel', RICHTEXT_LINK_SCHEME],
+  allowedSchemesAppliedToAttributes: ['href', 'src'],
+  disallowedTagsMode: 'discard',
+  transformTags: {
+    // Only absolute http(s) (incl. protocol-relative) links are "external" → open in a new isolated
+    // tab + nofollow. Internal/relative/mailto/tel/kestrel: links keep no target/rel (a same-site link
+    // must not open a new tab or be nofollowed); any author-supplied target/rel on them is dropped.
+    a: (tagName, attribs) => {
+      if (/^(https?:)?\/\//i.test(attribs.href ?? '')) {
+        return { tagName, attribs: { ...attribs, target: '_blank', rel: 'noopener noreferrer nofollow' } }
+      }
+      const { target: _t, rel: _r, ...rest } = attribs
+      return { tagName, attribs: rest }
+    },
+  },
+}
+
+export function sanitizeRichtext(html: string): string {
+  return sanitizeHtml(html, RICHTEXT_ALLOWLIST)
+}

package/layers/fields/server/field-registry/types.ts

@@ -0,0 +1,19 @@
+import type { SQLiteColumnBuilderBase } from 'drizzle-orm/sqlite-core'
+import type { ZodType } from 'zod'
+import type { FieldOf, FieldType } from '../../../core/server/utils/defineCollection'
+
+/** Descriptor for a field `type`. Generic over the type name so a built-in descriptor's body receives its
+ *  SPECIFIC `FieldDef` arm (`FieldOf<'text'>` etc.) — the registry can't discriminate the union itself
+ *  (the open consumer arm makes `type` a non-discriminant). The default `T = FieldType` widens `field` back
+ *  to the full union for the registry's storage type + consumer-registered descriptors. */
+export interface FieldTypeDescriptor<T extends FieldType = FieldType> {
+  /** The ONLY place a Drizzle column type is decided. Pure; no Nitro/DB. */
+  column(dbName: string, field: FieldOf<T>): SQLiteColumnBuilderBase
+  /** Complete, optionality-aware Zod for the field value (drop-in replacement schema). */
+  validator(field: FieldOf<T>): ZodType
+  /** Optional write-time derivation: given this field's (validated) value, the whole record, and the field
+   *  def, return the value to persist — e.g. a slug auto-generated from another field when left blank. Runs
+   *  on create/update AFTER validation, BEFORE insert. Pure (no DB/Nitro); cross-field reads come from
+   *  `record`. */
+  transform?(value: unknown, record: Record<string, unknown>, field: FieldOf<T>): unknown
+}

package/layers/fields/server/plugins/01.register-field-populate.ts

@@ -0,0 +1,11 @@
+import { registerPopulator } from '../../../core/server/utils/populate'
+import { buildFieldTreePopulator } from '../utils/field-populate'
+
+// The single global row populator: walks a record's fields + block tree and dispatches each field to its
+// per-type populator (media / link / richtext / relation), each registered by its owning layer. It recurses
+// repeater entries, block props, and slots, so nested references resolve everywhere — not just at the top
+// level. Field populators are looked up at read time, so this plugin's order vs the layer plugins that
+// register them does not matter.
+export default defineNitroPlugin(() => {
+  registerPopulator(buildFieldTreePopulator())
+})

package/layers/fields/server/utils/block-ids.ts

@@ -0,0 +1,43 @@
+import { randomUUID } from 'node:crypto'
+
+// Server-side twin of the admin's `cloneBlockTree` (layers/admin/app/utils/block-tree.ts): re-mint every
+// block id at every slot depth, preserving type / props / structure. This is a DELIBERATE crossing-free
+// duplication, NOT a reshape: `cloneBlockTree` lives in the ADMIN (client) layer and is unreachable from a
+// server layer, so the record-duplicate operation gets its own pure, node-tested helper here in `fields`
+// (the block-content-shape home) rather than inverting the layer dependency. No field-def dependency — a
+// plain traversal of the `{ id, type, props?, slots? }` node shape — so it unit-tests hard.
+
+type GenId = () => string
+
+interface BlockNode {
+  id: string
+  type: string
+  props?: Record<string, unknown>
+  slots?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+/**
+ * Return a copy of a block `content` array with a FRESH id on every node at every slot depth, so a
+ * duplicated record never shares block identity with its source (the id-addressed tree, error addressing
+ * and per-record edit state all rely on ids being unique per record). Props and slot structure are deep-
+ * cloned and preserved verbatim. A non-array `content` (or a non-object node) passes through untouched.
+ * `genId` is injectable for deterministic tests; it defaults to `crypto.randomUUID`.
+ */
+export function regenerateBlockIds(content: unknown, genId: GenId = randomUUID): unknown {
+  if (!Array.isArray(content)) return content
+  return content.map((node) => cloneNode(node, genId))
+}
+
+function cloneNode(node: unknown, genId: GenId): unknown {
+  if (!node || typeof node !== 'object' || Array.isArray(node)) return node
+  const n = node as BlockNode
+  const copy: BlockNode = { ...n, id: genId() }
+  if (n.props && typeof n.props === 'object') copy.props = structuredClone(n.props)
+  if (n.slots && typeof n.slots === 'object' && !Array.isArray(n.slots)) {
+    copy.slots = Object.fromEntries(
+      Object.entries(n.slots).map(([name, arr]) => [name, Array.isArray(arr) ? arr.map((c) => cloneNode(c, genId)) : arr]),
+    )
+  }
+  return copy
+}

package/layers/fields/server/utils/block-populate.ts

@@ -0,0 +1,41 @@
+import type { FieldDef } from '../../../core/server/utils/defineCollection'
+import { getBlock } from './defineBlock'
+
+/** A per-block-props mutation: populate/resolve one block's props in place, given its field defs. */
+export type ApplyBlockFields = (props: Record<string, unknown>, fields: Record<string, FieldDef>) => void
+
+/**
+ * The shared block-content walker for server-side populators (media `$media`, internal-link resolution,
+ * …). Maps a `content` array, deep-cloning each block node, applying `applyFields` to a clone of its
+ * `props` (block type looked up via the registry), and recursing into every declared slot. The differing
+ * per-field work lives in `applyFields`; only this clone-and-recurse traversal is shared. Returns a fresh
+ * array (server populators hand back new rows); nodes that aren't block objects pass through untouched.
+ */
+export function buildBlockPopulator(applyFields: ApplyBlockFields): (nodes: unknown) => unknown[] {
+  const walk = (nodes: unknown): unknown[] => {
+    if (!Array.isArray(nodes)) return []
+    return nodes.map((node) => {
+      if (!node || typeof node !== 'object') return node
+      const original = node as { type?: string; props?: Record<string, unknown>; slots?: Record<string, unknown> }
+      const cloned: Record<string, unknown> = { ...original }
+
+      const blockDef = original.type ? getBlock(original.type) : undefined
+      if (blockDef && original.props) {
+        const props: Record<string, unknown> = { ...original.props }
+        cloned.props = props
+        applyFields(props, blockDef.fields)
+      }
+
+      if (original.slots && typeof original.slots === 'object') {
+        const slots: Record<string, unknown> = {}
+        for (const [slotName, slotNodes] of Object.entries(original.slots)) {
+          slots[slotName] = walk(slotNodes)
+        }
+        cloned.slots = slots
+      }
+
+      return cloned
+    })
+  }
+  return walk
+}

package/layers/fields/server/utils/buildCollection.ts

@@ -0,0 +1,88 @@
+import { createInsertSchema, createUpdateSchema, createSelectSchema } from 'drizzle-zod'
+import { z } from 'zod'
+import type { ZodType } from 'zod'
+import type { CollectionDef } from '../../../core/server/utils/defineCollection'
+import type { BuiltCollection, CollectionSchema } from '../../../core/server/utils/collection-types'
+import { seoSchema } from '../../../core/server/utils/seo'
+import { evaluateCondition, isEmptyValue } from '../../app/utils/condition'
+import { buildTable } from './buildTable'
+import { buildFieldSchema } from './buildFieldSchema'
+import { resolveColumnName } from '../field-registry/naming'
+import { allBlocks, buildBlocksSchema } from './defineBlock'
+
+/** A page path is consumed verbatim at build time to derive prerender routes / output file paths,
+ *  so it must be incapable of traversal: url-path-safe charset only, no `.`/`..` segments. */
+export function isSafePagePath(p: string): boolean {
+  if (!/^[A-Za-z0-9._~%/-]*$/.test(p)) return false
+  return !p.split('/').some((seg) => seg === '.' || seg === '..')
+}
+
+export function systemRefinements(def: CollectionDef): Record<string, unknown> {
+  const refine: Record<string, unknown> = {}
+  if (def.translatable) refine.locale = z.string().optional()
+  if (def.mode === 'single') refine.singletonKey = z.string().optional()
+  else if (def.translatable) refine.translationGroup = z.string().optional()
+  if (def.pageLike) refine.path = z.string().refine(isSafePagePath, 'Invalid path').nullable().optional()
+  // The status column is a two-state enum; without this the schema accepts any string and a typo
+  // ('publushed') stores verbatim and silently unpublishes the record (every gate matches only 'published').
+  if (def.status) refine.status = z.enum(['draft', 'published']).optional()
+  if (def.blocks?.enabled) refine.content = z.lazy(() => buildBlocksSchema(allBlocks(def.blocks?.allowed))).optional()
+  if (def.seo) refine.seo = seoSchema.partial().optional()
+  return refine
+}
+
+// Update is a partial PATCH: every field may be omitted, so the field refinements
+// must be optional on update (a required validator would otherwise override
+// drizzle-zod's partial column schema and force the field on every update).
+function optionalize(refine: Record<string, ZodType>): Record<string, ZodType> {
+  const out: Record<string, ZodType> = {}
+  for (const [key, schema] of Object.entries(refine)) out[key] = schema.optional()
+  return out
+}
+
+/**
+ * Accept either a plain `CollectionDef` (the common consumer form: `export default defineCollection(…)`)
+ * or an already-built collection (the advanced form, when a server route needs the drizzle table object
+ * directly: `const built = buildCollection(…); export const t = built.table; export default built`).
+ * The discriminator is the presence of `table`, which only a BuiltCollection has.
+ */
+export function ensureBuilt(c: CollectionDef | BuiltCollection): BuiltCollection {
+  return 'table' in c ? c : buildCollection(c)
+}
+
+/**
+ * Build the `applyConditions` hook for a collection with conditional required fields, or `undefined`
+ * when it has none (so CRUD skips it). The per-field schema relaxed every conditional field to optional
+ * (it can't see siblings); this re-enforces `required` for the ones whose condition is met against the
+ * whole record. Issues are keyed by the field's def name (so they map to the editor's per-field errors),
+ * resolving each value at its column key (`<name>Id` for single relation/media).
+ */
+function buildApplyConditions(def: CollectionDef): BuiltCollection['applyConditions'] {
+  const required = Object.entries(def.fields).filter(([, f]) => f.condition && f.required)
+  if (!required.length) return undefined
+  return (record) => {
+    const scope: Record<string, unknown> = {}
+    for (const [key, field] of Object.entries(def.fields)) scope[key] = record[resolveColumnName(key, field).jsKey]
+    const issues = required
+      .filter(([key, field]) => evaluateCondition(field.condition!, scope) && isEmptyValue(record[resolveColumnName(key, field).jsKey]))
+      .map(([key]) => ({ path: [key], message: 'This field is required.' }))
+    return { issues }
+  }
+}
+
+export function buildCollection(def: CollectionDef): BuiltCollection {
+  const table = buildTable(def)
+  const fieldRefine = buildFieldSchema(def.fields)
+  const system = systemRefinements(def)
+  return {
+    name: def.name,
+    def,
+    table,
+    // Cast through the loose `CollectionSchema`: drizzle-zod's overloads otherwise infer mismatched (ZodEnum)
+    // types that don't unify across the three builders (see CollectionSchema's note).
+    insert: createInsertSchema(table, { ...fieldRefine, ...system } as never) as unknown as CollectionSchema,
+    update: createUpdateSchema(table, { ...optionalize(fieldRefine), ...system } as never) as unknown as CollectionSchema,
+    select: createSelectSchema(table) as unknown as CollectionSchema,
+    applyConditions: buildApplyConditions(def),
+  }
+}

package/layers/fields/server/utils/buildFieldSchema.ts

@@ -0,0 +1,22 @@
+import type { ZodType } from 'zod'
+import type { FieldDef } from '../../../core/server/utils/defineCollection'
+import { getFieldType } from '../field-registry'
+import { resolveColumnName } from '../field-registry/naming'
+
+function buildShape(fields: Record<string, FieldDef>, keyOf: (key: string, field: FieldDef) => string): Record<string, ZodType> {
+  const out: Record<string, ZodType> = {}
+  for (const [key, field] of Object.entries(fields)) {
+    out[keyOf(key, field)] = getFieldType(field.type).validator(field)
+  }
+  return out
+}
+
+/** Collection columns: keyed by jsKey (matches buildTable's column keys). */
+export function buildFieldSchema(fields: Record<string, FieldDef>): Record<string, ZodType> {
+  return buildShape(fields, (key, field) => resolveColumnName(key, field).jsKey)
+}
+
+/** Block props: keyed by the raw field name (props are not DB columns). */
+export function buildFieldObjectSchema(fields: Record<string, FieldDef>): Record<string, ZodType> {
+  return buildShape(fields, (key) => key)
+}

package/layers/fields/server/utils/buildTable.ts

@@ -0,0 +1,107 @@
+import { sqliteTable, integer, text, uniqueIndex, index } from 'drizzle-orm/sqlite-core'
+import type { SQLiteColumnBuilderBase, SQLiteTable } from 'drizzle-orm/sqlite-core'
+import { sql } from 'drizzle-orm'
+import type { Block } from '../../../core/server/utils/blocks'
+import type { SeoMeta } from '../../../core/server/utils/seo'
+import type { CollectionDef } from '../../../core/server/utils/defineCollection'
+import { getFieldType, fieldCanEnforceUnique } from '../field-registry'
+import { resolveColumnName } from '../field-registry/naming'
+
+/** The system columns this def actually emits (jsKey + DB-name forms), gated by the SAME flags that add
+ *  them in `buildTable` — so a field may only use e.g. `content`/`status` on a collection that doesn't
+ *  enable blocks/status. A field resolving to one of these would silently overwrite a system column. */
+function reservedColumns(def: CollectionDef): { js: Set<string>; db: Set<string> } {
+  const js = new Set(['id', 'createdAt', 'updatedAt'])
+  const db = new Set(['id', 'created_at', 'updated_at'])
+  const add = (j: string, d: string) => { js.add(j); db.add(d) }
+  if (def.translatable) add('locale', 'locale')
+  if (def.mode === 'single') add('singletonKey', 'singleton_key')
+  else if (def.translatable) add('translationGroup', 'translation_group')
+  if (def.pageLike) add('path', 'path')
+  if (def.status) add('status', 'status')
+  if (def.seo) add('seo', 'seo')
+  if (def.blocks?.enabled) add('content', 'content')
+  return { js, db }
+}
+
+function buildIndexes(def: CollectionDef, t: Record<string, never>) {
+  const out = []
+  const names = new Set<string>()
+  // System indexes are named first, so a colliding field index (below) is the one that fails loud —
+  // the fixed system naming scheme can't be the thing that has to change.
+  const system = (name: string) => { names.add(name); return name }
+  if (def.mode === 'single') {
+    out.push(def.translatable
+      ? uniqueIndex(system(`${def.name}_key_locale`)).on(t.singletonKey, t.locale)
+      : uniqueIndex(system(`${def.name}_key`)).on(t.singletonKey))
+  } else if (def.translatable) {
+    out.push(uniqueIndex(system(`${def.name}_group_locale`)).on(t.translationGroup, t.locale))
+    out.push(index(system(`${def.name}_group`)).on(t.translationGroup))
+  }
+  if (def.pageLike) {
+    out.push(def.translatable
+      ? uniqueIndex(system(`${def.name}_path_locale`)).on(t.path, t.locale).where(sql`path is not null`)
+      : uniqueIndex(system(`${def.name}_path`)).on(t.path).where(sql`path is not null`))
+  }
+  // Opt-in non-unique field indexes (`index: true`) — for columns that are frequently filtered/sorted but
+  // not unique (e.g. media.folder). `unique` fields already get an index from the field-type's `.unique()`.
+  // A name that collides with a system index (e.g. a field named "key" on a singleton) would otherwise mint
+  // TWO indexes of the same name — drizzle-kit's `syncSchema` then throws at DEPLOY time, not authoring
+  // time. Fail loud here instead, same style as the reserved-column / duplicate-column guards above.
+  for (const [key, field] of Object.entries(def.fields)) {
+    if (!field.index || field.unique) continue
+    const { jsKey, dbName } = resolveColumnName(key, field)
+    const name = `${def.name}_${dbName}`
+    if (names.has(name)) {
+      throw new Error(`kestrel: collection "${def.name}" field "${key}" produces the index name "${name}", which collides with a system index — rename the field.`)
+    }
+    names.add(name)
+    out.push(index(name).on(t[jsKey as keyof typeof t]))
+  }
+  return out
+}
+
+export function buildTable(def: CollectionDef): SQLiteTable {
+  const cols: Record<string, SQLiteColumnBuilderBase> = {}
+  cols.id = integer('id').primaryKey({ autoIncrement: true })
+  if (def.translatable) cols.locale = text('locale').notNull()
+  if (def.mode === 'single') cols.singletonKey = text('singleton_key').notNull()
+  else if (def.translatable) cols.translationGroup = text('translation_group').notNull()
+  if (def.pageLike) cols.path = text('path')
+  if (def.status) cols.status = text('status').notNull().default('draft')
+  if (def.seo) cols.seo = text('seo', { mode: 'json' }).$type<SeoMeta>().notNull().default(sql`'{}'`)
+  if (def.blocks?.enabled) cols.content = text('content', { mode: 'json' }).$type<Block[]>().notNull().default(sql`'[]'`)
+
+  const reserved = reservedColumns(def)
+  const seenJsKeys = new Set<string>()
+  const seenDbNames = new Set<string>()
+  for (const [key, field] of Object.entries(def.fields)) {
+    const { jsKey, dbName } = resolveColumnName(key, field)
+    // Fail loud (matching defineCollection's pageLike guard) rather than silently overwriting a system
+    // column — e.g. a field named `id`/`status` would clobber the PK / publish-gating column — or
+    // shadowing a sibling whose resolved key collides (a single-ref `foo` → `fooId` vs a literal `fooId`).
+    if (reserved.js.has(jsKey) || reserved.db.has(dbName)) {
+      throw new Error(`kestrel: collection "${def.name}" field "${key}" resolves to the reserved system column "${jsKey}" — rename the field.`)
+    }
+    if (seenJsKeys.has(jsKey) || seenDbNames.has(dbName)) {
+      throw new Error(`kestrel: collection "${def.name}" field "${key}" resolves to column "${jsKey}"/"${dbName}", which collides with another field — rename one of them.`)
+    }
+    // `unique` on a json/array-backed column (multi-choice, multi-media, many-relation, repeater, json) is
+    // a silent no-op — the column type never carries a DB constraint for it. Warn rather than throw: the
+    // flag is inert, so a definition that boots today must keep booting.
+    if (field.unique && !fieldCanEnforceUnique(field)) {
+      console.warn(`kestrel: collection "${def.name}" field "${key}" is "unique", but its storage (${field.type}, multi-valued) can never enforce a DB uniqueness constraint — the flag is ignored.`)
+    }
+    seenJsKeys.add(jsKey)
+    seenDbNames.add(dbName)
+    cols[jsKey] = getFieldType(field.type).column(dbName, field)
+  }
+
+  // `timestamp_ms` (not `timestamp`) keeps MILLISECOND precision: the optimistic-concurrency check compares
+  // `updatedAt` exactly, and second-granularity would let two saves in the same wall-clock second share a
+  // token — a stale tab could then silently revert a newer save. Same INTEGER column type, so no DDL change.
+  cols.createdAt = integer('created_at', { mode: 'timestamp_ms' }).notNull().$defaultFn(() => new Date())
+  cols.updatedAt = integer('updated_at', { mode: 'timestamp_ms' }).notNull().$defaultFn(() => new Date())
+
+  return sqliteTable(def.name, cols, (t) => buildIndexes(def, t as unknown as Record<string, never>))
+}