@supatype/cli 0.1.11 → 0.1.13

package/src/db-preflight.ts

@@ -113,6 +113,16 @@ async function probeLogicalDecoding(q: QueryFn): Promise<CheckResult> {
 
 const REQUIRED_ROLES = ["anon", "authenticated", "service_role", "authenticator"] as const
 
+/** The three roles PostgREST switches to per request. `authenticator` only connects and switches. */
+const API_ROLES = ["anon", "authenticated", "service_role"] as const
+
+/** One row per API role that exists, for the schema named in the query. */
+export interface AuthSchemaUsageRow {
+  rolname: string | null
+  has_usage: boolean | null
+  owner: string
+}
+
 /**
  * Stands in for the `authenticator` password when the operator has not supplied one.
  *
@@ -309,7 +319,7 @@ export async function runPreflight(
         WHERE g.rolname = 'authenticator'`,
     )
     const held = new Set(memberships.map((m) => m.rolname))
-    const needed = ["anon", "authenticated", "service_role"].filter((r) => !held.has(r))
+    const needed = API_ROLES.filter((r) => !held.has(r))
     results.push({
       id: "authenticator-memberships",
       title: "authenticator can reach the three API roles",
@@ -322,6 +332,19 @@ export async function runPreflight(
     })
   }
 
+  // USAGE on the auth schema, asked by OID so a role that does not exist cannot raise
+  // `role "x" does not exist` the way the name-taking overload would.
+  const authUsage = await q<AuthSchemaUsageRow>(
+    `SELECT r.rolname,
+            has_schema_privilege(r.oid, n.oid, 'USAGE') AS has_usage,
+            pg_get_userbyid(n.nspowner) AS owner
+       FROM pg_namespace n
+       LEFT JOIN pg_roles r ON r.rolname = ANY($1)
+      WHERE n.nspname = 'auth'`,
+    [API_ROLES as unknown as string[]],
+  )
+  results.push(authSchemaUsageCheck(authUsage, privs))
+
   // ── Extensions ─────────────────────────────────────────────────────────────
   const installed = new Set(
     (await q<{ extname: string }>("SELECT extname FROM pg_extension")).map((r) => r.extname),
@@ -456,6 +479,71 @@ export async function runPreflight(
   return { results, worst: worstOf(results) }
 }
 
+/**
+ * Can the API roles reach the auth helpers when a query calls them?
+ *
+ * Postgres evaluates a policy's `USING` clause with the table owner's privileges, so row-level
+ * security works without this grant and looks like proof the schema is fine. Field masking does
+ * not: `supatype_mask` rewrites a masked column into `CASE WHEN can_read_t__c(t) …` in the target
+ * list, which runs as the caller and reaches `auth.role()` directly. Studio's per-record
+ * `can_<op>_<table>` calls have the same shape.
+ *
+ * `supatype/postgres` grants this at initdb, so a missing grant means a database Supatype did not
+ * bootstrap. Kept a `degrade` rather than a `fail`: two named features stop working and the rest
+ * of the stack is unaffected.
+ */
+export function authSchemaUsageCheck(
+  rows: AuthSchemaUsageRow[],
+  privs: { current_user: string; is_super: boolean },
+): CheckResult {
+  const base = { id: "auth-schema-usage", title: "USAGE on schema auth (API roles)" }
+
+  // No auth schema yet: the first push creates it and grants on it, so there is nothing to fix.
+  if (rows.length === 0) {
+    return {
+      ...base,
+      severity: "pass",
+      detail: "schema auth does not exist yet; the first push creates it and grants usage",
+    }
+  }
+
+  const owner = rows[0]!.owner
+  const present = rows.filter((r) => r.rolname !== null)
+
+  // The roles check above owns this finding; repeating it here as a privilege problem would send
+  // the operator after the wrong fix.
+  if (present.length === 0) {
+    return { ...base, severity: "pass", detail: "no API roles exist on this server yet" }
+  }
+
+  const lacking = present.filter((r) => !r.has_usage).map((r) => r.rolname!)
+  if (lacking.length === 0) {
+    return {
+      ...base,
+      severity: "pass",
+      detail: `granted to ${present.map((r) => r.rolname).join(", ")} (schema owned by "${owner}")`,
+    }
+  }
+
+  // A grant from a role that owns neither the schema nor the server is discarded with a WARNING
+  // rather than an error, so `--fix` would report "Applied" having changed nothing. That is the
+  // same fault as a privilege generated and never applied, so hand it to the operator instead.
+  const canGrant = owner === privs.current_user || privs.is_super
+
+  return {
+    ...base,
+    severity: "degrade",
+    detail: `not granted to ${lacking.join(", ")} (schema owned by "${owner}")`,
+    impact:
+      "Field-level access is unavailable: a push declaring `access.fields` refuses rather than " +
+      "applying, and a masked column read by one of these roles fails with 42501 instead of " +
+      "masking. Studio's per-record permission checks fail the same way. Row-level security is " +
+      "unaffected, because Postgres evaluates policies with the table owner's privileges.",
+    remedy: `GRANT USAGE ON SCHEMA auth TO ${lacking.map(ident).join(", ")};`,
+    ...(!canGrant && { remedyNeedsOperator: true }),
+  }
+}
+
 function extensionCheck(
   name: string,
   installed: Set<string>,

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"}.`,
+    )
+  }
+}