@supatype/cli 0.1.12 → 0.2.0

package/tests/compose-services.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest"
+import { logsArgs } from "../src/commands/logs.js"
+import { composeArgs, parseComposePs } from "../src/compose-services.js"
+
+/**
+ * `supatype status` and `supatype logs` each carried a hardcoded list of container
+ * names. Both lists were wrong: they named `supatype-postgres` and `supatype-kong`,
+ * which the generated compose file does not create, and omitted `server`, `storage`,
+ * `functions-worker`, `schema-engine` and `valkey`, which it does. The file sets no
+ * `container_name`, so Docker names containers `<project>-<service>-<n>` and no
+ * guessed name could ever have matched.
+ *
+ * The fix is to ask Compose. These tests cover the parsing and argument seams, which
+ * are the parts that can be wrong without Docker present.
+ */
+
+const ctx = {
+  composePath: "/proj/.supatype/self-host/docker-compose.yml",
+  projectRoot: "/proj",
+  projectName: "supatype-demo",
+}
+
+describe("parseComposePs", () => {
+  // Compose v2 emits newline-delimited objects.
+  it("reads the NDJSON form", () => {
+    const stdout = [
+      JSON.stringify({ Service: "server", Name: "supatype-demo-server-1", State: "running", Status: "Up 2 minutes" }),
+      JSON.stringify({ Service: "db", Name: "supatype-demo-db-1", State: "exited", Status: "Exited (1)" }),
+    ].join("\n")
+
+    expect(parseComposePs(stdout)).toEqual([
+      { service: "db", container: "supatype-demo-db-1", state: "exited", ports: "", status: "Exited (1)" },
+      { service: "server", container: "supatype-demo-server-1", state: "running", ports: "", status: "Up 2 minutes" },
+    ])
+  })
+
+  // Other versions emit one array. Which you get depends on the Docker installed.
+  it("reads the array form", () => {
+    const stdout = JSON.stringify([{ Service: "studio", Name: "supatype-demo-studio-1", State: "running" }])
+    expect(parseComposePs(stdout).map((s) => s.service)).toEqual(["studio"])
+  })
+
+  it("sorts by service so the report is stable between runs", () => {
+    const stdout = ["valkey", "db", "server"].map((s) => JSON.stringify({ Service: s, State: "running" })).join("\n")
+    expect(parseComposePs(stdout).map((s) => s.service)).toEqual(["db", "server", "valkey"])
+  })
+
+  // Compose prefixes its own progress lines on some versions, and prints nothing
+  // at all when the project has never been started.
+  it("survives noise and emptiness", () => {
+    expect(parseComposePs("")).toEqual([])
+    expect(parseComposePs("   \n")).toEqual([])
+    expect(parseComposePs("[not json")).toEqual([])
+    expect(parseComposePs('pulling...\n{"Service":"db","State":"running"}')).toHaveLength(1)
+  })
+
+  // A row without a service name cannot be reported against, and a missing state
+  // must not read as running.
+  it("drops rows with no service and does not invent a state", () => {
+    const stdout = [
+      JSON.stringify({ Name: "orphan", State: "running" }),
+      JSON.stringify({ Service: "db" }),
+      "null",
+    ].join("\n")
+    const got = parseComposePs(stdout)
+    expect(got).toHaveLength(1)
+    expect(got[0]).toMatchObject({ service: "db", state: "unknown", container: "", ports: "" })
+  })
+
+  describe("ports", () => {
+    it("takes the string form as given", () => {
+      const stdout = JSON.stringify({ Service: "db", State: "running", Publishers: "0.0.0.0:5432->5432/tcp" })
+      expect(parseComposePs(stdout)[0]?.ports).toBe("0.0.0.0:5432->5432/tcp")
+    })
+
+    // Compose lists an entry per protocol and per host interface, so the same
+    // mapping arrives several times over.
+    it("renders the structured form, de-duplicated", () => {
+      const stdout = JSON.stringify({
+        Service: "db",
+        State: "running",
+        Publishers: [
+          { URL: "0.0.0.0", TargetPort: 5432, PublishedPort: 5432, Protocol: "tcp" },
+          { URL: "::", TargetPort: 5432, PublishedPort: 5432, Protocol: "tcp" },
+          { URL: "0.0.0.0", TargetPort: 9000, PublishedPort: 19000, Protocol: "tcp" },
+        ],
+      })
+      expect(parseComposePs(stdout)[0]?.ports).toBe("5432->5432, 19000->9000")
+    })
+
+    // An unpublished port is reachable only from inside the network, so reporting
+    // it would tell the developer to try an address that will refuse.
+    it("omits ports that are not published to the host", () => {
+      const stdout = JSON.stringify({
+        Service: "valkey",
+        State: "running",
+        Publishers: [{ URL: "", TargetPort: 6379, PublishedPort: 0, Protocol: "tcp" }, null, "nonsense"],
+      })
+      expect(parseComposePs(stdout)[0]?.ports).toBe("")
+    })
+  })
+})
+
+describe("composeArgs", () => {
+  // Without --project-directory, Compose resolves relative build contexts and
+  // env_file paths against .supatype/self-host/ rather than the project root.
+  it("names the project, the project directory and the file", () => {
+    expect(composeArgs(ctx)).toEqual([
+      "compose",
+      "-p",
+      "supatype-demo",
+      "--project-directory",
+      "/proj",
+      "-f",
+      "/proj/.supatype/self-host/docker-compose.yml",
+    ])
+  })
+})
+
+describe("logsArgs", () => {
+  it("tails the whole stack by default", () => {
+    expect(logsArgs(["compose"], { since: "5m", follow: true })).toEqual([
+      "compose",
+      "logs",
+      "--tail",
+      "100",
+      "--follow",
+      "--since",
+      "5m",
+    ])
+  })
+
+  // The service name is the Compose service, and it has to come last: Compose
+  // reads trailing arguments as the services to tail.
+  it("puts the service last", () => {
+    const args = logsArgs(["compose"], { service: "server", follow: false })
+    expect(args.at(-1)).toBe("server")
+    expect(args).not.toContain("--follow")
+  })
+
+  it("omits --since when there is none", () => {
+    expect(logsArgs(["compose"], {})).not.toContain("--since")
+  })
+})

