@ultimat3/db 13.0.0 → 15.0.0

package/src/generate.ts

@@ -3,26 +3,28 @@
 // the CLI passes `describeEntities()` and the types below mirror `EntityDescription` field for
 // field. Every generated migration must be reversible; a drop that loses data refuses instead.
 
-import { assert, systemClock } from '@ultimat3/core';
+import { systemClock } from '@ultimat3/core';
+import { checkClauses, checkPlan, declaredChecks } from './check-ddl';
+import { defaultExpression } from './column-default';
 import { isDestructive } from './destructive';
 import { dropOrder } from './drop-order';
-import type {
-  ColumnDescriptionLike,
-  EntityDescriptionLike,
-  IndexDescriptionLike,
-} from './entity-shape';
+import type { ColumnDescriptionLike, EntityDescriptionLike } from './entity-shape';
 import { migrationIrreversible } from './errors';
 import { type ConstraintPlans, foreignKeyPlan, foreignKeysOf, type Plan } from './foreign-key-plan';
 import type { Regeneration } from './generated-column';
 import { generatedClause, isGenerated, regenerate } from './generated-column';
-import { declaredMethod, indexMethodOf, indexMethodSql } from './index-method';
+import { createIndex, dropIndex, impliedByColumnClause, redefineIndex } from './index-ddl';
 import {
   type ColumnDescription,
   findTable,
-  type IndexDescription,
   type SchemaDescription,
   type TableDescription,
 } from './introspect';
+import { declaredIndexes } from './invariant-ddl';
+import type { MovedAside } from './retype-dependents';
+import { moveDependentsAside } from './retype-dependents';
+import { identifier } from './sql';
+import { type UnrenderedDeclaration, unrenderedComment, unrenderedOf } from './unrendered';
 
 const SQL_TYPES: Readonly<Record<string, string>> = {
   uuid: 'uuid',
@@ -44,61 +46,31 @@ function sqlType(kind: string): string {
   return SQL_TYPES[kind] ?? kind;
 }
 
-/**
- * Entity descriptions carry `hasDefault` but not the expression, so the two generated defaults
- * are inferred from the blessed column helpers. Anything else is left to a follow-up migration.
- */
-function defaultExpression(column: ColumnDescriptionLike): string | null {
-  if (!column.hasDefault) return null;
-  if (column.kind === 'uuid' && column.primaryKey) return 'gen_random_uuid()';
-  if (column.kind === 'timestamptz') return 'now()';
-  return null;
-}
-
 function columnClause(column: ColumnDescriptionLike): string {
   // The generation clause sits directly after the type, and `generatedClause` refuses the pairs
   // Postgres has no column for. Every other part below is unchanged and unreachable for a
   // generated column: it may carry no default, and `hasDefault` is what the refusal reads.
-  const parts = [`"${column.column}"`, `${sqlType(column.kind)}${generatedClause(column)}`];
+  //
+  // Through `identifier`, never `"${…}"`: the name arrives from a projection this package cannot
+  // typecheck and a name that closes its own quote produced a real `drop table` through
+  // `generateMigration` once already. It is also what makes an unrendered report safe to write
+  // into a `--` comment, since generation refuses the dangerous name before the comment exists.
+  const parts = [
+    identifier(column.column).text,
+    `${sqlType(column.kind)}${generatedClause(column)}`,
+  ];
   const expression = defaultExpression(column);
   if (expression !== null) parts.push(`default ${expression}`);
   if (column.notNull) parts.push('not null');
   if (column.unique && !column.primaryKey) parts.push('unique');
-  if (column.check !== null) parts.push(`check (${column.check})`);
-  // No `references` clause. A foreign key is `alter table … add constraint`, emitted after every
-  // table exists (`foreignKeyPlan`) — inline it must point at a table that already exists, and
+  // No `check` clause — written here it was ANONYMOUS and reached `create table` alone, so
+  // regenerating dropped the value set `enumerated()` declares; `check-ddl.ts` owns every CHECK now.
+  // No `references` clause either: a foreign key is `alter table … add constraint`, emitted after
+  // every table exists (`foreignKeyPlan`) — inline it must point at a table that already exists, and
   // entity registration order is the app's import order, which says nothing about that.
   return parts.join(' ');
 }
 
-/**
- * A `unique` column clause already creates an index, and Postgres names it exactly what the
- * entity's own convention names it — `<table>_<column>_key`. Emitting `create unique index` for
- * it too is the same index twice: `42P07`, and a migration that cannot be applied at all.
- * Mirrors the rule `entity()` already applies to a foreign key indexing its own column.
- *
- * A **partial** unique index is not that index: the column clause constrains every row, so
- * skipping the partial one would silently widen the constraint the entity declared.
- */
-function impliedByColumnClause(
-  entity: EntityDescriptionLike,
-  index: IndexDescriptionLike,
-  added: ReadonlySet<string>,
-): boolean {
-  const [only] = index.columns;
-  if (!index.unique || index.where !== null || index.columns.length !== 1 || only === undefined) {
-    return false;
-  }
-  const column = entity.columns.find((each) => each.column === only);
-  // `columnClause` writes `unique` under exactly this condition — keep the two in step.
-  //
-  // NOT an optional chain, despite what biome's useOptionalChain suggests: `column?.unique` is
-  // `boolean | undefined`, and this function returns `boolean`. The lint rule marks its own fix
-  // unsafe for exactly this reason — applying it turned a green typecheck red.
-  // biome-ignore lint/complexity/useOptionalChain: an optional chain widens the return to include undefined
-  return column !== undefined && column.unique && !column.primaryKey && added.has(only);
-}
-
 export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDescription {
   const tables = [...entities]
     .sort((a, b) => (a.table < b.table ? -1 : 1))
@@ -115,6 +87,7 @@ export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDe
           // field existed gains a key and no app's sidecar regenerates over a fact already true.
           ...(column.generated === undefined ? {} : { generated: column.generated }),
         }));
