@supatype/cli 0.3.1 → 0.3.3

package/tests/augmentation-generator.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it } from "vitest"
-import { generateClientAugmentation } from "../src/augmentation-generator.js"
+import { generateClientAugmentation, generateRowType } from "../src/augmentation-generator.js"
 
 describe("generateClientAugmentation", () => {
-  it("emits deterministic output independent of model order", () => {
+  it("emits models in the order the schema declares them", () => {
     const astA = {
       models: [
         {
@@ -32,9 +32,13 @@ describe("generateClientAugmentation", () => {
       ],
     }
 
-    expect(generateClientAugmentation(astA)).toEqual(generateClientAugmentation(astB))
-    expect(generateClientAugmentation(astA)).toContain("post:")
-    expect(generateClientAugmentation(astA)).toContain("comment:")
+    // The AST keeps the order `schema/index.ts` was written in, so the generated file does
+    // too: alphabetising threw away an order the author chose and the source of truth kept.
+    const a = generateClientAugmentation(astA)
+    const b = generateClientAugmentation(astB)
+    expect(a.indexOf("post:")).toBeLessThan(a.indexOf("comment:"))
+    expect(b.indexOf("comment:")).toBeLessThan(b.indexOf("post:"))
+    expect(a).not.toEqual(b)
   })
 
   it("resolves tableName from AST v2 annotations.db.tableName", () => {
@@ -80,7 +84,7 @@ describe("generateClientAugmentation", () => {
     expect(insertOnly).not.toContain("name?:")
   })
 
-  it("types richText fields as SerializedEditorState", () => {
+  it("types richText fields as the Lexical document they hold", () => {
     const ast = {
       models: [
         {
@@ -93,10 +97,40 @@ describe("generateClientAugmentation", () => {
       ],
     }
     const out = generateClientAugmentation(ast)
-    expect(out).toContain('import("@supatype/types/lexical").SerializedEditorState')
+    expect(out).toContain('import type { SerializedEditorState } from "@supatype/types/lexical"')
+    expect(out).toContain("export type RichText = SerializedEditorState")
+    expect(out).toContain("body: RichText")
     expect(out).not.toMatch(/body: Record<string, unknown>/)
   })
 
+  it("widens a localized richText column inside the locale map, not around it", () => {
+    // The column holds one document per locale and the trigger normalises each of them, so what
+    // accepts prose is the locale's value. `{ [locale: string]: RichText } | string` would say a
+    // bare string is a valid write, and the trigger would store it as a single document where a
+    // locale map belongs, which the Row type says cannot happen.
+    const ast = {
+      models: [
+        {
+          tableName: "page",
+          fields: {
+            id: { kind: "uuid", pgType: "UUID", required: true, primaryKey: true, default: { kind: "genRandomUuid" } },
+            title: { kind: "richText", pgType: "JSONB", required: false, localized: true },
+            body: { kind: "richText", pgType: "JSONB", required: false },
+          },
+        },
+      ],
+    }
+    const out = generateClientAugmentation(ast)
+
+    expect(out).toContain("title: { [locale: string]: RichText } | null")
+    expect(out).toContain("title?: { [locale: string]: RichText | string } | null")
+    expect(out).not.toContain("{ [locale: string]: RichText } | string")
+
+    // The plain column keeps the widening at the top, so one cannot be flattened into the other.
+    expect(out).toContain("body: RichText | null")
+    expect(out).toContain("body?: RichText | string | null")
+  })
+
   it("uses a field's declared tsType instead of collapsing JSONB to an opaque object", () => {
     // `Currency<"USD">` and `Code<"sql">` are stored as JSONB because each carries two values. If
     // the generated row typed them as `Record<string, unknown>`, a caller reading `price.amount`
@@ -125,3 +159,235 @@ describe("generateClientAugmentation", () => {
     expect(out).toContain("notes: Record<string, unknown> | null")
   })
 })
+
+describe("exact-value numeric kinds", () => {
+  /**
+   * A column whose value does not survive an IEEE-754 double must not be typed as one.
+   *
+   * `decimal` used to emit `number` here while `@supatype/types` declared `Decimal<P, S>` as
+   * `string` and the engine emitted `string`, so the ambient client type contradicted both and
+   * told a caller a rounded value was exact.
+   */
+  it("types money, decimal and bigInt so the exact value survives", () => {
+    const out = generateClientAugmentation({
+      models: [
+        {
+          name: "Invoice",
+          annotations: { db: { tableName: "invoice", indexes: [] } },
+          fields: {
+            total: { kind: "money", required: true },
+            rate: { kind: "decimal", required: true },
+            ref: { kind: "bigInt", required: true },
+            qty: { kind: "integer", required: true },
+          },
+        },
+      ],
+    })
+
+    expect(out).toContain("total: string")
+    expect(out).toContain("rate: string")
+    expect(out).toContain("ref: bigint")
+    // The kinds that genuinely fit a double are untouched.
+    expect(out).toContain("qty: number")
+  })
+})
+
+describe("relation fields", () => {
+  const talk = {
+    models: [
+      {
+        name: "Talk",
+        annotations: { db: { tableName: "talk", indexes: [] } },
+        fields: {
+          title: { kind: "text", required: true },
+          speaker: {
+            kind: "relation",
+            cardinality: "belongsTo",
+            target: "Speaker",
+            annotations: { db: { foreignKey: "speaker_id" } },
+          },
+          venue: {
+            kind: "relation",
+            cardinality: "belongsTo",
+            target: "Room",
+            required: true,
+            annotations: { db: { foreignKey: "room_id" } },
+          },
+          authUser: { kind: "relation", cardinality: "belongsTo", target: "User" },
+          slots: { kind: "relation", cardinality: "hasMany", target: "Slot" },
+        },
+      },
+    ],
+  }
+
+  /**
+   * A `belongsTo` is a foreign key column, not an embedded object.
+   *
+   * The generator used to group `relation` with geo/vector/image and emit
+   * `Record<string, unknown>` under the *declared* name, so the augmentation claimed a column
+   * named `speaker` holding an object while Postgres and the engine both had `speaker_id`
+   * holding text. Wrong name and wrong type on the same column.
+   */
+  it("emits the foreign key column, not the declared relation name", () => {
+    const out = generateClientAugmentation(talk)
+    expect(out).toContain("speaker_id: string | null")
+    expect(out).not.toContain("speaker: Record<string, unknown>")
+  })
+
+  it("keeps a required relation non-nullable, matching the engine", () => {
+    expect(generateClientAugmentation(talk)).toContain("room_id: string\n")
+  })
+
+  /** No `foreignKey` annotation, so the column name falls back to the same convention. */
+  it("derives the column name when the AST carries no foreignKey", () => {
+    expect(generateClientAugmentation(talk)).toContain("auth_user_id: string | null")
+  })
+
+  /** The key lives on the other table, so this side has no column to describe. */
+  it("omits hasMany, which is not a column on this table", () => {
+    const out = generateClientAugmentation(talk)
+    expect(out).not.toContain("slots")
+  })
+})
+
+describe("column shapes that disagreed with the database", () => {
+  it("types a localized column as a locale map", () => {
+    // `page.title` is jsonb holding {"en": "...", "fr": "..."} and this said `string`, so
+    // `page.title.toUpperCase()` compiled and then failed in the browser.
+    const row = generateRowType({
+      title: { kind: "text", required: true, localized: true },
+    })
+    expect(row).toContain("title: { [locale: string]: string }")
+  })
+
+  it("leaves a non-localized column of the same kind alone", () => {
+    // The control: a fix that wrapped every text column would pass the assertion above.
+    const row = generateRowType({ slug: { kind: "text", required: true } })
+    expect(row).toContain("slug: string")
+    expect(row).not.toContain("locale")
+  })
+
+  it("types an image as what storage.upload actually produces", () => {
+    // Was `Record<string, unknown>`, which is why the examples cast on the good path. Named
+    // rather than written out, so this file and `types/database.ts` say it the same way.
+    const row = generateRowType({
+      headshot: { kind: "image", required: false, bucket: "speaker-headshots" },
+    })
+    expect(row).toContain("headshot: StorageReference | null")
+  })
+
+  it("types a file the same way", () => {
+    const row = generateRowType({ attachment: { kind: "file", required: true } })
+    expect(row).toContain("attachment: StorageReference")
+  })
+
+  it("does not store a url, because a stored one goes stale", () => {
+    const row = generateRowType({ headshot: { kind: "image", required: true } })
+    expect(row).not.toContain("url")
+  })
+})
+
+/**
+ * What this file has to agree with.
+ *
+ * `types/database.ts` and `supatype/generated/index.d.ts` describe the same columns of the
+ * same tables, and are written by two different generators: the engine's and this one. When
+ * they were compared column by column for a real schema, three of them disagreed, and in
+ * every case this side was the one that was wrong. Each is pinned below.
+ *
+ * The comparison itself is not automated here, because it needs an engine binary. What is
+ * automated is the property each disagreement came down to.
+ */
+describe("agreement with the engine's generator", () => {
+  const ast = {
+    models: [
+      {
+        name: "Event",
+        fields: {
+          id: { kind: "uuid", required: true, primaryKey: true },
+          title: { kind: "text", required: true },
+          slug: { kind: "slug", required: true },
+          description: { kind: "richText", required: false },
+          cover_image: { kind: "image", required: false },
+        },
+        annotations: { db: { tableName: "event", indexes: [] } },
+      },
+    ],
+  }
+
+  /**
+   * A slug is filled by a trigger the engine emits, so an insert need not supply one. This
+   * side demanded it, which asked for a value the database was about to overwrite.
+   */
+  it("does not demand a slug on insert", () => {
+    const out = generateClientAugmentation(ast)
+    const insert = out.split("Insert: {")[1]?.split("}")[0] ?? ""
+    expect(insert).toContain("slug?:")
+    expect(insert).not.toContain("slug: ")
+  })
+
+  /**
+   * A rich-text column holds a Lexical document. `| string` said it might hold a bare string
+   * too, so this file and `types/database.ts` disagreed about the same column.
+   */
+  it("types rich text as the document it holds, and nothing looser", () => {
+    const out = generateClientAugmentation(ast)
+    expect(out).toContain("description: RichText | null")
+    expect(out).not.toContain("SerializedEditorState | string")
+  })
+
+  /**
+   * The three shapes differ by more than optionality here, which they do nowhere else. The
+   * engine emits a trigger that turns a plain string into a document on the way in, so a read
+   * is always a document and a write may be prose.
+   */
+  it("types rich text as a document to read and prose to write", () => {
+    const out = generateClientAugmentation(ast)
+    const block = (name: string): string =>
+      out.split(`${name}: {`)[1]?.split("      }")[0] ?? ""
+    expect(block("Row")).toContain("description: RichText | null")
+    expect(block("Insert")).toContain("description?: RichText | string | null")
+    expect(block("Update")).toContain("description?: RichText | string | null")
+  })
+
+  /** Named aliases, the same ones, so a reader moving between the two files is not
+   * comparing spellings. */
+  it("names the shared types rather than writing them out", () => {
+    const out = generateClientAugmentation(ast)
+    expect(out).toContain("export type RichText = SerializedEditorState")
+    expect(out).toContain("export type StorageReference = {")
+    expect(out).toContain("cover_image: StorageReference | null")
+    expect(out).not.toContain("{ bucket: string; path: string }")
+  })
+
+  /** Emitted only when the schema uses them. */
+  it("declares no alias the schema does not use", () => {
+    const plain = generateClientAugmentation({
+      models: [
+        {
+          name: "Note",
+          fields: { body: { kind: "text", required: true } },
+          annotations: { db: { tableName: "note", indexes: [] } },
+        },
+      ],
+    })
+    expect(plain).not.toContain("RichText")
+    expect(plain).not.toContain("StorageReference")
+  })
+
+  /** The columns sit inside the block that holds them. */
+  it("indents each column into its own block", () => {
+    const out = generateClientAugmentation(ast)
+    expect(out).toContain("        title: string")
+    expect(out).not.toMatch(/^ {2}title: string$/m)
+  })
+
+  /** In the order the schema declares them, because the AST keeps that order. */
+  it("keeps the schema's column order", () => {
+    const out = generateClientAugmentation(ast)
+    const row = out.split("Row: {")[1]?.split("}")[0] ?? ""
+    const order = ["id", "title", "slug", "description", "cover_image"]
+    const positions = order.map((column) => row.indexOf(`${column}:`))
+    expect(positions).toEqual([...positions].sort((a, b) => a - b))
+  })
+})

package/tests/client-generator.test.ts

@@ -0,0 +1,103 @@
+/**
+ * The client a project imports, generated into its own source tree.
+ *
+ * An app writes one import and nothing else:
+ *
+ *     import { createClient } from "./supatype/client"
+ *
+ * That single file carries three things that previously arrived by three different routes, two of
+ * which could silently fail:
+ *
+ *   the module augmentation  was a `.d.ts` found only through tsconfig `include`, so a stale or
+ *                            missing entry left every table name accepted and every column
+ *                            `unknown`, with the build passing
+ *   the field kinds          were read off disk and, failing that, reconstructed from PostgREST's
+ *                            OpenAPI document, which always succeeds and so could never report a
+ *                            project that had not generated
+ *   `createClient`           came from the package, which knows nothing about the project
+ *
+ * Arriving by import means the bundler carries them, tsconfig cannot lose them, nothing is
+ * fetched, and a project that has not generated has no file to import, so the build fails.
+ */
+import { describe, expect, it } from "vitest"
+import { generateProjectClient } from "../src/client-generator.js"
+
+const ast = {
+  models: [
+    {
+      name: "JobPost",
+      annotations: { db: { tableName: "job_post" } },
+      fields: {
+        id: { kind: "uuid", required: true },
+        title: { kind: "text", required: true },
+        views: { kind: "bigInt", required: true },
+        equityPct: { kind: "decimal", required: false },
+      },
+    },
+  ],
+}
+
+const plainAst = {
+  models: [
+    {
+      name: "LandingPage",
+      annotations: { db: { tableName: "landing_page" } },
+      fields: { id: { kind: "uuid", required: true } },
+    },
+  ],
+}
+
+describe("generateProjectClient", () => {
+  it("re-exports the client package, so one import is enough", () => {
+    expect(generateProjectClient(ast)).toContain('export * from "@supatype/client"')
+  })
+
+  it("carries the module augmentation, rather than relying on tsconfig to find it", () => {
+    const out = generateProjectClient(ast)
+    expect(out).toContain('declare module "@supatype/client"')
+    expect(out).toContain("interface SupatypeModels")
+    expect(out).toContain("job_post")
+  })
+
+  it("registers the columns a JSON parser would destroy", () => {
+    const out = generateProjectClient(ast)
+    expect(out).toContain("registerFieldKinds(")
+    expect(out).toContain('"views": "bigint"')
+    expect(out).toContain('"equityPct": "numeric"')
+  })
+
+  it("leaves ordinary columns out of the registration", () => {
+    // Listing a column that survives a parse would invite the client to convert one that was
+    // already correct.
+    const out = generateProjectClient(ast)
+    expect(out).not.toContain('"title"')
+    expect(out).not.toContain('"id": "')
+  })
+
+  it("still registers for a schema with nothing exact", () => {
+    // Registered-and-empty is how the client tells "this project generated and has no exact
+    // columns" from "this project never generated". Both must not look the same.
+    const out = generateProjectClient(plainAst)
+    expect(out).toContain("registerFieldKinds(")
+    expect(out).toContain('"tables": {}')
+  })
+
+  it("imports the registration function from the package", () => {
+    expect(generateProjectClient(ast)).toContain(
+      'import { registerFieldKinds } from "@supatype/client"',
+    )
+  })
+
+  it("says it is generated, on the first line", () => {
+    expect(generateProjectClient(ast).split("\n")[0]).toContain("Generated by supatype")
+  })
+
+  it("is stable across runs, so it does not churn the diff", () => {
+    expect(generateProjectClient(ast)).toBe(generateProjectClient(ast))
+  })
+
+  it("survives an ast it does not recognise", () => {
+    expect(() => generateProjectClient({})).not.toThrow()
+    expect(() => generateProjectClient(null)).not.toThrow()
+  })
+})

package/tests/db-port.test.ts

@@ -0,0 +1,128 @@
+/**
+ * `DATABASE_URL` has to name the port Postgres is published on.
+ *
+ * `SUPATYPE_DB_PORT` moves the host side of the compose mapping so two projects can coexist on one
+ * machine. `DATABASE_URL` is what every host-side script uses. Nothing reconciled them, so a
+ * project moved to 5433 started cleanly, served every request, and failed on its own seed script
+ * with `ECONNREFUSED 127.0.0.1:5432`, naming a port the person never chose.
+ *
+ * The cases that matter most here are the ones where it must NOT act: a remote database is not
+ * ours to repoint, and a malformed URL is not ours to half-fix.
+ */
+
+import { describe, expect, it, beforeEach, afterEach } from "vitest"
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+import { DEFAULT_DB_PORT, publishedDbPort, syncDatabaseUrlPort } from "../src/db-port.js"
+
+let dir: string
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "supatype-dbport-"))
+})
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+function writeEnv(lines: string): void {
+  writeFileSync(join(dir, ".env"), lines, "utf8")
+}
+
+function envText(): string {
+  return readFileSync(join(dir, ".env"), "utf8")
+}
+
+describe("publishedDbPort", () => {
+  it("defaults to the port compose binds when unset", () => {
+    expect(publishedDbPort({})).toBe(DEFAULT_DB_PORT)
+  })
+
+  it("reads the configured port", () => {
+    expect(publishedDbPort({ SUPATYPE_DB_PORT: "5433" })).toBe(5433)
+  })
+
+  it("prefers the dev-local port, because its presence marks the deployment shape", () => {
+    // Found by running the validation e2e: that project publishes on SUPATYPE_DEV_DB_PORT=54330
+    // for its host-side engine, and an earlier version of this file rewrote a correct URL to 5432.
+    expect(publishedDbPort({ SUPATYPE_DEV_DB_PORT: "54330" })).toBe(54330)
+    expect(publishedDbPort({ SUPATYPE_DEV_DB_PORT: "54330", SUPATYPE_DB_PORT: "5433" })).toBe(54330)
+  })
+
+  it("uses the self-host port when there is no dev-local one", () => {
+    expect(publishedDbPort({ SUPATYPE_DB_PORT: "5433" })).toBe(5433)
+  })
+
+  it("falls through a nonsense dev-local port to the self-host one", () => {
+    expect(publishedDbPort({ SUPATYPE_DEV_DB_PORT: "abc", SUPATYPE_DB_PORT: "5433" })).toBe(5433)
+  })
+
+  it("falls back rather than inventing a port from nonsense", () => {
+    // Compose reports a bad value far better than we can, and a made-up port would send the seed
+    // somewhere nothing is listening with no clue why.
+    for (const bad of ["", "   ", "abc", "-1", "0", "70000", "5433.5"]) {
+      expect(publishedDbPort({ SUPATYPE_DB_PORT: bad }), `value ${JSON.stringify(bad)}`).toBe(
+        DEFAULT_DB_PORT,
+      )
+    }
+  })
+})
+
+describe("syncDatabaseUrlPort", () => {
+  it("rewrites the port when the two disagree", () => {
+    writeEnv("DATABASE_URL=postgresql://u:p@localhost:5432/acme\nSUPATYPE_DB_PORT=5433\n")
+    expect(syncDatabaseUrlPort(dir)).toEqual({ from: "5432", to: "5433" })
+    expect(envText()).toContain("localhost:5433/acme")
+  })
+
+  it("keeps the credentials, database and query string intact", () => {
+    // The whole point is one field. A rewrite that dropped the password would take the stack down
+    // in a way that looks nothing like a port problem.
+    writeEnv(
+      "DATABASE_URL=postgresql://supatype_admin:s3cr3t@127.0.0.1:5432/acme?sslmode=disable\nSUPATYPE_DB_PORT=5440\n",
+    )
+    syncDatabaseUrlPort(dir)
+    const url = new URL(readFileSync(join(dir, ".env"), "utf8").match(/^DATABASE_URL=(.+)$/m)![1]!)
+    expect(url.port).toBe("5440")
+    expect(url.username).toBe("supatype_admin")
+    expect(url.password).toBe("s3cr3t")
+    expect(url.pathname).toBe("/acme")
+    expect(url.searchParams.get("sslmode")).toBe("disable")
+  })
+
+  it("does nothing when they already agree", () => {
+    writeEnv("DATABASE_URL=postgresql://u:p@localhost:5433/acme\nSUPATYPE_DB_PORT=5433\n")
+    expect(syncDatabaseUrlPort(dir)).toBeNull()
+  })
+
+  it("treats an absent port as the default rather than rewriting it every run", () => {
+    writeEnv("DATABASE_URL=postgresql://u:p@localhost/acme\n")
+    expect(syncDatabaseUrlPort(dir)).toBeNull()
+  })
+
+  it("leaves a remote database alone", () => {
+    // Somebody else's Postgres. Its port has nothing to do with our compose mapping, and
+    // rewriting it would repoint the project at a database that does not exist.
+    const remote = "postgresql://u:p@db.example.com:5432/acme"
+    writeEnv(`DATABASE_URL=${remote}\nSUPATYPE_DB_PORT=5433\n`)
+    expect(syncDatabaseUrlPort(dir)).toBeNull()
+    expect(envText()).toContain(remote)
+  })
+
+  it("leaves a malformed URL alone rather than half-fixing it", () => {
+    const broken = "postgres//u:p@localhost:5432/acme"
+    writeEnv(`DATABASE_URL=${broken}\nSUPATYPE_DB_PORT=5433\n`)
+    expect(syncDatabaseUrlPort(dir)).toBeNull()
+    expect(envText()).toContain(broken)
+  })
+
+  it("does nothing when there is no DATABASE_URL at all", () => {
+    writeEnv("SUPATYPE_DB_PORT=5433\n")
+    expect(syncDatabaseUrlPort(dir)).toBeNull()
+  })
+
+  it("does nothing when there is no .env", () => {
+    expect(syncDatabaseUrlPort(dir)).toBeNull()
+  })
+})

package/tests/engine-floor.test.ts

@@ -4,8 +4,12 @@ import {
   boundsRequiringHelpers,
   compareVersions,
   ENGINE_MIN_FOR_BOUNDS,
+  ENGINE_MIN_FOR_RICHTEXT_TRIGGER,
+  ENGINE_MIN_FOR_SEED,
   ENGINE_MIN_FOR_VERSIONS,
+  fieldsNeedingRichTextTrigger,
   modelsRequiringVersions,
+  seedUnsupportedByPinnedEngine,
 } from "../src/engine-floor.js"
 import type { ExtractedSchemaAstV2, FieldAstV2, ModelAstV2 } from "../src/schema-ast-v2.js"
 
@@ -36,6 +40,12 @@ function schema(models: ModelAstV2[]): ExtractedSchemaAstV2 {
 const WITH_BOUND = schema([model("Post", { title: field({ validation: { maxLength: 80 } }) })])
 const WITHOUT_BOUND = schema([model("Post", { title: field() })])
 
+const RICH_TEXT = field({ kind: "richText", annotations: { db: { pgType: "JSONB" }, platform: {} } })
+const WITH_RICH_TEXT = schema([model("Post", { title: field(), body: RICH_TEXT })])
+
+/** The engine released before either floor, so it is what a project pinned today would carry. */
+const BEFORE_BOTH = "0.3.3"
+
 describe("compareVersions", () => {
   it("orders by each numeric part, not lexically", () => {
     expect(compareVersions("0.10.0", "0.9.0")).toBeGreaterThan(0)
@@ -143,3 +153,86 @@ describe("the versions floor", () => {
     expect(() => { assertEngineSupportsSchema(WITH_BOUND, "0.1.9") }).toThrow(/bounds/)
   })
 })
+
+describe("the rich text trigger floor", () => {
+  it("names the columns that need it", () => {
+    expect(fieldsNeedingRichTextTrigger(WITH_RICH_TEXT)).toEqual(["Post.body"])
+    expect(fieldsNeedingRichTextTrigger(WITHOUT_BOUND)).toEqual([])
+  })
+
+  it("refuses a rich text column on an engine that cannot normalise it", () => {
+    expect(() => { assertEngineSupportsSchema(WITH_RICH_TEXT, BEFORE_BOTH) }).toThrow(
+      new RegExp(`schema-engine ${ENGINE_MIN_FOR_RICHTEXT_TRIGGER.replace(/\./g, "\.")} or newer`),
+    )
+  })
+
+  it("points at the column, because the remedy is in the schema", () => {
+    try {
+      assertEngineSupportsSchema(WITH_RICH_TEXT, BEFORE_BOTH)
+      expect.unreachable("a rich text column on an older engine has to be refused")
+    } catch (err) {
+      const message = (err as Error).message
+      expect(message).toContain("Post.body")
+      expect(message).toContain("rich text columns")
+      // The whole point of the refusal: what goes wrong is a read, not the push.
+      expect(message).toContain("what the types say is impossible")
+      expect(message).toContain(`versions: { engine: "${ENGINE_MIN_FOR_RICHTEXT_TRIGGER}" }`)
+    }
+  })
+
+  it("allows the release itself and anything newer", () => {
+    expect(() => {
+      assertEngineSupportsSchema(WITH_RICH_TEXT, ENGINE_MIN_FOR_RICHTEXT_TRIGGER)
+    }).not.toThrow()
+    expect(() => { assertEngineSupportsSchema(WITH_RICH_TEXT, "1.0.0") }).not.toThrow()
+  })
+
+  it("says nothing about a schema with no rich text column", () => {
+    expect(() => { assertEngineSupportsSchema(WITHOUT_BOUND, BEFORE_BOTH) }).not.toThrow()
+  })
+
+  it("leaves an unpinned or local project alone", () => {
+    expect(() => { assertEngineSupportsSchema(WITH_RICH_TEXT, undefined) }).not.toThrow()
+    expect(() => { assertEngineSupportsSchema(WITH_RICH_TEXT, "local") }).not.toThrow()
+  })
+})
+
+describe("seedUnsupportedByPinnedEngine", () => {
+  it("refuses a pin with no seed subcommand, and says what to change", () => {
+    const message = seedUnsupportedByPinnedEngine(BEFORE_BOTH)
+    expect(message).toBeDefined()
+    expect(message).toContain(`schema-engine ${ENGINE_MIN_FOR_SEED} or newer`)
+    expect(message).toContain(BEFORE_BOTH)
+    expect(message).toContain(`versions: { engine: "${ENGINE_MIN_FOR_SEED}" }`)
+  })
+
+  it("allows the release itself and anything newer", () => {
+    expect(seedUnsupportedByPinnedEngine(ENGINE_MIN_FOR_SEED)).toBeUndefined()
+    expect(seedUnsupportedByPinnedEngine("1.0.0")).toBeUndefined()
+  })
+
+  it("leaves an unpinned or local project alone", () => {
+    // Unpinned resolves to latest, which is at or above the floor by definition.
+    expect(seedUnsupportedByPinnedEngine(undefined)).toBeUndefined()
+    expect(seedUnsupportedByPinnedEngine("local")).toBeUndefined()
+  })
+
+  it("is not conditional on the schema, because every seed needs the subcommand", () => {
+    // No argument but the pin: there is nothing a project could declare to opt out of this one,
+    // which is what makes it different from every other floor in this file.
+    expect(seedUnsupportedByPinnedEngine.length).toBe(1)
+  })
+})
+
+describe("the floors themselves", () => {
+  it("name the engine release that introduced them", () => {
+    // Hard-coded rather than read back from the constant. Every other assertion in this file
+    // builds its expectation from the value under test, so lowering a floor would move the tests
+    // with it and nothing would go red. A floor is a reviewed claim about a published engine, and
+    // this is the one place that says which one.
+    expect(ENGINE_MIN_FOR_BOUNDS).toBe("0.2.0")
+    expect(ENGINE_MIN_FOR_VERSIONS).toBe("0.3.0")
+    expect(ENGINE_MIN_FOR_RICHTEXT_TRIGGER).toBe("0.4.0")
+    expect(ENGINE_MIN_FOR_SEED).toBe("0.4.0")
+  })
+})

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

@@ -42,13 +42,20 @@ describe("external database: compose", () => {
     const compose = renderSelfHostCompose(managed())
     expect(compose).toMatch(/^ {2}db:$/m)
     expect(compose).toContain("pg_isready")
+    // The positive half of "leaves no reference to the db host anywhere" below. Without this, that
+    // test's negative assertion could pass against a pattern that matches nothing at all.
+    expect(compose).toMatch(/^\s+db:\s*\n\s+condition:/m)
   })
 
   it("leaves no reference to the db host anywhere", () => {
     const compose = renderSelfHostCompose(external())
     expect(compose).not.toContain("@db:5432")
     expect(compose).not.toContain("db-data")
-    expect(compose).not.toContain("condition: service_healthy")
+    // Nothing may wait on a `db` service that is not there. Asserted as a dependency on `db`
+    // rather than as the absence of any health condition, which is what this used to say: storage
+    // waits for the object store to be healthy in every deployment, because that race is about
+    // seaweedfs and has nothing to do with where Postgres lives.
+    expect(compose).not.toMatch(/^\s+db:\s*\n\s+condition:/m)
   })
 
   it("points every database consumer at the one URL", () => {