package/tests/dev-ports-owner.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest"
+import { composeProjectOwnsPort } from "../src/dev-ports.js"
+
+/**
+ * The decision behind the port guard, without Docker.
+ *
+ * `supatype self-host compose up -d` followed by `supatype push` was impossible: the second
+ * command saw its own gateway on the port and refused. The fix has to accept our own stack while
+ * still refusing a stranger's, because proceeding against another project's gateway would push a
+ * schema into the wrong database.
+ */
+describe("composeProjectOwnsPort", () => {
+  it("accepts a port published by this project", () => {
+    expect(composeProjectOwnsPort("supatype-validation\n", "supatype-validation")).toBe(true)
+  })
+
+  it("refuses a port published by a different project", () => {
+    expect(composeProjectOwnsPort("someone-elses-stack\n", "supatype-validation")).toBe(false)
+  })
+
+  it("refuses when any publisher is a different project", () => {
+    const output = "supatype-validation\nsomeone-elses-stack\n"
+    expect(composeProjectOwnsPort(output, "supatype-validation")).toBe(false)
+  })
+
+  it("refuses when nothing reports a compose project", () => {
+    // A container with no compose label: something is on the port, and it is not ours.
+    expect(composeProjectOwnsPort("\n\n", "supatype-validation")).toBe(false)
+    expect(composeProjectOwnsPort("", "supatype-validation")).toBe(false)
+  })
+
+  it("tolerates the whitespace docker pads its columns with", () => {
+    expect(composeProjectOwnsPort("  supatype-validation  \n", "supatype-validation")).toBe(true)
+  })
+
+  it("does not match on a prefix", () => {
+    // `supatype-validation-2` is a different project, and a substring check would accept it.
+    expect(composeProjectOwnsPort("supatype-validation-2\n", "supatype-validation")).toBe(false)
+  })
+})

