@ultimat3/db 12.0.0 → 14.0.0

package/src/introspect.ts

@@ -14,6 +14,15 @@ export interface ColumnDescription {
   readonly nullable: boolean;
   readonly default: string | null;
   readonly position: number;
+  /**
+   * The generation expression, as the SNAPSHOT spells it. Absent for an ordinary column and absent
+   * for every row this module reads out of the live catalog — deliberately: Postgres stores its own
+   * rewriting of the expression (`COALESCE(title, ''::text)` for `coalesce("title", '')`), so a
+   * catalog value could never compare equal to a generated one, and drift would report a correct
+   * database forever. Both sides of the diff that DOES read it — `x db gen`'s — are generated
+   * spellings, which is the same rule `IndexDescription.where` states one field down.
+   */
+  readonly generated?: string | undefined;
 }
 
 export interface IndexDescription {
@@ -48,6 +57,21 @@ export interface ForeignKeyDescription {
   readonly onDelete: string | null;
 }
 
+/**
+ * A named CHECK constraint, as the SNAPSHOT spells it — an entity invariant of kind `check`.
+ *
+ * Absent from every row this module reads out of the live catalog, deliberately and for the reason
+ * `ColumnDescription.generated` gives one field up: `pg_get_constraintdef` answers Postgres' own
+ * rewriting of the expression, so a catalog value could never compare equal to a generated one and
+ * drift would report a correct database forever. The diff that DOES read it is `x db gen`'s, where
+ * both sides are this generator's own spellings.
+ */
+export interface CheckDescription {
+  readonly name: string;
+  /** The predicate, exactly as the entity's invariant spells it. */
+  readonly expression: string;
+}
+
 export interface TableDescription {
   readonly schema: string;
   readonly name: string;
@@ -55,6 +79,14 @@ export interface TableDescription {
   readonly primaryKey: readonly string[];
   readonly indexes: readonly IndexDescription[];
   readonly foreignKeys: readonly ForeignKeyDescription[];
+  /**
+   * The CHECK constraints migrations declare. Absent — never `[]` — on a table that declares none
+   * and in every sidecar written before this field existed, matching `IndexDescription.using`: a
+   * snapshot that predates it must read as "nothing recorded" so the next `x db gen` emits the
+   * `add constraint` the database is genuinely missing, rather than as "recorded none", which
+   * would leave every already-generated app's invariants unenforced forever.
+   */
+  readonly checks?: readonly CheckDescription[] | undefined;
 }
 
 export interface SchemaDescription {

package/src/invariant-ddl.ts

@@ -0,0 +1,193 @@
+// Single responsibility: the DDL an entity's INVARIANTS become — what a rule is called, the index a
+// `unique` becomes, and the CHECK list a caller merges. `check-ddl.ts` owns the plan those checks
+// join, because a column declares one of its own and the two are one list on the server.
+//
+// A `check` becomes a named CONSTRAINT, inline on a created table and `alter table … add
+// constraint` on an existing one. A `unique` becomes a unique INDEX — never a UNIQUE constraint —
+// because a soft-deleting entity stamps `deleted_at is null` onto it and Postgres has no partial
+// unique constraint, only a partial unique index. An `assert` becomes nothing: it is declared as a
+// rule only the app can judge (`sql: null`), which is what `hasJsOnlyInvariant` reads it as.
+
+import { assert } from '@ultimat3/core';
+import type {
+  EntityDescriptionLike,
+  IndexDescriptionLike,
+  InvariantDescriptionLike,
+} from './entity-shape';
+import { indexMethodOf } from './index-method';
+import type { CheckDescription } from './introspect';
+import { constraintNameUnsafe } from './invariant-errors';
+import { identifier } from './sql';
+
+/**
+ * `NAMEDATALEN - 1`. Postgres truncates a longer identifier and says nothing, so two constraints
+ * sharing their first 63 bytes are ONE constraint on the server while both names still differ in
+ * the snapshot — invisible to a drift check comparing declared names. `@ultimat3/entity` bounds
+ * the index names it mints for the same reason; this bound is Postgres', not a convention, so
+ * stating it on both sides of the tier seam is one fact written twice rather than two rules.
+ *
+ * Exported so `check-ddl.ts` bounds a column's constraint name against the same number: two copies
+ * of NAMEDATALEN in one package is two rules that can drift, which is the thing it exists against.
+ */
+export const MAX_IDENTIFIER_BYTES = 63;
+
+/**
+ * The convention alone, with nothing validated and nothing refused. One copy, so `constraintNameFor`
+ * and `namesConstraint` can never disagree about what a rule's constraint is called — the two
+ * questions "what do I emit" and "is this recorded constraint that rule's" are the same string.
+ */
+function spellConstraintName(table: string, invariant: InvariantDescriptionLike): string {
+  return `${table}_${invariant.name}_${invariant.kind === 'unique' ? 'key' : 'check'}`;
+}
+
+/**
+ * Whether a CHECK a migration RECORDED is this rule's own enforcement in the database. Two
+ * spellings, because two writers name it: this generator's `<table>_<name>_check`, and a
+ * hand-written migration that used the rule's own name — which is what `examples/dummy`'s
+ * `0001_init.sql` did for every one of its app-judged rules.
+ *
+ * Never throws, unlike `constraintNameFor`: its caller is a REPORTER (`unrendered.ts`), reached by
+ * `x verify`'s drift step, where a throw replaces a finding with a crash. The RECORDED name is
+ * required to be an identifier and the invariant's is not, because only the recorded one is written
+ * back out — into a `--` comment and into a `fix:` — and a sidecar is a hand-editable file.
+ */
+export function namesConstraint(
+  table: string,
+  invariant: InvariantDescriptionLike,
+  recorded: string,
+): boolean {
+  if (!isIdentifier(recorded)) return false;
+  return recorded === invariant.name || recorded === spellConstraintName(table, invariant);
+}
+
+/**
+ * The constraint an invariant becomes: `<table>_<name>_check` / `<table>_<name>_key`.
+ *
+ * The same string `@ultimat3/entity`'s `constraintName` builds, and it has to be re-derived here
+ * rather than read off the description because the projection carries the rule's own name and not
+ * the constraint's. Both spellings are pinned — entity's by `invariants.test.ts`, this one by
+ * `generate-invariant.test.ts` — and a divergence would show up as a constraint this generator
+ * adds twice under two names.
+ */
+export function constraintNameFor(table: string, invariant: InvariantDescriptionLike): string {
+  const name = spellConstraintName(table, invariant);
+  // Through the package's one identifier rule, never a second regex: an invariant name is
+  // validated by nobody at declaration, so this is where a name that closes the quote is stopped.
+  if (!isIdentifier(invariant.name) || !isIdentifier(table)) {
+    throw constraintNameUnsafe(table, invariant.name);
+  }
+  // Bytes and not characters: 63 is what the server counts, and `.length` stops seeing the
+  // truncation the moment a name is not ASCII.
+  const bytes = new TextEncoder().encode(name).length;
+  assert(
+    bytes <= MAX_IDENTIFIER_BYTES,
+    `constraint name "${name}" is ${bytes} bytes; Postgres truncates at ${MAX_IDENTIFIER_BYTES} and says nothing`,
+    `invariant('${invariant.name.slice(0, 20)}…', …)   # shorten the invariant name, then x db gen`,
+  );
+  return name;
+}
+
+/** Whether `identifier()` would accept this name — the package's one rule, asked rather than run. */
+export function isIdentifier(value: string): boolean {
+  try {
+    identifier(value);
+    return true;
+  } catch {
+    // `identifier` throws `X_SQL_UNSAFE` for exactly one reason and the caller re-throws its own,
+    // naming the invariant rather than the raw name — so nothing is swallowed here.
+    return false;
+  }
+}
+
+/**
+ * The physical columns a `unique` invariant names. `columns` when the description carries it;
+ * otherwise the `sql` field, which for a `unique` IS the comma-joined column list.
+ *
+ * The fallback is a re-read, not a name parsed back out of a convention: every part is validated
+ * as an identifier and a part that is not one is REFUSED, so the failure mode `parseIndexName` had
+ * — `posts_org_id_created_at_idx` silently becoming the column `"org_id_created_at"` — cannot
+ * happen, because a physical column name cannot contain a comma. It exists so this package can
+ * emit the constraint before `@ultimat3/entity` (tier 2, which this one may not import) projects
+ * `Invariant.columns`; the field it already holds is what makes the fallback deletable later.
+ */
+export function uniqueColumns(
+  table: string,
+  invariant: InvariantDescriptionLike,
+): readonly string[] {
+  const declared = invariant.columns ?? (invariant.sql ?? '').split(',').map((part) => part.trim());
+  assert(
+    declared.length > 0 && declared.every((column) => column.length > 0),
+    `unique invariant "${invariant.name}" on "${table}" names no columns`,
+    `invariant('${invariant.name}', c.unique(['<column>']))   # name the columns, then x db gen`,
+  );
+  for (const column of declared) {
+    if (!isIdentifier(column)) throw constraintNameUnsafe(table, column);
+  }
+  return declared;
+}
+
+/** A `unique` invariant as the index it is — so one list of indexes is created, diffed and recorded. */
+function uniqueIndexOf(
+  entity: EntityDescriptionLike,
+  invariant: InvariantDescriptionLike,
+): IndexDescriptionLike {
+  return {
+    name: constraintNameFor(entity.table, invariant),
+    columns: uniqueColumns(entity.table, invariant),
+    unique: true,
+    where: invariant.where,
+    order: null,
+  };
+}
+
+/** Every part of an index Postgres fixes at creation — the dedup key, and `redefineIndex`'s. */
+const shapeOf = (index: IndexDescriptionLike): string =>
+  JSON.stringify([
+    [...index.columns],
+    index.unique,
+    index.where,
+    index.order,
+    indexMethodOf(index),
+  ]);
+
+/**
+ * The indexes this entity declares: its own, plus one per `unique` invariant. ONE list, because
+ * `createTable`, `diffTable` and `snapshotOf` must agree about what exists — a unique index emitted
+ * but not recorded is `42P07` on the next `x db gen`, which is a worse failure than the silent drop
+ * this whole change is against.
+ *
+ * Deduped on the whole definition and never on the name, the rule `@ultimat3/entity` already
+ * applies. The case that bites: `invariant('slug', c.unique(['slug']))` on `members` derives
+ * `members_slug_key`, byte for byte what Postgres calls the index a `unique` column clause creates
+ * — so an entity declaring both pushes two `create unique index` statements under one name, which
+ * is `42P07` and a migration that cannot be applied at all. The entity's own index wins, because
+ * `impliedByColumnClause` is written against that name.
+ */
+export function declaredIndexes(entity: EntityDescriptionLike): readonly IndexDescriptionLike[] {
+  const invariants = entity.invariants ?? [];
+  if (invariants.length === 0) return entity.indexes;
+  const seen = new Set(entity.indexes.map(shapeOf));
+  const extra: IndexDescriptionLike[] = [];
+  for (const invariant of invariants) {
+    if (invariant.kind !== 'unique') continue;
+    const index = uniqueIndexOf(entity, invariant);
+    if (seen.has(shapeOf(index))) continue;
+    seen.add(shapeOf(index));
+    extra.push(index);
+  }
+  return [...entity.indexes, ...extra];
+}
+
+/**
+ * The CHECK constraints this entity's INVARIANTS declare, in declaration order. The predicate is
+ * handed on unvalidated: `check-ddl.ts` refuses a second command over the MERGED list, so one rule
+ * covers a rule's expression and a column's alike rather than one guard per producer.
+ */
+export function invariantChecks(entity: EntityDescriptionLike): readonly CheckDescription[] {
+  return (entity.invariants ?? [])
+    .filter((invariant) => invariant.kind === 'check' && invariant.sql !== null)
+    .map((invariant) => ({
+      name: constraintNameFor(entity.table, invariant),
+      expression: invariant.sql ?? '',
+    }));
+}

package/src/invariant-errors.ts

@@ -0,0 +1,47 @@
+// Single responsibility: the two refusals an entity INVARIANT earns before its DDL exists — a name
+// that cannot be an identifier, and a predicate holding a second command. Split out of `errors.ts`
+// only because that file reached the 500-line ceiling; both carry `X_SQL_UNSAFE`, which
+// `DB_OWNED_ERROR_CODES` there still declares and registers. No new code, and none is needed: an
+// invariant name reaching a statement text is the same hazard a branch name or an isolation level
+// is, and axiom 1 says one situation gets one code.
+
+import { describeValue } from '@ultimat3/core';
+import { DbError } from './errors';
+
+/**
+ * A name an invariant contributes to a statement — its own, or a column its `unique` list names —
+ * that cannot be an identifier. `X_SQL_UNSAFE` for the reason `branchNameInvalid` uses it:
+ * `create table` and `add constraint` take no parameters, so the name is SPLICED into the
+ * statement text, and NOTHING validates an invariant name at declaration, so
+ * `invariant('x" ); drop table t; --', …)` type-checks all the way to the generator. The identical
+ * hole `columnName` carried when it was `meta.name ?? snake(property)` with only the first branch
+ * checked, measured through `generateMigration` as a real `drop table`.
+ *
+ * Its own factory rather than `identifierUnsafe`, and that is the whole of its value — `identifier`
+ * refuses the same string one call later, at every site that emits it. What only this one carries
+ * is the REPAIR: `identifierUnsafe` says "pass a plain table/column name" to a caller holding a
+ * name, and an author holding a schema module needs the `invariant()` call named instead. Pinned
+ * on the `fix:` line, because a guard whose only value is its message is proven by nothing else.
+ */
+export const constraintNameUnsafe = (table: string, received: unknown): DbError =>
+  new DbError({
+    code: 'X_SQL_UNSAFE',
+    cause: `an invariant on "${table}" contributes ${describeValue(received)} to a statement, which cannot be a Postgres identifier`,
+    fix: "invariant('post_slug_unique', c.unique(['slug']))   # every name is [A-Za-z_][A-Za-z0-9_$]*, then x db gen",
+    meta: { table },
+  });
+
+/**
+ * A constraint predicate holding more than one command. Read through `statementsOf` — this
+ * package's one lexer, so a `;` inside a string literal is data and not a second statement — and
+ * refused before it is spliced into `check (…)`. The predicate arrives from `Expr.toSql()` at tier
+ * 2 or from a hand-built description, and an operand TypeScript never saw closing the parenthesis
+ * is an injection rather than a typo, which is what `X_SQL_UNSAFE` is for.
+ */
+export const constraintExpressionUnsafe = (constraint: string, count: number): DbError =>
+  new DbError({
+    code: 'X_SQL_UNSAFE',
+    cause: `the predicate of constraint "${constraint}" holds ${count} commands; a CHECK is one expression`,
+    fix: `invariant('${constraint}', c.column.atLeast(0))   # build the predicate with the column DSL, never as text`,
+    meta: { constraint, count },
+  });

package/src/snapshot-parse.ts

@@ -4,6 +4,7 @@
 // is a sidecar one of them accepts and the other cannot use.
 
 import type {
+  CheckDescription,
   ColumnDescription,
   ForeignKeyDescription,
   IndexDescription,
@@ -28,10 +29,30 @@ const order = (value: unknown): value is 'asc' | 'desc' | null =>
 
 function column(value: unknown): ColumnDescription | undefined {
   if (!isRow(value)) return undefined;
-  const { name, dataType, nullable, default: fallback, position } = value;
+  const { name, dataType, nullable, default: fallback, position, generated } = value;
   if (!str(name) || !str(dataType) || !bool(nullable) || !nullableStr(fallback)) return undefined;
   if (typeof position !== 'number') return undefined;
-  return { name, dataType, nullable, default: fallback, position };
+  // `generated` was recorded by `snapshotOf` and dropped HERE, silently, for as long as the field
+  // has existed: the sidecar carried the expression and the parse handed back a column without it,
+  // so `retypeColumn` read every generated column as newly generated and rebuilt it on every
+  // `x db gen`. Absent stays absent — an ordinary column must gain no key.
+  if (!(generated === undefined || str(generated))) return undefined;
+  return {
+    name,
+    dataType,
+    nullable,
+    default: fallback,
+    position,
+    ...(generated === undefined ? {} : { generated }),
+  };
+}
+
+/** The predicate is the snapshot's own spelling, so both halves are plain strings or nothing. */
+function check(value: unknown): CheckDescription | undefined {
+  if (!isRow(value)) return undefined;
+  const { name, expression } = value;
+  if (!str(name) || !str(expression)) return undefined;
+  return { name, expression };
 }
 
 function index(value: unknown): IndexDescription | undefined {
@@ -88,7 +109,14 @@ function tableOf(value: unknown): TableDescription | undefined {
   const indexes = all(value['indexes'], index);
   const foreignKeys = all(value['foreignKeys'], foreignKey);
   if (columns === undefined || indexes === undefined || foreignKeys === undefined) return undefined;
-  return { schema, name, columns, primaryKey, indexes, foreignKeys };
+  // Absent, never `[]`. A sidecar written before constraints were recorded says nothing about
+  // them, and reading that as "this table declares none" would drop every invariant an app has
+  // already generated instead of adding the ones its database is missing.
+  const raw = value['checks'];
+  if (raw === undefined) return { schema, name, columns, primaryKey, indexes, foreignKeys };
+  const checks = all(raw, check);
+  if (checks === undefined) return undefined;
+  return { schema, name, columns, primaryKey, indexes, foreignKeys, checks };
 }
 
 /**

package/src/statement-excerpt.ts

@@ -0,0 +1,18 @@
+// Single responsibility: one SQL statement as one capped line, for an error to print. Its own
+// module because two rails now report statements — `destructive.ts` and `ungeneratable.ts` — and a
+// second copy of "what does a reported statement look like" is two answers to one question.
+
+/**
+ * Only the comments *preceding* the statement come off, the ones `statementsOf` carries in from the
+ * file header or from the `-- backfill …` note above it; the SQL itself stays verbatim.
+ *
+ * Blanking is for **deciding**, never for reporting: `stripSqlNoise` empties quoted identifiers, so
+ * a report built from it says `drop table ""`, which names nothing an author can act on.
+ */
+export function statementExcerpt(statement: string): string {
+  const line = statement
+    .replace(/^(?:\s*(?:--[^\n]*|\/\*[\s\S]*?\*\/)\s*)+/, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return line.length > 120 ? `${line.slice(0, 117)}...` : line;
+}

package/src/ungeneratable.ts

@@ -0,0 +1,86 @@
+// Single responsibility: which statements in a migration's `up` half `x db gen` could never have
+// written — the SQL a squash discards in silence. `REPLICA IDENTITY FULL`, `CREATE EXTENSION`, a
+// `GRANT`, a data backfill: none of them is a declaration, none reaches a `.snapshot.json`, and no
+// declaration-based drift check can see them, because a regenerated sidecar equals the declaration
+// by construction. The rail is the same shape `destructive.ts` is — statements in, statements out.
+
+import { stripSqlNoise } from './sql-noise';
+import { statementExcerpt } from './statement-excerpt';
+import { statementsOf } from './statement-split';
+
+/** One statement form `generateMigration` emits, matched on its leading verb phrase. */
+export interface GeneratableForm {
+  /** What the form is called in a failing test's output. */
+  readonly name: string;
+  /** Anchored at the statement's start, against blanked and lowercased text. */
+  readonly pattern: RegExp;
+}
+
+/**
+ * Everything this package's generator can emit, and nothing else.
+ *
+ * **The list is not a hand-typed opinion, and `ungeneratable.test.ts` is what keeps it from
+ * becoming one.** Two assertions, in both directions, over a corpus that is the real output of
+ * `generateMigration`: no statement in that corpus may be reported (or the check fires on the
+ * framework's own migrations), and every entry here must match a statement in it (or the list has
+ * grown an entry excusing SQL the generator never writes — which is the exact thing this rail
+ * exists to report). A statement form added to `generate.ts` and not to this list fails the first;
+ * an entry added here to silence a finding fails the second.
+ *
+ * Matched on the leading **verb phrase**, never on the whole statement: `alter table` is four
+ * different operations and only some of them are generated, so the sub-clause is part of the
+ * phrase — `alter table … replica identity full` shares its first two words with `add column` and
+ * is the statement that started this.
+ *
+ * What it deliberately does not do is judge a statement's *body*. A hand-written `create table …
+ * partition by range (…)` reads as generatable, because its verb phrase is one the generator
+ * writes. Reporting that needs a schema comparison, which is `schema-drift`'s question and already
+ * has an answer; this one is only ever about a statement with no declaration behind it at all.
+ */
+export const GENERATABLE_FORMS: readonly GeneratableForm[] = [
+  { name: 'create table', pattern: /^create\s+table\b/ },
+  { name: 'drop table', pattern: /^drop\s+table\b/ },
+  { name: 'create index', pattern: /^create\s+index\b/ },
+  { name: 'create unique index', pattern: /^create\s+unique\s+index\b/ },
+  { name: 'drop index', pattern: /^drop\s+index\b/ },
+  { name: 'add column', pattern: /^alter\s+table\s[\s\S]*?\badd\s+column\b/ },
+  { name: 'drop column', pattern: /^alter\s+table\s[\s\S]*?\bdrop\s+column\b/ },
+  { name: 'add constraint', pattern: /^alter\s+table\s[\s\S]*?\badd\s+constraint\b/ },
+  { name: 'drop constraint', pattern: /^alter\s+table\s[\s\S]*?\bdrop\s+constraint\b/ },
+  {
+    name: 'alter column type',
+    pattern: /^alter\s+table\s[\s\S]*?\balter\s+column\s[\s\S]*?\btype\b/,
+  },
+  {
+    name: 'alter column set expression',
+    pattern: /^alter\s+table\s[\s\S]*?\balter\s+column\s[\s\S]*?\bset\s+expression\b/,
+  },
+  {
+    name: 'alter column drop expression',
+    pattern: /^alter\s+table\s[\s\S]*?\balter\s+column\s[\s\S]*?\bdrop\s+expression\b/,
+  },
+];
+
+/**
+ * Every statement in `up` that a regenerated migration would not carry, in apply order, as the one
+ * capped line an error prints — the statement, never a count, because the whole value is telling an
+ * author *which* line a squash discards.
+ *
+ * Decided on blanked text and reported from the original, the rule `destructiveStatements` states:
+ * `statementsOf` cuts on a `;` that is not inside a literal, an identifier, a dollar-quoted body or
+ * a comment, and `stripSqlNoise` blanks all four before a verb is looked for — so
+ * `-- create extension pg_trgm` is prose and `values ('grant select on posts')` is data. The
+ * excerpt keeps its identifiers, because `create extension ""` names nothing an author can act on.
+ *
+ * Only `up`, exactly as the destructive rail: `down` is full of statements the generator does emit
+ * and reversing it teaches nobody anything about what the committed file uniquely holds.
+ */
+export function ungeneratableStatements(up: string): readonly string[] {
+  const found: string[] = [];
+  for (const statement of statementsOf(up)) {
+    const bare = stripSqlNoise(statement).trim().toLowerCase();
+    if (GENERATABLE_FORMS.some((form) => form.pattern.test(bare))) continue;
+    found.push(statementExcerpt(statement));
+  }
+  return found;
+}

package/src/unrendered.ts

@@ -0,0 +1,170 @@
+// Single responsibility: what a generated migration declares it could NOT write, and how that
+// reaches the file. A generator that silently emits less than the declaration is the defect this
+// module exists against — ten invariants and nine defaults went missing between an entity and its
+// own regenerated migration, and the `drift` gate step compares a source hash to a sidecar and
+// never reads the SQL, so the loss was GREEN. A comment in the emitted `up` cannot be green.
+
+import { assert } from '@ultimat3/core';
+import { columnNamesConstraint } from './check-ddl';
+import { hasUnrenderedDefault } from './column-default';
+import type { EntityDescriptionLike, InvariantDescriptionLike } from './entity-shape';
+import { findTable, type SchemaDescription, type TableDescription } from './introspect';
+import { namesConstraint } from './invariant-ddl';
+
+export interface UnrenderedDeclaration {
+  /** Which half of the declaration reached no SQL. */
+  readonly kind: 'default' | 'invariant';
+  /** The physical table it was declared on. */
+  readonly table: string;
+  /** The column or the invariant it was declared on. */
+  readonly name: string;
+  /** What was declared and why nothing was written. One line. */
+  readonly cause: string;
+  /** The edit or the command that makes the next generation carry it. One line. */
+  readonly fix: string;
+}
+
+/**
+ * Refused, not sanitised: a `\n` inside a `--` line comment ENDS the comment, so a cause carrying
+ * one would put the rest of itself into the migration as real SQL. Every value that reaches here
+ * is built from identifiers this generator already validated, so this is the assertion that keeps
+ * that true rather than a filter that quietly rewrites text an author has to act on.
+ */
+function commentLine(text: string): string {
+  assert(
+    !/[\r\n]/.test(text),
+    `a migration comment may not span lines: ${JSON.stringify(text)}`,
+    'report this — a validated identifier reached the comment renderer carrying a newline',
+  );
+  return text;
+}
+
+/**
+ * The block that goes at the TOP of `up`, or nothing at all. Nothing at all is the point: a marker
+ * on every migration marks none, which is the rule `destructive.ts` already states for its own.
+ *
+ * Comments, never a refusal. `x db gen` refusing here would be a generator no app with a
+ * `.default('draft')` could run at all — the whole tree is in that state until `@ultimat3/entity`
+ * projects the expression — and a migration nobody can generate repairs nothing. The comment
+ * survives into the committed file, where a reviewer and the next agent both read it, and
+ * `GeneratedMigration.unrendered` carries the same list for a caller that would rather refuse.
+ */
+export function unrenderedComment(entries: readonly UnrenderedDeclaration[]): string {
+  if (entries.length === 0) return '';
+  const header =
+    `-- UNRENDERED: ${entries.length} declaration${entries.length === 1 ? '' : 's'} reached no SQL. ` +
+    'This migration is SMALLER than the entities declare.';
+  const lines = entries.flatMap((entry) => [
+    commentLine(`--   ${entry.kind} on "${entry.table}"."${entry.name}": ${entry.cause}`),
+    commentLine(`--     fix: ${entry.fix}`),
+  ]);
+  return [commentLine(header), ...lines, ''].join('\n');
+}
+
+/**
+ * A rule the app still declares and this migration TAKES AWAY. An `assert` reaches no SQL by
+ * design — `sql: null` says only the app can judge it — so on its own it is not a loss, and
+ * reporting every one would put a marker on nearly every app's every migration, which marks none.
+ *
+ * It becomes a loss the moment a migration RECORDED the rule as a real CHECK, because `checkPlan`
+ * drops a recorded check nothing declares: regenerating then deletes the database's half of a rule
+ * the entity still states — and it earns no `-- destructive:` marker of its own, because
+ * `destructive.ts` excludes `drop constraint` by name on the argument that the database rebuilds
+ * it, which here nothing does. Measured on `examples/dummy`: five constraints out of
+ * `0001_init.sql` dropped in one run, three of them declared as asserts and reported by this, and
+ * `unrendered` was empty — so `@ultimat3/cli`'s `repairFix` handed out
+ * `x db gen "drop post_slug_shape"` — the command that performs the loss — as the repair for it.
+ *
+ * Self-clearing, which is what keeps it off every later file: once the drop is applied and the new
+ * sidecar written, nothing records the check and the next generation reports nothing.
+ */
+function unrenderedInvariant(
+  entity: EntityDescriptionLike,
+  invariant: InvariantDescriptionLike,
+  recorded: string,
+): UnrenderedDeclaration {
+  return {
+    kind: 'invariant',
+    table: entity.table,
+    // The RECORDED name, never the rule's: it is the string in this migration's own `drop
+    // constraint`, in the sidecar, and in the drift finding a caller matches this entry against.
+    name: recorded,
+    cause:
+      `the entity declares "${invariant.name}" as an assert — a rule only the app can judge — ` +
+      'and this migration drops the CHECK a migration recorded for it',
+    fix:
+      `invariant('${invariant.name}', …)   # express it in SQL to keep the CHECK — ` +
+      'an assert has none, so the next x db gen drops it',
+  };
+}
+
+/** Every recorded CHECK on this table that an `assert` still declares and this run would drop. */
+function droppedAsserts(
+  entity: EntityDescriptionLike,
+  live: TableDescription | undefined,
+): UnrenderedDeclaration[] {
+  const recorded = live?.checks ?? [];
+  if (recorded.length === 0) return [];
+  const entries: UnrenderedDeclaration[] = [];
+  for (const invariant of entity.invariants ?? []) {
+    // `sql !== null` beside the kind, the pair `hasJsOnlyInvariant` already reads: a description
+    // carrying an expression is rendered by `declaredChecks` whatever its kind claims.
+    if (invariant.kind !== 'assert' || invariant.sql !== null) continue;
+    for (const check of recorded) {
+      if (!namesConstraint(entity.table, invariant, check.name)) continue;
+      // A recorded check one of this entity's COLUMNS still declares is not being dropped — the two
+      // naming conventions collide on `<table>_<column>_check` when an assert is named after a
+      // column, and only what this run DECLARES can tell the two apart.
+      if (columnNamesConstraint(entity, check.name)) continue;
+      entries.push(unrenderedInvariant(entity, invariant, check.name));
+    }
+  }
+  return entries;
+}
+
+/**
+ * What the entities declare and this migration does not carry. Two producers, and they are one
+ * question — "is this migration smaller than the declaration?" — never two:
+ *
+ * - a column whose description says `hasDefault` with no expression beside it, which is every
+ *   non-`now()`, non-`gen_random_uuid()` default until `@ultimat3/entity` projects
+ *   `ColumnMeta.default`;
+ * - an `assert` invariant whose CHECK a previous migration recorded, which this run drops.
+ *
+ * The defaults half is read off the ENTITIES and not off the plan, deliberately: a diff that
+ * emitted nothing for a table because nothing about it moved still has to report a default the
+ * create statement never carried, or the loss becomes invisible again on the second run. The
+ * invariants half needs `current` for the opposite reason — an assert with nothing recorded behind
+ * it is not a loss at all, and the recorded schema is the only thing that can tell the two apart.
+ *
+ * `current` is REQUIRED and may be `undefined`: a caller with no recorded schema (the first
+ * migration) has to say so, because the alternative is an argument nobody passes and a blind
+ * answer nobody notices — which is exactly how five drops shipped under an empty list.
+ */
+export function unrenderedOf(
+  entities: readonly EntityDescriptionLike[],
+  current: SchemaDescription | undefined,
+): UnrenderedDeclaration[] {
+  const entries: UnrenderedDeclaration[] = [];
+  for (const entity of entities) {
+    for (const column of entity.columns) {
+      if (!hasUnrenderedDefault(column)) continue;
+      entries.push({
+        kind: 'default',
+        table: entity.table,
+        name: column.column,
+        cause: 'the entity description carries hasDefault with no expression beside it',
+        fix:
+          'project ColumnMeta.default onto ColumnDescription in ' +
+          'packages/entity/src/describe.ts, then re-run x db gen',
+      });
+    }
+    entries.push(
+      ...droppedAsserts(
+        entity,
+        current === undefined ? undefined : findTable(current, entity.table),
+      ),
+    );
+  }
+  return entries;
+}