+      const checks = declaredChecks(entity);
       return {
         schema: 'public',
         name: entity.table,
@@ -123,7 +96,10 @@ export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDe
         // Whole, never partly: a snapshot that recorded the name and dropped the predicate made
         // the next generation blind to a `where` or an `order` changing, and a partial index
         // silently kept as a total one is a constraint the entity no longer declares.
-        indexes: entity.indexes.map((index) => ({
+        //
+        // `declaredIndexes`, so a `unique` invariant's index is recorded exactly like an entity's
+        // own — a statement emitted and not recorded is `42P07` on the very next `x db gen`.
+        indexes: declaredIndexes(entity).map((index) => ({
           name: index.name,
           columns: [...index.columns],
           unique: index.unique,
@@ -136,6 +112,10 @@ export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDe
           ...(index.using === undefined ? {} : { using: index.using }),
         })),
         foreignKeys: foreignKeysOf(entity),
+        // Absent, never `[]`, on a table declaring none: a sidecar that predates this field must
+        // read as "nothing recorded" so the next generation adds the constraints the database is
+        // genuinely missing — the rule `using` and `generated` already state one field up.
+        ...(checks.length === 0 ? {} : { checks }),
       };
     });
   return { tables };
@@ -144,141 +124,72 @@ export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDe
 function createTable(entity: EntityDescriptionLike): readonly string[] {
   const clauses = entity.columns.map(columnClause);
   if (entity.primaryKey.length > 0) {
-    clauses.push(`primary key (${entity.primaryKey.map((key) => `"${key}"`).join(', ')})`);
+    const key = entity.primaryKey.map((column) => identifier(column).text).join(', ');
+    clauses.push(`primary key (${key})`);
   }
-  const statements = [`create table "${entity.table}" (\n  ${clauses.join(',\n  ')}\n);`];
+  // After the key, so a table declaring no invariant emits the statement it always emitted.
+  clauses.push(...checkClauses(entity));
+  const statements = [
+    `create table ${identifier(entity.table).text} (\n  ${clauses.join(',\n  ')}\n);`,
+  ];
   // Every column of a new table carries its own clause, so every `unique` one brings its index.
   const added = new Set(entity.columns.map((column) => column.column));
-  for (const index of entity.indexes) {
+  for (const index of declaredIndexes(entity)) {
     if (impliedByColumnClause(entity, index, added)) continue;
     statements.push(createIndex(entity.table, index));
   }
   return statements;
 }
 
-/**
- * Every part of the declaration reaches the statement: the whole column list in its declared
- * order, the direction when one was asked for, and the predicate that makes it partial. A part
- * dropped here is a constraint the database does not hold or an index the planner cannot use.
- */
-function createIndex(table: string, index: IndexDescriptionLike): string {
-  assert(
-    index.columns.length > 0,
-    `index "${index.name}" on "${table}" names no columns`,
-    `indexes: [{ on: ['<column>'] }]   # name the columns in the entity(), then x db gen`,
-  );
-  const method = index.using ?? 'btree';
-  // Two rules Postgres has and a declaration can break, refused here rather than at migrate time:
-  // GIN supports neither a unique index nor an ASC/DESC option, and either one reaches the server
-  // as a syntax error inside `ROLE=migrate` — a release phase that fails with the server's words
-  // and none of the entity's. `X_INVARIANT` for the reason `createIndex` already uses it on an
-  // index naming no columns: a declaration this build cannot honour is refused, never reinterpreted.
-  assert(
-    method === 'btree' || !index.unique,
-    `index "${index.name}" on "${table}" is unique and ${method}; Postgres has no unique ${method} index`,
-    `indexes: [{ on: ['<column>'], using: '${method}' }]   # drop unique, or drop using`,
-  );
-  assert(
-    method === 'btree' || index.order === null,
-    `index "${index.name}" on "${table}" is ${method} and ${index.order}; only a btree orders its keys`,
-    `indexes: [{ on: ['<column>'], using: '${method}' }]   # drop order, or drop using`,
-  );
-  const kind = index.unique ? 'create unique index' : 'create index';
-  const direction = index.order === null ? '' : ` ${index.order}`;
-  const columns = index.columns.map((column) => `"${column}"${direction}`).join(', ');
-  const predicate = index.where === null ? '' : ` where (${index.where})`;
-  // Re-derived from the closed set, never spliced: `indexMethodSql` answers `''` for a btree, so
-  // an index that declared no method emits the statement this generator always emitted, byte for
-  // byte, and one that declared a method Postgres does not have is refused instead of built.
-  return `${kind} "${index.name}" on "${table}"${indexMethodSql(method)} (${columns})${predicate};`;
-}
-
 /**
  * Skipping an existing column by name alone missed the type moving under it: a table created
  * while money's currency was bare `char` keeps `char(1)` and rejects every ISO 4217 code, yet the
  * snapshot this run records claims `char(3)` — two claims with no statement between them. Both
  * sides are generated spellings (`current` is a previous migration's own snapshot), so any
  * difference is a real kind change, not a catalog alias.
+ *
+ * The ALTER is not the whole statement list: Postgres compiled every predicate written against
+ * this column with its OLD type and cannot recompile one, so a partial index or a CHECK that reads
+ * it is dropped FIRST and `moved` carries the names on to the arms that would otherwise act on
+ * them. Without that the retype is `42883` and the migration aborts mid-run
+ * (`retype-dependents.ts`).
  */
 function retypeColumn(
-  table: string,
+  live: TableDescription,
   column: ColumnDescriptionLike,
   recorded: ColumnDescription,
   plan: Plan,
+  moved: MovedAside,
 ): Regeneration {
   const wanted = sqlType(column.kind);
+  const table = live.name;
   // A generated column moves by its own rules — see `generated-column.ts`. Asked whenever EITHER
   // side is one, because becoming generated and ceasing to be are both changes with a statement.
   if (isGenerated(column) || recorded.generated !== undefined) {
     return regenerate(table, column, wanted, recorded, plan);
   }
   if (recorded.dataType === wanted) return 'unchanged';
+  moveDependentsAside(live, column.column, plan, moved);
   const alter = (type: string): string =>
-    `alter table "${table}" alter column "${column.column}" type ${type} ` +
-    `using "${column.column}"::${type};`;
+    `alter table ${identifier(table).text} alter column ${identifier(column.column).text} ` +
+    `type ${type} using ${identifier(column.column).text}::${type};`;
   plan.up.push(alter(wanted));
   plan.down.push(alter(recorded.dataType));
   return 'altered';
 }
 
-/** The parts of an index Postgres cannot alter in place — every one of them is a rebuild. */
-function indexShape(index: IndexDescriptionLike | IndexDescription): string {
-  return JSON.stringify([
-    [...index.columns],
-    index.unique,
-    index.where,
-    index.order ?? null,
-    indexMethodOf(index),
-  ]);
-}
-
-/**
- * A same-named index whose definition moved is dropped and recreated, because Postgres has no
- * `alter index` for any of it — the column list, the uniqueness, the predicate and the direction
- * are all fixed at creation.
- *
- * Matching on the name alone was the gap: `where` and `order` were not even recorded, so an
- * entity narrowing an index to a predicate, or reversing it to `desc`, generated an empty
- * migration and the database kept serving the old one. Both sides here are *generated* spellings
- * — `recorded` is a previous migration's own snapshot, never the catalog's rewriting of it — so a
- * text difference in `where` is a real change and not a formatting one.
- */
-function redefineIndex(
-  table: string,
-  index: IndexDescriptionLike,
-  recorded: IndexDescription,
-  plan: Plan,
-): void {
-  if (indexShape(index) === indexShape(recorded)) return;
-  plan.up.push(`drop index "${index.name}";`, createIndex(table, index));
-  // `down` is reversed at assembly, so the pair is pushed forwards and read backwards: recreating
-  // the recorded definition is what must land last, after the new one is dropped.
-  plan.down.push(
-    createIndex(table, {
-      name: recorded.name,
-      columns: recorded.columns,
-      unique: recorded.unique,
-      where: recorded.where,
-      order: recorded.order,
-      // `declaredMethod`, never a cast: `recorded` is a snapshot's, typed open because the catalog
-      // shares the shape, and a method this generator cannot emit must refuse rather than be
-      // rebuilt as a btree — a `down` that recreates the wrong structure is worse than none.
-      ...(recorded.using === undefined ? {} : { using: declaredMethod(recorded.using) }),
-    }),
-    `drop index "${index.name}";`,
-  );
-}
-
 function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan: Plan): void {
   const existing = new Map(live.columns.map((column) => [column.name, column]));
   const added = new Set<string>();
   // A column `regenerate` had to replace outright: `add column` implies no index, so every index
   // over it has to be stated again even though its own definition never moved.
   const rebuilt = new Set<string>();
+  // What a retype dropped ahead of itself, read by the two arms below.
+  const moved: MovedAside = { indexes: new Set(), checks: new Set() };
   for (const column of entity.columns) {
     const recorded = existing.get(column.column);
     if (recorded !== undefined) {
-      if (retypeColumn(entity.table, column, recorded, plan) === 'rebuilt') {
+      if (retypeColumn(live, column, recorded, plan, moved) === 'rebuilt') {
         rebuilt.add(column.column);
       }
       continue;
@@ -293,22 +204,26 @@ function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan:
     // step nobody can perform, since a generated column cannot be written to.
     const nullable = column.notNull && !isGenerated(column) && defaultExpression(column) === null;
     const clause = nullable ? columnClause({ ...column, notNull: false }) : columnClause(column);
-    plan.up.push(`alter table "${entity.table}" add column ${clause};`);
+    plan.up.push(`alter table ${identifier(entity.table).text} add column ${clause};`);
     if (nullable) {
       plan.up.push(
-        `-- backfill "${column.column}", then: ` +
-          `alter table "${entity.table}" alter column "${column.column}" set not null;`,
+        `-- backfill ${identifier(column.column).text}, then: alter table ` +
+          `${identifier(entity.table).text} alter column ${identifier(column.column).text} set not null;`,
       );
     }
-    plan.down.push(`alter table "${entity.table}" drop column "${column.column}";`);
+    plan.down.push(
+      `alter table ${identifier(entity.table).text} drop column ${identifier(column.column).text};`,
+    );
   }
 
   const indexed = new Map(live.indexes.map((index) => [index.name, index]));
-  for (const index of entity.indexes) {
+  for (const index of declaredIndexes(entity)) {
     const recorded = indexed.get(index.name);
-    // A rebuilt column took its indexes down with it, so this one is CREATED rather than compared:
+    // A rebuilt column took its indexes down with it, and a retype dropped the ones whose
+    // predicate it could not survive — either way this one is CREATED rather than compared:
     // `redefineIndex` sees a definition that never moved and would emit nothing at all.
-    if (recorded !== undefined && !index.columns.some((column) => rebuilt.has(column))) {
+    const gone = moved.indexes.has(index.name) || index.columns.some((each) => rebuilt.has(each));
+    if (recorded !== undefined && !gone) {
       redefineIndex(entity.table, index, recorded, plan);
       continue;
     }
@@ -316,8 +231,14 @@ function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan:
     // migration emits, so it still needs a statement of its own.
     if (impliedByColumnClause(entity, index, added)) continue;
     plan.up.push(createIndex(entity.table, index));
-    plan.down.push(`drop index "${index.name}";`);
+    plan.down.push(dropIndex(index.name));
   }
+
+  // Last: a CHECK may read a column this migration just added, and `add constraint` on a column
+  // that does not exist yet is `42703`. `check-ddl.ts` owns which of them move; `rebuilt` because a
+  // column dropped and re-added lost its constraint while the snapshot still records it, and
+  // `moved.checks` because a retype already dropped the ones written against the old type.
+  checkPlan(entity, live, plan, rebuilt, moved.checks);
 }
 
 export interface GenerateOptions {
@@ -343,6 +264,13 @@ export interface GeneratedMigration {
    * cannot be written unmarked and then refused by `x verify` for lacking the mark.
    */
   readonly destructive: boolean;
+  /**
+   * Every declaration this generator could not write down. Empty on a migration that carries the
+   * whole schema, which is what makes it readable as a verdict rather than as noise — and the same
+   * list `unrenderedComment` writes into the top of `up`, so a caller that would rather refuse
+   * (`x db gen`) and a reviewer reading the committed file are looking at one answer.
+   */
+  readonly unrendered: readonly UnrenderedDeclaration[];
 }
 
 export function migrationStamp(now: Date): string {
@@ -376,7 +304,7 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
     foreignKeyPlan(entity, live, plans);
     if (live === undefined) {
       plan.up.push(...createTable(entity));
-      plan.down.push(`drop table "${entity.table}";`);
+      plan.down.push(`drop table ${identifier(entity.table).text};`);
       continue;
     }
     diffTable(entity, live, plan);
@@ -389,9 +317,12 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
           `x db gen "${options.name}" --allow-destructive   # or keep the column and deprecate it`,
         );
       }
-      plan.up.push(`alter table "${entity.table}" drop column "${column.name}";`);
+      plan.up.push(
+        `alter table ${identifier(entity.table).text} drop column ${identifier(column.name).text};`,
+      );
       plan.down.push(
-        `alter table "${entity.table}" add column "${column.name}" ${column.dataType};` +
+        `alter table ${identifier(entity.table).text} add column ` +
+          `${identifier(column.name).text} ${column.dataType};` +
           ' -- data is not restored',
       );
     }
@@ -409,15 +340,33 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
   plan.up.push(...preDrops.up, ...order.constraints);
   plan.down.push(...preDrops.down, ...order.constraints.map(() => '-- constraint not restored'));
   for (const table of order.tables) {
-    plan.up.push(`drop table "${table.name}";`);
-    plan.down.push(`-- "${table.name}" cannot be restored; recover it from a backup`);
+    plan.up.push(`drop table ${identifier(table.name).text};`);
+    // `identifier` in a comment too: a `--` ends at the first newline, so a name holding one
+    // would put a second command on the next line of `down`.
+    plan.down.push(
+      `-- ${identifier(table.name).text} cannot be restored; recover it from a backup`,
+    );
   }
 
   plan.up.push(...constraints.up);
   plan.down.push(...constraints.down);
 
   const id = `${migrationStamp(options.now ?? systemClock.now())}_${slugify(options.name)}`;
-  const up = plan.up.join('\n');
+  // At the TOP of `up`, so what is MISSING is the first thing read — and a line comment, so it is
+  // noise to every reader that matters: `statementsOf` drops a chunk of comments alone,
+  // `stripSqlNoise` blanks it before `isDestructive` looks for a verb, and the server ignores it.
+  //
+  // Never onto an EMPTY diff. `@ultimat3/cli`'s `generateAppMigration` reads `up.trim().length` as
+  // "nothing changed" and re-records the hash sidecar instead of writing a file; a comment there
+  // would make every `x db gen` on an app with an unrendered default write a migration holding no
+  // statement — a ledger row, a checksum and a place in the apply order for nothing. The list is
+  // still on `GeneratedMigration.unrendered`, which is where a caller with no file reads it.
+  //
+  // `current`, not the entities alone: an `assert` whose CHECK a previous migration recorded is a
+  // loss only because THIS plan drops it, and the recorded schema is the only thing that knows.
+  const unrendered = unrenderedOf(options.entities, current);
+  const body = plan.up.join('\n');
+  const up = body.length === 0 ? body : unrenderedComment(unrendered) + body;
   return {
     id,
     name: options.name,
@@ -427,5 +376,6 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
     down: [...plan.down].reverse().join('\n'),
     snapshot: snapshotOf(options.entities),
     destructive: isDestructive(up),
+    unrendered,
   };
 }

package/src/generated-column.ts

@@ -7,12 +7,19 @@ import { assert } from '@ultimat3/core';
 import type { ColumnDescriptionLike } from './entity-shape';
 import type { Plan } from './foreign-key-plan';
 import type { ColumnDescription } from './introspect';
+import { identifier } from './sql';
 
 /** How a column that moved was brought back into line — what the caller has to do next, if anything. */
 export type Regeneration = 'unchanged' | 'altered' | 'rebuilt';
 
+/**
+ * Through `identifier`, never `"${…}"`, for the reason `columnClause` states — and this path is
+ * the one `columnClause` does NOT cover: `regenerate` is reached from `retypeColumn` for a column
+ * that ALREADY exists, so nothing on the way here has looked at the name. Both operands arrive
+ * from a projection this package cannot typecheck and from a `.snapshot.json` anything may edit.
+ */
 const alterColumn = (table: string, column: string): string =>
-  `alter table "${table}" alter column "${column}"`;
+  `alter table ${identifier(table).text} alter column ${identifier(column).text}`;
 
 /**
  * The `generated always as (…) stored` clause, or `''` for every ordinary column — so a description
@@ -82,16 +89,18 @@ export function regenerate(
   // column again. Reported as `rebuilt` so the caller can put the indexes back — an `add column`
   // implies none of them.
   if (held === null) {
+    const dropColumn = `alter table ${identifier(table).text} drop column ${identifier(column.column).text};`;
     plan.up.push(
-      `alter table "${table}" drop column "${column.column}";`,
-      `alter table "${table}" add column "${column.column}" ${wantedType}` +
-        `${generatedClause(column)}${column.notNull ? ' not null' : ''};`,
+      dropColumn,
+      `alter table ${identifier(table).text} add column ${identifier(column.column).text} ` +
+        `${wantedType}${generatedClause(column)}${column.notNull ? ' not null' : ''};`,
     );
     // Pushed forwards and read backwards — `down` is reversed at assembly.
     plan.down.push(
-      `alter table "${table}" add column "${column.column}" ${recorded.dataType};` +
+      `alter table ${identifier(table).text} add column ${identifier(column.column).text} ` +
+        `${recorded.dataType};` +
         ' -- was not a generated column',
-      `alter table "${table}" drop column "${column.column}";`,
+      dropColumn,
     );
     return 'rebuilt';
   }

package/src/index-ddl.ts

@@ -0,0 +1,137 @@
+// Single responsibility: the DDL an entity's INDEX declaration becomes — the `create index` a
+// declaration writes out, what makes two definitions the same index, and what a moved definition
+// rebuilds. Split out of `generate.ts` at the 500-line ceiling, along the seam `check-ddl.ts` and
+// `generated-column.ts` already drew: `generate.ts` assembles a plan, this file writes the index
+// statements it puts in it, and `invariant-ddl.ts` decides which indexes a table declares.
+
+import { assert } from '@ultimat3/core';
+import type { EntityDescriptionLike, IndexDescriptionLike } from './entity-shape';
+import type { Plan } from './foreign-key-plan';
+import { declaredMethod, indexMethodOf, indexMethodSql } from './index-method';
+import type { IndexDescription } from './introspect';
+import { identifier } from './sql';
+
+/**
+ * A `unique` column clause already creates an index, and Postgres names it exactly what the
+ * entity's own convention names it — `<table>_<column>_key`. Emitting `create unique index` for
+ * it too is the same index twice: `42P07`, and a migration that cannot be applied at all.
+ * Mirrors the rule `entity()` already applies to a foreign key indexing its own column.
+ *
+ * A **partial** unique index is not that index: the column clause constrains every row, so
+ * skipping the partial one would silently widen the constraint the entity declared.
+ */
+export function impliedByColumnClause(
+  entity: EntityDescriptionLike,
+  index: IndexDescriptionLike,
+  added: ReadonlySet<string>,
+): boolean {
+  const [only] = index.columns;
+  if (!index.unique || index.where !== null || index.columns.length !== 1 || only === undefined) {
+    return false;
+  }
+  const column = entity.columns.find((each) => each.column === only);
+  // `columnClause` writes `unique` under exactly this condition — keep the two in step.
+  //
+  // NOT an optional chain, despite what biome's useOptionalChain suggests: `column?.unique` is
+  // `boolean | undefined`, and this function returns `boolean`. The lint rule marks its own fix
+  // unsafe for exactly this reason — applying it turned a green typecheck red.
+  // biome-ignore lint/complexity/useOptionalChain: an optional chain widens the return to include undefined
+  return column !== undefined && column.unique && !column.primaryKey && added.has(only);
+}
+
+/**
+ * Every part of the declaration reaches the statement: the whole column list in its declared
+ * order, the direction when one was asked for, and the predicate that makes it partial. A part
+ * dropped here is a constraint the database does not hold or an index the planner cannot use.
+ */
+export function createIndex(table: string, index: IndexDescriptionLike): string {
+  assert(
+    index.columns.length > 0,
+    `index "${index.name}" on "${table}" names no columns`,
+    `indexes: [{ on: ['<column>'] }]   # name the columns in the entity(), then x db gen`,
+  );
+  const method = index.using ?? 'btree';
+  // Two rules Postgres has and a declaration can break, refused here rather than at migrate time:
+  // GIN supports neither a unique index nor an ASC/DESC option, and either one reaches the server
+  // as a syntax error inside `ROLE=migrate` — a release phase that fails with the server's words
+  // and none of the entity's. `X_INVARIANT` for the reason `createIndex` already uses it on an
+  // index naming no columns: a declaration this build cannot honour is refused, never reinterpreted.
+  assert(
+    method === 'btree' || !index.unique,
+    `index "${index.name}" on "${table}" is unique and ${method}; Postgres has no unique ${method} index`,
+    `indexes: [{ on: ['<column>'], using: '${method}' }]   # drop unique, or drop using`,
+  );
+  assert(
+    method === 'btree' || index.order === null,
+    `index "${index.name}" on "${table}" is ${method} and ${index.order}; only a btree orders its keys`,
+    `indexes: [{ on: ['<column>'], using: '${method}' }]   # drop order, or drop using`,
+  );
+  const kind = index.unique ? 'create unique index' : 'create index';
+  const direction = index.order === null ? '' : ` ${index.order}`;
+  const columns = index.columns
+    .map((column) => `${identifier(column).text}${direction}`)
+    .join(', ');
+  const predicate = index.where === null ? '' : ` where (${index.where})`;
+  // Re-derived from the closed set, never spliced: `indexMethodSql` answers `''` for a btree, so
+  // an index that declared no method emits the statement this generator always emitted, byte for
+  // byte, and one that declared a method Postgres does not have is refused instead of built.
+  return (
+    `${kind} ${identifier(index.name).text} on ${identifier(table).text}` +
+    `${indexMethodSql(method)} (${columns})${predicate};`
+  );
+}
+
+/** `drop index "n";` — the one spelling, so a drop and its recreate cannot name it differently. */
+export const dropIndex = (name: string): string => `drop index ${identifier(name).text};`;
+
+/**
+ * A RECORDED index as a declaration this generator can emit again — `declaredMethod`, never a
+ * cast: the recorded side is typed open because the catalog shares the shape, and a method this
+ * generator cannot write must refuse rather than be rebuilt as a btree. One copy, because
+ * `redefineIndex`'s `down` and `retype-dependents.ts`'s restore ask the same question.
+ */
+export function asDeclared(index: IndexDescription): IndexDescriptionLike {
+  return {
+    name: index.name,
+    columns: index.columns,
+    unique: index.unique,
+    where: index.where,
+    order: index.order,
+    ...(index.using === undefined ? {} : { using: declaredMethod(index.using) }),
+  };
+}
+
+/** The parts of an index Postgres cannot alter in place — every one of them is a rebuild. */
+export function indexShape(index: IndexDescriptionLike | IndexDescription): string {
+  return JSON.stringify([
+    [...index.columns],
+    index.unique,
+    index.where,
+    index.order ?? null,
+    indexMethodOf(index),
+  ]);
+}
+
+/**
+ * A same-named index whose definition moved is dropped and recreated, because Postgres has no
+ * `alter index` for any of it — the column list, the uniqueness, the predicate and the direction
+ * are all fixed at creation.
+ *
+ * Matching on the name alone was the gap: `where` and `order` were not even recorded, so an
+ * entity narrowing an index to a predicate, or reversing it to `desc`, generated an empty
+ * migration and the database kept serving the old one. Both sides here are *generated* spellings
+ * — `recorded` is a previous migration's own snapshot, never the catalog's rewriting of it — so a
+ * text difference in `where` is a real change and not a formatting one.
+ */
+export function redefineIndex(
+  table: string,
+  index: IndexDescriptionLike,
+  recorded: IndexDescription,
+  plan: Plan,
+): void {
+  if (indexShape(index) === indexShape(recorded)) return;
+  plan.up.push(dropIndex(index.name), createIndex(table, index));
+  // `down` is reversed at assembly, so the pair is pushed forwards and read backwards: recreating
+  // the recorded definition is what must land last, after the new one is dropped.
+  plan.down.push(createIndex(table, asDeclared(recorded)), dropIndex(index.name));
+}