package/tests/engine-floor.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest"
+import {
+  assertEngineSupportsSchema,
+  boundsRequiringHelpers,
+  compareVersions,
+  ENGINE_MIN_FOR_BOUNDS,
+} from "../src/engine-floor.js"
+import type { ExtractedSchemaAstV2, FieldAstV2, ModelAstV2 } from "../src/schema-ast-v2.js"
+
+function field(overrides: Partial<FieldAstV2> = {}): FieldAstV2 {
+  return {
+    kind: "text",
+    annotations: { db: { pgType: "TEXT" }, platform: {} },
+    ...overrides,
+  } as FieldAstV2
+}
+
+function model(name: string, fields: Record<string, FieldAstV2>, constraints?: unknown[]): ModelAstV2 {
+  return {
+    name,
+    fields,
+    options: {},
+    annotations: {
+      db: { tableName: name.toLowerCase(), indexes: [], ...(constraints && { constraints }) },
+      platform: { access: {} },
+    },
+  }
+}
+
+function schema(models: ModelAstV2[]): ExtractedSchemaAstV2 {
+  return { astVersion: 2, models } as ExtractedSchemaAstV2
+}
+
+const WITH_BOUND = schema([model("Post", { title: field({ validation: { maxLength: 80 } }) })])
+const WITHOUT_BOUND = schema([model("Post", { title: field() })])
+
+describe("compareVersions", () => {
+  it("orders by each numeric part, not lexically", () => {
+    expect(compareVersions("0.10.0", "0.9.0")).toBeGreaterThan(0)
+    expect(compareVersions("0.2.0", "0.2.0")).toBe(0)
+    expect(compareVersions("0.1.9", "0.2.0")).toBeLessThan(0)
+  })
+
+  it("ignores a leading v and a pre-release suffix", () => {
+    // A release candidate of the engine that creates the helpers does create them.
+    expect(compareVersions("v0.2.0", "0.2.0")).toBe(0)
+    expect(compareVersions("0.2.0-rc.1", "0.2.0")).toBe(0)
+  })
+})
+
+describe("boundsRequiringHelpers", () => {
+  it("names the fields that declare a bound", () => {
+    expect(boundsRequiringHelpers(WITH_BOUND)).toEqual(["Post.title"])
+  })
+
+  it("names models carrying a constraint", () => {
+    const ast = schema([model("Event", { start: field() }, [{ expr: "start < finish" }])])
+    expect(boundsRequiringHelpers(ast)).toEqual(["Event"])
+  })
+
+  it("is empty for a schema that declares neither", () => {
+    expect(boundsRequiringHelpers(WITHOUT_BOUND)).toEqual([])
+  })
+})
+
+describe("assertEngineSupportsSchema", () => {
+  it("refuses a bound schema on an engine below the floor", () => {
+    expect(() => assertEngineSupportsSchema(WITH_BOUND, "0.1.9")).toThrow(/schema-engine 0\.2\.0 or newer/)
+  })
+
+  it("names the pin and the field, so the message is actionable", () => {
+    try {
+      assertEngineSupportsSchema(WITH_BOUND, "0.1.9")
+      expect.unreachable("should have refused")
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      expect(message).toContain("pins 0.1.9")
+      expect(message).toContain("Post.title")
+      expect(message).toContain("versions: { engine:")
+    }
+  })
+
+  // The three cases where refusing would be worse than the failure it prevents: an old pin is
+  // fine without bounds, an unpinned project resolves to latest, and `local` cannot be compared.
+  it("allows an old pin when the schema declares no bounds", () => {
+    expect(() => assertEngineSupportsSchema(WITHOUT_BOUND, "0.1.9")).not.toThrow()
+  })
+
+  it("allows an unpinned project", () => {
+    expect(() => assertEngineSupportsSchema(WITH_BOUND, undefined)).not.toThrow()
+  })
+
+  it("allows a local override, whose version the config does not know", () => {
+    expect(() => assertEngineSupportsSchema(WITH_BOUND, "local")).not.toThrow()
+  })
+
+  it("allows the floor itself and anything above it", () => {
+    expect(() => assertEngineSupportsSchema(WITH_BOUND, ENGINE_MIN_FOR_BOUNDS)).not.toThrow()
+    expect(() => assertEngineSupportsSchema(WITH_BOUND, "0.3.1")).not.toThrow()
+    expect(() => assertEngineSupportsSchema(WITH_BOUND, "1.0.0")).not.toThrow()
+  })
+})

package/tests/external-database-compose.test.ts

