autumn-cli 0.10.0

//! The declarative-schema **diff engine** (slice 4 of tracking issue #1975).
//!
//! Given a **desired** state (the app's `#[model]` structs, lifted by the
//! slice-2 [parser](crate::schema::parse)) and a **baseline** (the checked-in,
//! dialect-tagged [snapshot](crate::schema::snapshot) from slice 3), this module
//! computes the pending migration — `desired − baseline` — as a structured
//! [`MigrationPlan`] and renders it as a diesel `up.sql` / `down.sql` pair.
//!
//! It is a **pure, DB-free, IO-free** library module: [`diff_schema`] is a pure
//! function of two in-memory schema states, [`guard_plan`] is a pure policy
//! check, and [`emit_up_sql`] / [`emit_down_sql`] are pure renderers. All IO
//! (loading the snapshot, parsing the models directory, writing the migration
//! files) lives in the command wiring ([`crate::schema::run`]'s `run_diff`), not
//! here.
//!
//! # Conservatism over completeness (the load-bearing rule)
//!
//! The slice-2 parser is a **partial** view of the schema: it documents three
//! gaps it cannot represent — (a) it never fabricates a `CHECK` for an enum
//! column, (b) only an explicit `#[references]` yields a foreign key (association
//! FKs are invisible), and (c) only convention `#[default]`s are recovered. A
//! migration derived from a partial desired state must therefore **never emit a
//! destructive op for a facet the parser simply cannot see** — doing so would
//! delete hand-written constraints that live only in the (richer) baseline.
//!
//! This module encodes that as the deliberate **absence** of `DropCheck`,
//! `DropForeignKey`, and `DropDefault` variants on [`SchemaChange`]: a baseline
//! check / FK / default absent from the desired side is treated as *unknown,
//! retained* — not *removed*. An enum column the parser skipped (recorded as a
//! [`SchemaDiagnostic`](crate::schema::parse::SchemaDiagnostic)) is likewise not
//! dropped. The **accepted trade-off** is that the diff is intentionally
//! conservative and will *miss* a genuine removal of one of those facets; that is
//! preferable to ever destroying parser-invisible or hand-written state. A
//! rename is not a removal: `#[renamed_from]` turns it into a `Rename*` change
//! (see [`crate::schema::rename`]).
//!
//! # Invisible `#[belongs_to(...)]` association foreign keys (offline limitation)
//!
//! The slice-2 parser cannot see a generated `#[belongs_to(...)]` association
//! foreign key: real generator output models it as a plain `<name>_id: i64`
//! column plus a **struct-level** `#[belongs_to(...)]` attribute, and the parser
//! lifts the `i64` field as an ordinary `Int64` column with `references: None` and
//! **no diagnostic** (only an *unresolvable field type* — a generated enum, or an
//! association written as a bare struct-typed field `pub user: User` — records a
//! [`SchemaDiagnostic`](crate::schema::parse::SchemaDiagnostic), and even that
//! carries no target-table). So the diff engine has **no offline signal** for the
//! presence, column, or target of an association FK. This produces two
//! consequences the engine handles conservatively:
//!
//! 1. **Adding a foreign key to a pre-existing column is refused**
//!    ([`DiffError::AddForeignKeyToPreexistingColumn`]). When a column present on
//!    both sides gains an explicit `#[references]` where the baseline recorded
//!    none, the baseline `references: None` is *unknown*, not proof the database
//!    lacks a constraint — the column may already carry an inline `REFERENCES`
//!    named `<table>_<column>_fkey` from the original association-FK generation, so
//!    a fresh `ADD CONSTRAINT <table>_<column>_fkey` would collide and the
//!    migration would not apply. The engine refuses (no override) rather than emit
//!    it; the fix is a manual migration or an authoritative re-snapshot. A
//!    **brand-new** FK column (an `AddColumn` whose `REFERENCES` renders inline) is
//!    safe and is emitted normally — there is no pre-existing constraint to hit.
//!
//! 2. **`DROP TABLE` cannot be checked against invisible inbound association
//!    FKs.** The inbound-reference scan ([`detect_inbound_fk_blocks`]) refuses a
//!    drop whenever a retained table holds a **visible** `references` to the
//!    dropped table (rounds 2/3/5, unchanged and still enforced). But an invisible
//!    `#[belongs_to(...)]` association FK on a retained table produces no
//!    `Column.references` and no diagnostic, so it cannot be detected offline —
//!    the resulting `DROP TABLE` (already `--allow-destructive`-gated) may fail to
//!    apply because the real `<retained>_<col>_fkey` constraint still depends on
//!    the dropped table. A precise guard needs schema introspection (the
//!    `--dev-url` replay gives a baseline that has these FKs); a blanket "refuse every
//!    table drop" would make the common case useless and is deliberately **not**
//!    done. Instead every emitted `DROP TABLE` carries an advisory
//!    `-- autumn-safety:` comment naming this exact gap so the operator verifies
//!    (introspection or a manual FK drop) before applying. This is a documented
//!    limitation of the offline approach, not a bug.
//!
//! # Uniqueness is diffed only through indexes
//!
//! `Column.unique` is treated as informational metadata and is **not** separately
//! diffed. The slice-2 parser always emits a `unique` column together with its
//! `idx_<table>_<field>_unique` unique index, so the index set already carries
//! the uniqueness signal; diffing both would double-count.
//!
//! # Required-column additions need a default
//!
//! Adding a `NOT NULL` column **without a default** to an *existing* table is
//! refused ([`DiffError::RequiredColumnWithoutDefault`]): Postgres validates the
//! constraint against existing rows the instant the column is added, so the
//! `ALTER TABLE ... ADD COLUMN ... NOT NULL` fails on any table that already has
//! rows, and the offline diff engine has no backfill value to synthesize (the
//! safe nullable → backfill → `SET NOT NULL` sequence is a manual multi-step
//! migration). Give the field a `#[default(...)]` (including a synthesized one
//! like `created_at DEFAULT NOW()`) or make it nullable (`Option<...>`). A
//! `NOT NULL`, no-default column inside a brand-new `CreateTable` is fine — the
//! table is empty — and is not refused.
//!
//! Its exact sibling — turning an *existing* nullable column non-null
//! (`SET NOT NULL`) — is refused for the same reason
//! ([`DiffError::SetNotNullRequiresBackfill`]): Postgres validates the
//! constraint against every existing row the instant the `ALTER COLUMN ... SET
//! NOT NULL` runs, so it fails on any pre-existing NULL, and the offline engine
//! has no backfill value to synthesize. The only appliable form would pair a
//! default with a backfill, which is not expressible offline. The inverse
//! (`DROP NOT NULL`, making a column nullable) is always safe and is emitted
//! normally.
//!
//! # Generated identifiers must fit Postgres's 63-byte limit
//!
//! This engine derives some identifiers by unbounded interpolation — the foreign-key
//! constraint name `{table}_{column}_fkey` (`ADD CONSTRAINT` up, `DROP CONSTRAINT`
//! down — both derive it identically, so they always agree) — and emits the
//! parser-provided index names (`idx_<table>_<field>`) verbatim. Postgres silently
//! truncates any identifier to 63 bytes (`NAMEDATALEN - 1`). A generated name over
//! that limit is therefore (a) *silently renamed* on apply, risking a mismatch with
//! hand-written SQL that spells the untruncated name, and (b) a *collision* hazard:
//! if two generated names in the same migration share their first 63 bytes, PG
//! accepts the first `ADD CONSTRAINT`/`CREATE INDEX` and rejects the second as a
//! duplicate relation — an unappliable migration.
//!
//! The **engine-generated FK-constraint name** is purely internal (Postgres would
//! otherwise auto-name the constraint), so it is safe to rename: when
//! `{table}_{column}_fkey` would exceed 63 bytes it is passed through
//! [`bounded_pg_identifier`], which truncates the head and appends a short,
//! deterministic hex suffix (a digest of the full untruncated name) so the result
//! is a valid `≤ 63`-byte identifier. The **same** helper drives both the up
//! `ADD CONSTRAINT` and the down `DROP CONSTRAINT`, and the [`guard_plan`] length
//! check, so all three always agree on the emitted name. A short FK name (the
//! common case) is returned unchanged, so Postgres output is byte-stable.
//!
//! Parser-provided index names (`idx_<table>_<field>`) are **not** truncated — the
//! app spells them elsewhere — so [`guard_plan`] still refuses (no override — the
//! SQL is unappliable, not merely lossy) any Postgres plan that generates an index
//! identifier **longer than 63 bytes**, plus (defensively) any pair of generated
//! names that collide after truncation ([`DiffError::GeneratedIdentifierTooLong`]).
//! The check is **Postgres-only**: `SQLite` has no comparably short identifier
//! limit and does not truncate.
//!
//! # `SQLite` boundary
//!
//! Slice 5 renders both dialects. Postgres emits the direct `ALTER`-family
//! statements; `SQLite` — which has no `ALTER COLUMN TYPE` / `SET`/`DROP NOT NULL`
//! / `SET DEFAULT` / `ADD CHECK` / `ADD CONSTRAINT` — realises those via the
//! **table-recreate** strategy ([`emit_up_sql_with_context`]): `CREATE` a new table
//! with the desired shape, `INSERT .. SELECT` the surviving rows, `DROP` the old
//! table, `RENAME` the new one into place, and recreate the desired indexes,
//! wrapped with `PRAGMA foreign_keys` + a `PRAGMA foreign_key_check`. The recreate
//! needs a table's full desired (up) / baseline (down) shape, which the per-change
//! [`SchemaChange`] deltas do not carry, so it is threaded in via a
//! [`SchemaContext`]; the context-free [`emit_up_sql`] / [`emit_down_sql`] cover
//! Postgres and the portable `SQLite` subset (`CREATE TABLE`, `DROP TABLE`,
//! `ADD COLUMN`, `CREATE`/`DROP INDEX`) and return [`EmitError::SqliteRebuildUnsupported`]
//! if a `SQLite` rebuild is required without the shapes to build it.

use std::collections::{BTreeMap, BTreeSet};
use std::fmt::Write as _;

use autumn_schema_core::{
    Backend, CheckConstraint, Column, ColumnDefault, ColumnType, ForeignKey, ForeignKeyAction,
    IdKind, Index, SerialKind, SqliteAffinity, Table,
};

use crate::schema::parse::ParsedSchema;

/// The computed migration: an ordered list of structural changes plus the
/// dialect they render against. Deterministic — same inputs ⇒ same plan ⇒ same
/// SQL.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MigrationPlan {
    /// The dialect the plan renders against (its provider-lock).
    pub backend: Backend,
    /// The structural changes, in a stable order.
    pub changes: Vec<SchemaChange>,
}

impl MigrationPlan {
    /// True when there is nothing to migrate (the no-op case).
    #[must_use]
    pub const fn is_empty(&self) -> bool {
        self.changes.is_empty()
    }
}

/// One structural change. Variants that DROP existing state carry the full
/// baseline object so `down.sql` can reconstruct it; `Alter*` carry both
/// endpoints so the down leg can invert.
///
/// **Deliberately-absent variants (conservatism):** there is no `DropDefault`,
/// no `DropForeignKey`, no `DropCheck`, and no `AlterUnique`. Those would fire on
/// facets the slice-2 parser cannot fully observe, so emitting them risks
/// destroying hand-written state — their absence is the conservatism mechanism,
/// not an oversight (see the module docs).
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SchemaChange {
    // ---- renames (`#[renamed_from]`, see [`crate::schema::rename`]) ----
    /// A managed table renamed by a `#[renamed_from]` hint. Not destructive.
    RenameTable {
        /// The old table name.
        from: String,
        /// The new table name.
        to: String,
    },
    /// A column renamed by a `#[renamed_from]` hint. Not destructive.
    RenameColumn {
        /// The table name (after any table rename).
        table: String,
        /// The old column name.
        from: String,
        /// The new column name.
        to: String,
    },
    /// A convention-named index renamed to follow a table or column rename.
    RenameIndex {
        /// The table name (after any table rename).
        table: String,
        /// The old index name.
        from: String,
        /// The index with its new name (`SQLite` recreates it from this shape).
        index: Index,
    },
    /// A `#[renamed_from]` hint that the engine cannot apply safely. A
    /// non-emittable marker: [`guard_plan`] refuses it, with no override.
    RenameConflict {
        /// The table the hint is on.
        table: String,
        /// Why the hint cannot apply.
        reason: String,
    },

    // ---- table level ----
    /// A managed table present in the desired state but not the baseline.
    CreateTable(Table),
    /// A managed table present in the baseline but not the desired state.
    /// DESTRUCTIVE; carries the full baseline [`Table`] so `down.sql` can rebuild
    /// it.
    DropTable(Table),

    // ---- column level (keyed on column NAME, never position) ----
    /// A column present in the desired table but not the baseline.
    AddColumn {
        /// The owning table name.
        table: String,
        /// The new column.
        column: Column,
    },
    /// A column present in the baseline table but not the desired one.
    /// DESTRUCTIVE; carries the full baseline [`Column`] so `down.sql` can re-add
    /// it.
    DropColumn {
        /// The owning table name.
        table: String,
        /// The baseline column being dropped.
        column: Column,
    },
    /// A same-named column whose logical type changed.
    AlterColumnType {
        /// The owning table name.
        table: String,
        /// The column name.
        column: String,
        /// The baseline type (for the down leg).
        from: ColumnType,
        /// The desired type.
        to: ColumnType,
    },
    /// A same-named column that gained a `NOT NULL` constraint.
    SetNotNull {
        /// The owning table name.
        table: String,
        /// The column name.
        column: String,
    },
    /// A same-named column that dropped its `NOT NULL` constraint.
    DropNotNull {
        /// The owning table name.
        table: String,
        /// The column name.
        column: String,
    },
    /// A same-named column whose default was set or changed. Carries the baseline
    /// default so the down leg can restore or drop it.
    SetDefault {
        /// The owning table name.
        table: String,
        /// The column name.
        column: String,
        /// The desired default.
        to: ColumnDefault,
        /// The baseline default, if any (for the down leg).
        from: Option<ColumnDefault>,
    },
    /// An explicit foreign key added as a **standalone** `ADD CONSTRAINT ...
    /// FOREIGN KEY` statement.
    ///
    /// Not currently produced by [`diff_schema`]: a **new** FK column renders its
    /// `REFERENCES` inline in the `ADD COLUMN`, and adding an FK to a
    /// **pre-existing** column is refused (see
    /// [`SchemaChange::AddForeignKeyToExistingColumn`] — the parser cannot see a
    /// generated association FK, so it cannot prove the constraint is absent). The
    /// variant and its renderer are retained for the future slice that can observe
    /// FK constraints reliably (schema introspection / a shadow-DB oracle) and can
    /// therefore safely emit a standalone FK add on an existing column.
    #[allow(dead_code)]
    AddForeignKey {
        /// The owning table name.
        table: String,
        /// The column name.
        column: String,
        /// The referenced table/column.
        foreign_key: autumn_schema_core::ForeignKey,
    },

    // ---- index / check level (add/remove by NAME) ----
    /// A secondary index present in the desired table but not the baseline.
    AddIndex {
        /// The owning table name.
        table: String,
        /// The new index.
        index: Index,
    },
    /// A secondary index present in the baseline table but not the desired one.
    /// Carries the full baseline [`Index`] so `down.sql` can recreate it. Not in
    /// the destructive tier (it drops no rows).
    DropIndex {
        /// The owning table name.
        table: String,
        /// The baseline index being dropped.
        index: Index,
    },
    /// A `CHECK` constraint present in the desired table but not the baseline.
    /// (There is deliberately no `DropCheck` — see the module docs.)
    AddCheck {
        /// The owning table name.
        table: String,
        /// The new check constraint.
        check: CheckConstraint,
    },

    /// A managed both-present table whose primary key differs. A non-emittable
    /// marker: [`guard_plan`] refuses any plan containing it (with no override),
    /// so it never reaches the emitters in the command flow. It exists so the
    /// plan-only `guard_plan` signature can detect the change — a PK migration is
    /// exotic, backend-divergent, and out of scope for this slice.
    PrimaryKeyChange {
        /// The table whose primary key changed.
        table: String,
    },

    /// A column whose existing foreign key changed its target or its
    /// `ON DELETE` / `ON UPDATE` action. For example, `author_id` changes from
    /// `users(id)` to `accounts(id)`. [`guard_plan`] refuses each plan that
    /// contains this marker. No flag overrides it.
    ///
    /// It exists because a conservative engine cannot safely retarget an FK: it
    /// has no `DropForeignKey` variant to remove the baseline constraint (whose
    /// name is PG's default `<table>_<column>_fkey`), so blindly emitting an
    /// `AddForeignKey` would collide on that constraint name and the migration
    /// would fail. Retargeting an FK is deferred (a later slice can drop+recreate
    /// once it can observe FK constraints reliably); until then it is refused.
    ForeignKeyChange {
        /// The owning table name.
        table: String,
        /// The column whose FK target changed.
        column: String,
        /// The baseline key, for example `users(id) ON DELETE CASCADE`.
        from: String,
        /// The desired key.
        to: String,
    },

    /// A same-named column whose `GENERATED … AS IDENTITY` clause changed between
    /// two authoritative introspections — e.g. the live database dropped the
    /// identity (`GENERATED ALWAYS AS IDENTITY` → a plain column) or flipped its
    /// generation (`ALWAYS` ↔ `BY DEFAULT`). A non-emittable marker: [`guard_plan`]
    /// refuses any plan containing it (with **no override**).
    ///
    /// It exists so an identity-generation change surfaces as real drift in the
    /// introspection diff (doctor's `database-schema-drift` and `pull --dry-run`)
    /// instead of being silently ignored — changing an identity clause requires
    /// `ADD`/`DROP`/`SET GENERATED …`, an exotic, out-of-scope operation this slice
    /// does not auto-emit (mirroring the serial-PK id-generation refusal). It is
    /// produced **only** in an authoritative diff (`definitions_authoritative`):
    /// the model parser cannot express an identity clause, so in a model diff a
    /// desired `identity: None` is "unknown, retained" (never drift), exactly like a
    /// baseline `definition` index the DSL cannot describe.
    IdentityChange {
        /// The owning table name.
        table: String,
        /// The column whose identity clause changed.
        column: String,
    },

    /// A managed table is dropped while a **retained** table still holds a
    /// baseline foreign key pointing at it (e.g. drop `users` while
    /// `posts.user_id REFERENCES users(id)` survives). A non-emittable marker:
    /// [`guard_plan`] refuses any plan containing it, with **no override** — even
    /// `--allow-destructive` cannot permit it, because that flag authorizes losing
    /// the dropped table's own data, not silently breaking another table's
    /// referential integrity (PG rejects the bare `DROP TABLE`, and this engine has
    /// no `DropForeignKey` variant to clear the constraint first). Self-referential
    /// FKs and FKs from a table that is itself being dropped do **not** produce
    /// this marker — those constraints go away with their table.
    DropTableBlockedByInboundFk {
        /// The table being dropped.
        table: String,
        /// The retained table whose FK references the dropped table.
        referencing_table: String,
        /// The column on `referencing_table` carrying the blocking FK.
        referencing_column: String,
    },

    /// A same-named column whose logical type changed *and* which participates in
    /// a foreign-key constraint that this engine cannot drop and recreate — either
    /// the column is itself a referencing FK column, or another retained table has
    /// a baseline FK targeting it. A non-emittable marker: [`guard_plan`] refuses
    /// any plan containing it with **no override**, because Postgres rejects
    /// `ALTER COLUMN ... TYPE` on a column bound by an FK constraint, and this
    /// engine has no `DropForeignKey`/re-add path to clear it first. It sits on top
    /// of the [`DiffError::NonImplicitTypeConversion`] guard, catching even the
    /// implicit widenings (`int4`→`int8`, `float4`→`float8`) that guard allows.
    AlterColumnTypeBlockedByFk {
        /// The owning table name.
        table: String,
        /// The column whose type change is blocked by an FK constraint.
        column: String,
    },

    /// A **pre-existing** baseline column (present on both sides) that gained an
    /// explicit `#[references]` where the baseline recorded no foreign key. A
    /// non-emittable marker: [`guard_plan`] refuses any plan containing it (with
    /// **no override**).
    ///
    /// It exists because the slice-2 parser cannot see a generated
    /// `#[belongs_to(...)]` association FK — a `<name>_id: i64` column is parsed as
    /// a plain `Int64` with `references: None`, producing *no* diagnostic. So a
    /// baseline `references: None` on a pre-existing column is **unknown**, not
    /// proof the database has no constraint: the column may already carry an inline
    /// `REFERENCES` constraint named `<table>_<column>_fkey` from the original
    /// association-FK generation. Emitting `AddForeignKey` would
    /// `ADD CONSTRAINT <table>_<column>_fkey` a second time and collide with that
    /// existing constraint — an unappliable migration. A **newly-added** FK column
    /// (an [`SchemaChange::AddColumn`], which renders its `REFERENCES` inline) is
    /// safe and is never flagged; only a pre-existing column gaining an FK is.
    AddForeignKeyToExistingColumn {
        /// The owning table name.
        table: String,
        /// The pre-existing column that gained an explicit foreign key.
        column: String,
    },

    /// A brand-new managed table whose model has one or more fields the parser
    /// could not represent (a generated enum, a bare `pub user: User` association)
    /// and therefore recorded a [`SchemaDiagnostic`](crate::schema::parse::SchemaDiagnostic)
    /// for instead of a column. A non-emittable marker: [`guard_plan`] refuses any
    /// plan containing it (with **no override**).
    ///
    /// It exists because emitting `CREATE TABLE` from the partial parser output
    /// would produce DDL that OMITS the skipped column(s) — the generated model
    /// still queries them, so the app would hit "column does not exist" at runtime
    /// the moment it touches the new table. A table missing a column the app
    /// queries is as broken as unappliable SQL, so the conservative stance refuses
    /// and directs the user to a manual migration rather than emit incomplete DDL.
    /// This fires ONLY for a table being CREATED; an existing table with a skipped
    /// column is handled by the `DropColumn`/`DropIndex` suppressions instead.
    CreateTableBlockedBySkippedField {
        /// The table that cannot be safely created.
        table: String,
        /// The parser-skipped field name(s) that would be missing from the DDL.
        fields: Vec<String>,
    },
}

/// Diff policy knobs.
#[derive(Debug, Clone, Copy, Default)]
pub struct DiffOptions {
    /// Second-tier destructive escape hatch. When `false` (the default), a plan
    /// containing a `DropColumn`/`DropTable` — or an ambiguous rename — is refused
    /// by [`guard_plan`]. When `true`, both are permitted (the rename is treated
    /// as an independent drop+add).
    pub allow_destructive: bool,

    /// Whether the DESIRED side can authoritatively express expression/partial
    /// indexes (an [`Index`] carrying a raw `definition`).
    ///
    /// `false` (the **default**) is the *model diff* case (`schema diff` /
    /// `--write-migration`, and doctor's model-vs-snapshot `compute_drift`): the
    /// desired side is parsed from the model DSL, which can only ever produce a
    /// plain `Index { definition: None, .. }` — it *cannot* express an
    /// expression/partial index. A baseline index carrying a `definition` is
    /// therefore an unmodellable/adopted construct, and [`diff_indexes`] **retains**
    /// it (never `DropIndex`/replace) — exactly like an unmanaged/adopted table.
    /// This retention is independent of `allow_destructive`: the declarative tool
    /// never drops what it cannot express.
    ///
    /// `true` is the *introspection diff* case (doctor's
    /// `database-schema-drift` `compute_db_schema_drift`, and `pull --dry-run`),
    /// where BOTH sides are complete introspections, so a `definition` index IS
    /// authoritative — a dropped/changed expression index is real drift and is
    /// still reported (via [`indexes_equivalent`]).
    pub definitions_authoritative: bool,
}

/// Why a computed plan is refused for emission (policy, not structure).
#[derive(Debug, thiserror::Error)]
pub enum DiffError {
    /// The plan drops a table or column and `--allow-destructive` was not passed.
    #[error(
        "refusing to emit a destructive migration: {summary}. \
         Re-run with --allow-destructive to generate it anyway."
    )]
    Destructive {
        /// A human-readable list of the destructive ops.
        summary: String,
        /// The destructive ops, for programmatic inspection.
        ops: Vec<DestructiveOp>,
    },

    /// A `#[renamed_from]` hint cannot apply (no override).
    #[error("cannot apply #[renamed_from] on table `{table}`: {reason}")]
    RenameConflict {
        /// The table the hint is on.
        table: String,
        /// Why the hint cannot apply.
        reason: String,
    },

    /// A single table both dropped and added column(s) — possibly a rename.
    #[error(
        "ambiguous change on table `{table}`: column(s) [{}] disappeared and [{}] appeared. \
         If this is a rename, put #[renamed_from] on the new field \
         (for example #[renamed_from(\"old_name\")]); \
         refusing to emit a drop+add. Re-run with --allow-destructive to treat them \
         as independent drop/add.",
        .dropped.join(", "),
        .added.join(", ")
    )]
    PossibleRename {
        /// The table with the ambiguous change.
        table: String,
        /// The dropped column names.
        dropped: Vec<String>,
        /// The added column names.
        added: Vec<String>,
    },

    /// A both-present table's primary key changed (unsupported this slice, no
    /// override).
    #[error("primary-key change on table `{table}` is not supported in this slice")]
    PrimaryKeyChange {
        /// The table whose primary key changed.
        table: String,
    },

    /// An existing foreign key changed its target or its `ON DELETE` /
    /// `ON UPDATE` action. No flag overrides it. See
    /// [`SchemaChange::ForeignKeyChange`].
    #[error(
        "foreign-key change on `{table}.{column}` is not supported: the baseline has \
         `REFERENCES {from}`, the model has `REFERENCES {to}`. The engine cannot drop \
         the `{table}_{column}_fkey` constraint before it adds the new one. If the \
         database is correct, change the model to agree with it (for example \
         `#[references(on_delete = \"cascade\")]`). If the model is correct, write a \
         manual migration (`autumn generate migration`), apply it, then run \
         `autumn schema pull`."
    )]
    ForeignKeyChange {
        /// The owning table name.
        table: String,
        /// The column whose FK target changed.
        column: String,
        /// The baseline key.
        from: String,
        /// The desired key.
        to: String,
    },

    /// A column's `GENERATED … AS IDENTITY` clause changed between two authoritative
    /// introspections (unsupported this slice, **no override** — see
    /// [`SchemaChange::IdentityChange`]).
    #[error(
        "identity-generation change on `{table}.{column}` is not supported in this slice: \
         changing or dropping a `GENERATED … AS IDENTITY` clause requires an \
         `ADD`/`DROP`/`SET GENERATED` migration this engine does not auto-emit."
    )]
    IdentityChange {
        /// The owning table name.
        table: String,
        /// The column whose identity clause changed.
        column: String,
    },

    /// A table is dropped while another table (a retained baseline table, or a
    /// new/retained desired table) references it (unsupported this slice, **no
    /// override** — `--allow-destructive` does not permit it).
    #[error(
        "cannot drop table `{table}`: `{referencing_table}.{referencing_column}` \
         has a foreign key referencing it. Dropping `{table}` would violate that constraint, \
         and this engine has no way to drop the inbound foreign key first. Drop or retarget \
         `{referencing_table}.{referencing_column}` first. (--allow-destructive does not override \
         this: it authorizes losing this table's data, not breaking another table's integrity.)"
    )]
    DropTableInboundReference {
        /// The table that cannot be dropped.
        table: String,
        /// The table holding the inbound foreign key.
        referencing_table: String,
        /// The column carrying the inbound foreign key.
        referencing_column: String,
    },

    /// A column type change PG cannot cast implicitly (needs a manual `USING`
    /// clause), so a bare `ALTER COLUMN ... TYPE` would be rejected (unsupported
    /// this slice, **no override** — the SQL is unappliable, not merely lossy).
    #[error(
        "non-implicit type conversion on `{table}.{column}` from {from} to {to} requires a manual \
         migration with a USING clause — not supported in this slice"
    )]
    NonImplicitTypeConversion {
        /// The owning table name.
        table: String,
        /// The column name.
        column: String,
        /// The baseline SQL type.
        from: String,
        /// The desired SQL type.
        to: String,
    },

    /// An `ADD COLUMN` of a `NOT NULL` column without a default, to an existing
    /// table (unsupported this slice, **no override** — the SQL is unappliable on
    /// a table that already has rows, not merely lossy). Postgres validates the
    /// `NOT NULL` against existing rows the moment the column is added, so
    /// `ALTER TABLE t ADD COLUMN c <type> NOT NULL` fails on any non-empty table;
    /// the offline diff engine has no backfill value to synthesize. A brand-new
    /// [`SchemaChange::CreateTable`] carrying such a column is fine (the table is
    /// empty) and is **not** refused.
    #[error(
        "cannot add required column `{table}.{column}`: a NOT NULL column without a default \
         fails on a table that already has rows. Add a default (`#[default(...)]`) or make the \
         column nullable (`Option<...>`)."
    )]
    RequiredColumnWithoutDefault {
        /// The table gaining the column.
        table: String,
        /// The required column name.
        column: String,
    },

    /// A `SET NOT NULL` on an existing (previously-nullable) column (unsupported
    /// this slice, **no override** — the SQL is unappliable on a table whose
    /// column already holds NULLs, not merely lossy). Postgres validates the
    /// constraint against every existing row the instant `ALTER COLUMN ... SET
    /// NOT NULL` runs, so it fails on any pre-existing NULL; the offline diff
    /// engine has no backfill value to synthesize. This is the exact sibling of
    /// [`DiffError::RequiredColumnWithoutDefault`] (adding a required column) —
    /// the only appliable form would be a simultaneous default plus a backfill,
    /// which is not expressible offline, so the engine refuses rather than emit
    /// an unappliable migration. The inverse [`SchemaChange::DropNotNull`]
    /// (non-null → nullable) is always safe and is never refused.
    #[error(
        "cannot set `{table}.{column}` NOT NULL: existing NULL rows would fail the constraint. \
         Backfill the column and apply the change manually, or keep it nullable (`Option<...>`)."
    )]
    SetNotNullRequiresBackfill {
        /// The owning table.
        table: String,
        /// The column being made non-null.
        column: String,
    },

    /// A unique-index add whose columns ALL pre-existed on an existing table
    /// (unsupported this slice, **no override** — the SQL is unappliable on a
    /// table whose existing rows may already hold duplicate values, not merely
    /// lossy). Postgres validates uniqueness against every existing row the
    /// instant `CREATE UNIQUE INDEX` runs, so it fails on any pre-existing
    /// duplicate; the offline diff engine cannot dedup the data. This is the
    /// index-level sibling of [`DiffError::SetNotNullRequiresBackfill`]. It fires
    /// only for an [`SchemaChange::AddIndex`] with `unique: true` on a
    /// pre-existing table where **none** of the indexed columns is being added in
    /// the same plan — a unique index on a brand-new [`SchemaChange::CreateTable`]
    /// (empty table) or one touching a newly-added column (whose existing rows are
    /// all NULL, which Postgres treats as distinct) is always safe and is never
    /// refused. A non-unique `AddIndex` is likewise never refused.
    #[error(
        "cannot add unique index `{index}` on `{table}`: existing rows may contain duplicate \
         values that would fail `CREATE UNIQUE INDEX`. Resolve duplicates and apply this \
         manually, or drop the uniqueness requirement."
    )]
    UniqueIndexRequiresDedup {
        /// The owning table.
        table: String,
        /// The unique index being added.
        index: String,
    },

    /// A column type change on a column that participates in a foreign-key
    /// constraint (unsupported this slice, **no override** — the SQL is
    /// unappliable, not merely lossy). Postgres rejects `ALTER COLUMN ... TYPE` on
    /// a column bound by an FK constraint (as either the referencing column or the
    /// referenced key), and this engine has no `DropForeignKey`/re-add path to
    /// clear the constraint first. This applies even to the implicit widenings the
    /// [`DiffError::NonImplicitTypeConversion`] guard would otherwise allow.
    #[error(
        "cannot change the type of `{table}.{column}`: it participates in a foreign-key \
         constraint, which this engine cannot drop and recreate. Change the type via a manual \
         migration that drops and recreates the foreign key."
    )]
    TypeChangeOnForeignKeyColumn {
        /// The owning table name.
        table: String,
        /// The column whose type change is blocked by an FK constraint.
        column: String,
    },

    /// An explicit foreign key was added to a **pre-existing** column whose
    /// baseline recorded no foreign key (unsupported this slice, **no override** —
    /// the SQL may be unappliable, not merely lossy). Because the slice-2 parser
    /// cannot see a generated `#[belongs_to(...)]` association FK (a `<name>_id`
    /// column parses as a plain `Int64` with `references: None` and no diagnostic),
    /// a baseline `references: None` on a pre-existing column is *unknown*, not
    /// proof the database lacks a constraint: the column may already carry an
    /// inline `REFERENCES` named `<table>_<column>_fkey`, so a fresh
    /// `ADD CONSTRAINT` of that same name would collide. A brand-new FK column (an
    /// `ADD COLUMN` with an inline `REFERENCES`) is safe and is never refused.
    #[error(
        "cannot add a foreign key to the pre-existing column `{table}.{column}`: the offline \
         snapshot cannot confirm whether the database already has a constraint for it (e.g. a \
         generated association foreign key), and adding a duplicate `{table}_{column}_fkey` would \
         fail. Add the foreign key via a manual migration, or re-snapshot from an authoritative \
         source."
    )]
    AddForeignKeyToPreexistingColumn {
        /// The owning table name.
        table: String,
        /// The pre-existing column that gained an explicit foreign key.
        column: String,
    },

    /// A generated FK-constraint or index identifier is emitted more than once, or
    /// exceeds Postgres's 63-byte identifier limit, or collides with another
    /// generated name after PG truncates both to 63 bytes (unsupported this slice,
    /// **no override** — the SQL is unappliable, not merely lossy). Postgres
    /// silently truncates any identifier to `NAMEDATALEN - 1` (63) bytes, so an
    /// over-long generated name is both renamed on apply (risking a mismatch with
    /// hand-written SQL) and a duplicate-relation hazard when two names share their
    /// first 63 bytes. A second, distinct hazard: two generated names that are
    /// *exactly* identical (e.g. a `#[unique] foo` field and a separate field named
    /// `foo_unique` both yield `idx_<table>_foo_unique`) — PG accepts the first
    /// `CREATE INDEX`/`ADD CONSTRAINT` and rejects the second as a duplicate
    /// relation. Postgres-only: `SQLite` has no comparable short limit.
    #[error(
        "generated constraint/index name `{name}` is emitted more than once, or exceeds \
         PostgreSQL's 63-byte identifier limit (colliding with another generated name after \
         truncation to 63 bytes); rename the offending field or shorten the table/column names."
    )]
    GeneratedIdentifierTooLong {
        /// The offending generated identifier.
        name: String,
    },

    /// A brand-new managed table whose model has field(s) the schema parser could
    /// not represent (a generated enum, a bare association like `pub user: User`),
    /// so the parser recorded a diagnostic and skipped the column(s) (unsupported
    /// this slice, **no override** — the DDL would be incomplete, not merely lossy).
    /// Emitting `CREATE TABLE` from that partial output would omit the skipped
    /// column(s), but the generated model still queries them, so the app would fail
    /// with "column does not exist" at runtime. A table missing a queried column is
    /// as broken as unappliable SQL, so the engine refuses rather than emit
    /// incomplete DDL. This applies only to a table being CREATED — an existing
    /// table with a skipped column keeps that column via the drop suppressions.
    #[error(
        "cannot generate `CREATE TABLE {table}`: the model has field(s) the schema parser \
         could not represent ({}), so the generated DDL would omit those column(s) and the \
         application would query a missing column at runtime. Write this table's migration \
         manually.",
        .fields.join(", ")
    )]
    CreateTableWithSkippedField {
        /// The table that cannot be safely created.
        table: String,
        /// The parser-skipped field name(s) that would be missing from the DDL.
        fields: Vec<String>,
    },
}

/// A single destructive operation, for [`DiffError::Destructive`] inspection.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum DestructiveOp {
    /// `DROP TABLE <name>`.
    Table(String),
    /// `DROP COLUMN <table>.<column>`.
    Column {
        /// The owning table.
        table: String,
        /// The dropped column.
        column: String,
    },
}

/// Why a plan cannot be rendered to SQL on its backend.
#[derive(Debug, thiserror::Error)]
pub enum EmitError {
    /// A change kind that this slice cannot render on `backend` (slice 5 owns the
    /// full `SQLite` `ALTER` path).
    #[error("change kind `{kind}` is not renderable on {backend:?} yet (slice 5 owns full SQLite)")]
    UnsupportedOnBackend {
        /// The unrenderable change kind.
        kind: &'static str,
        /// The backend it could not be rendered on.
        backend: Backend,
    },

    /// Two or more newly-created tables reference each other through inline
    /// foreign keys, so no `CREATE TABLE` order satisfies all of them. Inline
    /// `REFERENCES` cannot express a cycle (it needs a deferred `ALTER TABLE ADD
    /// CONSTRAINT` after all the `CREATE`s, deferred to a later slice), so this
    /// slice refuses rather than emitting a migration that cannot apply.
    #[error(
        "cannot order the new tables for creation: a foreign-key dependency cycle exists among \
         [{}]. Inline-FK cycles are not supported in this slice.",
        .tables.join(", ")
    )]
    CyclicTableDependencies {
        /// The tables participating in the cycle (sorted, for a stable message).
        tables: Vec<String>,
    },

    /// A `SQLite` `ALTER`-family change needs the table-recreate strategy, but the
    /// full table shape required to rebuild it is unavailable (the context-free
    /// [`emit_up_sql`] / [`emit_down_sql`] were used, or the shape is missing from
    /// the [`SchemaContext`]). Use [`emit_up_sql_with_context`] /
    /// [`emit_down_sql_with_context`] with a populated context.
    #[error("cannot rebuild SQLite table `{table}` for change `{kind}`: {reason}")]
    SqliteRebuildUnsupported {
        /// The table that could not be rebuilt.
        table: String,
        /// The kind of rebuild that was attempted.
        kind: &'static str,
        /// Why the rebuild could not be rendered.
        reason: String,
    },
}

// ---------------------------------------------------------------------------
// Structural diff
// ---------------------------------------------------------------------------

/// Pure structural diff: `desired − baseline` → [`MigrationPlan`]. NEVER refuses,
/// NEVER does IO. Applies the module's conservatism suppressions and
/// managed-table scoping.
///
/// `desired` is the whole [`ParsedSchema`] (tables **and** diagnostics) because
/// the diagnostics drive the enum-skipped-column suppression (a column the parser
/// skipped must not be diffed as a drop).
///
/// `opts` is accepted for API stability; refusal is [`guard_plan`]'s job, so the
/// pure diff does not consult it.
#[must_use]
pub fn diff_schema(baseline: &[Table], desired: &ParsedSchema, opts: DiffOptions) -> MigrationPlan {
    let backend = plan_backend(baseline, desired);
    // `#[renamed_from]` hints: emit the renames first, then diff the renamed
    // baseline so a renamed table or column is not a drop + add.
    let mut changes = crate::schema::rename::rename_changes(baseline, desired);
    let renamed = crate::schema::rename::renamed_baseline(baseline, &changes);
    let baseline = renamed.as_slice();

    let baseline_by_name: BTreeMap<&str, &Table> =
        baseline.iter().map(|t| (t.name.as_str(), t)).collect();
    let desired_by_name: BTreeMap<&str, &Table> = desired
        .tables
        .iter()
        .map(|t| (t.name.as_str(), t))
        .collect();

    // Iterate the union of table names in a stable (sorted) order.
    let mut names: Vec<&str> = baseline_by_name
        .keys()
        .chain(desired_by_name.keys())
        .copied()
        .collect();
    names.sort_unstable();
    names.dedup();

    for name in names {
        match (baseline_by_name.get(name), desired_by_name.get(name)) {
            // Present on both sides — diff only Autumn-managed tables.
            (Some(base), Some(want)) => {
                if want.managed {
                    diff_table(base, want, desired, opts, backend, &mut changes);
                }
            }
            // Desired only — create it if Autumn owns it. But if the parser
            // skipped any of the model's fields (a diagnostic for this table), the
            // parsed `Table` is incomplete: emitting `CREATE TABLE` from it would
            // omit those column(s) while the generated model still queries them, so
            // refuse via a non-emittable marker rather than emit broken DDL.
            (None, Some(want)) => {
                if want.managed {
                    let skipped = skipped_columns(&want.name, desired);
                    if skipped.is_empty() {
                        changes.push(SchemaChange::CreateTable((*want).clone()));
                    } else {
                        changes.push(SchemaChange::CreateTableBlockedBySkippedField {
                            table: want.name.clone(),
                            fields: skipped.into_iter().collect(),
                        });
                    }
                }
            }
            // Baseline only — drop it only if Autumn ever owned it.
            (Some(base), None) => {
                if base.managed {
                    changes.push(SchemaChange::DropTable((*base).clone()));
                }
            }
            (None, None) => unreachable!("name came from one of the two maps"),
        }
    }

    detect_inbound_fk_blocks(baseline, desired, &mut changes);
    detect_fk_type_change_blocks(baseline, desired, &mut changes);

    MigrationPlan { backend, changes }
}

/// Post-pass: for every dropped table, flag any table that still holds a foreign
/// key referencing it. Such a `DROP TABLE` is unappliable (PG rejects it and this
/// engine has no `DropForeignKey`), so a non-emittable
/// [`SchemaChange::DropTableBlockedByInboundFk`] marker is appended for
/// [`guard_plan`] to refuse.
///
/// Two referencer sources are scanned: the **baseline** side (a retained table
/// whose pre-existing FK targets a dropped table) and the **desired** side (a new
/// table, or a retained table with a newly-added FK column, referencing a dropped
/// table — the case the baseline scan cannot see, e.g. drop `users` while adding
/// `posts.author_id #[references(table = "users")]`). A dropped table is absent
/// from `desired`, so a self-referential FK and an FK from a co-dropped table are
/// excluded structurally on the desired side; the baseline scan excludes a
/// referencer that is itself being dropped — either way those constraints go away
/// with their table. The baseline scan additionally excludes a referencing
/// **column** that is itself being dropped in the same plan: `up_ordered` emits
/// every `DropColumn` (which removes the FK constraint) before every `DropTable`,
/// so dropping `posts.user_id` *and* `users` together is valid SQL and must not be
/// over-refused (a common combined cleanup). Markers are deduplicated (a
/// pre-existing FK on a retained table appears on both sides) and, via the
/// `BTreeSet`, deterministically sorted by (dropped, referencing table,
/// referencing column).
fn detect_inbound_fk_blocks(
    baseline: &[Table],
    desired: &ParsedSchema,
    changes: &mut Vec<SchemaChange>,
) {
    let dropped: BTreeSet<&str> = changes
        .iter()
        .filter_map(|c| match c {
            SchemaChange::DropTable(t) => Some(t.name.as_str()),
            _ => None,
        })
        .collect();
    if dropped.is_empty() {
        return;
    }

    // (referencing table, referencing column) pairs being dropped in this plan.
    // Such a column carries its FK constraint away with it — and `up_ordered`
    // emits every `DropColumn` before every `DropTable`, so the constraint is gone
    // before the referenced table is dropped. Excluding these avoids over-refusing
    // a valid combined "drop the FK column and its target table" cleanup.
    let dropped_columns: BTreeSet<(&str, &str)> = changes
        .iter()
        .filter_map(|c| match c {
            SchemaChange::DropColumn { table, column } => {
                Some((table.as_str(), column.name.as_str()))
            }
            _ => None,
        })
        .collect();

    // (dropped table, referencing table, referencing column); BTreeSet dedups the
    // baseline/desired overlap and keeps the emission order deterministic.
    let mut blocks: BTreeSet<(String, String, String)> = BTreeSet::new();

    // Baseline side: a retained table whose baseline FK targets a dropped table.
    for table in baseline {
        // A referencer that is itself being dropped takes its FK with it.
        if dropped.contains(table.name.as_str()) {
            continue;
        }
        for column in &table.columns {
            // A referencing column being dropped in this same plan takes its FK
            // constraint with it (emitted before the DROP TABLE), so it never
            // blocks the drop.
            if dropped_columns.contains(&(table.name.as_str(), column.name.as_str())) {
                continue;
            }
            if let Some(fk) = &column.references
                && dropped.contains(fk.table.as_str())
            {
                blocks.insert((fk.table.clone(), table.name.clone(), column.name.clone()));
            }
        }
    }

    // Desired side: a managed new-or-retained table whose FK targets a dropped
    // table (only managed desired tables emit any SQL). Dropped tables are absent
    // from `desired`, so self-references and co-dropped referencers never appear.
    for table in &desired.tables {
        if !table.managed {
            continue;
        }
        for column in &table.columns {
            if let Some(fk) = &column.references
                && dropped.contains(fk.table.as_str())
            {
                blocks.insert((fk.table.clone(), table.name.clone(), column.name.clone()));
            }
        }
    }

    changes.extend(
        blocks
            .into_iter()
            .map(|(table, referencing_table, referencing_column)| {
                SchemaChange::DropTableBlockedByInboundFk {
                    table,
                    referencing_table,
                    referencing_column,
                }
            }),
    );
}

/// Post-pass: for every `AlterColumnType` change, flag it when the column
/// participates in a foreign-key constraint this engine cannot drop and recreate.
/// Postgres rejects `ALTER COLUMN ... TYPE` on a column bound by an FK — whether
/// the column is the **referencing** column (its own `references` is set) or the
/// **referenced key** (another table's FK targets it) — so the bare
/// `ALTER COLUMN ... TYPE` this engine would emit is unappliable. A non-emittable
/// [`SchemaChange::AlterColumnTypeBlockedByFk`] marker is appended for
/// [`guard_plan`] to refuse (no override). This composes on top of the
/// [`DiffError::NonImplicitTypeConversion`] guard: that guard already refuses
/// non-implicit casts, and this one additionally refuses the implicit widenings
/// (`int4`→`int8`, `float4`→`float8`) it allows, whenever the column is FK-bound.
///
/// The FK scan mirrors [`detect_inbound_fk_blocks`]: baseline retained tables and
/// managed desired tables are both scanned for a referencing column so a
/// pre-existing or newly-declared FK constraint is seen either way. `AlterColumnType`
/// is only produced for a both-present managed table, so the altered column's own
/// table is always retained.
fn detect_fk_type_change_blocks(
    baseline: &[Table],
    desired: &ParsedSchema,
    changes: &mut Vec<SchemaChange>,
) {
    // (table, column) pairs undergoing a type change.
    let type_changes: BTreeSet<(&str, &str)> = changes
        .iter()
        .filter_map(|c| match c {
            SchemaChange::AlterColumnType { table, column, .. } => {
                Some((table.as_str(), column.as_str()))
            }
            _ => None,
        })
        .collect();
    if type_changes.is_empty() {
        return;
    }

    let mut blocks: BTreeSet<(String, String)> = BTreeSet::new();
    for &(table, column) in &type_changes {
        if column_participates_in_fk(table, column, baseline, desired) {
            blocks.insert((table.to_owned(), column.to_owned()));
        }
    }

    changes.extend(
        blocks
            .into_iter()
            .map(|(table, column)| SchemaChange::AlterColumnTypeBlockedByFk { table, column }),
    );
}

/// True when `table.column` participates in a foreign-key constraint — either as
/// the **referencing** column (it carries a `references`, baseline or desired) or
/// as the **referenced key** (some other table's FK targets `table.column`). Both
/// the baseline (existing constraints) and the managed desired tables (declared
/// constraints) are scanned, so a constraint that is present in the database, or
/// that the plan adds, both count. Used only to decide the FK-bound type-change
/// refusal, so it is deliberately conservative.
fn column_participates_in_fk(
    table: &str,
    column: &str,
    baseline: &[Table],
    desired: &ParsedSchema,
) -> bool {
    // Referencing side: the altered column itself carries an FK, in the baseline
    // (the constraint exists in the DB) or the desired managed table.
    let is_referencing = baseline
        .iter()
        .filter(|t| t.name == table)
        .flat_map(|t| &t.columns)
        .chain(
            desired
                .tables
                .iter()
                .filter(|t| t.managed && t.name == table)
                .flat_map(|t| &t.columns),
        )
        .any(|c| c.name == column && c.references.is_some());
    if is_referencing {
        return true;
    }

    // Referenced side: any baseline table, or any managed desired table, whose FK
    // targets `table.column`.
    baseline
        .iter()
        .flat_map(|t| &t.columns)
        .chain(
            desired
                .tables
                .iter()
                .filter(|t| t.managed)
                .flat_map(|t| &t.columns),
        )
        .any(|c| {
            c.references
                .as_ref()
                .is_some_and(|fk| fk.table == table && fk.column == column)
        })
}

/// Diff a table present on both sides (already known Autumn-managed on the
/// desired side), pushing column / index / check changes.
fn diff_table(
    base: &Table,
    want: &Table,
    desired: &ParsedSchema,
    opts: DiffOptions,
    backend: Backend,
    changes: &mut Vec<SchemaChange>,
) {
    // A primary-key change is refused wholesale (guarded); emit only the marker
    // and skip the rest of this table's diff. A change to the id-generation
    // strategy of the single-column PK (a plain `BIGINT PRIMARY KEY` becoming a
    // `BIGSERIAL`, or vice versa — surfaced by the [`SerialKind`] marker) is
    // likewise a primary-key change: converting one into the other requires
    // creating/dropping an owned sequence, which is deliberately out of scope for
    // an auto-generated migration, so it is refused through the same marker.
    if base.primary_key != want.primary_key || serial_kinds_conflict(base, want) {
        changes.push(SchemaChange::PrimaryKeyChange {
            table: want.name.clone(),
        });
        return;
    }

    let base_cols: BTreeMap<&str, &Column> =
        base.columns.iter().map(|c| (c.name.as_str(), c)).collect();
    let want_col_names: std::collections::BTreeSet<&str> =
        want.columns.iter().map(|c| c.name.as_str()).collect();

    // Columns the parser skipped for this table (rule D/E): a baseline column
    // whose name is skipped is "present but unmodelled" and must not be dropped.
    let skipped = skipped_columns(&want.name, desired);

    // Adds and same-name alters, in desired declared order.
    for want_col in &want.columns {
        match base_cols.get(want_col.name.as_str()) {
            None => changes.push(SchemaChange::AddColumn {
                table: want.name.clone(),
                column: want_col.clone(),
            }),
            Some(base_col) => diff_column(&want.name, base_col, want_col, opts, backend, changes),
        }
    }

    // Drops, in baseline declared order — suppressing parser-skipped columns.
    for base_col in &base.columns {
        if !want_col_names.contains(base_col.name.as_str())
            && !skipped.contains(base_col.name.as_str())
        {
            changes.push(SchemaChange::DropColumn {
                table: want.name.clone(),
                column: base_col.clone(),
            });
        }
    }

    diff_indexes(&want.name, base, want, &skipped, opts, backend, changes);
    diff_checks(&want.name, base, want, changes);
}

/// Diff a single same-named column (keyed on name, never position).
/// Whether two column types are equivalent for drift purposes on `backend`.
///
/// On **Postgres** this is exact [`ColumnType`] equality — `INTEGER` vs `BIGINT`
/// (int4 vs int8) is a genuine, distinct type change that must still diff —
/// with one deliberate exception: [`Attachment`](ColumnType::Attachment) and
/// [`Json`](ColumnType::Json) both render `JSONB`, and Postgres introspection
/// cannot tell them apart (`from_pg_introspection` always resolves a raw
/// `jsonb` column to `Attachment` — see its doc comment, issue #1341).
/// Comparing them by exact equality would report a permanent, spurious
/// `Attachment -> Json` (or the reverse) type change — and a needless
/// `ALTER COLUMN ... TYPE JSONB` — on every diff of a model that has a `json`
/// field, even though the physical column never changed. This exception
/// applies on both backends (checked before the backend branch below), since
/// it is about introspection ambiguity, not `SQLite`'s declared-type
/// collapsing.
///
/// On **`SQLite`** the emitter renders several distinct IR types to the same
/// declared type (`Int32`/`Int64`/`Bool` → `INTEGER`, `Float32`/`Float64` →
/// `REAL`, `Text`/`Uuid`/`Timestamp`/`TimestampTz`/`Decimal`/`Attachment`/`Json`/`Enum` →
/// `TEXT`, `Bytes` → `BLOB`), and a pull cannot recover the original variant — so
/// comparing by exact `ColumnType` would report a spurious type change (and a
/// table-recreate) for every `bool`/`i32`/`f32`/plain-`Timestamp` column on every
/// pull. Instead they are compared by [`SqliteAffinity`] class, so a matching
/// model↔pull round-trips CLEAN while a genuine class change (e.g. `INTEGER`→`TEXT`)
/// still drifts. An [`Opaque`](ColumnType::Opaque) type (a verbatim, pull-only type
/// with no clean class) or the ambiguous [`Numeric`](SqliteAffinity::Numeric)
/// catch-all falls back to exact equality so distinct verbatim types are never
/// conflated. Beyond the `Attachment`/`Json` exception above, this rule is
/// strictly `SQLite`-gated and never affects the pg lane. Two
/// [`Decimal`](ColumnType::Decimal)s with a different precision or scale are not
/// equivalent: their `SQLite` `CHECK`s are different (issue #2598).
fn column_types_equivalent(base: &ColumnType, want: &ColumnType, backend: Backend) -> bool {
    if base == want {
        return true;
    }
    if matches!(
        (base, want),
        (ColumnType::Decimal { .. }, ColumnType::Decimal { .. })
    ) {
        return false;
    }
    if matches!(
        (base, want),
        (ColumnType::Attachment, ColumnType::Json) | (ColumnType::Json, ColumnType::Attachment)
    ) {
        return true;
    }
    if backend != Backend::Sqlite {
        return false;
    }
    // An Opaque (verbatim, pull-only) type must match exactly — never conflate two
    // distinct raw types by affinity.
    if matches!(base, ColumnType::Opaque { .. }) || matches!(want, ColumnType::Opaque { .. }) {
        return false;
    }
    let base_class = base.sqlite_affinity();
    // Only the four unambiguous storage classes collapse; the NUMERIC catch-all
    // requires exact equality (already failed the `base == want` check above).
    base_class == want.sqlite_affinity() && base_class != SqliteAffinity::Numeric
}

fn diff_column(
    table: &str,
    base: &Column,
    want: &Column,
    opts: DiffOptions,
    backend: Backend,
    changes: &mut Vec<SchemaChange>,
) {
    if !column_types_equivalent(&base.ty, &want.ty, backend) {
        changes.push(SchemaChange::AlterColumnType {
            table: table.to_owned(),
            column: want.name.clone(),
            from: base.ty.clone(),
            to: want.ty.clone(),
        });
    }

    match (base.nullable, want.nullable) {
        (true, false) => changes.push(SchemaChange::SetNotNull {
            table: table.to_owned(),
            column: want.name.clone(),
        }),
        (false, true) => changes.push(SchemaChange::DropNotNull {
            table: table.to_owned(),
            column: want.name.clone(),
        }),
        _ => {}
    }

    // Rule C: only emit when the desired side has a default that differs. A
    // desired `None` is "unknown, retained" — never a DropDefault.
    if let Some(to) = &want.default
        && base.default.as_ref() != Some(to)
    {
        changes.push(SchemaChange::SetDefault {
            table: table.to_owned(),
            column: want.name.clone(),
            to: to.clone(),
            from: base.default.clone(),
        });
    }

    // Rule B: only the add direction is ever considered — a desired `None` is "unknown,
    // retained", never a DropForeignKey. `diff_column` runs only for a column present on
    // both sides, so an added FK here is on a pre-existing column, which is unsafe: the
    // parser cannot see a generated `#[belongs_to(...)]` association FK, so a baseline
    // `references: None` is unknown rather than proof the DB has no
    // `<table>_<column>_fkey` constraint, and emitting `ADD CONSTRAINT` could collide
    // with an existing one.
    //
    // The three sub-cases when the desired side has an explicit FK on a pre-existing
    // column:
    //   * baseline had none → the FK may already exist invisibly → the refused
    //     `AddForeignKeyToExistingColumn` marker, with no override.
    //   * baseline had the same FK → no change.
    //   * baseline had a different FK (target or action) → a change we cannot safely
    //     emit, since there is no `DropForeignKey` and re-`ADD CONSTRAINT`-ing the default
    //     `<table>_<column>_fkey` name would collide → the refused `ForeignKeyChange`
    //     marker, mirroring `PrimaryKeyChange`.
    //
    // A genuinely new FK column arrives as an `AddColumn`, whose `REFERENCES` is rendered
    // inline rather than as a separate `AddForeignKey`, so it never reaches this branch.
    if let Some(fk) = &want.references {
        match &base.references {
            None => changes.push(SchemaChange::AddForeignKeyToExistingColumn {
                table: table.to_owned(),
                column: want.name.clone(),
            }),
            Some(existing) if existing == fk => {}
            Some(existing) => changes.push(SchemaChange::ForeignKeyChange {
                table: table.to_owned(),
                column: want.name.clone(),
                from: describe_foreign_key(existing),
                to: describe_foreign_key(fk),
            }),
        }
    }

    // Identity clause: an id-generation change — `GENERATED ALWAYS AS IDENTITY` to plain,
    // or `ALWAYS` against `BY DEFAULT` — is compared only in an authoritative diff, where
    // both sides are introspected: doctor's `database-schema-drift` and `pull --dry-run`.
    // The model parser cannot express an identity clause, so in a model diff a desired
    // `identity: None` is "unknown, retained" and never drift, exactly like a baseline
    // `definition` index the DSL cannot describe; comparing it there would spuriously
    // refuse every model against an identity-column DB. In an authoritative diff both
    // sides carry the clause faithfully, so a genuine change surfaces as the refused
    // `IdentityChange` marker instead of being dropped.
    if opts.definitions_authoritative && base.identity != want.identity {
        changes.push(SchemaChange::IdentityChange {
            table: table.to_owned(),
            column: want.name.clone(),
        });
    }
    // NOTE: `Column.unique` is deliberately NOT diffed. On Postgres a single-column
    // unique is ALSO recorded as an `Index`, so a uniqueness change surfaces through
    // `diff_indexes` (comparing the flag too would double-report). On SQLite a
    // brownfield inline `col TEXT UNIQUE` is not modeled at all (#1975 deferral — see
    // `introspect::sqlite::collapse_indexes`), so there is no flag to diff.
}

/// Diff a table's indexes by name. A same-named index whose shape changed is a
/// drop-then-add (neither is destructive — an index drops no rows).
///
/// A `DropIndex` is **suppressed** when the baseline index references ANY column in
/// `skipped` (a parser-skipped column, per [`skipped_columns`]): the parser never
/// saw the column, so it never saw the column's indexes either — their absence from
/// the desired side is a parser gap, not proof the index was removed. Dropping such
/// an index would silently lose a constraint (e.g. a UNIQUE index → duplicate data
/// becomes possible) the same way an unsuppressed `DropColumn` would lose the
/// column. This mirrors the `DropColumn` suppression in [`diff_table`]. A composite
/// index touching even one skipped column is suppressed whole, since the parser
/// cannot authoritatively say it was removed.
/// Whether two same-named indexes are equivalent for drift purposes. When either
/// carries a raw `definition` (an expression/partial index preserved verbatim by
/// introspection), they are compared by that canonical `pg_get_indexdef` text and
/// `unique` — the `columns` list is only a partial, display-oriented view of such
/// an index. Otherwise (ordinary column indexes) they compare by `columns` +
/// `unique`, identical to the pre-`definition` behavior.
fn indexes_equivalent(a: &Index, b: &Index) -> bool {
    if a.definition.is_some() || b.definition.is_some() {
        a.definition == b.definition && a.unique == b.unique
    } else {
        a.columns == b.columns && a.unique == b.unique
    }
}

/// Whether `index` depends on column `col` — i.e. dropping `col` via
/// `ALTER TABLE … DROP COLUMN` would leave the index referencing a missing column
/// (so the index must be dropped/pruned first).
///
/// **Postgres**: dependency is EXACT `columns` membership. For a retained
/// (`definition`-carrying) expression/partial/constraint-owned index `columns` is
/// the **exact `pg_depend` dependent-column set** captured by introspection (key,
/// expression-referenced, AND predicate columns — the same set Postgres cascades on
/// a `DROP COLUMN`), so a text scan is unnecessary and deliberately avoided (it would
/// false-positive on a column name that merely appears in a string literal, e.g. a
/// partial index `WHERE kind = 'email'` while dropping an unrelated `email` column).
///
/// **`SQLite`**: a retained partial/expression index records only its KEY columns in
/// `columns` (its WHERE-predicate / key-expression columns are NOT captured there —
/// `SQLite`'s catalog exposes no `pg_depend` equivalent), so exact `columns`
/// membership misses a predicate/expression column. To avoid emitting an
/// invalid `DROP COLUMN` that orphans such an index, the verbatim `definition` is
/// **word-bounded token-scanned** for `col`: any occurrence counts as a dependency,
/// so the index is pruned before the column drop. This is the conservative
/// over-include-is-safe direction (a false positive from a string literal at worst
/// prunes an index that a rebuild would recreate anyway — never invalid SQL).
///
/// Both `project_plan_target` (snapshot projection) and [`emit_down_sql_pg`] use this
/// single test so they cannot drift.
pub fn index_depends_on_column(index: &Index, col: &str, backend: Backend) -> bool {
    if index.columns.iter().any(|c| c == col) {
        return true;
    }
    if backend == Backend::Sqlite
        && let Some(def) = &index.definition
    {
        return definition_references_column(def, col);
    }
    false
}

/// Whether the verbatim index `definition` references the identifier `col` as a
/// **word-bounded** token (case-insensitive; word chars are `[A-Za-z0-9_]`), so a
/// quoted `"col"`, a bare `col`, or `col` inside an expression/predicate matches, but
/// a longer identifier that merely contains it (`col_backup`, `old_col`) does not.
fn definition_references_column(definition: &str, col: &str) -> bool {
    if col.is_empty() {
        return false;
    }
    let hay = definition.to_ascii_lowercase();
    let needle = col.to_ascii_lowercase();
    let hb = hay.as_bytes();
    let is_word = |b: u8| b.is_ascii_alphanumeric() || b == b'_';
    let mut from = 0;
    while let Some(rel) = hay[from..].find(&needle) {
        let start = from + rel;
        let end = start + needle.len();
        let before_ok = start == 0 || !is_word(hb[start - 1]);
        let after_ok = end == hb.len() || !is_word(hb[end]);
        if before_ok && after_ok {
            return true;
        }
        from = start + 1;
    }
    false
}

///
/// ## Unmodellable (expression/partial) indexes
///
/// An [`Index`] carrying a raw `definition` (an expression or partial index,
/// preserved verbatim by `schema pull` introspection) **cannot be produced by the
/// model parser** — `#[indexed]`/`#[unique]` only ever yield
/// `Index { definition: None, .. }`. So in a *model diff*
/// (`opts.definitions_authoritative == false`) a baseline `definition` index is an
/// adopted construct the desired side is simply unable to describe, and it is
/// **retained** — never `DropIndex`'d or replaced — exactly like an
/// unmanaged/adopted table. This retention is independent of `allow_destructive`:
/// the declarative tool never drops what it cannot express. In an *introspection
/// diff* (`opts.definitions_authoritative == true`, from
/// [`compute_db_schema_drift`](super::doctor::compute_db_schema_drift) and
/// `pull --dry-run`) BOTH sides are complete introspections, so a `definition`
/// index IS authoritative and a dropped/changed one is reported as real drift via
/// [`indexes_equivalent`]. Plain (`definition: None`) indexes are diffed
/// identically in both modes — a model may always ADD a brand-new plain index.
///
/// ## Model `#[unique]` satisfied by an existing unique index (brownfield adoption)
///
/// In a *model diff* only, a desired UNIQUE index whose name is absent from the
/// baseline is nonetheless treated as **already satisfied** when the baseline
/// carries some `unique` index (under ANY name — including a `definition`-carrying
/// constraint index a brownfield `UNIQUE` produced, e.g. `accounts_email_key`)
/// over the **exact same column set** ([`baseline_unique_index_covers`]). This is
/// the brownfield-adoption case: the user pulls `email TEXT UNIQUE`, then writes
/// the natural model `Account { id, email }` with `#[unique]` on `email`. The
/// parser emits `idx_accounts_email_unique` (a differently-named unique index over
/// `{email}`); without this recognition `diff_indexes` would emit a redundant
/// `AddIndex`, which `guard_plan`'s dedup refusal would then reject on a populated
/// table — leaving the user unable to keep the annotation. Instead the desired
/// unique index is suppressed (no `AddIndex`, and no `DropIndex` for the retained
/// baseline index), so the model resolves to a clean, empty diff. Uniqueness must
/// match: a desired unique index over `{email}` is NOT satisfied by a baseline
/// *non-unique* index over `{email}` (it still emits `AddIndex`). Authoritative
/// diffs are unaffected — a brownfield constraint index shares its name on both
/// introspected sides and already matches by name, so real drift stays intact.
/// Whether the baseline table already carries a `unique` index whose covered
/// column set is **exactly** `want_columns` (order-insensitive) — used only in the
/// model-diff path to recognize that a desired `#[unique]` index is already
/// enforced by a differently-named brownfield constraint/unique index.
///
/// ## Why exact **key**-set-equality on a FULL, NON-PARTIAL index
///
/// Only a baseline unique index that actually enforces table-wide uniqueness of the
/// desired columns may suppress the `AddIndex`. Two catalog shapes look like they
/// cover the set but do **not**, and are deliberately rejected:
///
/// - A **partial** unique index (`… ON t(email) WHERE …`) enforces uniqueness only
///   for rows matching its predicate — duplicates can exist outside it — so it does
///   NOT guarantee the model's table-wide `#[unique] email`. Rejected via
///   [`Index::is_partial`].
/// - An **expression** unique index (`UNIQUE (lower(email))`) enforces uniqueness of
///   the *expression*, not the column, so it does NOT guarantee `#[unique] email`
///   either. Introspection records an expression index with an EMPTY
///   [`Index::key_columns`], which is rejected.
///
/// The comparison is therefore against the index's real **key** columns
/// ([`Index::key_columns`]), which excludes a covering index's non-key `INCLUDE`
/// columns — so `UNIQUE(a) INCLUDE(b)` (key `{a}`) satisfies `#[unique] a` but not
/// `#[unique] {a, b}`. For a plain simple index introspection leaves `key_columns`
/// empty (its key columns are exactly [`Index::columns`]); such a `definition`-less
/// index falls back to comparing `columns`. A `definition`-carrying index with an
/// empty `key_columns` is an expression index (or an older snapshot we cannot vouch
/// for) and never satisfies — the conservative direction (emit the `AddIndex`), not
/// a wrongful suppression.
fn baseline_unique_index_covers(base: &Table, want_columns: &[String]) -> bool {
    let want_set: BTreeSet<&str> = want_columns.iter().map(String::as_str).collect();
    // A single-column baseline `column.unique = true` fully enforces uniqueness of
    // that column. This covers the SQLite brownfield inline-`col TEXT UNIQUE` case:
    // its constraint auto-index (`sqlite_autoindex_*`) is deliberately folded into the
    // column flag (not recorded as an `Index` — its name is un-creatable/un-droppable,
    // see `introspect::sqlite::collapse_indexes`), so the flag is the signal that the
    // model's `#[unique]` is already satisfied (no redundant `AddIndex` that
    // `guard_plan` would refuse on a populated table). On Postgres the constraint ALSO
    // produces a retained unique index, so this clause is redundant-but-correct there.
    if want_columns.len() == 1
        && base
            .columns
            .iter()
            .any(|c| c.unique && c.name == want_columns[0])
    {
        return true;
    }
    base.indexes.iter().any(|idx| {
        if !idx.unique || idx.is_partial {
            return false;
        }
        // Effective KEY columns: an explicit `key_columns` (recorded for every
        // `definition`-carrying index; empty ⇒ expression key ⇒ reject) wins;
        // otherwise, for a plain `definition`-less index, its `columns` ARE its key
        // columns. A `definition`-carrying index with no recorded key columns cannot
        // be vouched for and is rejected.
        let key: BTreeSet<&str> = if !idx.key_columns.is_empty() {
            idx.key_columns.iter().map(String::as_str).collect()
        } else if idx.definition.is_none() {
            idx.columns.iter().map(String::as_str).collect()
        } else {
            return false;
        };
        key == want_set
    })
}

/// The single suppression predicate shared by **both** [`diff_indexes`] branches
/// (the same-name match and the desired-only `AddIndex`), so they can never
/// drift: a desired UNIQUE index is already satisfied — and may be suppressed —
/// only when SOME baseline index provides **full** coverage, i.e. a non-partial,
/// non-expression unique index over exactly its key columns (see
/// [`baseline_unique_index_covers`]). A non-unique desired index is never
/// suppressed by this rule, and a merely same-named baseline index that is
/// partial, an expression index (empty key columns), or keyed on a different
/// column set does **not** count as coverage.
fn baseline_satisfies_desired_unique(base: &Table, want_idx: &Index) -> bool {
    want_idx.unique && baseline_unique_index_covers(base, &want_idx.columns)
}

/// The full (non-partial) unique KEY column set of `idx`, or `None` when `idx` is not
/// a vouchable full-unique index (non-unique, partial, or an expression key with no
/// recorded key columns). Mirrors the key resolution in
/// [`baseline_unique_index_covers`].
fn full_unique_key_columns(idx: &Index) -> Option<BTreeSet<&str>> {
    if !idx.unique || idx.is_partial {
        return None;
    }
    if !idx.key_columns.is_empty() {
        Some(idx.key_columns.iter().map(String::as_str).collect())
    } else if idx.definition.is_none() {
        Some(idx.columns.iter().map(String::as_str).collect())
    } else {
        None
    }
}

/// Whether a baseline-only index `base_idx` (in a MODEL diff) is the covering index
/// for a desired `#[unique]` requirement whose own `AddIndex` was suppressed as
/// already-satisfied — i.e. the SAME uniqueness enforced under a DIFFERENT name (a
/// pulled `accounts_email_uq` vs the model's `idx_accounts_email_unique`). Such an
/// index must be RETAINED: dropping it would remove the only enforcement while the
/// model's matching `AddIndex` stays suppressed. The symmetric counterpart to
/// [`baseline_satisfies_desired_unique`] (which suppresses the add side).
fn base_index_covers_suppressed_model_unique(base: &Table, base_idx: &Index, want: &Table) -> bool {
    let Some(base_key) = full_unique_key_columns(base_idx) else {
        return false;
    };
    want.indexes.iter().any(|w| {
        // A same-named desired index is matched by name (not suppressed by coverage),
        // so only a DIFFERENTLY-named desired unique over the same key set counts.
        w.unique
            && !base.indexes.iter().any(|b| b.name == w.name)
            && full_unique_key_columns(w).is_some_and(|wk| wk == base_key)
    })
}

fn diff_indexes(
    table: &str,
    base: &Table,
    want: &Table,
    skipped: &BTreeSet<String>,
    opts: DiffOptions,
    backend: Backend,
    changes: &mut Vec<SchemaChange>,
) {
    let base_by_name: BTreeMap<&str, &Index> =
        base.indexes.iter().map(|i| (i.name.as_str(), i)).collect();
    let want_by_name: BTreeMap<&str, &Index> =
        want.indexes.iter().map(|i| (i.name.as_str(), i)).collect();
    // Columns that this diff DROPS (present in the baseline, absent from the desired
    // side, and not a parser-skipped column). An index — even a retained one — that
    // depends on such a column CANNOT survive the drop (SQLite rejects DROP COLUMN on
    // a referenced column), so it must be dropped BEFORE the column (`DropIndex` is
    // ordered ahead of `DropColumn`).
    let want_col_names: BTreeSet<&str> = want.columns.iter().map(|c| c.name.as_str()).collect();
    let dropped_columns: Vec<&str> = base
        .columns
        .iter()
        .map(|c| c.name.as_str())
        .filter(|n| !want_col_names.contains(n) && !skipped.contains(*n))
        .collect();

    for want_idx in &want.indexes {
        match base_by_name.get(want_idx.name.as_str()) {
            None => {
                // In a model diff (`!definitions_authoritative`), a desired UNIQUE
                // index whose column set is already enforced by an existing baseline
                // unique index — under any name, including a `definition`-carrying
                // constraint index a brownfield `UNIQUE` produced — is already
                // satisfied. The differently-named baseline index enforces exactly the
                // uniqueness the model's `#[unique]` asks for, so an `AddIndex` here
                // would be redundant and would trip `guard_plan`'s
                // unique-index-on-populated-table dedup refusal, blocking the user from
                // ever keeping the annotation. Suppress it, and leave the baseline index
                // in place with no `DropIndex`. Matching is by exact column set (see
                // [`baseline_unique_index_covers`]). Authoritative diffs are untouched:
                // a brownfield constraint index has the same name on both sides and
                // already matches by name, so real drift stays detected.
                if !opts.definitions_authoritative
                    && baseline_satisfies_desired_unique(base, want_idx)
                {
                    continue;
                }
                changes.push(SchemaChange::AddIndex {
                    table: table.to_owned(),
                    index: want_idx.clone(),
                });
            }
            Some(base_idx) => {
                // A same-named pair where EITHER carries a `definition`: in a model
                // diff the desired side cannot express the definition, so retain
                // the baseline index (emit nothing) rather than emit a destructive
                // DropIndex + plain replacement. In an introspection diff both
                // sides are authoritative, so fall through to the equivalence check.
                let involves_definition =
                    base_idx.definition.is_some() || want_idx.definition.is_some();
                if involves_definition && !opts.definitions_authoritative {
                    // Model diff: the desired side cannot express B's definition,
                    // so the same-named definition-carrying baseline index B is
                    // retained — the drop loop below skips a name still present in
                    // `want`. But a unique D whose uniqueness B does not fully cover
                    // — B is partial, an expression index with empty key columns, or
                    // keyed on a different column set — leaves the model's table-wide
                    // `#[unique]` unenforced even though a conventionally-named index
                    // exists. Emit `AddIndex(D)` so the full unique index is created
                    // alongside the retained B; suppress D only when some baseline
                    // index fully covers it, or D is non-unique.
                    if want_idx.unique && !baseline_satisfies_desired_unique(base, want_idx) {
                        changes.push(SchemaChange::AddIndex {
                            table: table.to_owned(),
                            index: want_idx.clone(),
                        });
                    }
                    continue;
                }
                if !indexes_equivalent(base_idx, want_idx) {
                    changes.push(SchemaChange::DropIndex {
                        table: table.to_owned(),
                        index: (*base_idx).clone(),
                    });
                    changes.push(SchemaChange::AddIndex {
                        table: table.to_owned(),
                        index: want_idx.clone(),
                    });
                }
            }
        }
    }

    for base_idx in &base.indexes {
        if want_by_name.contains_key(base_idx.name.as_str())
            || base_idx.columns.iter().any(|c| skipped.contains(c))
        {
            continue;
        }
        // SQLite only: an index that depends on a column being dropped must be dropped
        // first — even a retained `definition` one the model cannot express — or it would
        // reference a missing column and SQLite would reject the `DROP COLUMN`. This
        // overrides the retention rule below; its down leg recreates the index verbatim,
        // after the column is re-added, so the rollback is faithful. Postgres is excluded:
        // it cascade-drops the dependent index on `DROP COLUMN` and restores it on
        // rollback via `retained_indexes_depending_on_any`, so an explicit `DropIndex`
        // there would double-drop and break that mechanism.
        let orphaned_by_column_drop = backend == Backend::Sqlite
            && dropped_columns
                .iter()
                .any(|c| index_depends_on_column(base_idx, c, backend));
        // Retain, never DropIndex, in a model diff — and only when the index is not being
        // orphaned by a SQLite column drop — when either:
        //   (a) it carries a `definition` the model DSL cannot express: an expression,
        //       partial, or constraint-owned index; or
        //   (b) it is a plain unique index covering a model `#[unique]` whose own
        //       `AddIndex` was suppressed as already satisfied — the same uniqueness under
        //       a different name, such as a pulled `accounts_email_uq` against the model's
        //       `idx_accounts_email_unique`. Dropping it would remove the only uniqueness
        //       enforcement with no replacement, a silent data-integrity loss. This is the
        //       symmetric counterpart to the add branch's suppression.
        // In an introspection diff both sides are authoritative and indexes match by name,
        // so neither retention applies and a genuinely dropped index drops.
        let retain = !opts.definitions_authoritative
            && !orphaned_by_column_drop
            && (base_idx.definition.is_some()
                || base_index_covers_suppressed_model_unique(base, base_idx, want));
        if retain {
            continue;
        }
        changes.push(SchemaChange::DropIndex {
            table: table.to_owned(),
            index: base_idx.clone(),
        });
    }
}

/// Diff a table's checks — **add only** (rule A: a baseline-only check is never
/// dropped, because the parser cannot fabricate enum checks and so cannot prove
/// the check was removed).
fn diff_checks(table: &str, base: &Table, want: &Table, changes: &mut Vec<SchemaChange>) {
    for want_check in &want.checks {
        if !base.checks.iter().any(|c| c == want_check) {
            changes.push(SchemaChange::AddCheck {
                table: table.to_owned(),
                check: want_check.clone(),
            });
        }
    }
}

/// The set of column names the parser skipped for `table` (rule E): a
/// [`SchemaDiagnostic`](crate::schema::parse::SchemaDiagnostic) whose resolved
/// table name equals `table` contributes its field name. Such a baseline column
/// is "present but unmodelled" and must not be diffed as a drop.
///
/// The match is on the diagnostic's resolved `table` (the `#[model(table =
/// "...")]` override or the convention name), recorded at parse time — never a
/// re-derivation of the convention name from `model`, which would miss a custom
/// table name and let a real baseline column be diffed as a data-losing drop.
fn skipped_columns(table: &str, desired: &ParsedSchema) -> std::collections::BTreeSet<String> {
    desired
        .diagnostics
        .iter()
        .filter(|d| d.table == table)
        .map(|d| d.field.clone())
        .collect()
}

/// Infer the plan's backend from the (provider-locked) tables. The caller
/// guarantees both sides share a backend via `ensure_backend_matches`; defaulting
/// to Postgres only matters for the (backendless) empty-vs-empty case.
fn plan_backend(baseline: &[Table], desired: &ParsedSchema) -> Backend {
    desired
        .tables
        .first()
        .or_else(|| baseline.first())
        .map_or(Backend::Postgres, |t| t.backend)
}

// ---------------------------------------------------------------------------
// Policy guard
// ---------------------------------------------------------------------------

/// The refusal for the first [`SchemaChange::ForeignKeyChange`] in `plan`.
fn foreign_key_change_error(plan: &MigrationPlan) -> Option<DiffError> {
    plan.changes.iter().find_map(|c| match c {
        SchemaChange::ForeignKeyChange {
            table,
            column,
            from,
            to,
        } => Some(DiffError::ForeignKeyChange {
            table: table.clone(),
            column: column.clone(),
            from: from.clone(),
            to: to.clone(),
        }),
        _ => None,
    })
}

/// Policy guard, run AFTER [`diff_schema`] by the command. Refuses a plan that is
/// structurally computable but unsafe to emit unless permitted.
///
/// Guard order (most specific / most dangerous first, so the user sees the most
/// actionable message): **`PrimaryKeyChange` → `ForeignKeyChange` →
/// `PossibleRename` → `Destructive`**. `--allow-destructive` overrides the rename
/// and destructive tiers; a primary-key change and a foreign-key retarget have no
/// override.
///
/// # Errors
///
/// Returns a [`DiffError`] describing the first refusal; `Ok(())` for an
/// emittable plan (including the empty no-op plan).
pub fn guard_plan(plan: &MigrationPlan, opts: DiffOptions) -> Result<(), DiffError> {
    // 0. An unsafe `#[renamed_from]` hint — no override.
    find_rename_conflict(plan).map_or(Ok(()), Err)?;

    // 1. Primary-key change — no override.
    if let Some(table) = plan.changes.iter().find_map(|c| match c {
        SchemaChange::PrimaryKeyChange { table } => Some(table.clone()),
        _ => None,
    }) {
        return Err(DiffError::PrimaryKeyChange { table });
    }

    // 2. Foreign-key change — no override (there is no safe drop+recreate).
    if let Some(err) = foreign_key_change_error(plan) {
        return Err(err);
    }

    // 2a. Identity-generation change — no override (needs ADD/DROP/SET GENERATED,
    //     out of scope this slice). Only produced by an authoritative diff.
    if let Some(err) = find_identity_change_block(plan) {
        return Err(err);
    }

    // 2b. Foreign key added to a pre-existing column — no override. A baseline
    //     `references: None` is *unknown* (the parser cannot see an association
    //     FK), so the DB may already carry the `<table>_<column>_fkey` constraint;
    //     emitting `ADD CONSTRAINT` would collide. A new FK column (an `AddColumn`
    //     with an inline `REFERENCES`) is safe and never reaches this marker.
    if let Some((table, column)) = plan.changes.iter().find_map(|c| match c {
        SchemaChange::AddForeignKeyToExistingColumn { table, column } => {
            Some((table.clone(), column.clone()))
        }
        _ => None,
    }) {
        return Err(DiffError::AddForeignKeyToPreexistingColumn { table, column });
    }

    // 2c. Create of a table whose model has parser-skipped field(s) — no override.
    //     The parsed table omits the skipped column(s), so emitting `CREATE TABLE`
    //     from it would produce DDL missing a column the generated model queries →
    //     runtime "column does not exist". Incomplete DDL is as broken as
    //     unappliable SQL, so it refuses and directs to a manual migration. Only a
    //     table being CREATED carries this marker (an existing table's skipped
    //     column is retained by the drop suppressions, not this refusal).
    if let Some((table, fields)) = plan.changes.iter().find_map(|c| match c {
        SchemaChange::CreateTableBlockedBySkippedField { table, fields } => {
            Some((table.clone(), fields.clone()))
        }
        _ => None,
    }) {
        return Err(DiffError::CreateTableWithSkippedField { table, fields });
    }

    // 3. Drop of a table a retained table still references — no override (even
    //    --allow-destructive cannot break another table's integrity).
    if let Some(err) = find_inbound_fk_block(plan) {
        return Err(err);
    }

    // 4. Non-implicit column type conversion (pg) — no override; the bare
    //    `ALTER COLUMN ... TYPE` is unappliable without a `USING` clause.
    if let Some(err) = find_non_implicit_conversion(plan) {
        return Err(err);
    }

    // 4b. Column type change on an FK-bound column — no override. PG rejects
    //     `ALTER COLUMN ... TYPE` on a column bound by a foreign key (as either the
    //     referencing column or the referenced key), and this engine has no
    //     drop+recreate path for the constraint. Composes on top of guard 4: it
    //     catches even the implicit widenings that guard allows.
    if let Some(err) = find_fk_type_change_block(plan) {
        return Err(err);
    }

    // 4c. Generated identifier over Postgres's 63-byte limit (or a post-truncation
    //     collision) — no override. PG silently truncates identifiers to 63 bytes,
    //     so an over-long FK-constraint / index name is renamed on apply and can
    //     collide with a sibling generated name (duplicate-relation error). Unappliable
    //     SQL, not merely lossy, so it always refuses. Postgres-only (SQLite does not
    //     truncate). See the module docs' 63-byte-limit section.
    if let Some(err) = find_identifier_limit_violation(plan) {
        return Err(err);
    }

    // 5. Possible rename — a single table that both dropped and added columns.
    //    Overridable, so it is only enforced when destructive changes are not
    //    allowed. Deliberately checked *before* the required-column guard below so
    //    a rename-shaped drop+add reports the more-actionable `#[renamed_from]`
    //    guidance rather than "add a default".
    if !opts.allow_destructive
        && let Some(err) = find_possible_rename(plan)
    {
        return Err(err);
    }

    // 6. Add of a required column (NOT NULL, no default) to an existing table — no
    //    override. Postgres validates the NOT NULL against existing rows the instant the
    //    column is added, so `ADD COLUMN ... NOT NULL` fails on any non-empty table, and
    //    the offline engine has no backfill value to synthesize, so it refuses rather
    //    than emit an unappliable migration. This matches only `AddColumn`, altering an
    //    existing baseline table: a NOT NULL, no-default column inlined in a brand-new
    //    `CreateTable` is empty-table-safe and is never matched. It is not destructive,
    //    so it always refuses whatever `--allow-destructive` says — checked in both
    //    branches, since the short-circuit below is only reached after this guard.
    if let Some((table, column)) = plan.changes.iter().find_map(|c| match c {
        SchemaChange::AddColumn { table, column }
            if !column.nullable && column.default.is_none() =>
        {
            Some((table.clone(), column.name.clone()))
        }
        _ => None,
    }) {
        return Err(DiffError::RequiredColumnWithoutDefault { table, column });
    }

    // 6b. `SET NOT NULL` on an existing nullable column — no override. Postgres
    //     validates the constraint against every existing row the instant the
    //     ALTER runs, so it fails on any pre-existing NULL; the offline engine
    //     has no backfill value to synthesize. The exact sibling of the
    //     required-column refusal above. It is not destructive, so it always
    //     refuses, regardless of `--allow-destructive` (checked here, before the
    //     `allow_destructive` short-circuit below). The inverse `DropNotNull`
    //     (nullable-ing a column) is always safe and is never matched here.
    if let Some((table, column)) = plan.changes.iter().find_map(|c| match c {
        SchemaChange::SetNotNull { table, column } => Some((table.clone(), column.clone())),
        _ => None,
    }) {
        return Err(DiffError::SetNotNullRequiresBackfill { table, column });
    }

    // 6c. A unique index added to a pre-existing table where all its indexed columns
    //     already existed — no override. `CREATE UNIQUE INDEX` validates uniqueness
    //     against every existing row the instant it runs, so it fails on any pre-existing
    //     duplicate, and the offline engine cannot dedup the data. This is the
    //     index-level sibling of the `SET NOT NULL` refusal above. It is not destructive,
    //     so it always refuses whatever `--allow-destructive` says, checked before the
    //     short-circuit below. A unique index on a brand-new, empty `CreateTable` rides
    //     inline on that change and never reaches `AddIndex`; a unique index touching a
    //     newly-added column, whose existing rows are all NULL and so distinct, and any
    //     non-unique index are safe and never matched.
    if let Some(err) = find_unique_index_requires_dedup(plan) {
        return Err(err);
    }

    if opts.allow_destructive {
        return Ok(());
    }

    // 7. Destructive drops.
    let destructive_ops: Vec<DestructiveOp> = plan
        .changes
        .iter()
        .filter_map(|c| match c {
            SchemaChange::DropTable(t) => Some(DestructiveOp::Table(t.name.clone())),
            SchemaChange::DropColumn { table, column } => Some(DestructiveOp::Column {
                table: table.clone(),
                column: column.name.clone(),
            }),
            _ => None,
        })
        .collect();
    if !destructive_ops.is_empty() {
        let summary = destructive_ops
            .iter()
            .map(|op| match op {
                DestructiveOp::Table(t) => format!("DROP TABLE {t}"),
                DestructiveOp::Column { table, column } => {
                    format!("DROP COLUMN {table}.{column}")
                }
            })
            .collect::<Vec<_>>()
            .join("; ");
        return Err(DiffError::Destructive {
            summary,
            ops: destructive_ops,
        });
    }

    Ok(())
}

/// The [`DiffError::RenameConflict`] refusal for the first
/// [`SchemaChange::RenameConflict`] marker in `plan`, if any.
fn find_rename_conflict(plan: &MigrationPlan) -> Option<DiffError> {
    plan.changes.iter().find_map(|c| match c {
        SchemaChange::RenameConflict { table, reason } => Some(DiffError::RenameConflict {
            table: table.clone(),
            reason: reason.clone(),
        }),
        _ => None,
    })
}

/// The [`DiffError::IdentityChange`] refusal for the first
/// [`SchemaChange::IdentityChange`] marker in `plan`, if any.
fn find_identity_change_block(plan: &MigrationPlan) -> Option<DiffError> {
    plan.changes.iter().find_map(|c| match c {
        SchemaChange::IdentityChange { table, column } => Some(DiffError::IdentityChange {
            table: table.clone(),
            column: column.clone(),
        }),
        _ => None,
    })
}

/// The [`DiffError::DropTableInboundReference`] refusal for the first
/// [`SchemaChange::DropTableBlockedByInboundFk`] marker in `plan`, if any.
fn find_inbound_fk_block(plan: &MigrationPlan) -> Option<DiffError> {
    plan.changes.iter().find_map(|c| match c {
        SchemaChange::DropTableBlockedByInboundFk {
            table,
            referencing_table,
            referencing_column,
        } => Some(DiffError::DropTableInboundReference {
            table: table.clone(),
            referencing_table: referencing_table.clone(),
            referencing_column: referencing_column.clone(),
        }),
        _ => None,
    })
}

/// The [`DiffError::TypeChangeOnForeignKeyColumn`] refusal for the first
/// [`SchemaChange::AlterColumnTypeBlockedByFk`] marker in `plan`, if any.
/// Postgres-only: on `SQLite` an FK-bound type change is safely expressed by the
/// table-recreate path (the plan still carries the real `AlterColumnType`
/// alongside the blocked marker, and the rebuild applies it while preserving the
/// inline `REFERENCES`), so the guard stays out of the `SQLite` boundary.
fn find_fk_type_change_block(plan: &MigrationPlan) -> Option<DiffError> {
    if plan.backend != Backend::Postgres {
        return None;
    }
    plan.changes.iter().find_map(|c| match c {
        SchemaChange::AlterColumnTypeBlockedByFk { table, column } => {
            Some(DiffError::TypeChangeOnForeignKeyColumn {
                table: table.clone(),
                column: column.clone(),
            })
        }
        _ => None,
    })
}

/// The [`DiffError::UniqueIndexRequiresDedup`] refusal for the first unique
/// `AddIndex` in `plan` whose indexed columns ALL pre-existed on the table — none
/// is a column being added in this same plan.
///
/// An `AddIndex` is produced by [`diff_indexes`] only for a both-present
/// (pre-existing) table; a brand-new table's indexes ride inline on its
/// [`SchemaChange::CreateTable`] and never reach this path — so a unique
/// `AddIndex` already implies the table pre-exists and may hold rows. It is unsafe
/// (existing rows may contain duplicates that fail `CREATE UNIQUE INDEX`) UNLESS
/// at least one indexed column is newly added in this plan (an `AddColumn`): a
/// new column is NULL in every existing row, and Postgres treats NULLs as
/// distinct in a unique index, so the existing rows cannot conflict.
fn find_unique_index_requires_dedup(plan: &MigrationPlan) -> Option<DiffError> {
    let added: BTreeSet<(&str, &str)> = plan
        .changes
        .iter()
        .filter_map(|c| match c {
            SchemaChange::AddColumn { table, column } => {
                Some((table.as_str(), column.name.as_str()))
            }
            _ => None,
        })
        .collect();
    plan.changes.iter().find_map(|c| match c {
        SchemaChange::AddIndex { table, index } if index.unique => {
            let touches_new_column = index
                .columns
                .iter()
                .any(|col| added.contains(&(table.as_str(), col.as_str())));
            (!touches_new_column).then(|| DiffError::UniqueIndexRequiresDedup {
                table: table.clone(),
                index: index.name.clone(),
            })
        }
        _ => None,
    })
}

/// Postgres's identifier byte limit (`NAMEDATALEN - 1`). Names longer than this are
/// silently truncated on apply.
const PG_MAX_IDENTIFIER_BYTES: usize = 63;

/// The identifiers this engine generates for a plan, in change order: the
/// `{table}_{column}_fkey` FK-constraint name for each [`SchemaChange::AddForeignKey`]
/// (rendered as `ADD CONSTRAINT` up / `DROP CONSTRAINT` down, both from this same
/// derivation), and every index name emitted as a top-level `CREATE INDEX` — the
/// [`SchemaChange::AddIndex`] index name plus each index on a [`SchemaChange::CreateTable`].
/// These are exactly the names Postgres would truncate to 63 bytes.
fn generated_identifiers(plan: &MigrationPlan) -> Vec<String> {
    let mut names = Vec::new();
    for change in &plan.changes {
        match change {
            SchemaChange::AddForeignKey { table, column, .. } => {
                // The FK-constraint name is engine-generated and safe to rename, so it
                // goes through `bounded_pg_identifier` (matching the `ADD`/`DROP
                // CONSTRAINT` emitters). A short name is returned unchanged; only an
                // over-limit one is truncate+hashed — so this never trips the guard.
                names.push(bounded_pg_identifier(&format!("{table}_{column}_fkey")));
            }
            SchemaChange::AddIndex { index, .. } | SchemaChange::RenameIndex { index, .. } => {
                names.push(index.name.clone());
            }
            SchemaChange::CreateTable(table) => {
                names.extend(table.indexes.iter().map(|i| i.name.clone()));
            }
            _ => {}
        }
    }
    names
}

/// `name` truncated to at most `max` bytes, on a UTF-8 char boundary.
fn truncate_to_bytes(name: &str, max: usize) -> &str {
    if name.len() <= max {
        return name;
    }
    let mut end = max;
    while !name.is_char_boundary(end) {
        end -= 1;
    }
    &name[..end]
}

/// `name` truncated to Postgres's 63-byte identifier limit, on a UTF-8 char boundary
/// (PG truncates by byte; generated names are ASCII, but stay codepoint-safe anyway).
fn truncate_pg_identifier(name: &str) -> &str {
    truncate_to_bytes(name, PG_MAX_IDENTIFIER_BYTES)
}

/// A short, deterministic 8-hex-char digest of `raw`, for collision-resistant
/// identifier suffixing.
///
/// Uses a hand-rolled FNV-1a 64-bit hash (fully specified, dependency-free) rather
/// than `DefaultHasher`, whose output is not guaranteed stable across Rust versions —
/// this schema emitter must derive the same suffix on every toolchain, and the up and
/// down renderers must agree.
fn short_identifier_hash(raw: &str) -> String {
    let digest = fnv1a_64(raw.as_bytes());
    format!("{digest:016x}")[..8].to_owned()
}

/// FNV-1a 64-bit hash of `bytes` (offset basis `0xcbf29ce484222325`, prime
/// `0x100000001b3`), fully specified so the digest is deterministic everywhere.
const fn fnv1a_64(bytes: &[u8]) -> u64 {
    let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
    let prime: u64 = 0x0000_0100_0000_01b3;
    let mut i = 0;
    while i < bytes.len() {
        hash ^= bytes[i] as u64;
        hash = hash.wrapping_mul(prime);
        i += 1;
    }
    hash
}

/// A Postgres-safe (`≤ 63`-byte) identifier for `raw`.
///
/// Returns `raw` unchanged when it already fits, so short names — the common case —
/// are byte-stable. An over-limit name is truncated and suffixed with
/// `_<8-hex-hash>` of the **full untruncated** name, yielding a deterministic,
/// collision-resistant identifier that always fits. Applied only to
/// engine-generated FK-constraint names (safe to rename), never to parser-provided
/// index names.
fn bounded_pg_identifier(raw: &str) -> String {
    if raw.len() <= PG_MAX_IDENTIFIER_BYTES {
        return raw.to_owned();
    }
    let hash = short_identifier_hash(raw);
    // suffix is "_" + 8 hex chars = 9 bytes; leave room for it within the 63 limit.
    let head_budget = PG_MAX_IDENTIFIER_BYTES - (hash.len() + 1);
    let head = truncate_to_bytes(raw, head_budget);
    format!("{head}_{hash}")
}

/// The [`DiffError::GeneratedIdentifierTooLong`] refusal when the plan generates an
/// FK-constraint or index identifier over Postgres's 63-byte limit, two distinct
/// generated names that collide after truncation to 63 bytes, or two generated names
/// that are *exactly* identical. Postgres-only — `SQLite` does not truncate identifiers
/// to a short limit, so the truncation hazard does not apply there (an exact-duplicate
/// relation name would still be rejected, but the parser only produces the colliding
/// `idx_<table>_<field>_unique` shape for a Postgres plan).
fn find_identifier_limit_violation(plan: &MigrationPlan) -> Option<DiffError> {
    if plan.backend != Backend::Postgres {
        return None;
    }
    // A rename target comes from the models, so it has no length limit there.
    if let Some(name) = plan.changes.iter().find_map(|c| match c {
        SchemaChange::RenameTable { to, .. } | SchemaChange::RenameColumn { to, .. }
            if to.len() > PG_MAX_IDENTIFIER_BYTES =>
        {
            Some(to.clone())
        }
        _ => None,
    }) {
        return Some(DiffError::GeneratedIdentifierTooLong { name });
    }
    let mut by_truncated: BTreeMap<String, String> = BTreeMap::new();
    for name in generated_identifiers(plan) {
        // Over the limit: PG truncates it silently — refuse outright (this alone
        // catches every *distinct*-name post-truncation collision, since such a
        // collision requires at least one name to exceed 63 bytes).
        if name.len() > PG_MAX_IDENTIFIER_BYTES {
            return Some(DiffError::GeneratedIdentifierTooLong { name });
        }
        // Any collision on the on-apply (truncated) identifier is a duplicate-relation
        // hazard: PG accepts the first `CREATE INDEX`/`ADD CONSTRAINT` and rejects the
        // second. Because over-limit names are refused above, every name here truncates
        // to itself — so this fires on an *exact duplicate* generated name (e.g. a
        // `#[unique] foo` field plus a separate field named `foo_unique`, both yielding
        // `idx_<table>_foo_unique`), which PG would reject as a duplicate relation. This
        // must NOT dedup or skip the `prev == name` case: identical names are precisely
        // the hazard.
        if by_truncated
            .insert(truncate_pg_identifier(&name).to_owned(), name.clone())
            .is_some()
        {
            return Some(DiffError::GeneratedIdentifierTooLong { name });
        }
    }
    None
}

/// The [`DiffError::PossibleRename`] refusal for the first both-present table that
/// both dropped and added column(s) — the ambiguous drop+add that might be a
/// rename. Grouped in a `BTreeMap` so the reported table is deterministic
/// (sorted). The caller only consults this when `--allow-destructive` is off.
fn find_possible_rename(plan: &MigrationPlan) -> Option<DiffError> {
    let mut per_table: BTreeMap<String, (Vec<String>, Vec<String>)> = BTreeMap::new();
    for change in &plan.changes {
        match change {
            SchemaChange::DropColumn { table, column } => {
                per_table
                    .entry(table.clone())
                    .or_default()
                    .0
                    .push(column.name.clone());
            }
            SchemaChange::AddColumn { table, column } => {
                per_table
                    .entry(table.clone())
                    .or_default()
                    .1
                    .push(column.name.clone());
            }
            _ => {}
        }
    }
    per_table
        .into_iter()
        .find(|(_, (dropped, added))| !dropped.is_empty() && !added.is_empty())
        .map(|(table, (dropped, added))| DiffError::PossibleRename {
            table,
            dropped,
            added,
        })
}

/// The [`DiffError::NonImplicitTypeConversion`] refusal for the first
/// non-implicit `AlterColumnType` in `plan`, if any. Postgres-only: on `SQLite`
/// every `AlterColumnType` is realised by the table-recreate path (which restates
/// the whole column shape, so an implicit-vs-explicit cast distinction does not
/// apply), so the classifier stays out of the `SQLite` boundary.
fn find_non_implicit_conversion(plan: &MigrationPlan) -> Option<DiffError> {
    if plan.backend != Backend::Postgres {
        return None;
    }
    plan.changes.iter().find_map(|c| match c {
        SchemaChange::AlterColumnType {
            table,
            column,
            from,
            to,
        } if !is_implicit_pg_type_cast(from, to) => Some(DiffError::NonImplicitTypeConversion {
            table: table.clone(),
            column: column.clone(),
            from: from.sql_type(plan.backend),
            to: to.sql_type(plan.backend),
        }),
        _ => None,
    })
}

/// True when PG casts `from` → `to` **implicitly**, without a `USING`
/// clause — the only type changes this slice renders as a bare
/// `ALTER COLUMN ... TYPE`. Deliberately conservative: only the lossless numeric
/// widenings PG auto-casts (`int4` → `int8`, `float4` → `float8`). Every other
/// pair (e.g. `TEXT` → `INTEGER`/`UUID`, `BOOLEAN` → `INTEGER`, `NUMERIC`
/// narrowing) needs a manual `USING` migration and is refused by [`guard_plan`].
/// The IR does not distinguish `TEXT` from a `VARCHAR` family, so no string
/// widening pair exists to admit here.
const fn is_implicit_pg_type_cast(from: &ColumnType, to: &ColumnType) -> bool {
    matches!(
        (from, to),
        (ColumnType::Int32, ColumnType::Int64) | (ColumnType::Float32, ColumnType::Float64)
    )
}

// ---------------------------------------------------------------------------
// SQL emission (pg + sqlite)
// ---------------------------------------------------------------------------

/// Full desired + baseline table shapes, keyed by table name.
///
/// The `SQLite` table-recreate path needs a table's complete shape (all columns,
/// PK, checks, indexes), which the per-change [`SchemaChange`] deltas don't carry,
/// so the schema-aware [`emit_up_sql_with_context`] / [`emit_down_sql_with_context`]
/// entry points thread it in. Postgres never rebuilds and so ignores it.
#[derive(Debug, Clone, Default)]
pub struct SchemaContext {
    /// Desired (post-migration) tables, by name — the "new shape" for an up rebuild.
    pub desired: BTreeMap<String, Table>,
    /// Baseline (pre-migration) tables, by name — the "new shape" for a down rebuild.
    pub baseline: BTreeMap<String, Table>,
    /// `(table, column)` of each decimal column that the parser skipped (a bad
    /// `#[decimal_shape]`, issue #2598). A `SQLite` rebuild of its table refuses.
    pub skipped_decimals: BTreeSet<(String, String)>,
}

impl SchemaContext {
    /// Build a context from the desired + baseline table lists (as passed to
    /// [`diff_schema`]).
    #[must_use]
    pub fn from_tables(desired: &[Table], baseline: &[Table]) -> Self {
        Self {
            desired: desired
                .iter()
                .map(|t| (t.name.clone(), t.clone()))
                .collect(),
            baseline: baseline
                .iter()
                .map(|t| (t.name.clone(), t.clone()))
                .collect(),
            skipped_decimals: BTreeSet::new(),
        }
    }

    /// Record the decimal columns that the parser skipped in `desired` (issue
    /// #2598). The rebuild cannot write their `CHECK`.
    #[must_use]
    pub fn with_skipped_decimals(mut self, desired: &ParsedSchema) -> Self {
        self.skipped_decimals = desired
            .diagnostics
            .iter()
            .filter(|d| {
                matches!(
                    ColumnType::from_rust_type(&d.rust_type),
                    Some(ColumnType::Decimal { .. })
                )
            })
            .map(|d| (d.table.clone(), d.field.clone()))
            .collect();
        self
    }
}

/// Render the plan's forward SQL without a schema context.
///
/// Sufficient for Postgres and the portable `SQLite` subset. If the plan needs a
/// `SQLite` table rebuild, prefer [`emit_up_sql_with_context`].
///
/// # Errors
///
/// Returns [`EmitError::SqliteRebuildUnsupported`] when a `SQLite` `ALTER`-family
/// change needs a table rebuild but no shape context was supplied, or
/// [`EmitError::CyclicTableDependencies`] on an unorderable new-table FK cycle.
// Retained context-free public API (the command wiring and the SQLite rebuild path
// use the `_with_context` entry points; this signature is consumed by the parallel
// slice-6 lane and the diff tests).
#[allow(dead_code)]
pub fn emit_up_sql(plan: &MigrationPlan) -> Result<String, EmitError> {
    emit_up_sql_with_context(plan, &SchemaContext::default())
}

/// Render the plan's reverse SQL without a schema context.
///
/// # Errors
///
/// See [`emit_up_sql`].
#[allow(dead_code)]
pub fn emit_down_sql(plan: &MigrationPlan) -> Result<String, EmitError> {
    emit_down_sql_with_context(plan, &SchemaContext::default())
}

/// Render the plan's forward SQL, using `ctx` for any `SQLite` table rebuild.
///
/// Postgres emits the per-change `ALTER`-family statements directly; `SQLite`
/// coalesces every `ALTER`-family change on a table into a single table-recreate
/// block built from `ctx.desired`.
///
/// # Errors
///
/// Returns [`EmitError::SqliteRebuildUnsupported`] when a rebuild is required but
/// the table's desired/baseline shape is missing from `ctx`, or
/// [`EmitError::CyclicTableDependencies`] on an unorderable new-table FK cycle.
pub fn emit_up_sql_with_context(
    plan: &MigrationPlan,
    ctx: &SchemaContext,
) -> Result<String, EmitError> {
    match plan.backend {
        Backend::Postgres => emit_up_sql_pg(plan),
        Backend::Sqlite => emit_up_sql_sqlite(plan, ctx),
    }
}

/// Render the plan's reverse SQL, using `ctx` for any `SQLite` table rebuild.
///
/// # Errors
///
/// See [`emit_up_sql_with_context`].
pub fn emit_down_sql_with_context(
    plan: &MigrationPlan,
    ctx: &SchemaContext,
) -> Result<String, EmitError> {
    match plan.backend {
        Backend::Postgres => emit_down_sql_pg(plan, ctx),
        Backend::Sqlite => emit_down_sql_sqlite(plan, ctx),
    }
}

/// The Postgres forward path: one statement group per change, canonical up-order,
/// groups blank-line separated. Unchanged from the pg-first slice.
fn emit_up_sql_pg(plan: &MigrationPlan) -> Result<String, EmitError> {
    let ordered = up_ordered(&plan.changes)?;
    let mut groups = Vec::new();
    for change in ordered {
        let sql = emit_change_up(change, plan.backend)?;
        let sql = sql.trim_end();
        if !sql.is_empty() {
            groups.push(sql.to_owned());
        }
    }
    Ok(join_groups(&groups))
}

/// The Postgres reverse path: changes reversed and individually inverted, with
/// `-- irreversible:` markers where data cannot round-trip.
///
/// A `DropColumn` on a column covered by a RETAINED (`definition`-carrying)
/// baseline index — the expression/partial/constraint-owned indexes `schema pull`
/// preserves and the model diff never `DropIndex`'s — cascade-drops that index in
/// Postgres along with the column (the up path is a bare `ALTER TABLE … DROP
/// COLUMN`, never a failing `DROP INDEX` on a constraint-backed index). So after
/// re-adding the column the down path must recreate each such index from its
/// verbatim `definition`, else rollback silently loses the uniqueness/index. This
/// needs the baseline shapes carried in `ctx`; ordinary model-managed indexes are
/// restored via their own `DropIndex → AddIndex` inversion and are skipped here.
///
/// Recreation is **delayed and deduped**: a retained index can depend on more than
/// one dropped column (e.g. a partial index
/// `... ON t (lower(email)) WHERE tenant_id IS NOT NULL` when the model drops BOTH
/// `email` and `tenant_id`). Recreating it inline after re-adding only the *first*
/// dependent column would (a) fail — the other dependent column is still absent, so
/// Postgres rejects the `CREATE INDEX` — and (b) re-emit the same `CREATE INDEX`
/// again for the second column. So the down path first emits ALL the column
/// re-adds (and every other reversed change), then recreates each cascade-dropped
/// retained index EXACTLY ONCE, keyed by `(table, index name)`, after all of its
/// dropped columns have been restored.
fn emit_down_sql_pg(plan: &MigrationPlan, ctx: &SchemaContext) -> Result<String, EmitError> {
    let mut ordered = up_ordered(&plan.changes)?;
    ordered.reverse();
    let mut groups = Vec::new();
    // Per-table set of columns this migration drops (and the down path re-adds),
    // gathered so a multi-column retained index is recreated only after ALL its
    // dependent dropped columns are back.
    let mut dropped_by_table: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
    // The reversed renames run last, after the retained-index recreations below:
    // those use the new (renamed) names.
    let mut renames = Vec::new();
    for change in ordered {
        let sql = emit_change_down(change, plan.backend)?;
        let sql = sql.trim_end();
        if !sql.is_empty() {
            if is_rename(change) {
                renames.push(sql.to_owned());
            } else {
                groups.push(sql.to_owned());
            }
        }
        if let SchemaChange::DropColumn { table, column } = change {
            dropped_by_table
                .entry(table.clone())
                .or_default()
                .insert(column.name.clone());
        }
    }
    // Every column re-add is now emitted. Recreate each retained index whose
    // dependent-column set intersects this table's dropped columns — once per
    // (table, index name) — so a multi-column index is created exactly once, after
    // all of its dropped columns are restored.
    for (table, dropped) in &dropped_by_table {
        for idx in retained_indexes_depending_on_any(ctx, table, dropped) {
            groups.push(index_sql(table, idx).trim_end().to_owned());
        }
    }
    groups.extend(renames);
    Ok(join_groups(&groups))
}

/// The RETAINED (`definition`-carrying) baseline indexes of `table` whose
/// dependent-column set intersects `dropped_columns` — the
/// expression/partial/constraint-owned indexes Postgres cascade-drops when ANY of
/// those columns is dropped and that carry no `DropIndex` in the plan, so the down
/// migration must recreate them verbatim. Each qualifying index appears once (the
/// baseline lists each index once), so a retained index depending on two dropped
/// columns is returned — and thus recreated — exactly once. Returns empty when the
/// table is absent from `ctx.baseline` (e.g. context-free emit).
fn retained_indexes_depending_on_any<'a>(
    ctx: &'a SchemaContext,
    table: &str,
    dropped_columns: &BTreeSet<String>,
) -> Vec<&'a Index> {
    ctx.baseline.get(table).map_or_else(Vec::new, |t| {
        t.indexes
            .iter()
            .filter(|i| {
                i.definition.is_some()
                    && dropped_columns
                        .iter()
                        // pg-only rollback path (`emit_down_sql_pg`) — exact `columns`
                        // membership; the SQLite definition-scan branch never runs here.
                        .any(|c| index_depends_on_column(i, c, Backend::Postgres))
            })
            .collect()
    })
}

/// The change kinds whose `SQLite` realisation is a full table recreate: the
/// `ALTER`-family Postgres would express as `ALTER COLUMN` / `ADD CHECK` /
/// `ADD CONSTRAINT`, none of which `SQLite` supports.
fn sqlite_rebuild_tables(changes: &[SchemaChange]) -> BTreeSet<String> {
    changes
        .iter()
        .filter_map(|c| match c {
            SchemaChange::AlterColumnType { table, .. }
            | SchemaChange::DropNotNull { table, .. }
            | SchemaChange::SetDefault { table, .. }
            | SchemaChange::AddCheck { table, .. }
            | SchemaChange::AddForeignKey { table, .. } => Some(table.clone()),
            _ => None,
        })
        .collect()
}

/// The sorted, de-duplicated column names of every
/// [`SchemaChange::AlterColumnTypeBlockedByFk`] marker in `changes` that targets
/// `table`. Non-empty only when this table's `SQLite` rebuild is (partly) driven
/// by an FK-bound type change — the trigger for the FK type-consistency advisory.
fn fk_type_change_columns(changes: &[&SchemaChange], table: &str) -> Vec<String> {
    changes
        .iter()
        .filter_map(|c| match c {
            SchemaChange::AlterColumnTypeBlockedByFk { table: t, column } if t == table => {
                Some(column.clone())
            }
            _ => None,
        })
        .collect::<BTreeSet<String>>()
        .into_iter()
        .collect()
}

/// The table a change targets, for rebuild-membership tests.
const fn change_table_name(change: &SchemaChange) -> &str {
    match change {
        SchemaChange::CreateTable(t) | SchemaChange::DropTable(t) => t.name.as_str(),
        SchemaChange::RenameTable { to, .. } => to.as_str(),
        SchemaChange::RenameColumn { table, .. }
        | SchemaChange::RenameIndex { table, .. }
        | SchemaChange::RenameConflict { table, .. }
        | SchemaChange::AddColumn { table, .. }
        | SchemaChange::DropColumn { table, .. }
        | SchemaChange::AlterColumnType { table, .. }
        | SchemaChange::SetNotNull { table, .. }
        | SchemaChange::DropNotNull { table, .. }
        | SchemaChange::SetDefault { table, .. }
        | SchemaChange::AddForeignKey { table, .. }
        | SchemaChange::AddIndex { table, .. }
        | SchemaChange::DropIndex { table, .. }
        | SchemaChange::AddCheck { table, .. }
        | SchemaChange::PrimaryKeyChange { table }
        | SchemaChange::ForeignKeyChange { table, .. }
        | SchemaChange::IdentityChange { table, .. }
        | SchemaChange::DropTableBlockedByInboundFk { table, .. }
        | SchemaChange::AlterColumnTypeBlockedByFk { table, .. }
        | SchemaChange::AddForeignKeyToExistingColumn { table, .. }
        | SchemaChange::CreateTableBlockedBySkippedField { table, .. } => table.as_str(),
    }
}

/// The `SQLite` forward path. Every `ALTER`-family change on a table is coalesced
/// into a single table-recreate block (emitted once, at the first change touching
/// that table); all of that table's other changes are folded into the recreate,
/// which already targets its full desired shape. Non-rebuild tables emit through
/// the portable per-change path unchanged.
fn emit_up_sql_sqlite(plan: &MigrationPlan, ctx: &SchemaContext) -> Result<String, EmitError> {
    let ordered = up_ordered(&plan.changes)?;
    let rebuild = sqlite_rebuild_tables(&plan.changes);
    let mut emitted: BTreeSet<String> = BTreeSet::new();
    let mut groups = Vec::new();
    for change in &ordered {
        let table = change_table_name(change);
        // A rename runs as its own statement, before (up) or after (down) any
        // rebuild: the rebuild copies columns by their new names.
        if rebuild.contains(table) && !is_rename(change) {
            if emitted.insert(table.to_owned()) {
                let block = emit_sqlite_rebuild(table, ctx, &ordered, RebuildLeg::Up)?;
                let block = block.trim_end();
                if !block.is_empty() {
                    groups.push(block.to_owned());
                }
            }
            continue;
        }
        let sql = emit_change_up(change, plan.backend)?;
        let sql = sql.trim_end();
        if !sql.is_empty() {
            groups.push(sql.to_owned());
        }
    }
    Ok(join_groups(&groups))
}

/// The `SQLite` reverse path: the mirror of [`emit_up_sql_sqlite`], with each
/// rebuild block rolled back to the table's baseline shape.
fn emit_down_sql_sqlite(plan: &MigrationPlan, ctx: &SchemaContext) -> Result<String, EmitError> {
    let mut ordered = up_ordered(&plan.changes)?;
    ordered.reverse();
    let rebuild = sqlite_rebuild_tables(&plan.changes);
    let mut emitted: BTreeSet<String> = BTreeSet::new();
    let mut groups = Vec::new();
    for change in &ordered {
        let table = change_table_name(change);
        // A rename runs as its own statement, before (up) or after (down) any
        // rebuild: the rebuild copies columns by their new names.
        if rebuild.contains(table) && !is_rename(change) {
            if emitted.insert(table.to_owned()) {
                let block = emit_sqlite_rebuild(table, ctx, &ordered, RebuildLeg::Down)?;
                let block = block.trim_end();
                if !block.is_empty() {
                    groups.push(block.to_owned());
                }
            }
            continue;
        }
        let sql = emit_change_down(change, plan.backend)?;
        let sql = sql.trim_end();
        if !sql.is_empty() {
            groups.push(sql.to_owned());
        }
    }
    Ok(join_groups(&groups))
}

/// Which leg a `SQLite` rebuild renders — governs the target shape and the leading
/// marker.
#[derive(Debug, Clone, Copy)]
enum RebuildLeg {
    /// Rebuild to the post-migration shape (`ctx.baseline` + diff deltas).
    Up,
    /// Rebuild back to the baseline shape (`ctx.baseline`).
    Down,
}

/// Render the `SQLite` table-recreate block for `table` on the given leg, drawing
/// the target and source shapes from `ctx` and, on the up leg, the plan's own
/// `changes`.
///
/// The block `CREATE`s a `{table}__autumn_new` staging table with the target shape,
/// copies the columns common to both shapes, drops the old table, renames the
/// staging table into place, recreates the target shape's indexes, and validates
/// referential integrity — all wrapped in `PRAGMA foreign_keys` toggles.
///
/// The **up** leg's target shape is the rich baseline table with this table's
/// explicit diff deltas folded in ([`baseline_with_changes_applied`]) — **not** the
/// parser's partial `ctx.desired` table — so any baseline facet the parser cannot
/// see (a non-convention default, a skipped `CHECK`/enum, an association foreign
/// key) survives a rebuild triggered by an unrelated change. The **down** leg
/// targets the baseline shape directly and copies from the actual post-migration
/// shape (`baseline` + this table's diff deltas — the same value the up leg builds
/// as its target), **not** the parser's partial `ctx.desired`, so a
/// retained-but-parser-invisible column is copied back on rollback rather than
/// dropped. Both legs take the decimal precision and scale from `ctx.desired`
/// ([`with_desired_decimal_shapes`]), so the decimal `CHECK` stays.
fn emit_sqlite_rebuild(
    table: &str,
    ctx: &SchemaContext,
    changes: &[&SchemaChange],
    leg: RebuildLeg,
) -> Result<String, EmitError> {
    // The `{table}__autumn_new` staging name is not guaranteed collision-free: if a
    // real table already carries that name, the rebuild's CREATE/RENAME would clobber
    // it. Refuse rather than emit unappliable SQL.
    let staging = format!("{table}__autumn_new");
    if ctx.desired.contains_key(&staging) || ctx.baseline.contains_key(&staging) {
        return Err(EmitError::SqliteRebuildUnsupported {
            table: table.to_owned(),
            kind: "table rebuild",
            reason: format!(
                "staging table name `{staging}` collides with an existing table; \
                 rename the model to free that name"
            ),
        });
    }
    if let Some((child, action)) = rebuild_fires_child_action(table, ctx) {
        return Err(EmitError::SqliteRebuildUnsupported {
            table: table.to_owned(),
            kind: "table rebuild",
            reason: format!(
                "`{child}` references it with ON DELETE {}. The migration runs in a \
                 transaction, where `PRAGMA foreign_keys=OFF` has no effect, so the \
                 rebuild's DROP TABLE would change the rows of `{child}`. Write this \
                 change as a manual migration",
                action.sql()
            ),
        });
    }
    // A missing desired table is an error. Neither leg copies columns from the
    // desired table. The desired table supplies only the decimal precision and
    // scale.
    let desired = ctx
        .desired
        .get(table)
        .ok_or_else(|| missing_rebuild_shape(table, "desired"))?;
    let baseline = ctx
        .baseline
        .get(table)
        .ok_or_else(|| missing_rebuild_shape(table, "baseline"))?;
    let post_migration = baseline_with_changes_applied(baseline, changes, table);
    // #2598: a decimal column that the parser skipped has no desired precision
    // and scale. A `CHECK` from the baseline values can be wrong, and a `TEXT`
    // baseline gives no `CHECK`, so refuse.
    if let Some(column) = post_migration.columns.iter().find(|c| {
        ctx.skipped_decimals
            .contains(&(table.to_owned(), c.name.clone()))
            || (matches!(c.ty, ColumnType::Decimal { .. })
                && !desired.columns.iter().any(|d| d.name == c.name))
    }) {
        return Err(EmitError::SqliteRebuildUnsupported {
            table: table.to_owned(),
            kind: "table rebuild",
            reason: format!(
                "the model does not give the precision and scale of the decimal column \
                 `{}`, so the rebuild cannot write its `CHECK`. Correct the \
                 `#[decimal_shape]` of the field, or write this change as a manual migration",
                column.name
            ),
        });
    }
    let fk_cols = fk_type_change_columns(changes, table);
    match leg {
        // Build the up-leg target from the rich baseline with this table's explicit
        // diff deltas applied, preserving every unchanged baseline facet the parser
        // could not observe; the source (INSERT..SELECT) columns are the baseline's,
        // i.e. the actual existing table.
        RebuildLeg::Up => {
            let mut new_shape = post_migration;
            let mut added = with_desired_decimal_shapes(&mut new_shape, desired);
            added.extend(decimal_type_changes(changes, table, leg));
            Ok(render_sqlite_rebuild(
                table, &new_shape, baseline, leg, &fk_cols, &added,
            ))
        }
        // The down leg rolls back to the rich baseline shape. Its copy SOURCE is the
        // actual post-migration table — `baseline + this table's diff deltas`, the same
        // shape the up leg built as its target — NOT the parser's partial `ctx.desired`:
        // a retained-but-parser-invisible column (a skipped enum/association) is absent
        // from `desired`, so sourcing from it would drop that column from the rollback
        // INSERT..SELECT and lose its data. Intersecting the baseline target with the
        // post-migration source copies back every baseline column the up migration did
        // not drop, in baseline order.
        RebuildLeg::Down => {
            let mut old_shape = baseline.clone();
            let mut added = with_desired_decimal_shapes(&mut old_shape, desired);
            added.extend(decimal_type_changes(changes, table, leg));
            Ok(render_sqlite_rebuild(
                table,
                &old_shape,
                &post_migration,
                leg,
                &fk_cols,
                &added,
            ))
        }
    }
}

/// A foreign key as SQL, for example `users(id) ON DELETE CASCADE`.
fn describe_foreign_key(fk: &ForeignKey) -> String {
    format!("{}({}){}", fk.table, fk.column, fk.action_clauses())
}

/// The first column in `ctx` whose foreign key to `table` deletes or changes
/// rows on delete (`CASCADE`, `SET NULL`, `SET DEFAULT`). A rebuild drops
/// `table`, so it would fire that action. This includes a self-reference: the
/// staging table's rows reference the old table too.
fn rebuild_fires_child_action(
    table: &str,
    ctx: &SchemaContext,
) -> Option<(String, ForeignKeyAction)> {
    ctx.baseline
        .values()
        .chain(ctx.desired.values())
        .flat_map(|t| t.columns.iter().map(move |c| (t, c)))
        .find_map(|(t, c)| {
            let fk = c.references.as_ref().filter(|fk| fk.table == table)?;
            match fk.on_delete? {
                ForeignKeyAction::Restrict => None,
                action => Some((format!("{}.{}", t.name, c.name), action)),
            }
        })
}

/// Apply the table's own plan changes to its baseline shape, preserving every
/// baseline facet the diff did not explicitly change (parser-invisible defaults,
/// `CHECK`s, and so on) — the `SQLite` recreate's "new shape" for the up leg.
///
/// The slice-2 parser is deliberately partial (see the module header): it cannot
/// see a non-convention `#[default]`, some `CHECK`/enum facets, or an association
/// foreign key, and this engine has no `DropDefault` / `DropCheck` /
/// `DropForeignKey` variant. Rebuilding the whole table from the raw `ctx.desired`
/// (partial) shape would therefore silently drop any baseline facet the parser
/// could not observe. Folding the explicit diff deltas into the rich baseline
/// clone instead leaves every unchanged baseline facet intact, upholding the
/// engine's "never destroy parser-invisible state" invariant that the Postgres
/// per-change `ALTER` path already honours.
///
/// Only changes whose table is `table` are folded in; anything else (including the
/// non-emittable guard markers) is ignored.
fn baseline_with_changes_applied(
    baseline: &Table,
    changes: &[&SchemaChange],
    table: &str,
) -> Table {
    let mut shape = baseline.clone();
    for change in changes {
        if change_table_name(change) != table {
            continue;
        }
        match change {
            SchemaChange::AddColumn { column, .. } => shape.columns.push(column.clone()),
            SchemaChange::DropColumn { column, .. } => {
                shape.columns.retain(|c| c.name != column.name);
                shape.primary_key.retain(|n| n != &column.name);
                // Prune any index depending on the dropped column — including a
                // retained partial/expression index that references the column only
                // in its `definition` predicate/expression (SQLite rejects DROP
                // COLUMN on a referenced column, and this rebuild must NOT recreate an
                // orphaned index on the new table). This is the SQLite rebuild path.
                shape
                    .indexes
                    .retain(|i| !index_depends_on_column(i, &column.name, Backend::Sqlite));
            }
            SchemaChange::AlterColumnType { column, to, .. } => {
                if let Some(c) = shape.columns.iter_mut().find(|c| &c.name == column) {
                    c.ty = to.clone();
                }
            }
            SchemaChange::DropNotNull { column, .. } => {
                if let Some(c) = shape.columns.iter_mut().find(|c| &c.name == column) {
                    c.nullable = true;
                }
            }
            SchemaChange::SetNotNull { column, .. } => {
                if let Some(c) = shape.columns.iter_mut().find(|c| &c.name == column) {
                    c.nullable = false;
                }
            }
            SchemaChange::SetDefault { column, to, .. } => {
                if let Some(c) = shape.columns.iter_mut().find(|c| &c.name == column) {
                    c.default = Some(to.clone());
                }
            }
            SchemaChange::AddCheck { check, .. } => shape.checks.push(check.clone()),
            SchemaChange::AddForeignKey {
                column,
                foreign_key,
                ..
            } => {
                if let Some(c) = shape.columns.iter_mut().find(|c| &c.name == column) {
                    c.references = Some(foreign_key.clone());
                }
            }
            SchemaChange::AddIndex { index, .. } => shape.indexes.push(index.clone()),
            SchemaChange::DropIndex { index, .. } => {
                shape.indexes.retain(|i| i.name != index.name);
            }
            _ => {}
        }
    }
    shape
}

/// Copy the desired decimal precision and scale into a `SQLite` rebuild table,
/// for each baseline column that lost its decimal type (issue #2598).
///
/// The renderer builds the decimal `CHECK` from the precision and scale.
/// `--dev-url` and `schema pull` read a decimal column as `TEXT`. Without this
/// function, a rebuild removes the `CHECK`. A baseline decimal keeps its
/// precision and scale: a different value is a type change in the plan. A
/// column with a different storage class keeps its baseline type: that is a
/// real type change too.
///
/// Returns the names of the columns it changes. The rebuild writes a new
/// `CHECK` for each of them.
fn with_desired_decimal_shapes(shape: &mut Table, desired: &Table) -> Vec<String> {
    let mut changed = Vec::new();
    for column in &mut shape.columns {
        if let Some(want) = desired.columns.iter().find(|c| c.name == column.name)
            && matches!(want.ty, ColumnType::Decimal { .. })
            && !matches!(column.ty, ColumnType::Decimal { .. })
            && column_types_equivalent(&column.ty, &want.ty, Backend::Sqlite)
        {
            column.ty = want.ty.clone();
            changed.push(column.name.clone());
        }
    }
    changed
}

/// The columns of `table` with a type change to a decimal in the `leg` target:
/// `to` for the up leg, `from` for the down leg (issue #2598). The rebuild
/// writes a new decimal `CHECK` for each.
fn decimal_type_changes(changes: &[&SchemaChange], table: &str, leg: RebuildLeg) -> Vec<String> {
    changes
        .iter()
        .filter_map(|change| match change {
            SchemaChange::AlterColumnType {
                table: t,
                column,
                from,
                to,
            } if t == table
                && matches!(
                    if matches!(leg, RebuildLeg::Up) {
                        to
                    } else {
                        from
                    },
                    ColumnType::Decimal { .. }
                ) =>
            {
                Some(column.clone())
            }
            _ => None,
        })
        .collect()
}

/// The [`EmitError::SqliteRebuildUnsupported`] for a rebuild whose `which`
/// (`"desired"` / `"baseline"`) table shape is absent from the context.
fn missing_rebuild_shape(table: &str, which: &'static str) -> EmitError {
    EmitError::SqliteRebuildUnsupported {
        table: table.to_owned(),
        kind: "table rebuild",
        reason: format!(
            "the {which} table shape is unavailable — call \
             emit_up_sql_with_context / emit_down_sql_with_context with a \
             SchemaContext populated from the desired and baseline tables"
        ),
    }
}

/// Render the recreate block: staging `CREATE`, `INSERT .. SELECT` of the columns
/// common to both shapes (in `new_shape` order), `DROP`, `RENAME`, index recreate,
/// and the integrity check. `leg` only prepends the down-leg irreversibility marker.
fn render_sqlite_rebuild(
    table: &str,
    new_shape: &Table,
    source_shape: &Table,
    leg: RebuildLeg,
    fk_type_change_cols: &[String],
    new_decimal_checks: &[String],
) -> String {
    let new_table = format!("{table}__autumn_new");
    let source_cols: BTreeSet<&str> = source_shape
        .columns
        .iter()
        .map(|c| c.name.as_str())
        .collect();
    let common: Vec<&str> = new_shape
        .columns
        .iter()
        .map(|c| c.name.as_str())
        .filter(|n| source_cols.contains(n))
        .collect();
    let col_list = common.join(", ");

    let mut out = String::new();
    if matches!(leg, RebuildLeg::Down) {
        let _ = writeln!(
            out,
            "-- irreversible: a SQLite table rebuild rolled back to the prior shape may not restore data lost by a narrowing type change or dropped column"
        );
    }
    let _ = writeln!(
        out,
        "-- autumn: SQLite table rebuild for `{table}` — ALTER-family changes require a full table recreate."
    );
    let _ = writeln!(
        out,
        "-- Transaction semantics: this migration must run inside a single transaction (diesel wraps each"
    );
    let _ = writeln!(
        out,
        "-- migration in one). NOTE: `PRAGMA foreign_keys` is a no-op inside a transaction, so the harness"
    );
    let _ = writeln!(
        out,
        "-- must ensure foreign-key enforcement is disabled around the migration."
    );
    let _ = writeln!(
        out,
        "-- autumn-safety: this recreate copies columns and re-creates indexes only. DROP TABLE drops the table's TRIGGERS (not restored here); VIEWS that reference the table are not dropped and may be left dangling or block the rename — re-create triggers and repair dependent views in a manual migration."
    );
    let _ = writeln!(
        out,
        "-- autumn-safety: `PRAGMA foreign_key_check` below only REPORTS violation rows (it does not raise); the recreate copies existing values verbatim and introduces no new orphans, but the migration runner must inspect the pragma's output to treat any pre-existing orphan as an error."
    );
    push_rebuild_advisories(&mut out, fk_type_change_cols, new_decimal_checks);
    // Preserve the AUTOINCREMENT high-water mark only when both the copy source and the
    // target shape's single PK are `BigSerial` — an `INTEGER PRIMARY KEY AUTOINCREMENT`
    // column. Such a source table has a `sqlite_sequence` row that `DROP TABLE` would
    // discard, resetting the high-water to the max surviving id and letting a later insert
    // reuse an id that was previously issued and deleted.
    //
    // Gating on the source too is load-bearing: SQLite creates `sqlite_sequence` lazily,
    // only once some AUTOINCREMENT table exists, so a migration that introduces
    // autoincrement — an `i32` to `i64` PK change — on a database with no prior
    // AUTOINCREMENT table has no `sqlite_sequence`, and the capture SELECT would fail with
    // `no such table: sqlite_sequence`. The high-water only needs preserving when the
    // source was already AUTOINCREMENT, and then its row is guaranteed to exist. When the
    // source is not AUTOINCREMENT there is no prior high-water to preserve, so skipping is
    // correct too. Uuid, composite, and non-single-PK tables have no `sqlite_sequence`
    // entry either, so they emit none of these statements.
    let preserve_seq = matches!(single_pk_column(source_shape), Some((_, IdKind::BigSerial)))
        && matches!(single_pk_column(new_shape), Some((_, IdKind::BigSerial)));

    let _ = writeln!(out, "PRAGMA foreign_keys=OFF;");
    if preserve_seq {
        let _ = writeln!(
            out,
            "-- preserve the AUTOINCREMENT high-water mark so IDs issued-then-deleted are never reused"
        );
        let _ = writeln!(
            out,
            "CREATE TEMP TABLE _autumn_seq_{table} AS SELECT seq FROM sqlite_sequence WHERE name = '{table}';"
        );
    }
    out.push_str(&render_create_table_body(
        &new_table,
        new_shape,
        Backend::Sqlite,
    ));
    let _ = writeln!(out, "INSERT INTO {new_table} ({col_list})");
    let _ = writeln!(out, "    SELECT {col_list} FROM {table};");
    let _ = writeln!(out, "DROP TABLE {table};");
    // Wrap the staging rename in `PRAGMA legacy_alter_table=ON`…`OFF`. Under the modern
    // default (`legacy_alter_table=OFF`), `ALTER TABLE ... RENAME` descends into every
    // dependent VIEW to rewrite references and aborts because the just-dropped table no
    // longer resolves ("error in view v: no such table"). The offline emitter cannot see
    // or recreate views, so it emits this blind, always-present pragma pair: it makes the
    // rename a "dumb" rename that does not validate views, so the migration applies and
    // the view re-validates against the recreated table. Unlike `foreign_keys`, this
    // pragma is honoured inside a transaction (proven by `sqlite_rebuild_survives_dependent_view`).
    let _ = writeln!(out, "PRAGMA legacy_alter_table=ON;");
    let _ = writeln!(out, "ALTER TABLE {new_table} RENAME TO {table};");
    let _ = writeln!(out, "PRAGMA legacy_alter_table=OFF;");
    let mut indexes: Vec<&Index> = new_shape.indexes.iter().collect();
    indexes.sort_by(|a, b| a.name.cmp(&b.name));
    for index in indexes {
        let _ = writeln!(out, "{}", index_sql(table, index));
    }
    if preserve_seq {
        let _ = writeln!(
            out,
            "UPDATE sqlite_sequence SET seq = (SELECT seq FROM _autumn_seq_{table})\n    WHERE name = '{table}' AND (SELECT seq FROM _autumn_seq_{table}) IS NOT NULL;"
        );
        let _ = writeln!(
            out,
            "INSERT INTO sqlite_sequence (name, seq)\n    SELECT '{table}', (SELECT seq FROM _autumn_seq_{table})\n    WHERE (SELECT seq FROM _autumn_seq_{table}) IS NOT NULL\n      AND NOT EXISTS (SELECT 1 FROM sqlite_sequence WHERE name = '{table}');"
        );
        let _ = writeln!(out, "DROP TABLE _autumn_seq_{table};");
    }
    let _ = writeln!(out, "PRAGMA foreign_key_check;");
    let _ = writeln!(out, "PRAGMA foreign_keys=ON;");
    out
}

/// Write the optional `-- autumn-safety:` lines of a `SQLite` rebuild.
fn push_rebuild_advisories(
    out: &mut String,
    fk_type_change_cols: &[String],
    new_decimal_checks: &[String],
) {
    // When an FK-bound column's type is changed by this recreate, warn that SQLite
    // (unlike Postgres, which refuses the change outright) does not enforce that the
    // column still matches the referenced key's type — that consistency is now the
    // author's responsibility.
    if !fk_type_change_cols.is_empty() {
        let cols = fk_type_change_cols.join(", ");
        let _ = writeln!(
            out,
            "-- autumn-safety: foreign-key column(s) {cols} have their type changed by this recreate; SQLite does not enforce that they still match the referenced key's type, so ensure the referenced column stays type-compatible (Postgres rejects this change outright, which is why it is emitted only for SQLite)."
        );
    }
    // #2598: the table can have rows that a new decimal `CHECK` rejects.
    if !new_decimal_checks.is_empty() {
        let cols = new_decimal_checks.join(", ");
        let _ = writeln!(
            out,
            "-- autumn-safety: this recreate writes a new decimal CHECK for column(s) {cols}. If a row does not agree with the CHECK, the copy fails. Correct the rows first."
        );
    }
}

/// Join statement groups with a blank line and a trailing newline (empty for an
/// empty plan).
fn join_groups(groups: &[String]) -> String {
    if groups.is_empty() {
        return String::new();
    }
    let mut out = groups.join("\n\n");
    out.push('\n');
    out
}

/// Order the changes into the canonical up-buckets (a valid dependency order),
/// stable within a bucket (`diff_schema` already emits a deterministic order).
///
/// Two orderings need context the plain per-change bucket cannot provide, so they
/// are handled here rather than in [`up_bucket`]:
///
/// * **New-table FK dependencies** — `CREATE TABLE`s are **topologically** sorted
///   so a table referenced by an inline `REFERENCES` is created before the table
///   that references it (a cycle is [`EmitError::CyclicTableDependencies`]).
/// * **Replaced indexes** — a same-named index that is both dropped and re-added
///   (a shape change) must `DROP INDEX` **before** the `CREATE INDEX`, else the
///   create collides with the still-existing old index; such a "replacement drop"
///   is ordered just before the `AddIndex` bucket instead of in the general
///   `DropIndex` bucket.
///
/// # Errors
///
/// Returns [`EmitError::CyclicTableDependencies`] when the new tables reference
/// each other in a cycle that inline foreign keys cannot express.
fn up_ordered(changes: &[SchemaChange]) -> Result<Vec<&SchemaChange>, EmitError> {
    let replaced = replaced_index_names(changes);

    // Renames go before everything, in plan order (tables, then columns, then
    // indexes). The down leg reverses the plan, so it undoes them last.
    let renames: Vec<&SchemaChange> = changes.iter().filter(|c| is_rename(c)).collect();

    // `CreateTable`s are the first bucket; order them topologically so referenced
    // tables precede their referencers.
    let mut creates: Vec<&SchemaChange> = changes
        .iter()
        .filter(|c| matches!(c, SchemaChange::CreateTable(_)))
        .collect();
    topo_sort_creates(&mut creates)?;

    // `DropTable`s are the last bucket; order them in REVERSE topological order so
    // a table that references another (via its baseline inline FK) is dropped
    // before the table it references. `emit_down_sql` reverses the whole plan, so
    // this reverse-topo up-order becomes a forward-topo (referenced-first) recreate
    // on the down leg.
    let mut drops: Vec<&SchemaChange> = changes
        .iter()
        .filter(|c| matches!(c, SchemaChange::DropTable(_)))
        .collect();
    topo_sort_drops(&mut drops)?;

    // Everything else keeps its bucket order; the replacement-drop key threads
    // through so a replaced index drops before its re-add.
    let mut rest: Vec<&SchemaChange> = changes
        .iter()
        .filter(|c| {
            !is_rename(c) && !matches!(c, SchemaChange::CreateTable(_) | SchemaChange::DropTable(_))
        })
        .collect();
    rest.sort_by_key(|c| up_sort_key(c, &replaced));

    let mut ordered = renames;
    ordered.extend(creates);
    ordered.extend(rest);
    ordered.extend(drops);
    Ok(ordered)
}

/// Whether `change` is an emittable rename (table, column or index).
const fn is_rename(change: &SchemaChange) -> bool {
    matches!(
        change,
        SchemaChange::RenameTable { .. }
            | SchemaChange::RenameColumn { .. }
            | SchemaChange::RenameIndex { .. }
    )
}

/// The set of index names that appear in **both** an `AddIndex` and a `DropIndex`
/// in the same plan — i.e. a same-named index whose shape changed
/// ([`diff_indexes`] emits it as a drop + a re-add). Such a drop must precede its
/// re-add in `up.sql`.
fn replaced_index_names(changes: &[SchemaChange]) -> BTreeSet<String> {
    let added: BTreeSet<&str> = changes
        .iter()
        .filter_map(|c| match c {
            SchemaChange::AddIndex { index, .. } => Some(index.name.as_str()),
            _ => None,
        })
        .collect();
    changes
        .iter()
        .filter_map(|c| match c {
            SchemaChange::DropIndex { index, .. } if added.contains(index.name.as_str()) => {
                Some(index.name.clone())
            }
            _ => None,
        })
        .collect()
}

/// The up-order sort key for a non-`CreateTable` change. A two-level key so a
/// **replacement** `DropIndex` (its name is also re-added) sorts *just before* the
/// `AddIndex` bucket while every other change keeps its plain bucket.
fn up_sort_key(change: &SchemaChange, replaced: &BTreeSet<String>) -> (u8, u8) {
    match change {
        // Replacement drop: same bucket as AddIndex, but ordered before it.
        SchemaChange::DropIndex { index, .. } if replaced.contains(&index.name) => (3, 0),
        SchemaChange::AddIndex { .. } => (3, 1),
        other => (up_bucket(other), 1),
    }
}

/// Topologically order `creates` (all `CreateTable` changes) so a table referenced
/// by another's inline `REFERENCES` is created first. Only intra-batch
/// dependencies matter — a reference to a pre-existing baseline table imposes no
/// ordering. Deterministic (Kahn's algorithm, always taking the
/// lexicographically-smallest ready table).
///
/// # Errors
///
/// Returns [`EmitError::CyclicTableDependencies`] if the new tables form a
/// reference cycle (inline foreign keys cannot express one).
fn topo_sort_creates(creates: &mut [&SchemaChange]) -> Result<(), EmitError> {
    if creates.len() < 2 {
        return Ok(());
    }
    let tables: BTreeMap<&str, &Table> = creates
        .iter()
        .filter_map(|c| match c {
            SchemaChange::CreateTable(t) => Some((t.name.as_str(), t)),
            _ => None,
        })
        .collect();
    let names: BTreeSet<&str> = tables.keys().copied().collect();

    // deps[name] = the in-batch tables `name` references (must be created first).
    let mut deps: BTreeMap<&str, BTreeSet<&str>> = BTreeMap::new();
    for (&name, table) in &tables {
        let mut d = BTreeSet::new();
        for col in &table.columns {
            if let Some(fk) = &col.references {
                let target = fk.table.as_str();
                if target != name && names.contains(target) {
                    d.insert(target);
                }
            }
        }
        deps.insert(name, d);
    }

    // Kahn: repeatedly place the smallest name whose deps are all already placed.
    let mut remaining: BTreeSet<&str> = names;
    let mut order: BTreeMap<&str, usize> = BTreeMap::new();
    while !remaining.is_empty() {
        let ready = remaining
            .iter()
            .copied()
            .find(|n| deps[n].iter().all(|d| !remaining.contains(d)));
        if let Some(n) = ready {
            order.insert(n, order.len());
            remaining.remove(n);
        } else {
            let mut cyc: Vec<String> = remaining.iter().map(|s| (*s).to_owned()).collect();
            cyc.sort();
            return Err(EmitError::CyclicTableDependencies { tables: cyc });
        }
    }

    creates.sort_by_key(|c| match c {
        SchemaChange::CreateTable(t) => order.get(t.name.as_str()).copied().unwrap_or(usize::MAX),
        _ => usize::MAX,
    });
    Ok(())
}

/// Topologically order `drops` (all `DropTable` changes) in **reverse** dependency
/// order so a table that references another (via its own baseline inline FK) is
/// dropped **before** the table it references — PG rejects dropping a referenced
/// table while a referencing one still exists. The dependency graph is built from
/// the dropped tables' baseline FKs (carried on the [`SchemaChange::DropTable`]
/// payload). Only intra-batch dependencies matter: a retained referencer is a
/// separate concern handled by [`guard_plan`]'s inbound-FK refusal. Deterministic
/// (Kahn's algorithm, always taking the lexicographically-smallest ready table).
///
/// # Errors
///
/// Returns [`EmitError::CyclicTableDependencies`] if the dropped tables form a
/// reference cycle (the same refusal the [`SchemaChange::CreateTable`] path uses).
fn topo_sort_drops(drops: &mut [&SchemaChange]) -> Result<(), EmitError> {
    if drops.len() < 2 {
        return Ok(());
    }
    let tables: BTreeMap<&str, &Table> = drops
        .iter()
        .filter_map(|c| match c {
            SchemaChange::DropTable(t) => Some((t.name.as_str(), t)),
            _ => None,
        })
        .collect();
    let names: BTreeSet<&str> = tables.keys().copied().collect();

    // deps[name] = the in-batch tables that must be dropped BEFORE `name`, i.e.
    // the tables that reference `name` (referencers drop first). This is the edge
    // set of `topo_sort_creates` inverted.
    let mut deps: BTreeMap<&str, BTreeSet<&str>> =
        names.iter().map(|&n| (n, BTreeSet::new())).collect();
    for (&name, table) in &tables {
        for col in &table.columns {
            if let Some(fk) = &col.references {
                let target = fk.table.as_str();
                if target != name && names.contains(target) {
                    // `name` references `target` ⇒ `name` must drop before `target`.
                    deps.get_mut(target)
                        .expect("target is an in-batch name")
                        .insert(name);
                }
            }
        }
    }

    // Kahn: repeatedly place the smallest name whose deps are all already placed.
    let mut remaining: BTreeSet<&str> = names;
    let mut order: BTreeMap<&str, usize> = BTreeMap::new();
    while !remaining.is_empty() {
        let ready = remaining
            .iter()
            .copied()
            .find(|n| deps[n].iter().all(|d| !remaining.contains(d)));
        if let Some(n) = ready {
            order.insert(n, order.len());
            remaining.remove(n);
        } else {
            let mut cyc: Vec<String> = remaining.iter().map(|s| (*s).to_owned()).collect();
            cyc.sort();
            return Err(EmitError::CyclicTableDependencies { tables: cyc });
        }
    }

    drops.sort_by_key(|c| match c {
        SchemaChange::DropTable(t) => order.get(t.name.as_str()).copied().unwrap_or(usize::MAX),
        _ => usize::MAX,
    });
    Ok(())
}

/// The canonical up-order bucket for a change (lower = earlier).
const fn up_bucket(change: &SchemaChange) -> u8 {
    match change {
        // Renames never reach here: `up_ordered` puts them first.
        SchemaChange::RenameTable { .. }
        | SchemaChange::RenameColumn { .. }
        | SchemaChange::RenameIndex { .. }
        | SchemaChange::CreateTable(_) => 0,
        SchemaChange::AddColumn { .. } => 1,
        SchemaChange::AlterColumnType { .. }
        | SchemaChange::SetNotNull { .. }
        | SchemaChange::DropNotNull { .. }
        | SchemaChange::SetDefault { .. } => 2,
        SchemaChange::AddIndex { .. } => 3,
        SchemaChange::AddCheck { .. } | SchemaChange::AddForeignKey { .. } => 4,
        SchemaChange::DropIndex { .. } => 5,
        SchemaChange::DropColumn { .. } => 6,
        SchemaChange::DropTable(_) => 7,
        // Non-emittable markers; the guard refuses them before emission is reached.
        SchemaChange::RenameConflict { .. }
        | SchemaChange::PrimaryKeyChange { .. }
        | SchemaChange::ForeignKeyChange { .. }
        | SchemaChange::IdentityChange { .. }
        | SchemaChange::DropTableBlockedByInboundFk { .. }
        | SchemaChange::AlterColumnTypeBlockedByFk { .. }
        | SchemaChange::AddForeignKeyToExistingColumn { .. }
        | SchemaChange::CreateTableBlockedBySkippedField { .. } => 9,
    }
}

/// Render a single change's forward SQL.
fn emit_change_up(change: &SchemaChange, backend: Backend) -> Result<String, EmitError> {
    match change {
        SchemaChange::RenameTable { from, to } => {
            Ok(format!("ALTER TABLE {from} RENAME TO {to};\n"))
        }
        SchemaChange::RenameColumn { table, from, to } => Ok(format!(
            "ALTER TABLE {table} RENAME COLUMN {from} TO {to};\n"
        )),
        SchemaChange::RenameIndex { table, from, index } => {
            Ok(emit_rename_index(table, from, index, backend))
        }
        SchemaChange::CreateTable(table) => Ok(emit_create_table(table, backend)),
        SchemaChange::DropTable(table) => Ok(format!(
            "-- autumn-safety: this DROP TABLE is not checked against generated \
             #[belongs_to(...)] association foreign keys, which the offline snapshot cannot see; \
             if a retained table has an invisible association FK to `{0}`, this will fail to apply \
             -- verify with schema introspection or drop the FK manually first\n\
             DROP TABLE {0};\n",
            table.name
        )),
        SchemaChange::AddColumn { table, column } => emit_add_column(table, column, backend),
        SchemaChange::DropColumn { table, column } => Ok(format!(
            "ALTER TABLE {table} DROP COLUMN {};\n",
            column.name
        )),
        SchemaChange::AlterColumnType {
            table, column, to, ..
        } => {
            require_pg(backend, "AlterColumnType")?;
            Ok(format!(
                "ALTER TABLE {table} ALTER COLUMN {column} TYPE {};\n",
                to.sql_type(backend)
            ))
        }
        SchemaChange::SetNotNull { table, column } => {
            require_pg(backend, "SetNotNull")?;
            Ok(format!(
                "-- autumn-safety: potentially-blocking -- existing NULLs must be backfilled first\n\
                 ALTER TABLE {table} ALTER COLUMN {column} SET NOT NULL;\n"
            ))
        }
        SchemaChange::DropNotNull { table, column } => {
            require_pg(backend, "DropNotNull")?;
            Ok(format!(
                "ALTER TABLE {table} ALTER COLUMN {column} DROP NOT NULL;\n"
            ))
        }
        SchemaChange::SetDefault {
            table, column, to, ..
        } => {
            require_pg(backend, "SetDefault")?;
            Ok(format!(
                "ALTER TABLE {table} ALTER COLUMN {column} SET DEFAULT {};\n",
                default_sql(to, backend)
            ))
        }
        SchemaChange::AddIndex { table, index } => Ok(format!("{}\n", index_sql(table, index))),
        SchemaChange::DropIndex { index, .. } => Ok(format!("DROP INDEX {};\n", index.name)),
        SchemaChange::AddCheck { table, check } => {
            require_pg(backend, "AddCheck")?;
            Ok(check.name.as_ref().map_or_else(
                || format!("ALTER TABLE {table} ADD CHECK ({});\n", check.expression),
                |name| {
                    format!(
                        "ALTER TABLE {table} ADD CONSTRAINT {name} CHECK ({});\n",
                        check.expression
                    )
                },
            ))
        }
        SchemaChange::AddForeignKey {
            table,
            column,
            foreign_key,
        } => {
            require_pg(backend, "AddForeignKey")?;
            let constraint = bounded_pg_identifier(&format!("{table}_{column}_fkey"));
            Ok(format!(
                "ALTER TABLE {table} ADD CONSTRAINT {constraint} \
                 FOREIGN KEY ({column}) REFERENCES {}({}){};\n",
                foreign_key.table,
                foreign_key.column,
                foreign_key.action_clauses()
            ))
        }
        // Non-emittable markers: the guard refuses them, so they never reach here
        // in the command flow. Render nothing defensively rather than panicking.
        SchemaChange::RenameConflict { .. }
        | SchemaChange::PrimaryKeyChange { .. }
        | SchemaChange::ForeignKeyChange { .. }
        | SchemaChange::IdentityChange { .. }
        | SchemaChange::DropTableBlockedByInboundFk { .. }
        | SchemaChange::AlterColumnTypeBlockedByFk { .. }
        | SchemaChange::AddForeignKeyToExistingColumn { .. }
        | SchemaChange::CreateTableBlockedBySkippedField { .. } => Ok(String::new()),
    }
}

/// Render a single change's reverse SQL, with an `-- irreversible:` / `-- manual:`
/// marker where the round-trip is not clean.
fn emit_change_down(change: &SchemaChange, backend: Backend) -> Result<String, EmitError> {
    match change {
        SchemaChange::RenameTable { from, to } => {
            Ok(format!("ALTER TABLE {to} RENAME TO {from};\n"))
        }
        SchemaChange::RenameColumn { table, from, to } => Ok(format!(
            "ALTER TABLE {table} RENAME COLUMN {to} TO {from};\n"
        )),
        SchemaChange::RenameIndex { table, from, index } => {
            let old = crate::schema::rename::renamed_index(index, from).unwrap_or_else(|| {
                let mut old = index.clone();
                old.name.clone_from(from);
                old
            });
            Ok(emit_rename_index(table, &index.name, &old, backend))
        }
        SchemaChange::CreateTable(table) => Ok(format!("DROP TABLE {};\n", table.name)),
        SchemaChange::DropTable(table) => {
            let recreate = emit_create_table(table, backend);
            Ok(format!(
                "-- irreversible: table data dropped by this migration cannot be restored\n\
                 {recreate}"
            ))
        }
        SchemaChange::AddColumn { table, column } => Ok(format!(
            "ALTER TABLE {table} DROP COLUMN {};\n",
            column.name
        )),
        SchemaChange::DropColumn { table, column } => {
            let readd = emit_add_column(table, column, backend)?;
            Ok(format!(
                "-- irreversible: column data dropped by this migration cannot be restored\n\
                 {readd}"
            ))
        }
        SchemaChange::AlterColumnType {
            table,
            column,
            from,
            ..
        } => {
            require_pg(backend, "AlterColumnType")?;
            Ok(format!(
                "-- irreversible: a narrowing type change may have lost data; review before rolling back\n\
                 ALTER TABLE {table} ALTER COLUMN {column} TYPE {};\n",
                from.sql_type(backend)
            ))
        }
        SchemaChange::SetNotNull { table, column } => {
            require_pg(backend, "SetNotNull")?;
            Ok(format!(
                "ALTER TABLE {table} ALTER COLUMN {column} DROP NOT NULL;\n"
            ))
        }
        SchemaChange::DropNotNull { table, column } => {
            require_pg(backend, "DropNotNull")?;
            Ok(format!(
                "-- potentially-blocking: rolling back re-adds NOT NULL; existing NULL rows will block it\n\
                 ALTER TABLE {table} ALTER COLUMN {column} SET NOT NULL;\n"
            ))
        }
        SchemaChange::SetDefault {
            table,
            column,
            from,
            ..
        } => {
            require_pg(backend, "SetDefault")?;
            Ok(from.as_ref().map_or_else(
                || format!("ALTER TABLE {table} ALTER COLUMN {column} DROP DEFAULT;\n"),
                |d| {
                    format!(
                        "ALTER TABLE {table} ALTER COLUMN {column} SET DEFAULT {};\n",
                        default_sql(d, backend)
                    )
                },
            ))
        }
        SchemaChange::AddIndex { index, .. } => Ok(format!("DROP INDEX {};\n", index.name)),
        SchemaChange::DropIndex { table, index } => Ok(format!("{}\n", index_sql(table, index))),
        SchemaChange::AddCheck { table, check } => Ok(check.name.as_ref().map_or_else(
            || "-- manual: unnamed CHECK cannot be auto-dropped\n".to_owned(),
            |name| format!("ALTER TABLE {table} DROP CONSTRAINT {name};\n"),
        )),
        SchemaChange::AddForeignKey { table, column, .. } => {
            let constraint = bounded_pg_identifier(&format!("{table}_{column}_fkey"));
            Ok(format!(
                "ALTER TABLE {table} DROP CONSTRAINT {constraint};\n"
            ))
        }
        SchemaChange::RenameConflict { .. }
        | SchemaChange::PrimaryKeyChange { .. }
        | SchemaChange::ForeignKeyChange { .. }
        | SchemaChange::IdentityChange { .. }
        | SchemaChange::DropTableBlockedByInboundFk { .. }
        | SchemaChange::AlterColumnTypeBlockedByFk { .. }
        | SchemaChange::AddForeignKeyToExistingColumn { .. }
        | SchemaChange::CreateTableBlockedBySkippedField { .. } => Ok(String::new()),
    }
}

/// Guard the pg-only `ALTER`-family renderers: `SQLite` needs slice 5's
/// table-rebuild, so it is an explicit unsupported error here.
const fn require_pg(backend: Backend, kind: &'static str) -> Result<(), EmitError> {
    match backend {
        Backend::Postgres => Ok(()),
        Backend::Sqlite => Err(EmitError::UnsupportedOnBackend { kind, backend }),
    }
}

/// Rename index `from` to `index.name`. Postgres uses `ALTER INDEX`. `SQLite`
/// has no index rename, so it drops the index and creates it again. The data
/// already satisfies the index, so this is safe.
fn emit_rename_index(table: &str, from: &str, index: &Index, backend: Backend) -> String {
    match backend {
        Backend::Postgres => format!("ALTER INDEX {from} RENAME TO {};\n", index.name),
        Backend::Sqlite => format!("DROP INDEX {from};\n{}\n", index_sql(table, index)),
    }
}

/// Render a `CREATE TABLE` (reconstructing a single int/uuid PK via
/// [`IdKind::pk_sql`] so `BIGSERIAL` / `gen_random_uuid()` are not lost), followed
/// by one `CREATE [UNIQUE] INDEX` per index (name-sorted).
///
/// A `CREATE TABLE` is always renderable (the portable `SQLite` subset covers it),
/// so this is infallible.
fn emit_create_table(table: &Table, backend: Backend) -> String {
    let mut out = render_create_table_body(&table.name, table, backend);

    // Indexes, name-sorted for determinism.
    let mut indexes: Vec<&Index> = table.indexes.iter().collect();
    indexes.sort_by(|a, b| a.name.cmp(&b.name));
    for index in indexes {
        let _ = writeln!(out, "{}", index_sql(&table.name, index));
    }
    out
}

/// Render just the `CREATE TABLE {name} (…columns/PK/checks…);` statement (no index
/// `CREATE`s) for `table`'s shape, under an arbitrary `name`.
///
/// Split out of [`emit_create_table`] so the `SQLite` table-rebuild path can emit
/// the `{table}__autumn_new` staging table (whose indexes are recreated separately,
/// after the rename). [`emit_create_table`] recomposes this body plus its indexes,
/// so its output is unchanged.
fn render_create_table_body(name: &str, table: &Table, backend: Backend) -> String {
    let single_pk = single_pk_column(table);
    let mut lines: Vec<String> = Vec::with_capacity(table.columns.len() + 2);

    for col in &table.columns {
        if let Some((pk_col, kind)) = &single_pk
            && pk_col.name == col.name
        {
            lines.push(format!("    {} {}", col.name, kind.pk_sql(backend)));
        } else {
            // Render inline `UNIQUE` for a `Column.unique` column whose uniqueness is
            // NOT already owned by a separate index (the SQLite inline-`UNIQUE` fold),
            // so a rebuild/rollback preserves it without double-emitting for a model
            // `#[unique]` field (which has a covering named index).
            let render_unique = col.unique && !column_covered_by_unique_index(table, &col.name);
            lines.push(format!(
                "    {}",
                render_column_def(col, backend, render_unique)
            ));
        }
    }

    // Composite / exotic PK: a trailing table-level clause, columns rendered
    // normally above.
    if single_pk.is_none() && !table.primary_key.is_empty() {
        lines.push(format!(
            "    PRIMARY KEY ({})",
            table.primary_key.join(", ")
        ));
    }

    // Table-level checks (rare — the parser emits none today).
    for check in &table.checks {
        match &check.name {
            Some(cname) => lines.push(format!(
                "    CONSTRAINT {cname} CHECK ({})",
                check.expression
            )),
            None => lines.push(format!("    CHECK ({})", check.expression)),
        }
    }

    format!("CREATE TABLE {name} (\n{}\n);\n", lines.join(",\n"))
}

/// Render an `ALTER TABLE … ADD COLUMN`, mirroring the generator's house
/// convention for the `-- autumn-safety` comment on a `NOT NULL`-without-default
/// column.
///
/// **Index ownership:** this renderer emits **only** the column, never a
/// `CREATE INDEX`. A reference column's auto-index (`idx_<table>_<column>`) is
/// folded into the parser's table index set, so it arrives as its own
/// [`SchemaChange::AddIndex`] and is rendered by [`index_sql`] exactly once. If
/// `ADD COLUMN` also rendered the index inline it would be created twice and the
/// migration would fail. `diff_indexes`/`AddIndex` (and, for a brand-new table,
/// [`emit_create_table`]) is the single owner of index creation.
fn emit_add_column(table: &str, column: &Column, backend: Backend) -> Result<String, EmitError> {
    // `SQLite` rejects `ADD COLUMN … NOT NULL` without a DEFAULT — a slice-5 concern.
    if backend == Backend::Sqlite && !column.nullable && column.default.is_none() {
        return Err(EmitError::UnsupportedOnBackend {
            kind: "AddColumn (NOT NULL without a default on SQLite)",
            backend,
        });
    }

    let mut out = String::new();
    if !column.nullable && column.default.is_none() {
        let _ = writeln!(
            out,
            "-- autumn-safety: potentially-blocking -- add a DEFAULT or backfill existing rows before enforcing NOT NULL"
        );
    }
    let _ = writeln!(
        out,
        "ALTER TABLE {table} ADD COLUMN {};",
        // ADD COLUMN never renders inline UNIQUE: a model `#[unique]` column arrives
        // with a separate `AddIndex` that owns the uniqueness (SQLite column changes
        // go through the table-rebuild path, not ADD COLUMN).
        render_column_def(column, backend, false)
    );
    Ok(out)
}

/// Render a column definition body: `{name} {type} {NOT NULL|NULL} [REFERENCES
/// t(c) [ON DELETE a] [ON UPDATE a]] [DEFAULT d] [CHECK (…)]`. Shared by `CREATE
/// TABLE` (non-PK columns) and `ADD COLUMN`. The `CHECK` is the `SQLite` decimal
/// `CHECK` only.
fn render_column_def(column: &Column, backend: Backend, render_unique: bool) -> String {
    let mut def = format!(
        "{} {} {}",
        column.name,
        column.ty.sql_type(backend),
        nullability(column.nullable)
    );
    // Inline single-column `UNIQUE` — rendered ONLY when the caller says so. It is
    // emitted for a `Column.unique` column that is NOT already covered by a separate
    // unique `Index` in the table (the SQLite brownfield inline-`UNIQUE` fold, whose
    // constraint auto-index is deliberately not an `Index`). For a model `#[unique]`
    // field — which carries BOTH `Column.unique` AND a covering named `Index` — the
    // caller passes `false`, so the index owns the uniqueness and it is never
    // double-emitted (zero golden churn).
    if render_unique {
        def.push_str(" UNIQUE");
    }
    if let Some(fk) = &column.references {
        let _ = write!(
            def,
            " REFERENCES {}({}){}",
            fk.table,
            fk.column,
            fk.action_clauses()
        );
    }
    if let Some(default) = &column.default {
        let _ = write!(def, " DEFAULT {}", default_sql(default, backend));
    }
    // #2598: a `SQLite` decimal is `TEXT`. A `CHECK` enforces its precision and
    // scale. The generator uses the same builder, so the two lanes write the
    // same `CHECK`.
    if backend == Backend::Sqlite
        && let ColumnType::Decimal { precision, scale } = column.ty
    {
        let check = crate::generate::schema_edit::sqlite_decimal_check(
            &column.name,
            u32::from(precision),
            u32::from(scale),
        );
        let _ = write!(def, " {check}");
    }
    def
}

/// Whether some unique, non-partial `Index` in `table` keys on **exactly** the single
/// column `col` — i.e. the column's uniqueness is already owned by a separate index,
/// so it must NOT also be rendered as an inline `UNIQUE` (double-emit).
fn column_covered_by_unique_index(table: &Table, col: &str) -> bool {
    table
        .indexes
        .iter()
        .any(|idx| full_unique_key_columns(idx).is_some_and(|k| k.len() == 1 && k.contains(col)))
}

/// `CREATE [UNIQUE] INDEX {name} ON {table} ({cols});`.
///
/// When the index carries a raw `definition` (an expression/partial index
/// preserved verbatim by introspection), that full `pg_get_indexdef` statement is
/// emitted verbatim — with exactly one trailing `;` appended, since
/// `pg_get_indexdef` output has none — instead of reconstructing a
/// `CREATE INDEX … (columns)` form that cannot express the expression/predicate.
fn index_sql(table: &str, index: &Index) -> String {
    if let Some(def) = &index.definition {
        let def = def.trim_end().trim_end_matches(';');
        return format!("{def};");
    }
    let unique = if index.unique { "UNIQUE " } else { "" };
    format!(
        "CREATE {unique}INDEX {} ON {table} ({});",
        index.name,
        index.columns.join(", ")
    )
}

/// The nullability clause for a column.
const fn nullability(nullable: bool) -> &'static str {
    if nullable { "NULL" } else { "NOT NULL" }
}

/// Render a column default to SQL for `backend` (`Now` → `NOW()` on Postgres,
/// `CURRENT_TIMESTAMP` on `SQLite`; `Sql(s)` verbatim).
fn default_sql(default: &ColumnDefault, backend: Backend) -> String {
    match default {
        ColumnDefault::Now => match backend {
            Backend::Postgres => "NOW()".to_owned(),
            Backend::Sqlite => "CURRENT_TIMESTAMP".to_owned(),
        },
        // `SQLite` takes an expression default only inside parentheses, and its
        // catalog returns this one without them.
        ColumnDefault::Sql(sql)
            if backend == Backend::Sqlite
                && sql.trim() == autumn_schema_core::SQLITE_UUID_V4_SQL =>
        {
            format!("({})", sql.trim())
        }
        ColumnDefault::Sql(sql) => sql.clone(),
    }
}

/// The single-column primary key column and its reconstructed [`IdKind`], if the
/// table has exactly one PK column that is an int/uuid id.
///
/// The IR does not store `IdKind` on `Table` (a `BigSerial` PK is a
/// `Column { ty: Int64, primary_key: true, default: None }`), so naively emitting
/// it as `BIGINT` would silently drop auto-increment. This mirrors the
/// generator + parser conventions to recover it. Returns `None` for a composite
/// PK or a non-int/uuid PK → the caller falls back to a table-level `PRIMARY KEY
/// (…)` clause.
fn single_pk_column(table: &Table) -> Option<(&Column, IdKind)> {
    if table.primary_key.len() != 1 {
        return None;
    }
    let name = &table.primary_key[0];
    let column = table.columns.iter().find(|c| &c.name == name)?;
    pk_kind_for(column).map(|kind| (column, kind))
}

/// The [`SerialKind`] marker of a table's single-column primary key, or `None` for
/// a composite PK, no PK, a UUID single PK, or a legacy/unknown snapshot (the marker
/// predates the field). A plain integer PK carries `Some(Plain)`; an owned-sequence
/// id carries `Some(Serial)`/`Some(BigSerial)`. Used by [`serial_kinds_conflict`] /
/// [`diff_table`] to detect a plain-int-PK ↔ serial-PK id-generation change (which
/// is refused like any other primary-key change) while a legacy `None` never drifts.
fn single_pk_serial(table: &Table) -> Option<SerialKind> {
    if table.primary_key.len() != 1 {
        return None;
    }
    let name = &table.primary_key[0];
    table.columns.iter().find(|c| &c.name == name)?.serial
}

/// Whether the two tables' single-column-PK [`SerialKind`] markers CONFLICT — i.e.
/// both sides carry an **explicit** marker and they differ.
///
/// The marker is three-state: `None` is *unknown* (a snapshot written before the
/// field existed — serde default — or a non-integer/composite PK), while
/// `Some(_)` is an explicit introspected/parsed id-generation strategy. A conflict
/// is flagged ONLY when both sides are `Some(_)` and differ, so:
///   * a legacy snapshot (`None`) vs the parser's `Some(BigSerial)` → NO drift
///     (backward-compatibility: an existing project's pre-marker snapshot keeps
///     round-tripping clean instead of a spurious refused primary-key change);
///   * a fresh `BIGSERIAL` pull (`Some(BigSerial)`) vs model `Some(BigSerial)` →
///     no drift;
///   * a genuine plain-`BIGINT`-PK pull (`Some(Plain)`) vs model `Some(BigSerial)`
///     → drift (fidelity preserved).
fn serial_kinds_conflict(base: &Table, want: &Table) -> bool {
    matches!(
        (single_pk_serial(base), single_pk_serial(want)),
        (Some(a), Some(b)) if a != b
    )
}

/// Derive the id-generation strategy for a single-column PK:
///   `Int64` PK, no default                      → `BigSerial`
///   `Int32` PK, `nextval(...)` default           → `Serial` (a brownfield `SERIAL` id)
///   `Uuid`  PK, `gen_random_uuid()` default      → `Uuid`
/// Any other PK column → `None` (rendered normally with a table-level clause).
///
/// The `Int32`/`Serial` case only ever arises for a **brownfield-introspected**
/// table: the model DSL never produces an int4 PK, so this cannot conflict with a
/// model diff. Introspection deliberately preserves the `nextval(...)` default on an
/// int4 PK (see `introspect::normalize_serial_pk_default`) precisely so it is
/// recognized here and recreated as `SERIAL PRIMARY KEY` (auto-increment) rather
/// than a plain `INTEGER PRIMARY KEY`. An int4 PK with NO default falls through to
/// `None` → a plain integer PK (no auto-increment), which is correct.
///
/// The `Uuid` convention is likewise **default-gated**: the `IdKind::Uuid` shape
/// renders `UUID PRIMARY KEY DEFAULT gen_random_uuid()`, so it is only applied when
/// the pulled column's stored default is *exactly* that convention (the value the
/// model parser records — see `parse::convention_default` — so the round-trip stays
/// clean). A brownfield UUID PK whose default is a different expression (e.g.
/// `uuid_generate_v4()`) or is absent entirely falls through to `None`: it renders
/// as an ordinary `UUID` column preserving its real default (or lack of one), with
/// its primary key expressed via the trailing table-level `PRIMARY KEY (col)` clause
/// — so recreation (e.g. the down migration for a dropped table) never silently
/// swaps its UUID-generation behavior for `gen_random_uuid()` or adds a default
/// where none existed.
fn pk_kind_for(column: &Column) -> Option<IdKind> {
    // An explicit `Plain` serial marker — a brownfield plain `BIGINT`/`INTEGER PRIMARY
    // KEY` with no owned sequence, populated by both introspectors and never by the model
    // parser — must not reconstruct as `BIGSERIAL`/`AUTOINCREMENT`. That would fabricate
    // auto-increment, and a `sqlite_sequence` row, on a table rebuild or `DropTable`
    // rollback, silently changing id-generation behaviour. The `None` path renders it as
    // an ordinary integer column plus a table-level `PRIMARY KEY (col)` clause: a plain PK
    // with no sequence or AUTOINCREMENT. A legacy or unknown `None` marker keeps the
    // historical `BigSerial` behaviour for back-compat, since `serial_kinds_conflict`
    // treats a legacy `None` as compatible, so this fires only for an explicitly
    // `Plain`-marked pull.
    if column.serial == Some(SerialKind::Plain) {
        return None;
    }
    match &column.ty {
        ColumnType::Int64 if column.default.is_none() => Some(IdKind::BigSerial),
        ColumnType::Int32 if is_nextval_default(column) => Some(IdKind::Serial),
        ColumnType::Uuid if is_convention_uuid_default(column) => Some(IdKind::Uuid),
        // `SQLite` introspection reads the generated UUID key as `TEXT`. Its
        // default is the one marker that tells it from a plain text key.
        ColumnType::Text if is_sqlite_uuid_default(column) => Some(IdKind::Uuid),
        _ => None,
    }
}

/// Whether a UUID primary-key column's stored default is *exactly* the Autumn model
/// convention `gen_random_uuid()` (Postgres) or the `SQLite` `randomblob` v4
/// expression — the value `parse::convention_default` records for
/// a UUID `#[id]` and the string introspection preserves verbatim
/// (`normalize_default` keeps it as-is). Only then may the DDL emitter collapse the
/// column into the `IdKind::Uuid` shape (`UUID PRIMARY KEY DEFAULT
/// gen_random_uuid()`); a UUID PK with any other default — or none — is rendered as an
/// ordinary column so its true generation behavior is never silently rewritten.
fn is_convention_uuid_default(column: &Column) -> bool {
    matches!(
        &column.default,
        Some(ColumnDefault::Sql(sql))
            if sql.trim() == "gen_random_uuid()"
                || sql.trim() == autumn_schema_core::SQLITE_UUID_V4_SQL
    )
}

/// Whether a column's default is exactly the `SQLite` `randomblob` v4 UUID
/// expression (issue #2555).
fn is_sqlite_uuid_default(column: &Column) -> bool {
    matches!(
        &column.default,
        Some(ColumnDefault::Sql(sql)) if sql.trim() == autumn_schema_core::SQLITE_UUID_V4_SQL
    )
}

/// Whether a column's default is a `nextval(...)` sequence default (a `SERIAL`
/// auto-increment default), which the DDL emitter reconstructs by suppressing the
/// explicit default and rendering the `SERIAL`/`BIGSERIAL` keyword instead.
fn is_nextval_default(column: &Column) -> bool {
    matches!(
        &column.default,
        Some(ColumnDefault::Sql(sql)) if sql.trim_start().to_ascii_lowercase().starts_with("nextval(")
    )
}

// ---------------------------------------------------------------------------
// Human-readable summary
// ---------------------------------------------------------------------------

/// A human-readable plan summary for the default (no `--write-migration`) output.
#[must_use]
pub fn describe_plan(plan: &MigrationPlan) -> String {
    let backend = match plan.backend {
        Backend::Postgres => "postgres",
        Backend::Sqlite => "sqlite",
    };
    let mut out = format!(
        "Migration plan ({backend}): {} change(s)\n",
        plan.changes.len()
    );
    for change in &plan.changes {
        let _ = writeln!(out, "  {}", describe_change(change));
    }
    out
}

/// A one-line description of a single change.
fn describe_change(change: &SchemaChange) -> String {
    match change {
        SchemaChange::RenameTable { from, to } => format!("~ RENAME TABLE {from} TO {to}"),
        SchemaChange::RenameColumn { table, from, to } => {
            format!("~ RENAME COLUMN {table}.{from} TO {to}")
        }
        SchemaChange::RenameIndex { table, from, index } => {
            format!("~ RENAME INDEX {from} TO {} ON {table}", index.name)
        }
        SchemaChange::RenameConflict { table, reason } => {
            format!("! RENAME on {table}: {reason} (refused)")
        }
        SchemaChange::CreateTable(t) => format!("+ CREATE TABLE {}", t.name),
        SchemaChange::DropTable(t) => format!("- DROP TABLE {}", t.name),
        SchemaChange::AddColumn { table, column } => {
            format!("+ ADD COLUMN {table}.{}", column.name)
        }
        SchemaChange::DropColumn { table, column } => {
            format!("- DROP COLUMN {table}.{}", column.name)
        }
        SchemaChange::AlterColumnType {
            table,
            column,
            from,
            to,
        } => format!(
            "~ ALTER COLUMN {table}.{column} TYPE {} (was {})",
            to.sql_type(Backend::Postgres),
            from.sql_type(Backend::Postgres)
        ),
        SchemaChange::SetNotNull { table, column } => {
            format!("~ SET NOT NULL {table}.{column}")
        }
        SchemaChange::DropNotNull { table, column } => {
            format!("~ DROP NOT NULL {table}.{column}")
        }
        SchemaChange::SetDefault { table, column, .. } => {
            format!("~ SET DEFAULT {table}.{column}")
        }
        SchemaChange::AddForeignKey { table, column, .. } => {
            format!("+ ADD FOREIGN KEY {table}.{column}")
        }
        SchemaChange::AddIndex { table, index } => {
            format!("+ ADD INDEX {} ON {table}", index.name)
        }
        SchemaChange::DropIndex { table, index } => {
            format!("- DROP INDEX {} ON {table}", index.name)
        }
        SchemaChange::AddCheck { table, check } => format!(
            "+ ADD CHECK {} ON {table}",
            check.name.as_deref().unwrap_or("(unnamed)")
        ),
        SchemaChange::PrimaryKeyChange { table } => {
            format!("! PRIMARY KEY CHANGE on {table} (refused)")
        }
        SchemaChange::ForeignKeyChange {
            table,
            column,
            from,
            to,
        } => {
            format!("! FOREIGN KEY CHANGE on {table}.{column}: {from} -> {to} (refused)")
        }
        SchemaChange::IdentityChange { table, column } => {
            format!("! IDENTITY CHANGE on {table}.{column} (refused)")
        }
        SchemaChange::DropTableBlockedByInboundFk {
            table,
            referencing_table,
            referencing_column,
        } => format!(
            "! DROP TABLE {table} blocked by retained FK {referencing_table}.{referencing_column} (refused)"
        ),
        SchemaChange::AlterColumnTypeBlockedByFk { table, column } => {
            format!(
                "! ALTER COLUMN {table}.{column} TYPE blocked by foreign-key constraint (refused)"
            )
        }
        SchemaChange::AddForeignKeyToExistingColumn { table, column } => {
            format!("! ADD FOREIGN KEY on pre-existing column {table}.{column} (refused)")
        }
        SchemaChange::CreateTableBlockedBySkippedField { table, fields } => {
            format!(
                "! CREATE TABLE {table} blocked by parser-skipped field(s) [{}] (refused)",
                fields.join(", ")
            )
        }
    }
}

#[cfg(test)]
#[allow(clippy::needless_raw_string_hashes)]
mod tests {
    use super::*;
    use autumn_schema_core::{ForeignKey, ForeignKeyAction, Table};

    use crate::schema::parse::SchemaDiagnostic;

    // -- fixture helpers -----------------------------------------------------

    fn col(name: &str, ty: ColumnType) -> Column {
        Column::new(name, ty)
    }

    /// A `posts` table with an `id` `BigSerial` PK plus the given extra columns.
    fn posts_with(columns: Vec<Column>) -> Table {
        let mut t = Table::new("posts", Backend::Postgres);
        let mut id = col("id", ColumnType::Int64);
        id.primary_key = true;
        t.primary_key.push("id".to_owned());
        t.columns.push(id);
        t.columns.extend(columns);
        t
    }

    /// A managed table `name` with a `BigSerial` `id` PK plus one extra column
    /// (used to build cross-referencing new tables in the topo-order tests).
    fn posts_ref_table(name: &str, extra: Column) -> Table {
        let mut t = Table::new(name, Backend::Postgres);
        let mut id = col("id", ColumnType::Int64);
        id.primary_key = true;
        t.primary_key.push("id".to_owned());
        t.columns.push(id);
        t.columns.push(extra);
        t
    }

    fn parsed(tables: Vec<Table>, diagnostics: Vec<SchemaDiagnostic>) -> ParsedSchema {
        ParsedSchema {
            diagnostics,
            ..ParsedSchema::from_tables(tables)
        }
    }

    fn diag(model: &str, table: &str, field: &str) -> SchemaDiagnostic {
        SchemaDiagnostic {
            model: model.to_owned(),
            table: table.to_owned(),
            field: field.to_owned(),
            rust_type: "Unknown".to_owned(),
            message: format!("skipped {model}.{field}"),
        }
    }

    const DEFAULT_OPTS: DiffOptions = DiffOptions {
        allow_destructive: false,
        definitions_authoritative: false,
    };
    const ALLOW: DiffOptions = DiffOptions {
        allow_destructive: true,
        definitions_authoritative: false,
    };
    const AUTHORITATIVE: DiffOptions = DiffOptions {
        allow_destructive: false,
        definitions_authoritative: true,
    };

    /// `posts` with an explicit `serial` marker on its `id` PK (index 0).
    fn posts_with_id_serial(kind: Option<SerialKind>) -> Table {
        let mut t = posts_with(vec![]);
        t.columns[0].serial = kind;
        t
    }

    // -- serial-marker three-state compatibility -----------------------------

    #[test]
    fn serial_marker_legacy_none_is_compatible_with_parser_bigserial() {
        // A pre-marker (legacy) snapshot deserializes `id.serial = None`; the parser
        // marks the model `#[id]` as `Some(BigSerial)`. This must NOT flag a
        // primary-key change — otherwise every existing project breaks until it
        // rewrites its snapshot. Verified in BOTH diff modes.
        let legacy = vec![posts_with_id_serial(None)];
        let model = posts_with_id_serial(Some(SerialKind::BigSerial));
        for opts in [DEFAULT_OPTS, AUTHORITATIVE] {
            let plan = diff_schema(&legacy, &parsed(vec![model.clone()], vec![]), opts);
            assert!(
                !plan
                    .changes
                    .iter()
                    .any(|c| matches!(c, SchemaChange::PrimaryKeyChange { .. })),
                "legacy None vs Some(BigSerial) must be compatible ({opts:?}): {:?}",
                plan.changes
            );
        }
    }

    #[test]
    fn serial_marker_matching_bigserial_is_clean() {
        let base = vec![posts_with_id_serial(Some(SerialKind::BigSerial))];
        let want = posts_with_id_serial(Some(SerialKind::BigSerial));
        let plan = diff_schema(&base, &parsed(vec![want], vec![]), DEFAULT_OPTS);
        assert!(
            plan.changes.is_empty(),
            "matching markers: {:?}",
            plan.changes
        );
    }

    #[test]
    fn serial_marker_plain_conflicts_with_bigserial() {
        // A genuine plain-BIGINT-PK pull (`Some(Plain)`) vs a `BigSerial` model —
        // BOTH explicit — is a real id-generation change → refused primary-key change
        // (fidelity preserved).
        let base = vec![posts_with_id_serial(Some(SerialKind::Plain))];
        let want = posts_with_id_serial(Some(SerialKind::BigSerial));
        let plan = diff_schema(&base, &parsed(vec![want], vec![]), DEFAULT_OPTS);
        assert_eq!(
            plan.changes,
            vec![SchemaChange::PrimaryKeyChange {
                table: "posts".to_owned(),
            }]
        );
    }

    // -- identity-clause drift -----------------------------------------------

    #[test]
    fn identity_change_flagged_only_in_authoritative_diff() {
        // Two both-present introspections whose `id` identity clause differs
        // (`ALWAYS` dropped to a plain column). In an authoritative diff (doctor /
        // pull --dry-run) this is real drift → the refused `IdentityChange` marker;
        // in a model diff the parser cannot express identity, so a desired `None` is
        // "unknown, retained" (never drift).
        let mut base_id = posts_with_id_serial(Some(SerialKind::BigSerial));
        base_id.columns[0].identity = Some("ALWAYS".to_owned());
        let base = vec![base_id];
        let want = posts_with_id_serial(Some(SerialKind::BigSerial)); // identity: None

        let auth = diff_schema(&base, &parsed(vec![want.clone()], vec![]), AUTHORITATIVE);
        assert!(
            auth.changes.iter().any(|c| matches!(
                c,
                SchemaChange::IdentityChange { table, column } if table == "posts" && column == "id"
            )),
            "authoritative diff flags the identity change: {:?}",
            auth.changes
        );
        // The refused marker is rejected by the guard (no override).
        assert!(matches!(
            guard_plan(&auth, AUTHORITATIVE).unwrap_err(),
            DiffError::IdentityChange { .. }
        ));

        let model = diff_schema(&base, &parsed(vec![want], vec![]), DEFAULT_OPTS);
        assert!(
            !model
                .changes
                .iter()
                .any(|c| matches!(c, SchemaChange::IdentityChange { .. })),
            "model diff never flags an identity change: {:?}",
            model.changes
        );
    }

    // -- 13.1 structural diff ------------------------------------------------

    #[test]
    fn no_op_identical_returns_empty_plan() {
        let base = vec![posts_with(vec![col("body", ColumnType::Text)])];
        let want = parsed(
            vec![posts_with(vec![col("body", ColumnType::Text)])],
            vec![],
        );
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        assert!(plan.is_empty(), "identical schemas → empty plan: {plan:?}");
    }

    #[test]
    fn add_column_emits_add_column() {
        let base = vec![posts_with(vec![])];
        let mut bio = col("bio", ColumnType::Text);
        bio.nullable = true;
        let want = parsed(vec![posts_with(vec![bio.clone()])], vec![]);
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        assert_eq!(plan.changes.len(), 1);
        match &plan.changes[0] {
            SchemaChange::AddColumn { table, column } => {
                assert_eq!(table, "posts");
                assert_eq!(column, &bio);
            }
            other => panic!("expected AddColumn, got {other:?}"),
        }
    }

    #[test]
    fn drop_column_present_in_plan_carries_baseline_column() {
        let nickname = col("nickname", ColumnType::Text);
        let base = vec![posts_with(vec![nickname.clone()])];
        let want = parsed(vec![posts_with(vec![])], vec![]);
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        assert_eq!(plan.changes.len(), 1);
        match &plan.changes[0] {
            SchemaChange::DropColumn { table, column } => {
                assert_eq!(table, "posts");
                assert_eq!(column, &nickname, "carries the baseline column for down");
            }
            other => panic!("expected DropColumn, got {other:?}"),
        }
    }

    #[test]
    fn alter_column_type_int32_to_int64() {
        let base = vec![posts_with(vec![col("views", ColumnType::Int32)])];
        let want = parsed(
            vec![posts_with(vec![col("views", ColumnType::Int64)])],
            vec![],
        );
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        assert_eq!(
            plan.changes,
            vec![SchemaChange::AlterColumnType {
                table: "posts".to_owned(),
                column: "views".to_owned(),
                from: ColumnType::Int32,
                to: ColumnType::Int64,
            }]
        );
    }

    #[test]
    fn nullable_to_not_null_emits_set_not_null() {
        let mut nullable_bio = col("bio", ColumnType::Text);
        nullable_bio.nullable = true;
        let base = vec![posts_with(vec![nullable_bio])];
        let want = parsed(vec![posts_with(vec![col("bio", ColumnType::Text)])], vec![]);
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        assert_eq!(
            plan.changes,
            vec![SchemaChange::SetNotNull {
                table: "posts".to_owned(),
                column: "bio".to_owned(),
            }]
        );
    }

    #[test]
    fn not_null_to_nullable_emits_drop_not_null() {
        let base = vec![posts_with(vec![col("bio", ColumnType::Text)])];
        let mut nullable_bio = col("bio", ColumnType::Text);
        nullable_bio.nullable = true;
        let want = parsed(vec![posts_with(vec![nullable_bio])], vec![]);
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        assert_eq!(
            plan.changes,
            vec![SchemaChange::DropNotNull {
                table: "posts".to_owned(),
                column: "bio".to_owned(),
            }]
        );
    }

    #[test]
    fn set_default_added() {
        let base = vec![posts_with(vec![col("created_at", ColumnType::Timestamp)])];
        let mut created = col("created_at", ColumnType::Timestamp);
        created.default = Some(ColumnDefault::Now);
        let want = parsed(vec![posts_with(vec![created])], vec![]);
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        assert_eq!(
            plan.changes,
            vec![SchemaChange::SetDefault {
                table: "posts".to_owned(),
                column: "created_at".to_owned(),
                to: ColumnDefault::Now,
                from: None,
            }]
        );
    }

    #[test]
    fn add_index_and_drop_index_by_name() {
        let idx = Index {
            name: "idx_posts_body".to_owned(),
            columns: vec!["body".to_owned()],
            unique: false,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        };
        // desired gains the index.
        let base = vec![posts_with(vec![col("body", ColumnType::Text)])];
        let mut want_table = posts_with(vec![col("body", ColumnType::Text)]);
        want_table.indexes.push(idx.clone());
        let plan = diff_schema(&base, &parsed(vec![want_table], vec![]), DEFAULT_OPTS);
        assert_eq!(
            plan.changes,
            vec![SchemaChange::AddIndex {
                table: "posts".to_owned(),
                index: idx.clone(),
            }]
        );

        // baseline has it, desired dropped it — DropIndex carries the baseline.
        let mut base_table = posts_with(vec![col("body", ColumnType::Text)]);
        base_table.indexes.push(idx.clone());
        let want = parsed(
            vec![posts_with(vec![col("body", ColumnType::Text)])],
            vec![],
        );
        let plan = diff_schema(&[base_table], &want, DEFAULT_OPTS);
        assert_eq!(
            plan.changes,
            vec![SchemaChange::DropIndex {
                table: "posts".to_owned(),
                index: idx,
            }]
        );
    }

    /// A `definition`-carrying (expression/partial) index that the model DSL can
    /// never express: an expression index on `lower(email)`.
    fn expr_index() -> Index {
        Index {
            name: "idx_posts_lower_body".to_owned(),
            columns: vec!["body".to_owned()],
            unique: false,
            definition: Some("CREATE INDEX idx_posts_lower_body ON posts (lower(body))".to_owned()),
            is_partial: false,
            key_columns: Vec::new(),
        }
    }

    /// Model diff (`DEFAULT_OPTS`, `definitions_authoritative: false`): a
    /// baseline-only `definition` index absent from the desired (model) side is
    /// **retained** — the model DSL cannot express it, so its absence is a parser
    /// gap, not a removal. NO `DropIndex` is emitted.
    #[test]
    fn model_diff_retains_baseline_only_definition_index() {
        let mut base_table = posts_with(vec![col("body", ColumnType::Text)]);
        base_table.indexes.push(expr_index());
        let want = parsed(
            vec![posts_with(vec![col("body", ColumnType::Text)])],
            vec![],
        );
        let plan = diff_schema(&[base_table], &want, DEFAULT_OPTS);
        assert!(
            !plan
                .changes
                .iter()
                .any(|c| matches!(c, SchemaChange::DropIndex { .. })),
            "model diff must retain (not drop) an unmodellable definition index; got {:?}",
            plan.changes
        );
    }

    /// Model diff: a baseline constraint-owned index (a brownfield `UNIQUE`
    /// constraint's auto-created index, retained by `schema pull` via its
    /// `definition`) absent from the desired (model) side is **retained** — no
    /// `DropIndex`. This is the load-bearing case: Postgres rejects dropping an
    /// index that backs a constraint, so emitting a `DROP INDEX` would produce a
    /// failing migration. Retention is purely `definition`-based, so the same code
    /// path that preserves expression/partial indexes preserves this one.
    #[test]
    fn model_diff_retains_constraint_owned_unique_index() {
        let constraint_idx = Index {
            name: "users_email_key".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: Some(
                "CREATE UNIQUE INDEX users_email_key ON public.users USING btree (email)"
                    .to_owned(),
            ),
            is_partial: false,
            key_columns: vec!["email".to_owned()],
        };
        let mut base_table = posts_with(vec![col("email", ColumnType::Text)]);
        base_table.indexes.push(constraint_idx);
        let want = parsed(
            vec![posts_with(vec![col("email", ColumnType::Text)])],
            vec![],
        );
        let plan = diff_schema(&[base_table], &want, DEFAULT_OPTS);
        assert!(
            !plan
                .changes
                .iter()
                .any(|c| matches!(c, SchemaChange::DropIndex { .. })),
            "model diff must retain (not drop) a constraint-owned index; got {:?}",
            plan.changes
        );
    }

    /// Brownfield adoption (the P2 fix): a table pulled with `email TEXT UNIQUE`
    /// retains the constraint-owned unique index Postgres named `accounts_email_key`
    /// (`definition: Some(..)`, `unique`, columns `[email]`). The user then writes
    /// the natural model `Account { id, email }` with `#[unique]` on `email`, whose
    /// parser emits a differently-named unique index `idx_accounts_email_unique`
    /// over `[email]` (`definition: None`). A model diff must recognize the existing
    /// unique index as already satisfying the desired `#[unique]` — emitting NEITHER
    /// an `AddIndex` (which `guard_plan` would reject on a populated table) NOR a
    /// `DropIndex` for the retained constraint index. The plan must be clean.
    #[test]
    fn model_diff_existing_unique_index_satisfies_model_unique_by_columns() {
        let constraint_idx = Index {
            name: "accounts_email_key".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: Some(
                "CREATE UNIQUE INDEX accounts_email_key ON public.accounts USING btree (email)"
                    .to_owned(),
            ),
            is_partial: false,
            key_columns: vec!["email".to_owned()],
        };
        let mut base_table = posts_with(vec![col("email", ColumnType::Text)]);
        base_table.indexes.push(constraint_idx);

        // Desired (model): the parser-emitted, differently-named unique index.
        let mut want_table = posts_with(vec![col("email", ColumnType::Text)]);
        want_table.indexes.push(Index {
            name: "idx_posts_email_unique".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        });
        let plan = diff_schema(
            &[base_table],
            &parsed(vec![want_table], vec![]),
            DEFAULT_OPTS,
        );
        assert!(
            plan.changes.is_empty(),
            "existing unique index over the same column set must satisfy the model \
             #[unique]; expected a clean plan, got {:?}",
            plan.changes
        );
        // And the whole plan must pass the policy guard (no dedup refusal).
        assert!(
            guard_plan(&plan, DEFAULT_OPTS).is_ok(),
            "clean plan must not trip guard_plan"
        );
    }

    /// P1 (retain covering unique): a baseline **definition-less** unique index under
    /// a NON-model name (`accounts_email_uq`) that covers the model's `#[unique]`
    /// (whose own `AddIndex` is suppressed as already-satisfied) must be RETAINED — a
    /// `DropIndex` would remove the only uniqueness enforcement with no replacement.
    /// The plan must be clean (no `DropIndex`, no `AddIndex`).
    #[test]
    fn model_diff_retains_differently_named_covering_unique_index() {
        let covering = Index {
            name: "accounts_email_uq".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: None, // a plain CREATE UNIQUE INDEX, not a constraint index
            is_partial: false,
            key_columns: Vec::new(),
        };
        let mut base_table = posts_with(vec![col("email", ColumnType::Text)]);
        base_table.indexes.push(covering);
        // Model `#[unique] email` → a differently-named unique index.
        let mut want_table = posts_with(vec![col("email", ColumnType::Text)]);
        want_table.indexes.push(Index {
            name: "idx_posts_email_unique".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        });
        let plan = diff_schema(
            &[base_table],
            &parsed(vec![want_table], vec![]),
            DEFAULT_OPTS,
        );
        assert!(
            plan.changes.is_empty(),
            "a differently-named covering unique index is RETAINED and the model's \
             matching AddIndex suppressed (same uniqueness, different name): {:?}",
            plan.changes
        );
    }

    /// The retention is coverage-scoped: a baseline unique index the model does NOT
    /// cover (no matching `#[unique]`) still DROPS — the user removed the annotation.
    #[test]
    fn model_diff_unmatched_baseline_unique_index_still_drops() {
        let orphan = Index {
            name: "posts_nickname_uq".to_owned(),
            columns: vec!["nickname".to_owned()],
            unique: true,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        };
        let mut base_table = posts_with(vec![col("nickname", ColumnType::Text)]);
        base_table.indexes.push(orphan);
        // Model keeps the column but declares NO `#[unique]` on it.
        let want_table = posts_with(vec![col("nickname", ColumnType::Text)]);
        let plan = diff_schema(
            &[base_table],
            &parsed(vec![want_table], vec![]),
            DEFAULT_OPTS,
        );
        assert!(
            plan.changes.iter().any(|c| matches!(
                c,
                SchemaChange::DropIndex { index, .. } if index.name == "posts_nickname_uq"
            )),
            "an unmatched baseline unique index must still drop: {:?}",
            plan.changes
        );
    }

    /// The satisfaction is uniqueness-aware: a desired UNIQUE index over `[email]`
    /// is NOT satisfied by a baseline **non-unique** index over `[email]`, so the
    /// `AddIndex` is still emitted (the uniqueness is genuinely new).
    #[test]
    fn model_diff_nonunique_baseline_does_not_satisfy_unique_model_index() {
        let nonunique = Index {
            name: "idx_posts_email".to_owned(),
            columns: vec!["email".to_owned()],
            unique: false,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        };
        let mut base_table = posts_with(vec![col("email", ColumnType::Text)]);
        base_table.indexes.push(nonunique);

        let mut want_table = posts_with(vec![col("email", ColumnType::Text)]);
        want_table.indexes.push(Index {
            name: "idx_posts_email_unique".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        });
        let plan = diff_schema(
            &[base_table],
            &parsed(vec![want_table], vec![]),
            DEFAULT_OPTS,
        );
        assert!(
            plan.changes.iter().any(|c| matches!(
                c,
                SchemaChange::AddIndex { index, .. } if index.name == "idx_posts_email_unique"
            )),
            "a unique model index over a column with only a non-unique baseline index \
             must still emit AddIndex; got {:?}",
            plan.changes
        );
    }

    /// Authoritative mode (doctor drift / `pull --dry-run`, both sides introspected)
    /// is unaffected: a differently-named desired unique index is NOT suppressed by a
    /// column-set match, so real drift (a renamed/added unique index) is still
    /// detected. There the brownfield constraint index has the same name on both
    /// sides and would match by name; a genuinely new name is genuine drift.
    #[test]
    fn authoritative_diff_still_emits_add_for_differently_named_unique_index() {
        let constraint_idx = Index {
            name: "accounts_email_key".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: Some(
                "CREATE UNIQUE INDEX accounts_email_key ON public.accounts USING btree (email)"
                    .to_owned(),
            ),
            is_partial: false,
            key_columns: vec!["email".to_owned()],
        };
        let mut base_table = posts_with(vec![col("email", ColumnType::Text)]);
        base_table.indexes.push(constraint_idx);

        let mut want_table = posts_with(vec![col("email", ColumnType::Text)]);
        want_table.indexes.push(Index {
            name: "idx_posts_email_unique".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        });
        let plan = diff_schema(
            &[base_table],
            &parsed(vec![want_table], vec![]),
            AUTHORITATIVE,
        );
        assert!(
            plan.changes.iter().any(|c| matches!(
                c,
                SchemaChange::AddIndex { index, .. } if index.name == "idx_posts_email_unique"
            )),
            "authoritative diff must still emit AddIndex for a differently-named unique \
             index (column-set suppression is model-diff-only); got {:?}",
            plan.changes
        );
    }

    /// A **partial** unique index (`… ON t(email) WHERE …`) enforces uniqueness only
    /// for rows matching its predicate, so it does NOT satisfy a model `#[unique]
    /// email` (table-wide) — even though its key columns equal `{email}`. The
    /// `AddIndex` must still be emitted.
    #[test]
    fn baseline_partial_unique_index_does_not_satisfy_model_unique() {
        let partial = Index {
            name: "accounts_email_active_key".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: Some(
                "CREATE UNIQUE INDEX accounts_email_active_key ON accounts (email) WHERE active"
                    .to_owned(),
            ),
            is_partial: true,
            key_columns: vec!["email".to_owned()],
        };
        let mut base = posts_with(vec![col("email", ColumnType::Text)]);
        base.indexes.push(partial);
        assert!(
            !baseline_unique_index_covers(&base, &["email".to_owned()]),
            "a partial unique index must NOT satisfy a table-wide #[unique]"
        );

        // End-to-end: the model #[unique] still emits an AddIndex (not suppressed).
        let mut want_table = posts_with(vec![col("email", ColumnType::Text)]);
        want_table.indexes.push(Index {
            name: "idx_posts_email_unique".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        });
        let plan = diff_schema(&[base], &parsed(vec![want_table], vec![]), DEFAULT_OPTS);
        assert!(
            plan.changes.iter().any(|c| matches!(
                c,
                SchemaChange::AddIndex { index, .. } if index.name == "idx_posts_email_unique"
            )),
            "partial baseline unique index must not suppress the model AddIndex; got {:?}",
            plan.changes
        );
    }

    /// An **expression** unique index (`UNIQUE (lower(email))`) enforces uniqueness of
    /// the expression, not the column, so it does NOT satisfy `#[unique] email`.
    /// Introspection records it with an EMPTY `key_columns` (its dependency `columns`
    /// still names `email`), which must be rejected — the `AddIndex` is emitted.
    #[test]
    fn baseline_expression_unique_index_does_not_satisfy_model_unique() {
        let expr = Index {
            name: "accounts_lower_email_key".to_owned(),
            // `columns` is the pg_depend dependency set (references `email`)...
            columns: vec!["email".to_owned()],
            unique: true,
            definition: Some(
                "CREATE UNIQUE INDEX accounts_lower_email_key ON accounts (lower(email))"
                    .to_owned(),
            ),
            is_partial: false,
            // ...but its KEY is an expression, so no plain key columns are recorded.
            key_columns: Vec::new(),
        };
        let mut base = posts_with(vec![col("email", ColumnType::Text)]);
        base.indexes.push(expr);
        assert!(
            !baseline_unique_index_covers(&base, &["email".to_owned()]),
            "an expression unique index (empty key_columns) must NOT satisfy #[unique]"
        );

        let mut want_table = posts_with(vec![col("email", ColumnType::Text)]);
        want_table.indexes.push(Index {
            name: "idx_posts_email_unique".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        });
        let plan = diff_schema(&[base], &parsed(vec![want_table], vec![]), DEFAULT_OPTS);
        assert!(
            plan.changes.iter().any(|c| matches!(
                c,
                SchemaChange::AddIndex { index, .. } if index.name == "idx_posts_email_unique"
            )),
            "expression baseline unique index must not suppress the model AddIndex; got {:?}",
            plan.changes
        );
    }

    /// Regression guard for the last commit's fix: a plain, FULL, non-partial unique
    /// constraint index whose key columns exactly equal the target STILL satisfies the
    /// model `#[unique]` (no `AddIndex`). Covers both a `definition`-carrying
    /// constraint index (key columns recorded) and a plain `definition`-less unique
    /// index (key columns derived from `columns`).
    #[test]
    fn baseline_full_unique_constraint_index_still_satisfies_model_unique() {
        // (c1) constraint-owned (definition-carrying) unique index, key == [email].
        let constraint = Index {
            name: "accounts_email_key".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: Some(
                "CREATE UNIQUE INDEX accounts_email_key ON accounts (email)".to_owned(),
            ),
            is_partial: false,
            key_columns: vec!["email".to_owned()],
        };
        let mut base = posts_with(vec![col("email", ColumnType::Text)]);
        base.indexes.push(constraint);
        assert!(
            baseline_unique_index_covers(&base, &["email".to_owned()]),
            "a full non-partial unique constraint index over the exact key set must satisfy #[unique]"
        );

        // (c2) plain definition-less unique index: key columns derived from `columns`.
        let plain = Index {
            name: "idx_accounts_email_unique".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        };
        let mut base2 = posts_with(vec![col("email", ColumnType::Text)]);
        base2.indexes.push(plain);
        assert!(
            baseline_unique_index_covers(&base2, &["email".to_owned()]),
            "a plain full unique index must satisfy #[unique] via its columns"
        );
    }

    /// Retention holds even under `--allow-destructive`: the declarative tool
    /// never drops a construct it cannot express.
    #[test]
    fn model_diff_retains_definition_index_even_with_allow_destructive() {
        let mut base_table = posts_with(vec![col("body", ColumnType::Text)]);
        base_table.indexes.push(expr_index());
        let want = parsed(
            vec![posts_with(vec![col("body", ColumnType::Text)])],
            vec![],
        );
        let plan = diff_schema(&[base_table], &want, ALLOW);
        assert!(
            !plan
                .changes
                .iter()
                .any(|c| matches!(c, SchemaChange::DropIndex { .. })),
            "--allow-destructive must still retain an unmodellable definition index; got {:?}",
            plan.changes
        );
    }

    /// Model diff: a baseline `definition` index sharing a NAME with a desired
    /// (model-parsed, `definition: None`) index is **retained** — no
    /// `DropIndex`/replacement that would clobber the expression/partial index with
    /// a plain column index.
    #[test]
    fn model_diff_retains_definition_index_sharing_name_with_plain_desired() {
        // Baseline: an expression index named `idx_posts_body`.
        let base_expr = Index {
            name: "idx_posts_body".to_owned(),
            columns: vec!["body".to_owned()],
            unique: false,
            definition: Some("CREATE INDEX idx_posts_body ON posts (lower(body))".to_owned()),
            is_partial: false,
            key_columns: Vec::new(),
        };
        let mut base_table = posts_with(vec![col("body", ColumnType::Text)]);
        base_table.indexes.push(base_expr);

        // Desired (model): a plain column index of the SAME name (definition: None).
        let mut want_table = posts_with(vec![col("body", ColumnType::Text)]);
        want_table.indexes.push(Index {
            name: "idx_posts_body".to_owned(),
            columns: vec!["body".to_owned()],
            unique: false,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        });
        let plan = diff_schema(
            &[base_table],
            &parsed(vec![want_table], vec![]),
            DEFAULT_OPTS,
        );
        assert!(
            plan.changes.is_empty(),
            "model diff must retain the definition index and emit no drop/replace; got {:?}",
            plan.changes
        );
    }

    /// A model-parsed unique index over `[email]` on the `posts` table, carrying
    /// the parser's conventional name `idx_posts_email_unique` (`definition: None`).
    fn desired_posts_email_unique() -> Index {
        Index {
            name: "idx_posts_email_unique".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        }
    }

    /// Fix 1 (a): a baseline **partial** unique index that happens to carry the
    /// model's conventional name (`idx_posts_email_unique`) hits the same-NAME
    /// match branch but does NOT provide table-wide coverage. It must NOT suppress
    /// the model's `#[unique]` — the full unique `AddIndex` is emitted — while the
    /// partial index (definition-carrying) is itself RETAINED (no `DropIndex`).
    #[test]
    fn model_diff_same_named_partial_unique_does_not_suppress_and_retains_partial() {
        let partial = Index {
            name: "idx_posts_email_unique".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: Some(
                "CREATE UNIQUE INDEX idx_posts_email_unique ON posts (email) \
                 WHERE email IS NOT NULL"
                    .to_owned(),
            ),
            is_partial: true,
            key_columns: vec!["email".to_owned()],
        };
        let mut base = posts_with(vec![col("email", ColumnType::Text)]);
        base.indexes.push(partial);

        let mut want_table = posts_with(vec![col("email", ColumnType::Text)]);
        want_table.indexes.push(desired_posts_email_unique());
        let plan = diff_schema(&[base], &parsed(vec![want_table], vec![]), DEFAULT_OPTS);
        assert!(
            plan.changes.iter().any(|c| matches!(
                c,
                SchemaChange::AddIndex { index, .. }
                    if index.name == "idx_posts_email_unique" && index.definition.is_none()
            )),
            "a same-named PARTIAL unique index must not suppress the model's full \
             #[unique]; got {:?}",
            plan.changes
        );
        assert!(
            !plan
                .changes
                .iter()
                .any(|c| matches!(c, SchemaChange::DropIndex { .. })),
            "the retained partial index must not be dropped; got {:?}",
            plan.changes
        );
    }

    /// Fix 1 (b): a baseline **expression** unique index (empty `key_columns`)
    /// carrying the model's conventional name must NOT suppress the model's
    /// `#[unique]` — the full unique `AddIndex` is emitted, and the expression
    /// index is retained (no `DropIndex`).
    #[test]
    fn model_diff_same_named_expression_unique_does_not_suppress() {
        let expr = Index {
            name: "idx_posts_email_unique".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: Some(
                "CREATE UNIQUE INDEX idx_posts_email_unique ON posts (lower(email))".to_owned(),
            ),
            is_partial: false,
            key_columns: Vec::new(),
        };
        let mut base = posts_with(vec![col("email", ColumnType::Text)]);
        base.indexes.push(expr);

        let mut want_table = posts_with(vec![col("email", ColumnType::Text)]);
        want_table.indexes.push(desired_posts_email_unique());
        let plan = diff_schema(&[base], &parsed(vec![want_table], vec![]), DEFAULT_OPTS);
        assert!(
            plan.changes.iter().any(|c| matches!(
                c,
                SchemaChange::AddIndex { index, .. }
                    if index.name == "idx_posts_email_unique" && index.definition.is_none()
            )),
            "a same-named EXPRESSION unique index must not suppress the model's \
             #[unique]; got {:?}",
            plan.changes
        );
        assert!(
            !plan
                .changes
                .iter()
                .any(|c| matches!(c, SchemaChange::DropIndex { .. })),
            "the retained expression index must not be dropped; got {:?}",
            plan.changes
        );
    }

    /// Fix 1 (c) regression guard: a baseline **full plain** unique index
    /// (`definition: None`) over exactly the model's key, sharing its name, STILL
    /// suppresses the model `#[unique]` — a clean, empty plan (no `AddIndex`, no
    /// `DropIndex`).
    #[test]
    fn model_diff_same_named_full_plain_unique_still_suppresses() {
        let plain_index = Index {
            name: "idx_posts_email_unique".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        };
        let mut base = posts_with(vec![col("email", ColumnType::Text)]);
        base.indexes.push(plain_index);

        let mut want_table = posts_with(vec![col("email", ColumnType::Text)]);
        want_table.indexes.push(desired_posts_email_unique());
        let plan = diff_schema(&[base], &parsed(vec![want_table], vec![]), DEFAULT_OPTS);
        assert!(
            plan.changes.is_empty(),
            "a same-named FULL plain unique index over the same key must still \
             suppress the model #[unique]; got {:?}",
            plan.changes
        );
    }

    /// Fix 1 (d): a baseline **full constraint** (definition-carrying) unique index
    /// over exactly the model's key, sharing its name, fully covers the model
    /// `#[unique]` — so it is retained and the model index is suppressed (empty
    /// plan). This exercises the same-NAME branch's "B fully covers → suppress D"
    /// path.
    #[test]
    fn model_diff_same_named_full_constraint_unique_suppresses() {
        let constraint = Index {
            name: "idx_posts_email_unique".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: Some(
                "CREATE UNIQUE INDEX idx_posts_email_unique ON posts USING btree (email)"
                    .to_owned(),
            ),
            is_partial: false,
            key_columns: vec!["email".to_owned()],
        };
        let mut base = posts_with(vec![col("email", ColumnType::Text)]);
        base.indexes.push(constraint);

        let mut want_table = posts_with(vec![col("email", ColumnType::Text)]);
        want_table.indexes.push(desired_posts_email_unique());
        let plan = diff_schema(&[base], &parsed(vec![want_table], vec![]), DEFAULT_OPTS);
        assert!(
            plan.changes.is_empty(),
            "a same-named FULL constraint unique index that fully covers the key \
             must suppress the model #[unique] (retained, no add); got {:?}",
            plan.changes
        );
    }

    /// Introspection diff (`AUTHORITATIVE`, `definitions_authoritative: true`): a
    /// baseline-only `definition` index absent from the desired side IS a genuine
    /// drop and MUST emit `DropIndex` — this proves doctor's `database-schema-drift`
    /// / `pull --dry-run` still catches a dropped expression/partial index.
    #[test]
    fn authoritative_diff_drops_baseline_only_definition_index() {
        let mut base_table = posts_with(vec![col("body", ColumnType::Text)]);
        base_table.indexes.push(expr_index());
        let want = parsed(
            vec![posts_with(vec![col("body", ColumnType::Text)])],
            vec![],
        );
        let plan = diff_schema(&[base_table], &want, AUTHORITATIVE);
        assert_eq!(
            plan.changes,
            vec![SchemaChange::DropIndex {
                table: "posts".to_owned(),
                index: expr_index(),
            }],
            "authoritative introspection diff must report a dropped definition index as drift"
        );
    }

    #[test]
    fn add_check_emitted_but_no_drop_check() {
        let check = CheckConstraint {
            name: Some("posts_body_len".to_owned()),
            expression: "length(body) > 0".to_owned(),
        };
        // desired gains a check → AddCheck.
        let base = vec![posts_with(vec![col("body", ColumnType::Text)])];
        let mut want_table = posts_with(vec![col("body", ColumnType::Text)]);
        want_table.checks.push(check.clone());
        let plan = diff_schema(&base, &parsed(vec![want_table], vec![]), DEFAULT_OPTS);
        assert_eq!(
            plan.changes,
            vec![SchemaChange::AddCheck {
                table: "posts".to_owned(),
                check,
            }]
        );

        // baseline-only check → NO change (rule A: never drop a check).
        let mut base_table = posts_with(vec![col("body", ColumnType::Text)]);
        base_table.checks.push(CheckConstraint {
            name: Some("posts_body_len".to_owned()),
            expression: "length(body) > 0".to_owned(),
        });
        let want = parsed(
            vec![posts_with(vec![col("body", ColumnType::Text)])],
            vec![],
        );
        let plan = diff_schema(&[base_table], &want, DEFAULT_OPTS);
        assert!(
            plan.is_empty(),
            "baseline-only check must not be dropped: {plan:?}"
        );
    }

    #[test]
    fn new_table_creates() {
        let base: Vec<Table> = vec![];
        let want_table = posts_with(vec![col("body", ColumnType::Text)]);
        let plan = diff_schema(
            &base,
            &parsed(vec![want_table.clone()], vec![]),
            DEFAULT_OPTS,
        );
        assert_eq!(plan.changes, vec![SchemaChange::CreateTable(want_table)]);
    }

    #[test]
    fn missing_table_drops_carrying_baseline() {
        let base_table = posts_with(vec![col("body", ColumnType::Text)]);
        let want = parsed(vec![], vec![]);
        let plan = diff_schema(std::slice::from_ref(&base_table), &want, DEFAULT_OPTS);
        assert_eq!(plan.changes, vec![SchemaChange::DropTable(base_table)]);
    }

    #[test]
    fn key_columns_diff_by_name_not_position() {
        // Same columns, reordered → empty plan (name-keyed, not positional).
        let base = vec![posts_with(vec![
            col("a", ColumnType::Text),
            col("b", ColumnType::Int32),
        ])];
        let want = parsed(
            vec![posts_with(vec![
                col("b", ColumnType::Int32),
                col("a", ColumnType::Text),
            ])],
            vec![],
        );
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        assert!(plan.is_empty(), "reordered columns → no change: {plan:?}");
    }

    // -- 13.2 parser-gap conservatism (rules A–E) ----------------------------

    #[test]
    fn baseline_enum_check_not_dropped() {
        let mut base_table = posts_with(vec![col("status", ColumnType::Text)]);
        base_table.checks.push(CheckConstraint {
            name: Some("posts_status_check".to_owned()),
            expression: "status IN ('draft','live')".to_owned(),
        });
        // desired (parser output) has no checks.
        let want = parsed(
            vec![posts_with(vec![col("status", ColumnType::Text)])],
            vec![],
        );
        let plan = diff_schema(&[base_table], &want, DEFAULT_OPTS);
        assert!(plan.is_empty(), "rule A: enum CHECK not dropped: {plan:?}");
    }

    #[test]
    fn baseline_association_fk_not_dropped() {
        let mut author = col("author_id", ColumnType::Int64);
        author.references = Some(ForeignKey::new("users", "id"));
        let base = vec![posts_with(vec![author])];
        // desired same column, references None (parser can't resolve association FK).
        let want = parsed(
            vec![posts_with(vec![col("author_id", ColumnType::Int64)])],
            vec![],
        );
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        assert!(
            plan.is_empty(),
            "rule B: association FK not dropped: {plan:?}"
        );
    }

    #[test]
    fn baseline_non_convention_default_not_dropped() {
        let mut status = col("status", ColumnType::Text);
        status.default = Some(ColumnDefault::Sql("'draft'".to_owned()));
        let base = vec![posts_with(vec![status])];
        let want = parsed(
            vec![posts_with(vec![col("status", ColumnType::Text)])],
            vec![],
        );
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        assert!(
            plan.is_empty(),
            "rule C: non-convention default not dropped: {plan:?}"
        );
    }

    #[test]
    fn enum_skipped_column_not_dropped_via_diagnostic() {
        // baseline has an enum-ish `status` column; desired omits it but records a
        // diagnostic for Post.status → pluralize(pascal_to_snake("Post")) == "posts".
        let base = vec![posts_with(vec![col(
            "status",
            ColumnType::Enum {
                variants: vec!["draft".into(), "live".into()],
            },
        )])];
        let want = parsed(
            vec![posts_with(vec![])],
            vec![diag("Post", "posts", "status")],
        );
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        assert!(
            plan.is_empty(),
            "rules D+E: parser-skipped column not dropped: {plan:?}"
        );
    }

    #[test]
    fn custom_table_name_skipped_column_not_dropped_via_diagnostic() {
        // A managed model `#[model(table = "app_users")]` with a skipped
        // enum/assoc field records a diagnostic whose resolved `table` is the
        // CUSTOM name `app_users` — NOT the convention name `users`. The baseline
        // `app_users` carries the extra unmodelled `role` column; the suppression
        // must match on the resolved table name so the column is treated as
        // "present but unmodelled" and NOT dropped — even under
        // `--allow-destructive`, which would otherwise DROP the real column and
        // its data.
        let mut base_table = Table::new("app_users", Backend::Postgres);
        base_table.managed = true;
        let mut id = col("id", ColumnType::Int64);
        id.primary_key = true;
        base_table.columns.push(id);
        base_table.primary_key.push("id".to_owned());
        base_table.columns.push(col(
            "role",
            ColumnType::Enum {
                variants: vec!["admin".into(), "member".into()],
            },
        ));

        let mut desired_table = Table::new("app_users", Backend::Postgres);
        desired_table.managed = true;
        let mut did = col("id", ColumnType::Int64);
        did.primary_key = true;
        desired_table.columns.push(did);
        desired_table.primary_key.push("id".to_owned());

        // Model `User` → convention table `users`, but the resolved table is the
        // `#[model(table = "app_users")]` override.
        let want = parsed(vec![desired_table], vec![diag("User", "app_users", "role")]);

        // Destructive-allowed: proves the suppression, not the destructive guard,
        // is what keeps the column.
        let plan = diff_schema(&[base_table], &want, ALLOW);
        assert!(
            plan.is_empty(),
            "custom-table diagnostic must suppress the DropColumn: {plan:?}"
        );
    }

    #[test]
    fn drop_still_fires_without_matching_diagnostic() {
        // A genuinely-removed column (no diagnostic) is still a DropColumn — the
        // suppression is exact, not blanket.
        let base = vec![posts_with(vec![col("legacy", ColumnType::Text)])];
        let want = parsed(
            vec![posts_with(vec![])],
            vec![diag("Post", "posts", "something_else")],
        );
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        assert_eq!(plan.changes.len(), 1);
        assert!(matches!(plan.changes[0], SchemaChange::DropColumn { .. }));
    }

    #[test]
    fn index_on_diagnostic_skipped_column_is_not_dropped() {
        // baseline: an enum `status` column carrying a UNIQUE index. The parser
        // skips the enum field (diagnostic) so desired omits BOTH the column and
        // its index. The `DropColumn` is already suppressed; the `DropIndex` must
        // be too — otherwise the retained column silently loses its UNIQUE
        // constraint and duplicate data becomes possible.
        let mut base_table = posts_with(vec![col(
            "status",
            ColumnType::Enum {
                variants: vec!["draft".into(), "live".into()],
            },
        )]);
        base_table.indexes.push(Index {
            name: "idx_posts_status".to_owned(),
            columns: vec!["status".to_owned()],
            unique: true,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        });
        let want = parsed(
            vec![posts_with(vec![])],
            vec![diag("Post", "posts", "status")],
        );
        let plan = diff_schema(&[base_table], &want, DEFAULT_OPTS);
        assert!(
            !plan
                .changes
                .iter()
                .any(|c| matches!(c, SchemaChange::DropIndex { .. })),
            "index on a parser-skipped column must not be dropped: {plan:?}"
        );
        assert!(
            plan.is_empty(),
            "column and its index both suppressed → empty plan: {plan:?}"
        );
    }

    #[test]
    fn index_on_normal_column_still_dropped() {
        // Control: an ordinary removed index (no diagnostic) still drops — the
        // suppression is exact, not blanket.
        let idx = Index {
            name: "idx_posts_body".to_owned(),
            columns: vec!["body".to_owned()],
            unique: false,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        };
        let mut base_table = posts_with(vec![col("body", ColumnType::Text)]);
        base_table.indexes.push(idx.clone());
        let want = parsed(
            vec![posts_with(vec![col("body", ColumnType::Text)])],
            vec![],
        );
        let plan = diff_schema(&[base_table], &want, DEFAULT_OPTS);
        assert_eq!(
            plan.changes,
            vec![SchemaChange::DropIndex {
                table: "posts".to_owned(),
                index: idx,
            }]
        );
    }

    #[test]
    fn composite_index_touching_skipped_column_is_not_dropped() {
        // A composite UNIQUE index over (author_id, status) where `status` is
        // parser-skipped. If ANY column is skipped the whole drop is suppressed —
        // the parser cannot authoritatively say the index was removed, and
        // dropping it would silently lose the multi-column uniqueness.
        let mut base_table = posts_with(vec![
            col("author_id", ColumnType::Int64),
            col(
                "status",
                ColumnType::Enum {
                    variants: vec!["draft".into(), "live".into()],
                },
            ),
        ]);
        base_table.indexes.push(Index {
            name: "idx_posts_author_status".to_owned(),
            columns: vec!["author_id".to_owned(), "status".to_owned()],
            unique: true,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        });
        // desired retains `author_id` but the enum `status` is skipped (diagnostic),
        // so the parser never sees the composite index either.
        let want = parsed(
            vec![posts_with(vec![col("author_id", ColumnType::Int64)])],
            vec![diag("Post", "posts", "status")],
        );
        let plan = diff_schema(&[base_table], &want, DEFAULT_OPTS);
        assert!(
            !plan
                .changes
                .iter()
                .any(|c| matches!(c, SchemaChange::DropIndex { .. })),
            "composite index touching a skipped column must not be dropped: {plan:?}"
        );
    }

    #[test]
    fn create_table_with_diagnostic_skipped_field_is_refused() {
        // A brand-new managed table whose model has a skipped enum field parses to
        // a `Table` OMITTING that column (only a diagnostic is recorded). Emitting
        // `CREATE TABLE` from that partial output would create a table missing a
        // column the generated model queries → runtime "column does not exist". The
        // diff must surface the refused marker, and `guard_plan` must reject it
        // (with no override) naming the missing field.
        let mut new_table = Table::new("events", Backend::Postgres);
        new_table.managed = true;
        let mut id = col("id", ColumnType::Int64);
        id.primary_key = true;
        new_table.columns.push(id);
        new_table.primary_key.push("id".to_owned());
        // The `kind` enum field is skipped by the parser → not a column, only a diag.
        let want = parsed(vec![new_table], vec![diag("Event", "events", "kind")]);
        let plan = diff_schema(&[], &want, DEFAULT_OPTS);
        assert_eq!(
            plan.changes,
            vec![SchemaChange::CreateTableBlockedBySkippedField {
                table: "events".to_owned(),
                fields: vec!["kind".to_owned()],
            }],
            "a diagnostic-skipped new table must not emit CREATE TABLE: {plan:?}"
        );
        match guard_plan(&plan, DEFAULT_OPTS) {
            Err(DiffError::CreateTableWithSkippedField { table, fields }) => {
                assert_eq!(table, "events");
                assert_eq!(fields, vec!["kind".to_owned()]);
            }
            other => panic!("expected CreateTableWithSkippedField refusal, got {other:?}"),
        }
        // No override — even --allow-destructive refuses (incomplete DDL, not lossy).
        assert!(matches!(
            guard_plan(&plan, ALLOW),
            Err(DiffError::CreateTableWithSkippedField { .. })
        ));
        // The message names both the table and the missing field.
        let msg = guard_plan(&plan, DEFAULT_OPTS).unwrap_err().to_string();
        assert!(
            msg.contains("events") && msg.contains("kind"),
            "refusal message names table + field: {msg}"
        );
    }

    #[test]
    fn create_table_without_diagnostics_is_allowed() {
        // Control: a clean new managed table (no skipped fields) still emits
        // CREATE TABLE and passes the guard.
        let new_table = posts_ref_table("events", col("title", ColumnType::Text));
        let want = parsed(vec![new_table.clone()], vec![]);
        let plan = diff_schema(&[], &want, DEFAULT_OPTS);
        assert_eq!(plan.changes, vec![SchemaChange::CreateTable(new_table)]);
        assert!(
            guard_plan(&plan, DEFAULT_OPTS).is_ok(),
            "a clean new table is emittable"
        );
    }

    #[test]
    fn add_fk_to_preexisting_column_is_refused() {
        // A PRE-EXISTING generated association column (`author_id`,
        // present in the baseline with `references: None` because the parser cannot
        // see the `#[belongs_to(...)]` association FK) is changed to an explicit
        // `#[references]`. The DB may already carry the inline `posts_author_id_fkey`
        // constraint from the original association-FK generation, so emitting
        // `ADD CONSTRAINT posts_author_id_fkey` would collide → an unappliable
        // migration. The diff must surface the refused marker, never an
        // `AddForeignKey`.
        let base = vec![posts_with(vec![col("author_id", ColumnType::Int64)])];
        let mut author = col("author_id", ColumnType::Int64);
        author.references = Some(ForeignKey::new("users", "id"));
        let want = parsed(vec![posts_with(vec![author])], vec![]);
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        assert_eq!(
            plan.changes,
            vec![SchemaChange::AddForeignKeyToExistingColumn {
                table: "posts".to_owned(),
                column: "author_id".to_owned(),
            }],
            "an FK added to a pre-existing column is the refused marker, never an AddForeignKey: \
             {plan:?}"
        );
        assert!(
            !plan
                .changes
                .iter()
                .any(|c| matches!(c, SchemaChange::AddForeignKey { .. })),
            "must never emit an AddForeignKey on a pre-existing column"
        );

        // The guard refuses it — with no override (the SQL may be unappliable).
        let err = guard_plan(&plan, DEFAULT_OPTS).unwrap_err();
        assert!(
            matches!(err, DiffError::AddForeignKeyToPreexistingColumn { .. }),
            "guard refuses the pre-existing-column FK add: {err:?}"
        );
        assert!(
            err.to_string().contains("posts_author_id_fkey"),
            "the error explains the constraint-name collision: {err}"
        );
        // --allow-destructive does NOT override it (no safe way to skip a duplicate).
        assert!(matches!(
            guard_plan(&plan, ALLOW).unwrap_err(),
            DiffError::AddForeignKeyToPreexistingColumn { .. }
        ));
    }

    #[test]
    fn add_fk_on_new_column_is_allowed() {
        // Control for the case above: a BRAND-NEW FK column (absent from the baseline)
        // is safe — there is no pre-existing constraint to collide with. It arrives
        // as an `AddColumn` whose `REFERENCES` renders inline in the `ADD COLUMN`
        // (never as a separate `AddForeignKey`), so it is neither refused nor a
        // marker, and the emitted SQL carries the foreign key.
        let base = vec![posts_with(vec![])];
        let mut author = col("author_id", ColumnType::Int64);
        author.nullable = true;
        author.references = Some(ForeignKey::new("users", "id"));
        let want = parsed(vec![posts_with(vec![author.clone()])], vec![]);
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        assert_eq!(
            plan.changes,
            vec![SchemaChange::AddColumn {
                table: "posts".to_owned(),
                column: author,
            }],
            "a new FK column is a plain AddColumn, not a refused marker: {plan:?}"
        );
        // It passes the guard and emits the inline REFERENCES.
        guard_plan(&plan, DEFAULT_OPTS).expect("a new FK column is emittable");
        let up = emit_up_sql(&plan).expect("emit up");
        assert!(
            up.contains("ADD COLUMN author_id BIGINT NULL REFERENCES users(id)"),
            "the new FK column emits its inline REFERENCES: {up}"
        );
    }

    #[test]
    fn fk_retarget_is_a_refused_marker_not_a_duplicate_add() {
        // Regression: baseline `author_id` already has an explicit FK
        // to users(id); desired retargets it to accounts(id). Emitting a plain
        // `AddForeignKey` would `ADD CONSTRAINT posts_author_id_fkey` a second
        // time and collide with the baseline constraint of the same name. The diff
        // must instead surface the refused `ForeignKeyChange` marker (never an
        // `AddForeignKey`).
        let mut base_author = col("author_id", ColumnType::Int64);
        base_author.references = Some(ForeignKey::new("users", "id"));
        let base = vec![posts_with(vec![base_author])];

        let mut want_author = col("author_id", ColumnType::Int64);
        want_author.references = Some(ForeignKey::new("accounts", "id"));
        let want = parsed(vec![posts_with(vec![want_author])], vec![]);

        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        assert_eq!(
            plan.changes,
            vec![SchemaChange::ForeignKeyChange {
                table: "posts".to_owned(),
                column: "author_id".to_owned(),
                from: "users(id)".to_owned(),
                to: "accounts(id)".to_owned(),
            }],
            "an FK retarget is the refused marker, not an AddForeignKey: {plan:?}"
        );
        assert!(
            !plan
                .changes
                .iter()
                .any(|c| matches!(c, SchemaChange::AddForeignKey { .. })),
            "must never emit a duplicate AddForeignKey on retarget"
        );

        // The guard refuses it — with no override, like a PK change.
        let err = guard_plan(&plan, DEFAULT_OPTS).unwrap_err();
        assert!(
            matches!(err, DiffError::ForeignKeyChange { .. }),
            "guard refuses the retarget: {err:?}"
        );
        assert!(
            err.to_string().contains("posts_author_id_fkey"),
            "the error explains the constraint-name collision: {err}"
        );
        // --allow-destructive does NOT override it (no safe drop+recreate).
        assert!(matches!(
            guard_plan(&plan, ALLOW).unwrap_err(),
            DiffError::ForeignKeyChange { .. }
        ));
    }

    #[test]
    fn fk_unchanged_target_is_no_change() {
        // Same explicit FK on both sides → nothing to do (not a retarget marker).
        let mut base_author = col("author_id", ColumnType::Int64);
        base_author.references = Some(ForeignKey::new("users", "id"));
        let mut want_author = col("author_id", ColumnType::Int64);
        want_author.references = Some(ForeignKey::new("users", "id"));
        let plan = diff_schema(
            &[posts_with(vec![base_author])],
            &parsed(vec![posts_with(vec![want_author])], vec![]),
            DEFAULT_OPTS,
        );
        assert!(plan.is_empty(), "unchanged FK → empty plan: {plan:?}");
    }

    #[test]
    fn colliding_over_long_fk_names_get_distinct_bounded_names() {
        // Deferred item #4: a >63-byte table name plus two added FK columns whose
        // raw `{table}_{column}_fkey` names share their first 63 bytes would, under
        // plain PG truncation, collide into one duplicate relation. The bounded
        // scheme appends a hash of the FULL untruncated name, so the two now get
        // DISTINCT valid ≤63-byte names and the plan is accepted, not refused.
        let long_table = "a".repeat(60); // {table}_{col}_fkey is well over 63 bytes.
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![
                SchemaChange::AddForeignKey {
                    table: long_table.clone(),
                    column: "author_id".to_owned(),
                    foreign_key: ForeignKey::new("users", "id"),
                },
                SchemaChange::AddForeignKey {
                    table: long_table.clone(),
                    column: "editor_id".to_owned(),
                    foreign_key: ForeignKey::new("users", "id"),
                },
            ],
        };
        guard_plan(&plan, DEFAULT_OPTS).expect("distinct bounded FK names are no longer refused");

        let author = bounded_pg_identifier(&format!("{long_table}_author_id_fkey"));
        let editor = bounded_pg_identifier(&format!("{long_table}_editor_id_fkey"));
        assert!(
            author.len() <= PG_MAX_IDENTIFIER_BYTES && editor.len() <= PG_MAX_IDENTIFIER_BYTES,
            "both bounded names fit the limit: {author} / {editor}"
        );
        assert_ne!(
            author, editor,
            "the hash suffix keeps the two colliding-prefix names distinct"
        );

        let up = emit_up_sql(&plan).expect("emit up");
        assert!(up.contains(&format!("ADD CONSTRAINT {author} ")), "{up}");
        assert!(up.contains(&format!("ADD CONSTRAINT {editor} ")), "{up}");
    }

    #[test]
    fn normal_length_fk_names_are_allowed() {
        // Ordinary table/column names produce a `posts_author_id_fkey` well under
        // 63 bytes — the guard passes and the plan emits.
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddForeignKey {
                table: "posts".to_owned(),
                column: "author_id".to_owned(),
                foreign_key: ForeignKey::new("users", "id"),
            }],
        };
        assert!(
            guard_plan(&plan, DEFAULT_OPTS).is_ok(),
            "normal-length FK names must not be refused"
        );
    }

    #[test]
    fn over_long_index_name_is_refused() {
        // The same 63-byte hazard applies to generated index names emitted as
        // top-level `CREATE INDEX`. An index name over the limit is refused.
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddIndex {
                table: "posts".to_owned(),
                index: Index {
                    name: format!("idx_{}", "x".repeat(70)),
                    columns: vec!["body".to_owned()],
                    unique: false,
                    definition: None,
                    is_partial: false,
                    key_columns: Vec::new(),
                },
            }],
        };
        let err = guard_plan(&plan, DEFAULT_OPTS).unwrap_err();
        assert!(
            matches!(err, DiffError::GeneratedIdentifierTooLong { .. }),
            "over-long index name is refused: {err:?}"
        );
    }

    #[test]
    fn over_long_generated_name_is_allowed_on_sqlite() {
        // SQLite has no comparable short identifier limit, so the check is
        // Postgres-only. (AddForeignKey does not render on SQLite anyway, but the
        // guard must not refuse the plan on backend grounds.)
        let plan = MigrationPlan {
            backend: Backend::Sqlite,
            changes: vec![SchemaChange::AddIndex {
                table: "posts".to_owned(),
                index: Index {
                    name: format!("idx_{}", "x".repeat(70)),
                    columns: vec!["body".to_owned()],
                    unique: false,
                    definition: None,
                    is_partial: false,
                    key_columns: Vec::new(),
                },
            }],
        };
        assert!(
            guard_plan(&plan, DEFAULT_OPTS).is_ok(),
            "the 63-byte guard is Postgres-only"
        );
    }

    #[test]
    fn duplicate_generated_index_names_are_refused() {
        // A `#[unique] foo` field yields `idx_<table>_foo_unique` while a separate
        // field literally named `foo_unique` yields the *same* `idx_<table>_foo_unique`
        // (parse.rs). Both are within 63 bytes, so the truncation-collision path never
        // fires — but PG accepts the first `CREATE INDEX` and rejects the second as a
        // duplicate relation. The guard must refuse the plan and name the duplicate.
        let dup = "idx_posts_foo_unique".to_owned();
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![
                SchemaChange::AddIndex {
                    table: "posts".to_owned(),
                    index: Index {
                        name: dup.clone(),
                        columns: vec!["foo".to_owned()],
                        unique: true,
                        definition: None,
                        is_partial: false,
                        key_columns: Vec::new(),
                    },
                },
                SchemaChange::AddIndex {
                    table: "posts".to_owned(),
                    index: Index {
                        name: dup.clone(),
                        columns: vec!["foo_unique".to_owned()],
                        unique: false,
                        definition: None,
                        is_partial: false,
                        key_columns: Vec::new(),
                    },
                },
            ],
        };
        let err = guard_plan(&plan, DEFAULT_OPTS).unwrap_err();
        assert!(
            matches!(err, DiffError::GeneratedIdentifierTooLong { .. }),
            "an exact-duplicate generated index name is refused: {err:?}"
        );
        assert!(
            err.to_string().contains(&dup),
            "the error names the duplicated identifier: {err}"
        );
        // No override — the SQL is unappliable, not merely lossy.
        assert!(matches!(
            guard_plan(&plan, ALLOW).unwrap_err(),
            DiffError::GeneratedIdentifierTooLong { .. }
        ));
    }

    #[test]
    fn duplicate_generated_names_on_create_table_are_refused() {
        // The same collision emitted inline on a brand-new table's `CREATE TABLE`
        // (both indexes live on `table.indexes`) is likewise refused.
        let dup = "idx_posts_foo_unique".to_owned();
        let mut table = posts_with(vec![
            col("foo", ColumnType::Text),
            col("foo_unique", ColumnType::Text),
        ]);
        table.indexes = vec![
            Index {
                name: dup.clone(),
                columns: vec!["foo".to_owned()],
                unique: true,
                definition: None,
                is_partial: false,
                key_columns: Vec::new(),
            },
            Index {
                name: dup.clone(),
                columns: vec!["foo_unique".to_owned()],
                unique: false,
                definition: None,
                is_partial: false,
                key_columns: Vec::new(),
            },
        ];
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::CreateTable(table)],
        };
        let err = guard_plan(&plan, DEFAULT_OPTS).unwrap_err();
        assert!(
            matches!(err, DiffError::GeneratedIdentifierTooLong { .. }),
            "duplicate inline index names on CREATE TABLE are refused: {err:?}"
        );
        assert!(err.to_string().contains(&dup), "names the duplicate: {err}");
    }

    #[test]
    fn distinct_index_names_are_allowed() {
        // Control: two legitimately-distinct index names (both well under 63 bytes)
        // must not be treated as a collision.
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![
                SchemaChange::AddIndex {
                    table: "posts".to_owned(),
                    index: Index {
                        name: "idx_posts_foo".to_owned(),
                        columns: vec!["foo".to_owned()],
                        unique: false,
                        definition: None,
                        is_partial: false,
                        key_columns: Vec::new(),
                    },
                },
                SchemaChange::AddIndex {
                    table: "posts".to_owned(),
                    index: Index {
                        name: "idx_posts_bar".to_owned(),
                        columns: vec!["bar".to_owned()],
                        unique: false,
                        definition: None,
                        is_partial: false,
                        key_columns: Vec::new(),
                    },
                },
            ],
        };
        assert!(
            guard_plan(&plan, DEFAULT_OPTS).is_ok(),
            "distinct index names must not be refused as a collision"
        );
    }

    #[test]
    fn unique_index_add_on_existing_column_is_refused() {
        // Marking a pre-existing column `#[unique]` yields a unique `AddIndex`
        // whose only column (`email`) already existed — `CREATE UNIQUE INDEX`
        // would fail if the table's existing rows hold duplicate emails. The
        // engine cannot dedup offline, so it refuses (no override — unappliable,
        // not merely destructive).
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddIndex {
                table: "posts".to_owned(),
                index: Index {
                    name: "idx_posts_email_unique".to_owned(),
                    columns: vec!["email".to_owned()],
                    unique: true,
                    definition: None,
                    is_partial: false,
                    key_columns: Vec::new(),
                },
            }],
        };
        let err = guard_plan(&plan, DEFAULT_OPTS).unwrap_err();
        assert!(
            matches!(err, DiffError::UniqueIndexRequiresDedup { .. }),
            "a unique index on a pre-existing column is refused: {err:?}"
        );
        assert!(
            err.to_string().contains("idx_posts_email_unique") && err.to_string().contains("posts"),
            "the error names the index and table: {err}"
        );
        // No override — the SQL is unappliable, not merely lossy.
        assert!(
            matches!(
                guard_plan(&plan, ALLOW).unwrap_err(),
                DiffError::UniqueIndexRequiresDedup { .. }
            ),
            "--allow-destructive does not override an unappliable unique-index add"
        );
    }

    #[test]
    fn unique_index_add_on_new_column_is_allowed() {
        // A brand-new nullable column that also carries `#[unique]` arrives as an
        // `AddColumn` plus a unique `AddIndex` on that same new column. Every
        // existing row is NULL in the new column, and Postgres treats NULLs as
        // distinct in a unique index, so `CREATE UNIQUE INDEX` cannot conflict —
        // the plan is emittable.
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![
                SchemaChange::AddColumn {
                    table: "posts".to_owned(),
                    column: {
                        let mut c = col("email", ColumnType::Text);
                        c.nullable = true;
                        c
                    },
                },
                SchemaChange::AddIndex {
                    table: "posts".to_owned(),
                    index: Index {
                        name: "idx_posts_email_unique".to_owned(),
                        columns: vec!["email".to_owned()],
                        unique: true,
                        definition: None,
                        is_partial: false,
                        key_columns: Vec::new(),
                    },
                },
            ],
        };
        assert!(
            guard_plan(&plan, DEFAULT_OPTS).is_ok(),
            "a unique index on a newly-added column must not be refused"
        );
    }

    #[test]
    fn unique_index_on_new_table_is_allowed() {
        // A unique index on a brand-new table rides inline on `CreateTable` (an
        // empty table — no rows to conflict), never as a top-level `AddIndex`, so
        // it is never refused.
        let mut table = posts_with(vec![col("email", ColumnType::Text)]);
        table.indexes = vec![Index {
            name: "idx_posts_email_unique".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        }];
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::CreateTable(table)],
        };
        assert!(
            guard_plan(&plan, DEFAULT_OPTS).is_ok(),
            "a unique index on a brand-new table must not be refused"
        );
    }

    #[test]
    fn non_unique_index_add_on_existing_column_still_allowed() {
        // Control: a plain (non-unique) index on a pre-existing column is always
        // appliable and must still emit.
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddIndex {
                table: "posts".to_owned(),
                index: Index {
                    name: "idx_posts_email".to_owned(),
                    columns: vec!["email".to_owned()],
                    unique: false,
                    definition: None,
                    is_partial: false,
                    key_columns: Vec::new(),
                },
            }],
        };
        assert!(
            guard_plan(&plan, DEFAULT_OPTS).is_ok(),
            "a non-unique index on a pre-existing column must not be refused"
        );
    }

    // -- 13.3 guards ---------------------------------------------------------

    fn drop_column_plan() -> MigrationPlan {
        MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::DropColumn {
                table: "users".to_owned(),
                column: col("nickname", ColumnType::Text),
            }],
        }
    }

    #[test]
    fn drop_column_refused_without_flag() {
        let err = guard_plan(&drop_column_plan(), DEFAULT_OPTS).unwrap_err();
        match err {
            DiffError::Destructive { summary, ops } => {
                assert!(
                    summary.contains("users.nickname"),
                    "names the column: {summary}"
                );
                assert_eq!(
                    ops,
                    vec![DestructiveOp::Column {
                        table: "users".to_owned(),
                        column: "nickname".to_owned(),
                    }]
                );
            }
            other => panic!("expected Destructive, got {other:?}"),
        }
    }

    #[test]
    fn drop_column_allowed_with_flag() {
        assert!(guard_plan(&drop_column_plan(), ALLOW).is_ok());
    }

    #[test]
    fn drop_table_refused_then_allowed() {
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::DropTable(posts_with(vec![]))],
        };
        let err = guard_plan(&plan, DEFAULT_OPTS).unwrap_err();
        assert!(matches!(err, DiffError::Destructive { .. }));
        assert!(guard_plan(&plan, ALLOW).is_ok());
    }

    #[test]
    fn possible_rename_refused() {
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![
                SchemaChange::DropColumn {
                    table: "users".to_owned(),
                    column: col("nickname", ColumnType::Text),
                },
                SchemaChange::AddColumn {
                    table: "users".to_owned(),
                    column: col("handle", ColumnType::Text),
                },
            ],
        };
        let err = guard_plan(&plan, DEFAULT_OPTS).unwrap_err();
        match err {
            DiffError::PossibleRename {
                table,
                dropped,
                added,
            } => {
                assert_eq!(table, "users");
                assert_eq!(dropped, vec!["nickname".to_owned()]);
                assert_eq!(added, vec!["handle".to_owned()]);
                assert!(
                    err_message_mentions_renamed_from(&DiffError::PossibleRename {
                        table: "users".to_owned(),
                        dropped: vec!["nickname".to_owned()],
                        added: vec!["handle".to_owned()],
                    }),
                    "message mentions #[renamed_from]"
                );
            }
            other => panic!("expected PossibleRename, got {other:?}"),
        }
    }

    fn err_message_mentions_renamed_from(err: &DiffError) -> bool {
        err.to_string().contains("#[renamed_from]")
    }

    #[test]
    fn possible_rename_overridden_by_allow_destructive() {
        // The added `handle` is nullable so it is itself appliable — this test
        // exercises the rename→independent-drop/add override in isolation, not the
        // orthogonal required-column guard (an independent add of a NOT NULL,
        // no-default column is unappliable and is refused even under --allow-destructive;
        // see `add_not_null_column_without_default_is_refused`).
        let mut handle = col("handle", ColumnType::Text);
        handle.nullable = true;
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![
                SchemaChange::DropColumn {
                    table: "users".to_owned(),
                    column: col("nickname", ColumnType::Text),
                },
                SchemaChange::AddColumn {
                    table: "users".to_owned(),
                    column: handle,
                },
            ],
        };
        assert!(guard_plan(&plan, ALLOW).is_ok());
    }

    #[test]
    fn primary_key_change_refused() {
        // PK ["id"] → ["uuid_id"] on a both-present managed table.
        let base = vec![posts_with(vec![])];
        let mut want_table = Table::new("posts", Backend::Postgres);
        let mut uuid_id = col("uuid_id", ColumnType::Uuid);
        uuid_id.primary_key = true;
        want_table.primary_key.push("uuid_id".to_owned());
        want_table.columns.push(uuid_id);
        let plan = diff_schema(&base, &parsed(vec![want_table], vec![]), DEFAULT_OPTS);
        assert_eq!(
            plan.changes,
            vec![SchemaChange::PrimaryKeyChange {
                table: "posts".to_owned(),
            }]
        );
        let err = guard_plan(&plan, DEFAULT_OPTS).unwrap_err();
        assert!(matches!(err, DiffError::PrimaryKeyChange { .. }));
        // No override — even --allow-destructive refuses.
        let err = guard_plan(&plan, ALLOW).unwrap_err();
        assert!(matches!(err, DiffError::PrimaryKeyChange { .. }));
    }

    // -- 13.4 managed scoping ------------------------------------------------

    #[test]
    fn unmanaged_desired_table_not_created() {
        let mut t = posts_with(vec![]);
        t.managed = false;
        let plan = diff_schema(&[], &parsed(vec![t], vec![]), DEFAULT_OPTS);
        assert!(
            plan.is_empty(),
            "unmanaged desired table not created: {plan:?}"
        );
    }

    #[test]
    fn unmanaged_baseline_table_not_dropped() {
        let mut t = posts_with(vec![]);
        t.managed = false;
        let plan = diff_schema(&[t], &parsed(vec![], vec![]), DEFAULT_OPTS);
        assert!(
            plan.is_empty(),
            "unmanaged baseline table not dropped: {plan:?}"
        );
    }

    // -- 13.5 SQL emission ---------------------------------------------------

    #[test]
    fn create_table_bigserial_pk_renders_bigserial() {
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::CreateTable(posts_with(vec![col(
                "body",
                ColumnType::Text,
            )]))],
        };
        let up = emit_up_sql(&plan).expect("emit");
        assert!(
            up.contains("id BIGSERIAL PRIMARY KEY"),
            "bigserial PK: {up}"
        );
        assert!(
            !up.contains("id BIGINT"),
            "must not render BIGINT for the id PK: {up}"
        );
        assert!(up.contains("body TEXT NOT NULL"), "body column: {up}");
    }

    #[test]
    fn create_table_uuid_pk_renders_gen_random_uuid() {
        let mut t = Table::new("posts", Backend::Postgres);
        let mut id = col("id", ColumnType::Uuid);
        id.primary_key = true;
        // The model convention default — the exact string `parse::convention_default`
        // records and introspection preserves — is required for the `IdKind::Uuid`
        // shape to render.
        id.default = Some(ColumnDefault::Sql("gen_random_uuid()".to_owned()));
        t.primary_key.push("id".to_owned());
        t.columns.push(id);
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::CreateTable(t)],
        };
        let up = emit_up_sql(&plan).expect("emit");
        assert!(
            up.contains("id UUID PRIMARY KEY DEFAULT gen_random_uuid()"),
            "uuid PK: {up}"
        );
    }

    #[test]
    fn create_table_uuid_pk_renders_the_v4_expression_on_sqlite() {
        let mut t = Table::new("posts", Backend::Sqlite);
        let mut id = col("id", ColumnType::Uuid);
        id.primary_key = true;
        id.default = Some(ColumnDefault::Sql(
            autumn_schema_core::SQLITE_UUID_V4_SQL.to_owned(),
        ));
        t.primary_key.push("id".to_owned());
        t.columns.push(id);
        let plan = MigrationPlan {
            backend: Backend::Sqlite,
            changes: vec![SchemaChange::CreateTable(t)],
        };
        let up = emit_up_sql(&plan).expect("emit");
        assert!(
            up.contains("id TEXT PRIMARY KEY NOT NULL DEFAULT (lower(hex(randomblob(4)))"),
            "uuid PK: {up}"
        );
        // The shape owns the default: it is not appended a second time.
        assert_eq!(up.matches("randomblob(4)").count(), 1, "{up}");
    }

    /// `SQLite` introspection reads the generated UUID key as `TEXT`, not `Uuid`.
    /// A table rebuild from that shape must still write the key as the shape does,
    /// with the default in parentheses. A bare function call is a syntax error.
    #[test]
    fn rebuild_from_an_introspected_sqlite_uuid_key_keeps_the_parenthesized_default() {
        let mut t = Table::new("posts", Backend::Sqlite);
        let mut id = col("id", ColumnType::Text);
        id.primary_key = true;
        id.default = Some(ColumnDefault::Sql(
            autumn_schema_core::SQLITE_UUID_V4_SQL.to_owned(),
        ));
        t.primary_key.push("id".to_owned());
        t.columns.push(id);
        assert_eq!(single_pk_column(&t).map(|(_, k)| k), Some(IdKind::Uuid));
        let body = render_create_table_body("posts", &t, Backend::Sqlite);
        assert!(
            body.contains("id TEXT PRIMARY KEY NOT NULL DEFAULT (lower(hex(randomblob(4)))"),
            "{body}"
        );
        // A non-key column with the same default is parenthesized too.
        let mut other = col("ref", ColumnType::Text);
        other.default = Some(ColumnDefault::Sql(
            autumn_schema_core::SQLITE_UUID_V4_SQL.to_owned(),
        ));
        let def = render_column_def(&other, Backend::Sqlite, false);
        assert!(def.contains("DEFAULT (lower(hex(randomblob(4)))"), "{def}");
    }

    #[test]
    fn pk_kind_for_uuid_accepts_the_sqlite_convention_default() {
        let mut conv = col("id", ColumnType::Uuid);
        conv.primary_key = true;
        conv.default = Some(ColumnDefault::Sql(
            autumn_schema_core::SQLITE_UUID_V4_SQL.to_owned(),
        ));
        assert_eq!(pk_kind_for(&conv), Some(IdKind::Uuid));
    }

    #[test]
    fn pk_kind_for_uuid_is_gated_on_the_convention_default() {
        // Convention `gen_random_uuid()` default → the `IdKind::Uuid` shape.
        let mut conv = col("id", ColumnType::Uuid);
        conv.primary_key = true;
        conv.default = Some(ColumnDefault::Sql("gen_random_uuid()".to_owned()));
        assert_eq!(pk_kind_for(&conv), Some(IdKind::Uuid));
        // A leading/trailing whitespace variant still resolves (trim-tolerant).
        let mut conv_ws = col("id", ColumnType::Uuid);
        conv_ws.primary_key = true;
        conv_ws.default = Some(ColumnDefault::Sql("  gen_random_uuid()  ".to_owned()));
        assert_eq!(pk_kind_for(&conv_ws), Some(IdKind::Uuid));

        // A non-convention default (`uuid_generate_v4()`) → None (ordinary column).
        let mut v4 = col("id", ColumnType::Uuid);
        v4.primary_key = true;
        v4.default = Some(ColumnDefault::Sql("uuid_generate_v4()".to_owned()));
        assert_eq!(pk_kind_for(&v4), None);

        // No default → None (ordinary column; the PK is expressed table-level).
        let mut none = col("id", ColumnType::Uuid);
        none.primary_key = true;
        assert_eq!(pk_kind_for(&none), None);
    }

    #[test]
    fn pk_kind_for_honors_plain_serial_marker() {
        // An explicit `Some(Plain)` Int64 PK must NOT reconstruct as BigSerial (that
        // would fabricate auto-increment on a rebuild/rollback).
        let mut plain = col("id", ColumnType::Int64);
        plain.primary_key = true;
        plain.serial = Some(SerialKind::Plain);
        assert_eq!(pk_kind_for(&plain), None, "a Plain PK is a plain column");

        // A `BigSerial`-marked (or legacy `None`) Int64 PK keeps the BigSerial shape.
        let mut big = col("id", ColumnType::Int64);
        big.primary_key = true;
        big.serial = Some(SerialKind::BigSerial);
        assert_eq!(pk_kind_for(&big), Some(IdKind::BigSerial));
        let mut legacy = col("id", ColumnType::Int64);
        legacy.primary_key = true; // serial: None (legacy/unknown)
        assert_eq!(pk_kind_for(&legacy), Some(IdKind::BigSerial));
    }

    #[test]
    fn plain_pk_reconstructs_without_bigserial_or_autoincrement() {
        for (backend, forbidden) in [
            (Backend::Postgres, "BIGSERIAL"),
            (Backend::Sqlite, "AUTOINCREMENT"),
        ] {
            let mut t = Table::new("ledger", backend);
            let mut id = col("id", ColumnType::Int64);
            id.primary_key = true;
            id.serial = Some(SerialKind::Plain);
            t.primary_key.push("id".to_owned());
            t.columns.push(id);
            let body = render_create_table_body("ledger", &t, backend);
            assert!(
                !body.contains(forbidden),
                "a Plain PK must not render {forbidden} on {backend:?}: {body}"
            );
            assert!(
                body.contains("PRIMARY KEY (id)"),
                "a Plain PK renders a table-level primary key on {backend:?}: {body}"
            );
        }
    }

    // -- SQLite affinity-aware type comparison -------------------------------

    #[test]
    fn sqlite_type_comparison_is_affinity_aware_but_pg_stays_exact() {
        // On SQLite, types that collapse to the same declared type are equivalent.
        for (a, b) in [
            (ColumnType::Int32, ColumnType::Int64),
            (ColumnType::Int64, ColumnType::Bool),
            (ColumnType::Float32, ColumnType::Float64),
            (ColumnType::Text, ColumnType::Timestamp),
            (ColumnType::Timestamp, ColumnType::TimestampTz),
        ] {
            assert!(
                column_types_equivalent(&a, &b, Backend::Sqlite),
                "{a:?} and {b:?} share a SQLite affinity class"
            );
            // Postgres keeps exact equality — these are genuinely distinct there.
            assert!(
                !column_types_equivalent(&a, &b, Backend::Postgres),
                "{a:?} vs {b:?} must still differ on Postgres"
            );
        }
        // A genuine class change still drifts on SQLite.
        assert!(!column_types_equivalent(
            &ColumnType::Int64,
            &ColumnType::Text,
            Backend::Sqlite
        ));
        assert!(!column_types_equivalent(
            &ColumnType::Bytes,
            &ColumnType::Text,
            Backend::Sqlite
        ));
        // Opaque (verbatim) types require exact equality even on SQLite.
        let a = ColumnType::Opaque {
            pg_type: "citext".to_owned(),
        };
        let b = ColumnType::Opaque {
            pg_type: "hstore".to_owned(),
        };
        assert!(!column_types_equivalent(&a, &b, Backend::Sqlite));
        assert!(column_types_equivalent(&a, &a.clone(), Backend::Sqlite));
    }

    #[test]
    fn attachment_and_json_are_equivalent_on_both_backends_despite_introspection_ambiguity() {
        // Issue #1341 (review): a model's `serde_json::Value` field parses to
        // `ColumnType::Json`, but Postgres introspection of the SAME physical
        // `JSONB` column always resolves to `ColumnType::Attachment`
        // (`from_pg_introspection` cannot tell a `json` field from an
        // `Attachment` blob apart — see its doc comment). Without this
        // exception, every diff of a model with a `json` field would report a
        // permanent, spurious `Attachment -> Json` type change on Postgres.
        assert!(column_types_equivalent(
            &ColumnType::Attachment,
            &ColumnType::Json,
            Backend::Postgres
        ));
        assert!(column_types_equivalent(
            &ColumnType::Json,
            &ColumnType::Attachment,
            Backend::Postgres
        ));
        // Also holds on SQLite (both render TEXT there — already covered by
        // the affinity rule, but assert it directly so this exception can't
        // silently regress if the affinity mapping ever changes).
        assert!(column_types_equivalent(
            &ColumnType::Attachment,
            &ColumnType::Json,
            Backend::Sqlite
        ));
        // A genuinely different type is still NOT equivalent to either.
        assert!(!column_types_equivalent(
            &ColumnType::Attachment,
            &ColumnType::Text,
            Backend::Postgres
        ));
        assert!(!column_types_equivalent(
            &ColumnType::Json,
            &ColumnType::Text,
            Backend::Postgres
        ));
    }

    #[test]
    fn pg_diff_reports_no_alter_between_attachment_and_json() {
        // End-to-end: a `json` model field diffed against a pulled `Attachment`
        // column (both physically `JSONB`) must not emit `AlterColumnType`.
        let mut base = Table::new("posts", Backend::Postgres);
        base.managed = true;
        base.columns.push(col("meta", ColumnType::Attachment));
        let mut want = Table::new("posts", Backend::Postgres);
        want.managed = true;
        want.columns.push(col("meta", ColumnType::Json));
        let plan = diff_schema(
            std::slice::from_ref(&base),
            &parsed(vec![want], vec![]),
            AUTHORITATIVE,
        );
        assert!(
            !plan
                .changes
                .iter()
                .any(|c| matches!(c, SchemaChange::AlterColumnType { .. })),
            "Attachment vs Json on the same JSONB column must not drift: {:?}",
            plan.changes
        );

        // A genuine type change (Json -> Text) still drifts.
        let mut want2 = Table::new("posts", Backend::Postgres);
        want2.managed = true;
        want2.columns.push(col("meta", ColumnType::Text));
        let plan2 = diff_schema(&[base], &parsed(vec![want2], vec![]), AUTHORITATIVE);
        assert!(
            plan2
                .changes
                .iter()
                .any(|c| matches!(c, SchemaChange::AlterColumnType { .. })),
            "a genuine type change must still drift on Postgres: {:?}",
            plan2.changes
        );
    }

    #[test]
    fn sqlite_diff_no_alter_within_affinity_class_but_drifts_across() {
        // Baseline `views: Int64` (pulled), model `views: Int32` — same INTEGER class
        // on SQLite → NO AlterColumnType.
        let mut base = Table::new("posts", Backend::Sqlite);
        base.managed = true;
        base.columns.push(col("views", ColumnType::Int64));
        let mut want = Table::new("posts", Backend::Sqlite);
        want.managed = true;
        want.columns.push(col("views", ColumnType::Int32));
        let plan = diff_schema(
            std::slice::from_ref(&base),
            &parsed(vec![want], vec![]),
            AUTHORITATIVE,
        );
        assert!(
            !plan
                .changes
                .iter()
                .any(|c| matches!(c, SchemaChange::AlterColumnType { .. })),
            "same-class INTEGER change must not drift on SQLite: {:?}",
            plan.changes
        );

        // A cross-class change (Int64 → Text) still drifts.
        let mut want2 = Table::new("posts", Backend::Sqlite);
        want2.managed = true;
        want2.columns.push(col("views", ColumnType::Text));
        let plan2 = diff_schema(&[base], &parsed(vec![want2], vec![]), AUTHORITATIVE);
        assert!(
            plan2
                .changes
                .iter()
                .any(|c| matches!(c, SchemaChange::AlterColumnType { .. })),
            "a cross-class change must still drift on SQLite: {:?}",
            plan2.changes
        );
    }

    /// A convention UUID PK (`DEFAULT gen_random_uuid()`) renders the `IdKind::Uuid`
    /// shape verbatim — the `gen_random_uuid()` default is not double-emitted.
    #[test]
    fn create_table_convention_uuid_pk_renders_id_kind_shape() {
        let mut t = Table::new("sessions", Backend::Postgres);
        let mut id = col("id", ColumnType::Uuid);
        id.primary_key = true;
        id.default = Some(ColumnDefault::Sql("gen_random_uuid()".to_owned()));
        t.primary_key.push("id".to_owned());
        t.columns.push(id);
        let body = render_create_table_body("sessions", &t, Backend::Postgres);
        assert!(
            body.contains("id UUID PRIMARY KEY DEFAULT gen_random_uuid()"),
            "convention UUID PK renders the IdKind::Uuid shape: {body}"
        );
        // Exactly one `gen_random_uuid()` — the explicit column default is not also
        // appended alongside the `IdKind::Uuid` shape's own default.
        assert_eq!(
            body.matches("gen_random_uuid()").count(),
            1,
            "the convention default is emitted exactly once: {body}"
        );
    }

    /// A UUID PK with NO default must NOT gain a `gen_random_uuid()` default on
    /// recreation: it renders as an ordinary `UUID` column plus a table-level
    /// `PRIMARY KEY (id)` clause, preserving "no default".
    #[test]
    fn create_table_uuid_pk_without_default_renders_ordinary_column_with_pk() {
        let mut t = Table::new("tokens", Backend::Postgres);
        let mut id = col("id", ColumnType::Uuid);
        id.primary_key = true;
        t.primary_key.push("id".to_owned());
        t.columns.push(id);
        t.columns.push(col("label", ColumnType::Text));
        let body = render_create_table_body("tokens", &t, Backend::Postgres);
        assert!(
            body.contains("id UUID NOT NULL"),
            "no-default UUID PK renders as an ordinary UUID column: {body}"
        );
        assert!(
            !body.contains("gen_random_uuid()"),
            "no default must be invented on recreation: {body}"
        );
        assert!(
            body.contains("PRIMARY KEY (id)"),
            "the PK is still expressed via the table-level clause: {body}"
        );
    }

    /// A brownfield UUID PK whose default is a NON-convention expression
    /// (`uuid_generate_v4()`) renders that default verbatim — recreation preserves the
    /// real UUID-generation behavior rather than silently swapping it for
    /// `gen_random_uuid()`.
    #[test]
    fn create_table_uuid_pk_with_non_convention_default_renders_it_verbatim() {
        let mut t = Table::new("tokens", Backend::Postgres);
        let mut id = col("id", ColumnType::Uuid);
        id.primary_key = true;
        id.default = Some(ColumnDefault::Sql("uuid_generate_v4()".to_owned()));
        t.primary_key.push("id".to_owned());
        t.columns.push(id);
        let body = render_create_table_body("tokens", &t, Backend::Postgres);
        assert!(
            body.contains("id UUID NOT NULL DEFAULT uuid_generate_v4()"),
            "the real non-convention default renders verbatim: {body}"
        );
        assert!(
            !body.contains("gen_random_uuid()"),
            "the convention default is never substituted: {body}"
        );
        assert!(
            body.contains("PRIMARY KEY (id)"),
            "the PK is still expressed via the table-level clause: {body}"
        );
    }

    /// A brownfield single-column `Int32` PK whose default is a `nextval(...)`
    /// sequence (a `SERIAL PRIMARY KEY`) recreates as `SERIAL PRIMARY KEY` — the
    /// explicit default is suppressed and auto-increment is preserved, mirroring the
    /// `Int64` → `BIGSERIAL` path. It must NOT render `INTEGER … DEFAULT nextval`.
    #[test]
    fn create_table_int4_serial_pk_renders_serial() {
        let mut t = Table::new("counters", Backend::Postgres);
        let mut id = col("id", ColumnType::Int32);
        id.primary_key = true;
        id.default = Some(ColumnDefault::Sql(
            "nextval('counters_id_seq'::regclass)".to_owned(),
        ));
        t.primary_key.push("id".to_owned());
        t.columns.push(id);
        t.columns.push(col("label", ColumnType::Text));
        let body = render_create_table_body("counters", &t, Backend::Postgres);
        assert!(
            body.contains("id SERIAL PRIMARY KEY"),
            "int4 SERIAL PK renders SERIAL: {body}"
        );
        assert!(
            !body.contains("nextval") && !body.contains("id INTEGER"),
            "the explicit nextval default is suppressed (no INTEGER … DEFAULT nextval): {body}"
        );
    }

    /// A single-column `Int32` PK with NO default is a plain integer PK (no
    /// auto-increment): it renders `INTEGER` with a table-level `PRIMARY KEY` clause,
    /// never `SERIAL`.
    #[test]
    fn create_table_int4_pk_without_default_renders_plain_integer() {
        let mut t = Table::new("counters", Backend::Postgres);
        let mut id = col("id", ColumnType::Int32);
        id.primary_key = true;
        t.primary_key.push("id".to_owned());
        t.columns.push(id);
        let body = render_create_table_body("counters", &t, Backend::Postgres);
        assert!(
            !body.contains("SERIAL"),
            "a plain int4 PK must not become SERIAL: {body}"
        );
        assert!(
            body.contains("id INTEGER NOT NULL") && body.contains("PRIMARY KEY (id)"),
            "a plain int4 PK renders a plain INTEGER column with a table-level PRIMARY KEY: {body}"
        );
    }

    /// The existing `Int64` PK path is unchanged: `BIGSERIAL PRIMARY KEY`.
    #[test]
    fn create_table_int8_pk_still_renders_bigserial() {
        let t = posts_with(vec![col("body", ColumnType::Text)]);
        let body = render_create_table_body("posts", &t, Backend::Postgres);
        assert!(
            body.contains("id BIGSERIAL PRIMARY KEY"),
            "int8 PK renders BIGSERIAL: {body}"
        );
    }

    #[test]
    fn create_table_composite_pk_uses_table_clause() {
        let mut t = Table::new("memberships", Backend::Postgres);
        let mut a = col("user_id", ColumnType::Int64);
        a.primary_key = true;
        let mut b = col("group_id", ColumnType::Int64);
        b.primary_key = true;
        t.columns.push(a);
        t.columns.push(b);
        t.primary_key.push("user_id".to_owned());
        t.primary_key.push("group_id".to_owned());
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::CreateTable(t)],
        };
        let up = emit_up_sql(&plan).expect("emit");
        assert!(
            up.contains("user_id BIGINT NOT NULL"),
            "columns rendered normally: {up}"
        );
        assert!(
            up.contains("PRIMARY KEY (user_id, group_id)"),
            "table-level PK: {up}"
        );
    }

    #[test]
    fn add_column_not_null_no_default_has_safety_comment() {
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddColumn {
                table: "posts".to_owned(),
                column: col("title", ColumnType::Text),
            }],
        };
        let up = emit_up_sql(&plan).expect("emit");
        assert!(
            up.contains("-- autumn-safety: potentially-blocking"),
            "safety comment: {up}"
        );
        assert!(
            up.contains("ALTER TABLE posts ADD COLUMN title TEXT NOT NULL;"),
            "{up}"
        );
    }

    #[test]
    fn add_column_nullable_no_safety_comment() {
        let mut bio = col("bio", ColumnType::Text);
        bio.nullable = true;
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddColumn {
                table: "posts".to_owned(),
                column: bio,
            }],
        };
        let up = emit_up_sql(&plan).expect("emit");
        assert!(
            !up.contains("autumn-safety"),
            "no safety comment for nullable: {up}"
        );
        assert!(
            up.contains("ALTER TABLE posts ADD COLUMN bio TEXT NULL;"),
            "{up}"
        );
    }

    #[test]
    fn add_not_null_column_without_default_is_refused() {
        // Adding a NOT NULL, no-default column to an *existing* table is unappliable
        // on a table that already has rows — refused, with no override.
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddColumn {
                table: "posts".to_owned(),
                column: col("title", ColumnType::Text),
            }],
        };
        let err = guard_plan(&plan, DEFAULT_OPTS).unwrap_err();
        match &err {
            DiffError::RequiredColumnWithoutDefault { table, column } => {
                assert_eq!(table, "posts");
                assert_eq!(column, "title");
            }
            other => panic!("expected RequiredColumnWithoutDefault, got {other:?}"),
        }
        assert!(
            err.to_string()
                .contains("cannot add required column `posts.title`"),
            "message: {err}"
        );
        // No override — --allow-destructive does not permit it (it is unappliable,
        // not merely destructive).
        assert!(
            matches!(
                guard_plan(&plan, ALLOW).unwrap_err(),
                DiffError::RequiredColumnWithoutDefault { .. }
            ),
            "must refuse even with --allow-destructive"
        );
    }

    #[test]
    fn add_not_null_column_with_default_is_allowed() {
        // A NOT NULL column WITH a default is appliable (existing rows get the
        // default) — emit it normally, do not refuse.
        let mut created = col("created_at", ColumnType::Timestamp);
        created.default = Some(ColumnDefault::Now);
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddColumn {
                table: "posts".to_owned(),
                column: created,
            }],
        };
        guard_plan(&plan, DEFAULT_OPTS).expect("NOT NULL with a default is appliable");
        let up = emit_up_sql(&plan).expect("emit");
        assert!(
            up.contains(
                "ALTER TABLE posts ADD COLUMN created_at TIMESTAMP NOT NULL DEFAULT NOW();"
            ),
            "{up}"
        );
    }

    #[test]
    fn add_nullable_column_is_allowed() {
        // A nullable added column is always appliable.
        let mut bio = col("bio", ColumnType::Text);
        bio.nullable = true;
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddColumn {
                table: "posts".to_owned(),
                column: bio,
            }],
        };
        guard_plan(&plan, DEFAULT_OPTS).expect("nullable add is appliable");
        let up = emit_up_sql(&plan).expect("emit");
        assert!(
            up.contains("ALTER TABLE posts ADD COLUMN bio TEXT NULL;"),
            "{up}"
        );
    }

    #[test]
    fn create_table_with_not_null_no_default_column_is_not_refused() {
        // A NOT NULL, no-default column inside a brand-new CreateTable is fine —
        // the table is empty — so the required-column guard must NOT fire on it.
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::CreateTable(posts_with(vec![col(
                "title",
                ColumnType::Text,
            )]))],
        };
        guard_plan(&plan, DEFAULT_OPTS).expect("CreateTable with a NOT NULL column is empty-safe");
        let up = emit_up_sql(&plan).expect("emit");
        assert!(up.contains("title TEXT NOT NULL"), "{up}");
    }

    #[test]
    fn set_not_null_on_existing_column_is_refused() {
        // Turning an existing nullable column non-null is unappliable on a table
        // whose column already holds NULLs — refused, with no override (the exact
        // sibling of the required-column refusal).
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::SetNotNull {
                table: "posts".to_owned(),
                column: "bio".to_owned(),
            }],
        };
        let err = guard_plan(&plan, DEFAULT_OPTS).unwrap_err();
        match &err {
            DiffError::SetNotNullRequiresBackfill { table, column } => {
                assert_eq!(table, "posts");
                assert_eq!(column, "bio");
            }
            other => panic!("expected SetNotNullRequiresBackfill, got {other:?}"),
        }
        assert!(
            err.to_string().contains("cannot set `posts.bio` NOT NULL"),
            "message: {err}"
        );
        // No override — --allow-destructive does not permit it (it is unappliable,
        // not merely destructive).
        assert!(
            matches!(
                guard_plan(&plan, ALLOW).unwrap_err(),
                DiffError::SetNotNullRequiresBackfill { .. }
            ),
            "must refuse even with --allow-destructive"
        );
    }

    #[test]
    fn drop_not_null_is_allowed() {
        // The inverse (non-null → nullable) is always appliable — emit it
        // normally, never refuse.
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::DropNotNull {
                table: "posts".to_owned(),
                column: "bio".to_owned(),
            }],
        };
        guard_plan(&plan, DEFAULT_OPTS).expect("DROP NOT NULL is always appliable");
        let up = emit_up_sql(&plan).expect("emit");
        assert!(
            up.contains("ALTER TABLE posts ALTER COLUMN bio DROP NOT NULL;"),
            "{up}"
        );
    }

    #[test]
    fn add_column_renders_only_the_column_not_the_index() {
        // The `AddColumn` renderer is NOT the index owner: a lone `AddColumn` for a
        // reference column emits the column + its FK clause but no `CREATE INDEX`.
        // The reference auto-index arrives as a separate `AddIndex` (see
        // `add_reference_column_emits_index_exactly_once`), so rendering it inline
        // here would double it and the migration would fail.
        let mut author = col("author_id", ColumnType::Int64);
        author.nullable = true;
        author.references = Some(ForeignKey::new("users", "id"));
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddColumn {
                table: "posts".to_owned(),
                column: author,
            }],
        };
        let up = emit_up_sql(&plan).expect("emit");
        assert!(up.contains("REFERENCES users(id)"), "fk clause: {up}");
        assert!(
            !up.contains("CREATE INDEX"),
            "the reference index is a separate AddIndex change, not inline: {up}"
        );
    }

    #[test]
    fn add_reference_column_emits_index_exactly_once() {
        // Regression: the slice-2 parser folds `idx_<t>_<c>` into
        // `table.indexes` AND the column carries `references`. Diffing a new
        // reference column onto an existing table therefore yields both an
        // `AddColumn` and an `AddIndex` for that index — the emitted up.sql must
        // contain the `CREATE INDEX` exactly once, never a duplicate.
        let base = vec![posts_with(vec![])];
        let mut author = col("author_id", ColumnType::Int64);
        author.nullable = true;
        author.references = Some(ForeignKey::new("users", "id"));
        let mut want_table = posts_with(vec![author]);
        want_table.indexes.push(Index {
            name: "idx_posts_author_id".to_owned(),
            columns: vec!["author_id".to_owned()],
            unique: false,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        });
        let plan = diff_schema(&base, &parsed(vec![want_table], vec![]), DEFAULT_OPTS);
        let up = emit_up_sql(&plan).expect("emit");
        assert_eq!(
            up.matches("CREATE INDEX idx_posts_author_id").count(),
            1,
            "the reference index must be emitted exactly once: {up}"
        );
        // And the column itself is still added.
        assert!(
            up.contains("ALTER TABLE posts ADD COLUMN author_id BIGINT NULL REFERENCES users(id);"),
            "the column is still added: {up}"
        );
    }

    #[test]
    fn alter_type_and_set_not_null_templates() {
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![
                SchemaChange::AlterColumnType {
                    table: "posts".to_owned(),
                    column: "views".to_owned(),
                    from: ColumnType::Int32,
                    to: ColumnType::Int64,
                },
                SchemaChange::SetNotNull {
                    table: "posts".to_owned(),
                    column: "views".to_owned(),
                },
            ],
        };
        let up = emit_up_sql(&plan).expect("emit");
        assert!(
            up.contains("ALTER TABLE posts ALTER COLUMN views TYPE BIGINT;"),
            "{up}"
        );
        assert!(
            up.contains("ALTER TABLE posts ALTER COLUMN views SET NOT NULL;"),
            "{up}"
        );
    }

    #[test]
    fn create_unique_index_and_drop_index_templates() {
        let up = index_sql(
            "posts",
            &Index {
                name: "idx_posts_slug_unique".to_owned(),
                columns: vec!["slug".to_owned()],
                unique: true,
                definition: None,
                is_partial: false,
                key_columns: Vec::new(),
            },
        );
        assert_eq!(
            up,
            "CREATE UNIQUE INDEX idx_posts_slug_unique ON posts (slug);"
        );

        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::DropIndex {
                table: "posts".to_owned(),
                index: Index {
                    name: "idx_posts_slug".to_owned(),
                    columns: vec!["slug".to_owned()],
                    unique: false,
                    definition: None,
                    is_partial: false,
                    key_columns: Vec::new(),
                },
            }],
        };
        // DropIndex is not destructive, so it emits without a guard.
        let sql = emit_up_sql(&plan).expect("emit");
        assert_eq!(sql, "DROP INDEX idx_posts_slug;\n");
    }

    #[test]
    fn up_ordering_is_canonical() {
        // A mixed plan should render create → add col → drop col → drop table.
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![
                SchemaChange::DropTable(Table::new("legacy", Backend::Postgres)),
                SchemaChange::DropColumn {
                    table: "posts".to_owned(),
                    column: col("old", ColumnType::Text),
                },
                SchemaChange::AddIndex {
                    table: "posts".to_owned(),
                    index: Index {
                        name: "idx_posts_new".to_owned(),
                        columns: vec!["new".to_owned()],
                        unique: false,
                        definition: None,
                        is_partial: false,
                        key_columns: Vec::new(),
                    },
                },
                SchemaChange::AddColumn {
                    table: "posts".to_owned(),
                    column: {
                        let mut c = col("new", ColumnType::Text);
                        c.nullable = true;
                        c
                    },
                },
                SchemaChange::CreateTable(posts_with(vec![])),
            ],
        };
        let up = emit_up_sql(&plan).expect("emit");
        let create = up.find("CREATE TABLE posts").expect("create present");
        let add = up.find("ADD COLUMN new").expect("add present");
        let index = up.find("idx_posts_new").expect("index present");
        let drop_col = up.find("DROP COLUMN old").expect("drop col present");
        let drop_table = up.find("DROP TABLE legacy").expect("drop table present");
        assert!(create < add, "create before add");
        assert!(add < index, "add before index");
        assert!(index < drop_col, "index before drop col");
        assert!(drop_col < drop_table, "drop col before drop table");
    }

    #[test]
    fn replaced_index_drops_before_add_in_up_and_inverts_in_down() {
        // Regression: a same-named index whose shape changed becomes a
        // DropIndex(old) + AddIndex(new). In up.sql the DROP must precede the
        // CREATE (same name) or PG rejects the create; in down.sql the inverse
        // must drop the new before recreating the old.
        let old = Index {
            name: "idx_posts_slug".to_owned(),
            columns: vec!["slug".to_owned()],
            unique: false,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        };
        let new = Index {
            name: "idx_posts_slug".to_owned(),
            columns: vec!["slug".to_owned()],
            unique: true,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        };
        let mut base_table = posts_with(vec![col("slug", ColumnType::Text)]);
        base_table.indexes.push(old);
        let mut want_table = posts_with(vec![col("slug", ColumnType::Text)]);
        want_table.indexes.push(new);

        let plan = diff_schema(
            &[base_table],
            &parsed(vec![want_table], vec![]),
            DEFAULT_OPTS,
        );
        // Sanity: it really is a drop+add of the same name.
        assert_eq!(plan.changes.len(), 2, "drop+add of the same name: {plan:?}");

        let up = emit_up_sql(&plan).expect("emit");
        let drop = up
            .find("DROP INDEX idx_posts_slug;")
            .expect("up drop present");
        let create = up
            .find("CREATE UNIQUE INDEX idx_posts_slug")
            .expect("up create present");
        assert!(
            drop < create,
            "DROP must precede CREATE for a replaced index: {up}"
        );

        let down = emit_down_sql(&plan).expect("emit");
        let d_drop = down
            .find("DROP INDEX idx_posts_slug;")
            .expect("down drop present");
        let d_create = down
            .find("CREATE INDEX idx_posts_slug ON posts (slug);")
            .expect("down recreate (old, non-unique) present");
        assert!(
            d_drop < d_create,
            "down: drop the new before recreating the old: {down}"
        );
    }

    #[test]
    fn unrelated_drop_index_still_after_add_index() {
        // A DropIndex whose name is NOT re-added keeps the general (late) drop
        // bucket, so an unrelated add still renders before it.
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![
                SchemaChange::DropIndex {
                    table: "posts".to_owned(),
                    index: Index {
                        name: "idx_posts_old".to_owned(),
                        columns: vec!["old".to_owned()],
                        unique: false,
                        definition: None,
                        is_partial: false,
                        key_columns: Vec::new(),
                    },
                },
                SchemaChange::AddIndex {
                    table: "posts".to_owned(),
                    index: Index {
                        name: "idx_posts_new".to_owned(),
                        columns: vec!["new".to_owned()],
                        unique: false,
                        definition: None,
                        is_partial: false,
                        key_columns: Vec::new(),
                    },
                },
            ],
        };
        let up = emit_up_sql(&plan).expect("emit");
        let add = up.find("CREATE INDEX idx_posts_new").expect("add present");
        let drop = up.find("DROP INDEX idx_posts_old;").expect("drop present");
        assert!(
            add < drop,
            "an unrelated add still precedes an unrelated drop: {up}"
        );
    }

    #[test]
    fn create_tables_topologically_ordered_by_fk() {
        // Regression: two new managed tables where `comments`
        // references `posts`. Lexically `comments` < `posts`, so a naive sort
        // would CREATE comments (REFERENCES posts) before posts exists → invalid.
        // The referenced table must be created first, and dropped last.
        let posts = posts_with(vec![col("body", ColumnType::Text)]);
        let mut post_ref = col("post_id", ColumnType::Int64);
        post_ref.references = Some(ForeignKey::new("posts", "id"));
        let comments = posts_ref_table("comments", post_ref);

        let plan = diff_schema(&[], &parsed(vec![comments, posts], vec![]), DEFAULT_OPTS);
        let up = emit_up_sql(&plan).expect("emit");
        let p = up.find("CREATE TABLE posts").expect("posts present");
        let c = up.find("CREATE TABLE comments").expect("comments present");
        assert!(
            p < c,
            "referenced `posts` must be created before referencing `comments`: {up}"
        );

        let down = emit_down_sql(&plan).expect("emit");
        let dp = down.find("DROP TABLE posts").expect("down posts");
        let dc = down.find("DROP TABLE comments").expect("down comments");
        assert!(
            dc < dp,
            "down: drop referencing `comments` before referenced `posts`: {down}"
        );
    }

    #[test]
    fn create_table_fk_cycle_is_refused() {
        // Two new tables referencing each other via inline FKs → unsatisfiable
        // (inline REFERENCES cannot express a cycle) → refused, not invalid SQL.
        let mut a_b = col("b_id", ColumnType::Int64);
        a_b.references = Some(ForeignKey::new("b", "id"));
        let table_a = posts_ref_table("a", a_b);
        let mut b_a = col("a_id", ColumnType::Int64);
        b_a.references = Some(ForeignKey::new("a", "id"));
        let table_b = posts_ref_table("b", b_a);

        let plan = diff_schema(&[], &parsed(vec![table_a, table_b], vec![]), DEFAULT_OPTS);
        let err = emit_up_sql(&plan).unwrap_err();
        let EmitError::CyclicTableDependencies { tables } = &err else {
            panic!("expected CyclicTableDependencies, got {err:?}");
        };
        assert_eq!(
            *tables,
            vec!["a".to_owned(), "b".to_owned()],
            "names the cycle"
        );
    }

    #[test]
    fn down_add_column_inverts_to_drop_clean() {
        let mut bio = col("bio", ColumnType::Text);
        bio.nullable = true;
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddColumn {
                table: "posts".to_owned(),
                column: bio,
            }],
        };
        let down = emit_down_sql(&plan).expect("emit");
        assert_eq!(down, "ALTER TABLE posts DROP COLUMN bio;\n");
        assert!(!down.contains("irreversible"), "clean, no marker: {down}");
    }

    #[test]
    fn down_drop_column_reads_add_with_irreversible_marker() {
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::DropColumn {
                table: "posts".to_owned(),
                column: {
                    let mut c = col("nickname", ColumnType::Text);
                    c.nullable = true;
                    c
                },
            }],
        };
        let down = emit_down_sql(&plan).expect("emit");
        assert!(
            down.contains("-- irreversible: column data dropped"),
            "irreversible marker: {down}"
        );
        assert!(
            down.contains("ALTER TABLE posts ADD COLUMN nickname TEXT NULL;"),
            "re-adds from baseline: {down}"
        );
    }

    #[test]
    fn down_drop_table_recreates_with_marker() {
        let mut t = posts_with(vec![col("body", ColumnType::Text)]);
        t.indexes.push(Index {
            name: "idx_posts_body".to_owned(),
            columns: vec!["body".to_owned()],
            unique: false,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        });
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::DropTable(t)],
        };
        let down = emit_down_sql(&plan).expect("emit");
        assert!(
            down.contains("-- irreversible: table data dropped"),
            "marker: {down}"
        );
        assert!(
            down.contains("CREATE TABLE posts"),
            "recreates the table: {down}"
        );
        assert!(
            down.contains("id BIGSERIAL PRIMARY KEY"),
            "recreates PK: {down}"
        );
        assert!(
            down.contains("CREATE INDEX idx_posts_body ON posts (body);"),
            "recreates its indexes: {down}"
        );
    }

    #[test]
    fn down_alter_type_marked_irreversible() {
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AlterColumnType {
                table: "posts".to_owned(),
                column: "views".to_owned(),
                from: ColumnType::Int32,
                to: ColumnType::Int64,
            }],
        };
        let down = emit_down_sql(&plan).expect("emit");
        assert!(
            down.contains("-- irreversible: a narrowing type change"),
            "marker: {down}"
        );
        assert!(
            down.contains("ALTER TABLE posts ALTER COLUMN views TYPE INTEGER;"),
            "structural inverse restores the `from` type: {down}"
        );
    }

    #[test]
    fn down_set_default_from_none_drops_default() {
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::SetDefault {
                table: "posts".to_owned(),
                column: "created_at".to_owned(),
                to: ColumnDefault::Now,
                from: None,
            }],
        };
        let down = emit_down_sql(&plan).expect("emit");
        assert_eq!(
            down,
            "ALTER TABLE posts ALTER COLUMN created_at DROP DEFAULT;\n"
        );
    }

    #[test]
    fn down_set_default_from_some_restores_it() {
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::SetDefault {
                table: "posts".to_owned(),
                column: "status".to_owned(),
                to: ColumnDefault::Sql("'live'".to_owned()),
                from: Some(ColumnDefault::Sql("'draft'".to_owned())),
            }],
        };
        let down = emit_down_sql(&plan).expect("emit");
        assert_eq!(
            down,
            "ALTER TABLE posts ALTER COLUMN status SET DEFAULT 'draft';\n"
        );
    }

    #[test]
    fn clean_plan_down_has_no_markers() {
        let mut bio = col("bio", ColumnType::Text);
        bio.nullable = true;
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![
                SchemaChange::CreateTable(posts_with(vec![])),
                SchemaChange::AddColumn {
                    table: "posts".to_owned(),
                    column: bio,
                },
                SchemaChange::AddIndex {
                    table: "posts".to_owned(),
                    index: Index {
                        name: "idx_posts_bio".to_owned(),
                        columns: vec!["bio".to_owned()],
                        unique: false,
                        definition: None,
                        is_partial: false,
                        key_columns: Vec::new(),
                    },
                },
            ],
        };
        let down = emit_down_sql(&plan).expect("emit");
        assert!(!down.contains("irreversible"), "no markers: {down}");
        assert!(!down.contains("manual"), "no markers: {down}");
    }

    #[test]
    fn down_add_check_named_drops_constraint_unnamed_is_manual() {
        let named = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddCheck {
                table: "posts".to_owned(),
                check: CheckConstraint {
                    name: Some("posts_body_len".to_owned()),
                    expression: "length(body) > 0".to_owned(),
                },
            }],
        };
        assert_eq!(
            emit_down_sql(&named).expect("emit"),
            "ALTER TABLE posts DROP CONSTRAINT posts_body_len;\n"
        );

        let unnamed = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddCheck {
                table: "posts".to_owned(),
                check: CheckConstraint {
                    name: None,
                    expression: "length(body) > 0".to_owned(),
                },
            }],
        };
        assert!(
            emit_down_sql(&unnamed)
                .expect("emit")
                .contains("-- manual: unnamed CHECK cannot be auto-dropped"),
            "unnamed check → manual note"
        );
    }

    #[test]
    fn add_foreign_key_up_and_down() {
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddForeignKey {
                table: "posts".to_owned(),
                column: "author_id".to_owned(),
                foreign_key: ForeignKey::new("users", "id"),
            }],
        };
        let up = emit_up_sql(&plan).expect("emit");
        assert_eq!(
            up,
            "ALTER TABLE posts ADD CONSTRAINT posts_author_id_fkey \
             FOREIGN KEY (author_id) REFERENCES users(id);\n"
        );
        let down = emit_down_sql(&plan).expect("emit");
        assert_eq!(
            down,
            "ALTER TABLE posts DROP CONSTRAINT posts_author_id_fkey;\n"
        );
    }

    /// A `SQLite`-tagged table: a `BigSerial` `id` PK plus the given extra columns
    /// and indexes.
    fn sqlite_table(name: &str, extra: Vec<Column>, indexes: Vec<Index>) -> Table {
        let mut t = Table::new(name, Backend::Sqlite);
        let mut id = col("id", ColumnType::Int64);
        id.primary_key = true;
        t.primary_key.push("id".to_owned());
        t.columns.push(id);
        t.columns.extend(extra);
        t.indexes = indexes;
        t
    }

    /// The shared fixture for the `SQLite` rebuild golden/coalescing/real-DB tests:
    /// `posts` alters `views` `Int32` → `Int64` and adds an index on `body`.
    fn sqlite_rebuild_fixture() -> (MigrationPlan, SchemaContext) {
        let idx = Index {
            name: "idx_posts_body".to_owned(),
            columns: vec!["body".to_owned()],
            unique: false,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        };
        let baseline = sqlite_table(
            "posts",
            vec![
                col("views", ColumnType::Int32),
                col("body", ColumnType::Text),
            ],
            vec![],
        );
        let desired = sqlite_table(
            "posts",
            vec![
                col("views", ColumnType::Int64),
                col("body", ColumnType::Text),
            ],
            vec![idx.clone()],
        );
        let plan = MigrationPlan {
            backend: Backend::Sqlite,
            changes: vec![
                SchemaChange::AlterColumnType {
                    table: "posts".to_owned(),
                    column: "views".to_owned(),
                    from: ColumnType::Int32,
                    to: ColumnType::Int64,
                },
                SchemaChange::AddIndex {
                    table: "posts".to_owned(),
                    index: idx,
                },
            ],
        };
        let ctx = SchemaContext::from_tables(
            std::slice::from_ref(&desired),
            std::slice::from_ref(&baseline),
        );
        (plan, ctx)
    }

    #[test]
    fn sqlite_alter_type_renders_table_rebuild_up_golden() {
        let (plan, ctx) = sqlite_rebuild_fixture();
        let up = emit_up_sql_with_context(&plan, &ctx).expect("emit up");
        let expected = "\
-- autumn: SQLite table rebuild for `posts` — ALTER-family changes require a full table recreate.
-- Transaction semantics: this migration must run inside a single transaction (diesel wraps each
-- migration in one). NOTE: `PRAGMA foreign_keys` is a no-op inside a transaction, so the harness
-- must ensure foreign-key enforcement is disabled around the migration.
-- autumn-safety: this recreate copies columns and re-creates indexes only. DROP TABLE drops the table's TRIGGERS (not restored here); VIEWS that reference the table are not dropped and may be left dangling or block the rename — re-create triggers and repair dependent views in a manual migration.
-- autumn-safety: `PRAGMA foreign_key_check` below only REPORTS violation rows (it does not raise); the recreate copies existing values verbatim and introduces no new orphans, but the migration runner must inspect the pragma's output to treat any pre-existing orphan as an error.
PRAGMA foreign_keys=OFF;
-- preserve the AUTOINCREMENT high-water mark so IDs issued-then-deleted are never reused
CREATE TEMP TABLE _autumn_seq_posts AS SELECT seq FROM sqlite_sequence WHERE name = 'posts';
CREATE TABLE posts__autumn_new (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    views INTEGER NOT NULL,
    body TEXT NOT NULL
);
INSERT INTO posts__autumn_new (id, views, body)
    SELECT id, views, body FROM posts;
DROP TABLE posts;
PRAGMA legacy_alter_table=ON;
ALTER TABLE posts__autumn_new RENAME TO posts;
PRAGMA legacy_alter_table=OFF;
CREATE INDEX idx_posts_body ON posts (body);
UPDATE sqlite_sequence SET seq = (SELECT seq FROM _autumn_seq_posts)
    WHERE name = 'posts' AND (SELECT seq FROM _autumn_seq_posts) IS NOT NULL;
INSERT INTO sqlite_sequence (name, seq)
    SELECT 'posts', (SELECT seq FROM _autumn_seq_posts)
    WHERE (SELECT seq FROM _autumn_seq_posts) IS NOT NULL
      AND NOT EXISTS (SELECT 1 FROM sqlite_sequence WHERE name = 'posts');
DROP TABLE _autumn_seq_posts;
PRAGMA foreign_key_check;
PRAGMA foreign_keys=ON;
";
        assert_eq!(up, expected, "SQLite up rebuild golden:\n{up}");
    }

    #[test]
    fn sqlite_alter_type_renders_table_rebuild_down_golden() {
        let (plan, ctx) = sqlite_rebuild_fixture();
        let down = emit_down_sql_with_context(&plan, &ctx).expect("emit down");
        let expected = "\
-- irreversible: a SQLite table rebuild rolled back to the prior shape may not restore data lost by a narrowing type change or dropped column
-- autumn: SQLite table rebuild for `posts` — ALTER-family changes require a full table recreate.
-- Transaction semantics: this migration must run inside a single transaction (diesel wraps each
-- migration in one). NOTE: `PRAGMA foreign_keys` is a no-op inside a transaction, so the harness
-- must ensure foreign-key enforcement is disabled around the migration.
-- autumn-safety: this recreate copies columns and re-creates indexes only. DROP TABLE drops the table's TRIGGERS (not restored here); VIEWS that reference the table are not dropped and may be left dangling or block the rename — re-create triggers and repair dependent views in a manual migration.
-- autumn-safety: `PRAGMA foreign_key_check` below only REPORTS violation rows (it does not raise); the recreate copies existing values verbatim and introduces no new orphans, but the migration runner must inspect the pragma's output to treat any pre-existing orphan as an error.
PRAGMA foreign_keys=OFF;
-- preserve the AUTOINCREMENT high-water mark so IDs issued-then-deleted are never reused
CREATE TEMP TABLE _autumn_seq_posts AS SELECT seq FROM sqlite_sequence WHERE name = 'posts';
CREATE TABLE posts__autumn_new (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    views INTEGER NOT NULL,
    body TEXT NOT NULL
);
INSERT INTO posts__autumn_new (id, views, body)
    SELECT id, views, body FROM posts;
DROP TABLE posts;
PRAGMA legacy_alter_table=ON;
ALTER TABLE posts__autumn_new RENAME TO posts;
PRAGMA legacy_alter_table=OFF;
UPDATE sqlite_sequence SET seq = (SELECT seq FROM _autumn_seq_posts)
    WHERE name = 'posts' AND (SELECT seq FROM _autumn_seq_posts) IS NOT NULL;
INSERT INTO sqlite_sequence (name, seq)
    SELECT 'posts', (SELECT seq FROM _autumn_seq_posts)
    WHERE (SELECT seq FROM _autumn_seq_posts) IS NOT NULL
      AND NOT EXISTS (SELECT 1 FROM sqlite_sequence WHERE name = 'posts');
DROP TABLE _autumn_seq_posts;
PRAGMA foreign_key_check;
PRAGMA foreign_keys=ON;
";
        assert_eq!(down, expected, "SQLite down rebuild golden:\n{down}");
    }

    #[test]
    fn sqlite_down_rebuild_preserves_parser_invisible_column() {
        // A rebuild triggered by an UNRELATED change (`views` Int32 -> Int64) must,
        // on the DOWN leg, copy back a baseline column the partial parser cannot see
        // (here `status`, absent from `ctx.desired`). The post-migration table (what
        // is actually in the DB at rollback time) is `baseline + deltas`, which still
        // carries `status`, so the down-leg INSERT..SELECT source must be that shape —
        // not `ctx.desired`, whose partial view would omit `status` and lose its data.
        let mut status_baseline = col("status", ColumnType::Text);
        status_baseline.default = Some(ColumnDefault::Sql("'draft'".to_owned()));
        let baseline = sqlite_table(
            "posts",
            vec![
                col("views", ColumnType::Int32),
                col("body", ColumnType::Text),
                status_baseline,
            ],
            vec![],
        );
        // The parser's blind spot: `status` is absent from the desired view entirely.
        let desired = sqlite_table(
            "posts",
            vec![
                col("views", ColumnType::Int64),
                col("body", ColumnType::Text),
            ],
            vec![],
        );
        let plan = MigrationPlan {
            backend: Backend::Sqlite,
            changes: vec![SchemaChange::AlterColumnType {
                table: "posts".to_owned(),
                column: "views".to_owned(),
                from: ColumnType::Int32,
                to: ColumnType::Int64,
            }],
        };
        let ctx = SchemaContext::from_tables(
            std::slice::from_ref(&desired),
            std::slice::from_ref(&baseline),
        );

        let down = emit_down_sql_with_context(&plan, &ctx).expect("emit down");
        assert!(
            down.contains(
                "INSERT INTO posts__autumn_new (id, views, body, status)\n    \
                 SELECT id, views, body, status FROM posts;"
            ),
            "the down rollback copies back the parser-invisible retained column: {down}"
        );

        // Pin the up leg too: it copies from the baseline (which carries `status`) into
        // the baseline+deltas shape (which also carries it), so `status` round-trips.
        let up = emit_up_sql_with_context(&plan, &ctx).expect("emit up");
        assert!(
            up.contains(
                "INSERT INTO posts__autumn_new (id, views, body, status)\n    \
                 SELECT id, views, body, status FROM posts;"
            ),
            "the up rebuild also carries the parser-invisible retained column: {up}"
        );
    }

    #[test]
    fn postgres_alter_type_still_emits_plain_alter_column() {
        // The same logical change on Postgres emits the direct ALTER, never a rebuild.
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AlterColumnType {
                table: "posts".to_owned(),
                column: "views".to_owned(),
                from: ColumnType::Int32,
                to: ColumnType::Int64,
            }],
        };
        let up = emit_up_sql(&plan).expect("emit up");
        assert_eq!(
            up, "ALTER TABLE posts ALTER COLUMN views TYPE BIGINT;\n",
            "{up}"
        );
        assert!(!up.contains("__autumn_new"), "no rebuild on Postgres: {up}");
    }

    #[test]
    fn sqlite_rebuild_coalesces_alter_and_index_into_one_block() {
        // An AlterColumnType and an AddIndex on the same table produce exactly ONE
        // rebuild block; the index is recreated inside it (after the rename), never
        // as a separate top-level CREATE INDEX.
        let (plan, ctx) = sqlite_rebuild_fixture();
        let up = emit_up_sql_with_context(&plan, &ctx).expect("emit up");
        assert_eq!(
            up.matches("CREATE TABLE posts__autumn_new").count(),
            1,
            "exactly one rebuild block: {up}"
        );
        assert_eq!(
            up.matches("CREATE INDEX idx_posts_body").count(),
            1,
            "the index is created exactly once: {up}"
        );
        let rename = up.find("RENAME TO posts").expect("rename present");
        let index = up
            .find("CREATE INDEX idx_posts_body ON posts (body);")
            .expect("index recreated");
        assert!(
            index > rename,
            "the index is recreated as part of the rebuild, after the rename: {up}"
        );
    }

    #[test]
    fn sqlite_rebuild_copies_only_surviving_columns() {
        // A rebuild that also drops a column copies only the columns common to both
        // shapes — the dropped `legacy` column is never named in INSERT..SELECT.
        let mut legacy = col("legacy", ColumnType::Text);
        legacy.nullable = true;
        let baseline = sqlite_table(
            "posts",
            vec![col("views", ColumnType::Int32), legacy.clone()],
            vec![],
        );
        let desired = sqlite_table("posts", vec![col("views", ColumnType::Int64)], vec![]);
        let plan = MigrationPlan {
            backend: Backend::Sqlite,
            changes: vec![
                SchemaChange::AlterColumnType {
                    table: "posts".to_owned(),
                    column: "views".to_owned(),
                    from: ColumnType::Int32,
                    to: ColumnType::Int64,
                },
                SchemaChange::DropColumn {
                    table: "posts".to_owned(),
                    column: legacy,
                },
            ],
        };
        let ctx = SchemaContext::from_tables(
            std::slice::from_ref(&desired),
            std::slice::from_ref(&baseline),
        );
        let up = emit_up_sql_with_context(&plan, &ctx).expect("emit up");
        assert!(
            up.contains(
                "INSERT INTO posts__autumn_new (id, views)\n    SELECT id, views FROM posts;"
            ),
            "copies only the surviving columns: {up}"
        );
        // The dropped column is absent from the recreated table shape (and therefore
        // never copied). Match `legacy TEXT` (the column definition) specifically rather
        // than the bare substring `legacy`, which now also appears in the unrelated
        // `PRAGMA legacy_alter_table` rename guard.
        assert!(
            !up.contains("legacy TEXT"),
            "dropped column is absent from the recreated shape: {up}"
        );
    }

    #[test]
    fn sqlite_rebuild_preserves_parser_invisible_baseline_default() {
        // A rebuild triggered by an UNRELATED change (here `views` Int32 -> Int64)
        // must not silently drop a baseline facet the partial parser cannot see. The
        // baseline `status` column carries a non-convention default (`'draft'`) and
        // the table a hand-written CHECK; the desired (parser) view records neither
        // and emits NO SetDefault/DropDefault/DropCheck (the engine has no such
        // variant). Building the up-leg recreate shape from `baseline + deltas`
        // instead of the raw `desired` table preserves both.
        let mut status_baseline = col("status", ColumnType::Text);
        status_baseline.default = Some(ColumnDefault::Sql("'draft'".to_owned()));
        let mut baseline = sqlite_table(
            "posts",
            vec![col("views", ColumnType::Int32), status_baseline],
            vec![],
        );
        baseline.checks.push(CheckConstraint {
            name: None,
            expression: "length(status) > 0".to_owned(),
        });

        // The parser's blind spot: `status.default` recorded as None and the CHECK
        // absent, plus the unrelated `views` widening that triggers the rebuild.
        let desired = sqlite_table(
            "posts",
            vec![
                col("views", ColumnType::Int64),
                col("status", ColumnType::Text),
            ],
            vec![],
        );

        let plan = MigrationPlan {
            backend: Backend::Sqlite,
            changes: vec![SchemaChange::AlterColumnType {
                table: "posts".to_owned(),
                column: "views".to_owned(),
                from: ColumnType::Int32,
                to: ColumnType::Int64,
            }],
        };
        let ctx = SchemaContext::from_tables(
            std::slice::from_ref(&desired),
            std::slice::from_ref(&baseline),
        );

        let up = emit_up_sql_with_context(&plan, &ctx).expect("emit up");
        assert!(
            up.contains("status TEXT NOT NULL DEFAULT 'draft'"),
            "the parser-invisible baseline default is preserved in the recreate: {up}"
        );
        assert!(
            up.contains("CHECK (length(status) > 0)"),
            "the parser-invisible baseline CHECK is preserved in the recreate: {up}"
        );
    }

    #[test]
    fn sqlite_rebuild_without_context_is_a_clear_error() {
        // The context-free entry cannot build a rebuild; it returns a directed error
        // rather than a broken/partial rebuild.
        let (plan, _ctx) = sqlite_rebuild_fixture();
        let err = emit_up_sql(&plan).unwrap_err();
        assert!(
            matches!(err, EmitError::SqliteRebuildUnsupported { .. }),
            "missing-context rebuild is a clear error: {err:?}"
        );
        assert!(
            err.to_string().contains("emit_up_sql_with_context"),
            "the error directs the caller to the context-aware entry: {err}"
        );
    }

    #[test]
    fn sqlite_rebuild_refuses_on_staging_name_collision() {
        // A real table already named `posts__autumn_new` would be clobbered by the
        // rebuild's staging CREATE/RENAME, so the emitter refuses rather than emit
        // unappliable SQL.
        let (plan, ctx) = sqlite_rebuild_fixture();
        let collider = sqlite_table(
            "posts__autumn_new",
            vec![col("body", ColumnType::Text)],
            vec![],
        );
        let mut ctx = ctx;
        ctx.desired.insert(collider.name.clone(), collider.clone());
        ctx.baseline.insert(collider.name.clone(), collider);

        let err = emit_up_sql_with_context(&plan, &ctx).unwrap_err();
        assert!(
            matches!(err, EmitError::SqliteRebuildUnsupported { .. }),
            "staging-name collision is refused: {err:?}"
        );
        assert!(
            err.to_string().contains("posts__autumn_new") && err.to_string().contains("collides"),
            "the error names the colliding staging table: {err}"
        );
    }

    #[test]
    fn sqlite_rebuild_preserves_rows_on_real_sqlite() {
        // Exercise the generated UP rebuild against a real in-memory SQLite DB
        // (diesel's `sqlite` backend is a workspace dependency), asserting the rows
        // survive with the new shape and the integrity/foreign-key checks are clean.
        use diesel::connection::SimpleConnection as _;
        use diesel::prelude::*;

        #[derive(QueryableByName)]
        struct PostRow {
            #[diesel(sql_type = diesel::sql_types::BigInt)]
            id: i64,
            #[diesel(sql_type = diesel::sql_types::BigInt)]
            views: i64,
            #[diesel(sql_type = diesel::sql_types::Text)]
            body: String,
        }

        // `PRAGMA foreign_key_check` REPORTS violation rows (child table / rowid /
        // parent / fkid); an empty result set means no violations.
        #[derive(QueryableByName)]
        struct FkViolation {
            #[diesel(sql_type = diesel::sql_types::Text, column_name = "table")]
            _child_table: String,
        }

        // `PRAGMA integrity_check` returns a single `TEXT` row; a clean DB reports `ok`.
        #[derive(QueryableByName)]
        struct IntegrityRow {
            #[diesel(sql_type = diesel::sql_types::Text, column_name = "integrity_check")]
            status: String,
        }

        let mut conn = SqliteConnection::establish(":memory:").expect("open in-memory sqlite");
        conn.batch_execute(
            "CREATE TABLE posts (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    \
             views INTEGER NOT NULL,\n    body TEXT NOT NULL\n);\n\
             INSERT INTO posts (views, body) VALUES (3, 'hello'), (7, 'world');",
        )
        .expect("seed the original table");

        let (plan, ctx) = sqlite_rebuild_fixture();
        let up = emit_up_sql_with_context(&plan, &ctx).expect("emit up");
        conn.batch_execute(&up)
            .expect("apply the generated rebuild");

        let rows: Vec<PostRow> = diesel::sql_query("SELECT id, views, body FROM posts ORDER BY id")
            .load(&mut conn)
            .expect("query the rebuilt table");
        assert_eq!(rows.len(), 2, "both rows survived the rebuild");
        assert_eq!(
            (rows[0].id, rows[0].views, rows[0].body.as_str()),
            (1, 3, "hello")
        );
        assert_eq!(
            (rows[1].id, rows[1].views, rows[1].body.as_str()),
            (2, 7, "world")
        );

        // `PRAGMA foreign_key_check` only REPORTS violation rows — it does not raise —
        // so actually READ its output and assert it is empty, rather than firing it via
        // `batch_execute`, which discards the rows and would pass even on a violation.
        let violations: Vec<FkViolation> = diesel::sql_query("PRAGMA foreign_key_check")
            .load(&mut conn)
            .expect("run PRAGMA foreign_key_check");
        assert!(
            violations.is_empty(),
            "foreign_key_check reported {} violation row(s)",
            violations.len()
        );

        let integrity: Vec<IntegrityRow> = diesel::sql_query("PRAGMA integrity_check")
            .load(&mut conn)
            .expect("run PRAGMA integrity_check");
        assert_eq!(integrity.len(), 1, "integrity_check returns one row");
        assert_eq!(integrity[0].status, "ok", "integrity_check is clean");
    }

    #[test]
    fn sqlite_rebuild_survives_dependent_view() {
        // A SQLite view referencing the rebuilt table makes the post-`DROP TABLE` `ALTER
        // TABLE ... RENAME` fail with "error in view v: no such table: main.posts" under
        // the modern default `legacy_alter_table=OFF`. The offline emitter cannot see or
        // recreate views, so the rebuild wraps the rename with `PRAGMA
        // legacy_alter_table=ON`…`OFF`, a blind rename that does not descend into or
        // validate views, so the migration applies and the view re-validates against the
        // recreated table. This exercises the real in-transaction path — diesel wraps each
        // migration in one — to confirm the pragma is not a mid-transaction no-op like
        // `foreign_keys`.
        use diesel::connection::SimpleConnection as _;
        use diesel::prelude::*;

        #[derive(QueryableByName)]
        struct ViewRow {
            #[diesel(sql_type = diesel::sql_types::BigInt)]
            id: i64,
            #[diesel(sql_type = diesel::sql_types::Text)]
            body: String,
        }

        let mut conn = SqliteConnection::establish(":memory:").expect("open in-memory sqlite");
        conn.batch_execute(
            "CREATE TABLE posts (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    \
             views INTEGER NOT NULL,\n    body TEXT NOT NULL\n);\n\
             INSERT INTO posts (views, body) VALUES (3, 'hello');\n\
             CREATE VIEW posts_v AS SELECT id, body FROM posts;",
        )
        .expect("seed the original table and a dependent view");

        let (plan, ctx) = sqlite_rebuild_fixture();
        let up = emit_up_sql_with_context(&plan, &ctx).expect("emit up");

        // Run the generated rebuild INSIDE an explicit transaction — the real path diesel
        // uses — so a mid-transaction pragma no-op would surface here as a rename error.
        conn.transaction::<_, diesel::result::Error, _>(|conn| conn.batch_execute(&up))
            .expect("the rebuild applies inside a transaction with a dependent view present");

        // The view is still valid against the recreated table and the row survived.
        let rows: Vec<ViewRow> = diesel::sql_query("SELECT id, body FROM posts_v ORDER BY id")
            .load(&mut conn)
            .expect("the dependent view is still queryable after the rebuild");
        assert_eq!(rows.len(), 1, "the view still resolves one row");
        assert_eq!((rows[0].id, rows[0].body.as_str()), (1, "hello"));
    }

    #[test]
    fn sqlite_rebuild_uuid_pk_emits_no_sequence_preservation() {
        // A table whose single PK is `Uuid` has no `sqlite_sequence` row, so the
        // rebuild must emit none of the high-water preservation statements — those
        // apply only to `BigSerial` (`INTEGER PRIMARY KEY AUTOINCREMENT`) PKs.
        let uuid_table = |name: &str| -> Table {
            let mut t = Table::new(name, Backend::Sqlite);
            let mut id = col("id", ColumnType::Uuid);
            id.primary_key = true;
            t.primary_key.push("id".to_owned());
            t.columns.push(id);
            t.columns.push(col("body", ColumnType::Text));
            t
        };
        let baseline = uuid_table("posts");
        let desired = uuid_table("posts");
        // A default-less UUID PK is no longer the `IdKind::Uuid` convention shape
        // (that is gated on the `gen_random_uuid()` default): it resolves to `None`
        // and is rendered as an ordinary column with a table-level PK. Either way it
        // is not an autoincrement PK, so no sequence preservation is emitted.
        assert!(
            single_pk_column(&desired).is_none(),
            "a default-less UUID PK is not the IdKind::Uuid convention shape"
        );
        for leg in [RebuildLeg::Up, RebuildLeg::Down] {
            let sql = render_sqlite_rebuild("posts", &desired, &baseline, leg, &[], &[]);
            assert!(
                !sql.contains("sqlite_sequence"),
                "no sqlite_sequence statements for a Uuid PK ({leg:?}): {sql}"
            );
            assert!(
                !sql.contains("_autumn_seq_"),
                "no high-water temp table for a Uuid PK ({leg:?}): {sql}"
            );
        }
    }

    #[test]
    fn sqlite_rebuild_preserves_autoincrement_sequence() {
        // The definitive non-reuse proof: after a table recreate, an id that was
        // issued-then-deleted must NOT be handed out again. Seed ids 1..5, delete
        // 2..5 (the `sqlite_sequence` high-water stays 5), apply the generated
        // rebuild, then insert a new row and assert its id is 6 — not the reused 2.
        use diesel::connection::SimpleConnection as _;
        use diesel::prelude::*;

        #[derive(QueryableByName)]
        struct BigRow {
            #[diesel(sql_type = diesel::sql_types::BigInt, column_name = "v")]
            v: i64,
        }

        // `PRAGMA integrity_check` returns a single `TEXT` row; a clean DB reports `ok`.
        #[derive(QueryableByName)]
        struct IntegrityRow {
            #[diesel(sql_type = diesel::sql_types::Text, column_name = "integrity_check")]
            status: String,
        }

        let mut conn = SqliteConnection::establish(":memory:").expect("open in-memory sqlite");
        conn.batch_execute(
            "CREATE TABLE posts (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    \
             views INTEGER NOT NULL,\n    body TEXT NOT NULL\n);\n\
             INSERT INTO posts (views, body) VALUES \
             (1, 'a'), (2, 'b'), (3, 'c'), (4, 'd'), (5, 'e');",
        )
        .expect("seed five rows -> ids 1..5");

        // The AUTOINCREMENT high-water is 5 after five inserts.
        let seq: Vec<BigRow> =
            diesel::sql_query("SELECT seq AS v FROM sqlite_sequence WHERE name = 'posts'")
                .load(&mut conn)
                .expect("read sqlite_sequence");
        assert_eq!(seq.len(), 1, "sqlite_sequence has a row for posts");
        assert_eq!(seq[0].v, 5, "high-water is 5 before the delete");

        // Delete every row but id=1; the high-water in sqlite_sequence stays 5.
        conn.batch_execute("DELETE FROM posts WHERE id > 1;")
            .expect("delete ids 2..5");

        let (plan, ctx) = sqlite_rebuild_fixture();
        let up = emit_up_sql_with_context(&plan, &ctx).expect("emit up");
        conn.batch_execute(&up)
            .expect("apply the generated rebuild");

        // A fresh insert must NOT reuse a deleted id: the next id is 6, not 2.
        conn.batch_execute("INSERT INTO posts (views, body) VALUES (9, 'new');")
            .expect("insert a new row after the rebuild");
        let max: Vec<BigRow> = diesel::sql_query("SELECT MAX(id) AS v FROM posts")
            .load(&mut conn)
            .expect("max id after rebuild");
        assert_eq!(
            max[0].v, 6,
            "the next id after the rebuild does not reuse a deleted id"
        );

        // The surviving id=1 row is untouched by the rebuild.
        let survivors: Vec<BigRow> =
            diesel::sql_query("SELECT COUNT(*) AS v FROM posts WHERE id = 1")
                .load(&mut conn)
                .expect("count id=1");
        assert_eq!(survivors[0].v, 1, "the surviving id=1 row is intact");

        let integrity: Vec<IntegrityRow> = diesel::sql_query("PRAGMA integrity_check")
            .load(&mut conn)
            .expect("run PRAGMA integrity_check");
        assert_eq!(integrity.len(), 1, "integrity_check returns one row");
        assert_eq!(integrity[0].status, "ok", "integrity_check is clean");
    }

    #[test]
    fn sqlite_rebuild_skips_sequence_when_source_not_autoincrement() {
        // A migration that INTRODUCES autoincrement (an `id` Int32 -> Int64 primary-key
        // change) must NOT emit the `sqlite_sequence` high-water capture/restore: the
        // copy SOURCE is not AUTOINCREMENT, so there is no prior high-water to preserve,
        // and — because SQLite creates `sqlite_sequence` LAZILY — capturing from it on a
        // database with no existing AUTOINCREMENT table would fail with
        // `no such table: sqlite_sequence`, aborting an otherwise-valid migration.
        use diesel::connection::SimpleConnection as _;
        use diesel::{Connection as _, RunQueryDsl as _, SqliteConnection};

        #[derive(diesel::QueryableByName)]
        struct BigRow {
            #[diesel(sql_type = diesel::sql_types::BigInt, column_name = "v")]
            v: i64,
        }

        let int32_pk_table = |name: &str| -> Table {
            let mut t = Table::new(name, Backend::Sqlite);
            let mut id = col("id", ColumnType::Int32);
            id.primary_key = true;
            t.primary_key.push("id".to_owned());
            t.columns.push(id);
            t.columns.push(col("views", ColumnType::Int32));
            t.columns.push(col("body", ColumnType::Text));
            t
        };
        let baseline = int32_pk_table("posts");
        // The desired shape only changes the `id` column type Int32 -> Int64 (BigSerial).
        let mut desired = int32_pk_table("posts");
        desired.columns[0].ty = ColumnType::Int64;

        // Sanity: the copy source (baseline) is NOT BigSerial; the target IS.
        assert!(
            !matches!(single_pk_column(&baseline), Some((_, IdKind::BigSerial))),
            "the baseline (copy source) PK is Int32, not BigSerial"
        );
        assert!(
            matches!(single_pk_column(&desired), Some((_, IdKind::BigSerial))),
            "the target PK resolves to BigSerial"
        );

        let plan = MigrationPlan {
            backend: Backend::Sqlite,
            changes: vec![SchemaChange::AlterColumnType {
                table: "posts".to_owned(),
                column: "id".to_owned(),
                from: ColumnType::Int32,
                to: ColumnType::Int64,
            }],
        };
        let ctx = SchemaContext::from_tables(
            std::slice::from_ref(&desired),
            std::slice::from_ref(&baseline),
        );
        let up = emit_up_sql_with_context(&plan, &ctx).expect("emit up");

        // The gate is false (source not BigSerial), so no capture/restore is emitted.
        assert!(
            !up.contains("sqlite_sequence"),
            "no sqlite_sequence statements when the source is not AUTOINCREMENT:\n{up}"
        );
        assert!(
            !up.contains("_autumn_seq_"),
            "no high-water temp table when the source is not AUTOINCREMENT:\n{up}"
        );

        // Real SQLite: a fresh DB with a non-AUTOINCREMENT `posts` (`INTEGER PRIMARY KEY`
        // WITHOUT `AUTOINCREMENT`, so `sqlite_sequence` does not exist) and a seeded row.
        let mut conn = SqliteConnection::establish(":memory:").expect("open in-memory sqlite");
        conn.batch_execute(
            "CREATE TABLE posts (\n    id INTEGER PRIMARY KEY,\n    \
             views INTEGER NOT NULL,\n    body TEXT NOT NULL\n);\n\
             INSERT INTO posts (id, views, body) VALUES (1, 9, 'a');",
        )
        .expect("seed a non-AUTOINCREMENT table");

        // The generated rebuild applies without `no such table: sqlite_sequence`.
        conn.batch_execute(&up)
            .expect("apply the generated rebuild");

        // The seeded row survived the rebuild.
        let survivors: Vec<BigRow> =
            diesel::sql_query("SELECT COUNT(*) AS v FROM posts WHERE id = 1 AND views = 9")
                .load(&mut conn)
                .expect("count the surviving row");
        assert_eq!(
            survivors[0].v, 1,
            "the seeded id=1 row survives the rebuild"
        );
    }

    #[test]
    fn sqlite_create_table_and_add_column_render() {
        // CreateTable + a nullable AddColumn are within the portable `SQLite` subset.
        let mut t = Table::new("posts", Backend::Sqlite);
        let mut id = col("id", ColumnType::Int64);
        id.primary_key = true;
        t.primary_key.push("id".to_owned());
        t.columns.push(id);
        t.columns.push(col("body", ColumnType::Text));
        let mut bio = col("bio", ColumnType::Text);
        bio.nullable = true;
        let plan = MigrationPlan {
            backend: Backend::Sqlite,
            changes: vec![
                SchemaChange::CreateTable(t),
                SchemaChange::AddColumn {
                    table: "posts".to_owned(),
                    column: bio,
                },
            ],
        };
        let up = emit_up_sql(&plan).expect("emit");
        assert!(
            up.contains("id INTEGER PRIMARY KEY AUTOINCREMENT"),
            "sqlite PK: {up}"
        );
        assert!(up.contains("ADD COLUMN bio TEXT NULL"), "{up}");
    }

    // -- #2598: the SQLite decimal CHECK on the declarative lane -------------

    const PRICE: ColumnType = ColumnType::Decimal {
        precision: 10,
        scale: 2,
    };

    /// The generator's `CHECK` for `price decimal{10,2}`: the one builder both
    /// lanes share.
    fn price_check() -> String {
        crate::generate::schema_edit::sqlite_decimal_check("price", 10, 2)
    }

    /// `CREATE TABLE` and `ADD COLUMN` on `SQLite` put the generator's decimal
    /// `CHECK` on the column, byte for byte. Postgres gets `NUMERIC` and no
    /// `CHECK`.
    #[test]
    fn sqlite_decimal_column_renders_the_generator_check() {
        let table = sqlite_table("products", vec![col("price", PRICE)], vec![]);
        let mut cost = col("cost", PRICE);
        cost.nullable = true;
        let plan = MigrationPlan {
            backend: Backend::Sqlite,
            changes: vec![
                SchemaChange::CreateTable(table.clone()),
                SchemaChange::AddColumn {
                    table: "products".to_owned(),
                    column: cost,
                },
            ],
        };
        let up = emit_up_sql(&plan).expect("emit");
        assert!(
            up.contains(&format!("    price TEXT NOT NULL {}", price_check())),
            "CREATE TABLE carries the generator CHECK: {up}"
        );
        let cost_check = crate::generate::schema_edit::sqlite_decimal_check("cost", 10, 2);
        assert!(
            up.contains(&format!("ADD COLUMN cost TEXT NULL {cost_check};")),
            "ADD COLUMN carries the generator CHECK: {up}"
        );

        let mut pg_table = table;
        pg_table.backend = Backend::Postgres;
        let pg = emit_create_table(&pg_table, Backend::Postgres);
        assert!(pg.contains("price NUMERIC(10,2) NOT NULL"), "{pg}");
        assert!(!pg.contains("CHECK"), "Postgres needs no CHECK: {pg}");
    }

    /// The baseline and the model for the rebuild tests. `DROP NOT NULL` on
    /// `views` is the change: `SQLite` applies it only with a rebuild. `price`
    /// and the nullable `cost` are decimals with different shapes.
    fn decimal_rebuild_tables(price: ColumnType, cost: ColumnType) -> (Table, Table) {
        let mut cost_col = col("cost", cost);
        cost_col.nullable = true;
        let baseline = sqlite_table(
            "products",
            vec![
                col("views", ColumnType::Int64),
                col("price", price),
                cost_col,
            ],
            vec![],
        );
        let mut views = col("views", ColumnType::Int64);
        views.nullable = true;
        let mut cost_want = col(
            "cost",
            ColumnType::Decimal {
                precision: 5,
                scale: 0,
            },
        );
        cost_want.nullable = true;
        let desired = sqlite_table(
            "products",
            vec![views, col("price", PRICE), cost_want],
            vec![],
        );
        (baseline, desired)
    }

    /// The up SQL and the down SQL of the plan from `baseline` to `desired`.
    fn rebuild_legs(
        baseline: &Table,
        desired: &Table,
        changes: usize,
    ) -> [(&'static str, String); 2] {
        let plan = diff_schema(
            std::slice::from_ref(baseline),
            &parsed(vec![desired.clone()], vec![]),
            DiffOptions::default(),
        );
        assert_eq!(plan.changes.len(), changes, "{:?}", plan.changes);
        let ctx = SchemaContext::from_tables(
            std::slice::from_ref(desired),
            std::slice::from_ref(baseline),
        );
        [
            (
                "up",
                emit_up_sql_with_context(&plan, &ctx).expect("emit up"),
            ),
            (
                "down",
                emit_down_sql_with_context(&plan, &ctx).expect("emit down"),
            ),
        ]
    }

    /// A rebuild for a different change keeps the decimal `CHECK` of each
    /// column. `--dev-url` and `schema pull` read a decimal column as `TEXT`.
    /// Then the model gives the precision and scale, and the SQL tells the user
    /// that the rebuild adds the `CHECK`.
    #[test]
    fn sqlite_rebuild_keeps_the_desired_decimal_check() {
        let cost = ColumnType::Decimal {
            precision: 5,
            scale: 0,
        };
        let cost_check = crate::generate::schema_edit::sqlite_decimal_check("cost", 5, 0);
        for (price, cost, text_baseline) in [
            (PRICE, cost, false),
            (ColumnType::Text, ColumnType::Text, true),
        ] {
            let (baseline, desired) = decimal_rebuild_tables(price, cost.clone());
            for (leg, sql) in rebuild_legs(&baseline, &desired, 1) {
                assert!(
                    sql.contains(&format!("    price TEXT NOT NULL {}", price_check())),
                    "the {leg} rebuild keeps the `price` CHECK: {sql}"
                );
                assert!(
                    sql.contains(&format!("    cost TEXT NULL {cost_check}")),
                    "the {leg} rebuild keeps the `cost` CHECK: {sql}"
                );
                assert_eq!(
                    sql.contains(
                        "-- autumn-safety: this recreate writes a new decimal CHECK for column(s) price, cost."
                    ),
                    text_baseline,
                    "the {leg} rebuild tells the user only when it adds a CHECK: {sql}"
                );
            }
        }
    }

    /// On `SQLite`, a different decimal precision or scale is a type change.
    /// Both are `TEXT`, but the `CHECK` is different. The up leg writes the new
    /// `CHECK`, and the down leg writes the old `CHECK` again.
    #[test]
    fn sqlite_decimal_shape_change_is_a_type_change() {
        let old = ColumnType::Decimal {
            precision: 12,
            scale: 2,
        };
        let old_check = crate::generate::schema_edit::sqlite_decimal_check("price", 12, 2);
        let baseline = sqlite_table("products", vec![col("price", old)], vec![]);
        let desired = sqlite_table("products", vec![col("price", PRICE)], vec![]);
        let [(_, up), (_, down)] = rebuild_legs(&baseline, &desired, 1);
        assert!(up.contains(&price_check()), "{up}");
        assert!(!up.contains(&old_check), "{up}");
        assert!(down.contains(&old_check), "{down}");
        assert!(!down.contains(&price_check()), "{down}");
        for sql in [&up, &down] {
            assert!(
                sql.contains("writes a new decimal CHECK for column(s) price."),
                "the SQL does not tell the user about the new CHECK: {sql}"
            );
        }
    }

    /// A decimal column that the parser skipped (a bad `#[decimal_shape]`) has
    /// no desired precision and scale. The rebuild refuses: a `CHECK` from the
    /// baseline values can be wrong, and a `TEXT` baseline gives no `CHECK`.
    #[test]
    fn sqlite_rebuild_refuses_a_skipped_decimal_column() {
        let stale = ColumnType::Decimal {
            precision: 12,
            scale: 2,
        };
        let skipped = SchemaDiagnostic {
            rust_type: "rust_decimal::Decimal".to_owned(),
            ..diag("Product", "products", "price")
        };
        for baseline_ty in [stale, ColumnType::Text] {
            let baseline = sqlite_table(
                "products",
                vec![col("views", ColumnType::Int64), col("price", baseline_ty)],
                vec![],
            );
            let mut views = col("views", ColumnType::Int64);
            views.nullable = true;
            let desired = parsed(
                vec![sqlite_table("products", vec![views], vec![])],
                vec![skipped.clone()],
            );
            let plan = diff_schema(
                std::slice::from_ref(&baseline),
                &desired,
                DiffOptions::default(),
            );
            let ctx = SchemaContext::from_tables(&desired.tables, std::slice::from_ref(&baseline))
                .with_skipped_decimals(&desired);
            for result in [
                emit_up_sql_with_context(&plan, &ctx),
                emit_down_sql_with_context(&plan, &ctx),
            ] {
                let err = result.expect_err("the rebuild did not refuse");
                assert!(
                    matches!(err, EmitError::SqliteRebuildUnsupported { .. }),
                    "{err:?}"
                );
                assert!(err.to_string().contains("`price`"), "{err}");
            }
        }
    }

    /// A column that the parser skipped for a different reason (an enum) does
    /// not block the rebuild.
    #[test]
    fn sqlite_rebuild_allows_a_skipped_non_decimal_column() {
        let baseline = sqlite_table(
            "products",
            vec![
                col("views", ColumnType::Int64),
                col("status", ColumnType::Text),
            ],
            vec![],
        );
        let mut views = col("views", ColumnType::Int64);
        views.nullable = true;
        let desired = parsed(
            vec![sqlite_table("products", vec![views], vec![])],
            vec![SchemaDiagnostic {
                rust_type: "ProductStatus".to_owned(),
                ..diag("Product", "products", "status")
            }],
        );
        let plan = diff_schema(
            std::slice::from_ref(&baseline),
            &desired,
            DiffOptions::default(),
        );
        let ctx = SchemaContext::from_tables(&desired.tables, std::slice::from_ref(&baseline))
            .with_skipped_decimals(&desired);
        emit_up_sql_with_context(&plan, &ctx).expect("emit up");
        emit_down_sql_with_context(&plan, &ctx).expect("emit down");
    }

    /// The model precision and scale replace only a baseline type of the same
    /// storage class. A real type change (`INTEGER` to `TEXT`) keeps the
    /// baseline type in the down leg.
    #[test]
    fn sqlite_rebuild_down_leg_keeps_a_changed_column_type() {
        let baseline = sqlite_table("products", vec![col("price", ColumnType::Int64)], vec![]);
        let desired = sqlite_table("products", vec![col("price", PRICE)], vec![]);
        let [(_, up), (_, down)] = rebuild_legs(&baseline, &desired, 1);
        assert!(up.contains(&price_check()), "the up leg has no CHECK: {up}");
        assert!(up.contains("writes a new decimal CHECK"), "{up}");
        assert!(down.contains("    price INTEGER NOT NULL"), "{down}");
        assert!(!down.contains("CHECK"), "the down leg has a CHECK: {down}");
    }

    /// `ADD COLUMN` with the decimal `CHECK` applies to a table with rows, and
    /// the new column then rejects what the `CHECK` rejects.
    #[test]
    fn sqlite_add_decimal_column_applies_on_real_sqlite() {
        use diesel::connection::SimpleConnection as _;
        use diesel::prelude::*;

        let mut conn = SqliteConnection::establish(":memory:").expect("in-memory sqlite");
        conn.batch_execute(
            "CREATE TABLE products (id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL);\n\
             INSERT INTO products (title) VALUES ('a'), ('b');",
        )
        .expect("seed");
        let mut price = col("price", PRICE);
        price.nullable = true;
        let up = emit_up_sql(&MigrationPlan {
            backend: Backend::Sqlite,
            changes: vec![SchemaChange::AddColumn {
                table: "products".to_owned(),
                column: price,
            }],
        })
        .expect("emit");
        conn.batch_execute(&up).expect("apply ADD COLUMN");
        let insert = |conn: &mut SqliteConnection, value: &str| {
            conn.batch_execute(&format!(
                "INSERT INTO products (title, price) VALUES ('c', {value});"
            ))
            .is_ok()
        };
        assert!(insert(&mut conn, "'19.99'"), "the CHECK rejects '19.99'");
        assert!(insert(&mut conn, "NULL"), "the CHECK rejects NULL");
        for value in crate::generate::schema_edit::SQLITE_DECIMAL_10_2_REJECTS {
            assert!(
                !insert(&mut conn, &format!("'{value}'")),
                "the CHECK accepts '{value}'"
            );
        }
        assert!(
            !insert(&mut conn, "x'31392e3939'"),
            "the CHECK accepts a blob"
        );
    }

    #[test]
    fn sqlite_add_not_null_without_default_is_unsupported() {
        let plan = MigrationPlan {
            backend: Backend::Sqlite,
            changes: vec![SchemaChange::AddColumn {
                table: "posts".to_owned(),
                column: col("title", ColumnType::Text),
            }],
        };
        assert!(matches!(
            emit_up_sql(&plan).unwrap_err(),
            EmitError::UnsupportedOnBackend { .. }
        ));
    }

    #[test]
    fn down_drops_fk_column_before_dropping_referenced_table() {
        // Deferred item #1: baseline `posts(id)` only; desired adds a `target` table
        // plus `posts.target_id` (nullable FK → target.id). The down leg must DROP
        // COLUMN target_id BEFORE DROP TABLE target, else the rollback is unappliable.
        // Pins `emit_down_sql` as a pure reverse of `up_ordered` for the create-table
        // + add-FK-column pattern.
        let baseline = vec![posts_with(vec![])];

        let mut target_id = col("target_id", ColumnType::Int64);
        target_id.nullable = true;
        target_id.references = Some(ForeignKey::new("target", "id"));
        let desired_posts = posts_with(vec![target_id]);

        let mut target = Table::new("target", Backend::Postgres);
        let mut tid = col("id", ColumnType::Int64);
        tid.primary_key = true;
        target.primary_key.push("id".to_owned());
        target.columns.push(tid);

        let desired = parsed(vec![desired_posts, target], vec![]);
        let plan = diff_schema(&baseline, &desired, DEFAULT_OPTS);
        guard_plan(&plan, DEFAULT_OPTS).expect("emittable");
        let down = emit_down_sql(&plan).expect("emit down");

        let drop_col = down
            .find("ALTER TABLE posts DROP COLUMN target_id")
            .expect("down drops the FK column");
        let drop_table = down
            .find("DROP TABLE target")
            .expect("down drops the referenced table");
        assert!(
            drop_col < drop_table,
            "DROP COLUMN target_id must precede DROP TABLE target:\n{down}"
        );
    }

    #[test]
    fn over_long_fkey_constraint_name_is_bounded_not_refused() {
        // Deferred item #4: an engine-generated FK-constraint name over 63 bytes is
        // truncate+hashed to a valid ≤63-byte identifier — the SAME name in the up
        // ADD and the down DROP — and the guard no longer refuses it.
        let table = "a".repeat(40);
        let column = "b".repeat(40);
        let raw = format!("{table}_{column}_fkey");
        assert!(
            raw.len() > PG_MAX_IDENTIFIER_BYTES,
            "the raw name is over the limit"
        );

        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddForeignKey {
                table,
                column,
                foreign_key: ForeignKey::new("targets", "id"),
            }],
        };
        guard_plan(&plan, DEFAULT_OPTS)
            .expect("the length guard no longer refuses a bounded FK name");

        let bounded = bounded_pg_identifier(&raw);
        assert!(
            bounded.len() <= PG_MAX_IDENTIFIER_BYTES,
            "the bounded name fits the limit: {bounded}"
        );
        assert_ne!(bounded, raw, "the over-long name is actually shortened");

        let up = emit_up_sql(&plan).expect("emit up");
        let down = emit_down_sql(&plan).expect("emit down");
        assert!(
            up.contains(&format!("ADD CONSTRAINT {bounded} ")),
            "up uses the bounded name: {up}"
        );
        assert!(
            down.contains(&format!("DROP CONSTRAINT {bounded};")),
            "down uses the SAME bounded name: {down}"
        );
    }

    #[test]
    fn short_fkey_constraint_name_is_unchanged() {
        // A normal (short) FK-constraint name passes through unchanged, so Postgres
        // output stays byte-stable.
        assert_eq!(
            bounded_pg_identifier("posts_author_id_fkey"),
            "posts_author_id_fkey"
        );
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddForeignKey {
                table: "posts".to_owned(),
                column: "author_id".to_owned(),
                foreign_key: ForeignKey::new("users", "id"),
            }],
        };
        let up = emit_up_sql(&plan).expect("emit up");
        assert!(
            up.contains(
                "ADD CONSTRAINT posts_author_id_fkey FOREIGN KEY (author_id) REFERENCES users(id);"
            ),
            "{up}"
        );
        let down = emit_down_sql(&plan).expect("emit down");
        assert!(
            down.contains("DROP CONSTRAINT posts_author_id_fkey;"),
            "{down}"
        );
    }

    #[test]
    fn describe_plan_lists_each_change() {
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![
                SchemaChange::CreateTable(posts_with(vec![])),
                SchemaChange::AddColumn {
                    table: "posts".to_owned(),
                    column: col("body", ColumnType::Text),
                },
            ],
        };
        let text = describe_plan(&plan);
        assert!(text.contains("postgres"), "names the backend: {text}");
        assert!(text.contains("2 change(s)"), "counts changes: {text}");
        assert!(text.contains("CREATE TABLE posts"), "{text}");
        assert!(text.contains("ADD COLUMN posts.body"), "{text}");
    }

    // -- 13.6 Codex round-2 regressions -------------------------------------

    /// Finding A: dropping a table while a RETAINED table still holds a baseline
    /// FK to it emits an unappliable `DROP TABLE`. Must be refused — even under
    /// `--allow-destructive` (that flag permits losing the dropped table's own
    /// data, not breaking another table's referential integrity).
    #[test]
    fn drop_table_with_retained_inbound_fk_is_refused_even_with_allow_destructive() {
        // baseline: users (dropped) + posts (retained) with posts.user_id → users.
        let users = Table::new("users", Backend::Postgres);
        let mut user_fk = col("user_id", ColumnType::Int64);
        user_fk.references = Some(ForeignKey::new("users", "id"));
        let posts = posts_ref_table("posts", user_fk);
        let baseline = vec![users, posts.clone()];
        // desired keeps posts unchanged; users is gone.
        let plan = diff_schema(&baseline, &parsed(vec![posts], vec![]), ALLOW);
        let err = guard_plan(&plan, ALLOW)
            .expect_err("retained posts.user_id → users blocks DROP TABLE users");
        let msg = err.to_string();
        assert!(
            msg.contains("users") && msg.contains("posts.user_id"),
            "names the dropped table and the retained referencer: {msg}"
        );
    }

    /// Documented limitation: the slice-2 parser cannot see a
    /// generated `#[belongs_to(...)]` association FK — a `<name>_id: i64` column is
    /// lifted as a plain `Int64` with `references: None` and NO diagnostic — so an
    /// invisible inbound association FK on a *retained* table cannot be detected
    /// offline, and this engine emits an unchecked `DROP TABLE` for it. A precise
    /// guard is impossible without schema introspection (a future slice); a blanket
    /// refuse-all-drops would make the common case useless. Instead every emitted
    /// `DROP TABLE` carries an advisory `-- autumn-safety:` comment naming this gap.
    /// This test pins that advisory (no behavioral test is possible for the
    /// invisible case — by definition the engine has no signal for it). The
    /// *visible*-FK protection is unaffected — see
    /// `drop_table_with_retained_inbound_fk_is_refused_even_with_allow_destructive`
    /// above, which still refuses a drop blocked by an observable `references`.
    #[test]
    fn drop_table_emits_invisible_association_fk_advisory() {
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::DropTable(posts_with(vec![]))],
        };
        guard_plan(&plan, ALLOW).expect("a plain DROP TABLE (no visible inbound FK) is allowed");
        let up = emit_up_sql(&plan).expect("emit up");
        assert!(
            up.contains("-- autumn-safety:")
                && up.contains("#[belongs_to(...)]")
                && up.contains("the offline snapshot cannot see"),
            "the DROP TABLE carries the invisible-association-FK advisory: {up}"
        );
        // The advisory precedes the statement, and the real statement is still emitted.
        let advisory = up.find("-- autumn-safety:").expect("advisory present");
        let stmt = up.find("DROP TABLE posts;").expect("statement present");
        assert!(
            advisory < stmt,
            "advisory comment precedes the DROP TABLE: {up}"
        );
    }

    /// Finding A: a self-referential FK on the dropped table does NOT block its
    /// own drop, and neither does an FK from another table that is also dropped.
    #[test]
    fn drop_table_self_ref_and_co_dropped_ref_do_not_block() {
        // users has a self-FK (parent_id → users) and is dropped alone.
        let mut parent = col("parent_id", ColumnType::Int64);
        parent.references = Some(ForeignKey::new("users", "id"));
        let users = posts_ref_table("users", parent);
        let plan = diff_schema(&[users], &parsed(vec![], vec![]), ALLOW);
        guard_plan(&plan, ALLOW).expect("self-referential FK goes away with the table");
    }

    /// Round 3 / Finding Y: a DESIRED-side FK to a table being dropped in the
    /// same plan is refused. Drop `users` while adding `posts.author_id ->
    /// users`; the emitted `CREATE TABLE posts ... REFERENCES users` would depend
    /// on the dropped `users`, so PG rejects. The round-2 baseline-only guard
    /// missed this — only desired-side references catch it.
    #[test]
    fn desired_side_fk_to_dropped_table_is_refused() {
        // baseline: users (managed, no inbound FK). desired: users gone, new
        // posts.author_id -> users.
        let users = Table::new("users", Backend::Postgres);
        let mut author_fk = col("author_id", ColumnType::Int64);
        author_fk.references = Some(ForeignKey::new("users", "id"));
        let posts = posts_ref_table("posts", author_fk);
        let plan = diff_schema(&[users], &parsed(vec![posts], vec![]), ALLOW);
        let err = guard_plan(&plan, ALLOW)
            .expect_err("new posts.author_id -> users blocks DROP TABLE users");
        let msg = err.to_string();
        assert!(
            msg.contains("users") && msg.contains("posts.author_id"),
            "names the dropped table and the desired-side referencer: {msg}"
        );
    }

    /// Round 3 / Finding Y control: a desired-side FK pointing at a RETAINED
    /// table is NOT a blocker even while an unrelated table is dropped — only
    /// references to a *dropped* table are refused (no over-refusal).
    #[test]
    fn desired_side_fk_to_retained_table_is_allowed() {
        // baseline: users (retained) + stale (dropped). desired: users retained,
        // stale gone, new posts.author_id -> users (a retained table).
        let users = Table::new("users", Backend::Postgres);
        let stale = Table::new("stale", Backend::Postgres);
        let mut author_fk = col("author_id", ColumnType::Int64);
        author_fk.references = Some(ForeignKey::new("users", "id"));
        let posts = posts_ref_table("posts", author_fk);
        let plan = diff_schema(
            &[users.clone(), stale],
            &parsed(vec![users, posts], vec![]),
            ALLOW,
        );
        guard_plan(&plan, ALLOW)
            .expect("FK to a retained table is fine even while another table is dropped");
    }

    /// Finding B: a non-implicit type change (`TEXT` → `INTEGER`) has no implicit
    /// PG cast, so a bare `ALTER COLUMN ... TYPE` is unappliable. Must be refused
    /// (needs a manual `USING`), regardless of `--allow-destructive`.
    #[test]
    fn non_implicit_type_conversion_is_refused() {
        let base = vec![posts_with(vec![col("views", ColumnType::Text)])];
        let want = parsed(
            vec![posts_with(vec![col("views", ColumnType::Int32)])],
            vec![],
        );
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        let err = guard_plan(&plan, ALLOW).expect_err("TEXT→INTEGER needs a USING clause");
        let msg = err.to_string();
        assert!(
            msg.contains("USING") && msg.contains("views"),
            "explains the USING requirement and names the column: {msg}"
        );
    }

    /// Finding B: an implicit widening (`Int32` → `Int64`, i.e. int4 → int8) IS
    /// emittable as a bare `ALTER COLUMN ... TYPE` — the classifier must not
    /// over-refuse.
    #[test]
    fn implicit_widening_type_conversion_is_allowed() {
        let base = vec![posts_with(vec![col("views", ColumnType::Int32)])];
        let want = parsed(
            vec![posts_with(vec![col("views", ColumnType::Int64)])],
            vec![],
        );
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        guard_plan(&plan, DEFAULT_OPTS).expect("Int32→Int64 is an implicit widening");
        let up = emit_up_sql(&plan).expect("emit");
        assert!(
            up.contains("ALTER TABLE posts ALTER COLUMN views TYPE BIGINT;"),
            "emits the bare ALTER TYPE for the widening: {up}"
        );
    }

    /// Finding S: a type change on a **referencing** FK column
    /// (`posts.account_id` → `accounts.id`, widened `Int32` → `Int64`) is an
    /// implicit widening the round-2 classifier ALLOWS, but PG rejects
    /// `ALTER COLUMN ... TYPE` on a column bound by an FK. Must be refused (no
    /// override) — the bare ALTER is unappliable.
    #[test]
    fn type_change_on_referencing_fk_column_is_refused() {
        let accounts = posts_ref_table("accounts", col("name", ColumnType::Text));
        let mut fk_base = col("account_id", ColumnType::Int32);
        fk_base.references = Some(ForeignKey::new("accounts", "id"));
        let base = vec![accounts.clone(), posts_with(vec![fk_base])];
        let mut fk_want = col("account_id", ColumnType::Int64);
        fk_want.references = Some(ForeignKey::new("accounts", "id"));
        let want = parsed(vec![accounts, posts_with(vec![fk_want])], vec![]);
        let plan = diff_schema(&base, &want, ALLOW);
        let err = guard_plan(&plan, ALLOW)
            .expect_err("type change on a referencing FK column is unappliable");
        let msg = err.to_string();
        assert!(
            msg.contains("posts.account_id") && msg.contains("foreign-key"),
            "names the FK column and the FK reason: {msg}"
        );
    }

    /// Finding S: a type change on a **referenced key** column (`accounts.id`
    /// widened `Int32` → `Int64`) while a retained `posts.account_id` → `accounts`
    /// FK survives is likewise refused — PG rejects altering the referenced key
    /// while the inbound FK exists, and this engine cannot drop+recreate it.
    #[test]
    fn type_change_on_referenced_key_column_is_refused() {
        // accounts.id: Int32 → Int64 (PK unchanged, so no PrimaryKeyChange).
        let mut acc_id_base = col("id", ColumnType::Int32);
        acc_id_base.primary_key = true;
        let mut accounts_base = Table::new("accounts", Backend::Postgres);
        accounts_base.primary_key.push("id".to_owned());
        accounts_base.columns.push(acc_id_base);

        let mut acc_id_want = col("id", ColumnType::Int64);
        acc_id_want.primary_key = true;
        let mut accounts_want = Table::new("accounts", Backend::Postgres);
        accounts_want.primary_key.push("id".to_owned());
        accounts_want.columns.push(acc_id_want);

        let mut fk = col("account_id", ColumnType::Int64);
        fk.references = Some(ForeignKey::new("accounts", "id"));
        let posts = posts_ref_table("posts", fk);

        let base = vec![accounts_base, posts.clone()];
        let want = parsed(vec![accounts_want, posts], vec![]);
        let plan = diff_schema(&base, &want, ALLOW);
        let err = guard_plan(&plan, ALLOW)
            .expect_err("type change on a referenced key column is unappliable");
        let msg = err.to_string();
        assert!(
            msg.contains("accounts.id") && msg.contains("foreign-key"),
            "names the referenced key column and the FK reason: {msg}"
        );
    }

    /// Finding S control: an implicit widening on a **plain** (non-FK) column
    /// still emits the bare `ALTER COLUMN ... TYPE` — the FK guard must not
    /// over-refuse.
    #[test]
    fn type_change_on_plain_column_still_allowed() {
        let base = vec![posts_with(vec![col("views", ColumnType::Int32)])];
        let want = parsed(
            vec![posts_with(vec![col("views", ColumnType::Int64)])],
            vec![],
        );
        let plan = diff_schema(&base, &want, DEFAULT_OPTS);
        guard_plan(&plan, DEFAULT_OPTS).expect("plain-column widening is not FK-bound");
        let up = emit_up_sql(&plan).expect("emit");
        assert!(
            up.contains("ALTER TABLE posts ALTER COLUMN views TYPE BIGINT;"),
            "emits the bare ALTER TYPE for the plain-column widening: {up}"
        );
    }

    /// A `users(id)` table for the `SQLite` FK-type-change fixtures.
    fn sqlite_users_table() -> Table {
        let mut t = Table::new("users", Backend::Sqlite);
        let mut id = col("id", ColumnType::Int64);
        id.primary_key = true;
        t.primary_key.push("id".to_owned());
        t.columns.push(id);
        t
    }

    /// A `posts(id, author_id -> users.id)` `SQLite` table whose `author_id` FK
    /// column carries `ty`, for the `SQLite` FK-type-change fixtures.
    fn sqlite_posts_with_author(ty: ColumnType) -> Table {
        let mut t = Table::new("posts", Backend::Sqlite);
        let mut id = col("id", ColumnType::Int64);
        id.primary_key = true;
        t.primary_key.push("id".to_owned());
        t.columns.push(id);
        let mut author = col("author_id", ty);
        author.nullable = true;
        author.references = Some(ForeignKey::new("users", "id"));
        t.columns.push(author);
        t
    }

    /// The `SQLite` counterpart to `type_change_on_referencing_fk_column_is_refused`:
    /// the FK-bound-type-change guard is `Postgres`-only, so on `SQLite` an FK
    /// column's type change (`posts.author_id` `Int64` → `Text`, still
    /// `REFERENCES users(id)`) is NOT refused — it flows to the table-recreate,
    /// which applies the new type, preserves the inline `REFERENCES`, and emits the
    /// FK type-consistency advisory naming the column. (A GENUINE cross-affinity-class
    /// change is used because on `SQLite` a same-class change like `Int32` → `Int64`
    /// is now a no-op — both are `INTEGER` affinity — see the affinity-aware
    /// comparison in [`column_types_equivalent`].) The `Postgres` plan with an int4→
    /// int8 change still refuses with `TypeChangeOnForeignKeyColumn` (the backend
    /// contrast).
    #[test]
    fn sqlite_fk_column_type_change_recreates_with_advisory() {
        let baseline = vec![
            sqlite_users_table(),
            sqlite_posts_with_author(ColumnType::Int64),
        ];
        let desired = vec![
            sqlite_users_table(),
            sqlite_posts_with_author(ColumnType::Text),
        ];
        let plan = diff_schema(&baseline, &parsed(desired.clone(), vec![]), ALLOW);

        // The plan is a SQLite plan carrying the real (cross-class) type change AND
        // the blocked marker appended alongside it.
        assert_eq!(plan.backend, Backend::Sqlite);
        assert!(
            plan.changes.iter().any(|c| matches!(
                c,
                SchemaChange::AlterColumnType { table, column, to, .. }
                    if table == "posts" && column == "author_id" && *to == ColumnType::Text
            )),
            "the real AlterColumnType (→ Text) rides in the plan: {:?}",
            plan.changes
        );
        assert!(
            plan.changes.iter().any(|c| matches!(
                c,
                SchemaChange::AlterColumnTypeBlockedByFk { table, column }
                    if table == "posts" && column == "author_id"
            )),
            "the FK-bound type-change marker is still recorded: {:?}",
            plan.changes
        );

        // (a) The Postgres-only gate lets SQLite through the guard.
        guard_plan(&plan, ALLOW)
            .expect("SQLite FK-column type change flows to the table recreate, not a refusal");

        // (b) The recreate applies the new type (Int64 → SQLite INTEGER), preserves
        //     the inline REFERENCES, and carries the FK type-consistency advisory.
        let ctx = SchemaContext::from_tables(&desired, &baseline);
        let up = emit_up_sql_with_context(&plan, &ctx).expect("emit sqlite rebuild");
        assert!(
            up.contains("author_id TEXT NULL REFERENCES users(id)"),
            "the recreate expresses author_id with its (changed) type and keeps the \
             inline REFERENCES: {up}"
        );
        assert!(
            up.contains(
                "-- autumn-safety: foreign-key column(s) author_id have their type \
                 changed by this recreate; SQLite does not enforce that they still \
                 match the referenced key's type, so ensure the referenced column \
                 stays type-compatible (Postgres rejects this change outright, which \
                 is why it is emitted only for SQLite)."
            ),
            "emits the FK type-consistency advisory naming the column: {up}"
        );
        // The down leg carries it too.
        let down = emit_down_sql_with_context(&plan, &ctx).expect("emit sqlite down rebuild");
        assert!(
            down.contains("-- autumn-safety: foreign-key column(s) author_id have their type"),
            "the down rebuild also carries the FK type-consistency advisory: {down}"
        );

        // (c) The Postgres plan with the same change still refuses (backend contrast).
        let mut users_pg = Table::new("users", Backend::Postgres);
        let mut uid = col("id", ColumnType::Int64);
        uid.primary_key = true;
        users_pg.primary_key.push("id".to_owned());
        users_pg.columns.push(uid);
        let mut author_base = col("author_id", ColumnType::Int32);
        author_base.nullable = true;
        author_base.references = Some(ForeignKey::new("users", "id"));
        let mut author_want = col("author_id", ColumnType::Int64);
        author_want.nullable = true;
        author_want.references = Some(ForeignKey::new("users", "id"));
        let pg_baseline = vec![users_pg.clone(), posts_with(vec![author_base])];
        let pg_desired = parsed(vec![users_pg, posts_with(vec![author_want])], vec![]);
        let pg_plan = diff_schema(&pg_baseline, &pg_desired, ALLOW);
        let err = guard_plan(&pg_plan, ALLOW)
            .expect_err("Postgres still refuses the FK-column type change");
        assert!(
            matches!(
                err,
                DiffError::TypeChangeOnForeignKeyColumn { ref table, ref column }
                    if table == "posts" && column == "author_id"
            ),
            "Postgres refuses with TypeChangeOnForeignKeyColumn: {err:?}"
        );
    }

    /// An ordinary `SQLite` rebuild (no FK-bound type change) must NOT carry the FK
    /// type-consistency advisory — the line is emitted only when a blocked marker
    /// for that table is present.
    #[test]
    fn sqlite_plain_rebuild_omits_fk_type_advisory() {
        // A plain (non-FK) column widening on `posts` triggers a table rebuild but
        // no `AlterColumnTypeBlockedByFk` marker.
        let mut base = Table::new("posts", Backend::Sqlite);
        let mut id = col("id", ColumnType::Int64);
        id.primary_key = true;
        base.primary_key.push("id".to_owned());
        base.columns.push(id);
        base.columns.push(col("views", ColumnType::Int32));
        let mut want = base.clone();
        want.columns[1].ty = ColumnType::Int64;

        let baseline = vec![base];
        let desired = vec![want];
        let plan = diff_schema(&baseline, &parsed(desired.clone(), vec![]), ALLOW);
        let ctx = SchemaContext::from_tables(&desired, &baseline);
        let up = emit_up_sql_with_context(&plan, &ctx).expect("emit sqlite rebuild");
        assert!(
            !up.contains("foreign-key column(s)"),
            "a rebuild with no FK-type-change marker carries no FK advisory: {up}"
        );
    }

    /// A real in-memory `SQLite` database applies the generated FK-column-type-change
    /// recreate without error and the seeded referencing row survives.
    #[test]
    fn sqlite_fk_column_type_change_recreate_applies_in_memory() {
        use diesel::connection::SimpleConnection as _;
        use diesel::{Connection as _, RunQueryDsl as _, SqliteConnection};

        #[derive(diesel::QueryableByName)]
        struct BigRow {
            #[diesel(sql_type = diesel::sql_types::BigInt, column_name = "v")]
            v: i64,
        }
        #[derive(diesel::QueryableByName)]
        struct FkRow {
            #[diesel(sql_type = diesel::sql_types::Text, column_name = "table")]
            table: String,
        }

        let baseline = vec![
            sqlite_users_table(),
            sqlite_posts_with_author(ColumnType::Int32),
        ];
        let desired = vec![
            sqlite_users_table(),
            sqlite_posts_with_author(ColumnType::Int64),
        ];
        let plan = diff_schema(&baseline, &parsed(desired.clone(), vec![]), ALLOW);
        guard_plan(&plan, ALLOW).expect("SQLite FK-column type change is emittable");
        let ctx = SchemaContext::from_tables(&desired, &baseline);
        let up = emit_up_sql_with_context(&plan, &ctx).expect("emit up");

        let mut conn = SqliteConnection::establish(":memory:").expect("open in-memory sqlite");
        conn.batch_execute(
            "CREATE TABLE users (\n    id INTEGER PRIMARY KEY AUTOINCREMENT\n);\n\
             CREATE TABLE posts (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    \
             author_id BIGINT NULL REFERENCES users(id)\n);\n\
             INSERT INTO users (id) VALUES (1);\n\
             INSERT INTO posts (id, author_id) VALUES (1, 1);",
        )
        .expect("seed the referenced + referencing tables and a row");

        // Apply the generated recreate inside a single transaction (as diesel runs a
        // migration).
        conn.transaction::<_, diesel::result::Error, _>(|conn| conn.batch_execute(&up))
            .expect("apply the FK-column-type-change recreate in a transaction");

        // The seeded referencing row survived the rebuild, still pointing at users(1).
        let survivors: Vec<BigRow> =
            diesel::sql_query("SELECT COUNT(*) AS v FROM posts WHERE id = 1 AND author_id = 1")
                .load(&mut conn)
                .expect("count the surviving row");
        assert_eq!(
            survivors[0].v, 1,
            "the seeded post row survives the FK-column type-change recreate"
        );

        // The recreated `posts` still declares the foreign key to `users`.
        let fks: Vec<FkRow> = diesel::sql_query("PRAGMA foreign_key_list(posts)")
            .load(&mut conn)
            .expect("read posts foreign keys");
        assert!(
            fks.iter().any(|f| f.table == "users"),
            "the recreate preserves the posts.author_id -> users foreign key"
        );
    }

    /// Finding R: dropping a retained table's FK column AND its referenced table in
    /// the SAME plan is a valid combined cleanup — `up_ordered` emits every
    /// `DROP COLUMN` (which removes the FK constraint) before every `DROP TABLE`,
    /// so `DROP COLUMN posts.user_id` runs before `DROP TABLE users`. The
    /// inbound-FK guard must NOT over-refuse it under `--allow-destructive`.
    #[test]
    fn drop_fk_column_and_target_table_together_is_allowed_with_allow_destructive() {
        let users = Table::new("users", Backend::Postgres);
        let mut user_fk = col("user_id", ColumnType::Int64);
        user_fk.references = Some(ForeignKey::new("users", "id"));
        let baseline = vec![users, posts_with(vec![user_fk])];
        // desired: users gone, posts.user_id dropped.
        let desired = parsed(vec![posts_with(vec![])], vec![]);
        let plan = diff_schema(&baseline, &desired, ALLOW);
        guard_plan(&plan, ALLOW)
            .expect("co-dropping the FK column and its target table is valid SQL");
        let up = emit_up_sql(&plan).expect("emit");
        let drop_col = up
            .find("DROP COLUMN user_id")
            .expect("emits DROP COLUMN user_id");
        let drop_tbl = up.find("DROP TABLE users").expect("emits DROP TABLE users");
        assert!(
            drop_col < drop_tbl,
            "DROP COLUMN posts.user_id must precede DROP TABLE users:\n{up}"
        );
    }

    /// Finding C: two managed tables both dropped, `audit_logs.account_id` →
    /// `accounts`. Lexically `accounts` < `audit_logs`, so a naive order would
    /// `DROP TABLE accounts` (referenced) before `audit_logs` (referencing) → PG
    /// rejects. Drops must be REVERSE-topological (referencing first); the down
    /// leg recreates FORWARD (referenced first).
    #[test]
    fn drop_tables_reverse_topologically_ordered_by_fk() {
        let accounts = posts_ref_table("accounts", col("name", ColumnType::Text));
        let mut acct_fk = col("account_id", ColumnType::Int64);
        acct_fk.references = Some(ForeignKey::new("accounts", "id"));
        let audit = posts_ref_table("audit_logs", acct_fk);
        let baseline = vec![accounts, audit];
        let plan = diff_schema(&baseline, &parsed(vec![], vec![]), ALLOW);
        // Both tables are dropped, so nothing retained references either.
        guard_plan(&plan, ALLOW).expect("both dropped — no retained inbound reference");

        let up = emit_up_sql(&plan).expect("emit");
        let referenced = up.find("DROP TABLE accounts").expect("accounts dropped");
        let referencing = up
            .find("DROP TABLE audit_logs")
            .expect("audit_logs dropped");
        assert!(
            referencing < referenced,
            "drop referencing `audit_logs` before referenced `accounts`: {up}"
        );

        let down = emit_down_sql(&plan).expect("emit");
        let d_referenced = down.find("CREATE TABLE accounts").expect("down accounts");
        let d_referencing = down
            .find("CREATE TABLE audit_logs")
            .expect("down audit_logs");
        assert!(
            d_referenced < d_referencing,
            "down recreates referenced `accounts` before referencing `audit_logs`: {down}"
        );
    }

    /// Finding C: a cycle among dropped tables is refused (reuses the existing
    /// `CyclicTableDependencies` error), never emitted as unorderable SQL.
    #[test]
    fn drop_tables_fk_cycle_is_refused() {
        let mut a_b = col("b_id", ColumnType::Int64);
        a_b.references = Some(ForeignKey::new("b", "id"));
        let table_a = posts_ref_table("a", a_b);
        let mut b_a = col("a_id", ColumnType::Int64);
        b_a.references = Some(ForeignKey::new("a", "id"));
        let table_b = posts_ref_table("b", b_a);
        let plan = diff_schema(&[table_a, table_b], &parsed(vec![], vec![]), ALLOW);
        // (The inbound-FK guard excludes co-dropped referencers, so the cycle
        // surfaces at emission, mirroring the CreateTable cycle case.)
        guard_plan(&plan, ALLOW).expect("co-dropped tables never trip the inbound guard");
        let err = emit_up_sql(&plan).unwrap_err();
        let EmitError::CyclicTableDependencies { tables } = &err else {
            panic!("expected CyclicTableDependencies, got {err:?}");
        };
        assert_eq!(
            *tables,
            vec!["a".to_owned(), "b".to_owned()],
            "names the cycle"
        );
    }

    // -- Part B: rollback restores a cascade-dropped retained index ----------

    /// The `index_depends_on_column` contract: dependency is EXACT `columns`
    /// membership (the introspected `pg_depend` set), never a `definition`-text
    /// scan. A column name that merely appears in the `definition` string — e.g.
    /// as a string literal in a partial-index predicate — is NOT a dependency, so
    /// the projection can't wrongly prune an index Postgres actually keeps.
    #[test]
    fn index_dependency_detection_is_exact_column_membership() {
        // A partial index on `id` whose predicate string literal mentions `email`,
        // but which does NOT depend on the `email` column (its `pg_depend` set is
        // just `id`). Dropping `email` must NOT be read as a dependency.
        let partial = Index {
            name: "t_id_email_kind".to_owned(),
            columns: vec!["id".to_owned()],
            unique: false,
            definition: Some(
                "CREATE INDEX t_id_email_kind ON t (id) WHERE kind = 'email'".to_owned(),
            ),
            is_partial: false,
            key_columns: Vec::new(),
        };
        assert!(
            !index_depends_on_column(&partial, "email", Backend::Postgres),
            "a column name in a definition string literal is NOT a dependency (no false positive)"
        );
        assert!(
            index_depends_on_column(&partial, "id", Backend::Postgres),
            "the true dependent column (in `columns`) IS a dependency"
        );

        // An expression index carrying its exact `pg_depend` dependent set.
        let expr = Index {
            name: "u_lower_email".to_owned(),
            columns: vec!["email".to_owned()],
            unique: false,
            definition: Some("CREATE INDEX u_lower_email ON users (lower(email))".to_owned()),
            is_partial: false,
            key_columns: Vec::new(),
        };
        assert!(
            index_depends_on_column(&expr, "email", Backend::Postgres),
            "the expression-referenced `email` is captured in `columns`"
        );
        assert!(
            !index_depends_on_column(&expr, "mail", Backend::Postgres),
            "a column absent from `columns` is not a dependency"
        );

        let plain = Index {
            name: "u_email".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: None,
            is_partial: false,
            key_columns: Vec::new(),
        };
        assert!(
            index_depends_on_column(&plain, "email", Backend::Postgres),
            "columns membership counts as a dependency"
        );
    }

    /// On `SQLite` a retained partial/expression index records only its KEY columns in
    /// `columns`, so a WHERE-predicate / key-expression column is detected via a
    /// word-bounded `definition` scan — otherwise dropping it would orphan the index
    /// and `SQLite` rejects the `DROP COLUMN`.
    #[test]
    fn sqlite_index_dependency_includes_predicate_and_expression_columns() {
        // A partial index whose KEY is `email` but whose predicate references
        // `deleted_at` (only in the definition text, NOT in `columns`).
        let partial = Index {
            name: "t_email_active".to_owned(),
            columns: vec!["email".to_owned()],
            unique: false,
            definition: Some(
                "CREATE INDEX t_email_active ON t (email) WHERE deleted_at IS NULL".to_owned(),
            ),
            is_partial: true,
            key_columns: Vec::new(),
        };
        assert!(
            index_depends_on_column(&partial, "deleted_at", Backend::Sqlite),
            "the WHERE-predicate column is a dependency on SQLite (definition scan)"
        );
        assert!(
            index_depends_on_column(&partial, "email", Backend::Sqlite),
            "the key column is still a dependency"
        );
        // Word-bounded: a longer identifier that merely contains the name is NOT a hit.
        assert!(!index_depends_on_column(
            &partial,
            "deleted",
            Backend::Sqlite
        ));
        assert!(!index_depends_on_column(&partial, "at", Backend::Sqlite));
        // The SAME index on Postgres keeps exact `columns` semantics (its real deps
        // would be in `columns`), so the definition text is never scanned.
        assert!(!index_depends_on_column(
            &partial,
            "deleted_at",
            Backend::Postgres
        ));
    }

    #[test]
    fn definition_references_column_is_word_bounded_and_case_insensitive() {
        let def = "CREATE INDEX i ON t (email) WHERE Deleted_At IS NULL AND kind = 'deleted_at_x'";
        assert!(definition_references_column(def, "email"));
        assert!(
            definition_references_column(def, "deleted_at"),
            "case-insensitive match against `Deleted_At`"
        );
        // A quoted identifier still matches (quotes are non-word boundaries).
        assert!(definition_references_column(
            "CREATE INDEX i ON t (\"email\")",
            "email"
        ));
        // Substring of a longer token does NOT match.
        assert!(!definition_references_column(
            "CREATE INDEX i ON t (email_verified)",
            "email"
        ));
        assert!(!definition_references_column(def, ""));
    }

    #[test]
    fn drop_column_up_drops_column_and_down_restores_retained_index() {
        // Baseline `users(id, email)` with a RETAINED constraint-owned unique
        // index on `email` (definition-carrying, no paired DropIndex). The model
        // removes `email`, so the plan carries only a DropColumn.
        let mut email_col = col("email", ColumnType::Text);
        email_col.nullable = false;
        let mut baseline = posts_ref_table("users", email_col);
        baseline.indexes.push(Index {
            name: "users_email_key".to_owned(),
            columns: vec!["email".to_owned()],
            unique: true,
            definition: Some("CREATE UNIQUE INDEX users_email_key ON users (email)".to_owned()),
            is_partial: false,
            key_columns: Vec::new(),
        });
        // Desired side: `email` removed. `diff_indexes` retains the definition
        // index (no DropIndex), so the plan is a lone DropColumn.
        let desired = posts_ref_table("users", col("keep", ColumnType::Text));
        let plan = diff_schema(
            std::slice::from_ref(&baseline),
            &parsed(vec![desired.clone()], vec![]),
            ALLOW,
        );
        assert!(
            plan.changes.iter().any(
                |c| matches!(c, SchemaChange::DropColumn { column, .. } if column.name == "email")
            ),
            "plan must drop `email`: {:?}",
            plan.changes
        );
        assert!(
            !plan
                .changes
                .iter()
                .any(|c| matches!(c, SchemaChange::DropIndex { index, .. } if index.name == "users_email_key")),
            "the retained definition index must NOT get a DropIndex: {:?}",
            plan.changes
        );

        let ctx = SchemaContext::from_tables(
            std::slice::from_ref(&desired),
            std::slice::from_ref(&baseline),
        );
        let up = emit_up_sql_with_context(&plan, &ctx).expect("emit up");
        let down = emit_down_sql_with_context(&plan, &ctx).expect("emit down");

        // UP: a bare DROP COLUMN (Postgres cascade-drops the index), never a
        // failing DROP INDEX on the constraint-backed index.
        assert!(
            up.contains("ALTER TABLE users DROP COLUMN email"),
            "up must drop the column: {up}"
        );
        assert!(
            !up.contains("DROP INDEX users_email_key"),
            "up must NOT emit DROP INDEX for the cascade-dropped retained index: {up}"
        );

        // DOWN: re-add the column, THEN recreate the retained index verbatim.
        assert!(
            down.contains("ADD COLUMN email"),
            "down must re-add the column: {down}"
        );
        assert!(
            down.contains("CREATE UNIQUE INDEX users_email_key ON users (email)"),
            "down must restore the cascade-dropped retained index: {down}"
        );
        let readd_at = down.find("ADD COLUMN email").expect("re-add present");
        let index_at = down
            .find("CREATE UNIQUE INDEX users_email_key")
            .expect("index restore present");
        assert!(
            readd_at < index_at,
            "column must be re-added before its dependent index is recreated: {down}"
        );
        // No regression: a single-column retained index is restored EXACTLY ONCE.
        assert_eq!(
            down.matches("CREATE UNIQUE INDEX users_email_key").count(),
            1,
            "the single-column retained index must be recreated exactly once: {down}"
        );
    }

    /// A retained index depending on TWO columns, both dropped, must have its
    /// recreation DELAYED until BOTH columns are restored and emitted EXACTLY ONCE
    /// (never once per dependent dropped column). Recreating it inline after the
    /// first re-add would fail (the second dependent column is still absent) and
    /// duplicate the `CREATE INDEX`.
    #[test]
    fn drop_two_columns_down_restores_multicol_retained_index_once_after_both() {
        // Baseline `users(id, keep, email, tenant_id)` with a RETAINED partial +
        // expression index depending on BOTH `email` and `tenant_id`
        // (definition-carrying, no paired DropIndex).
        let mut baseline = Table::new("users", Backend::Postgres);
        let mut id = col("id", ColumnType::Int64);
        id.primary_key = true;
        baseline.primary_key.push("id".to_owned());
        baseline.columns.push(id);
        baseline.columns.push(col("keep", ColumnType::Text));
        let mut email = col("email", ColumnType::Text);
        email.nullable = false;
        baseline.columns.push(email);
        baseline.columns.push(col("tenant_id", ColumnType::Int64));
        baseline.indexes.push(Index {
            name: "users_active".to_owned(),
            // The exact `pg_depend` dependent set: expression column + predicate
            // column (sorted by name, as introspection records it).
            columns: vec!["email".to_owned(), "tenant_id".to_owned()],
            unique: false,
            definition: Some(
                "CREATE INDEX users_active ON users (lower(email)) WHERE tenant_id IS NOT NULL"
                    .to_owned(),
            ),
            is_partial: false,
            key_columns: Vec::new(),
        });

        // Desired side: BOTH `email` and `tenant_id` removed. The model diff
        // retains the definition index (no DropIndex), so the plan is two
        // DropColumns.
        let mut desired = Table::new("users", Backend::Postgres);
        let mut did = col("id", ColumnType::Int64);
        did.primary_key = true;
        desired.primary_key.push("id".to_owned());
        desired.columns.push(did);
        desired.columns.push(col("keep", ColumnType::Text));

        let plan = diff_schema(
            std::slice::from_ref(&baseline),
            &parsed(vec![desired.clone()], vec![]),
            ALLOW,
        );
        assert_eq!(
            plan.changes
                .iter()
                .filter(|c| matches!(c, SchemaChange::DropColumn { .. }))
                .count(),
            2,
            "plan must drop both columns: {:?}",
            plan.changes
        );
        assert!(
            !plan
                .changes
                .iter()
                .any(|c| matches!(c, SchemaChange::DropIndex { index, .. } if index.name == "users_active")),
            "the retained definition index must NOT get a DropIndex: {:?}",
            plan.changes
        );

        let ctx = SchemaContext::from_tables(
            std::slice::from_ref(&desired),
            std::slice::from_ref(&baseline),
        );
        let down = emit_down_sql_with_context(&plan, &ctx).expect("emit down");

        // DOWN re-adds BOTH columns and recreates the index EXACTLY ONCE.
        let email_at = down.find("ADD COLUMN email").expect("email re-add present");
        let tenant_at = down
            .find("ADD COLUMN tenant_id")
            .expect("tenant_id re-add present");
        assert_eq!(
            down.matches("CREATE INDEX users_active").count(),
            1,
            "the multi-column retained index must be recreated exactly once (deduped): {down}"
        );
        let index_at = down
            .find("CREATE INDEX users_active")
            .expect("index restore present");
        assert!(
            email_at < index_at && tenant_at < index_at,
            "both dependent columns must be re-added BEFORE the index is recreated: {down}"
        );
    }
    // -- foreign-key actions (#1975) -------------------------------------------

    fn cascade_fk() -> ForeignKey {
        ForeignKey::new("users", "id")
            .with_on_delete(Some(ForeignKeyAction::Cascade))
            .with_on_update(Some(ForeignKeyAction::Restrict))
    }

    #[test]
    fn fk_actions_render_on_add_column() {
        for (backend, ty) in [(Backend::Postgres, "BIGINT"), (Backend::Sqlite, "INTEGER")] {
            let mut author = col("author_id", ColumnType::Int64);
            author.nullable = true;
            author.references = Some(cascade_fk());
            let plan = MigrationPlan {
                backend,
                changes: vec![SchemaChange::AddColumn {
                    table: "posts".to_owned(),
                    column: author,
                }],
            };
            let up = emit_up_sql(&plan).expect("emit");
            assert!(
                up.contains(&format!(
                    "ADD COLUMN author_id {ty} NULL REFERENCES users(id) \
                     ON DELETE CASCADE ON UPDATE RESTRICT;"
                )),
                "{backend:?}: {up}"
            );
        }
    }

    #[test]
    fn fk_actions_render_on_create_table() {
        let mut author = col("author_id", ColumnType::Int64);
        author.references =
            Some(ForeignKey::new("users", "id").with_on_delete(Some(ForeignKeyAction::SetDefault)));
        let plan = diff_schema(
            &[],
            &parsed(vec![posts_with(vec![author])], vec![]),
            DEFAULT_OPTS,
        );
        let up = emit_up_sql(&plan).expect("emit");
        assert!(
            up.contains("author_id BIGINT NOT NULL REFERENCES users(id) ON DELETE SET DEFAULT"),
            "{up}"
        );
    }

    #[test]
    fn fk_actions_render_on_add_foreign_key() {
        let plan = MigrationPlan {
            backend: Backend::Postgres,
            changes: vec![SchemaChange::AddForeignKey {
                table: "posts".to_owned(),
                column: "author_id".to_owned(),
                foreign_key: cascade_fk(),
            }],
        };
        let up = emit_up_sql(&plan).expect("emit");
        assert!(
            up.contains(
                "FOREIGN KEY (author_id) REFERENCES users(id) ON DELETE CASCADE ON UPDATE RESTRICT;"
            ),
            "{up}"
        );
    }

    #[test]
    fn fk_actions_are_restored_by_the_down_of_a_drop_table() {
        let mut author = col("author_id", ColumnType::Int64);
        author.references = Some(cascade_fk());
        let base = vec![posts_with(vec![author])];
        let plan = diff_schema(&base, &parsed(vec![], vec![]), ALLOW);
        guard_plan(&plan, ALLOW).expect("drop allowed");
        let down = emit_down_sql(&plan).expect("emit down");
        assert!(
            down.contains("REFERENCES users(id) ON DELETE CASCADE ON UPDATE RESTRICT"),
            "{down}"
        );
    }

    #[test]
    fn fk_action_change_is_refused_with_no_override() {
        // The engine has no step that drops the old constraint, so it refuses.
        let mut base_author = col("author_id", ColumnType::Int64);
        base_author.references = Some(ForeignKey::new("users", "id"));
        let mut want_author = col("author_id", ColumnType::Int64);
        want_author.references = Some(cascade_fk());
        let plan = diff_schema(
            &[posts_with(vec![base_author])],
            &parsed(vec![posts_with(vec![want_author])], vec![]),
            DEFAULT_OPTS,
        );
        assert_eq!(
            plan.changes,
            vec![SchemaChange::ForeignKeyChange {
                table: "posts".to_owned(),
                column: "author_id".to_owned(),
                from: "users(id)".to_owned(),
                to: "users(id) ON DELETE CASCADE ON UPDATE RESTRICT".to_owned(),
            }]
        );
        let err = guard_plan(&plan, ALLOW).unwrap_err();
        assert!(matches!(err, DiffError::ForeignKeyChange { .. }), "{err:?}");
        let msg = err.to_string();
        assert!(
            msg.contains("`REFERENCES users(id) ON DELETE CASCADE ON UPDATE RESTRICT`"),
            "{msg}"
        );
        assert!(msg.contains("on_delete = \"cascade\""), "{msg}");
        assert!(
            describe_change(&plan.changes[0]).contains("FOREIGN KEY CHANGE"),
            "the plan label names a change, not a retarget"
        );
    }

    #[test]
    fn sqlite_recreate_keeps_fk_actions() {
        let mut base_posts = sqlite_posts_with_author(ColumnType::Int64);
        base_posts.columns[1].references = Some(cascade_fk());
        let mut want_posts = base_posts.clone();
        // A NOT NULL -> NULL change forces a recreate on SQLite.
        let mut body = col("body", ColumnType::Text);
        base_posts.columns.push(body.clone());
        body.nullable = true;
        want_posts.columns.push(body);
        let baseline = vec![sqlite_users_table(), base_posts];
        let desired = vec![sqlite_users_table(), want_posts];
        let plan = diff_schema(&baseline, &parsed(desired.clone(), vec![]), DEFAULT_OPTS);
        guard_plan(&plan, DEFAULT_OPTS).expect("drop not null is safe");
        let ctx = SchemaContext::from_tables(&desired, &baseline);
        let up = emit_up_sql_with_context(&plan, &ctx).expect("emit sqlite rebuild");
        assert!(
            up.contains(
                "author_id INTEGER NULL REFERENCES users(id) ON DELETE CASCADE ON UPDATE RESTRICT"
            ),
            "{up}"
        );
    }
    /// The migration runs in a transaction, where `PRAGMA foreign_keys=OFF` has
    /// no effect. So `DROP TABLE users` in a rebuild of `users` fires the child
    /// actions. The emitter must refuse when a child cascades or sets values.
    #[test]
    fn sqlite_rebuild_of_a_cascade_target_is_refused() {
        for action in [
            ForeignKeyAction::Cascade,
            ForeignKeyAction::SetNull,
            ForeignKeyAction::SetDefault,
        ] {
            let mut posts = sqlite_posts_with_author(ColumnType::Int64);
            posts.columns[1].references =
                Some(ForeignKey::new("users", "id").with_on_delete(Some(action)));
            let mut base_users = sqlite_users_table();
            base_users.columns.push(col("name", ColumnType::Text));
            let mut want_users = sqlite_users_table();
            let mut name = col("name", ColumnType::Text);
            name.nullable = true;
            want_users.columns.push(name);
            let baseline = vec![base_users, posts.clone()];
            let desired = vec![want_users, posts];
            let plan = diff_schema(&baseline, &parsed(desired.clone(), vec![]), DEFAULT_OPTS);
            guard_plan(&plan, DEFAULT_OPTS).expect("drop not null is safe");
            let ctx = SchemaContext::from_tables(&desired, &baseline);
            for result in [
                emit_up_sql_with_context(&plan, &ctx),
                emit_down_sql_with_context(&plan, &ctx),
            ] {
                let err = result.expect_err("a rebuild must not fire child actions");
                assert!(
                    matches!(err, EmitError::SqliteRebuildUnsupported { .. }),
                    "{err:?}"
                );
                assert!(err.to_string().contains("posts.author_id"), "{err}");
                assert!(err.to_string().contains(action.sql()), "{err}");
            }
        }
    }

    /// A `NO ACTION` or `RESTRICT` child does not change rows. The rebuild
    /// stays as before.
    #[test]
    fn sqlite_rebuild_of_a_restrict_target_is_emitted() {
        let mut posts = sqlite_posts_with_author(ColumnType::Int64);
        posts.columns[1].references =
            Some(ForeignKey::new("users", "id").with_on_delete(Some(ForeignKeyAction::Restrict)));
        let mut base_users = sqlite_users_table();
        base_users.columns.push(col("name", ColumnType::Text));
        let mut want_users = sqlite_users_table();
        let mut name = col("name", ColumnType::Text);
        name.nullable = true;
        want_users.columns.push(name);
        let baseline = vec![base_users, posts.clone()];
        let desired = vec![want_users, posts];
        let plan = diff_schema(&baseline, &parsed(desired.clone(), vec![]), DEFAULT_OPTS);
        let ctx = SchemaContext::from_tables(&desired, &baseline);
        emit_up_sql_with_context(&plan, &ctx).expect("a RESTRICT child does not block");
    }

    /// A typo in an action skips the column. The diff then keeps the column,
    /// its foreign key and its index as they are.
    #[test]
    fn a_bad_action_keeps_the_existing_column() {
        let src = r#"
            #[model(managed)]
            pub struct Post {
                #[id]
                pub id: i64,
                #[references(table = "users", on_delete = "casade")]
                pub author_id: i64,
                #[default]
                pub created_at: chrono::NaiveDateTime,
            }
        "#;
        let desired =
            crate::schema::parse::parse_model_source(src, Backend::Postgres).expect("parse");
        assert_eq!(desired.diagnostics.len(), 1, "{:?}", desired.diagnostics);
        // The baseline is the same model with a valid FK.
        let valid = src.replace(", on_delete = \"casade\"", "");
        let baseline = crate::schema::parse::parse_model_source(&valid, Backend::Postgres)
            .expect("parse baseline")
            .tables;
        assert!(
            baseline[0]
                .indexes
                .iter()
                .any(|i| i.name == "idx_posts_author_id"),
            "{baseline:?}"
        );
        let plan = diff_schema(&baseline, &desired, DEFAULT_OPTS);
        assert!(
            plan.is_empty(),
            "the skipped column must not change: {plan:?}"
        );
    }

    /// A self-reference is a child too. The staging table's rows reference
    /// the old table, so its `DROP TABLE` would fire the action on them.
    #[test]
    fn sqlite_rebuild_of_a_self_cascade_table_is_refused() {
        let mut base = sqlite_users_table();
        let mut parent = col("parent_id", ColumnType::Int64);
        parent.nullable = true;
        parent.references =
            Some(ForeignKey::new("users", "id").with_on_delete(Some(ForeignKeyAction::Cascade)));
        base.columns.push(parent);
        base.columns.push(col("name", ColumnType::Text));
        let mut want = base.clone();
        want.columns[2].nullable = true;
        let baseline = vec![base];
        let desired = vec![want];
        let plan = diff_schema(&baseline, &parsed(desired.clone(), vec![]), DEFAULT_OPTS);
        let ctx = SchemaContext::from_tables(&desired, &baseline);
        let err = emit_up_sql_with_context(&plan, &ctx).expect_err("a self cascade must refuse");
        assert!(err.to_string().contains("users.parent_id"), "{err}");
    }
}