@supatype/cli 0.1.12 → 0.1.13

package/src/dev-compose.ts

@@ -14,10 +14,12 @@ import {
   connectionString,
   projectRootFromConfig,
   resolveRuntimeProvider,
+  hooksPathFromProject,
   schemaPathFromProject,
   usesExternalDatabase,
   type SupatypeProjectConfig,
 } from "./project-config.js"
+import { syncManifestHooks, writeHooksModule } from "./model-hooks.js"
 import { signJwt } from "./jwt.js"
 import { ensureDevDbPort, ensureKongPort } from "./dev-ports.js"
 import { handleComposeProjectRename } from "./compose-rename.js"
@@ -37,11 +39,16 @@ import {
 import type { DockerBrandOptions } from "./docker-runtime.js"
 import { hasEngineOverride } from "./binary-cache.js"
 import { STUDIO_DEV_PORT, startStudioViteDevServer } from "./studio-dev-server.js"
-import { ensureLocalServerDockerImage } from "./compose-local-server-image.js"
+import {
+  ensureLocalServerDockerImage,
+  usesLocalServerImage,
+  LOCAL_SERVER_DOCKER_IMAGE,
+} from "./compose-local-server-image.js"
 import { ensureEngine, engineRequest, type DiffResult } from "./engine-client.js"
 import { writeSchemaSourcePushArtifacts, type SchemaSourcePushArtifacts } from "./schema-sources.js"
 import { readEnvValue, upsertEnvFile } from "./env-file.js"
 import {
+  devAuthenticatorPassword,
   devJwtSecret,
   devPostgresPassword,
   seedMissingDatabaseIdentity,
@@ -219,14 +226,13 @@ async function startComposeDatabase(
   await waitComposeHealthy(paths, cwd, timeoutMs, project)
 }
 
-function upsertDevComposeEnv(
+export function upsertDevComposeEnv(
   cwd: string,
   config: SupatypeProjectConfig,
   anonKey: string,
   serviceRoleKey: string,
   kongPort: number,
   devDbPort?: number,
-  localServerImage?: string,
 ): void {
   const apiUrl = `http://localhost:${kongPort}`
   const imagePins = composeDockerImageEnv(config)
@@ -261,7 +267,6 @@ function upsertDevComposeEnv(
     SITE_URL: apiUrl,
     GOTRUE_MAILER_AUTOCONFIRM: "true",
     ...imagePins,
-    ...(localServerImage !== undefined && { SUPATYPE_SERVER_IMAGE: localServerImage }),
   }
   // Never for an external database: this URL describes the `db` container, which that project does
   // not have. Writing it overwrote the operator's own DATABASE_URL, the value the whole stack and
@@ -278,10 +283,25 @@ function upsertDevComposeEnv(
     updates.DATABASE_URL =
       `postgresql://${dbUser}:${devPostgresPassword(cwd)}@localhost:${devDbPort}/${dbName}?sslmode=disable`
   }
-  const removeImageKeys = COMPOSE_PINNED_IMAGE_ENV_KEYS.filter((key) => !(key in imagePins))
+  // `SUPATYPE_SERVER_IMAGE` is written here, not passed in, and it is deliberately *not* marked
+  // managed. The managed marker means "this value came from `versions` in the config and is mine to
+  // clean up when the pin goes away". The locally built image comes from `overrides`, so removing
+  // it as an unpinned managed key was wrong: any `.env` write that did not know about the local
+  // image deleted it, and compose then recreated the server from the published image.
+  const wantsLocalServer = usesLocalServerImage(cwd, config)
+  if (wantsLocalServer) updates.SUPATYPE_SERVER_IMAGE = LOCAL_SERVER_DOCKER_IMAGE
+
+  const managedImageKeys = COMPOSE_PINNED_IMAGE_ENV_KEYS.filter(
+    (key) => !(wantsLocalServer && key === "SUPATYPE_SERVER_IMAGE"),
+  )
+  const removeImageKeys = managedImageKeys.filter((key) => !(key in imagePins))
   upsertEnvFile(cwd, updates, {
     removeManaged: removeImageKeys,
-    managed: COMPOSE_PINNED_IMAGE_ENV_KEYS,
+    managed: managedImageKeys,
+    // A local image left in `.env` after the project stopped asking for one would keep pointing
+    // compose at a stale build, and it carries no marker for `removeManaged` to act on.
+    ...(!wantsLocalServer &&
+      !("SUPATYPE_SERVER_IMAGE" in imagePins) && { remove: ["SUPATYPE_SERVER_IMAGE"] }),
   })
 }
 
@@ -293,9 +313,8 @@ function ensureDevComposeEnv(
   serviceRoleKey: string,
   kongPort: number,
   devDbPort?: number,
-  localServerImage?: string,
 ): void {
-  upsertDevComposeEnv(cwd, config, anonKey, serviceRoleKey, kongPort, devDbPort, localServerImage)
+  upsertDevComposeEnv(cwd, config, anonKey, serviceRoleKey, kongPort, devDbPort)
 }
 
 async function waitComposeHealthy(paths: SelfHostComposePaths, cwd: string, maxMs: number, composeProject: string): Promise<void> {
@@ -441,6 +460,20 @@ async function refreshSchemaArtifacts(
   const supatypeDir = join(cwd, ".supatype")
   const adminConfigPath = join(supatypeDir, "admin-config.json")
 
+  // Before the engine gate below: these are read straight off the AST, so a push whose engine is
+  // unavailable should still leave the server the right maps. The server watches this file, so a
+  // hook or validator added to the schema takes effect without restarting the stack.
+  //
+  // `dev` used to skip both entirely, because only the `direct`/`local` push branch wrote them.
+  // Every project running on Compose therefore had a manifest with no `hooks` and no `validators`
+  // key, and the server, having nothing to call, ran neither. A hook silently not firing is bad; a
+  // validator silently not firing means a write the schema says is checked is accepted with a 201.
+  const hooksModule = writeHooksModule(cwd, hooksPathFromProject(config, cwd), ast)
+  if (hooksModule !== null) console.log(`[supatype] Hook handler types written to ${hooksModule}`)
+  if (syncManifestHooks(cwd, ast)) {
+    console.log("[supatype] Hook and validator maps written to .supatype/manifest.json")
+  }
+
   try {
     await ensureEngine()
   } catch (err) {
@@ -848,7 +881,7 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
   const devBrand = { intro: "Local development" }
   const localServerImage = await ensureLocalServerDockerImage(cwd, config, devBrand)
 
-  ensureDevComposeEnv(cwd, config, anonKey, serviceRoleKey, kongPort, devDbPort, localServerImage)
+  ensureDevComposeEnv(cwd, config, anonKey, serviceRoleKey, kongPort, devDbPort)
 
   console.log(`[supatype] provider docker, starting self-host Compose stack (project ${project}, gateway :${kongPort})...`)
   const paths = writeSelfHostCompose(cwd, config, { devLocal: true })
@@ -901,6 +934,10 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
   // Settle before DDL: pg_isready can pass slightly before the instance is stable.
   await new Promise((r) => setTimeout(r, 3000))
 
+  if (!usesExternalDatabase(config)) {
+    reconcileAuthenticatorPassword(paths, cwd, project)
+  }
+
   // A: apply schema before realtime (and the rest of the stack) starts decoding WAL.
   const schemaPath = schemaPathFromProject(config, cwd)
   {
@@ -1104,6 +1141,56 @@ function astHasSystemAuthRelation(ast: unknown): boolean {
   return false
 }
 
+/**
+ * Set `authenticator`'s password to the one `.env` holds, every time the stack starts.
+ *
+ * The Postgres image passwords that role from `AUTHENTICATOR_PASSWORD` in its init scripts, which
+ * run once, on an empty data directory. So the value the role actually has is whatever `.env` said
+ * the day the volume was created, and `.env` can move afterwards. When the two diverge PostgREST
+ * cannot log in, exits, and every REST request answers 502 with the real reason visible only in a
+ * container log the developer has no reason to read.
+ *
+ * Reconciling here makes `.env` the answer to what the password is, rather than the volume's
+ * birthday. It is idempotent, and it runs before the schema push so the API is already reachable by
+ * the time the stack reports ready.
+ */
+function reconcileAuthenticatorPassword(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+): void {
+  const composeDir = dirname(paths.composePath)
+  const owner = readEnvValue(cwd, "POSTGRES_USER", "supatype_admin")
+  const database = readEnvValue(cwd, "POSTGRES_DB", "supatype")
+  const result = spawnSync(
+    "docker",
+    [
+      "compose", "-p", composeProject, "-f", paths.composePath,
+      "exec", "-T",
+      "-e", `PGPASSWORD=${devPostgresPassword(cwd)}`,
+      "-e", `SUPATYPE_AUTHENTICATOR_PASSWORD=${devAuthenticatorPassword(cwd)}`,
+      "db", "psql", "-v", "ON_ERROR_STOP=1", "-U", owner, "-d", database,
+    ],
+    {
+      cwd: composeDir,
+      encoding: "utf8",
+      timeout: 10_000,
+      // `\getenv` reads the value from the container's environment, so the password is never a
+      // `docker exec` argument, which any process listing on the machine would show.
+      input: [
+        "\\getenv pw SUPATYPE_AUTHENTICATOR_PASSWORD",
+        "ALTER ROLE authenticator WITH LOGIN PASSWORD :'pw';",
+        "",
+      ].join("\n"),
+    },
+  )
+  if (result.status !== 0) {
+    console.warn(
+      "[supatype] Could not set the authenticator password; the REST API may answer 502.",
+    )
+  }
+}
+
 function grantAuthSchemaAccess(
   paths: SelfHostComposePaths,
   cwd: string,

package/src/field-bounds.ts

@@ -0,0 +1,359 @@
+/**
+ * What a declared bound means for each field kind, and the SQL it compiles to.
+ *
+ * **This table is the mechanism.** Bounds used to be compiled inside the modifier cases of
+ * `type-extractor.ts`, which meant `MaxLength` became `char_length(col)` whatever the column turned
+ * out to be: `char_length(text[])` does not exist, so the RFC's own `tags: MaxLength<string[], 10>`
+ * produced SQL that fails `CREATE TABLE`. Worse, nine of twelve engine field structs had nowhere to
+ * put a `check`, so the constraint was dropped by serde with no error anywhere in the chain.
+ *
+ * A table keyed by kind fixes the class of bug rather than the instances: a kind absent from
+ * {@link BOUNDS_BY_KIND} throws, so a new field kind cannot be added without answering "what does a
+ * bound mean here", and every answer is either an expression or a refusal with a named alternative.
+ * There is no third outcome, which is what "no bound is ever silent" means in practice.
+ */
+import { FIELD_KINDS, type FieldKind, type FieldValidation } from "./schema-ast-v2.js"
+
+/** Bounds as declared on the type, before anything knows what column they will land on. */
+export interface DeclaredBounds {
+  maxLength?: number
+  minLength?: number
+  maxItems?: number
+  minItems?: number
+  min?: number | string
+  max?: number | string
+}
+
+/** What "length" counts, per storage. */
+type LengthForm = "chars" | "octets" | "richText"
+/** What "items" counts, per storage. */
+type ItemsForm = "array" | "jsonbArray"
+/** What a range compares against. Temporal forms name the cast, which is never `numeric`. */
+type RangeForm = "numeric" | "timestamptz" | "date" | "timestamp" | "interval"
+
+type BoundFamily = "length" | "items" | "range"
+
+interface KindBounds {
+  length?: LengthForm
+  items?: ItemsForm
+  range?: RangeForm
+  /** Where to send someone whose bound this kind refuses. */
+  instead?: Partial<Record<BoundFamily, string>>
+}
+
+const TEXTUAL: KindBounds = {
+  length: "chars",
+  instead: {
+    items: "text has characters, not items; use MaxLength/MinLength",
+    range: "text is not ordered numerically; use a model-level constraint if you need a comparison",
+  },
+}
+
+const NUMERIC: KindBounds = {
+  range: "numeric",
+  instead: {
+    length: "a number has no length; use Between to bound its value",
+    items: "a number has no items; use Between to bound its value",
+  },
+}
+
+const temporal = (range: RangeForm): KindBounds => ({
+  range,
+  instead: {
+    length: "a date has no length; use Between with ISO-8601 string bounds",
+    items: "a date has no items; use Between with ISO-8601 string bounds",
+  },
+})
+
+const NO_BOUNDS = (why: string): KindBounds => ({
+  instead: { length: why, items: why, range: why },
+})
+
+/**
+ * What each bound means for each kind.
+ *
+ * `Record<FieldKind, KindBounds>` is the whole mechanism: it is **exhaustive by the compiler**, so
+ * adding a kind to `FIELD_KINDS` fails the build here until someone says what `MaxLength`,
+ * `MaxItems` and `Between` do for it. Composite kinds (`timestamps`, `publishable`, `softDelete`)
+ * expand into real columns before a bound could apply, so they carry none, but they still have to
+ * say so.
+ */
+const BOUNDS_BY_KIND: Record<FieldKind, KindBounds> = {
+  text: TEXTUAL,
+  email: TEXTUAL,
+  url: TEXTUAL,
+  slug: TEXTUAL,
+  color: TEXTUAL,
+  xml: TEXTUAL,
+  ip: TEXTUAL,
+  cidr: TEXTUAL,
+  macaddr: TEXTUAL,
+  tsQuery: TEXTUAL,
+  tsVector: TEXTUAL,
+
+  richText: {
+    length: "richText",
+    instead: {
+      items: "rich text is measured in characters of plain text; use MaxLength/MinLength",
+      range: "rich text is not ordered; use MaxLength/MinLength",
+    },
+  },
+
+  bytes: {
+    length: "octets",
+    instead: {
+      items: "a binary column has octets, not items; use MaxLength/MinLength",
+      range: "a binary column is not ordered; use MaxLength/MinLength",
+    },
+  },
+
+  integer: NUMERIC,
+  smallInt: NUMERIC,
+  bigInt: NUMERIC,
+  float: NUMERIC,
+  serial: NUMERIC,
+  bigSerial: NUMERIC,
+  decimal: NUMERIC,
+  money: NUMERIC,
+
+  datetime: temporal("timestamptz"),
+  timestamp: temporal("timestamp"),
+  date: temporal("date"),
+  interval: temporal("interval"),
+
+  array: {
+    items: "array",
+    instead: {
+      length: "an array has items, not characters; use MaxItems/MinItems",
+      range: "an array is not ordered; use MaxItems/MinItems",
+    },
+  },
+
+  blocks: {
+    items: "jsonbArray",
+    instead: {
+      length: "blocks are counted, not measured; use MaxItems/MinItems",
+      range: "blocks are not ordered; use MaxItems/MinItems",
+    },
+  },
+
+  // `json` is decided per field, not per kind: `JSON<Item[]>` takes item bounds and `JSON<{...}>`
+  // takes none. {@link boundsForKind} applies that, which is why the entry here is the object case.
+  json: NO_BOUNDS(
+    "a JSON object has no single measure; bound a sub-field with a model-level constraint, " +
+      "or declare the field as JSON<T[]> to bound its element count",
+  ),
+  button: NO_BOUNDS("a button is a composite value; bound a sub-field with a model-level constraint"),
+
+  enum: NO_BOUNDS("the union already constrains the permitted values"),
+  boolean: NO_BOUNDS("a boolean has two values and needs no bound"),
+  uuid: NO_BOUNDS("a UUID is fixed width"),
+  image: NO_BOUNDS("size and type limits belong on the bucket: fileSizeLimit and allowedMimeTypes"),
+  file: NO_BOUNDS("size and type limits belong on the bucket: fileSizeLimit and allowedMimeTypes"),
+  geo: NO_BOUNDS("a geometry is not measured this way"),
+  vector: NO_BOUNDS("the dimension is already fixed by the type, as Vector<N>"),
+  relation: NO_BOUNDS("bound the column on the model this relation points at"),
+  custom: NO_BOUNDS("a plugin field declares its own storage; bounds are the plugin's to define"),
+
+  timestamps: NO_BOUNDS("a composite expands into columns before a bound could apply"),
+  publishable: NO_BOUNDS("a composite expands into columns before a bound could apply"),
+  softDelete: NO_BOUNDS("a composite expands into columns before a bound could apply"),
+}
+
+/**
+ * Re-exported for tests. Completeness is now the compiler's job, not a test's: this exists so the
+ * matrix can assert it covers every kind, which is a different question from whether every kind is
+ * classified.
+ */
+export const CLASSIFIED_KINDS: readonly FieldKind[] = FIELD_KINDS
+
+/** `JSON<T[]>` counts elements; `JSON<{...}>` takes no bound. Anything else follows its kind. */
+function boundsForKind(kind: FieldKind, jsonIsArray: boolean): KindBounds {
+  const entry = BOUNDS_BY_KIND[kind]
+  if (kind === "json" && jsonIsArray) {
+    return {
+      items: "jsonbArray",
+      instead: {
+        length: "a JSON array has items, not characters; use MaxItems/MinItems",
+        range: "a JSON array is not ordered; use MaxItems/MinItems",
+      },
+    }
+  }
+  return entry
+}
+
+/** How a column is measured, once the kind has decided. */
+export type MeasureForm = LengthForm | ItemsForm
+
+export interface MeasureResolution {
+  /** How to measure, when this kind can be measured this way. */
+  form?: MeasureForm
+  /** Why it cannot, and what to use instead. Present exactly when `form` is not. */
+  instead?: string
+}
+
+/**
+ * How a kind is measured, for one measure family.
+ *
+ * **The single answer for both paths.** `MaxLength<T, N>` on a field and `Length<"col">` inside a
+ * model constraint have to agree about what "length" means for a given column, or the same schema
+ * gets `char_length` in one place and `cardinality` in the other. A second table for the constraint
+ * path is how `char_length(text[])` would come back, in a new file, having been fixed once already.
+ */
+export function measureFormFor(
+  kind: FieldKind,
+  measure: "length" | "items",
+  options: { jsonIsArray?: boolean } = {},
+): MeasureResolution {
+  const entry = boundsForKind(kind, options.jsonIsArray === true)
+  const form = measure === "length" ? entry.length : entry.items
+  if (form !== undefined) return { form }
+  return { instead: entry.instead?.[measure] ?? `a ${kind} field cannot be measured that way` }
+}
+
+const COLUMN = '"{name}"'
+
+function lengthExpr(form: LengthForm): string {
+  switch (form) {
+    case "chars":
+      return `char_length(${COLUMN})`
+    case "octets":
+      return `octet_length(${COLUMN})`
+    case "richText":
+      return `char_length(_supatype.richtext_text(${COLUMN}))`
+  }
+}
+
+/**
+ * `jsonb_array_length` raises `cannot get array length of a non-array` at insert time, so the type
+ * guard is part of the constraint rather than an assumption about what callers send.
+ */
+function itemsClause(form: ItemsForm, comparisons: string[]): string {
+  if (form === "array") {
+    return comparisons.map((c) => `cardinality(${COLUMN}) ${c}`).join(" AND ")
+  }
+  const guarded = comparisons.map((c) => `jsonb_array_length(${COLUMN}) ${c}`).join(" AND ")
+  return `jsonb_typeof(${COLUMN}) = 'array' AND ${guarded}`
+}
+
+function rangeLiteral(form: RangeForm, value: number | string): string {
+  if (form === "numeric") return String(value)
+  const cast = form === "timestamptz" ? "timestamptz" : form
+  return `'${String(value).replace(/'/g, "''")}'::${cast}`
+}
+
+/** ISO-8601 date, date-time or a Postgres interval. Validated here so a bad literal is a CLI error. */
+function isTemporalLiteral(form: RangeForm, value: string): boolean {
+  if (form === "interval") return /^\s*\d+\s+[a-z]+(\s+\d+\s+[a-z]+)*\s*$/i.test(value)
+  return !Number.isNaN(Date.parse(value))
+}
+
+export interface BoundsCompileResult {
+  check?: string
+  validation?: FieldValidation
+}
+
+function refuse(field: string, modifier: string, kind: FieldKind, hint: string | undefined): never {
+  const tail = hint ? ` ${hint}.` : ""
+  throw new Error(
+    `Field "${field}": ${modifier} is not supported on a ${kind} field.${tail}`,
+  )
+}
+
+/**
+ * Compile declared bounds against the kind they landed on.
+ *
+ * Throws rather than dropping. A bound that cannot be honoured is a mistake in the schema, and the
+ * failure it used to produce, silence, is the one failure this must not have.
+ */
+export function compileBounds(
+  field: string,
+  kind: FieldKind,
+  bounds: DeclaredBounds,
+  options: { jsonIsArray?: boolean } = {},
+): BoundsCompileResult {
+  const entry = boundsForKind(kind, options.jsonIsArray === true)
+  const clauses: string[] = []
+  const validation: FieldValidation = {}
+
+  const { maxLength, minLength } = bounds
+  if (maxLength !== undefined || minLength !== undefined) {
+    const resolved = measureFormFor(kind, "length", options)
+    if (resolved.form === undefined) {
+      refuse(field, maxLength !== undefined ? "MaxLength" : "MinLength", kind, resolved.instead)
+    }
+    const expr = lengthExpr(resolved.form as LengthForm)
+    if (maxLength !== undefined) {
+      clauses.push(`${expr} <= ${maxLength}`)
+      validation.maxLength = maxLength
+    }
+    if (minLength !== undefined) {
+      clauses.push(`${expr} >= ${minLength}`)
+      validation.minLength = minLength
+    }
+  }
+
+  const { maxItems, minItems } = bounds
+  const itemsResolved = measureFormFor(kind, "items", options)
+  if (maxItems !== undefined || minItems !== undefined) {
+    if (itemsResolved.form === undefined) {
+      refuse(field, maxItems !== undefined ? "MaxItems" : "MinItems", kind, itemsResolved.instead)
+    }
+    const comparisons: string[] = []
+    if (maxItems !== undefined) {
+      comparisons.push(`<= ${maxItems}`)
+      validation.maxItems = maxItems
+    }
+    if (minItems !== undefined) {
+      comparisons.push(`>= ${minItems}`)
+      validation.minItems = minItems
+    }
+    clauses.push(itemsClause(itemsResolved.form as ItemsForm, comparisons))
+  }
+
+  const { min, max } = bounds
+  if (min !== undefined || max !== undefined) {
+    if (!entry.range) refuse(field, "Between", kind, entry.instead?.range)
+    for (const [bound, comparison] of [[min, ">="], [max, "<="]] as const) {
+      if (bound === undefined) continue
+      assertRangeShape(field, kind, entry.range, bound)
+      clauses.push(`${COLUMN} ${comparison} ${rangeLiteral(entry.range, bound)}`)
+    }
+    if (min !== undefined) validation.min = min
+    if (max !== undefined) validation.max = max
+  }
+
+  // Parenthesised only when there is something to bind, matching `mergeCheckConstraint`. Gratuitous
+  // parentheses are not cosmetic here: the differ compares this text against what Postgres hands
+  // back from `pg_get_constraintdef`, so every avoidable difference is a false "changed" on push.
+  return {
+    ...(clauses.length > 0 && { check: joinClauses(clauses) }),
+    ...(Object.keys(validation).length > 0 && { validation }),
+  }
+}
+
+function joinClauses(clauses: string[]): string {
+  const [only] = clauses
+  if (clauses.length === 1 && only !== undefined) return only
+  return clauses.map((c) => `(${c})`).join(" AND ")
+}
+
+/** A number bounds a number and a string bounds a date. Crossing them is a mistake, not a cast. */
+function assertRangeShape(field: string, kind: FieldKind, form: RangeForm, bound: number | string): void {
+  const isNumeric = form === "numeric"
+  if (isNumeric && typeof bound !== "number") {
+    throw new Error(
+      `Field "${field}": Between on a ${kind} field takes numbers, but "${bound}" is a string.`,
+    )
+  }
+  if (!isNumeric && typeof bound !== "string") {
+    throw new Error(
+      `Field "${field}": Between on a ${kind} field takes ISO-8601 string bounds, but ${bound} is a number.`,
+    )
+  }
+  if (!isNumeric && !isTemporalLiteral(form, bound as string)) {
+    throw new Error(
+      `Field "${field}": Between bound "${bound}" is not a valid ${form === "interval" ? "interval" : "ISO-8601 date"}.`,
+    )
+  }
+}

package/src/hooks-generator.ts

@@ -28,16 +28,21 @@ function hookedModels(ast: unknown): HookedModel[] {
 
   return models
     .filter((model) => {
-      const hooks = (model as { annotations?: { platform?: { hooks?: unknown } } }).annotations
-        ?.platform?.hooks
-      return typeof hooks === "object" && hooks !== null && Object.keys(hooks).length > 0
+      const platform = (
+        model as { annotations?: { platform?: { hooks?: unknown; validate?: unknown } } }
+      ).annotations?.platform
+      const declares = (value: unknown): boolean =>
+        typeof value === "object" && value !== null && Object.keys(value).length > 0
+      // Validators need the same row types hooks do, so a model declaring only validators must
+      // still appear here or `FieldValidator<"products", ...>` would not compile.
+      return declares(platform?.hooks) || declares(platform?.validate)
     })
     .map((model) => ({ table: resolveTableName(model), fields: model.fields }))
     .sort((a, b) => a.table.localeCompare(b.table))
 }
 
 /**
- * The module source, or `null` when no model declares a hook.
+ * The module source, or `null` when no model declares a hook or a field validator.
  *
  * Returning null rather than an empty module keeps a `_supatype/hooks.ts` from appearing in projects
  * that have no hooks, a generated file nobody imports is a file somebody eventually edits.
@@ -169,6 +174,78 @@ export type AfterDelete<T extends HookedTable> = (
   ctx: AfterDeleteContext<T>,
 ) => void | Promise<void>
 
+
+/**
+ * A per-field validator: one field's value, and a verdict about it.
+ *
+ * \`FieldValidator<"products", "setup_items">\` types \`value\` as that column's real type, so a
+ * validator cannot quietly be written against the wrong shape.
+ *
+ * Return \`true\` to accept, or a message to refuse. The message reaches the caller attached to the
+ * field name, which is what lets a form put it on the input rather than in a banner: the whole
+ * reason for declaring this instead of putting the same logic in a \`beforeChange\` hook.
+ */
+export type FieldValidatorContext<T extends HookedTable, F extends keyof HookTables[T]["Row"]> =
+  HookBase & {
+    readonly operation: "insert" | "update"
+    readonly field: F
+    readonly value: HookTables[T]["Row"][F]
+  }
+
+export type FieldVerdict = true | string
+
+export type FieldValidator<T extends HookedTable, F extends keyof HookTables[T]["Row"]> = (
+  ctx: FieldValidatorContext<T, F>,
+) => FieldVerdict | Promise<FieldVerdict>
+
+interface WireValidatorContext {
+  table?: string
+  operation?: string
+  field?: string
+  value?: unknown
+  user?: unknown
+  requestId?: string
+}
+
+/**
+ * Wrap a typed validator as the request handler the worker expects.
+ *
+ * A refusal is **422 with the field named**, not a bare 400: the request was understood and one
+ * value was rejected. A thrown error is deliberately *not* turned into a refusal, because a broken
+ * validator has not decided anything: it becomes a 500, which the server reads as unavailable and
+ * refuses the write on, rather than as the validator saying no.
+ */
+export function fieldValidator(
+  handler: (ctx: never) => FieldVerdict | Promise<FieldVerdict>,
+): (req: Request) => Promise<Response> {
+  return async (req: Request): Promise<Response> => {
+    if (req.method !== "POST") {
+      return json({ message: "A validator is invoked with POST" }, 405)
+    }
+
+    let wire: WireValidatorContext
+    try {
+      wire = (await req.json()) as WireValidatorContext
+    } catch {
+      return json({ message: "Validator payload was not JSON" }, 400)
+    }
+
+    const field = wire.field ?? ""
+    const ctx = {
+      table: wire.table ?? "",
+      operation: wire.operation === "update" ? "update" : "insert",
+      field,
+      value: wire.value,
+      user: (wire.user ?? null) as never,
+      requestId: wire.requestId ?? "",
+    }
+
+    const verdict = await handler(ctx as never)
+    if (verdict === true) return json({}, 200)
+    return json({ field, message: String(verdict), error: String(verdict) }, 422)
+  }
+}
+
 /** Every handler a single function may serve, when one function covers a model's whole lifecycle. */
 export interface HookHandlers<T extends HookedTable> {
   readonly beforeChange?: BeforeChange<T>