@@ -53,7 +53,7 @@ describe("external database: compose", () => {
 
   it("points every database consumer at the one URL", () => {
     const compose = renderSelfHostCompose(external())
-    // storage, realtime, control-plane, server (SUPATYPE_SQL_DATABASE_URL), and GoTrue.
+    // storage, realtime, control-plane, server (SUPATYPE_SQL_DATABASE_URL), and auth.
     const references = compose.match(/\$\{DATABASE_URL:\?/g) ?? []
     expect(references.length).toBe(5)
   })
@@ -85,9 +85,9 @@ describe("external database: compose", () => {
     expect(compose).toContain("@db.example.com:5432/app?sslmode=require")
   })
 
-  it("appends GoTrue's search_path with the right separator", () => {
+  it("appends the auth search_path with the right separator", () => {
     // A URL that already has a query string needs `&`; a second `?` produces a DSN that fails to
-    // parse, and GoTrue would exit rather than run its auth migrations.
+    // parse, and the service would exit rather than run its auth migrations.
     expect(renderSelfHostCompose(external())).toContain('${DATABASE_URL:?DATABASE_URL is missing from .env, required by database.external}?search_path=auth"')
     expect(
       renderSelfHostCompose(

package/tests/field-bounds-matrix.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it } from "vitest"
+import { compileBounds } from "../src/field-bounds.js"
+import type { FieldKind } from "../src/schema-ast-v2.js"
+
+/**
+ * Every field kind, against every bound family, asserted to do exactly one of two things.
+ *
+ * This is the test whose absence caused the whole defect. Nine of twelve field kinds accepted a
+ * declared bound and enforced nothing, and no test noticed, because no test enumerated the kinds:
+ * each was handled wherever someone happened to look.
+ *
+ * `MATRIX` is typed `Record<FieldKind, KindRow>`, so **completeness is the compiler's job**: adding
+ * a kind to `FIELD_KINDS` fails the build in three places at once, here, in `BOUNDS_BY_KIND`, and
+ * at any `scalar()` call using a name the registry does not know. No assertion can rot into
+ * vacuous, because there is nothing to keep in sync by hand.
+ *
+ * Every cell is either an expression or a refusal. **A cell that is silently empty is the bug**, so
+ * there is no way to express one.
+ */
+
+type Cell = { sql: string } | { refused: RegExp }
+
+interface KindRow {
+  /** `MaxLength<T, 5>` */
+  length: Cell
+  /** `MaxItems<T, 5>` */
+  items: Cell
+  /** `Between<T, ...>`, using whichever bound shape the kind accepts. */
+  range: Cell
+  /** The literal to bound with, when the kind takes a string rather than a number. */
+  rangeBound?: string
+}
+
+const COL = '"{name}"'
+const refusedAs = (alternative: string): Cell => ({ refused: new RegExp(alternative) })
+
+const textual = (): KindRow => ({
+  length: { sql: `char_length(${COL}) <= 5` },
+  items: refusedAs("MaxItems is not supported"),
+  range: refusedAs("Between is not supported"),
+})
+
+const numeric = (): KindRow => ({
+  length: refusedAs("MaxLength is not supported"),
+  items: refusedAs("MaxItems is not supported"),
+  range: { sql: `${COL} <= 5` },
+})
+
+// An interval is bounded by a duration, not by a date. The matrix keeps them distinct because the
+// extractor validates the literal shape per cast and would otherwise reject one of them at push time.
+const temporal = (cast: string, bound = "2026-12-31"): KindRow => ({
+  length: refusedAs("MaxLength is not supported"),
+  items: refusedAs("MaxItems is not supported"),
+  range: { sql: `${COL} <= '${bound}'::${cast}` },
+  rangeBound: bound,
+})
+
+const unbounded = (why: string): KindRow => ({
+  length: refusedAs(why),
+  items: refusedAs(why),
+  range: refusedAs(why),
+})
+
+const collection = (measure: string): KindRow => ({
+  length: refusedAs("MaxItems"),
+  items: { sql: measure },
+  range: refusedAs("Between is not supported"),
+})
+
+const MATRIX: Record<FieldKind, KindRow> = {
+  text: textual(),
+  email: textual(),
+  url: textual(),
+  slug: textual(),
+  color: textual(),
+  xml: textual(),
+  ip: textual(),
+  cidr: textual(),
+  macaddr: textual(),
+  tsQuery: textual(),
+  tsVector: textual(),
+
+  richText: {
+    length: { sql: `char_length(_supatype.richtext_text(${COL})) <= 5` },
+    items: refusedAs("MaxItems is not supported"),
+    range: refusedAs("Between is not supported"),
+  },
+  bytes: {
+    length: { sql: `octet_length(${COL}) <= 5` },
+    items: refusedAs("MaxItems is not supported"),
+    range: refusedAs("Between is not supported"),
+  },
+
+  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", "30 days"),
+
+  array: collection(`cardinality(${COL}) <= 5`),
+  blocks: collection(`jsonb_typeof(${COL}) = 'array' AND jsonb_array_length(${COL}) <= 5`),
+  json: unbounded("JSON object has no single measure"),
+  button: unbounded("composite value"),
+
+  enum: unbounded("union already constrains"),
+  boolean: unbounded("boolean has two values"),
+  uuid: unbounded("fixed width"),
+  image: unbounded("fileSizeLimit"),
+  file: unbounded("fileSizeLimit"),
+  geo: unbounded("not measured this way"),
+  vector: unbounded("dimension is already fixed"),
+  relation: unbounded("bound the column on the model"),
+  custom: unbounded("plugin field declares its own storage"),
+  timestamps: unbounded("composite expands into columns"),
+  publishable: unbounded("composite expands into columns"),
+  softDelete: unbounded("composite expands into columns"),
+}
+
+function assertCell(kind: FieldKind, family: string, cell: Cell, run: () => { check?: string }): void {
+  if ("refused" in cell) {
+    expect(
+      run,
+      `${kind}.${family} must refuse rather than silently accept a bound it cannot honour`,
+    ).toThrow(cell.refused)
+    return
+  }
+  const { check } = run()
+  expect(check, `${kind}.${family} must compile to its own expression`).toBe(cell.sql)
+}
+
+describe("bounds matrix", () => {
+  for (const [kind, row] of Object.entries(MATRIX) as Array<[FieldKind, KindRow]>) {
+    describe(kind, () => {
+      it("length", () => {
+        assertCell(kind, "length", row.length, () => compileBounds("f", kind, { maxLength: 5 }))
+      })
+
+      it("items", () => {
+        assertCell(kind, "items", row.items, () => compileBounds("f", kind, { maxItems: 5 }))
+      })
+
+      it("range", () => {
+        const max = row.rangeBound ?? 5
+        assertCell(kind, "range", row.range, () => compileBounds("f", kind, { max }))
+      })
+    })
+  }
+
+  it("treats JSON as a collection only when its type argument is an array", () => {
+    // The one cell the kind alone cannot decide: the CLI reads it from the declared type.
+    expect(compileBounds("f", "json", { maxItems: 5 }, { jsonIsArray: true }).check).toBe(
+      `jsonb_typeof(${COL}) = 'array' AND jsonb_array_length(${COL}) <= 5`,
+    )
+  })
+})

package/tests/field-bounds.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from "vitest"
+import { compileBounds } from "../src/field-bounds.js"
+import type { FieldKind } from "../src/schema-ast-v2.js"
+
+// The bug this module exists to prevent: a declared bound that reaches neither Postgres nor Studio
+// and raises nothing. Every assertion here is therefore either "this exact SQL" or "this throws".
+// A kind that silently returns no check is the failure mode, so there is no test that permits one.
+
+describe("compileBounds: length", () => {
+  it("counts characters for text-like kinds", () => {
+    expect(compileBounds("title", "text", { maxLength: 120 })).toEqual({
+      check: 'char_length("{name}") <= 120',
+      validation: { maxLength: 120 },
+    })
+    expect(compileBounds("email", "email", { minLength: 5 }).check).toBe(
+      'char_length("{name}") >= 5',
+    )
+  })
+
+  it("counts octets for a binary column, not characters", () => {
+    expect(compileBounds("blob", "bytes", { maxLength: 1024 }).check).toBe(
+      'octet_length("{name}") <= 1024',
+    )
+  })
+
+  it("counts plain-text characters for rich text, through the managed helper", () => {
+    expect(compileBounds("body", "richText", { maxLength: 320 }).check).toBe(
+      'char_length(_supatype.richtext_text("{name}")) <= 320',
+    )
+  })
+
+  it("merges both ends into one constraint", () => {
+    expect(compileBounds("body", "text", { maxLength: 4000, minLength: 20 })).toEqual({
+      check: '(char_length("{name}") <= 4000) AND (char_length("{name}") >= 20)',
+      validation: { maxLength: 4000, minLength: 20 },
+    })
+  })
+})
+
+describe("compileBounds: items", () => {
+  it("uses cardinality for a real array, never char_length", () => {
+    // char_length(text[]) does not exist: the old generator's output failed CREATE TABLE.
+    expect(compileBounds("tags", "array", { maxItems: 10 }).check).toBe(
+      'cardinality("{name}") <= 10',
+    )
+  })
+
+  it("guards jsonb_array_length with a type check", () => {
+    // Unguarded, an object value raises "cannot get array length of a non-array" at insert.
+    expect(compileBounds("sections", "blocks", { minItems: 1 }).check).toBe(
+      'jsonb_typeof("{name}") = \'array\' AND jsonb_array_length("{name}") >= 1',
+    )
+  })
+
+  it("accepts item bounds on JSON only when the declared type argument is an array", () => {
+    expect(compileBounds("items", "json", { minItems: 1 }, { jsonIsArray: true }).check).toBe(
+      'jsonb_typeof("{name}") = \'array\' AND jsonb_array_length("{name}") >= 1',
+    )
+    expect(() => compileBounds("meta", "json", { minItems: 1 })).toThrow(
+      /MinItems is not supported on a json field.*JSON<T\[\]>/s,
+    )
+  })
+})
+
+describe("compileBounds: range", () => {
+  it("compares a numeric column directly, with no cast", () => {
+    expect(compileBounds("score", "integer", { min: 1, max: 5 })).toEqual({
+      check: '("{name}" >= 1) AND ("{name}" <= 5)',
+      validation: { min: 1, max: 5 },
+    })
+  })
+
+  it("money and decimal are NUMERIC columns, so they need no cast either", () => {
+    expect(compileBounds("price", "money", { min: 0 }).check).toBe('"{name}" >= 0')
+    expect(compileBounds("rate", "decimal", { max: 100 }).check).toBe('"{name}" <= 100')
+  })
+
+  it("casts a temporal bound to the column's own type", () => {
+    expect(compileBounds("startsAt", "datetime", { min: "2026-01-01T00:00:00Z" }).check).toBe(
+      `"{name}" >= '2026-01-01T00:00:00Z'::timestamptz`,
+    )
+    expect(compileBounds("day", "date", { max: "2026-12-31" }).check).toBe(
+      `"{name}" <= '2026-12-31'::date`,
+    )
+    expect(compileBounds("window", "interval", { max: "30 days" }).check).toBe(
+      `"{name}" <= '30 days'::interval`,
+    )
+  })
+
+  it("refuses a string bound on a number and a number bound on a date", () => {
+    expect(() => compileBounds("score", "integer", { min: "1" })).toThrow(
+      /takes numbers, but "1" is a string/,
+    )
+    expect(() => compileBounds("day", "date", { min: 20260101 })).toThrow(
+      /takes ISO-8601 string bounds, but 20260101 is a number/,
+    )
+  })
+
+  it("refuses a temporal bound that is not a date, before it reaches a migration", () => {
+    expect(() => compileBounds("day", "date", { max: "next tuesday" })).toThrow(
+      /is not a valid ISO-8601 date/,
+    )
+  })
+})
+
+describe("compileBounds: refusals name the alternative", () => {
+  const cases: Array<[string, FieldKind, Parameters<typeof compileBounds>[2], RegExp]> = [
+    ["tags", "array", { maxLength: 10 }, /MaxLength is not supported on a array field.*MaxItems/s],
+    ["body", "richText", { maxItems: 3 }, /MaxItems is not supported on a richText field/],
+    ["score", "integer", { maxLength: 3 }, /MaxLength is not supported on a integer field/],
+    ["title", "text", { min: 1 }, /Between is not supported on a text field/],
+    ["status", "enum", { maxLength: 5 }, /union already constrains the permitted values/],
+    ["cover", "image", { maxLength: 5 }, /fileSizeLimit and allowedMimeTypes/],
+    ["embedding", "vector", { max: 1 }, /dimension is already fixed by the type/],
+    ["author", "relation", { maxLength: 5 }, /bound the column on the model this relation points at/],
+    ["flag", "boolean", { min: 0 }, /a boolean has two values/],
+  ]
+
+  for (const [field, kind, bounds, expected] of cases) {
+    it(`${kind} refuses and says where to go instead`, () => {
+      expect(() => compileBounds(field, kind, bounds)).toThrow(expected)
+    })
+  }
+
+  it("names the field, so the error is actionable in a large schema", () => {
+    expect(() => compileBounds("setupItems", "json", { maxLength: 3 })).toThrow(/Field "setupItems"/)
+  })
+})
+
+describe("compileBounds: coverage is enforced, not assumed", () => {
+  // Completeness moved from a runtime throw to the type system: `BOUNDS_BY_KIND` is
+  // `Record<FieldKind, ...>` and `scalar()` takes a `FieldKind`, so an unclassified kind cannot be
+  // written down, let alone reach here. Asserting the old throw would mean calling `compileBounds`
+  // with a kind that no longer typechecks, which is the point.
+
+  it("returns nothing when nothing was declared", () => {
+    expect(compileBounds("x", "text", {})).toEqual({})
+  })
+})