rustango_macros/

lib.rs

//! Proc-macros for rustango.
//!
//! v0.1 ships `#[derive(Model)]`, which emits:
//! * a `Model` impl carrying a static `ModelSchema`,
//! * an `inventory::submit!` so the model is discoverable from the registry,
//! * an inherent `objects()` returning a `QuerySet<Self>`,
//! * a `sqlx::FromRow` impl so query results decode into the struct.

use proc_macro::TokenStream;
use proc_macro2::TokenStream as TokenStream2;
use quote::quote;
use syn::{
    parse_macro_input, spanned::Spanned, Data, DeriveInput, Fields, GenericArgument, LitStr,
    PathArguments, Type, TypePath,
};

/// Resolve the consumer's local name for the `rustango` crate so the
/// macro-emitted code keeps compiling when a downstream `Cargo.toml`
/// renames the dep (`[dependencies] orm = { package = "rustango", … }`)
/// or when the standalone `rustango-orm` crate ships in a future
/// slice of the [orm-extract epic](https://github.com/ujeenet/rustango/issues/149).
///
/// Returns one of:
/// - `quote!(::rustango)` — the consumer IS the `rustango` crate
///   itself. We emit the absolute path `::rustango` (NOT `crate`)
///   because examples and integration tests inside the rustango
///   package compile as separate binaries — their own `crate::`
///   namespace is the example/test file, not rustango's lib root.
///   The absolute `::rustango` resolves correctly in both contexts
///   (rustango lib code AND rustango/examples/*.rs).
/// - `quote!(::ident)` — the consumer renamed the dep; emit the
///   user's chosen ident.
/// - `quote!(::rustango)` — fallback when `proc-macro-crate` can't
///   read the manifest (rare; preserves today's behavior).
///
/// Issue [#142](https://github.com/ujeenet/rustango/issues/142).
fn rustango_root() -> TokenStream2 {
    use proc_macro_crate::{crate_name, FoundCrate};
    match crate_name("rustango") {
        Ok(FoundCrate::Itself) => quote!(::rustango),
        Ok(FoundCrate::Name(name)) => {
            let ident = proc_macro2::Ident::new(&name, proc_macro2::Span::call_site());
            quote!(::#ident)
        }
        Err(_) => quote!(::rustango),
    }
}

/// Derive a `Model` impl. See crate docs for the supported attributes.
#[proc_macro_derive(Model, attributes(rustango))]
pub fn derive_model(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    expand(&input)
        .unwrap_or_else(syn::Error::into_compile_error)
        .into()
}

/// Derive a `router(prefix, pool) -> axum::Router` associated method on a
/// marker struct, wiring the full CRUD ViewSet in one annotation.
///
/// ```ignore
/// #[derive(ViewSet)]
/// #[viewset(
///     model        = Post,
///     fields       = "id, title, body, author_id",
///     filter_fields = "author_id",
///     search_fields = "title, body",
///     ordering     = "-published_at",
///     page_size    = 20,
/// )]
/// pub struct PostViewSet;
///
/// // Mount into your app:
/// let app = Router::new()
///     .merge(PostViewSet::router("/api/posts", pool.clone()));
/// ```
///
/// Attributes:
/// * `model = TypeName` — *required*. The `#[derive(Model)]` struct whose
///   `SCHEMA` constant drives the endpoints.
/// * `fields = "a, b, c"` — scalar fields included in list/retrieve JSON
///   and accepted on create/update (default: all scalar fields).
/// * `filter_fields = "a, b"` — fields filterable via `?a=v` query params.
/// * `search_fields = "a, b"` — fields searched by `?search=...`.
/// * `ordering = "a, -b"` — default list ordering; prefix `-` for DESC.
/// * `page_size = N` — default page size (default: 20, max: 1000).
/// * `read_only` — flag; wires only `list` + `retrieve` (no mutations).
/// * `allow_anonymous` — flag; write actions without codenames are
///   intended, so the mount warning is skipped.
/// * `serializer = SomeSerializer` — render list / retrieve / create
///   responses through a `#[derive(Serializer)]` type instead of the
///   default field-level projection (`read_only` / `source` / `method`
///   / `write_only` overrides apply). Tri-dialect. Requires the
///   `serializer` feature.
/// * `permissions(list = "...", retrieve = "...", create = "...",
///   update = "...", destroy = "...")` — codenames required per action.
#[proc_macro_derive(ViewSet, attributes(viewset))]
pub fn derive_viewset(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    expand_viewset(&input)
        .unwrap_or_else(syn::Error::into_compile_error)
        .into()
}

/// Derive `rustango::forms::Form` (slice 8.4B). Generates a
/// `parse(&HashMap<String, String>) -> Result<Self, FormErrors>` impl
/// that walks every named field and:
///
/// * Parses the string value into the field's Rust type (`String`,
///   `i32`, `i64`, `f32`, `f64`, `bool`, plus `Option<T>` for the
///   nullable case).
/// * Applies any `#[form(min = ..)]` / `#[form(max = ..)]` /
///   `#[form(min_length = ..)]` / `#[form(max_length = ..)]`
///   validators in declaration order, returning `FormError::Parse`
///   on the first failure.
///
/// Example:
///
/// ```ignore
/// #[derive(Form)]
/// pub struct CreateItemForm {
///     #[form(min_length = 1, max_length = 64)]
///     pub name: String,
///     #[form(min = 0, max = 150)]
///     pub age: i32,
///     pub active: bool,
///     pub email: Option<String>,
/// }
///
/// let parsed = CreateItemForm::parse(&form_map)?;
/// ```
#[proc_macro_derive(Form, attributes(form))]
pub fn derive_form(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    expand_form(&input)
        .unwrap_or_else(syn::Error::into_compile_error)
        .into()
}

/// Derive `rustango::serializer::ModelSerializer` for a struct.
/// (intra-doc link disabled — the macro crate doesn't depend on
/// `rustango` itself, so rustdoc can't resolve the path.)
///
/// # Container attribute (required)
/// `#[serializer(model = TypeName)]` — the [`Model`] type this serializer maps from.
///
/// # Field attributes
/// - `#[serializer(read_only)]` — mapped from model; included in JSON output; excluded from `writable_fields()`
/// - `#[serializer(write_only)]` — `Default::default()` in `from_model`; excluded from JSON output; included in `writable_fields()`
/// - `#[serializer(source = "field_name")]` — reads from `model.field_name` instead of `model.<field_ident>`
/// - `#[serializer(skip)]` — `Default::default()` in `from_model`; included in JSON output; excluded from `writable_fields()` (user sets manually)
/// - `#[serializer(method = "fn_name")]` — computed field: calls `Self::fn_name(&model)` for the field value; excluded from `writable_fields()`
/// - `#[serializer(nested)]` / `nested(strict)` — auto-resolves nested serializer from a loaded `ForeignKey`; excluded from `writable_fields()`
/// - `#[serializer(many = ChildSerializer)]` — collection of nested serializers; populated via macro-emitted `set_<field>(&[Child::Model])`; excluded from `writable_fields()`
/// - `#[serializer(slug = "name")]` — render a relation (`ForeignKey<T>` or `Option<ForeignKey<T>>`) as one of its fields: clones the loaded parent's `name`; excluded from `writable_fields()` (v0.44)
/// - `#[serializer(validate = "fn_name")]` — per-field validator surfaced by `Self::validate(&self)`
/// - `#[serializer(max_length = N)]` / `min_length` / `min` / `max` — declarative bounds checked on
///   write; auto-inherit from the model's `FieldSchema` (`max_length`/`min`/`max`/`choices`) when
///   no attr is given, override it when given (`min_length` is serializer-only)
///
/// The macro also emits a custom `impl serde::Serialize` — do **not** also `#[derive(Serialize)]`.
#[proc_macro_derive(Serializer, attributes(serializer))]
pub fn derive_serializer(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    expand_serializer(&input)
        .unwrap_or_else(syn::Error::into_compile_error)
        .into()
}

/// Bake every `*.json` migration file in a directory into the binary
/// at compile time. Returns a `&'static [(&'static str, &'static str)]`
/// of `(name, json_content)` pairs, lex-sorted by file stem.
///
/// Pair with `rustango::migrate::migrate_embedded` at runtime — same
/// behaviour as `migrate(pool, dir)` but with no filesystem access.
/// The path is interpreted relative to the user's `CARGO_MANIFEST_DIR`
/// (i.e. the crate that invokes the macro). Default is
/// `"./migrations"` if no argument is supplied.
///
/// ```ignore
/// const EMBEDDED: &[(&str, &str)] = rustango::embed_migrations!();
/// // or:
/// const EMBEDDED: &[(&str, &str)] = rustango::embed_migrations!("./migrations");
///
/// rustango::migrate::migrate_embedded(&pool, EMBEDDED).await?;
/// ```
///
/// **Compile-time guarantees** (rustango v0.4+, slice 5): every JSON
/// file's `name` field must equal its file stem, every `prev`
/// reference must point to another migration in the same directory,
/// and the JSON must parse. A broken chain — orphan `prev`, missing
/// predecessor, malformed file — fails at macro-expansion time with
/// a clear `compile_error!`. *No other Rust web framework
/// validates migration chains at compile time*: Cot's migrations are
/// imperative Rust code (no static chain), Loco's are SeaORM
/// up/down (same), Rwf's are raw SQL (no chain at all).
///
/// Each migration is included via `include_str!` so cargo's rebuild
/// detection picks up file *content* changes. Cargo does not watch
/// directory listings, so a new migration file is missed until the
/// crate rebuilds. Add a `build.rs` that tracks the directory:
///
/// ```ignore
/// fn main() { println!("cargo:rerun-if-changed=migrations"); }
/// ```
///
/// A missing directory embeds nothing and emits a deprecation warning.
#[proc_macro]
pub fn embed_migrations(input: TokenStream) -> TokenStream {
    expand_embed_migrations(input.into())
        .unwrap_or_else(syn::Error::into_compile_error)
        .into()
}

/// `Q!()` — `Model.field__lookup = value` filter syntax, resolved at
/// compile time against typed columns. Issue #269 / T1.7.
///
/// Each invocation lowers to the equivalent typed-column method call:
///
/// ```ignore
/// // These expand identically:
/// Q!(User.email__icontains = "alice")
/// User::email.ilike("%alice%")
/// ```
///
/// Field-name typos fail the build (the macro emits `User::no_such_field`
/// which doesn't exist) — the headline ergonomic win of this slice over
/// filters keyed by a plain string.
///
/// # Supported lookup suffixes
///
/// * bare `=` / `__exact` → `.eq(value)`
/// * `__iexact` → `.ilike(value)` (case-insensitive equality, no wildcards)
/// * `__ne` → `.ne(value)`
/// * `__gt` / `__gte` / `__lt` / `__lte` → corresponding comparison
/// * `__contains` / `__icontains` → `.like("%v%")` / `.ilike("%v%")`
/// * `__startswith` / `__istartswith` → `.like("v%")` / `.ilike("v%")`
/// * `__endswith` / `__iendswith` → `.like("%v")` / `.ilike("%v")`
/// * `__in` → `.is_in(iterable)`
/// * `__not_in` → `.not_in(iterable)`
/// * `__isnull = true` → `.is_null()`; `__isnull = false` → `.is_not_null()`
/// * `__between` accepts a tuple literal `(lo, hi)` → `.between(lo, hi)`
/// * `__regex` / `__iregex` → `.regex(pattern)` / `.iregex(pattern)`
///
/// Unknown suffixes fail the build with a `compile_error!` pointing at
/// the lookup token.
///
/// # Combine
///
/// Each `Q!()` returns a `TypedFilter<Model>` — chain via the existing
/// `.and()` / `.or()` / `.not()` methods:
///
/// ```ignore
/// User::objects()
///     .where_(
///         Q!(User.active = true)
///             .and(Q!(User.email__icontains = "alice"))
///     )
///     .fetch(&pool).await?;
/// ```
///
/// All emitted code routes through existing per-dialect writers — no new
/// SQL emission machinery. Tri-dialect support is inherent.
#[allow(non_snake_case)]
#[proc_macro]
pub fn Q(input: TokenStream) -> TokenStream {
    expand_q(input.into())
        .unwrap_or_else(syn::Error::into_compile_error)
        .into()
}

/// `#[rustango::main]` — the runserver entrypoint. Wraps
/// `#[tokio::main]` and a default `tracing_subscriber` initialisation
/// (env-filter, falling back to `info,sqlx=warn`) so user `main`
/// functions are zero-boilerplate. `RUST_LOG` and
/// `RUSTANGO__LOGGING__FORMAT` (e.g. `json`) come from the real
/// environment, else from `./.env` (only those keys are read):
///
/// ```ignore
/// #[rustango::main]
/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
///     rustango::server::Builder::from_env().await?
///         .migrate("migrations").await?
///         .api(my_app::urls::api())
///         .seed_with(my_app::seed::run).await?
///         .serve("0.0.0.0:8080").await
/// }
/// ```
///
/// Optional `flavor = "current_thread"` passes through to
/// `#[tokio::main]`; default is the multi-threaded runtime.
///
/// `logging = false` suppresses the default subscriber, for apps
/// that install their own. Needed whenever the body reaches
/// `Cli::with_logging()` or `logging::Setup`: the subscriber this
/// macro installs gets there first, and `tracing` keeps the first
/// one, so the `[logging]` section would otherwise be read and
/// discarded (#1465).
///
/// ```ignore
/// #[rustango::main(logging = false)]
/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
///     rustango::manage::Cli::new()
///         .with_settings_from_env()
///         .with_logging()          // now the first installer
///         .run().await
/// }
/// ```
///
/// Pulls `tracing-subscriber` into the rustango crate behind the
/// `runtime` sub-feature (implied by `tenancy`), so apps that opt
/// out get plain `#[tokio::main]` ergonomics without the dependency.
#[proc_macro_attribute]
pub fn main(args: TokenStream, item: TokenStream) -> TokenStream {
    expand_main(args.into(), item.into())
        .unwrap_or_else(syn::Error::into_compile_error)
        .into()
}

fn expand_main(args: TokenStream2, item: TokenStream2) -> syn::Result<TokenStream2> {
    let mut input: syn::ItemFn = syn::parse2(item)?;
    if input.sig.asyncness.is_none() {
        return Err(syn::Error::new(
            input.sig.ident.span(),
            "`#[rustango::main]` must wrap an `async fn`",
        ));
    }

    // v0.31.1 (#4): hand-roll the tokio runtime instead of delegating
    // to `#[tokio::main]`. Tokio's proc-macro internally emits
    // `::tokio::*` paths that resolve against the user crate's deps,
    // so calling it through the rustango re-export still requires the
    // user to add tokio to their own Cargo.toml. Building the
    // runtime ourselves keeps the dep transitive through the
    // `runtime` feature on rustango.
    //
    // Parse optional `flavor = "current_thread"` / `flavor =
    // "multi_thread"` from the attribute args. Unknown args are
    // tolerated (forward-compat with tokio's own arg surface).
    let root = rustango_root();
    let flavor = parse_flavor(&args);
    let builder_call = match flavor {
        Flavor::CurrentThread => quote! {
            #root::__private_runtime::tokio::runtime::Builder::new_current_thread()
        },
        Flavor::MultiThread => quote! {
            #root::__private_runtime::tokio::runtime::Builder::new_multi_thread()
        },
    };

    // Detach the user body and rewrite `main` as a sync fn that
    // builds the runtime and blocks on the async body.
    let user_body = input.block.clone();
    input.sig.asyncness = None;

    // `logging = false` drops the block entirely, so a later
    // `Cli::with_logging()` is the first installer and its
    // `[logging]` settings actually take effect (#1465).
    let logging_prologue = if parse_logging(&args) {
        quote! {
            // `Setup`'s defaults, not a copy of them: filter, format and
            // the `Color::Auto` rule live in one place (#1493).
            // `logging` and this macro share the `runtime` gate.
            // The real `RUST_LOG` still wins over `./.env`'s (#2204).
            let _ = #root::logging::Setup::new()
                .with_default_env_filter(#root::__private_runtime::main_default_filter())
                .with_format(#root::__private_runtime::main_format())
                .install();
        }
    } else {
        quote! {}
    };

    input.block = syn::parse2(quote! {{
        { #logging_prologue }
        let __rt = #builder_call
            .enable_all()
            .build()
            .expect("failed to build tokio runtime");
        __rt.block_on(async move #user_body)
    }})?;

    Ok(quote! {
        #input
    })
}

enum Flavor {
    MultiThread,
    CurrentThread,
}

fn parse_flavor(args: &TokenStream2) -> Flavor {
    // Cheap parser: look for the literal token sequence
    // `flavor = "current_thread"`. Everything else (including
    // bare `multi_thread` or no args) defaults to multi-thread.
    let s = args.to_string();
    if s.contains("current_thread") {
        Flavor::CurrentThread
    } else {
        Flavor::MultiThread
    }
}

/// `false` when the attribute carries `logging = false` — the caller
/// installs their own subscriber, usually via `Cli::with_logging`
/// (#1465). Same cheap token match as `parse_flavor`.
fn parse_logging(args: &TokenStream2) -> bool {
    !args.to_string().replace(' ', "").contains("logging=false")
}

/// Parse form for `Q!()` — `<TypePath>.<Ident> = <Expr>`.
struct QInput {
    base_path: syn::Path,
    field: syn::Ident,
    value: syn::Expr,
}

impl syn::parse::Parse for QInput {
    fn parse(input: syn::parse::ParseStream) -> syn::Result<Self> {
        let base_path: syn::Path = input.parse()?;
        input.parse::<syn::Token![.]>()?;
        let field: syn::Ident = input.parse()?;
        input.parse::<syn::Token![=]>()?;
        let value: syn::Expr = input.parse()?;
        Ok(QInput {
            base_path,
            field,
            value,
        })
    }
}

fn expand_q(input: TokenStream2) -> syn::Result<TokenStream2> {
    let q: QInput = syn::parse2(input)?;
    let root = rustango_root();
    let field_str = ident_name(&q.field);
    let field_span = q.field.span();
    let (base, suffix) = match field_str.find("__") {
        Some(idx) => (&field_str[..idx], &field_str[idx + 2..]),
        None => (field_str.as_str(), ""),
    };
    if base.is_empty() {
        return Err(syn::Error::new(
            field_span,
            "Q!(): field name is empty before `__` suffix",
        ));
    }
    let base_ident = ident_from_name(base, field_span);
    let value = &q.value;
    let path = &q.base_path;

    // Most suffixes map directly to a Column method with the value
    // forwarded unchanged. Some need value-shape massaging (wildcards
    // for LIKE-family, tuple destructure for BETWEEN, literal-bool for
    // ISNULL). Unknown suffixes fail the build.
    let expanded = match suffix {
        "" | "exact" => quote! {
            #root::core::Column::eq(#path::#base_ident, #value)
        },
        "ne" => quote! {
            #root::core::Column::ne(#path::#base_ident, #value)
        },
        "gt" => quote! {
            #root::core::Column::gt(#path::#base_ident, #value)
        },
        "gte" => quote! {
            #root::core::Column::gte(#path::#base_ident, #value)
        },
        "lt" => quote! {
            #root::core::Column::lt(#path::#base_ident, #value)
        },
        "lte" => quote! {
            #root::core::Column::lte(#path::#base_ident, #value)
        },
        // The escaped-LIKE lookups delegate to the typed Column
        // methods, which escape the value and pair it with the
        // *Escaped ops so `%` / `_` match literally on every dialect
        // (#1257) — the macro no longer owns any pattern wrapping.
        "iexact" => quote! {
            #root::core::Column::iexact(#path::#base_ident, ::std::string::ToString::to_string(&(#value)))
        },
        "contains" => quote! {
            #root::core::Column::contains(#path::#base_ident, ::std::string::ToString::to_string(&(#value)))
        },
        "icontains" => quote! {
            #root::core::Column::icontains(#path::#base_ident, ::std::string::ToString::to_string(&(#value)))
        },
        "startswith" => quote! {
            #root::core::Column::startswith(#path::#base_ident, ::std::string::ToString::to_string(&(#value)))
        },
        "istartswith" => quote! {
            #root::core::Column::istartswith(#path::#base_ident, ::std::string::ToString::to_string(&(#value)))
        },
        "endswith" => quote! {
            #root::core::Column::endswith(#path::#base_ident, ::std::string::ToString::to_string(&(#value)))
        },
        "iendswith" => quote! {
            #root::core::Column::iendswith(#path::#base_ident, ::std::string::ToString::to_string(&(#value)))
        },
        "in" => quote! {
            #root::core::Column::is_in(#path::#base_ident, #value)
        },
        "not_in" => quote! {
            #root::core::Column::not_in(#path::#base_ident, #value)
        },
        "isnull" => {
            // Must be a bool literal at macro time so we can route to
            // is_null vs is_not_null without a runtime branch.
            let b = match value {
                syn::Expr::Lit(syn::ExprLit {
                    lit: syn::Lit::Bool(b),
                    ..
                }) => b.value(),
                _ => {
                    return Err(syn::Error::new_spanned(
                        value,
                        "Q!(): `__isnull` requires a `true` or `false` literal",
                    ));
                }
            };
            if b {
                quote! { #root::core::Column::is_null(#path::#base_ident) }
            } else {
                quote! { #root::core::Column::is_not_null(#path::#base_ident) }
            }
        }
        "between" => {
            // Accept a tuple literal `(lo, hi)`.
            let tuple = match value {
                syn::Expr::Tuple(t) if t.elems.len() == 2 => t,
                _ => {
                    return Err(syn::Error::new_spanned(
                        value,
                        "Q!(): `__between` requires a tuple literal `(lo, hi)`",
                    ));
                }
            };
            let lo = &tuple.elems[0];
            let hi = &tuple.elems[1];
            quote! { #root::core::Column::between(#path::#base_ident, #lo, #hi) }
        }
        "regex" => quote! {
            #root::core::Column::regex(#path::#base_ident, #value)
        },
        "iregex" => quote! {
            #root::core::Column::iregex(#path::#base_ident, #value)
        },
        _ => {
            return Err(syn::Error::new(
                field_span,
                format!(
                    "Q!(): unknown lookup suffix `__{}`. Supported: __exact / __iexact / __ne / __gt / __gte / __lt / __lte / __contains / __icontains / __startswith / __istartswith / __endswith / __iendswith / __in / __not_in / __isnull / __between / __regex / __iregex",
                    suffix
                ),
            ));
        }
    };
    Ok(expanded)
}

fn expand_embed_migrations(input: TokenStream2) -> syn::Result<TokenStream2> {
    // Default to "./migrations" if invoked without args.
    let path_str = if input.is_empty() {
        "./migrations".to_string()
    } else {
        let lit: LitStr = syn::parse2(input)?;
        lit.value()
    };

    let manifest = std::env::var("CARGO_MANIFEST_DIR").map_err(|_| {
        syn::Error::new(
            proc_macro2::Span::call_site(),
            "embed_migrations! must be invoked during a Cargo build (CARGO_MANIFEST_DIR not set)",
        )
    })?;
    let abs = std::path::Path::new(&manifest).join(&path_str);

    let mut entries: Vec<(String, std::path::PathBuf)> = Vec::new();
    if abs.is_dir() {
        let read = std::fs::read_dir(&abs).map_err(|e| {
            syn::Error::new(
                proc_macro2::Span::call_site(),
                format!("embed_migrations!: cannot read {}: {e}", abs.display()),
            )
        })?;
        for entry in read.flatten() {
            let path = entry.path();
            if !path.is_file() {
                continue;
            }
            if path.extension().and_then(|s| s.to_str()) != Some("json") {
                continue;
            }
            let Some(stem) = path.file_stem().and_then(|s| s.to_str()) else {
                continue;
            };
            entries.push((stem.to_owned(), path));
        }
    }
    entries.sort_by(|a, b| a.0.cmp(&b.0));

    // Compile-time chain validation: read each migration's JSON,
    // pull `name` and `prev` (file-stem-keyed for the chain check),
    // and verify every `prev` points to another migration in the
    // slice. Mismatches between the file stem and the embedded
    // `name` field — and broken `prev` chains — fail at MACRO
    // EXPANSION time so a misshapen migration set never compiles.
    //
    // This is the v0.4 Slice 5 distinguisher: rustango's JSON
    // migrations + a Rust proc-macro that reads them is a combo no
    // other Rust web framework matches (Cot's are imperative Rust
    // code, Loco's are SeaORM up/down, Rwf's are raw SQL — none have
    // a static chain to validate).
    let mut chain_names: Vec<String> = Vec::with_capacity(entries.len());
    let mut prev_refs: Vec<(String, Option<String>)> = Vec::with_capacity(entries.len());
    for (stem, path) in &entries {
        let raw = std::fs::read_to_string(path).map_err(|e| {
            syn::Error::new(
                proc_macro2::Span::call_site(),
                format!(
                    "embed_migrations!: cannot read {} for chain validation: {e}",
                    path.display()
                ),
            )
        })?;
        let json: serde_json::Value = serde_json::from_str(&raw).map_err(|e| {
            syn::Error::new(
                proc_macro2::Span::call_site(),
                format!(
                    "embed_migrations!: {} is not valid JSON: {e}",
                    path.display()
                ),
            )
        })?;
        let name = json
            .get("name")
            .and_then(|v| v.as_str())
            .ok_or_else(|| {
                syn::Error::new(
                    proc_macro2::Span::call_site(),
                    format!(
                        "embed_migrations!: {} is missing the `name` field",
                        path.display()
                    ),
                )
            })?
            .to_owned();
        if name != *stem {
            return Err(syn::Error::new(
                proc_macro2::Span::call_site(),
                format!(
                    "embed_migrations!: file stem `{stem}` does not match the migration's \
                     `name` field `{name}` — rename the file or fix the JSON",
                ),
            ));
        }
        let prev = json.get("prev").and_then(|v| v.as_str()).map(str::to_owned);
        chain_names.push(name.clone());
        prev_refs.push((name, prev));
    }

    let name_set: std::collections::HashSet<&str> =
        chain_names.iter().map(String::as_str).collect();
    for (name, prev) in &prev_refs {
        if let Some(p) = prev {
            if !name_set.contains(p.as_str()) {
                return Err(syn::Error::new(
                    proc_macro2::Span::call_site(),
                    format!(
                        "embed_migrations!: broken migration chain — `{name}` declares \
                         prev=`{p}` but no migration with that name exists in {}",
                        abs.display()
                    ),
                ));
            }
        }
    }

    let pairs: Vec<TokenStream2> = entries
        .iter()
        .map(|(name, path)| {
            let path_lit = path.display().to_string();
            quote! { (#name, ::core::include_str!(#path_lit)) }
        })
        .collect();

    // A wrong path used to embed nothing silently; a deprecation use is
    // the only stable way for a proc macro to warn without breaking builds.
    let missing_warning = if abs.is_dir() {
        quote! {}
    } else {
        let note = format!(
            "embed_migrations!: directory {} does not exist; no migrations are embedded",
            abs.display()
        );
        quote! {
            #[deprecated(note = #note)]
            const __RUSTANGO_MIGRATIONS_DIR_MISSING: () = ();
            #[allow(clippy::let_unit_value)]
            let _ = __RUSTANGO_MIGRATIONS_DIR_MISSING;
        }
    };

    Ok(quote! {
        {
            #missing_warning
            const __RUSTANGO_EMBEDDED: &[(&'static str, &'static str)] = &[#(#pairs),*];
            __RUSTANGO_EMBEDDED
        }
    })
}

fn expand(input: &DeriveInput) -> syn::Result<TokenStream2> {
    let root = rustango_root();
    let struct_name = &input.ident;

    let Data::Struct(data) = &input.data else {
        return Err(syn::Error::new_spanned(
            struct_name,
            "Model can only be derived on structs",
        ));
    };
    let Fields::Named(named) = &data.fields else {
        return Err(syn::Error::new_spanned(
            struct_name,
            "Model requires a struct with named fields",
        ));
    };

    let container = parse_container_attrs(input)?;
    let table = container
        .table
        .unwrap_or_else(|| to_snake_case(&struct_name.to_string()));
    let model_name = struct_name.to_string();

    let collected = collect_fields(named, &table)?;

    // Validate that #[rustango(display = "…")] names a real field.
    if let Some((ref display, span)) = container.display {
        if !collected.field_names.iter().any(|n| n == display) {
            return Err(syn::Error::new(
                span,
                format!("`display = \"{display}\"` does not match any field on this struct"),
            ));
        }
    }
    let display = container.display.map(|(name, _)| name);
    let app_label = container.app.clone();

    // Validate admin field-name lists against declared field names.
    // Note: `list_display` is intentionally NOT validated here. As of
    // v0.32 it may also reference inventory-registered computed
    // fields (via `register_admin_computed!`) whose existence the
    // macro can't see at compile time — they're submitted from any
    // crate that depends on rustango. The runtime list-view resolves
    // unknown names against the inventory + silently drops the
    // truly-bogus ones, which is the cheaper trade-off versus
    // forcing a per-Model attr to opt out.
    if let Some(admin) = &container.admin {
        for (label, list) in [
            ("search_fields", &admin.search_fields),
            ("readonly_fields", &admin.readonly_fields),
            ("list_filter", &admin.list_filter),
        ] {
            if let Some((names, span)) = list {
                for name in names {
                    if !collected.field_names.iter().any(|n| n == name) {
                        return Err(syn::Error::new(
                            *span,
                            format!(
                                "`{label} = \"{name}\"`: \"{name}\" is not a declared field on this struct"
                            ),
                        ));
                    }
                }
            }
        }
        if let Some((pairs, span)) = &admin.ordering {
            for (name, _) in pairs {
                if !collected.field_names.iter().any(|n| n == name) {
                    return Err(syn::Error::new(
                        *span,
                        format!(
                            "`ordering = \"{name}\"`: \"{name}\" is not a declared field on this struct"
                        ),
                    ));
                }
            }
        }
        if let Some((groups, span)) = &admin.fieldsets {
            for (_, fields) in groups {
                for name in fields {
                    if !collected.field_names.iter().any(|n| n == name) {
                        return Err(syn::Error::new(
                            *span,
                            format!(
                                "`fieldsets`: \"{name}\" is not a declared field on this struct"
                            ),
                        ));
                    }
                }
            }
        }
    }
    if let Some(audit) = &container.audit {
        if let Some((names, span)) = &audit.track {
            for name in names {
                if !collected.field_names.iter().any(|n| n == name) {
                    return Err(syn::Error::new(
                        *span,
                        format!(
                            "`audit(track = \"{name}\")`: \"{name}\" is not a declared field on this struct"
                        ),
                    ));
                }
            }
        }
    }

    // Issue #291 / T2.5 — validate each `default_order` column name
    // against the model's collected fields. Typos fail at macro-expand
    // time, not at the database.
    for (col, _desc, span) in &container.default_order {
        if !collected.field_names.iter().any(|n| n == col) {
            return Err(syn::Error::new(
                *span,
                format!(
                    "`default_order = \"...\"`: \"{col}\" is not a declared field on this struct"
                ),
            ));
        }
    }

    // Build the audit_track list for ModelSchema: None when no audit attr,
    // Some(empty) when audit present without track, Some(names) when explicit.
    let audit_track_names: Option<Vec<String>> = container.audit.as_ref().map(|audit| {
        audit
            .track
            .as_ref()
            .map(|(names, _)| names.clone())
            .unwrap_or_default()
    });

    // The upsert conflict target: a container-level composite unique,
    // never a field `index(unique)` or a partial index PG can't target.
    let upsert_unique: Option<Vec<String>> = container
        .indexes
        .iter()
        .find(|i| i.unique && i.where_clause.is_none() && !i.columns.is_empty())
        .map(|i| i.columns.clone());

    // Merge field-level indexes into the container's index list.
    let mut all_indexes: Vec<IndexAttr> = container.indexes;
    for field in &named.named {
        let ident = field.ident.as_ref().expect("named");
        // The same default column as `process_field` (#1937).
        let col = ident_name(ident);
        // Re-parse field attrs to check for index flag
        if let Ok(fa) = parse_field_attrs(field) {
            if fa.index {
                let col_name = fa.column.clone().unwrap_or_else(|| col.clone());
                let auto_name = capped_index_name(if fa.index_unique {
                    format!("{table}_{col_name}_uq_idx")
                } else {
                    format!("{table}_{col_name}_idx")
                });
                all_indexes.push(IndexAttr {
                    name: fa.index_name.or(Some(auto_name)),
                    columns: vec![col_name],
                    unique: fa.index_unique,
                    method: fa.index_method,
                    where_clause: None,
                    include: Vec::new(),
                });
            }
        }
    }
    // An unbounded String is LONGTEXT on MySQL, which no key can hold (1170, #2575).
    for field in &named.named {
        let (Ok(fa), Ok(det)) = (parse_field_attrs(field), detect_type(&field.ty)) else {
            continue;
        };
        if det.kind != DetectedKind::String || fa.max_length.is_some() {
            continue;
        }
        let col = fa
            .column
            .clone()
            .unwrap_or_else(|| ident_name(field.ident.as_ref().expect("named")));
        // MySQL indexes every foreign-key column too.
        let relation = det.fk_inner.is_some() || fa.fk.is_some() || fa.o2o.is_some();
        if fa.primary_key
            || fa.unique
            || relation
            || all_indexes.iter().any(|i| i.columns.contains(&col))
        {
            return Err(syn::Error::new_spanned(
                field,
                "a primary-key, unique, indexed or foreign-key `String` needs \
                 `max_length`: MySQL cannot index an unbounded (LONGTEXT) column",
            ));
        }
    }

    let model_impl = model_impl_tokens(
        struct_name,
        &model_name,
        &table,
        display.as_deref(),
        app_label.as_deref(),
        container.admin.as_ref(),
        &container.default_order,
        &collected.field_schemas,
        collected.soft_delete_column.as_deref(),
        container.permissions,
        audit_track_names.as_deref(),
        &container.m2m,
        &all_indexes,
        &container.checks,
        &container.excludes,
        &container.composite_fks,
        &container.generic_fks,
        container.scope.as_deref(),
        container.is_view,
        container.verbose_name.as_deref(),
        container.verbose_name_plural.as_deref(),
        container.managed,
        container.base_manager_name.as_deref(),
        container.order_with_respect_to.as_deref(),
        container.proxy,
        &container.required_db_features,
        container.required_db_vendor.as_deref(),
        container.default_related_name.as_deref(),
        container.db_table_comment.as_deref(),
        container
            .get_latest_by
            .as_ref()
            .map(|(c, d)| (c.as_str(), *d)),
        &container.extra_permissions,
        &container.default_permissions,
        &container.global_scopes,
        &container.reverse_has_relations,
        &container.generic_has_relations,
    );
    let module_ident = column_module_ident(struct_name);
    let column_consts = column_const_tokens(&module_ident, &collected.column_entries);
    let audited_fields: Option<Vec<&ColumnEntry>> = container.audit.as_ref().map(|audit| {
        let track_set: Option<std::collections::HashSet<&str>> = audit
            .track
            .as_ref()
            .map(|(names, _)| names.iter().map(String::as_str).collect());
        collected
            .column_entries
            .iter()
            .filter(|c| {
                track_set
                    .as_ref()
                    .map_or(true, |s| s.contains(c.name.as_str()))
            })
            .collect()
    });
    let inherent_impl = inherent_impl_tokens(
        struct_name,
        &collected,
        collected.primary_key.as_ref(),
        &column_consts,
        audited_fields.as_deref(),
        upsert_unique.as_deref(),
        &container.manager_fns,
    );
    let column_module = column_module_tokens(&module_ident, struct_name, &collected.column_entries);
    let from_row_impl = from_row_impl_tokens(
        struct_name,
        &collected.from_row_inits,
        &collected.from_row_inits_my,
    );
    let reverse_helpers = reverse_helper_tokens(
        struct_name,
        &collected.fk_relations,
        container.default_related_name.as_deref(),
    )?;
    let m2m_accessors = m2m_accessor_tokens(struct_name, &container.m2m);
    let generic_m2m_accessors = generic_m2m_accessor_tokens(struct_name, &container.generic_m2m);
    // Issue #817 — `#[rustango(through(...))]` accessors.
    let through_accessors = through_accessor_tokens(struct_name, &container.through_relations);
    // Issue #830 — `#[rustango(reverse_has(...))]` static accessors.
    let reverse_has_accessors =
        reverse_has_accessor_tokens(struct_name, &container.reverse_has_relations);
    let generic_fk_accessors = generic_fk_accessor_tokens(
        struct_name,
        &container.generic_fks,
        &collected.column_entries,
    );

    Ok(quote! {
        #model_impl
        #inherent_impl
        #from_row_impl
        #column_module
        #reverse_helpers
        #m2m_accessors
        #generic_m2m_accessors
        #through_accessors
        #reverse_has_accessors
        #generic_fk_accessors

        #root::core::inventory::submit! {
            // `module_path!()` evaluates at the registration site,
            // so a Model declared in `crate::blog::models` records
            // `"<crate>::blog::models"` and `resolved_app_label()`
            // can infer "blog" without an explicit attribute.
            #root::core::ModelEntry::new(
                <#struct_name as #root::core::Model>::SCHEMA,
                ::core::module_path!(),
            )
            .with_audited(
                <#struct_name as #root::core::Model>::__rustango_audited_update,
                <#struct_name as #root::core::Model>::__rustango_audited_delete,
            )
            .with_audited_create(<#struct_name as #root::core::Model>::__rustango_audited_create)
            .with_audited_update_record(
                <#struct_name as #root::core::Model>::__rustango_audited_update_record,
            )
        }
    })
}

/// Guard before decoding a `select_related` target (#2293): a NULL nullable
/// FK leaves the relation unloaded; a set FK whose row is missing is an error.
fn join_guard_tokens(rel: &FkRelation, receiver: &TokenStream2) -> TokenStream2 {
    let root = rustango_root();
    let parent_ty = &rel.parent_type;
    let field_ident = &rel.field_ident;
    let null_fk = if rel.nullable {
        quote! {
            if #receiver.#field_ident.is_none() {
                return ::core::result::Result::Ok(false);
            }
        }
    } else {
        quote! {}
    };
    quote! {
        #null_fk
        #root::sql::__rustango_require_join(
            row, <#parent_ty as #root::core::Model>::SCHEMA, alias,
        )?;
    }
}

/// A target an earlier chain already loaded (`a__b` before `a__c`) is
/// reused, and the deeper chain stitched into it; re-decoding it would
/// drop what that chain loaded.
fn loaded_reuse_tokens(
    rel: &FkRelation,
    receiver: &TokenStream2,
    load: &TokenStream2,
) -> TokenStream2 {
    let root = rustango_root();
    let field_ident = &rel.field_ident;
    let pattern = if rel.nullable {
        quote!(::core::option::Option::Some(#root::sql::ForeignKey::Loaded { value: __loaded, .. }))
    } else {
        quote!(#root::sql::ForeignKey::Loaded { value: __loaded, .. })
    };
    quote! {
        if let #pattern = &mut #receiver.#field_ident {
            if let ::core::option::Option::Some(__r) = __rest {
                let _ = #load(&mut **__loaded, row, __r, &__next_alias)?;
            }
            return ::core::result::Result::Ok(true);
        }
    }
}

/// Store the decoded `_parent` on the FK field, keeping the key the row
/// holds: with `on = <unique column>` it is not the parent's PK.
fn loaded_assign_tokens(rel: &FkRelation, receiver: &TokenStream2) -> TokenStream2 {
    let root = rustango_root();
    let field_ident = &rel.field_ident;
    if rel.nullable {
        quote! {
            if let ::core::option::Option::Some(__fk) = &mut #receiver.#field_ident {
                let _pk = ::core::clone::Clone::clone(__fk.pk_ref());
                *__fk = #root::sql::ForeignKey::loaded(_pk, _parent);
            }
        }
    } else {
        quote! {
            let _pk = ::core::clone::Clone::clone(#receiver.#field_ident.pk_ref());
            #receiver.#field_ident = #root::sql::ForeignKey::loaded(_pk, _parent);
        }
    }
}

/// Emit `impl LoadRelated for #StructName` — slice 9.0d. Pattern-
/// matches `field_name` against the model's FK fields and, for a
/// match, decodes the FK target via the parent's macro-generated
/// `__rustango_from_aliased_row`, and stores `ForeignKey::Loaded` on
/// `self` under the key the row already holds.
///
/// Always emitted (with empty arms for FK-less models, which
/// return `Ok(false)` for any field name) so the `T: LoadRelated`
/// trait bound on `fetch_on` is universally satisfied — users
/// never have to think about implementing it.
fn load_related_impl_tokens(struct_name: &syn::Ident, fk_relations: &[FkRelation]) -> TokenStream2 {
    let root = rustango_root();
    let arms = fk_relations.iter().map(|rel| {
        let parent_ty = &rel.parent_type;
        let field_ident = &rel.field_ident;
        let fk_name = ident_name(field_ident);
        let fk_col = fk_name.as_str();
        let guard = join_guard_tokens(rel, &quote!(self));
        let reuse = loaded_reuse_tokens(
            rel,
            &quote!(self),
            &quote!(#root::sql::LoadRelated::__rustango_load_related),
        );
        let assign = loaded_assign_tokens(rel, &quote!(self));
        quote! {
            #fk_col => {
                #guard
                #reuse
                let mut _parent: #parent_ty = <#parent_ty>::__rustango_from_aliased_row(row, alias)?;
                // Audit #451 — multi-hop `select_related("a__b__c")`:
                // stitch the deeper relation onto this parent first,
                // decoding it at the accumulated `__next_alias`. The
                // parent type also impls `LoadRelated`, so this recurses
                // the FK chain to arbitrary depth.
                if let ::core::option::Option::Some(__r) = __rest {
                    let _ = #root::sql::LoadRelated::__rustango_load_related(
                        &mut _parent, row, __r, &__next_alias,
                    )?;
                }
                #assign
                ::core::result::Result::Ok(true)
            }
        }
    });
    quote! {
        #[cfg(feature = "postgres")]
        impl #root::sql::LoadRelated for #struct_name {
            #[allow(unused_variables)]
            fn __rustango_load_related(
                &mut self,
                row: &#root::sql::sqlx::postgres::PgRow,
                field_name: &str,
                alias: &str,
            ) -> ::core::result::Result<bool, #root::sql::sqlx::Error> {
                // Audit #451 — split the multi-hop path: `base` is the FK
                // on THIS model, `__rest` (if any) is the remaining chain
                // to stitch onto the loaded parent. `__next_alias` is the
                // accumulated join alias the parent's columns live under
                // (`{alias}__{next-hop}`), matching `lower_select_related`.
                let (__base, __rest): (&str, ::core::option::Option<&str>) =
                    match field_name.split_once("__") {
                        ::core::option::Option::Some((b, r)) => (b, ::core::option::Option::Some(r)),
                        ::core::option::Option::None => (field_name, ::core::option::Option::None),
                    };
                let __next_alias: ::std::string::String = match __rest {
                    ::core::option::Option::Some(__r) => {
                        let __rb = __r.split_once("__").map(|(b, _)| b).unwrap_or(__r);
                        ::std::format!("{}__{}", alias, __rb)
                    }
                    ::core::option::Option::None => ::std::string::String::new(),
                };
                match __base {
                    #( #arms )*
                    _ => ::core::result::Result::Ok(false),
                }
            }
        }
    }
}

/// MySQL counterpart of [`load_related_impl_tokens`] — v0.23.0-batch8.
/// Emits a call to the cfg-gated `__impl_my_load_related!` macro_rules,
/// which expands to a `LoadRelatedMy` impl when rustango is built with
/// the `mysql` feature, and to nothing otherwise. The decoded parent
/// is read via `__rustango_from_aliased_my_row` (the MySQL aliased
/// decoder, also batch8) so the dual emission is symmetric across
/// backends.
fn load_related_impl_my_tokens(
    struct_name: &syn::Ident,
    fk_relations: &[FkRelation],
) -> TokenStream2 {
    let root = rustango_root();
    let arms = fk_relations.iter().map(|rel| {
        let parent_ty = &rel.parent_type;
        let field_ident = &rel.field_ident;
        let fk_name = ident_name(field_ident);
        let fk_col = fk_name.as_str();
        let guard = join_guard_tokens(rel, &quote!(__self));
        let reuse = loaded_reuse_tokens(
            rel,
            &quote!(__self),
            &quote!(#root::sql::LoadRelatedMy::__rustango_load_related_my),
        );
        let assign = loaded_assign_tokens(rel, &quote!(__self));
        // `self` IS hygiene-tracked through macro_rules — emitted from
        // a different context than the `&mut self` parameter inside
        // the macro_rules-expanded fn. Pass it through as `__self`
        // and let the macro_rules rebind it to the receiver.
        quote! {
            #fk_col => {
                #guard
                #reuse
                let mut _parent: #parent_ty =
                    <#parent_ty>::__rustango_from_aliased_my_row(row, alias)?;
                // Audit #451 — multi-hop: stitch the deeper relation onto
                // the parent at the accumulated alias (see PG twin).
                if let ::core::option::Option::Some(__r) = __rest {
                    let _ = #root::sql::LoadRelatedMy::__rustango_load_related_my(
                        &mut _parent, row, __r, &__next_alias,
                    )?;
                }
                #assign
                ::core::result::Result::Ok(true)
            }
        }
    });
    quote! {
        #root::__impl_my_load_related!(#struct_name, |__self, row, field_name, alias, __rest, __next_alias| {
            #( #arms )*
        });
    }
}

/// Same shape as [`load_related_impl_my_tokens`] but for SQLite.
/// Emits a call to `__impl_sqlite_load_related!` which expands to a
/// `LoadRelatedSqlite` impl when the `sqlite` feature is on.
fn load_related_impl_sqlite_tokens(
    struct_name: &syn::Ident,
    fk_relations: &[FkRelation],
) -> TokenStream2 {
    let root = rustango_root();
    let arms = fk_relations.iter().map(|rel| {
        let parent_ty = &rel.parent_type;
        let field_ident = &rel.field_ident;
        let fk_name = ident_name(field_ident);
        let fk_col = fk_name.as_str();
        let guard = join_guard_tokens(rel, &quote!(__self));
        let reuse = loaded_reuse_tokens(
            rel,
            &quote!(__self),
            &quote!(#root::sql::LoadRelatedSqlite::__rustango_load_related_sqlite),
        );
        let assign = loaded_assign_tokens(rel, &quote!(__self));
        quote! {
            #fk_col => {
                #guard
                #reuse
                let mut _parent: #parent_ty =
                    <#parent_ty>::__rustango_from_aliased_sqlite_row(row, alias)?;
                // Audit #451 — multi-hop: stitch the deeper relation onto
                // the parent at the accumulated alias (see PG twin).
                if let ::core::option::Option::Some(__r) = __rest {
                    let _ = #root::sql::LoadRelatedSqlite::__rustango_load_related_sqlite(
                        &mut _parent, row, __r, &__next_alias,
                    )?;
                }
                #assign
                ::core::result::Result::Ok(true)
            }
        }
    });
    quote! {
        #root::__impl_sqlite_load_related!(#struct_name, |__self, row, field_name, alias, __rest, __next_alias| {
            #( #arms )*
        });
    }
}

/// Emit `impl FkPkAccess for #StructName` — slice 9.0e. Pattern-
/// matches `field_name` against the model's FK fields and returns
/// the FK's stored PK as `i64`. Used by `fetch_with_prefetch` to
/// group children by parent PK.
///
/// Always emitted (with `_ => None` for FK-less models) so the
/// trait bound on `fetch_with_prefetch` is universally satisfied.
fn fk_pk_access_impl_tokens(struct_name: &syn::Ident, fk_relations: &[FkRelation]) -> TokenStream2 {
    let root = rustango_root();
    let arms = fk_relations.iter().map(|rel| {
        let field_ident = &rel.field_ident;
        let fk_name = ident_name(field_ident);
        let fk_col = fk_name.as_str();
        if rel.pk_kind == DetectedKind::I64 {
            // i64 FK — return the stored PK so prefetch_related can
            // group children by it. Nullable variant unwraps via
            // `as_ref().map(...)`: an unset (NULL) FK column yields
            // `None` and that child sits out of the grouping (correct
            // semantics — it has no parent to attach to).
            if rel.nullable {
                quote! {
                    #fk_col => self.#field_ident
                        .as_ref()
                        .map(|fk| #root::sql::ForeignKey::pk(fk)),
                }
            } else {
                quote! {
                    #fk_col => ::core::option::Option::Some(self.#field_ident.pk()),
                }
            }
        } else {
            // Non-i64 FK PKs (e.g. `ForeignKey<T, String>`,
            // `ForeignKey<T, Uuid>`) opt out of `prefetch_related`'s
            // i64-keyed grouping path — the trait signature is
            // `Option<i64>` and a non-i64 PK can't lower into it.
            // The FK still works for everything else (CRUD, lazy
            // load via `.get()`, select_related JOINs); only the
            // bulk prefetch grouper needs the integer key.
            quote! {
                #fk_col => ::core::option::Option::None,
            }
        }
    });
    // PK-type-agnostic version: every FK arm emits an
    // `Option<SqlValue>` so `fetch_with_prefetch` can group by any
    // PK type (i64, i32, String, Uuid). Models with non-i64 FK PKs
    // opt OUT of the legacy i64 method (it returns None) but opt IN
    // here.
    let value_arms = fk_relations.iter().map(|rel| {
        let field_ident = &rel.field_ident;
        let fk_name = ident_name(field_ident);
        let fk_col = fk_name.as_str();
        if rel.nullable {
            quote! {
                #fk_col => self.#field_ident
                    .as_ref()
                    .map(|fk| ::core::convert::Into::<#root::core::SqlValue>::into(
                        #root::sql::ForeignKey::pk(fk)
                    )),
            }
        } else {
            quote! {
                #fk_col => ::core::option::Option::Some(
                    ::core::convert::Into::<#root::core::SqlValue>::into(
                        self.#field_ident.pk()
                    )
                ),
            }
        }
    });
    quote! {
        impl #root::sql::FkPkAccess for #struct_name {
            #[allow(unused_variables)]
            fn __rustango_fk_pk(&self, field_name: &str) -> ::core::option::Option<i64> {
                match field_name {
                    #( #arms )*
                    _ => ::core::option::Option::None,
                }
            }
            #[allow(unused_variables)]
            fn __rustango_fk_pk_value(
                &self,
                field_name: &str,
            ) -> ::core::option::Option<#root::core::SqlValue> {
                match field_name {
                    #( #value_arms )*
                    _ => ::core::option::Option::None,
                }
            }
        }
    }
}

/// `related_name = "+"`: the FK gets no reverse accessor on its parent.
const NO_REVERSE_ACCESSOR: &str = "+";

/// For every `ForeignKey<Parent>` field on `Child`, emit
/// `impl Parent { pub async fn <child_table>_set(&self, executor) -> Vec<Child> }`.
/// Reads the parent's PK via the macro-generated `__rustango_pk_value`
/// and runs a single `SELECT … FROM <child_table> WHERE <fk_column> = $1`
/// — the canonical reverse-FK fetch. One round trip, no N+1.
///
/// **PG-only emission**: the accessor is bounded on
/// `sqlx::Executor<Database = sqlx::Postgres>` and calls `fetch_on`,
/// both of which are gated behind the `postgres` cargo feature. The
/// emitted code is wrapped in `#[cfg(feature = "postgres")]` so the
/// model derive itself compiles on tri-dialect / sqlite-only
/// downstream builds — the accessor just isn't materialised. A tri-
/// dialect `_set_pool` variant is a separate follow-up.
fn reverse_helper_tokens(
    child_ident: &syn::Ident,
    fk_relations: &[FkRelation],
    default_related_name: Option<&str>,
) -> syn::Result<TokenStream2> {
    let root = rustango_root();
    // `related_name = "+"`: no accessor, so a parent from another crate works.
    let fk_relations: Vec<&FkRelation> = fk_relations
        .iter()
        .filter(|rel| rel.related_name.as_deref() != Some(NO_REVERSE_ACCESSOR))
        .collect();
    if fk_relations.is_empty() {
        return Ok(TokenStream2::new());
    }
    // Method-name resolution per FK (issue #816 + follow-up):
    //   1. Field-level `#[rustango(related_name = "...")]` on the FK
    //      itself — wins over everything else.
    //   2. Container-level `default_related_name = "..."` on the
    //      child. Applies to every FK on this model that didn't
    //      override.
    //   3. Fallback: `<child_snake>_set`. `Post` → `post_set`,
    //      `BlogComment` → `blog_comment_set`. Avoids English-plural
    //      edge cases.
    //
    // The PG-on-executor variant keeps the resolved name; the
    // tri-dialect `_pool` variant appends `_pool` to it (matches the
    // framework's convention for the `&Pool` flavor of every helper).
    let default_pg_suffix = default_related_name
        .map(str::to_owned)
        .unwrap_or_else(|| format!("{}_set", to_snake_case(&ident_name(child_ident))));
    let name_of = |rel: &FkRelation| {
        rel.related_name
            .clone()
            .unwrap_or_else(|| default_pg_suffix.clone())
    };
    // Two FKs to one parent would define the same method twice (E0592).
    for (i, rel) in fk_relations.iter().enumerate() {
        let parent_ty = &rel.parent_type;
        let parent = quote!(#parent_ty).to_string();
        let name = name_of(rel);
        if let Some(first) = fk_relations[..i].iter().find(|r| {
            let other = &r.parent_type;
            quote!(#other).to_string() == parent && name_of(r) == name
        }) {
            return Err(syn::Error::new_spanned(
                &rel.field_ident,
                format!(
                    "`{}` and `{}` both point at `{parent}` and would both add `{parent}::{name}`; \
                     give one `#[rustango(related_name = \"...\")]`, or `related_name = \"+\"` for none",
                    first.field_ident, rel.field_ident
                ),
            ));
        }
    }
    let impls = fk_relations.iter().map(|rel| {
        let pg_suffix = name_of(rel);
        let pool_suffix = format!("{}_pool", pg_suffix);
        let pg_method_ident = syn::Ident::new(&pg_suffix, child_ident.span());
        let pool_method_ident = syn::Ident::new(&pool_suffix, child_ident.span());
        let parent_ty = &rel.parent_type;
        let fk_name = ident_name(&rel.field_ident);
        let fk_col = fk_name.as_str();
        let doc = format!(
            "Fetch every `{child_ident}` whose `{fk_col}` foreign key points at this row. \
             Single SQL query — `SELECT … FROM <{child_ident} table> WHERE {fk_col} = $1` — \
             generated from the FK declaration on `{child_ident}::{fk_col}`. Composes with \
             further `{child_ident}::objects()` filters via direct queryset use."
        );
        let pool_doc = format!(
            "Tri-dialect counterpart of [`Self::{pg_suffix}`] — takes \
             [`#root::sql::Pool`] and dispatches per backend so the \
             reverse-FK fetch works on PG / MySQL / SQLite under one method. \
             Use this from framework code that holds a `&Pool` (admin, \
             tenancy resolver, viewset handlers); reach for the executor- \
             bound variant when you already have a typed `sqlx::Executor`."
        );
        quote! {
            #[cfg(feature = "postgres")]
            impl #parent_ty {
                #[doc = #doc]
                ///
                /// # Errors
                /// Returns [`#root::sql::ExecError`] for SQL-writing
                /// or driver failures.
                pub async fn #pg_method_ident<'_c, _E>(
                    &self,
                    _executor: _E,
                ) -> ::core::result::Result<
                    ::std::vec::Vec<#child_ident>,
                    #root::sql::ExecError,
                >
                where
                    _E: #root::sql::sqlx::Executor<
                        '_c,
                        Database = #root::sql::sqlx::Postgres,
                    >,
                {
                    let _pk: #root::core::SqlValue = self.__rustango_pk_value();
                    #root::query::QuerySet::<#child_ident>::new()
                        .filter_op(#fk_col, #root::core::Op::Eq, _pk)
                        .fetch_on(_executor)
                        .await
                }
            }

            impl #parent_ty {
                #[doc = #pool_doc]
                ///
                /// # Errors
                /// Returns [`#root::sql::ExecError`] for SQL-writing
                /// or driver failures.
                pub async fn #pool_method_ident(
                    &self,
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<
                    ::std::vec::Vec<#child_ident>,
                    #root::sql::ExecError,
                > {
                    use #root::sql::FetcherPool as _;
                    let _pk: #root::core::SqlValue = self.__rustango_pk_value();
                    #root::query::QuerySet::<#child_ident>::new()
                        .filter_op(#fk_col, #root::core::Op::Eq, _pk)
                        .fetch(pool)
                        .await
                }
            }
        }
    });
    Ok(quote! { #( #impls )* })
}

/// Emit `<name>_m2m(&self) -> M2MManager` inherent methods for every M2M
/// relation declared on the model.
/// Emit `{name}_pool` accessor + `set_{name}_for` setter for every
/// `#[rustango(generic_fk(name, ct_column, pk_column))]` declaration.
///
/// Closes #239 + #240 — `comment.content_object` /
/// `comment.content_object = post` ergonomics on top of the existing
/// `GenericForeignKey { content_type_id, object_pk }` primitive.
///
/// `column_entries` is passed so we can resolve each `ct_column` /
/// `pk_column` SQL name back to its Rust field ident — the macro
/// only sees the column-side strings in the attribute, but the
/// emitted accessor needs to read the actual struct field.
fn generic_fk_accessor_tokens(
    struct_name: &syn::Ident,
    generic_fks: &[GenericFkAttr],
    column_entries: &[ColumnEntry],
) -> TokenStream2 {
    let root = rustango_root();
    if generic_fks.is_empty() {
        return TokenStream2::new();
    }
    let methods = generic_fks.iter().filter_map(|gfk| {
        // Resolve `ct_column` + `pk_column` to the struct's Rust
        // field idents. A typo (column name doesn't match any field)
        // emits no method for that registration — the user will see
        // the compiler reject the SCHEMA literal anyway, so there's
        // a clear error path without us double-reporting.
        let ct_ident = column_entries
            .iter()
            .find(|c| c.column == gfk.ct_column)
            .map(|c| c.ident.clone())?;
        let pk_ident = column_entries
            .iter()
            .find(|c| c.column == gfk.pk_column)
            .map(|c| c.ident.clone())?;

        let accessor_ident =
            syn::Ident::new(&format!("{}_pool", gfk.name), struct_name.span());
        let setter_ident =
            syn::Ident::new(&format!("set_{}_for", gfk.name), struct_name.span());
        let name_literal = gfk.name.as_str();

        Some(quote! {
            #[doc = concat!(
                "Resolve the polymorphic `",
                #name_literal,
                "` relation. Reads `self.",
                stringify!(#ct_ident),
                "` + `self.",
                stringify!(#pk_ident),
                "`, looks up the matching `ContentType`, and fetches the target row as a JSON map.\n\n",
                "Returns `Ok(None)` when the ContentType is stale / unseeded or the target row was deleted. Emitted by `#[rustango(generic_fk(name = \"",
                #name_literal,
                "\", ...))]`."
            )]
            pub async fn #accessor_ident(
                &self,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::core::option::Option<#root::__serde_json::Value>,
                #root::sql::ExecError,
            > {
                let gfk = #root::contenttypes::GenericForeignKey::new(
                    self.#ct_ident as i64,
                    self.#pk_ident as i64,
                );
                gfk.get_object(pool).await
            }

            #[doc = concat!(
                "Set the polymorphic `",
                #name_literal,
                "` target. Looks up the `ContentType` for `T` via the cached registry, then assigns both `self.",
                stringify!(#ct_ident),
                "` and `self.",
                stringify!(#pk_ident),
                "`.\n\nFollow with `self.insert(pool)` or `self.update(pool)` to persist. Emitted by `#[rustango(generic_fk(name = \"",
                #name_literal,
                "\", ...))]`."
            )]
            pub async fn #setter_ident<T: #root::core::Model>(
                &mut self,
                pool: &#root::sql::Pool,
                target_pk: i64,
            ) -> ::core::result::Result<(), #root::sql::ExecError> {
                let gfk = #root::contenttypes::GenericForeignKey::for_target::<T>(
                    pool,
                    target_pk,
                ).await?;
                self.#ct_ident = gfk.content_type_id as _;
                self.#pk_ident = gfk.object_pk as _;
                ::core::result::Result::Ok(())
            }
        })
    });
    quote! {
        impl #struct_name {
            #( #methods )*
        }
    }
}

fn m2m_accessor_tokens(struct_name: &syn::Ident, m2m_relations: &[M2MAttr]) -> TokenStream2 {
    let root = rustango_root();
    if m2m_relations.is_empty() {
        return TokenStream2::new();
    }
    let methods = m2m_relations.iter().map(|rel| {
        let method_name = format!("{}_m2m", rel.name);
        let method_ident = syn::Ident::new(&method_name, struct_name.span());
        let through = rel.through.as_str();
        let src_col = rel.src.as_str();
        let dst_col = rel.dst.as_str();
        quote! {
            pub fn #method_ident(&self) -> #root::sql::M2MManager {
                #root::sql::M2MManager {
                    src_pk: self.__rustango_pk_value(),
                    through: #through,
                    src_col: #src_col,
                    dst_col: #dst_col,
                }
            }
        }
    });
    quote! {
        impl #struct_name {
            #( #methods )*
        }
    }
}

/// Emit `<name>_m2m(&self) -> GenericM2MManager` inherent methods for
/// every `#[rustango(generic_m2m(...))]` (polymorphic M2M, issue #818).
fn generic_m2m_accessor_tokens(
    struct_name: &syn::Ident,
    relations: &[GenericM2MAttr],
) -> TokenStream2 {
    let root = rustango_root();
    if relations.is_empty() {
        return TokenStream2::new();
    }
    let methods = relations.iter().map(|rel| {
        let method_ident = syn::Ident::new(&format!("{}_m2m", rel.name), struct_name.span());
        let through = rel.through.as_str();
        let pk_col = rel.pk_column.as_str();
        let ct_col = rel.ct_column.as_str();
        let related_col = rel.related_column.as_str();
        quote! {
            pub fn #method_ident(&self) -> #root::sql::GenericM2MManager {
                #root::sql::GenericM2MManager {
                    src_pk: self.__rustango_pk_value(),
                    src_schema: <Self as #root::core::Model>::SCHEMA,
                    through: #through,
                    pk_col: #pk_col,
                    ct_col: #ct_col,
                    dst_col: #related_col,
                }
            }
        }
    });
    // Lets an owner delete find and clear its junction rows.
    let entries = relations.iter().map(|rel| {
        let through = rel.through.as_str();
        let pk_col = rel.pk_column.as_str();
        let ct_col = rel.ct_column.as_str();
        quote! {
            #root::core::inventory::submit! {
                #root::core::GenericM2MEntry::new(
                    <#struct_name as #root::core::Model>::SCHEMA,
                    #through,
                    #pk_col,
                    #ct_col,
                )
            }
        }
    });
    quote! {
        impl #struct_name {
            #( #methods )*
        }
        #( #entries )*
    }
}

/// Emit `<name>_exists_expr()` + `<name>_not_exists_expr()`
/// associated functions for each `#[rustango(reverse_has(...))]`
/// attribute. Issue #830.
///
/// The two emitted functions return ready-to-use `WhereExpr` nodes
/// that downstream callers drop into
/// `QuerySet::<Self>::where_raw(...)`:
///
/// - `<name>_exists_expr()` → `EXISTS (SELECT 1 FROM <child> WHERE
///   <child_fk_column> = OuterRef("<self_pk_column>"))`. Eloquent
///   `whereHas` parity (without the closure-style sub-predicate
///   refinement — that's a follow-up; users can layer additional
///   predicates by constructing the SelectQuery themselves and
///   calling `where_raw(exists(query))` from `crate::core::subquery`).
/// - `<name>_not_exists_expr()` → same but `NOT EXISTS`. Eloquent
///   `whereDoesntHave` parity.
///
/// Tri-dialect: `EXISTS` / `NOT EXISTS` over a correlated subquery
/// is portable across PG / MySQL / SQLite. The writer's scope-stack
/// machinery threads the outer-table reference through automatically
/// (`OuterRef(col)` resolves to `<outer>.<col>` at emit time).
fn reverse_has_accessor_tokens(
    struct_name: &syn::Ident,
    reverse_has_relations: &[ReverseHasAttr],
) -> TokenStream2 {
    let root = rustango_root();
    if reverse_has_relations.is_empty() {
        return TokenStream2::new();
    }
    let methods = reverse_has_relations.iter().map(|rel| {
        let exists_name = format!("{}_exists_expr", rel.name);
        let not_exists_name = format!("{}_not_exists_expr", rel.name);
        let count_name = format!("{}_count", rel.name);
        let fetch_name = format!("{}_fetch", rel.name);
        let first_name = format!("{}_first", rel.name);
        let pluck_name = format!("{}_pluck", rel.name);
        let accessor_name = rel.name.as_str();
        let exists_ident = syn::Ident::new(&exists_name, struct_name.span());
        let not_exists_ident = syn::Ident::new(&not_exists_name, struct_name.span());
        let count_ident = syn::Ident::new(&count_name, struct_name.span());
        let fetch_ident = syn::Ident::new(&fetch_name, struct_name.span());
        let first_ident = syn::Ident::new(&first_name, struct_name.span());
        let pluck_ident = syn::Ident::new(&pluck_name, struct_name.span());
        let accessor_ident = syn::Ident::new(accessor_name, struct_name.span());
        let child = &rel.child;
        let child_fk_column = rel.child_fk_column.as_str();
        let self_pk_column = rel.self_pk_column.as_str();
        let exists_doc = format!(
            "Eloquent `whereHas` analog — yields `EXISTS (SELECT 1 \
             FROM <{child}> WHERE {child_fk_column} = <outer>.{self_pk_column})`. \
             Drop into `QuerySet::<{struct_name}>::where_raw(...)` to \
             filter to {struct_name}s with at least one matching child.",
        );
        let not_exists_doc = format!(
            "Eloquent `whereDoesntHave` analog — yields `NOT EXISTS \
             (SELECT 1 FROM <{child}> WHERE {child_fk_column} = \
             <outer>.{self_pk_column})`. Drop into \
             `QuerySet::<{struct_name}>::where_raw(...)` to filter to \
             {struct_name}s with **no** matching child.",
        );
        let count_doc = format!(
            "Eloquent `$model->{name}->count()` analog — returns \
             the number of `{child}` rows whose `{child_fk_column}` \
             matches this `{struct_name}` instance's primary key. \
             Issued as `SELECT COUNT(*) FROM <{child}> WHERE \
             {child_fk_column} = <self.pk>`.",
            name = rel.name,
        );
        let accessor_doc = format!(
            "Eloquent `$model->{name}` accessor — returns a \
             `QuerySet<{child}>` filtered to rows whose \
             `{child_fk_column}` matches this `{struct_name}` \
             instance's primary key. **Chainable**: compose `.filter()` \
             / `.order_by()` / `.limit()` etc. on top, then call \
             `.fetch(&pool)` (the QuerySet trait method) when \
             done. For the simple \"fetch all\" hot path with no \
             further composition, prefer the bare-name \
             `{name}_fetch(&pool)` companion.",
            name = rel.name,
        );
        let fetch_doc = format!(
            "Eloquent `$model->{name}->get()` — bare-name hot-path \
             over `{name}(&self).fetch(&pool)`. Use this when \
             you don't need further `.filter()` / `.order_by()` \
             composition; falls back to the chainable accessor when \
             you do. Avoids the `_pool` suffix on the most common \
             call-site shape.",
            name = rel.name,
        );
        quote! {
            #[doc = #accessor_doc]
            pub fn #accessor_ident(&self) -> #root::query::QuerySet<#child> {
                #root::query::QuerySet::<#child>::new()
                    .filter(#child_fk_column, self.__rustango_pk_value())
            }

            #[doc = #fetch_doc]
            pub async fn #fetch_ident(
                &self,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<#child>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                self.#accessor_ident().fetch(pool).await
            }

            /// Eloquent `$model->relation->first()` / `hasOne`
            /// semantics — bare-name shortcut over
            /// `self.<name>().first(&pool)`. Returns `None` when no
            /// child rows match. Useful when the relation is
            /// nominally many-to-one in shape but at most one row is
            /// expected (latest comment, primary tag, etc.).
            pub async fn #first_ident(
                &self,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::core::option::Option<#child>,
                #root::sql::ExecError,
            > {
                self.#accessor_ident().first(pool).await
            }

            /// Eloquent `$model->relation->pluck($col)` — project a
            /// single column from the child rows into a `Vec<U>`.
            /// Skips the typed `Child` decode, which is cheaper when
            /// you only need one column (e.g. `post.comments_pluck::<String>("body", &pool)`).
            pub async fn #pluck_ident<U>(
                &self,
                col: &'static str,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<U>,
                #root::sql::ExecError,
            >
            where
                U: #root::sql::FlatScalar,
            {
                self.#accessor_ident()
                    .values_list_flat(col)
                    .fetch::<U>(pool)
                    .await
            }

            #[doc = #exists_doc]
            pub fn #exists_ident() -> #root::core::WhereExpr {
                use #root::core::{Expr, Model as _, Op, SelectQuery, WhereExpr};
                let child_schema =
                    <#child as #root::core::Model>::SCHEMA;
                let inner = SelectQuery::new(child_schema).where_clause(WhereExpr::ExprCompare {
                    lhs: Expr::Column(#child_fk_column),
                    op: Op::Eq,
                    rhs: Expr::OuterRef(#self_pk_column),
                });
                WhereExpr::Exists(::std::boxed::Box::new(inner))
            }

            #[doc = #not_exists_doc]
            pub fn #not_exists_ident() -> #root::core::WhereExpr {
                use #root::core::{Expr, Model as _, Op, SelectQuery, WhereExpr};
                let child_schema =
                    <#child as #root::core::Model>::SCHEMA;
                let inner = SelectQuery::new(child_schema).where_clause(WhereExpr::ExprCompare {
                    lhs: Expr::Column(#child_fk_column),
                    op: Op::Eq,
                    rhs: Expr::OuterRef(#self_pk_column),
                });
                WhereExpr::NotExists(::std::boxed::Box::new(inner))
            }

            #[doc = #count_doc]
            pub async fn #count_ident(
                &self,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                i64,
                #root::sql::ExecError,
            > {
                use #root::sql::CounterPool as _;
                #root::query::QuerySet::<#child>::new()
                    .filter(#child_fk_column, self.__rustango_pk_value())
                    .count(pool)
                    .await
            }
        }
    });
    quote! {
        impl #struct_name {
            #( #methods )*
        }
    }
}

/// Emit `<name>_through(&self) -> QuerySet<Far>` accessors for each
/// `#[rustango(through(...))]` attribute. Issue #817.
///
/// Each accessor builds a correlated subquery via
/// `WhereExpr::InSubquery`: the inner `SelectQuery` reads from the
/// intermediate table, filters on the FK column pointing at this
/// model, and projects the intermediate PK. The outer queryset
/// filters the far model by its FK-to-intermediate column being in
/// that set.
///
/// The returned `QuerySet<Far>` is **chainable** — the subquery
/// lives inside a `where_raw` clause so the user's later
/// `.filter()` / `.order_by()` / `.limit()` compositions don't
/// disturb it.
///
/// Tri-dialect: `IN (subquery)` is portable across PG / MySQL /
/// SQLite — no LATERAL or backend-specific syntax involved.
fn through_accessor_tokens(
    struct_name: &syn::Ident,
    through_relations: &[ThroughAttr],
) -> TokenStream2 {
    let root = rustango_root();
    if through_relations.is_empty() {
        return TokenStream2::new();
    }
    let methods = through_relations.iter().map(|rel| {
        let method_name = format!("{}_through", rel.name);
        let count_name = format!("{}_through_count", rel.name);
        let fetch_name = format!("{}_through_fetch", rel.name);
        let first_name = format!("{}_through_first", rel.name);
        let pluck_name = format!("{}_through_pluck", rel.name);
        let method_ident = syn::Ident::new(&method_name, struct_name.span());
        let count_ident = syn::Ident::new(&count_name, struct_name.span());
        let fetch_ident = syn::Ident::new(&fetch_name, struct_name.span());
        let first_ident = syn::Ident::new(&first_name, struct_name.span());
        let pluck_ident = syn::Ident::new(&pluck_name, struct_name.span());
        let far = &rel.far;
        let intermediate = &rel.intermediate;
        let far_fk_column = rel.far_fk_column.as_str();
        let intermediate_fk_column = rel.intermediate_fk_column.as_str();
        let intermediate_pk_column = rel.intermediate_pk_column.as_str();
        let doc = format!(
            "Eloquent `hasManyThrough` accessor — returns a \
             `QuerySet<{far}>` whose rows reach this `{struct_name}` \
             instance through the intermediate `{intermediate}` table. \
             Generated SQL shape: \
             `… WHERE {far_fk_column} IN (SELECT \
             {intermediate_pk_column} FROM <{intermediate}> WHERE \
             {intermediate_fk_column} = self.pk)`. Chainable like any \
             other QuerySet — compose `.filter()` / `.order_by()` / \
             `.limit()` etc. on top.",
        );
        let count_doc = format!(
            "Eloquent `$model->{name}->count()` analog for the \
             through-relation — returns the number of `{far}` rows \
             reachable through `{intermediate}`. Equivalent to \
             `self.{name}_through().count(pool)` but spelled \
             as a bare instance method for parity with the \
             `reverse_has` `<name>_count` shape.",
            name = rel.name,
        );
        quote! {
            #[doc = #doc]
            pub fn #method_ident(&self) -> #root::query::QuerySet<#far> {
                use #root::core::{Filter, Model as _, Op, SelectQuery, WhereExpr};
                let intermediate_schema =
                    <#intermediate as #root::core::Model>::SCHEMA;
                let sub = SelectQuery::new(intermediate_schema)
                    .where_clause(WhereExpr::Predicate(Filter::new(
                        #intermediate_fk_column,
                        Op::Eq,
                        self.__rustango_pk_value(),
                    )))
                    .projection(::std::vec![#intermediate_pk_column]);
                #root::query::QuerySet::<#far>::new().where_raw(
                    WhereExpr::InSubquery {
                        column: #far_fk_column,
                        negated: false,
                        subquery: ::std::boxed::Box::new(sub),
                    },
                )
            }

            #[doc = #count_doc]
            pub async fn #count_ident(
                &self,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                i64,
                #root::sql::ExecError,
            > {
                use #root::sql::CounterPool as _;
                self.#method_ident().count(pool).await
            }

            /// Eloquent `$model->relation->get()` for the
            /// through-relation — bare-name hot-path over
            /// `self.<name>_through().fetch(&pool)`. Use this
            /// when you don't need further `.filter()` /
            /// `.order_by()` composition; falls back to the
            /// chainable accessor when you do. Avoids the `_pool`
            /// suffix on the most common call-site shape.
            pub async fn #fetch_ident(
                &self,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<#far>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                self.#method_ident().fetch(pool).await
            }

            /// Eloquent `hasOneThrough` analog — bare-name shortcut
            /// over `self.<name>_through().first(&pool)`. Returns
            /// `None` when no far rows are reachable through the
            /// intermediate. Useful when at most one row is
            /// expected (latest comment by country, primary tag,
            /// etc.).
            pub async fn #first_ident(
                &self,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::core::option::Option<#far>,
                #root::sql::ExecError,
            > {
                self.#method_ident().first(pool).await
            }

            /// Pluck a single column from the far rows into `Vec<U>`
            /// — cheaper than the typed `<Far>` decode when only one
            /// scalar column is needed.
            pub async fn #pluck_ident<U>(
                &self,
                col: &'static str,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<U>,
                #root::sql::ExecError,
            >
            where
                U: #root::sql::FlatScalar,
            {
                self.#method_ident()
                    .values_list_flat(col)
                    .fetch::<U>(pool)
                    .await
            }
        }
    });
    quote! {
        impl #struct_name {
            #( #methods )*
        }
    }
}

struct ColumnEntry {
    /// The struct field ident, used both for the inherent const name on
    /// the model and for the inner column type's name.
    ident: syn::Ident,
    /// The struct's field type, used as `Column::Value`.
    value_ty: Type,
    /// Rust-side field name (e.g. `"id"`).
    name: String,
    /// SQL-side column name (e.g. `"user_id"`).
    column: String,
    /// `#root::core::FieldType::I64` etc.
    field_type_tokens: TokenStream2,
    /// A bare or optional `Uuid` field; MySQL decodes it from text.
    uuid_column: bool,
}

struct CollectedFields {
    field_schemas: Vec<TokenStream2>,
    from_row_inits: Vec<TokenStream2>,
    /// Aliased counterparts of `from_row_inits` — read columns via
    /// `format!("{prefix}__{col}")` aliases so a Model can be
    /// decoded from a JOINed row's projected target columns.
    from_aliased_row_inits: Vec<TokenStream2>,
    /// MySQL twins of `from_row_inits` / `from_aliased_row_inits`.
    from_row_inits_my: Vec<TokenStream2>,
    from_aliased_row_inits_my: Vec<TokenStream2>,
    /// Static column-name list — used by the simple insert path
    /// (no `Auto<T>` fields). Aligned with `insert_values`.
    insert_columns: Vec<TokenStream2>,
    /// Static `Into<SqlValue>` expressions, one per field. Aligned
    /// with `insert_columns`. Used by the simple insert path only.
    insert_values: Vec<TokenStream2>,
    /// Per-field push expressions for the dynamic (Auto-aware)
    /// insert path. Each statement either unconditionally pushes
    /// `(column, value)` or, for an `Auto<T>` field, conditionally
    /// pushes only when `Auto::Set(_)`. Built only when `has_auto`.
    insert_pushes: Vec<TokenStream2>,
    /// SQL columns for `RETURNING` — one per `Auto<T>` field. Empty
    /// when `has_auto == false`.
    returning_cols: Vec<TokenStream2>,
    /// `self.<field> = Row::try_get(&row, "<col>")?;` for each Auto
    /// field. Run after `insert_returning` to populate the model.
    auto_assigns: Vec<TokenStream2>,
    /// `(ident, column_literal, is_uuid)` for every Auto field. Used by
    /// the bulk_insert codegen to rebuild assigns against `_row_mut`
    /// instead of `self`.
    auto_field_idents: Vec<(syn::Ident, String, bool)>,
    /// #1028 — `(ident, column)` for each `generated_as` field. Drives
    /// the PG/SQLite RETURNING refresh that decodes the DB-computed value
    /// back into the struct after insert (MySQL has no RETURNING → the
    /// field stays at its placeholder until the next read).
    generated_field_idents: Vec<(syn::Ident, String)>,
    /// First `Auto<T>` field the database fills, with its inner `T`: the
    /// MySQL `LAST_INSERT_ID()` target. Rust-filled ones never are (#1934).
    first_db_auto: Option<(syn::Ident, Type)>,
    /// Bulk-insert per-row pushes for **non-Auto fields only**. Used
    /// by the all-Auto-Unset bulk path (Auto cols dropped from
    /// `columns`).
    bulk_pushes_no_auto: Vec<TokenStream2>,
    /// Bulk-insert per-row pushes for **all fields including Auto**.
    /// Used by the all-Auto-Set bulk path (Auto col included with the
    /// caller-supplied value).
    bulk_pushes_all: Vec<TokenStream2>,
    /// Column-name literals for non-Auto fields only (paired with
    /// `bulk_pushes_no_auto`).
    bulk_columns_no_auto: Vec<TokenStream2>,
    /// Column-name literals for every field including Auto (paired
    /// with `bulk_pushes_all`).
    bulk_columns_all: Vec<TokenStream2>,
    /// Fills each `default_uuid_v7` field of `_row` in place, so a
    /// mutable bulk insert hands the PKs back (#1934).
    bulk_fill_in_place: Vec<TokenStream2>,
    /// Rust-filled `Auto` fields (`default_uuid_v7`, `auto_now(_add)`), reset when `insert_or_ignore` skips (#1937).
    rust_filled_idents: Vec<syn::Ident>,
    /// `auto_now` fields: `upsert` stamps them before binding.
    auto_now_idents: Vec<syn::Ident>,
    /// `default_uuid_v7` fields: an `Unset` one gets a fresh id, so the
    /// upsert marks it `generated` for the MySQL key guard.
    uuid_v7_fields: Vec<(syn::Ident, String)>,
    /// `let _i_unset_<n> = matches!(rows[0].<auto_field>, Auto::Unset);`
    /// + the loop that asserts every row matches. One pair per Auto
    /// field. Empty when `has_auto == false`.
    bulk_auto_uniformity: Vec<TokenStream2>,
    /// Identifier of the first Auto field, used as the witness for
    /// "all rows agree on Set vs Unset". Set only when `has_auto`.
    first_auto_ident: Option<syn::Ident>,
    /// `true` if any field on the struct is `Auto<T>`.
    has_auto: bool,
    /// `true` when the primary-key field's Rust type is `Auto<T>`.
    /// Gates `save()` codegen — only Auto PKs let us infer
    /// insert-vs-update from the in-memory value.
    pk_is_auto: bool,
    /// `Assignment` constructors for every non-PK column. Drives the
    /// UPDATE branch of `save()`.
    update_assignments: Vec<TokenStream2>,
    /// Column name literals (`"col"`) for every non-PK, non-auto_now_add column.
    /// Drives the `ON CONFLICT ... DO UPDATE SET` clause in `upsert_on`.
    upsert_update_columns: Vec<TokenStream2>,
    primary_key: Option<(syn::Ident, String)>,
    column_entries: Vec<ColumnEntry>,
    /// Rust-side field names, in declaration order. Used to validate
    /// container attributes like `display = "…"`.
    field_names: Vec<String>,
    /// FK fields on this child model. Drives the reverse-relation
    /// helper emit — for each FK, the macro adds an inherent
    /// `<parent>::<child_table>_set(&self, executor) -> Vec<Self>`
    /// method on the parent type.
    fk_relations: Vec<FkRelation>,
    /// SQL column name of the `#[rustango(soft_delete)]` field, if
    /// the model has one. Drives emission of the `soft_delete_on` /
    /// `restore_on` inherent methods. At most one such column per
    /// model is allowed; collect_fields rejects duplicates.
    soft_delete_column: Option<String>,
    /// Rust field ident of the `#[rustango(soft_delete)]` field —
    /// companion to `soft_delete_column` for emitting predicates
    /// that need to read the field off `&self` (e.g. `trashed()`).
    soft_delete_field_ident: Option<syn::Ident>,
}

#[derive(Clone)]
struct FkRelation {
    /// Inner type of `ForeignKey<T, K>` — the parent model. The reverse
    /// helper is emitted as `impl <ParentType> { … }`.
    parent_type: Type,
    /// Rust field ident of the FK. Its name is the key for select_related,
    /// prefetch and filters; the SQL column may differ (#1936).
    field_ident: syn::Ident,
    /// `K`'s underlying scalar kind — drives the `match SqlValue { … }`
    /// arm emitted by [`load_related_impl_tokens`]. `I64` for the
    /// default `ForeignKey<T>` (no explicit K); other kinds when the
    /// user wrote `ForeignKey<T, String>`, `ForeignKey<T, Uuid>`, etc.
    pk_kind: DetectedKind,
    /// `true` when the field is `Option<ForeignKey<T, K>>` (nullable
    /// FK column). Drives the `Some(...)` wrapping in load_related
    /// assignment and `.as_ref().map(...)` in the FK PK accessor so
    /// the codegen matches the field's declared shape.
    nullable: bool,
    /// `#[rustango(related_name = "...")]` per-FK reverse-accessor
    /// override. When set, the reverse helper picks this name instead
    /// of `default_related_name` / `<child_snake>_set`. Follow-up to
    /// #816 (issue's "Related" note re: per-FK override).
    related_name: Option<String>,
}

fn collect_fields(named: &syn::FieldsNamed, table: &str) -> syn::Result<CollectedFields> {
    let root = rustango_root();
    let cap = named.named.len();
    let mut out = CollectedFields {
        field_schemas: Vec::with_capacity(cap),
        from_row_inits: Vec::with_capacity(cap),
        from_aliased_row_inits: Vec::with_capacity(cap),
        from_row_inits_my: Vec::with_capacity(cap),
        from_aliased_row_inits_my: Vec::with_capacity(cap),
        insert_columns: Vec::with_capacity(cap),
        insert_values: Vec::with_capacity(cap),
        insert_pushes: Vec::with_capacity(cap),
        returning_cols: Vec::new(),
        auto_assigns: Vec::new(),
        auto_field_idents: Vec::new(),
        generated_field_idents: Vec::new(),
        first_db_auto: None,
        bulk_pushes_no_auto: Vec::with_capacity(cap),
        bulk_pushes_all: Vec::with_capacity(cap),
        bulk_columns_no_auto: Vec::with_capacity(cap),
        bulk_columns_all: Vec::with_capacity(cap),
        bulk_fill_in_place: Vec::new(),
        rust_filled_idents: Vec::new(),
        auto_now_idents: Vec::new(),
        uuid_v7_fields: Vec::new(),
        bulk_auto_uniformity: Vec::new(),
        first_auto_ident: None,
        has_auto: false,
        pk_is_auto: false,
        update_assignments: Vec::with_capacity(cap),
        upsert_update_columns: Vec::with_capacity(cap),
        primary_key: None,
        column_entries: Vec::with_capacity(cap),
        field_names: Vec::with_capacity(cap),
        fk_relations: Vec::new(),
        soft_delete_column: None,
        soft_delete_field_ident: None,
    };

    for field in &named.named {
        let info = process_field(field, table)?;
        out.field_names.push(ident_name(info.ident));
        out.field_schemas.push(info.schema);
        out.from_row_inits.push(info.from_row_init);
        out.from_aliased_row_inits.push(info.from_aliased_row_init);
        out.from_row_inits_my.push(info.from_row_init_my);
        out.from_aliased_row_inits_my
            .push(info.from_aliased_row_init_my);
        if let Some(parent_ty) = info.fk_inner.clone() {
            out.fk_relations.push(FkRelation {
                parent_type: parent_ty,
                field_ident: info.ident.clone(),
                pk_kind: info.fk_pk_kind,
                nullable: info.nullable,
                related_name: info.related_name.clone(),
            });
        }
        if info.soft_delete {
            if out.soft_delete_column.is_some() {
                return Err(syn::Error::new_spanned(
                    field,
                    "only one field may be marked `#[rustango(soft_delete)]`",
                ));
            }
            out.soft_delete_column = Some(info.column.clone());
            out.soft_delete_field_ident = Some(info.ident.clone());
        }
        let column = info.column.as_str();
        let ident = info.ident;
        // Generated columns (`#[rustango(generated_as = "EXPR")]`)
        // skip every write path — Postgres recomputes the value
        // from EXPR. Push only the column-entry record (so typed
        // column constants still exist for filtering / projection)
        // and the schema literal (already pushed above) and move
        // on. No insert_columns/values, no insert_pushes, no
        // bulk_*, no update_assignments, no upsert_update_columns,
        // no returning_cols.
        if info.generated_as.is_some() {
            out.column_entries.push(ColumnEntry {
                ident: ident.clone(),
                value_ty: info.value_ty.clone(),
                name: ident_name(ident),
                column: info.column.clone(),
                field_type_tokens: info.field_type_tokens,
                uuid_column: info.uuid_column,
            });
            // #1028 — refresh the DB-computed value after insert on
            // RETURNING-capable backends. The column joins `returning_cols`
            // (so PG/SQLite `INSERT … RETURNING` includes it) and the
            // ident is recorded so the `AssignAutoPkPool` impl decodes it
            // back into the struct. MySQL has no `INSERT … RETURNING`, so
            // it keeps the placeholder until the next read.
            out.returning_cols.push(quote!(#column));
            out.generated_field_idents
                .push((ident.clone(), info.column.clone()));
            continue;
        }
        out.insert_columns.push(quote!(#column));
        out.insert_values.push(quote! {
            ::core::convert::Into::<#root::core::SqlValue>::into(
                ::core::clone::Clone::clone(&self.#ident)
            )
        });
        if info.auto {
            out.has_auto = true;
            if out.first_auto_ident.is_none() {
                out.first_auto_ident = Some(ident.clone());
            }
            // `default_uuid_v7` (issue #823) generates the PK Rust-side
            // before binding, so the value is already in
            // `self.#ident` after the insert_push — RETURNING is
            // redundant. Skip adding this column to returning_cols /
            // auto_assigns / auto_field_idents to avoid (a) an
            // unnecessary RETURNING column on every dialect, and (b)
            // the MySQL `LAST_INSERT_ID()` path that can only fill an
            // integer PK.
            // `auto_now_add` / `auto_now` join `default_uuid_v7` here
            // for the same reason: they are filled Rust-side below and
            // bound, so the value is already in `self` and RETURNING
            // would be a redundant column on every dialect.
            if !info.default_uuid_v7 && !info.auto_now_add && !info.auto_now {
                if out.first_db_auto.is_none() {
                    out.first_db_auto = auto_inner_type(info.value_ty)
                        .cloned()
                        .map(|ty| (ident.clone(), ty));
                }
                out.returning_cols.push(quote!(#column));
                out.auto_field_idents.push((
                    ident.clone(),
                    info.column.clone(),
                    info.fk_pk_kind == DetectedKind::Uuid,
                ));
                out.auto_assigns.push(quote! {
                    self.#ident = #root::sql::try_get_returning(_returning_row, #column)?;
                });
            }
            if info.default_uuid_v7 {
                // Rust-side UUIDv7 generation (issue #823, Eloquent
                // `HasUuids`). Auto::Unset → fill with `Uuid::now_v7()`
                // and bind; Auto::Set → bind the user's value. The
                // column is ALWAYS present in the INSERT statement —
                // no RETURNING / no DB DEFAULT needed.
                out.insert_pushes.push(quote! {
                    if matches!(&self.#ident, #root::sql::Auto::Unset) {
                        self.#ident = #root::sql::Auto::Set(
                            #root::__uuid::Uuid::now_v7(),
                        );
                    }
                    if let #root::sql::Auto::Set(_v) = &self.#ident {
                        _columns.push(#column);
                        _values.push(::core::convert::Into::<#root::core::SqlValue>::into(
                            ::core::clone::Clone::clone(_v)
                        ));
                    }
                });
            } else if info.auto_now_add || info.auto_now {
                // Rust-side write timestamp (#1464), mirroring
                // `default_uuid_v7` above. `auto_now` has always bound
                // `Utc::now()` on UPDATE but not on INSERT, so the
                // first write of an `updated_at` took the DB default
                // while every later one took the clock — the same
                // column, filled two different ways.
                //
                // The default is the problem. `CREATE TABLE IF NOT
                // EXISTS` leaves an upgraded table's
                // `DEFAULT CURRENT_TIMESTAMP` in place, and SQLite's
                // ALTER TABLE grammar (RENAME/ADD/DROP) has no
                // statement that changes it — so every insert relying
                // on that default wrote the legacy shape forever, while
                // the migrate sweep converted the rows around it. The
                // column went permanently mixed and `ORDER BY` inverted
                // the admin audit log (#1616 rework review,
                // correctness-001 / dialects-005 / security-002).
                //
                // Binding it here makes the stale default unreachable
                // rather than trying to migrate it: the timestamp comes
                // from the application, not the database.
                out.insert_pushes.push(quote! {
                    if matches!(&self.#ident, #root::sql::Auto::Unset) {
                        self.#ident = #root::sql::Auto::Set(
                            #root::__chrono::Utc::now(),
                        );
                    }
                    if let #root::sql::Auto::Set(_v) = &self.#ident {
                        _columns.push(#column);
                        _values.push(::core::convert::Into::<#root::core::SqlValue>::into(
                            ::core::clone::Clone::clone(_v)
                        ));
                    }
                });
            } else {
                out.insert_pushes.push(quote! {
                    if let #root::sql::Auto::Set(_v) = &self.#ident {
                        _columns.push(#column);
                        _values.push(::core::convert::Into::<#root::core::SqlValue>::into(
                            ::core::clone::Clone::clone(_v)
                        ));
                    }
                });
            }
            // …except the timestamp columns, which must appear in BOTH
            // paths (#1464). The path is chosen by the *first* Auto
            // field — in practice the PK — so a bulk insert of rows
            // with an unset PK took the no-auto branch and dropped the
            // timestamp column, falling back to the DB default that
            // this change exists to stop depending on.
            //
            // `rows` is borrowed immutably here, so this fills per row
            // at push time rather than writing back into the struct. An
            // explicitly-Set value is still honoured; only `Unset`
            // takes the clock.
            // `default_uuid_v7` likewise: its column has no DB default (#1934).
            if info.default_uuid_v7 || info.auto_now_add || info.auto_now {
                out.rust_filled_idents.push(ident.clone());
            }
            if info.auto_now {
                out.auto_now_idents.push(ident.clone());
            }
            if info.default_uuid_v7 {
                out.uuid_v7_fields
                    .push((ident.clone(), info.column.clone()));
            }
            let rust_fill = if info.default_uuid_v7 {
                Some(quote!(#root::__uuid::Uuid::now_v7()))
            } else if info.auto_now_add || info.auto_now {
                Some(quote!(#root::__chrono::Utc::now()))
            } else {
                None
            };
            // Bulk: Auto fields appear in the all-Set path. An unset filled
            // field takes its fill there too, not NULL (#1950).
            out.bulk_columns_all.push(quote!(#column));
            if let Some(fill) = &rust_fill {
                let push = quote! {
                    _row_vals.push(::core::convert::Into::<#root::core::SqlValue>::into(
                        match &_row.#ident {
                            #root::sql::Auto::Set(_v) => ::core::clone::Clone::clone(_v),
                            #root::sql::Auto::Unset => #fill,
                        }
                    ));
                };
                out.bulk_columns_no_auto.push(quote!(#column));
                out.bulk_pushes_no_auto.push(push.clone());
                out.bulk_pushes_all.push(push);
            } else {
                out.bulk_pushes_all.push(quote! {
                    _row_vals.push(::core::convert::Into::<#root::core::SqlValue>::into(
                        ::core::clone::Clone::clone(&_row.#ident)
                    ));
                });
            }
            if info.default_uuid_v7 {
                out.bulk_fill_in_place.push(quote! {
                    if matches!(&_row.#ident, #root::sql::Auto::Unset) {
                        _row.#ident = #root::sql::Auto::Set(#root::__uuid::Uuid::now_v7());
                    }
                });
            }
            // Uniformity check: every row's Auto state must match the
            // first row's. Mixed Set/Unset within one bulk_insert is
            // rejected here so the column list stays consistent.
            // A filled field may be unset on any row, so it is exempt.
            let ident_clone = ident.clone();
            if rust_fill.is_none() {
                out.bulk_auto_uniformity.push(quote! {
                    for _r in rows.iter().skip(1) {
                        if matches!(_r.#ident_clone, #root::sql::Auto::Unset) != _first_unset {
                            return ::core::result::Result::Err(
                                #root::sql::ExecError::Sql(
                                    #root::sql::SqlError::BulkAutoMixed
                                )
                            );
                        }
                    }
                });
            }
        } else {
            out.insert_pushes.push(quote! {
                _columns.push(#column);
                _values.push(::core::convert::Into::<#root::core::SqlValue>::into(
                    ::core::clone::Clone::clone(&self.#ident)
                ));
            });
            // Bulk: non-Auto fields appear in BOTH paths.
            out.bulk_columns_no_auto.push(quote!(#column));
            out.bulk_columns_all.push(quote!(#column));
            let push_expr = quote! {
                _row_vals.push(::core::convert::Into::<#root::core::SqlValue>::into(
                    ::core::clone::Clone::clone(&_row.#ident)
                ));
            };
            out.bulk_pushes_no_auto.push(push_expr.clone());
            out.bulk_pushes_all.push(push_expr);
        }
        if info.primary_key {
            if out.primary_key.is_some() {
                return Err(syn::Error::new_spanned(
                    field,
                    "only one field may be marked `#[rustango(primary_key)]`",
                ));
            }
            out.primary_key = Some((ident.clone(), info.column.clone()));
            if info.auto {
                out.pk_is_auto = true;
            }
        } else if info.auto_now_add {
            // Immutable post-insert: skip from UPDATE entirely.
        } else if info.auto_now {
            // `auto_now` columns: bind `chrono::Utc::now()` on every
            // UPDATE, and write it back so `self` matches the row.
            out.update_assignments.push(quote! {
                #root::core::Assignment::new(
                    #column,
                    {
                        let _now = #root::__chrono::Utc::now();
                        self.#ident = #root::sql::Auto::Set(_now);
                        ::core::convert::Into::<#root::core::SqlValue>::into(_now)
                    },
                )
            });
            out.upsert_update_columns.push(quote!(#column));
        } else {
            out.update_assignments.push(quote! {
                #root::core::Assignment::new(
                    #column,
                    ::core::convert::Into::<#root::core::SqlValue>::into(
                        ::core::clone::Clone::clone(&self.#ident)
                    ),
                )
            });
            out.upsert_update_columns.push(quote!(#column));
        }
        out.column_entries.push(ColumnEntry {
            ident: ident.clone(),
            value_ty: info.value_ty.clone(),
            name: ident_name(ident),
            column: info.column.clone(),
            field_type_tokens: info.field_type_tokens,
            uuid_column: info.uuid_column,
        });
    }
    Ok(out)
}

/// A derived index name within PG's 63 bytes (MySQL takes 64); a longer one
/// keeps a prefix plus a hash of the whole, so two long names stay distinct.
fn capped_index_name(name: String) -> String {
    const MAX: usize = 63;
    if name.len() <= MAX {
        return name;
    }
    // FNV-1a: stable across builds, unlike `DefaultHasher`.
    let hash = name.bytes().fold(0x811c_9dc5_u32, |h, b| {
        (h ^ u32::from(b)).wrapping_mul(0x0100_0193)
    });
    let mut cut = MAX - 9;
    while !name.is_char_boundary(cut) {
        cut -= 1;
    }
    format!("{}_{hash:08x}", &name[..cut])
}

fn model_impl_tokens(
    struct_name: &syn::Ident,
    model_name: &str,
    table: &str,
    display: Option<&str>,
    app_label: Option<&str>,
    admin: Option<&AdminAttrs>,
    default_order: &[(String, bool, proc_macro2::Span)],
    field_schemas: &[TokenStream2],
    soft_delete_column: Option<&str>,
    permissions: bool,
    audit_track: Option<&[String]>,
    m2m_relations: &[M2MAttr],
    indexes: &[IndexAttr],
    checks: &[CheckAttr],
    excludes: &[ExcludeAttr],
    composite_fks: &[CompositeFkAttr],
    generic_fks: &[GenericFkAttr],
    scope: Option<&str>,
    is_view: bool,
    verbose_name: Option<&str>,
    verbose_name_plural: Option<&str>,
    managed: bool,
    base_manager_name: Option<&str>,
    order_with_respect_to: Option<&str>,
    proxy: bool,
    required_db_features: &[String],
    required_db_vendor: Option<&str>,
    default_related_name: Option<&str>,
    db_table_comment: Option<&str>,
    get_latest_by: Option<(&str, bool)>,
    extra_permissions: &[(String, String)],
    default_permissions: &[String],
    global_scopes: &[GlobalScopeAttr],
    reverse_has_relations: &[ReverseHasAttr],
    generic_has_relations: &[GenericHasAttr],
) -> TokenStream2 {
    let root = rustango_root();
    let display_tokens = if let Some(name) = display {
        quote!(::core::option::Option::Some(#name))
    } else {
        quote!(::core::option::Option::None)
    };
    let app_label_tokens = if let Some(name) = app_label {
        quote!(::core::option::Option::Some(#name))
    } else {
        quote!(::core::option::Option::None)
    };
    let soft_delete_tokens = if let Some(col) = soft_delete_column {
        quote!(::core::option::Option::Some(#col))
    } else {
        quote!(::core::option::Option::None)
    };
    let audit_track_tokens = match audit_track {
        None => quote!(::core::option::Option::None),
        Some(names) => {
            let lits = names.iter().map(|n| n.as_str());
            quote!(::core::option::Option::Some(&[ #(#lits),* ]))
        }
    };
    let admin_tokens = admin_config_tokens(admin);
    // Default `tenant` so single-tenant projects (no `scope` attr
    // anywhere) keep the v0.24.x behavior. Container-attr parser
    // already validated the value is "registry" or "tenant".
    let scope_tokens = match scope.map(|s| s.to_ascii_lowercase()).as_deref() {
        Some("registry") => quote!(#root::core::ModelScope::Registry),
        _ => quote!(#root::core::ModelScope::Tenant),
    };
    let verbose_name_tokens = optional_str(verbose_name);
    let verbose_name_plural_tokens = optional_str(verbose_name_plural);
    let base_manager_name_tokens = optional_str(base_manager_name);
    let order_with_respect_to_tokens = optional_str(order_with_respect_to);
    let required_db_features_lits: Vec<&str> =
        required_db_features.iter().map(String::as_str).collect();
    let required_db_vendor_tokens = optional_str(required_db_vendor);
    let default_related_name_tokens = optional_str(default_related_name);
    let db_table_comment_tokens = optional_str(db_table_comment);
    let get_latest_by_tokens = match get_latest_by {
        Some((col, desc)) => {
            quote!(::core::option::Option::Some((#col, #desc)))
        }
        None => quote!(::core::option::Option::None),
    };
    let extra_permission_tokens: Vec<_> = extra_permissions
        .iter()
        .map(|(c, l)| quote!((#c, #l)))
        .collect();
    let default_permission_tokens: Vec<_> = default_permissions
        .iter()
        .map(|action| quote!(#action))
        .collect();
    let indexes_tokens = indexes.iter().map(|idx| {
        // When no explicit `name = "..."` was given, derive a stable,
        // collision-free name from the table + columns
        // (`<table>_<col>_<col>_idx`) instead of a shared literal that
        // would clash the moment a model declares two unnamed indexes.
        let derived_name = idx
            .name
            .clone()
            .unwrap_or_else(|| capped_index_name(format!("{table}_{}_idx", idx.columns.join("_"))));
        let name = derived_name.as_str();
        let cols: Vec<&str> = idx.columns.iter().map(String::as_str).collect();
        let unique = idx.unique;
        // Map the parsed method string onto the IndexMethod enum
        // variant — kept at the codegen layer so the IR doesn't
        // carry the string form.
        let method_variant = match idx.method.as_str() {
            "gin" => quote!(#root::core::IndexMethod::Gin),
            "gist" => quote!(#root::core::IndexMethod::Gist),
            "brin" => quote!(#root::core::IndexMethod::Brin),
            "spgist" => quote!(#root::core::IndexMethod::SpGist),
            "hash" => quote!(#root::core::IndexMethod::Hash),
            "bloom" => quote!(#root::core::IndexMethod::Bloom),
            _ => quote!(#root::core::IndexMethod::BTree),
        };
        let where_clause = match &idx.where_clause {
            Some(s) => quote!(::core::option::Option::Some(#s)),
            None => quote!(::core::option::Option::None),
        };
        let include_lits: Vec<&str> = idx.include.iter().map(String::as_str).collect();
        quote! {{
            let mut i = #root::core::IndexSchema::new(#name, &[ #(#cols),* ]);
            i.unique = #unique;
            i.method = #method_variant;
            i.where_clause = #where_clause;
            i.include = &[ #(#include_lits),* ];
            i
        }}
    });
    let checks_tokens = checks.iter().map(|c| {
        let name = c.name.as_str();
        let expr = c.expr.as_str();
        quote!(#root::core::CheckConstraint::new(#name, #expr))
    });
    let excludes_tokens = excludes.iter().map(|e| {
        let name = e.name.as_str();
        let using = e.using.as_str();
        let element_tokens = e.elements.iter().map(|(col, op)| {
            let col_s = col.as_str();
            let op_s = op.as_str();
            quote!((#col_s, #op_s))
        });
        let where_tokens = match e.where_clause.as_deref() {
            Some(w) => quote!(::core::option::Option::Some(#w)),
            None => quote!(::core::option::Option::None),
        };
        quote! {{
            let mut e = #root::core::ExclusionConstraint::new(
                #name,
                #using,
                &[ #(#element_tokens),* ],
            );
            e.where_clause = #where_tokens;
            e
        }}
    });
    let composite_fk_tokens = composite_fks.iter().map(|rel| {
        let name = rel.name.as_str();
        let to = rel.to.as_str();
        let from_cols: Vec<&str> = rel.from.iter().map(String::as_str).collect();
        let on_cols: Vec<&str> = rel.on.iter().map(String::as_str).collect();
        quote! {
            #root::core::CompositeFkRelation::new(
                #name,
                #to,
                &[ #(#from_cols),* ],
                &[ #(#on_cols),* ],
            )
        }
    });
    let generic_fk_tokens = generic_fks.iter().map(|rel| {
        let name = rel.name.as_str();
        let ct_col = rel.ct_column.as_str();
        let pk_col = rel.pk_column.as_str();
        quote!(#root::core::GenericRelation::new(#name, #ct_col, #pk_col))
    });
    // Issue #291 / T2.5 — `default_order` slice literal. Empty when
    // no `#[rustango(default_order = "...")]` attribute was supplied.
    let default_order_tokens = default_order.iter().map(|(col, desc, _)| {
        let col_lit = col.as_str();
        quote! { (#col_lit, #desc) }
    });

    // Issue #820 — `global_scopes` slice literal. Empty when no
    // `#[rustango(global_scope(...))]` attribute was supplied. The
    // `apply` path is re-emitted verbatim so it resolves in the
    // consumer's scope; the name is stored as a string literal.
    let global_scope_tokens = global_scopes.iter().map(|s| {
        let name = s.name.as_str();
        // The slice sits in a nested `const`, where `Self` does not resolve.
        let mut apply = s.apply.clone();
        if let Some(first) = apply.segments.first_mut() {
            if first.ident == "Self" {
                first.ident = struct_name.clone();
            }
        }
        quote!(#root::core::GlobalScope::new(#name, #apply))
    });

    let m2m_tokens = m2m_relations.iter().map(|rel| {
        let name = rel.name.as_str();
        let to = rel.to.as_str();
        let through = rel.through.as_str();
        let src = rel.src.as_str();
        let dst = rel.dst.as_str();
        let auto_create = rel.auto_create;
        quote! {{
            let mut m = #root::core::M2MRelation::new(#name, #to, #through, #src, #dst);
            m.auto_create = #auto_create;
            m
        }}
    });
    // Issue #830 sub-piece: emit `Model::reverse_relations()` override
    // when the model declares `#[rustango(reverse_has(...))]`. Each
    // entry uses `<Child as Model>::SCHEMA.table` so the literal stays
    // a const expression. Models without reverse_has fall through to
    // the trait's empty default — no override emitted.
    let reverse_relations_override = if reverse_has_relations.is_empty() {
        quote!()
    } else {
        let entries = reverse_has_relations.iter().map(|rel| {
            let name = rel.name.as_str();
            let child = &rel.child;
            let child_fk_column = rel.child_fk_column.as_str();
            let self_pk_column = rel.self_pk_column.as_str();
            quote! {
                #root::core::ReverseRelation::new(
                    #name,
                    <#child as #root::core::Model>::SCHEMA,
                    #child_fk_column,
                    #self_pk_column,
                )
            }
        });
        quote! {
            fn reverse_relations() -> &'static [#root::core::ReverseRelation] {
                const RELS: &[#root::core::ReverseRelation] = &[ #(#entries),* ];
                RELS
            }
        }
    };
    // Issue #830 — `Model::generic_reverse_relations()` override for
    // `#[rustango(generic_has(...))]` (the reverse generic-FK arm).
    let generic_reverse_relations_override = if generic_has_relations.is_empty() {
        quote!()
    } else {
        let entries = generic_has_relations.iter().map(|rel| {
            let name = rel.name.as_str();
            let child = &rel.child;
            let ct_column = rel.ct_column.as_str();
            let pk_column = rel.pk_column.as_str();
            let self_pk_column = rel.self_pk_column.as_str();
            quote! {
                #root::core::GenericReverseRelation::new(
                    #name,
                    <#child as #root::core::Model>::SCHEMA,
                    #ct_column,
                    #pk_column,
                    #self_pk_column,
                )
            }
        });
        quote! {
            fn generic_reverse_relations() -> &'static [#root::core::GenericReverseRelation] {
                const RELS: &[#root::core::GenericReverseRelation] = &[ #(#entries),* ];
                RELS
            }
        }
    };
    let fields_slice = const_slice(
        &quote!(#root::core::FieldSchema),
        field_schemas.iter().cloned(),
    );
    let m2m_slice = const_slice(&quote!(#root::core::M2MRelation), m2m_tokens);
    let indexes_slice = const_slice(&quote!(#root::core::IndexSchema), indexes_tokens);
    let checks_slice = const_slice(&quote!(#root::core::CheckConstraint), checks_tokens);
    let excludes_slice = const_slice(&quote!(#root::core::ExclusionConstraint), excludes_tokens);
    let composite_fk_slice = const_slice(
        &quote!(#root::core::CompositeFkRelation),
        composite_fk_tokens,
    );
    let generic_fk_slice = const_slice(&quote!(#root::core::GenericRelation), generic_fk_tokens);
    let audited_update_override = if audit_track.is_some() {
        quote! {
            fn __rustango_audited_update() -> ::core::option::Option<#root::audit::AuditedUpdate> {
                ::core::option::Option::Some(Self::__rustango_update_audited)
            }
            fn __rustango_audited_delete() -> ::core::option::Option<#root::audit::AuditedDelete> {
                ::core::option::Option::Some(Self::__rustango_delete_audited)
            }
            fn __rustango_audited_create() -> ::core::option::Option<#root::audit::AuditedCreate> {
                ::core::option::Option::Some(Self::__rustango_create_audited)
            }
            fn __rustango_audited_update_record(
            ) -> ::core::option::Option<#root::audit::AuditedUpdateRecord> {
                ::core::option::Option::Some(Self::__rustango_update_record_audited)
            }
        }
    } else {
        quote!()
    };
    let global_scope_slice = const_slice(&quote!(#root::core::GlobalScope), global_scope_tokens);
    quote! {
        impl #root::core::Model for #struct_name {
            const SCHEMA: &'static #root::core::ModelSchema = &{
                #root::core::ModelSchema::from_parts(#root::core::ModelSchemaParts {
                    name: #model_name,
                    table: #table,
                    fields: #fields_slice,
                    display: #display_tokens,
                    app_label: #app_label_tokens,
                    admin: #admin_tokens,
                    soft_delete_column: #soft_delete_tokens,
                    permissions: #permissions,
                    audit_track: #audit_track_tokens,
                    m2m: #m2m_slice,
                    indexes: #indexes_slice,
                    check_constraints: #checks_slice,
                    exclusion_constraints: #excludes_slice,
                    composite_relations: #composite_fk_slice,
                    generic_relations: #generic_fk_slice,
                    scope: #scope_tokens,
                    default_order: &[ #(#default_order_tokens),* ],
                    is_view: #is_view,
                    verbose_name: #verbose_name_tokens,
                    verbose_name_plural: #verbose_name_plural_tokens,
                    managed: #managed,
                    base_manager_name: #base_manager_name_tokens,
                    order_with_respect_to: #order_with_respect_to_tokens,
                    proxy: #proxy,
                    required_db_features: &[ #(#required_db_features_lits),* ],
                    required_db_vendor: #required_db_vendor_tokens,
                    default_related_name: #default_related_name_tokens,
                    db_table_comment: #db_table_comment_tokens,
                    get_latest_by: #get_latest_by_tokens,
                    extra_permissions: &[ #(#extra_permission_tokens),* ],
                    default_permissions: &[ #(#default_permission_tokens),* ],
                    global_scopes: #global_scope_slice,
                })
            };

            #reverse_relations_override
            #generic_reverse_relations_override
            #audited_update_override
        }
    }
}

/// Emit the `admin: Option<&'static AdminConfig>` field for the model
/// schema. `None` when the user wrote no `#[rustango(admin(...))]`;
/// otherwise a static reference to a populated `AdminConfig`.
fn admin_config_tokens(admin: Option<&AdminAttrs>) -> TokenStream2 {
    let root = rustango_root();
    let Some(admin) = admin else {
        return quote!(::core::option::Option::None);
    };

    let list_display = admin
        .list_display
        .as_ref()
        .map(|(v, _)| v.as_slice())
        .unwrap_or(&[]);
    let list_display_lits = list_display.iter().map(|s| s.as_str());

    let search_fields = admin
        .search_fields
        .as_ref()
        .map(|(v, _)| v.as_slice())
        .unwrap_or(&[]);
    let search_fields_lits = search_fields.iter().map(|s| s.as_str());

    let readonly_fields = admin
        .readonly_fields
        .as_ref()
        .map(|(v, _)| v.as_slice())
        .unwrap_or(&[]);
    let readonly_fields_lits = readonly_fields.iter().map(|s| s.as_str());

    let list_filter = admin
        .list_filter
        .as_ref()
        .map(|(v, _)| v.as_slice())
        .unwrap_or(&[]);
    let list_filter_lits = list_filter.iter().map(|s| s.as_str());

    let actions = admin
        .actions
        .as_ref()
        .map(|(v, _)| v.as_slice())
        .unwrap_or(&[]);
    let actions_lits = actions.iter().map(|s| s.as_str());

    let fieldsets = admin
        .fieldsets
        .as_ref()
        .map(|(v, _)| v.as_slice())
        .unwrap_or(&[]);
    let fieldset_tokens = const_slice(
        &quote!(#root::core::Fieldset),
        fieldsets.iter().map(|(title, fields)| {
            let title = title.as_str();
            let field_lits = fields.iter().map(String::as_str);
            quote!(#root::core::Fieldset::new(#title, &[ #( #field_lits ),* ]))
        }),
    );

    let list_display_links = admin
        .list_display_links
        .as_ref()
        .map(|(v, _)| v.as_slice())
        .unwrap_or(&[]);
    let list_display_links_lits = list_display_links.iter().map(|s| s.as_str());

    let search_help_text = admin.search_help_text.as_deref().unwrap_or("");
    let actions_on_top = admin.actions_on_top.unwrap_or(true);
    let actions_on_bottom = admin.actions_on_bottom.unwrap_or(false);
    let date_hierarchy = admin.date_hierarchy.as_deref().unwrap_or("");

    let prepopulated = admin
        .prepopulated_fields
        .as_ref()
        .map(|(v, _)| v.as_slice())
        .unwrap_or(&[]);
    let prepopulated_tokens = const_slice(
        &quote!(#root::core::PrepopulatedField),
        prepopulated.iter().map(|(target, sources)| {
            let target = target.as_str();
            let source_lits = sources.iter().map(String::as_str);
            quote!(#root::core::PrepopulatedField::new(#target, &[ #( #source_lits ),* ]))
        }),
    );

    let raw_id_fields = admin
        .raw_id_fields
        .as_ref()
        .map(|(v, _)| v.as_slice())
        .unwrap_or(&[]);
    let raw_id_fields_lits = raw_id_fields.iter().map(|s| s.as_str());

    let autocomplete_fields = admin
        .autocomplete_fields
        .as_ref()
        .map(|(v, _)| v.as_slice())
        .unwrap_or(&[]);
    let autocomplete_fields_lits = autocomplete_fields.iter().map(|s| s.as_str());

    // #352 — list_select_related accepts "all" | "none" | "field, field, …".
    let list_select_related_tokens = match admin.list_select_related.as_deref() {
        None | Some("all") => quote!(#root::core::ListSelectRelated::All),
        Some("none") => quote!(#root::core::ListSelectRelated::None),
        Some(raw) => {
            let names: Vec<&str> = raw
                .split(',')
                .map(str::trim)
                .filter(|s| !s.is_empty())
                .collect();
            quote!(#root::core::ListSelectRelated::Only(&[ #( #names ),* ]))
        }
    };

    // #359 — formfield_overrides: parse "field:widget,field2:widget2" into
    // a Vec<(String, String)>. Empty / unset → no overrides.
    let formfield_pairs: Vec<(&str, &str)> = admin
        .formfield_overrides
        .as_ref()
        .map(|(v, _)| v.iter().map(|(f, w)| (f.as_str(), w.as_str())).collect())
        .unwrap_or_default();
    let formfield_tokens = formfield_pairs.iter().map(|(field, widget)| {
        let field = *field;
        let widget = *widget;
        quote!((#field, #widget))
    });

    let list_per_page = admin.list_per_page.unwrap_or(0);

    let ordering_pairs = admin
        .ordering
        .as_ref()
        .map(|(v, _)| v.as_slice())
        .unwrap_or(&[]);
    let ordering_tokens = ordering_pairs.iter().map(|(name, desc)| {
        let name = name.as_str();
        let desc = *desc;
        quote!((#name, #desc))
    });

    quote! {
        ::core::option::Option::Some({
            const ADMIN: &#root::core::AdminConfig = &{
                #root::core::AdminConfig::from_parts(#root::core::AdminConfigParts {
                    list_display: &[ #( #list_display_lits ),* ],
                    search_fields: &[ #( #search_fields_lits ),* ],
                    list_per_page: #list_per_page,
                    ordering: &[ #( #ordering_tokens ),* ],
                    readonly_fields: &[ #( #readonly_fields_lits ),* ],
                    list_filter: &[ #( #list_filter_lits ),* ],
                    actions: &[ #( #actions_lits ),* ],
                    fieldsets: #fieldset_tokens,
                    list_display_links: &[ #( #list_display_links_lits ),* ],
                    search_help_text: #search_help_text,
                    actions_on_top: #actions_on_top,
                    actions_on_bottom: #actions_on_bottom,
                    date_hierarchy: #date_hierarchy,
                    prepopulated_fields: #prepopulated_tokens,
                    raw_id_fields: &[ #( #raw_id_fields_lits ),* ],
                    autocomplete_fields: &[ #( #autocomplete_fields_lits ),* ],
                    list_select_related: #list_select_related_tokens,
                    formfield_overrides: &[ #( #formfield_tokens ),* ],
                })
            };
            ADMIN
        })
    }
}

fn inherent_impl_tokens(
    struct_name: &syn::Ident,
    fields: &CollectedFields,
    primary_key: Option<&(syn::Ident, String)>,
    column_consts: &TokenStream2,
    audited_fields: Option<&[&ColumnEntry]>,
    upsert_unique: Option<&[String]>,
    manager_fns: &[syn::Ident],
) -> TokenStream2 {
    let root = rustango_root();
    // Audit-emit fragments threaded into write paths. Non-empty only
    // when the model carries `#[rustango(audit(...))]`. They reborrow
    // `_executor` (a `&mut PgConnection` for audited models — the
    // macro switches the signature below) so the data write and the
    // audit INSERT both run on the same caller-supplied connection.
    let executor_passes_to_data_write = if audited_fields.is_some() {
        quote!(&mut *_executor)
    } else {
        quote!(_executor)
    };
    let executor_param = if audited_fields.is_some() {
        quote!(_executor: &mut #root::sql::sqlx::PgConnection)
    } else {
        quote!(_executor: _E)
    };
    let executor_generics = if audited_fields.is_some() {
        quote!()
    } else {
        quote!(<'_c, _E>)
    };
    let executor_where = if audited_fields.is_some() {
        quote!()
    } else {
        quote! {
            where
                _E: #root::sql::sqlx::Executor<'_c, Database = #root::sql::sqlx::Postgres>,
        }
    };
    // Audited `_on` methods take `&mut PgConnection`; `&PgPool` is an Executor for the rest.
    // One transaction: the before-image's FOR UPDATE must hold through
    // the UPDATE and its audit row.
    let pool_to_save_on = if audited_fields.is_some() {
        // Any failure, COMMIT included, rolls the INSERT back: put the pk and
        // stamps back too, or a retry takes the UPDATE path and writes nothing.
        let restored: Vec<&syn::Ident> = primary_key
            .map(|(pk, _)| pk)
            .into_iter()
            .chain(&fields.auto_now_idents)
            .collect();
        let prev: Vec<syn::Ident> = (0..restored.len())
            .map(|i| quote::format_ident!("__rustango_save_prev_{}", i))
            .collect();
        quote! {
            #( let #prev = ::core::clone::Clone::clone(&self.#restored); )*
            let _saved: ::core::result::Result<u64, #root::sql::ExecError> = async {
                let mut _tx = pool.begin().await?;
                let _affected = self.save_on(&mut *_tx).await?;
                _tx.commit().await?;
                ::core::result::Result::Ok(_affected)
            }
            .await;
            if _saved.is_err() {
                #( self.#restored = #prev; )*
            }
            _saved
        }
    } else {
        quote!(self.save_on(pool).await)
    };
    // One transaction so the write and its audit row commit together.
    let pool_to_insert_on = if audited_fields.is_some() {
        // A failed COMMIT leaves the RETURNING values on `self`; put them back.
        let assigned: Vec<syn::Ident> = fields
            .auto_field_idents
            .iter()
            .map(|(ident, _, _)| ident.clone())
            .collect();
        restore_auto_now_unless(
            &assigned,
            &quote!(::core::result::Result<(), #root::sql::ExecError>),
            &quote!(_saved.is_ok()),
            &quote! {
                let mut _tx = pool.begin().await?;
                self.insert_on(&mut *_tx).await?;
                _tx.commit().await?;
                ::core::result::Result::Ok(())
            },
        )
    } else {
        quote!(self.insert_on(pool).await)
    };
    let pool_to_delete_on = if audited_fields.is_some() {
        quote! {
            let mut _tx = pool.begin().await?;
            let _affected = self.delete_on(&mut *_tx).await?;
            _tx.commit().await?;
            ::core::result::Result::Ok(_affected)
        }
    } else {
        quote!(self.delete_on(pool).await)
    };
    let pool_to_bulk_insert_on = if audited_fields.is_some() {
        quote! {
            let mut _tx = pool.begin().await?;
            Self::bulk_insert_on(rows, &mut *_tx).await?;
            _tx.commit().await?;
            ::core::result::Result::Ok(())
        }
    } else {
        quote!(Self::bulk_insert_on(rows, pool).await)
    };
    // Pre-existing bug surfaced by batch 22's first audited Auto<T>
    // PK test model: `upsert(&PgPool)` body called `self.upsert_on(pool)`
    // directly, but `upsert_on` for audited models takes
    // `&mut PgConnection` (the audit emit needs a real connection).
    // Add the missing acquire shim to keep audited Auto-PK upsert
    // compiling.
    let pool_to_upsert_on = if audited_fields.is_some() {
        quote! {
            let mut _tx = pool.begin().await?;
            self.upsert_on(&mut *_tx).await?;
            _tx.commit().await?;
            ::core::result::Result::Ok(())
        }
    } else {
        quote!(self.upsert_on(pool).await)
    };

    // `insert_pool(&Pool)` — v0.23.0-batch9. Non-audited models only
    // (audit-on-connection over &Pool needs a bi-dialect transaction
    // helper, deferred). Two body shapes:
    // - has_auto: build InsertQuery skipping Auto::Unset columns,
    //   request Auto cols in `returning`, dispatch via
    //   `insert_returning_pool`, then on the returned `PgRow` /
    //   `MySqlAutoId(id)` enum — pull each Auto field from the PG
    //   row OR drop the single i64 into the first Auto field on MySQL
    //   (multi-Auto models on MySQL error at runtime since
    //   `LAST_INSERT_ID()` only reports one)
    // - non-Auto: build InsertQuery with explicit columns/values and
    //   call `insert_pool` (no returning needed)
    // pool_insert_method body for the audited Auto-PK case is moved
    // to after audit_pair_tokens / audit_pk_to_string (they live
    // ~150 lines below). This block keeps the non-audited and
    // non-Auto branches in place — the audited Auto-PK arm is
    // computed below and merged via the dispatch helper variable.
    let pool_insert_method = if audited_fields.is_some() && !fields.has_auto {
        // Audited models with explicit (non-Auto) PKs go through
        // the non-Auto insert path below — the audit emit is one
        // round-trip after the INSERT inside the same tx via
        // audit::save_one_with_audit? No, INSERT semantics
        // differ. For non-Auto PK + audited, route through a
        // dedicated insert + audit emit on the same tx, but defer
        // the macro emission to the audit-bundle-aware block below
        // — this `quote!()` placeholder gets overwritten there.
        quote!()
    } else if audited_fields.is_some() && fields.has_auto {
        // Audited Auto-PK insert_pool — assembled after the audit
        // bundles. Placeholder; real emission below.
        quote!()
    } else if fields.has_auto {
        let pushes = &fields.insert_pushes;
        let returning_cols = &fields.returning_cols;
        // A row not inserted was never saved, so a Rust-filled value must not stay (#1937).
        let filled = &fields.rust_filled_idents;
        let was_unset: Vec<syn::Ident> = filled
            .iter()
            .map(|i| quote::format_ident!("__{}_was_unset", ident_name(i)))
            .collect();
        let insert_or_ignore_call = quote! {
            #( let #was_unset = matches!(&self.#filled, #root::sql::Auto::Unset); )*
            let mut _columns: ::std::vec::Vec<&'static str> =
                ::std::vec::Vec::new();
            let mut _values: ::std::vec::Vec<#root::core::SqlValue> =
                ::std::vec::Vec::new();
            #( #pushes )*
            let _query = #root::core::InsertQuery::new(
                <Self as #root::core::Model>::SCHEMA,
                _columns,
                _values,
            );
            let _result = #root::sql::insert_or_ignore(pool, &_query).await;
            if !matches!(_result, ::core::result::Result::Ok(true)) {
                #( if #was_unset { self.#filled = #root::sql::Auto::Unset; } )*
            }
            _result
        };
        // When every `Auto<T>` field is filled Rust-side
        // (`default_uuid_v7`, issue #823), there is no column to read
        // back from the database — `returning_cols` is empty. Route
        // through plain `insert_pool` instead of
        // `insert_returning_pool` to skip the redundant RETURNING /
        // LAST_INSERT_ID round-trip.
        if fields.returning_cols.is_empty() {
            quote! {
                /// Insert this row against either backend. Every
                /// `Auto<T>` PK on this model is filled Rust-side
                /// (e.g. `default_uuid_v7`) before binding, so no
                /// RETURNING round-trip is needed.
                ///
                /// # Errors
                /// As [`Self::insert`].
                pub async fn insert_pool(
                    &mut self,
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<(), #root::sql::ExecError> {
                    let mut _columns: ::std::vec::Vec<&'static str> =
                        ::std::vec::Vec::new();
                    let mut _values: ::std::vec::Vec<#root::core::SqlValue> =
                        ::std::vec::Vec::new();
                    #( #pushes )*
                    let _query = #root::core::InsertQuery::new(
                        <Self as #root::core::Model>::SCHEMA,
                        _columns,
                        _values,
                    );
                    #root::sql::insert_pool(pool, &_query).await
                }

                /// Eloquent `Model::insertOrIgnore()` — same shape
                /// as the auto-PK branch above. Returns `Ok(true)`
                /// when inserted, `Ok(false)` when a conflict caused
                /// the INSERT to silently skip.
                ///
                /// # Errors
                /// As [`Self::insert`].
                pub async fn insert_or_ignore(
                    &mut self,
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<bool, #root::sql::ExecError> {
                    #insert_or_ignore_call
                }
            }
        } else {
            quote! {
                /// Insert this row against either backend, populating any
                /// `Auto<T>` PK from the auto-assigned value.
                ///
                /// # Errors
                /// As [`Self::insert`].
                pub async fn insert_pool(
                    &mut self,
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<(), #root::sql::ExecError> {
                    let mut _columns: ::std::vec::Vec<&'static str> =
                        ::std::vec::Vec::new();
                    let mut _values: ::std::vec::Vec<#root::core::SqlValue> =
                        ::std::vec::Vec::new();
                    #( #pushes )*
                    let _query = #root::core::InsertQuery::new(
                        <Self as #root::core::Model>::SCHEMA,
                        _columns,
                        _values,
                    )
                    .returning(::std::vec![ #( #returning_cols ),* ]);
                    let _result = #root::sql::insert_returning_pool(
                        pool, &_query,
                    ).await?;
                    #root::sql::apply_auto_pk(_result, self)
                }

                /// Eloquent `Model::insertOrIgnore()` — INSERT this
                /// row or silently skip on unique-constraint
                /// violation. Returns `Ok(true)` when a row was
                /// inserted, `Ok(false)` when a conflict caused the
                /// INSERT to silently skip.
                ///
                /// **Caveat on auto-PK models**: when the row is
                /// skipped (conflict), this instance's `Auto<T>`
                /// fields stay `Unset` — no PK is back-populated
                /// because the server didn't auto-assign one. For
                /// "insert then read back the PK or the existing
                /// row's PK", use the `upsert` family or
                /// `get_or_create`.
                ///
                /// # Errors
                /// As [`Self::insert`].
                pub async fn insert_or_ignore(
                    &mut self,
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<bool, #root::sql::ExecError> {
                    #insert_or_ignore_call
                }
            }
        }
    } else {
        let insert_columns = &fields.insert_columns;
        let insert_values = &fields.insert_values;
        quote! {
            /// Insert this row into its table against either backend.
            /// Equivalent to [`Self::insert`] but takes
            /// [`#root::sql::Pool`].
            ///
            /// # Errors
            /// As [`Self::insert`].
            pub async fn insert_pool(
                &self,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<(), #root::sql::ExecError> {
                let _query = #root::core::InsertQuery::new(
                    <Self as #root::core::Model>::SCHEMA,
                    ::std::vec![ #( #insert_columns ),* ],
                    ::std::vec![ #( #insert_values ),* ],
                );
                #root::sql::insert_pool(pool, &_query).await
            }

            /// Eloquent `Model::insertOrIgnore()` — INSERT this row
            /// or silently skip on unique-constraint violation. Maps
            /// to per-dialect "INSERT ... DO NOTHING on conflict":
            /// PG `INSERT … ON CONFLICT DO NOTHING`, SQLite
            /// `INSERT … ON CONFLICT DO NOTHING` (3.24+), MySQL an
            /// `ON DUPLICATE KEY UPDATE` that leaves the row as is.
            ///
            /// Returns `Ok(true)` when a row was inserted,
            /// `Ok(false)` when a conflict caused the INSERT to
            /// silently skip.
            ///
            /// Use for "create-if-absent" patterns where you don't
            /// need the row back. For "find-or-create with the row
            /// returned", use the queryset-level
            /// `crate::sql::get_or_create` free function.
            ///
            /// # Errors
            /// As [`Self::insert`], plus any dialect-specific
            /// translation error from the ConflictClause writer.
            pub async fn insert_or_ignore(
                &self,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<bool, #root::sql::ExecError> {
                let _query = #root::core::InsertQuery::new(
                    <Self as #root::core::Model>::SCHEMA,
                    ::std::vec![ #( #insert_columns ),* ],
                    ::std::vec![ #( #insert_values ),* ],
                );
                #root::sql::insert_or_ignore(pool, &_query).await
            }
        }
    };

    // The tracked (column, JSON value) pairs, spliced only into
    // `__rustango_audit_pairs`. Empty when the model isn't audited.
    let audit_pair_tokens: Vec<TokenStream2> = audited_fields
        .map(|tracked| {
            tracked
                .iter()
                .map(|c| {
                    let column_lit = c.column.as_str();
                    let ident = &c.ident;
                    quote! {
                        (
                            #column_lit,
                            #root::core::__json_value(&self.#ident),
                        )
                    }
                })
                .collect()
        })
        .unwrap_or_default();
    let audit_pk_to_string = if let Some((pk_ident, _)) = primary_key {
        if fields.pk_is_auto {
            quote!(self.#pk_ident.get().map(|v| ::std::format!("{}", v)).unwrap_or_default())
        } else {
            quote!(::std::format!("{}", &self.#pk_ident))
        }
    } else {
        quote!(::std::string::String::new())
    };
    // `__rustango_audit_entry`: the one place a snapshot `PendingEntry`
    // is built, so every audited write path records the same shape.
    let delete_audited_body = if primary_key.is_some() {
        quote! {
            ::std::boxed::Box::pin(#root::audit::delete_many_with_audit::<Self>(
                pool,
                query,
                |_r: &Self| _r.__rustango_audit_entry(#root::audit::AuditOp::Delete),
            ))
        }
    } else {
        quote! {
            let _ = (pool, query);
            ::std::boxed::Box::pin(async {
                ::core::result::Result::Err(#root::sql::ExecError::MissingPrimaryKey {
                    table: <Self as #root::core::Model>::SCHEMA.table,
                })
            })
        }
    };
    let update_audited_body = if primary_key.is_some() {
        quote! {
            ::std::boxed::Box::pin(#root::audit::update_many_with_audit::<Self>(
                pool,
                query,
                move |_r: &Self| _r.__rustango_audit_entry(op),
            ))
        }
    } else {
        quote! {
            let _ = (pool, query, op);
            ::std::boxed::Box::pin(async {
                ::core::result::Result::Err(#root::sql::ExecError::MissingPrimaryKey {
                    table: <Self as #root::core::Model>::SCHEMA.table,
                })
            })
        }
    };
    let audit_entry_method = if audited_fields.is_some() {
        let pairs = audit_pair_tokens.iter();
        let pk_str = audit_pk_to_string.clone();
        quote! {
            /// This row's tracked `(column, value)` pairs.
            #[doc(hidden)]
            pub fn __rustango_audit_pairs(
                &self,
            ) -> ::std::vec::Vec<(&'static str, #root::__serde_json::Value)> {
                ::std::vec![ #( #pairs ),* ]
            }

            /// This row's audit PK.
            #[doc(hidden)]
            pub fn __rustango_audit_pk(&self) -> ::std::string::String {
                #pk_str
            }

            /// Snapshot audit entry for `operation` on this row.
            #[doc(hidden)]
            pub fn __rustango_audit_entry(
                &self,
                operation: #root::audit::AuditOp,
            ) -> #root::audit::PendingEntry {
                #root::audit::PendingEntry {
                    entity_table: <Self as #root::core::Model>::SCHEMA.table,
                    entity_pk: self.__rustango_audit_pk(),
                    operation,
                    source: #root::audit::current_source(),
                    changes: #root::audit::snapshot_changes(&self.__rustango_audit_pairs()),
                }
            }

            /// Audited bulk `UPDATE`, behind `Model::__rustango_audited_update`.
            #[doc(hidden)]
            pub fn __rustango_update_audited<'a>(
                pool: &'a #root::sql::Pool,
                query: &'a #root::core::UpdateQuery,
                op: #root::audit::AuditOp,
            ) -> ::std::pin::Pin<::std::boxed::Box<
                dyn ::core::future::Future<
                    Output = ::core::result::Result<u64, #root::sql::ExecError>,
                > + ::core::marker::Send + 'a,
            >> {
                #update_audited_body
            }

            /// Audited `create` entry for a new row, behind `Model::__rustango_audited_create`.
            #[doc(hidden)]
            pub fn __rustango_create_audited<'a, 't>(
                tx: &'a mut #root::sql::PoolTx<'t>,
                pk: #root::core::SqlValue,
            ) -> ::std::pin::Pin<::std::boxed::Box<
                dyn ::core::future::Future<
                    Output = ::core::result::Result<(), #root::sql::ExecError>,
                > + ::core::marker::Send + 'a,
            >> {
                ::std::boxed::Box::pin(#root::audit::record_create::<Self>(
                    tx,
                    <Self as #root::core::Model>::SCHEMA,
                    pk,
                    |_r: &Self| _r.__rustango_audit_entry(#root::audit::AuditOp::Create),
                ))
            }

            /// Audited one-row `update` entry, behind `Model::__rustango_audited_update_record`.
            #[doc(hidden)]
            pub fn __rustango_update_record_audited<'a, 't>(
                tx: &'a mut #root::sql::PoolTx<'t>,
                pk: #root::core::SqlValue,
            ) -> ::std::pin::Pin<::std::boxed::Box<
                dyn ::core::future::Future<
                    Output = ::core::result::Result<(), #root::sql::ExecError>,
                > + ::core::marker::Send + 'a,
            >> {
                ::std::boxed::Box::pin(#root::audit::record_update::<Self>(
                    tx,
                    <Self as #root::core::Model>::SCHEMA,
                    pk,
                    |_r: &Self| _r.__rustango_audit_entry(#root::audit::AuditOp::Update),
                ))
            }

            /// Audited bulk `DELETE`, behind `Model::__rustango_audited_delete`.
            #[doc(hidden)]
            pub fn __rustango_delete_audited<'a>(
                pool: &'a #root::sql::Pool,
                query: &'a #root::core::DeleteQuery,
            ) -> ::std::pin::Pin<::std::boxed::Box<
                dyn ::core::future::Future<
                    Output = ::core::result::Result<u64, #root::sql::ExecError>,
                > + ::core::marker::Send + 'a,
            >> {
                #delete_audited_body
            }
        }
    } else {
        quote!()
    };
    // Builds `_audit_entry`; `written` is the soft-delete column's new
    // value, recorded in place of the stale `self` field.
    let make_entry = |op_path: TokenStream2, written: Option<TokenStream2>| -> TokenStream2 {
        if let (Some(v), Some(col)) = (written, fields.soft_delete_column.as_deref()) {
            quote! {
                let mut _audit_entry = self.__rustango_audit_entry(#op_path);
                _audit_entry.set_tracked(#col, #v);
            }
        } else {
            quote!(let _audit_entry = self.__rustango_audit_entry(#op_path);)
        }
    };
    let soft_deleted_json = quote!(#root::__serde_json::to_value(&_now)
        .unwrap_or(#root::__serde_json::Value::Null));
    let restored_json = quote!(#root::__serde_json::Value::Null);
    // `_on` emit; `affected` paths skip the row when nothing changed.
    let make_op_emit =
        |op_path: TokenStream2, written: Option<TokenStream2>, affected: bool| -> TokenStream2 {
            if audited_fields.is_none() {
                return quote!();
            }
            let entry = make_entry(op_path, written);
            let emit = quote! {
                #entry
                #root::audit::emit_one(&mut *_executor, &_audit_entry).await?;
            };
            if affected {
                quote!(if _affected > 0 { #emit })
            } else {
                emit
            }
        };
    let audit_insert_emit = make_op_emit(quote!(#root::audit::AuditOp::Create), None, false);
    let audit_delete_emit = make_op_emit(quote!(#root::audit::AuditOp::Delete), None, true);
    let audit_softdelete_emit = make_op_emit(
        quote!(#root::audit::AuditOp::SoftDelete),
        Some(soft_deleted_json.clone()),
        true,
    );
    let audit_restore_emit = make_op_emit(
        quote!(#root::audit::AuditOp::Restore),
        Some(restored_json.clone()),
        true,
    );
    // `&Pool` update runner for soft_delete / restore: one tx with the
    // audit row when audited, a plain UPDATE otherwise.
    let make_pool_update = |op_path: TokenStream2, written: TokenStream2| -> TokenStream2 {
        if audited_fields.is_some() {
            let entry = make_entry(op_path, Some(written));
            quote! {
                #entry
                #root::audit::save_one_with_audit(pool, &_query, &_audit_entry).await
            }
        } else {
            quote!(#root::sql::update_pool(pool, &_query).await)
        }
    };
    let pool_softdelete_run =
        make_pool_update(quote!(#root::audit::AuditOp::SoftDelete), soft_deleted_json);
    let pool_restore_run = make_pool_update(quote!(#root::audit::AuditOp::Restore), restored_json);

    // `save_pool(&Pool)` — emitted for every model with a PK. The
    // audited `save_pool` is built below on the diff path; both share
    // `save_partial_methods`, which differ only in how they run `_query`.
    let save_ret = quote!(::core::result::Result<u64, #root::sql::ExecError>);
    let save_keep = quote!(matches!(_saved, ::core::result::Result::Ok(n) if n > 0));
    let save_partial_methods = |pk_ident: &syn::Ident,
                                pk_column_lit: &str,
                                run: TokenStream2|
     -> TokenStream2 {
        let assignments = &fields.update_assignments;
        // Pushed in step with `update_assignments`: one column each.
        let assignment_cols = &fields.upsert_update_columns;
        let write = restore_auto_now_unless(
            &fields.auto_now_idents,
            &save_ret,
            &save_keep,
            &quote! {
                // Build only the wanted assignments, so an unnamed
                // `auto_now` field is not stamped.
                let mut _filtered: ::std::vec::Vec<#root::core::Assignment> =
                    ::std::vec::Vec::with_capacity(_wanted_cols.len());
                #(
                    if _wanted_cols.contains(#assignment_cols) {
                        _filtered.push(#assignments);
                    }
                )*
                if _filtered.is_empty() {
                    // All field names valid, but they all map to
                    // non-assignable slots (PK column, computed/
                    // virtual fields, relations without an
                    // assignment). Same no-op as an empty list.
                    #root::__tracing::warn!(
                        target: "rustango::save_partial",
                        model = _schema.name,
                        "save_partial: every named field maps to a non-assignable column — no-op"
                    );
                    return ::core::result::Result::Ok(0);
                }
                let _query = #root::core::UpdateQuery::new(
                    _schema,
                    _filtered,
                    #root::core::WhereExpr::Predicate(#root::core::Filter::new(
                        #pk_column_lit,
                        #root::core::Op::Eq,
                        ::core::convert::Into::<#root::core::SqlValue>::into(
                            ::core::clone::Clone::clone(&self.#pk_ident)
                        ),
                    )),
                );
                #run
            },
        );
        quote! {
            /// Save (UPDATE) only the listed Rust-side fields,
            /// leaving every other column untouched. Issue #66.
            ///
            /// `fields` are Rust-side struct field names; the macro
            /// resolves each to its SQL column. Unknown field
            /// names return [`#root::core::QueryError::UnknownField`]
            /// wrapped in `ExecError::Query`. An empty list is a
            /// no-op (returns `Ok(())` and logs a `tracing::warn!`).
            /// On an audited model the audit diff covers only these fields.
            ///
            /// Use this when:
            /// * you only mutated a couple of fields on a wide row
            ///   (avoid re-writing every column on every save), or
            /// * two writers diverged after their initial read and
            ///   you want to preserve the other writer's changes to
            ///   columns you didn't touch.
            ///
            /// Auto-PK models with an unset PK return
            /// [`#root::core::QueryError::UnknownField`] with
            /// field name `<pk>` — `save_partial` is an
            /// UPDATE-only path. Call [`Self::insert_pool`]
            /// (or [`Self::save_pool`] which dispatches based on
            /// PK state) for the INSERT case.
            ///
            /// # Errors
            /// As [`Self::save_pool`], plus `UnknownField` for
            /// unknown / empty / Auto-Unset cases.
            pub async fn save_partial(
                &mut self,
                fields: &[&str],
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                if fields.is_empty() {
                    #root::__tracing::warn!(
                        target: "rustango::save_partial",
                        model = <Self as #root::core::Model>::SCHEMA.name,
                        "save_partial called with empty field list — no-op"
                    );
                    return ::core::result::Result::Ok(0);
                }
                let _schema = <Self as #root::core::Model>::SCHEMA;
                // Validate field names against the schema.
                let mut _wanted_cols: ::std::collections::HashSet<&'static str> =
                    ::std::collections::HashSet::with_capacity(fields.len());
                for f in fields {
                    match _schema.field(f) {
                        ::core::option::Option::Some(fs) => {
                            _wanted_cols.insert(fs.column);
                        }
                        ::core::option::Option::None => {
                            return ::core::result::Result::Err(
                                #root::sql::ExecError::Query(
                                    #root::core::QueryError::UnknownField {
                                        model: _schema.name,
                                        field: (*f).to_owned(),
                                    }
                                )
                            );
                        }
                    }
                }
                #write
            }

            /// Typed-column counterpart of [`Self::save_partial`] —
            /// issue #67. `fields` is a tuple of [`Column`]
            /// constants whose `Model` matches `Self`; typos and
            /// model mismatches surface at *compile time*
            /// (`Author::name` inside a `Post::save_partial_typed`
            /// call is a type error, no runtime check).
            ///
            /// ```ignore
            /// post.save_partial_typed((Post::title, Post::slug), &pool).await?;
            /// ```
            ///
            /// Lowers to [`Self::save_partial`] under the hood — the
            /// tuple is reduced to a `&[&str]` slice of Rust-side
            /// field names and forwarded.
            ///
            /// [`Column`]: #root::core::Column
            ///
            /// # Errors
            /// As [`Self::save_partial`].
            pub async fn save_partial_typed<
                L: #root::core::TypedFieldList<Self>,
            >(
                &mut self,
                fields: L,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                let _names = fields.rust_field_names();
                let _refs: ::std::vec::Vec<&str> =
                    _names.iter().copied().collect();
                self.save_partial(&_refs, pool).await
            }
        }
    };
    let pool_save_method = if let Some((pk_ident, pk_col)) = primary_key {
        let pk_column_lit = pk_col.as_str();
        let assignments = &fields.update_assignments;
        if audited_fields.is_some() {
            quote!()
        } else {
            let partial = save_partial_methods(
                pk_ident,
                pk_column_lit,
                quote!(#root::sql::update_pool(pool, &_query).await),
            );
            let dispatch_unset = if fields.pk_is_auto {
                quote! {
                    if matches!(self.#pk_ident, #root::sql::Auto::Unset) {
                        return self.insert_pool(pool).await.map(|()| 1u64);
                    }
                }
            } else {
                quote!()
            };
            let write = restore_auto_now_unless(
                &fields.auto_now_idents,
                &save_ret,
                &save_keep,
                &quote! {
                    let _query = #root::core::UpdateQuery::new(
                        <Self as #root::core::Model>::SCHEMA,
                        ::std::vec![ #( #assignments ),* ],
                        #root::core::WhereExpr::Predicate(#root::core::Filter::new(
                            #pk_column_lit,
                            #root::core::Op::Eq,
                            ::core::convert::Into::<#root::core::SqlValue>::into(
                                ::core::clone::Clone::clone(&self.#pk_ident)
                            ),
                        )),
                    );
                    let _affected = #root::sql::update_pool(pool, &_query).await?;
                    ::core::result::Result::Ok(_affected)
                },
            );
            quote! {
                /// Save this row to its table against either backend.
                /// `INSERT` when the `Auto<T>` PK is `Unset`, else
                /// `UPDATE` keyed on the PK; global scopes do not apply.
                ///
                /// # Errors
                /// As [`Self::save`].
                pub async fn save_pool(
                    &mut self,
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                    #dispatch_unset
                    #write
                }

                #partial
            }
        }
    } else {
        quote!()
    };

    // Audited `insert_pool` (overrides the placeholder set higher up
    // in the function). v0.23.0-batch22 — both Auto-PK and non-Auto-PK
    // audited models get insert_pool routing through
    // audit::insert_one_with_audit (per-backend tx wraps INSERT
    // + auto-PK readback + audit emit). Snapshot-style audit (the
    // PendingEntry's `changes` carries post-write field values).
    let pool_insert_method = if audited_fields.is_some() {
        if let Some(_) = primary_key {
            let pushes = if fields.has_auto {
                fields.insert_pushes.clone()
            } else {
                // For non-Auto-PK models, the macro normally builds
                // {columns, values} from fields.insert_columns +
                // fields.insert_values rather than insert_pushes.
                // Map those into the pushes shape.
                fields
                    .insert_columns
                    .iter()
                    .zip(&fields.insert_values)
                    .map(|(col, val)| {
                        quote! {
                            _columns.push(#col);
                            _values.push(#val);
                        }
                    })
                    .collect()
            };
            // Rust-filled Auto PKs (`default_uuid_v7`) leave the list empty (#1934).
            let returning_cols: Vec<proc_macro2::TokenStream> = if !fields.returning_cols.is_empty()
            {
                fields.returning_cols.clone()
            } else {
                // Non-Auto-PK: still need RETURNING something for the
                // audit helper's contract (it errors on empty
                // returning). Return the PK column so the audit row
                // can carry the assigned PK back. Some non-Auto PKs
                // are server-side-default (e.g. UUIDv4 default), so
                // RETURNING is genuinely useful.
                primary_key
                    .map(|(_, col)| {
                        let lit = col.as_str();
                        vec![quote!(#lit)]
                    })
                    .unwrap_or_default()
            };
            quote! {
                /// Insert this row against either backend with audit
                /// emission inside the same transaction. Bi-dialect
                /// counterpart of [`Self::insert`] for audited models.
                ///
                /// Snapshot-style audit (post-write field values).
                ///
                /// # Errors
                /// As [`Self::insert`].
                pub async fn insert_pool(
                    &mut self,
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<(), #root::sql::ExecError> {
                    let mut _columns: ::std::vec::Vec<&'static str> =
                        ::std::vec::Vec::new();
                    let mut _values: ::std::vec::Vec<#root::core::SqlValue> =
                        ::std::vec::Vec::new();
                    #( #pushes )*
                    let _query = #root::core::InsertQuery::new(
                        <Self as #root::core::Model>::SCHEMA,
                        _columns,
                        _values,
                    )
                    .returning(::std::vec![ #( #returning_cols ),* ]);
                    #root::audit::insert_one_with_audit(pool, &_query, self, |_m: &Self| {
                        _m.__rustango_audit_entry(#root::audit::AuditOp::Create)
                    })
                    .await
                }
            }
        } else {
            quote!()
        }
    } else {
        // Keep the non-audited pool_insert_method we built earlier.
        pool_insert_method
    };

    // Update audited save_pool: now that insert_pool is wired for
    // audited Auto-PK models, save_pool can dispatch Auto::Unset →
    // insert_pool. Non-audited save_pool already does this.
    // v0.23.0-batch25 — diff-style audit on the audited save_pool path.
    // Replaces the snapshot-only emission with a per-backend transaction
    // body that:
    //  1. SELECTs the tracked columns by PK (typed Row::try_get per
    //     column), capturing BEFORE values
    //  2. compiles the UPDATE via pool.dialect() and runs it on the tx
    //  3. builds AFTER pairs from &self
    //  4. diffs BEFORE/AFTER, emits one PendingEntry with
    //     AuditOp::Update + diff_changes(...) on the same tx connection
    //  5. commits
    //
    // Per-backend arms inline the SQL string + placeholder shape, then
    // share the `audit_before_pair_tokens` decoder block (Row::try_get
    // is polymorphic over Row type — the same tokens work against
    // PgRow and MySqlRow as long as the field's Rust type implements
    // both Decode<Postgres> and Decode<MySql>, which Auto<T> +
    // primitives + chrono/uuid/serde_json::Value all do).
    let pool_save_method = if let Some(tracked) = audited_fields {
        if let Some((pk_ident, pk_col)) = primary_key {
            let pk_column_lit = pk_col.as_str();
            let partial = save_partial_methods(
                pk_ident,
                pk_column_lit,
                quote! {
                    self.__rustango_save_with_diff(
                        pool,
                        &_query,
                        ::core::option::Option::Some(&_wanted_cols),
                    )
                    .await
                },
            );
            // Per-tracked-column BEFORE-pair token list. Each entry
            // is `(col_lit, try_get_returning<value_ty>(row, col_lit) → Json)`.
            // The Row alias resolves to PgRow / MySqlRow per call site,
            // so the same template generates both the PG and MySQL bodies.
            let mk_before_pairs =
                |getter: &dyn Fn(&ColumnEntry) -> TokenStream2| -> Vec<TokenStream2> {
                    tracked
                        .iter()
                        .map(|c| {
                            let getter = getter(c);
                            let column_lit = c.column.as_str();
                            let value_ty = &c.value_ty;
                            quote! {
                                (
                                    #column_lit,
                                    match #getter::<#value_ty>(
                                        _audit_before_row, #column_lit,
                                    ) {
                                        ::core::result::Result::Ok(v) => {
                                            #root::core::__json_value(&v)
                                        }
                                        ::core::result::Result::Err(_) => #root::__serde_json::Value::Null,
                                    },
                                )
                            }
                        })
                        .collect()
                };
            let before_pairs_pg = mk_before_pairs(&|_| quote!(#root::sql::try_get_returning));
            let before_pairs_my = mk_before_pairs(&|c| {
                if c.uuid_column {
                    quote!(#root::sql::try_get_flat_my)
                } else {
                    quote!(#root::sql::try_get_returning_my)
                }
            });
            let before_pairs_sqlite =
                mk_before_pairs(&|_| quote!(#root::sql::try_get_returning_sqlite));
            let tracked_cols: Vec<&str> = tracked.iter().map(|c| c.column.as_str()).collect();
            let pk_value_for_bind = if fields.pk_is_auto {
                quote!(self.#pk_ident.get().copied().unwrap_or_default())
            } else {
                quote!(::core::clone::Clone::clone(&self.#pk_ident))
            };
            let assignments = &fields.update_assignments;
            let unset_dispatch = if fields.has_auto {
                quote! {
                    if matches!(self.#pk_ident, #root::sql::Auto::Unset) {
                        return self.insert_pool(pool).await.map(|()| 1u64);
                    }
                }
            } else {
                quote!()
            };
            let write = restore_auto_now_unless(
                &fields.auto_now_idents,
                &save_ret,
                &save_keep,
                &quote! {
                    let _query = #root::core::UpdateQuery::new(
                        <Self as #root::core::Model>::SCHEMA,
                        ::std::vec![ #( #assignments ),* ],
                        #root::core::WhereExpr::Predicate(#root::core::Filter::new(
                            #pk_column_lit,
                            #root::core::Op::Eq,
                            ::core::convert::Into::<#root::core::SqlValue>::into(
                                ::core::clone::Clone::clone(&self.#pk_ident)
                            ),
                        )),
                    );
                    self.__rustango_save_with_diff(pool, &_query, ::core::option::Option::None)
                        .await
                },
            );
            quote! {
                /// Save this row against either backend with audit
                /// emission (diff-style: BEFORE+AFTER) inside the
                /// same transaction. Auto::Unset PK routes to
                /// insert_pool. Bi-dialect counterpart of
                /// [`Self::save`] for audited models.
                ///
                /// The audit row's `changes` JSON contains one
                /// `{ "field": { "before": …, "after": … } }` entry
                /// per tracked column whose value actually changed
                /// — same shape as the existing &PgPool save() emits.
                /// Keyed on the PK; global scopes do not apply.
                ///
                /// # Errors
                /// As [`Self::save`].
                pub async fn save_pool(
                    &mut self,
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                    #unset_dispatch
                    #write
                }

                /// Run `query` and write its diff entry, limited to `only` columns.
                #[doc(hidden)]
                async fn __rustango_save_with_diff(
                    &self,
                    pool: &#root::sql::Pool,
                    query: &#root::core::UpdateQuery,
                    only: ::core::option::Option<&::std::collections::HashSet<&'static str>>,
                ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                    let mut _after_pairs = self.__rustango_audit_pairs();
                    if let ::core::option::Option::Some(only) = only {
                        _after_pairs.retain(|(col, _)| only.contains(col));
                    }
                    let _before_query = #root::audit::before_image_query(
                        <Self as #root::core::Model>::SCHEMA,
                        #pk_column_lit,
                        ::core::convert::Into::<#root::core::SqlValue>::into(
                            #pk_value_for_bind,
                        ),
                        &[ #( #tracked_cols ),* ],
                    );
                    #root::audit::save_one_with_diff(
                        pool,
                        query,
                        &_before_query,
                        <Self as #root::core::Model>::SCHEMA.table,
                        self.__rustango_audit_pk(),
                        _after_pairs,
                        |_audit_before_row| ::std::vec![ #( #before_pairs_pg ),* ],
                        |_audit_before_row| ::std::vec![ #( #before_pairs_my ),* ],
                        |_audit_before_row| ::std::vec![ #( #before_pairs_sqlite ),* ],
                    ).await
                }

                #partial
            }
        } else {
            quote!()
        }
    } else {
        pool_save_method
    };

    // `delete_pool(&Pool)` — emitted for every model with a PK. Two
    // body shapes:
    // - non-audited: simple dispatch through `sql::delete_pool`
    // - audited: routes through `audit::delete_one_with_audit`,
    //   which opens a per-backend transaction wrapping DELETE +
    //   audit emit so the data write and audit row commit atomically.
    let pool_delete_method = {
        let pk_column_lit = primary_key.map(|(_, col)| col.as_str()).unwrap_or("id");
        let pk_ident_for_pool = primary_key.map(|(ident, _)| ident);
        if let Some(pk_ident) = pk_ident_for_pool {
            if audited_fields.is_some() {
                quote! {
                    /// Delete this row against either backend with audit
                    /// emission inside the same transaction. Bi-dialect
                    /// counterpart of [`Self::delete`] for audited models.
                    /// Keyed on the PK; global scopes do not apply.
                    ///
                    /// # Errors
                    /// As [`Self::delete`].
                    pub async fn delete_pool(
                        &self,
                        pool: &#root::sql::Pool,
                    ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                        let _query = #root::core::DeleteQuery::by_pk(
                            <Self as #root::core::Model>::SCHEMA,
                            #pk_column_lit,
                            ::core::convert::Into::<#root::core::SqlValue>::into(
                                ::core::clone::Clone::clone(&self.#pk_ident)
                            ),
                        );
                        let _audit_entry =
                            self.__rustango_audit_entry(#root::audit::AuditOp::Delete);
                        #root::audit::delete_one_with_audit(
                            pool, &_query, &_audit_entry,
                        ).await
                    }
                }
            } else {
                quote! {
                    /// Delete the row identified by this instance's primary key
                    /// against either backend. Equivalent to [`Self::delete`] but
                    /// takes [`#root::sql::Pool`] and dispatches per backend.
                    /// Global scopes do not apply.
                    ///
                    /// # Errors
                    /// As [`Self::delete`].
                    pub async fn delete_pool(
                        &self,
                        pool: &#root::sql::Pool,
                    ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                        let _query = #root::core::DeleteQuery::by_pk(
                            <Self as #root::core::Model>::SCHEMA,
                            #pk_column_lit,
                            ::core::convert::Into::<#root::core::SqlValue>::into(
                                ::core::clone::Clone::clone(&self.#pk_ident)
                            ),
                        );
                        #root::sql::delete_pool(pool, &_query).await
                    }
                }
            }
        } else {
            quote!()
        }
    };

    // Bulk writers on audited models write one audit row per affected
    // row, in the write's transaction (#1747).
    let (bulk_delete_run, bulk_update_run, truncate_run) = if audited_fields.is_some() {
        (
            quote!(#root::audit::delete_many_with_audit::<Self>(pool, &_query, |_r: &Self| {
                _r.__rustango_audit_entry(#root::audit::AuditOp::Delete)
            })
            .await),
            quote!(#root::audit::update_many_with_audit::<Self>(pool, &_query, |_r: &Self| {
                _r.__rustango_audit_entry(#root::audit::AuditOp::Update)
            })
            .await),
            quote! {
                let _table = <Self as #root::core::Model>::SCHEMA.table;
                let _sql = #root::sql::truncate_sql(pool.dialect(), _table);
                #root::audit::truncate_with_audit(pool, _table, &_sql).await
            },
        )
    } else {
        (
            quote!(#root::sql::delete_pool(pool, &_query).await),
            quote!(#root::sql::update_pool(pool, &_query).await),
            quote!(#root::sql::truncate(pool, <Self as #root::core::Model>::SCHEMA).await),
        )
    };

    // `refresh_from_db_pool(&mut self, pool)` — re-SELECT the row
    // matching this instance's PK and overwrite the in-memory state
    // with the freshly-fetched columns.
    // Issue #825. Only emitted when the model declares a PK; non-PK
    // models can't address a specific row.
    //
    // `replicate(&self)` — Eloquent-style clone-as-insertable. Copies
    // every field from `self`; resets the PK to `Auto::Unset` when
    // `pk_is_auto` so the next `save_pool` / `insert_pool` allocates
    // a fresh autoincrement value. Non-Auto PKs preserve the source
    // PK — the caller must overwrite before insert. Pure-Rust, no
    // I/O, no dialect surface.
    let refresh_replicate_methods = if let Some((pk_ident, _)) = primary_key {
        let other_field_clones: Vec<TokenStream2> = fields
            .column_entries
            .iter()
            .filter(|c| &c.ident != pk_ident)
            .map(|c| {
                let ident = &c.ident;
                quote! {
                    #ident: ::core::clone::Clone::clone(&self.#ident)
                }
            })
            .collect();
        let pk_clone_token = if fields.pk_is_auto {
            quote! { #pk_ident: #root::sql::Auto::Unset }
        } else {
            quote! { #pk_ident: ::core::clone::Clone::clone(&self.#pk_ident) }
        };
        let replicate_doc = if fields.pk_is_auto {
            quote! {
                /// Eloquent-style `replicate()` — return a clone of this
                /// row with the primary key reset to [`Auto::Unset`] so
                /// the copy is ready for `insert_pool` / `save_pool` to
                /// allocate a fresh autoincrement value. Every other
                /// field is `Clone`d verbatim. Issue #825.
                ///
                /// `auto_now_add` / `auto_now` timestamp fields are
                /// **not** reset (Eloquent's `replicate` doesn't reset
                /// them either) — pass them through the normal insert
                /// path if you want fresh values, or assign them
                /// explicitly after the call.
            }
        } else {
            quote! {
                /// Eloquent-style `replicate()` — clone this row
                /// verbatim. Because the primary key is **not** an
                /// `Auto<T>`, the clone keeps the source PK; the
                /// caller must overwrite `copy.<pk>` before inserting
                /// to avoid a unique-key violation. Issue #825.
            }
        };
        // 2026-06-07 — field-name / shortcut collision guard.
        //
        // The macro emits both `pub const <field>: <field>_col = ...`
        // (per-field typed-column const, used by the typed-builder
        // surface as `Post::id.eq(...)`) AND `pub async fn <shortcut>(...)`
        // for the Eloquent shortcuts (`count`, `sum`, `min` …). When a
        // model has a field named e.g. `count`, both items would land
        // in the same inherent impl with the same name, and the
        // compiler rejects the derive with "duplicate definitions".
        //
        // Drop the conflicting shortcut for that model. Callers can
        // still reach the same behavior via
        // `QuerySet::<Model>::default().count(&pool)`.
        let column_names: ::std::collections::HashSet<String> = fields
            .column_entries
            .iter()
            .map(|c| ident_name(&c.ident))
            .collect();
        let emit_if_no_field_collision = |name: &str, tokens: TokenStream2| -> TokenStream2 {
            if column_names.contains(name) {
                quote! {}
            } else {
                tokens
            }
        };
        let count_method = emit_if_no_field_collision(
            "count",
            quote! {
                /// Count rows of this model — `SELECT COUNT(*) FROM
                /// <table>`. Eloquent `Model::count()` parity.
                ///
                /// Skipped on models that already declare a field named
                /// `count`. Drop into `QuerySet::<Self>::default().count(&pool)`
                /// in that case.
                ///
                /// # Errors
                /// As [`CounterPool::count`].
                ///
                /// [`CounterPool::count`]: rustango::sql::CounterPool::count
                pub async fn count(
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<i64, #root::sql::ExecError> {
                    use #root::sql::CounterPool as _;
                    #root::query::QuerySet::<Self>::default()
                        .count(pool)
                        .await
                }
            },
        );
        let value_method = emit_if_no_field_collision(
            "value",
            quote! {
                /// Pluck a single scalar from the first row.
                /// Eloquent `Model::query()->value($col)` parity.
                ///
                /// Skipped on models that already declare a field named
                /// `value`. Drop into
                /// `QuerySet::<Self>::default().values_list_flat(col).first::<U>(&pool)` instead.
                ///
                /// # Errors
                /// As `ValuesFlatQuerySet::first`.
                pub async fn value<U>(
                    col: &str,
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<
                    ::core::option::Option<U>,
                    #root::sql::ExecError,
                >
                where
                    U: #root::sql::FlatScalar,
                {
                    let _col_static: &'static str = Self::__resolve_col(col)?;
                    #root::query::QuerySet::<Self>::default()
                        .values_list_flat(_col_static)
                        .first::<U>(pool)
                        .await
                }
            },
        );
        let sum_method = emit_if_no_field_collision(
            "sum",
            quote! {
                /// `SUM(col)` over every row. Eloquent `Model::sum($col)`.
                /// Skipped on models that already declare a field named
                /// `sum`.
                ///
                /// # Errors
                /// As [`#root::sql::fetch_aggregate_pool`].
                pub async fn sum<U>(
                    col: &str,
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<
                    ::core::option::Option<U>,
                    #root::sql::ExecError,
                >
                where
                    (::core::option::Option<U>,): #root::sql::MaybePgFromRow
                        + #root::sql::MaybeMyFromRow
                        + #root::sql::MaybeSqliteFromRow
                        + ::core::marker::Send
                        + ::core::marker::Unpin,
                {
                    #root::query::QuerySet::<Self>::default()
                        .sum::<U>(col, pool)
                        .await
                }
            },
        );
        let avg_method = emit_if_no_field_collision(
            "avg",
            quote! {
                /// `AVG(col)`. Eloquent `Model::avg($col)`. Skipped on
                /// models that already declare a field named `avg`.
                ///
                /// # Errors
                /// As [`#root::sql::fetch_aggregate_pool`].
                pub async fn avg<U>(
                    col: &str,
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<
                    ::core::option::Option<U>,
                    #root::sql::ExecError,
                >
                where
                    (::core::option::Option<U>,): #root::sql::MaybePgFromRow
                        + #root::sql::MaybeMyFromRow
                        + #root::sql::MaybeSqliteFromRow
                        + ::core::marker::Send
                        + ::core::marker::Unpin,
                {
                    #root::query::QuerySet::<Self>::default()
                        .avg::<U>(col, pool)
                        .await
                }
            },
        );
        let min_method = emit_if_no_field_collision(
            "min",
            quote! {
                /// `MIN(col)`. Eloquent `Model::min($col)`. Skipped on
                /// models that already declare a field named `min`.
                ///
                /// # Errors
                /// As [`#root::sql::fetch_aggregate_pool`].
                pub async fn min<U>(
                    col: &str,
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<
                    ::core::option::Option<U>,
                    #root::sql::ExecError,
                >
                where
                    (::core::option::Option<U>,): #root::sql::MaybePgFromRow
                        + #root::sql::MaybeMyFromRow
                        + #root::sql::MaybeSqliteFromRow
                        + ::core::marker::Send
                        + ::core::marker::Unpin,
                {
                    #root::query::QuerySet::<Self>::default()
                        .min::<U>(col, pool)
                        .await
                }
            },
        );
        let max_method = emit_if_no_field_collision(
            "max",
            quote! {
                /// `MAX(col)`. Eloquent `Model::max($col)`. Skipped on
                /// models that already declare a field named `max`.
                ///
                /// # Errors
                /// As [`#root::sql::fetch_aggregate_pool`].
                pub async fn max<U>(
                    col: &str,
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<
                    ::core::option::Option<U>,
                    #root::sql::ExecError,
                >
                where
                    (::core::option::Option<U>,): #root::sql::MaybePgFromRow
                        + #root::sql::MaybeMyFromRow
                        + #root::sql::MaybeSqliteFromRow
                        + ::core::marker::Send
                        + ::core::marker::Unpin,
                {
                    #root::query::QuerySet::<Self>::default()
                        .max::<U>(col, pool)
                        .await
                }
            },
        );
        let first_method = emit_if_no_field_collision(
            "first",
            quote! {
                /// First row of this model. Eloquent `Model::first()`.
                /// Skipped on models that already declare a field named
                /// `first`. Drop into `QuerySet::<Self>::default().first(&pool)`.
                ///
                /// # Errors
                /// As `QuerySet::first`.
                pub async fn first(
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<
                    ::core::option::Option<Self>,
                    #root::sql::ExecError,
                > {
                    #root::query::QuerySet::<Self>::default()
                        .first(pool)
                        .await
                }
            },
        );
        let last_method = emit_if_no_field_collision(
            "last",
            quote! {
                /// Last row of this model by primary-key DESC.
                /// Eloquent `Model::query()->latest('id')->first()`
                /// parity — fetches the highest-PK row without
                /// requiring the caller to spell the PK column.
                /// Returns `None` on an empty table.
                ///
                /// Equivalent to `QuerySet::<Self>::default().last(&pool)`.
                /// Skipped on models that already declare a field
                /// named `last`.
                ///
                /// # Errors
                /// As `QuerySet::last`.
                pub async fn last(
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<
                    ::core::option::Option<Self>,
                    #root::sql::ExecError,
                > {
                    #root::query::QuerySet::<Self>::default()
                        .last(pool)
                        .await
                }
            },
        );
        quote! {
            /// Re-SELECT this row by its primary key and overwrite
            /// every in-memory field with the freshly-fetched value.
            /// Issue #825.
            ///
            /// Use this when the row may have been modified by another
            /// process / connection / job since you read it — e.g. after
            /// a queued task callback, or to re-sync stale UI state
            /// before re-saving.
            ///
            /// Returns [`ExecError::Driver(sqlx::Error::RowNotFound)`]
            /// when the primary key no longer matches any row (e.g.
            /// the row was deleted concurrently).
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`]; also `RowNotFound` when
            /// the PK no longer exists.
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn refresh_from_db(
                &mut self,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<(), #root::sql::ExecError> {
                use #root::sql::FetcherPool as _;
                let _pk_val: #root::core::SqlValue = ::core::convert::Into::into(
                    ::core::clone::Clone::clone(&self.#pk_ident),
                );
                let mut _rows: ::std::vec::Vec<Self> =
                    #root::query::QuerySet::<Self>::default()
                        .filter(::core::stringify!(#pk_ident), _pk_val)
                        .limit(1)
                        .fetch(pool)
                        .await?;
                match _rows.into_iter().next() {
                    ::core::option::Option::Some(_fresh) => {
                        *self = _fresh;
                        ::core::result::Result::Ok(())
                    }
                    ::core::option::Option::None => ::core::result::Result::Err(
                        #root::sql::ExecError::Driver(
                            #root::sql::sqlx::Error::RowNotFound,
                        ),
                    ),
                }
            }

            /// Atomically increment the integer column `col` by
            /// `by` for this row. Equivalent to
            /// `UPDATE <table> SET <col> = <col> + $1 WHERE <pk> = $2`.
            ///
            /// **Doesn't mutate `self`** — the in-memory copy is now
            /// stale; call [`Self::refresh_from_db`] /
            /// [`Self::fresh`] to re-sync. Returns the rows-
            /// affected count (0 when the PK doesn't match any row,
            /// 1 on success).
            ///
            /// `col` is the Rust field name as a string; unknown
            /// fields surface as `UnknownField` at runtime. Negative
            /// `by` values atomically decrement (see also
            /// [`Self::decrement`]).
            ///
            /// # Errors
            /// As [`UpdaterPool::execute_pool`].
            ///
            /// [`UpdaterPool::execute_pool`]: rustango::sql::UpdaterPool::execute_pool
            pub async fn increment(
                &self,
                col: &str,
                by: i64,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                Self::__increment_one(self, col, by, pool).await
            }

            /// Sibling of [`Self::increment`] — atomically
            /// decrement this row's `col` by `by`. Eloquent
            /// `$model->decrement($col, $by)` parity. Equivalent to
            /// `self.increment(col, -by, &pool)`; the separate name
            /// keeps call sites readable.
            ///
            /// # Errors
            /// As [`Self::increment`].
            pub async fn decrement(
                &self,
                col: &str,
                by: i64,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                Self::__increment_one(self, col, -by, pool).await
            }

            /// Bulk-increment: add `by` to `col` on every row of the
            /// table. Eloquent `Model::query()->increment($col, $by)`
            /// parity. Use for counters, score adjustments, view
            /// rollups.
            ///
            /// # Errors
            /// As [`UpdaterPool::execute_pool`].
            ///
            /// [`UpdaterPool::execute_pool`]: rustango::sql::UpdaterPool::execute_pool
            pub async fn increment_each(
                col: &str,
                by: i64,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                Self::__increment_all(col, by, pool).await
            }

            /// Sibling of [`Self::increment_each`] — bulk-decrement.
            ///
            /// # Errors
            /// As [`Self::increment_each`].
            pub async fn decrement_each(
                col: &str,
                by: i64,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                Self::__increment_all(col, -by, pool).await
            }

            /// Internal: forward to
            /// [`#root::sql::model_shortcuts::increment_one_pool`].
            /// One-line wrapper kept as a per-Model method so the
            /// macro's emitted `increment` / `decrement` instance
            /// calls don't have to thread `Self` through manually.
            #[doc(hidden)]
            pub async fn __increment_one(
                this: &Self,
                col: &str,
                by: i64,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                let _pk_val: #root::core::SqlValue = ::core::convert::Into::into(
                    ::core::clone::Clone::clone(&this.#pk_ident),
                );
                #root::sql::model_shortcuts::increment_one_pool::<Self>(
                    ::core::stringify!(#pk_ident),
                    _pk_val,
                    col,
                    by,
                    pool,
                )
                .await
            }

            /// Internal: run
            /// [`#root::sql::model_shortcuts::increment_all_query`].
            #[doc(hidden)]
            pub async fn __increment_all(
                col: &str,
                by: i64,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                let _query =
                    #root::sql::model_shortcuts::increment_all_query::<Self>(col, by)?;
                #bulk_update_run
            }

            /// Internal: forward to
            /// [`#root::sql::model_shortcuts::resolve_col`].
            #[doc(hidden)]
            pub fn __resolve_col(
                col: &str,
            ) -> ::core::result::Result<&'static str, #root::sql::ExecError> {
                #root::sql::model_shortcuts::resolve_col::<Self>(col)
            }

            /// Internal: forward to
            /// [`#root::sql::model_shortcuts::add_signed_expr`].
            #[doc(hidden)]
            #[must_use]
            pub fn __add_signed_expr(
                col_static: &'static str,
                signed_by: i64,
            ) -> #root::core::Expr {
                #root::sql::model_shortcuts::add_signed_expr(col_static, signed_by)
            }

            /// Re-SELECT this row by its primary key and return a
            /// **new** instance with the freshly-fetched fields.
            /// Eloquent `Model::fresh()` parity — non-mutating
            /// counterpart of [`Self::refresh_from_db`].
            ///
            /// Returns `Ok(None)` when the row was deleted
            /// concurrently — vs [`Self::refresh_from_db`]
            /// which surfaces that as `RowNotFound` because
            /// in-place mutation has nothing to write to.
            ///
            /// Useful when you want to compare the in-memory
            /// instance against the persisted state (audit-style
            /// diffs, conflict detection) without mutating the
            /// reference you already hold.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn fresh(
                &self,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::core::option::Option<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _pk_val: #root::core::SqlValue = ::core::convert::Into::into(
                    ::core::clone::Clone::clone(&self.#pk_ident),
                );
                let _rows: ::std::vec::Vec<Self> =
                    #root::query::QuerySet::<Self>::default()
                        .filter(::core::stringify!(#pk_ident), _pk_val)
                        .limit(1)
                        .fetch(pool)
                        .await?;
                ::core::result::Result::Ok(_rows.into_iter().next())
            }

            #replicate_doc
            #[must_use]
            pub fn replicate(&self) -> Self {
                Self {
                    #pk_clone_token,
                    #( #other_field_clones, )*
                }
            }

            #first_method

            #last_method

            /// Throwing counterpart of [`Self::first`] —
            /// errors with `RowNotFound` when the table is empty.
            /// Eloquent `Model::firstOrFail()` parity.
            ///
            /// # Errors
            /// As [`Self::first`]; additionally
            /// [`sqlx::Error::RowNotFound`] on empty tables.
            ///
            /// [`sqlx::Error::RowNotFound`]: rustango::sql::sqlx::Error::RowNotFound
            pub async fn first_or_fail(
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<Self, #root::sql::ExecError> {
                // Route through the queryset rather than `Self::first`,
                // which is suppressed on models with a field named
                // `first` (field/shortcut collision guard).
                match #root::query::QuerySet::<Self>::default().first(pool).await? {
                    ::core::option::Option::Some(_row) => ::core::result::Result::Ok(_row),
                    ::core::option::Option::None => ::core::result::Result::Err(
                        #root::sql::ExecError::Driver(
                            #root::sql::sqlx::Error::RowNotFound,
                        ),
                    ),
                }
            }

            /// Single-column projection — `SELECT <col> FROM
            /// <table>`. Returns `Vec<U>` where each element is the
            /// decoded value of the column. Eloquent
            /// `Model::pluck($column)` parity.
            ///
            /// Thin wrapper over `QuerySet::<Self>::default()
            /// .values_list_flat(col).fetch::<U>(pool)`. `U` is a
            /// `FlatScalar`; use `Option<_>` for a nullable column.
            ///
            /// # Errors
            /// As `ValuesFlatQuerySet::fetch`.
            pub async fn pluck<U>(
                col: &'static str,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<::std::vec::Vec<U>, #root::sql::ExecError>
            where
                U: #root::sql::FlatScalar,
            {
                #root::query::QuerySet::<Self>::default()
                    .values_list_flat(col)
                    .fetch::<U>(pool)
                    .await
            }

            /// Eloquent `Model::chunk($n, fn ($chunk) { ... })` —
            /// stream every row of this model in batches of `n`,
            /// invoking the callback once per batch. Stable PK-ASC
            /// ordering so the LIMIT/OFFSET pagination is
            /// deterministic across drivers.
            ///
            /// The callback is async — it can do further DB work
            /// (writes, related-row lookups, queue dispatch) per
            /// batch. Return `Err(...)` from the callback to abort
            /// the iteration early; the error bubbles up.
            ///
            /// **When to use**: bulk processing flows that can't
            /// fit the whole table in memory — sending newsletters,
            /// running data migrations, computing summary
            /// statistics. For small / known-bounded tables, plain
            /// `Self::all(&pool)` is simpler.
            ///
            /// **Caveat**: ascending OFFSET pagination is O(N²) on
            /// large tables. For multi-million-row scans prefer
            /// keyset-by-PK (the standard "WHERE id > last_seen"
            /// shape) over `chunk(...)`.
            ///
            /// Skipped on models without a primary key — chunking
            /// needs a stable order to avoid skipping / repeating
            /// rows across batches.
            pub async fn chunk<F, Fut>(
                n: i64,
                pool: &#root::sql::Pool,
                mut cb: F,
            ) -> ::core::result::Result<(), #root::sql::ExecError>
            where
                F: ::core::ops::FnMut(::std::vec::Vec<Self>) -> Fut,
                Fut: ::core::future::Future<
                    Output = ::core::result::Result<(), #root::sql::ExecError>,
                >,
            {
                use #root::sql::FetcherPool as _;
                let pk_col = match Self::primary_key_column() {
                    ::core::option::Option::Some(c) => c,
                    ::core::option::Option::None => {
                        return ::core::result::Result::Ok(());
                    }
                };
                let mut offset: i64 = 0;
                loop {
                    let rows: ::std::vec::Vec<Self> =
                        #root::query::QuerySet::<Self>::default()
                            .order_by(&[(pk_col, false)])
                            .limit(n)
                            .offset(offset)
                            .fetch(pool)
                            .await?;
                    if rows.is_empty() {
                        return ::core::result::Result::Ok(());
                    }
                    let len = rows.len() as i64;
                    cb(rows).await?;
                    if len < n {
                        return ::core::result::Result::Ok(());
                    }
                    offset += n;
                }
            }

            /// Eloquent `Model::chunkById($n, fn (...))` — same
            /// per-batch callback shape as [`Self::chunk`], but uses
            /// **keyset pagination** (`WHERE pk > last_seen LIMIT n`)
            /// instead of OFFSET. O(N) total scan vs OFFSET's O(N²)
            /// — the right choice for multi-million-row sweeps.
            ///
            /// Requires the primary key to be a signed integer type
            /// (`i64` / `i32`); the keyset comparison rides on
            /// `__rustango_pk_value()` lowering through
            /// `SqlValue::I64` / `SqlValue::I32`. Skipped on
            /// non-integer PKs (UUID, String) — those should use
            /// the OFFSET-shaped [`Self::chunk`] or a hand-rolled
            /// keyset loop.
            ///
            /// Callback errors abort iteration; the error bubbles up
            /// unchanged. Empty table → callback invoked zero times.
            pub async fn chunk_by_id<F, Fut>(
                n: i64,
                pool: &#root::sql::Pool,
                mut cb: F,
            ) -> ::core::result::Result<(), #root::sql::ExecError>
            where
                F: ::core::ops::FnMut(::std::vec::Vec<Self>) -> Fut,
                Fut: ::core::future::Future<
                    Output = ::core::result::Result<(), #root::sql::ExecError>,
                >,
            {
                use #root::sql::FetcherPool as _;
                let pk_col = match Self::primary_key_column() {
                    ::core::option::Option::Some(c) => c,
                    ::core::option::Option::None => {
                        return ::core::result::Result::Ok(());
                    }
                };
                // Track the largest PK seen so the next batch picks
                // up from there. `i64::MIN` as the sentinel — the
                // very first iteration's `> MIN` matches every row,
                // so the loop entry is uniform with subsequent
                // iterations.
                let mut last_seen: i64 = i64::MIN;
                loop {
                    let key = ::std::format!("{}__gt", pk_col);
                    let rows: ::std::vec::Vec<Self> =
                        #root::query::QuerySet::<Self>::default()
                            .filter(key.as_str(), last_seen)
                            .order_by(&[(pk_col, false)])
                            .limit(n)
                            .fetch(pool)
                            .await?;
                    if rows.is_empty() {
                        return ::core::result::Result::Ok(());
                    }
                    let len = rows.len() as i64;
                    // Capture the last row's PK BEFORE moving rows
                    // into the callback.
                    let max_pk = match rows
                        .last()
                        .map(|r| r.__rustango_pk_value())
                    {
                        ::core::option::Option::Some(
                            #root::core::SqlValue::I64(v),
                        ) => v,
                        ::core::option::Option::Some(
                            #root::core::SqlValue::I32(v),
                        ) => i64::from(v),
                        _ => return ::core::result::Result::Ok(()),
                    };
                    cb(rows).await?;
                    if len < n {
                        return ::core::result::Result::Ok(());
                    }
                    last_seen = max_pk;
                }
            }

            /// Eloquent `Model::each(fn ($row) { ... }, $n)` —
            /// per-row callback companion to [`Self::chunk`].
            /// Streams every row in keyset-paginated batches of
            /// `batch` size, calling `cb` once per row.
            ///
            /// Inherits the keyset-paginated scan of
            /// [`Self::chunk_by_id`] (O(N) total, integer PK only —
            /// non-integer PKs are silently a no-op).
            ///
            /// ```ignore
            /// Post::each(500, &pool, |p| async move {
            ///     reindex(p).await?;
            ///     Ok(())
            /// }).await?;
            /// ```
            ///
            /// Return `Err(...)` from the callback to abort
            /// iteration; the error bubbles up unchanged.
            pub async fn each<F, Fut>(
                batch: i64,
                pool: &#root::sql::Pool,
                mut cb: F,
            ) -> ::core::result::Result<(), #root::sql::ExecError>
            where
                F: ::core::ops::FnMut(Self) -> Fut,
                Fut: ::core::future::Future<
                    Output = ::core::result::Result<(), #root::sql::ExecError>,
                >,
            {
                use #root::sql::FetcherPool as _;
                let pk_col = match Self::primary_key_column() {
                    ::core::option::Option::Some(c) => c,
                    ::core::option::Option::None => {
                        return ::core::result::Result::Ok(());
                    }
                };
                let mut last_seen: i64 = i64::MIN;
                loop {
                    let key = ::std::format!("{}__gt", pk_col);
                    let rows: ::std::vec::Vec<Self> =
                        #root::query::QuerySet::<Self>::default()
                            .filter(key.as_str(), last_seen)
                            .order_by(&[(pk_col, false)])
                            .limit(batch)
                            .fetch(pool)
                            .await?;
                    if rows.is_empty() {
                        return ::core::result::Result::Ok(());
                    }
                    let len = rows.len() as i64;
                    let max_pk = match rows
                        .last()
                        .map(|r| r.__rustango_pk_value())
                    {
                        ::core::option::Option::Some(
                            #root::core::SqlValue::I64(v),
                        ) => v,
                        ::core::option::Option::Some(
                            #root::core::SqlValue::I32(v),
                        ) => i64::from(v),
                        _ => return ::core::result::Result::Ok(()),
                    };
                    for row in rows {
                        cb(row).await?;
                    }
                    if len < batch {
                        return ::core::result::Result::Ok(());
                    }
                    last_seen = max_pk;
                }
            }

            /// Delete every row of this model — `TRUNCATE TABLE
            /// <table> RESTART IDENTITY CASCADE` on Postgres,
            /// `DELETE FROM <table>` on MySQL / SQLite (which don't
            /// support `TRUNCATE` inside foreign-key constraints
            /// or — for SQLite — at all). Eloquent `Model::truncate()`
            /// parity.
            ///
            /// **Use only in tests / fixture-reset flows.** Production
            /// writes through this would silently bypass the
            /// `pre_delete` / `post_delete` signals (no per-row hooks
            /// fire on a TRUNCATE / bulk DELETE FROM). An audited model
            /// gets one bulk audit entry, not one per row. Global scopes
            /// do not apply: every row goes, generic M2M links too.
            ///
            /// # Errors
            /// As [`truncate`].
            ///
            /// [`truncate`]: rustango::sql::truncate
            pub async fn truncate(
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                #truncate_run
            }

            /// Bulk-delete every row whose primary key is in
            /// `pks` — `DELETE FROM <table> WHERE <pk> IN (...)`.
            /// Returns the affected row count.
            ///
            /// Eloquent `Model::destroy([1, 2, 3])` parity.
            /// Empty `pks` is a no-op (returns 0).
            ///
            /// Accepts any iterable whose elements are
            /// `Into<SqlValue>` — `Vec<i64>`, `&[i64]`,
            /// `[i64; N]`, etc.
            ///
            /// # Errors
            /// As `delete_pool`.
            pub async fn destroy<V>(
                pks: impl ::core::iter::IntoIterator<Item = V>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<u64, #root::sql::ExecError>
            where
                V: ::core::convert::Into<#root::core::SqlValue>,
            {
                let _values: ::std::vec::Vec<#root::core::SqlValue> =
                    pks.into_iter().map(::core::convert::Into::into).collect();
                if _values.is_empty() {
                    return ::core::result::Result::Ok(0);
                }
                let _pk = <Self as #root::core::Model>::SCHEMA
                    .primary_key()
                    .ok_or_else(|| {
                        #root::sql::ExecError::Sql(#root::sql::SqlError::MissingPrimaryKey)
                    })?;
                let _query = #root::query::QuerySet::<Self>::default()
                    .filter_op(
                        _pk.name,
                        #root::core::Op::In,
                        #root::core::SqlValue::List(_values),
                    )
                    .compile_delete()?;
                #bulk_delete_run
            }

            /// Fetch every row where `<col> = <val>`. Eloquent
            /// `Model::where($col, $val)->get()` parity.
            ///
            /// Thin wrapper over `QuerySet::<Self>::default()
            /// .filter(col, val).fetch(pool)`. For one row,
            /// use [`Self::first_where`]; for a chain that
            /// needs further `.filter()` / `.order_by()` /
            /// `.limit()`, drop down to `Self::query().filter(...)`
            /// directly.
            ///
            /// `val` accepts any value `Into<SqlValue>` so plain
            /// strings, ints, UUIDs, etc. all work.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_(
                col: &str,
                val: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                #root::query::QuerySet::<Self>::default()
                    .filter(col, val)
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `<col> IN (vals)`. Eloquent
            /// `Model::whereIn($col, $vals)->get()` parity. Empty
            /// `vals` returns no rows (matches SQL's empty-IN
            /// semantics).
            ///
            /// `vals` accepts any iterable whose items are
            /// `Into<SqlValue>` — `Vec<i64>`, `&[&str]`, `[Uuid; N]`,
            /// etc.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_in<V>(
                col: &str,
                vals: impl ::core::iter::IntoIterator<Item = V>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            >
            where
                V: ::core::convert::Into<#root::core::SqlValue>,
            {
                use #root::sql::FetcherPool as _;
                let _values: ::std::vec::Vec<#root::core::SqlValue> =
                    vals.into_iter().map(::core::convert::Into::into).collect();
                if _values.is_empty() {
                    return ::core::result::Result::Ok(::std::vec::Vec::new());
                }
                let _key = ::std::format!("{}__in", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, #root::core::SqlValue::List(_values))
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `<col> NOT IN (vals)`. Eloquent
            /// `Model::whereNotIn($col, $vals)->get()` parity. Empty
            /// `vals` returns every row (matches SQL's empty-NOT-IN
            /// semantics — vacuously true for every row).
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_not_in<V>(
                col: &str,
                vals: impl ::core::iter::IntoIterator<Item = V>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            >
            where
                V: ::core::convert::Into<#root::core::SqlValue>,
            {
                use #root::sql::FetcherPool as _;
                let _values: ::std::vec::Vec<#root::core::SqlValue> =
                    vals.into_iter().map(::core::convert::Into::into).collect();
                if _values.is_empty() {
                    return #root::query::QuerySet::<Self>::default()
                        .fetch(pool)
                        .await;
                }
                let _key = ::std::format!("{}__not_in", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, #root::core::SqlValue::List(_values))
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `<col> IS NULL`. Eloquent
            /// `Model::whereNull($col)->get()` parity.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_null(
                col: &str,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__isnull", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, #root::core::SqlValue::Bool(true))
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `<col> IS NOT NULL`. Eloquent
            /// `Model::whereNotNull($col)->get()` parity.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_not_null(
                col: &str,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__isnull", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, #root::core::SqlValue::Bool(false))
                    .fetch(pool)
                    .await
            }

            /// Fetch up to `n` rows in random order. Eloquent
            /// `Model::inRandomOrder()->limit($n)->get()` /
            /// `Model::query()->inRandomOrder()->get()->take($n)`
            /// parity. **Performance caveat**: random ordering
            /// forces a full table scan + per-row random key sort;
            /// the optimizer cannot use an index. Prefer a
            /// `pk >= rand_offset LIMIT N` walk for huge tables.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn random_n(
                n: i64,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                #root::query::QuerySet::<Self>::default()
                    .order_random()
                    .limit(n)
                    .fetch(pool)
                    .await
            }

            /// Fetch one row in random order. Eloquent
            /// `Model::inRandomOrder()->first()` parity. Same
            /// performance caveat as [`Self::random_n`].
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn random(
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::core::option::Option<Self>,
                #root::sql::ExecError,
            > {
                ::core::result::Result::Ok(
                    Self::random_n(1, pool).await?.into_iter().next(),
                )
            }

            /// Fetch every row ordered ASC by `field`. Eloquent
            /// `Model::oldest($field)->get()` parity — the multi-row
            /// counterpart of [`Self::earliest`].
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn oldest(
                field: &str,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                #root::query::QuerySet::<Self>::default()
                    .order_by(&[(field, false)])
                    .fetch(pool)
                    .await
            }

            /// Fetch every row ordered DESC by `field`. Eloquent
            /// `Model::latest($field)->get()` parity — the multi-row
            /// counterpart of [`Self::latest`].
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn newest(
                field: &str,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                #root::query::QuerySet::<Self>::default()
                    .order_by(&[(field, true)])
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `EXTRACT(YEAR FROM <col>) = year`.
            /// Eloquent `Model::whereYear($col, $year)->get()` parity.
            /// Routes through the existing `__year` lookup suffix
            /// (issue #829).
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_year(
                col: &str,
                year: i64,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__year", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, #root::core::SqlValue::I64(year))
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `EXTRACT(MONTH FROM <col>) = month`.
            /// Eloquent `Model::whereMonth($col, $m)->get()` parity.
            /// `month` is 1–12.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_month(
                col: &str,
                month: i64,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__month", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, #root::core::SqlValue::I64(month))
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `EXTRACT(DAY FROM <col>) = day`.
            /// Eloquent `Model::whereDay($col, $d)->get()` parity.
            /// `day` is 1–31.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_day(
                col: &str,
                day: i64,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__day", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, #root::core::SqlValue::I64(day))
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `EXTRACT(HOUR FROM <col>) = hour`.
            /// Eloquent `Model::whereHour($col, $h)->get()` parity.
            /// `hour` is 0–23.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_hour(
                col: &str,
                hour: i64,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__hour", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, #root::core::SqlValue::I64(hour))
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `EXTRACT(MINUTE FROM <col>) = minute`.
            /// Eloquent `Model::whereMinute($col, $m)->get()` parity.
            /// `minute` is 0–59.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_minute(
                col: &str,
                minute: i64,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__minute", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, #root::core::SqlValue::I64(minute))
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `<col> LIKE <pattern>` —
            /// caller-supplied pattern (must include `%` / `_`
            /// wildcards manually). Eloquent `Model::whereLike`
            /// parity.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_like(
                col: &str,
                pattern: impl ::core::convert::Into<::std::string::String>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__like", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(
                        &_key,
                        #root::core::SqlValue::String(pattern.into()),
                    )
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `<col> ILIKE <pattern>` —
            /// case-insensitive LIKE (PG native, MySQL/SQLite
            /// emulated via `LOWER(col) LIKE LOWER(pattern)`).
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_ilike(
                col: &str,
                pattern: impl ::core::convert::Into<::std::string::String>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__ilike", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(
                        &_key,
                        #root::core::SqlValue::String(pattern.into()),
                    )
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `<col>` starts with `prefix`
            /// (auto-appends `%`). Eloquent
            /// `whereLike("col", "$prefix%")` parity.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_starts_with(
                col: &str,
                prefix: impl ::core::convert::Into<::std::string::String>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__startswith", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(
                        &_key,
                        #root::core::SqlValue::String(prefix.into()),
                    )
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `<col>` ends with `suffix`
            /// (auto-prepends `%`). Eloquent
            /// `whereLike("col", "%$suffix")` parity.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_ends_with(
                col: &str,
                suffix: impl ::core::convert::Into<::std::string::String>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__endswith", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(
                        &_key,
                        #root::core::SqlValue::String(suffix.into()),
                    )
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `<col>` contains `substr`
            /// (auto-wraps with `%`).
            /// Eloquent `whereLike("col", "%$substr%")` parity.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_contains(
                col: &str,
                substr: impl ::core::convert::Into<::std::string::String>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__contains", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(
                        &_key,
                        #root::core::SqlValue::String(substr.into()),
                    )
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `<col> > val`. Eloquent
            /// `Model::where($col, ">", $val)->get()` parity.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_gt(
                col: &str,
                val: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__gt", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, val)
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `<col> >= val`. Eloquent
            /// `Model::where($col, ">=", $val)->get()` parity.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_gte(
                col: &str,
                val: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__gte", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, val)
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `<col> < val`. Eloquent
            /// `Model::where($col, "<", $val)->get()` parity.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_lt(
                col: &str,
                val: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__lt", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, val)
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `<col> <= val`. Eloquent
            /// `Model::where($col, "<=", $val)->get()` parity.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_lte(
                col: &str,
                val: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__lte", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, val)
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `<col> <> val`. Eloquent
            /// `Model::where($col, "!=", $val)->get()` parity.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_ne(
                col: &str,
                val: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__ne", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, val)
                    .fetch(pool)
                    .await
            }

            /// Fetch every row matching `<col> = val` for ANY of the
            /// listed columns. Eloquent `Model::whereAny($cols, $val)`
            /// parity. Empty `cols` returns no rows.
            ///
            /// Resolves each `&str` column to its SCHEMA-registered
            /// `&'static str` once and builds a single OR-composed
            /// `Q` expression (`col1 = ? OR col2 = ? OR …`).
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`]; `QueryError::UnknownField`
            /// when any column is not declared on the model.
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_any(
                cols: &[&str],
                val: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                Self::__where_multi(cols, val, false, pool).await
            }

            /// Fetch every row matching `<col> = val` for ALL listed
            /// columns. Eloquent `Model::whereAll($cols, $val)` parity.
            /// Empty `cols` returns every row (vacuous AND).
            ///
            /// # Errors
            /// As [`Self::where_any`].
            pub async fn where_all(
                cols: &[&str],
                val: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                Self::__where_multi(cols, val, true, pool).await
            }

            /// Internal: build a Q expression composing `cols` via
            /// AND (`all`) or OR (`!all`), then fetch. Backs
            /// `where_any` / `where_all`.
            #[doc(hidden)]
            pub async fn __where_multi(
                cols: &[&str],
                val: impl ::core::convert::Into<#root::core::SqlValue>,
                all: bool,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                #root::sql::model_shortcuts::where_multi_pool::<Self>(cols, val, all, pool)
                    .await
            }

            /// Fetch up to `n` rows. Eloquent `Model::take($n)->get()`
            /// parity. PK-ordered
            /// is NOT guaranteed without an explicit `order_by` —
            /// drop into `Self::query()` for that.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn take(
                n: i64,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                #root::query::QuerySet::<Self>::default()
                    .limit(n)
                    .fetch(pool)
                    .await
            }

            /// Fetch the page-th window of `per_page` rows
            /// (1-indexed). Eloquent
            /// `Model::query()->forPage($page, $perPage)->get()`
            /// parity. The DB scans an `OFFSET (page - 1) * per_page
            /// LIMIT per_page`; for large offsets this is O(N) —
            /// prefer keyset pagination via PK on hot paths.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn for_page(
                page: i64,
                per_page: i64,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _offset = #root::list_params::page_offset(page, per_page);
                #root::query::QuerySet::<Self>::default()
                    .limit(per_page)
                    .offset(_offset)
                    .fetch(pool)
                    .await
            }

            /// Eloquent `Model::paginate($per_page, $page)` — fetch
            /// one page of rows AND the total row count in one
            /// call. Returns `(rows, total)`. Two queries: a
            /// LIMIT/OFFSET SELECT for the page + a `SELECT COUNT(*)`
            /// for the total.
            ///
            /// Useful for paginated UIs that need both the visible
            /// rows AND a "Page X of Y" / total-count widget. For
            /// large tables prefer keyset pagination + cached count;
            /// every call to `paginate` re-counts the full table.
            ///
            /// Same 1-indexed `page` convention as [`Self::for_page`].
            ///
            /// # Errors
            /// As [`Self::for_page`] and [`Self::count`].
            pub async fn paginate(
                page: i64,
                per_page: i64,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                (::std::vec::Vec<Self>, i64),
                #root::sql::ExecError,
            > {
                // Route through the queryset rather than `Self::count`:
                // the `count` inherent method is suppressed on models
                // that declare a field named `count` (field/shortcut
                // collision guard), and `paginate` must still compile
                // for those models.
                let total = {
                    use #root::sql::CounterPool as _;
                    #root::query::QuerySet::<Self>::default()
                        .count(pool)
                        .await?
                };
                let rows = Self::for_page(page, per_page, pool).await?;
                ::core::result::Result::Ok((rows, total))
            }

            /// Bulk-update — set `set_col = set_val` on every row
            /// matching `where_col = where_val`. Returns affected row
            /// count. Eloquent
            /// `Model::where($where_col, $where_val)->update([$set_col => $set_val])`
            /// parity.
            ///
            /// For multi-column updates drop into the queryset
            /// builder: `Self::query().filter(...).update().set(...).set(...).execute_pool(&pool)`.
            ///
            /// # Errors
            /// As [`UpdaterPool::execute_pool`].
            ///
            /// [`UpdaterPool::execute_pool`]: rustango::sql::UpdaterPool::execute_pool
            pub async fn update_where(
                where_col: &str,
                where_val: impl ::core::convert::Into<#root::core::SqlValue>,
                set_col: &str,
                set_val: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                let _query = #root::query::QuerySet::<Self>::default()
                    .filter(where_col, where_val)
                    .update()
                    .set(set_col, set_val)
                    .compile()?;
                #bulk_update_run
            }

            /// Bulk-delete — remove every row matching
            /// `where_col = where_val`. Returns affected row count.
            /// Eloquent
            /// `Model::where($where_col, $where_val)->delete()` parity.
            ///
            /// # Errors
            /// As [`#root::sql::delete_pool`].
            pub async fn delete_where(
                where_col: &str,
                where_val: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                let _query = #root::query::QuerySet::<Self>::default()
                    .filter_op(where_col, #root::core::Op::Eq, where_val)
                    .compile_delete()?;
                #bulk_delete_run
            }

            /// Bulk-update — set `set_col = set_val` on EVERY row of
            /// this model's table. **No WHERE clause** — use with
            /// care. Eloquent `Model::query()->update([$col => $val])`
            /// parity.
            ///
            /// Use for backfills, one-shot reset flows, etc. The
            /// returned count is rows affected.
            ///
            /// # Errors
            /// As [`UpdaterPool::execute_pool`].
            ///
            /// [`UpdaterPool::execute_pool`]: rustango::sql::UpdaterPool::execute_pool
            pub async fn update_all(
                set_col: &str,
                set_val: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                let _query = #root::query::QuerySet::<Self>::default()
                    .update()
                    .set(set_col, set_val)
                    .compile()?;
                #bulk_update_run
            }

            /// Fetch every row where `<col> NOT LIKE <pattern>`.
            /// Eloquent `Model::whereNotLike` parity. Pattern is
            /// passed verbatim — caller controls `%` / `_`.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_not_like(
                col: &str,
                pattern: impl ::core::convert::Into<::std::string::String>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__not_like", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(
                        &_key,
                        #root::core::SqlValue::String(pattern.into()),
                    )
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `<col> NOT ILIKE <pattern>` —
            /// case-insensitive `NOT LIKE` (PG native, MySQL /
            /// SQLite emulated via `LOWER(col) NOT LIKE LOWER(pattern)`).
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_not_ilike(
                col: &str,
                pattern: impl ::core::convert::Into<::std::string::String>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__not_ilike", col);
                #root::query::QuerySet::<Self>::default()
                    .filter(
                        &_key,
                        #root::core::SqlValue::String(pattern.into()),
                    )
                    .fetch(pool)
                    .await
            }

            /// Fetch every row where `<col> NOT BETWEEN lo AND hi`.
            /// Eloquent `Model::whereNotBetween($col, [$lo, $hi])`
            /// parity.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_not_between(
                col: &str,
                lo: impl ::core::convert::Into<#root::core::SqlValue>,
                hi: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__not_between", col);
                let _vals = #root::core::SqlValue::List(::std::vec![
                    ::core::convert::Into::into(lo),
                    ::core::convert::Into::into(hi),
                ]);
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, _vals)
                    .fetch(pool)
                    .await
            }

            /// Returns the SQL table name for this model. Eloquent
            /// `$model->getTable()` parity.
            #[must_use]
            pub fn table_name() -> &'static str {
                <Self as #root::core::Model>::SCHEMA.table
            }

            /// Returns the SQL column name of this model's primary
            /// key, or `None` when the model has no
            /// `#[rustango(primary_key)]`. Eloquent
            /// `$model->getKeyName()` parity.
            #[must_use]
            pub fn primary_key_column() -> ::core::option::Option<&'static str> {
                <Self as #root::core::Model>::SCHEMA
                    .primary_key()
                    .map(|f| f.column)
            }

            /// Fetch every row where `<col> BETWEEN lo AND hi`
            /// (inclusive on both ends — same as SQL). Eloquent
            /// `Model::whereBetween($col, [$lo, $hi])->get()` parity.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn where_between(
                col: &str,
                lo: impl ::core::convert::Into<#root::core::SqlValue>,
                hi: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            > {
                use #root::sql::FetcherPool as _;
                let _key = ::std::format!("{}__between", col);
                let _vals = #root::core::SqlValue::List(::std::vec![
                    ::core::convert::Into::into(lo),
                    ::core::convert::Into::into(hi),
                ]);
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, _vals)
                    .fetch(pool)
                    .await
            }

            /// Fetch the first row where `<col> = <val>`. Returns
            /// `Ok(None)` when no row matches. Eloquent
            /// `Model::firstWhere($col, $val)` parity.
            ///
            /// Thin wrapper over `QuerySet::<Self>::default()
            /// .filter(col, val).first(pool)`. Use this when you
            /// want one row identified by a non-PK column (e.g.
            /// `User::first_where_pool("email", "x@y.com", &pool)`).
            ///
            /// `val` accepts any value `Into<SqlValue>` so plain
            /// strings, ints, UUIDs, etc. all work.
            ///
            /// # Errors
            /// As `QuerySet::first`.
            pub async fn first_where(
                col: &str,
                val: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::core::option::Option<Self>,
                #root::sql::ExecError,
            > {
                #root::query::QuerySet::<Self>::default()
                    .filter(col, val)
                    .first(pool)
                    .await
            }

            #value_method

            /// Fetch the row with the largest `field` value —
            /// `SELECT … ORDER BY <field> DESC LIMIT 1`. Returns
            /// `Ok(None)` for an empty table. Eloquent
            /// `Model::latest($field)->first()` parity.
            /// Thin wrapper over `QuerySet::<Self>::default()
            /// .latest(field, pool)`.
            ///
            /// **Field name** is the Rust field ident as a string
            /// (not the SQL column). It is a runtime `&str`, so an
            /// unknown one compiles and surfaces as
            /// `ExecError::Query(QueryError::UnknownField)` when the
            /// query runs.
            ///
            /// # Errors
            /// As `QuerySet::latest`.
            pub async fn latest(
                field: &str,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::core::option::Option<Self>,
                #root::sql::ExecError,
            > {
                #root::query::QuerySet::<Self>::default()
                    .latest(field, pool)
                    .await
            }

            /// Sibling of [`Self::latest`] — fetches the row
            /// with the smallest `field` value (`ORDER BY <field>
            /// ASC LIMIT 1`). Eloquent `Model::oldest($field)
            /// ->first()` parity.
            ///
            /// # Errors
            /// As [`Self::latest`].
            pub async fn earliest(
                field: &str,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::core::option::Option<Self>,
                #root::sql::ExecError,
            > {
                #root::query::QuerySet::<Self>::default()
                    .earliest(field, pool)
                    .await
            }

            #count_method

            /// `true` when the table contains at least one row.
            /// Eloquent `Model::query()->exists()` parity. Thin wrapper
            /// over `QuerySet::<Self>::default().exists(pool)`.
            ///
            /// # Errors
            /// As [`ExistsPool::exists`].
            ///
            /// [`ExistsPool::exists`]: rustango::sql::ExistsPool::exists
            pub async fn exists(
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<bool, #root::sql::ExecError> {
                use #root::sql::ExistsPool as _;
                #root::query::QuerySet::<Self>::default()
                    .exists(pool)
                    .await
            }

            /// Inverse of [`Self::exists`] — returns `true` when
            /// the table has zero rows. Eloquent
            /// `Model::doesntExist()` parity.
            ///
            /// # Errors
            /// As [`Self::exists`].
            pub async fn doesnt_exist(
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<bool, #root::sql::ExecError> {
                Self::exists(pool).await.map(|e| !e)
            }

            /// Eloquent `Model::query()->whereKey($pk)->exists()` —
            /// `true` when a row with primary key `pk` exists in
            /// the table. Sugar over
            /// `QuerySet::<Self>::default().contains_pk(pool, pk)`.
            ///
            /// Differs from [`Self::exists`] (which checks "any row
            /// in the table") by checking a specific PK existence.
            /// Cheaper than `Self::find(pk, &pool).await?.is_some()`
            /// because the row is never materialized — the SQL is
            /// `SELECT COUNT(*) > 0 FROM <table> WHERE pk = ?`.
            ///
            /// # Errors
            /// As [`#root::sql::ExistsPool::contains_pk`].
            pub async fn contains_pk(
                pk: impl ::core::convert::Into<#root::core::SqlValue> + ::core::marker::Send,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<bool, #root::sql::ExecError> {
                use #root::sql::ExistsPool as _;
                #root::query::QuerySet::<Self>::default()
                    .contains_pk(pool, pk)
                    .await
            }

            #sum_method
            #avg_method
            #min_method
            #max_method

            /// Fetch every row of this model from `pool`. Eloquent
            /// `Model::all()` parity — a thin wrapper over
            /// `QuerySet::<Self>::default().fetch(pool)`.
            ///
            /// **Use with care on large tables** — there's no
            /// pagination or limit; the entire table is materialized
            /// into memory. For anything beyond fixture / lookup
            /// tables, page through `QuerySet::<Self>::default()
            /// .order_by(...).limit(N).offset(M).fetch(pool)`
            /// or stream via `.iterator(chunk_size)`.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn all(
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<::std::vec::Vec<Self>, #root::sql::ExecError>
            {
                use #root::sql::FetcherPool as _;
                #root::query::QuerySet::<Self>::default()
                    .fetch(pool)
                    .await
            }

            /// Look up every row whose primary key is in `pks`.
            /// Returns the matching rows in **inventory** order — NOT
            /// the order of `pks`. Empty `pks` returns an empty
            /// `Vec`. Eloquent `Model::find([1, 2, 3])` (when called
            /// with a list) parity.
            ///
            /// Thin wrapper over `QuerySet::<Self>::default()
            /// .filter("<pk>__in", SqlValue::List([...])).fetch(pool)`.
            /// Caller-supplied PKs that don't match a row are
            /// silently skipped (the returned vec is shorter than
            /// the input list). For an order-preserving / "fail
            /// when any missing" variant, build the queryset
            /// explicitly with `in_bulk` instead.
            ///
            /// Accepts any iterable whose elements are
            /// `Into<SqlValue>` — `Vec<i64>`, `&[i64]`, `[i64; N]`,
            /// `Vec<Uuid>`, etc.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn find_many<V>(
                pks: impl ::core::iter::IntoIterator<Item = V>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            >
            where
                V: ::core::convert::Into<#root::core::SqlValue>,
            {
                use #root::sql::FetcherPool as _;
                let _values: ::std::vec::Vec<#root::core::SqlValue> =
                    pks.into_iter().map(::core::convert::Into::into).collect();
                if _values.is_empty() {
                    return ::core::result::Result::Ok(::std::vec::Vec::new());
                }
                let _key = ::std::format!("{}__in", ::core::stringify!(#pk_ident));
                #root::query::QuerySet::<Self>::default()
                    .filter(&_key, #root::core::SqlValue::List(_values))
                    .fetch(pool)
                    .await
            }

            /// Look up the row whose primary key equals `pk`. Returns
            /// `Ok(None)` when no row matches, rather than erroring.
            /// Eloquent `Model::find`
            /// shape — accepts any value `Into<SqlValue>`.
            ///
            /// One-liner shortcut for the common
            /// `QuerySet::<Self>::default().filter("<pk_field>", pk)
            /// .limit(1).fetch(pool).await?.into_iter().next()`
            /// dance.
            ///
            /// # Errors
            /// As [`FetcherPool::fetch`].
            ///
            /// [`FetcherPool::fetch`]: rustango::sql::FetcherPool::fetch
            pub async fn find(
                pk: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<::core::option::Option<Self>, #root::sql::ExecError>
            {
                use #root::sql::FetcherPool as _;
                let _pk_val: #root::core::SqlValue = pk.into();
                let mut _rows: ::std::vec::Vec<Self> =
                    #root::query::QuerySet::<Self>::default()
                        .filter(::core::stringify!(#pk_ident), _pk_val)
                        .limit(1)
                        .fetch(pool)
                        .await?;
                ::core::result::Result::Ok(_rows.into_iter().next())
            }

            /// Look up the row whose primary key equals `pk`. Errors
            /// when no row matches — the throwing counterpart of
            /// [`Self::find`]. Eloquent `Model::findOrFail`
            /// parity.
            ///
            /// Translates the miss into
            /// [`ExecError::Driver`]\([`sqlx::Error::RowNotFound`])\)
            /// so callers can `?`-bubble straight through the typical
            /// `ExecError` error chain.
            ///
            /// # Errors
            /// As [`Self::find`]; additionally
            /// [`sqlx::Error::RowNotFound`] when no row matches.
            ///
            /// [`ExecError::Driver`]: rustango::sql::ExecError::Driver
            /// [`sqlx::Error::RowNotFound`]: rustango::sql::sqlx::Error::RowNotFound
            pub async fn find_or_fail(
                pk: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<Self, #root::sql::ExecError> {
                match Self::find(pk, pool).await? {
                    ::core::option::Option::Some(_row) => ::core::result::Result::Ok(_row),
                    ::core::option::Option::None => ::core::result::Result::Err(
                        #root::sql::ExecError::Driver(
                            #root::sql::sqlx::Error::RowNotFound,
                        ),
                    ),
                }
            }

            /// Look up multiple rows by primary key, **failing** if
            /// any requested PK is missing. Eloquent
            /// `Model::findOrFail([1, 2, 3])` parity. Returns rows in
            /// inventory order (NOT request order — same as
            /// [`Self::find_many`]).
            ///
            /// Empty `pks` returns an empty `Vec` (no rows requested
            /// → nothing to fail on).
            ///
            /// Differs from [`Self::find_many`] in that this method
            /// requires every PK to resolve. If even one is missing,
            /// the call surfaces `sqlx::Error::RowNotFound` (wrapped
            /// in `ExecError::Driver`). Rows are deduped at the SQL
            /// layer, so passing the same PK twice in `pks` counts as
            /// one expected row.
            ///
            /// # Errors
            /// As [`Self::find_many`], plus `RowNotFound` when the
            /// returned row count is less than the count of distinct
            /// requested PKs.
            pub async fn find_many_or_fail<V>(
                pks: impl ::core::iter::IntoIterator<Item = V>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<
                ::std::vec::Vec<Self>,
                #root::sql::ExecError,
            >
            where
                V: ::core::convert::Into<#root::core::SqlValue>,
            {
                let _values: ::std::vec::Vec<#root::core::SqlValue> =
                    pks.into_iter().map(::core::convert::Into::into).collect();
                if _values.is_empty() {
                    return ::core::result::Result::Ok(::std::vec::Vec::new());
                }
                // Dedup the requested PK list before counting so
                // duplicate-PK requests don't false-fail (the SQL
                // `IN (...)` clause naturally dedups too).
                let mut _seen: ::std::collections::HashSet<
                    ::std::string::String,
                > = ::std::collections::HashSet::new();
                for v in &_values {
                    _seen.insert(v.to_display_string());
                }
                let _expected = _seen.len();
                let _rows = Self::find_many(_values, pool).await?;
                if _rows.len() < _expected {
                    return ::core::result::Result::Err(
                        #root::sql::ExecError::Driver(
                            #root::sql::sqlx::Error::RowNotFound,
                        ),
                    );
                }
                ::core::result::Result::Ok(_rows)
            }

            /// Find by primary key or run `fallback` to produce a
            /// default row to return. Eloquent
            /// `Model::findOr($pk, fn() => …)` parity.
            ///
            /// Unlike [`Self::find_or_fail`] (which raises on
            /// miss), this is the "give me something sensible"
            /// branch: typical use is "fetch the user's row, else
            /// fall back to an anonymous/guest stub".
            ///
            /// `fallback` runs only when no row matches — the DB
            /// round-trip happens unconditionally.
            ///
            /// # Errors
            /// As [`Self::find`].
            pub async fn find_or<F>(
                pk: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
                fallback: F,
            ) -> ::core::result::Result<Self, #root::sql::ExecError>
            where
                F: ::core::ops::FnOnce() -> Self,
            {
                ::core::result::Result::Ok(
                    Self::find(pk, pool).await?.unwrap_or_else(fallback),
                )
            }

            /// Same as [`Self::find_or`] but also returns a `bool`
            /// indicating whether the row was found in the DB
            /// (`true`) or freshly built from `fallback` (`false`).
            /// Eloquent `Model::findOrNew($pk, [attrs])` parity —
            /// in PHP the returned model also exposes `->exists`;
            /// here that's surfaced as the second tuple element.
            ///
            /// Useful for edit-or-create form handlers where the
            /// caller needs to know whether to PATCH or POST when
            /// the user submits the form.
            ///
            /// # Errors
            /// As [`Self::find`].
            pub async fn find_or_new<F>(
                pk: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
                fallback: F,
            ) -> ::core::result::Result<(Self, bool), #root::sql::ExecError>
            where
                F: ::core::ops::FnOnce() -> Self,
            {
                match Self::find(pk, pool).await? {
                    ::core::option::Option::Some(_row) => ::core::result::Result::Ok((_row, true)),
                    ::core::option::Option::None => {
                        ::core::result::Result::Ok((fallback(), false))
                    }
                }
            }

            /// Eloquent `Model::findOrCreate(pk, defaults)` — like
            /// [`Self::find_or_new`] but **persists** the new row
            /// when the PK isn't found. Returns `(row, exists: bool)`
            /// — `exists=true` when the PK was found,
            /// `false` when a fresh row was inserted.
            ///
            /// ```ignore
            /// let (post, found) = Post::find_or_insert(
            ///     pk,
            ///     &pool,
            ///     || Post { id: Auto::default(), title: "new".into() },
            /// ).await?;
            /// // `found` true → returned existing row;
            /// // `found` false → fallback was inserted, `post.id` populated.
            /// ```
            ///
            /// **Caveat**: two concurrent calls that both miss the
            /// find can both INSERT, violating uniqueness. Wrap in a
            /// transaction or rely on a UNIQUE constraint + handle
            /// the conflict error if you need race-free semantics.
            ///
            /// # Errors
            /// As [`Self::find`] and [`Self::save_pool`].
            pub async fn find_or_insert<F>(
                pk: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
                fallback: F,
            ) -> ::core::result::Result<(Self, bool), #root::sql::ExecError>
            where
                F: ::core::ops::FnOnce() -> Self,
            {
                if let ::core::option::Option::Some(_row) = Self::find(pk, pool).await? {
                    return ::core::result::Result::Ok((_row, true));
                }
                let mut _new = fallback();
                _new.save_pool(pool).await?;
                ::core::result::Result::Ok((_new, false))
            }

            /// Fetch the first row of the table, or run `fallback`
            /// when the table is empty. Eloquent
            /// `Model::firstOr(fn() => …)` parity.
            ///
            /// # Errors
            /// As [`Self::first`].
            pub async fn first_or<F>(
                pool: &#root::sql::Pool,
                fallback: F,
            ) -> ::core::result::Result<Self, #root::sql::ExecError>
            where
                F: ::core::ops::FnOnce() -> Self,
            {
                // Route through the queryset rather than `Self::first`,
                // which is suppressed on models with a field named
                // `first` (field/shortcut collision guard).
                ::core::result::Result::Ok(
                    #root::query::QuerySet::<Self>::default()
                        .first(pool)
                        .await?
                        .unwrap_or_else(fallback),
                )
            }

            /// Fetch exactly one row matching `<col> = <val>`. Errors
            /// when zero rows match (`ExecError::Driver(RowNotFound)`)
            /// or more than one matches
            /// (`ExecError::Query(QueryError::Sql(MultipleRowsReturned))`).
            /// Eloquent `Model::sole($col, $val)` parity.
            ///
            /// # Errors
            /// As [`Self::where_`] plus the explicit
            /// `RowNotFound` / `MultipleRowsReturned` cases above.
            pub async fn sole(
                col: &str,
                val: impl ::core::convert::Into<#root::core::SqlValue>,
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<Self, #root::sql::ExecError> {
                let mut _rows = Self::where_(col, val, pool).await?;
                match _rows.len() {
                    0 => ::core::result::Result::Err(
                        #root::sql::ExecError::Driver(
                            #root::sql::sqlx::Error::RowNotFound,
                        ),
                    ),
                    1 => ::core::result::Result::Ok(_rows.remove(0)),
                    n => ::core::result::Result::Err(
                        #root::sql::ExecError::MultipleRowsReturned {
                            op: "sole",
                            table: <Self as #root::core::Model>::SCHEMA.name,
                            count: n,
                        },
                    ),
                }
            }
        }
    } else {
        quote!()
    };

    // `_tx` family — `insert_tx`, `save_tx`, `delete_tx`. These mirror
    // the non-audited `_pool` methods but execute against an open
    // `PoolTx` so the writes participate in the caller's transaction.
    // Auditing inside TX is deferred; these always use the plain
    // executor primitives regardless of whether the model is audited.
    let tx_insert_method = if fields.has_auto {
        let pushes = &fields.insert_pushes;
        let returning_cols = &fields.returning_cols;
        quote! {
            /// Insert this row inside an open transaction, populating
            /// any `Auto<T>` PK from the auto-assigned value. Works
            /// against any backend that `tx` wraps.
            ///
            /// # Errors
            /// As [`Self::insert_pool`].
            pub async fn insert_tx(
                &mut self,
                tx: &mut #root::sql::PoolTx<'_>,
            ) -> ::core::result::Result<(), #root::sql::ExecError> {
                let mut _columns: ::std::vec::Vec<&'static str> =
                    ::std::vec::Vec::new();
                let mut _values: ::std::vec::Vec<#root::core::SqlValue> =
                    ::std::vec::Vec::new();
                #( #pushes )*
                let _query = #root::core::InsertQuery::new(
                    <Self as #root::core::Model>::SCHEMA,
                    _columns,
                    _values,
                )
                .returning(::std::vec![ #( #returning_cols ),* ]);
                let _result = #root::sql::insert_returning_tx(tx, &_query).await?;
                #root::sql::apply_auto_pk(_result, self)
            }
        }
    } else {
        let insert_columns = &fields.insert_columns;
        let insert_values = &fields.insert_values;
        quote! {
            /// Insert this row inside an open transaction.
            ///
            /// # Errors
            /// As [`Self::insert_pool`].
            pub async fn insert_tx(
                &self,
                tx: &mut #root::sql::PoolTx<'_>,
            ) -> ::core::result::Result<(), #root::sql::ExecError> {
                let _query = #root::core::InsertQuery::new(
                    <Self as #root::core::Model>::SCHEMA,
                    ::std::vec![ #( #insert_columns ),* ],
                    ::std::vec![ #( #insert_values ),* ],
                );
                #root::sql::insert_tx(tx, &_query).await
            }
        }
    };

    let tx_save_method = if let Some((pk_ident, pk_col)) = primary_key {
        let pk_column_lit = pk_col.as_str();
        let assignments = &fields.update_assignments;
        let dispatch_unset = if fields.pk_is_auto {
            quote! {
                if matches!(self.#pk_ident, #root::sql::Auto::Unset) {
                    return self.insert_tx(tx).await.map(|()| 1u64);
                }
            }
        } else {
            quote!()
        };
        let write = restore_auto_now_unless(
            &fields.auto_now_idents,
            &save_ret,
            &save_keep,
            &quote! {
                let _query = #root::core::UpdateQuery::new(
                    <Self as #root::core::Model>::SCHEMA,
                    ::std::vec![ #( #assignments ),* ],
                    #root::core::WhereExpr::Predicate(#root::core::Filter::new(
                        #pk_column_lit,
                        #root::core::Op::Eq,
                        ::core::convert::Into::<#root::core::SqlValue>::into(
                            ::core::clone::Clone::clone(&self.#pk_ident)
                        ),
                    )),
                );
                let _affected = #root::sql::update_tx(tx, &_query).await?;
                ::core::result::Result::Ok(_affected)
            },
        );
        quote! {
            /// Save this row inside an open transaction. `INSERT` when
            /// the `Auto<T>` PK is `Unset`, else `UPDATE` keyed on the
            /// PK. Works against any backend that `tx` wraps.
            ///
            /// # Errors
            /// As [`Self::save_pool`].
            pub async fn save_tx(
                &mut self,
                tx: &mut #root::sql::PoolTx<'_>,
            ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                #dispatch_unset
                #write
            }
        }
    } else {
        quote!()
    };

    let tx_delete_method = {
        let pk_column_lit = primary_key.map(|(_, col)| col.as_str()).unwrap_or("id");
        let pk_ident_for_tx = primary_key.map(|(ident, _)| ident);
        if let Some(pk_ident) = pk_ident_for_tx {
            quote! {
                /// Delete the row identified by this instance's PK
                /// inside an open transaction. Works against any backend
                /// that `tx` wraps.
                ///
                /// # Errors
                /// As [`Self::delete_pool`].
                pub async fn delete_tx(
                    &self,
                    tx: &mut #root::sql::PoolTx<'_>,
                ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                    let _query = #root::core::DeleteQuery::by_pk(
                        <Self as #root::core::Model>::SCHEMA,
                        #pk_column_lit,
                        ::core::convert::Into::<#root::core::SqlValue>::into(
                            ::core::clone::Clone::clone(&self.#pk_ident)
                        ),
                    );
                    #root::sql::delete_tx(tx, &_query).await
                }
            }
        } else {
            quote!()
        }
    };

    // Update emission captures both BEFORE and AFTER state — runs an
    // extra SELECT against `_executor` BEFORE the UPDATE, captures
    // each tracked field's prior value, then after the UPDATE diffs
    // against the in-memory `&self`. `diff_changes` drops unchanged
    // columns so the JSON only contains the actual delta.
    //
    // Two-fragment shape: `audit_update_pre` runs before the UPDATE
    // and binds `_audit_before_pairs`; `audit_update_post` runs
    // after the UPDATE and emits the PendingEntry.
    let (audit_update_pre, audit_update_post): (TokenStream2, TokenStream2) = if let Some(tracked) =
        audited_fields
    {
        if tracked.is_empty() {
            (quote!(), quote!())
        } else {
            let tracked_cols: Vec<&str> = tracked.iter().map(|c| c.column.as_str()).collect();
            let pk_column_lit_for_select =
                primary_key.map(|(_, col)| col.clone()).unwrap_or_default();
            let pk_value_for_bind = if let Some((pk_ident, _)) = primary_key {
                if fields.pk_is_auto {
                    quote!(self.#pk_ident.get().copied().unwrap_or_default())
                } else {
                    quote!(::core::clone::Clone::clone(&self.#pk_ident))
                }
            } else {
                quote!(0_i64)
            };
            let before_pairs = tracked.iter().map(|c| {
                let column_lit = c.column.as_str();
                let value_ty = &c.value_ty;
                quote! {
                    (
                        #column_lit,
                        match #root::sql::sqlx::Row::try_get::<#value_ty, _>(
                            &_audit_before_row, #column_lit,
                        ) {
                            ::core::result::Result::Ok(v) => #root::core::__json_value(&v),
                            ::core::result::Result::Err(_) => #root::__serde_json::Value::Null,
                        },
                    )
                }
            });
            let pre = quote! {
                let _audit_before_query = #root::audit::before_image_query(
                    <Self as #root::core::Model>::SCHEMA,
                    #pk_column_lit_for_select,
                    ::core::convert::Into::<#root::core::SqlValue>::into(#pk_value_for_bind),
                    &[ #( #tracked_cols ),* ],
                );
                // A failed pre-read must not let the UPDATE run unaudited (#1907).
                let _audit_before_pairs:
                    ::std::option::Option<::std::vec::Vec<(&'static str, #root::__serde_json::Value)>> =
                    #root::sql::select_rows_on(&mut *_executor, &_audit_before_query)
                        .await?
                        .into_iter()
                        .next()
                        .map(|_audit_before_row| ::std::vec![ #( #before_pairs ),* ]);
            };
            let post = quote! {
                if let ::core::option::Option::Some(_audit_before) = _audit_before_pairs {
                    let _audit_after = self.__rustango_audit_pairs();
                    if let ::core::option::Option::Some(_audit_entry) =
                        #root::audit::PendingEntry::update_diff(
                            <Self as #root::core::Model>::SCHEMA.table,
                            self.__rustango_audit_pk(),
                            &_audit_before,
                            &_audit_after,
                        )
                    {
                        #root::audit::emit_one(&mut *_executor, &_audit_entry).await?;
                    }
                }
            };
            (pre, post)
        }
    } else {
        (quote!(), quote!())
    };

    // Bulk-insert audit: one `Create` entry per row once RETURNING has
    // set its PK, written in one batched INSERT.
    let audit_bulk_insert_emit: TokenStream2 = if audited_fields.is_some() {
        quote! {
            let _audit_entries: ::std::vec::Vec<#root::audit::PendingEntry> = rows
                .iter()
                .map(|_row| _row.__rustango_audit_entry(#root::audit::AuditOp::Create))
                .collect();
            #root::audit::emit_many(&mut *_executor, &_audit_entries).await?;
        }
    } else {
        quote!()
    };

    let save_method = if fields.pk_is_auto {
        let (pk_ident, pk_column) = primary_key.expect("pk_is_auto implies primary_key is Some");
        let pk_column_lit = pk_column.as_str();
        let assignments = &fields.update_assignments;
        let upsert_cols = &fields.upsert_update_columns;
        let upsert_pushes = &fields.insert_pushes;
        // Read before the pushes, which fill each unset id.
        let (gen_idents, gen_cols): (Vec<_>, Vec<_>) =
            fields.uuid_v7_fields.iter().cloned().unzip();
        let upsert_returning = &fields.returning_cols;
        let upsert_auto_assigns = &fields.auto_assigns;
        let auto_now_idents = &fields.auto_now_idents;
        // Conflict target: prefer the first declared `unique_together`
        // when it exists. Plain `Auto<T>` PKs are server-assigned via
        // `BIGSERIAL` and never collide on insert, so a PK-only target
        // would silently turn `upsert()` into "always-insert" for
        // surrogate-PK models with composite UNIQUE constraints — see
        // `RolePermission` / `UserRole` / `UserPermission` in the
        // tenancy permission engine. When no `unique_together` is
        // declared we keep the PK target (the original behaviour).
        let upsert_target_columns: Vec<String> =
            upsert_unique.map_or_else(|| vec![pk_column.clone()], <[String]>::to_vec);
        let upsert_target_lits = upsert_target_columns
            .iter()
            .map(String::as_str)
            .collect::<Vec<_>>();
        let conflict_clause = if fields.upsert_update_columns.is_empty() {
            quote!(#root::core::ConflictClause::DoNothing)
        } else {
            quote!(#root::core::ConflictClause::DoUpdate {
                target: ::std::vec![ #( #upsert_target_lits ),* ],
                update_columns: ::std::vec![ #( #upsert_cols ),* ],
            })
        };
        // Audited: the upsert reports whether it inserted or updated (#1795).
        let (upsert_run, audit_upsert_emit) = if audited_fields.is_some() {
            (
                quote! {
                    let (_returning_row_v, _audit_op) =
                        #root::audit::upsert_returning_on(&mut *_executor, &query).await?;
                },
                quote! {
                    let _audit_entry = self.__rustango_audit_entry(_audit_op);
                    #root::audit::emit_one(&mut *_executor, &_audit_entry).await?;
                },
            )
        } else {
            (
                quote! {
                    let _returning_row_v =
                        #root::sql::__macro_internals::insert_returning_on(_executor, &query)
                            .await?;
                },
                quote!(),
            )
        };
        let save_on_write = restore_auto_now_unless(
            auto_now_idents,
            &save_ret,
            &save_keep,
            &quote! {
                #audit_update_pre
                let _query = #root::core::UpdateQuery::new(
                    <Self as #root::core::Model>::SCHEMA,
                    ::std::vec![ #( #assignments ),* ],
                    #root::core::WhereExpr::Predicate(#root::core::Filter::new(
                        #pk_column_lit,
                        #root::core::Op::Eq,
                        ::core::convert::Into::<#root::core::SqlValue>::into(
                            ::core::clone::Clone::clone(&self.#pk_ident)
                        ),
                    )),
                );
                let _affected = #root::sql::__macro_internals::update_on(
                    #executor_passes_to_data_write,
                    &_query,
                ).await?;
                #audit_update_post
                ::core::result::Result::Ok(_affected)
            },
        );
        let upsert_write = restore_auto_now_unless(
            auto_now_idents,
            &quote!(::core::result::Result<(), #root::sql::ExecError>),
            &quote!(_saved.is_ok()),
            &quote! {
                // The UPDATE branch writes `auto_now` too, so stamp it like `save`.
                #( self.#auto_now_idents = #root::sql::Auto::Set(#root::__chrono::Utc::now()); )*
                #( #upsert_pushes )*
                let query = #root::core::InsertQuery::new(
                    <Self as #root::core::Model>::SCHEMA,
                    _columns,
                    _values,
                )
                .returning(::std::vec![ #( #upsert_returning ),* ])
                .on_conflict(#conflict_clause)
                .generated(_generated);
                #upsert_run
                let _returning_row = &_returning_row_v;
                #( #upsert_auto_assigns )*
                #audit_upsert_emit
                ::core::result::Result::Ok(())
            },
        );
        Some(quote! {
            /// Insert this row if its `Auto<T>` primary key is
            /// `Unset`, otherwise update the existing row matching the
            /// PK. The caller doesn't need to pick `insert` vs the
            /// bulk-update path manually.
            ///
            /// On the insert branch, populates the PK from `RETURNING`
            /// (same behavior as `insert`). On the update branch,
            /// writes every non-PK column back; if no row matches the
            /// PK, returns `Ok(())` silently.
            ///
            /// Only generated when the primary key is declared as
            /// `Auto<T>`. Models with a manually-managed PK must use
            /// `insert` or the QuerySet update builder.
            ///
            /// **Postgres only — prefer [`Self::save_pool`].** This takes a
            /// driver-specific `PgPool`, so it does not exist at all on a
            /// build without the `postgres` feature: selecting `sqlite`
            /// makes the method vanish rather than fail with anything that
            /// names the cause.
            ///
            /// [`Self::save_pool`] takes `rustango::sql::Pool` and works on
            /// all three backends. The naming is inverted — the short name
            /// is the narrow one — and that is tracked in #1293.
            ///
            /// # Errors
            /// Returns [`#root::sql::ExecError`] for SQL-writing
            /// or driver failures.
            #[cfg(feature = "postgres")]
            pub async fn save(
                &mut self,
                pool: &#root::sql::sqlx::PgPool,
            ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                #pool_to_save_on
            }

            /// Like [`Self::save`] but accepts any sqlx executor —
            /// `&PgPool`, `&mut PgConnection`, or a transaction. The
            /// escape hatch for tenant-scoped writes: schema-mode
            /// tenants share the registry pool but rely on a per-
            /// checkout `SET search_path`, so passing `&PgPool` would
            /// silently hit the wrong schema. Acquire a connection
            /// via `TenantPools::acquire(&org)` and pass `&mut *conn`.
            ///
            /// # Errors
            /// As [`Self::save`].
            #[cfg(feature = "postgres")]
            pub async fn save_on #executor_generics (
                &mut self,
                #executor_param,
            ) -> ::core::result::Result<u64, #root::sql::ExecError>
            #executor_where
            {
                // #1029 — INSERT writes exactly one row → 1; UPDATE returns
                // the rows-affected count (0 when the PK no longer exists).
                if matches!(self.#pk_ident, #root::sql::Auto::Unset) {
                    return self.insert_on(#executor_passes_to_data_write).await.map(|()| 1u64);
                }
                #save_on_write
            }

            /// Per-call override for the audit source. Runs
            /// [`Self::save_on`] inside an [`#root::audit::with_source`]
            /// scope so the resulting audit entry records `source`
            /// instead of the task-local default. Useful for seed
            /// scripts and one-off CLI tools that don't sit inside an
            /// admin handler. The override applies only to this call;
            /// no global state changes.
            ///
            /// # Errors
            /// As [`Self::save_on`].
            #[cfg(feature = "postgres")]
            pub async fn save_on_with #executor_generics (
                &mut self,
                #executor_param,
                source: #root::audit::AuditSource,
            ) -> ::core::result::Result<u64, #root::sql::ExecError>
            #executor_where
            {
                #root::audit::with_source(source, self.save_on(_executor)).await
            }

            /// Insert this row or update it in-place if the primary key already
            /// exists — single round-trip via `INSERT … ON CONFLICT (pk) DO UPDATE`.
            ///
            /// With `Auto::Unset` PK the server assigns a new key and no conflict
            /// can occur (equivalent to `insert`). With `Auto::Set` PK the row is
            /// inserted if absent or all non-PK columns are overwritten if present.
            ///
            /// # Errors
            /// As [`Self::insert_on`].
            #[cfg(feature = "postgres")]
            pub async fn upsert(
                &mut self,
                pool: &#root::sql::sqlx::PgPool,
            ) -> ::core::result::Result<(), #root::sql::ExecError> {
                #pool_to_upsert_on
            }

            /// Like [`Self::upsert`] but accepts any sqlx executor.
            /// See [`Self::save_on`] for tenancy-scoped rationale.
            ///
            /// # Errors
            /// As [`Self::upsert`].
            #[cfg(feature = "postgres")]
            pub async fn upsert_on #executor_generics (
                &mut self,
                #executor_param,
            ) -> ::core::result::Result<(), #root::sql::ExecError>
            #executor_where
            {
                let mut _columns: ::std::vec::Vec<&'static str> =
                    ::std::vec::Vec::new();
                let mut _values: ::std::vec::Vec<#root::core::SqlValue> =
                    ::std::vec::Vec::new();
                #[allow(unused_mut)]
                let mut _generated: ::std::vec::Vec<&'static str> = ::std::vec::Vec::new();
                #(
                    if matches!(&self.#gen_idents, #root::sql::Auto::Unset) {
                        _generated.push(#gen_cols);
                    }
                )*
                #upsert_write
            }
        })
    } else {
        None
    };

    let pk_methods = primary_key.map(|(pk_ident, pk_column)| {
        let pk_column_lit = pk_column.as_str();
        // Optional `soft_delete_on` / `restore_on` companions when the
        // model has a `#[rustango(soft_delete)]` column. They land
        // alongside the regular `delete_on` so callers have both
        // options — a hard delete (audit-tracked as a real DELETE) and
        // a logical delete (audit-tracked as an UPDATE setting the
        // deleted_at column to NOW()).
        let soft_delete_methods = if let Some(col) = fields.soft_delete_column.as_deref() {
            let col_lit = col;
            let sd_field_ident = fields
                .soft_delete_field_ident
                .clone()
                .expect("soft_delete_column without ident");
            quote! {
                /// Soft-delete this row by setting its
                /// `#[rustango(soft_delete)]` column to `NOW()`.
                /// The row stays in the table; query helpers can
                /// filter it out by checking the column for `IS NOT
                /// NULL`.
                ///
                /// # Errors
                /// As [`Self::delete`].
                #[cfg(feature = "postgres")]
                pub async fn soft_delete_on #executor_generics (
                    &self,
                    #executor_param,
                ) -> ::core::result::Result<u64, #root::sql::ExecError>
                #executor_where
                {
                    let _now = #root::__chrono::Utc::now();
                    let _query = #root::soft_delete::__mark_query(
                        <Self as #root::core::Model>::SCHEMA,
                        #col_lit,
                        #pk_column_lit,
                        ::core::convert::Into::<#root::core::SqlValue>::into(
                            ::core::clone::Clone::clone(&self.#pk_ident)
                        ),
                        ::core::option::Option::Some(_now),
                    );
                    let _affected = #root::sql::__macro_internals::update_on(
                        #executor_passes_to_data_write,
                        &_query,
                    ).await?;
                    #audit_softdelete_emit
                    ::core::result::Result::Ok(_affected)
                }

                /// Inverse of [`Self::soft_delete_on`] — clears the
                /// soft-delete column back to NULL so the row is
                /// considered live again.
                ///
                /// # Errors
                /// As [`Self::delete`].
                #[cfg(feature = "postgres")]
                pub async fn restore_on #executor_generics (
                    &self,
                    #executor_param,
                ) -> ::core::result::Result<u64, #root::sql::ExecError>
                #executor_where
                {
                    let _query = #root::soft_delete::__mark_query(
                        <Self as #root::core::Model>::SCHEMA,
                        #col_lit,
                        #pk_column_lit,
                        ::core::convert::Into::<#root::core::SqlValue>::into(
                            ::core::clone::Clone::clone(&self.#pk_ident)
                        ),
                        ::core::option::Option::None,
                    );
                    let _affected = #root::sql::__macro_internals::update_on(
                        #executor_passes_to_data_write,
                        &_query,
                    ).await?;
                    #audit_restore_emit
                    ::core::result::Result::Ok(_affected)
                }

                /// Tri-dialect counterpart of [`Self::soft_delete_on`]
                /// — takes [`#root::sql::Pool`] and dispatches per
                /// backend. Eloquent `Model::delete()` semantics on
                /// soft-delete-enabled models (closes #821 partial).
                ///
                /// Sets the `#[rustango(soft_delete)]` column to
                /// `NOW()` on every backend. Query helpers
                /// (`QuerySet::active()` / `only_trashed()`,
                /// `soft_delete::active_filter` /
                /// `compose_with_active`) filter trashed rows out by
                /// reading `IS NULL` on the same column. Keyed on the PK;
                /// global scopes do not apply.
                ///
                /// # Errors
                /// As [`#root::sql::update_pool`].
                pub async fn soft_delete(
                    &self,
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                    let _now = #root::__chrono::Utc::now();
                    let _query = #root::soft_delete::__mark_query(
                        <Self as #root::core::Model>::SCHEMA,
                        #col_lit,
                        #pk_column_lit,
                        ::core::convert::Into::<#root::core::SqlValue>::into(
                            ::core::clone::Clone::clone(&self.#pk_ident)
                        ),
                        ::core::option::Option::Some(_now),
                    );
                    #pool_softdelete_run
                }

                /// Tri-dialect counterpart of [`Self::restore_on`].
                /// Clears the `#[rustango(soft_delete)]` column back
                /// to `NULL`, marking the row live again. Eloquent
                /// `Model::restore()` parity. Keyed on the PK; global
                /// scopes do not apply.
                ///
                /// # Errors
                /// As [`#root::sql::update_pool`].
                pub async fn restore(
                    &self,
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                    let _query = #root::soft_delete::__mark_query(
                        <Self as #root::core::Model>::SCHEMA,
                        #col_lit,
                        #pk_column_lit,
                        ::core::convert::Into::<#root::core::SqlValue>::into(
                            ::core::clone::Clone::clone(&self.#pk_ident)
                        ),
                        ::core::option::Option::None,
                    );
                    #pool_restore_run
                }

                /// Hard-delete this row, ignoring the soft-delete
                /// column. Eloquent `Model::forceDelete()` parity —
                /// the escape hatch when you need to actually purge
                /// data (GDPR, fixture cleanup, etc.).
                ///
                /// Equivalent to [`Self::delete_pool`] (the framework's
                /// non-soft delete) — exposed under the Eloquent name
                /// for muscle-memory + so soft-delete-enabled models
                /// have all three operations (soft / restore / force)
                /// in one place.
                ///
                /// # Errors
                /// As [`Self::delete_pool`].
                pub async fn force_delete(
                    &self,
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                    Self::delete_pool(self, pool).await
                }

                /// Returns `true` when this row is soft-deleted (its
                /// `#[rustango(soft_delete)]` column is currently
                /// set — Eloquent `$model->trashed()` parity).
                ///
                /// Pure in-memory predicate over `&self`; does not
                /// hit the database. Useful in admin/template code
                /// like `{% if post.trashed() %}…{% endif %}` and in
                /// guard clauses on restore/force-delete flows.
                pub fn trashed(&self) -> bool {
                    ::core::option::Option::is_some(&self.#sd_field_ident)
                }

                /// Fetch every row whose `#[rustango(soft_delete)]`
                /// column is `NULL` (a.k.a. the live, non-trashed
                /// rows). Eloquent's default `Model::all()` behavior on
                /// a soft-delete model (Eloquent auto-scopes trashed
                /// rows out; rustango doesn't have auto-scoping yet —
                /// see issue #820 — so this is the explicit shortcut).
                ///
                /// One-liner over `QuerySet::<Self>::default()
                /// .active().fetch(pool)`. Closes #821 partial.
                ///
                /// # Errors
                /// As [`#root::sql::FetcherPool::fetch`].
                pub async fn active(
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<
                    ::std::vec::Vec<Self>,
                    #root::sql::ExecError,
                > {
                    use #root::sql::FetcherPool as _;
                    #root::query::QuerySet::<Self>::default()
                        .active()
                        .fetch(pool)
                        .await
                }

                /// Fetch ONLY soft-deleted rows. Eloquent
                /// `Model::onlyTrashed()->get()` parity — drives the
                /// admin "Trash" page, restore flows, GDPR purge
                /// scans, etc.
                ///
                /// One-liner over `QuerySet::<Self>::default()
                /// .only_trashed().fetch(pool)`. Closes #821
                /// partial.
                ///
                /// # Errors
                /// As [`#root::sql::FetcherPool::fetch`].
                pub async fn only_trashed(
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<
                    ::std::vec::Vec<Self>,
                    #root::sql::ExecError,
                > {
                    use #root::sql::FetcherPool as _;
                    #root::query::QuerySet::<Self>::default()
                        .only_trashed()
                        .fetch(pool)
                        .await
                }

                /// Fetch every row, both live and soft-deleted.
                /// Eloquent `Model::withTrashed()->get()` parity.
                ///
                /// Today every queryset already includes trashed rows
                /// (rustango has no global-scope tracking yet — issue
                /// #820), so this is functionally equivalent to
                /// [`Self::all`]. Exposed as a named shortcut so
                /// soft-delete-aware code reads `Model::with_trashed_pool`
                /// rather than `Model::all_pool` — keeps intent visible
                /// in callers and stays correct when auto-scoping lands.
                ///
                /// Closes #821 partial.
                ///
                /// # Errors
                /// As [`#root::sql::FetcherPool::fetch`].
                pub async fn with_trashed(
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<
                    ::std::vec::Vec<Self>,
                    #root::sql::ExecError,
                > {
                    use #root::sql::FetcherPool as _;
                    #root::query::QuerySet::<Self>::default()
                        .with_trashed()
                        .fetch(pool)
                        .await
                }

            }
        } else {
            quote!()
        };
        quote! {
            /// Delete the row identified by this instance's primary key.
            ///
            /// Returns the number of rows affected (0 or 1).
            ///
            /// **Postgres only — prefer [`Self::delete_pool`].** This takes
            /// a driver-specific `PgPool`, so it does not exist on a build
            /// without the `postgres` feature. [`Self::delete_pool`] takes
            /// `rustango::sql::Pool` and works on all three. The naming is
            /// inverted; tracked in #1293.
            ///
            /// # Errors
            /// Returns [`#root::sql::ExecError`] for SQL-writing or
            /// driver failures.
            #[cfg(feature = "postgres")]
            pub async fn delete(
                &self,
                pool: &#root::sql::sqlx::PgPool,
            ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                #pool_to_delete_on
            }

            /// Like [`Self::delete`] but accepts any sqlx executor —
            /// for tenant-scoped deletes against an explicitly-acquired
            /// connection. See [`Self::save_on`] for the rationale.
            ///
            /// # Errors
            /// As [`Self::delete`].
            #[cfg(feature = "postgres")]
            pub async fn delete_on #executor_generics (
                &self,
                #executor_param,
            ) -> ::core::result::Result<u64, #root::sql::ExecError>
            #executor_where
            {
                let query = #root::core::DeleteQuery::by_pk(
                    <Self as #root::core::Model>::SCHEMA,
                    #pk_column_lit,
                    ::core::convert::Into::<#root::core::SqlValue>::into(
                        ::core::clone::Clone::clone(&self.#pk_ident)
                    ),
                );
                let _affected = #root::sql::__macro_internals::delete_on(
                    #executor_passes_to_data_write,
                    &query,
                ).await?;
                #audit_delete_emit
                ::core::result::Result::Ok(_affected)
            }

            /// Per-call audit-source override for [`Self::delete_on`].
            /// See [`Self::save_on_with`] for shape rationale.
            ///
            /// # Errors
            /// As [`Self::delete_on`].
            #[cfg(feature = "postgres")]
            pub async fn delete_on_with #executor_generics (
                &self,
                #executor_param,
                source: #root::audit::AuditSource,
            ) -> ::core::result::Result<u64, #root::sql::ExecError>
            #executor_where
            {
                #root::audit::with_source(source, self.delete_on(_executor)).await
            }
            #pool_delete_method
            #pool_insert_method
            #audit_entry_method
            #pool_save_method
            #refresh_replicate_methods
            #tx_delete_method
            #tx_insert_method
            #tx_save_method
            #soft_delete_methods

            /// Returns `true` when `other` represents the same DB
            /// row as `self` — i.e. their primary keys compare
            /// equal. Eloquent `$model->is($other)` parity.
            ///
            /// Because both arguments are typed `&Self`, the
            /// model/table check is automatic — `Post::is` cannot
            /// be invoked against a `Comment` at compile time. Only
            /// the PK has to be compared at runtime.
            pub fn is(&self, other: &Self) -> bool {
                self.#pk_ident == other.#pk_ident
            }

            /// Inverse of [`Self::is`]. Eloquent `$model->isNot($other)`
            /// parity.
            pub fn is_not(&self, other: &Self) -> bool {
                self.#pk_ident != other.#pk_ident
            }

            /// Returns this row's primary-key value as an
            /// [`#root::core::SqlValue`]. Eloquent
            /// `$model->getKey()` parity.
            ///
            /// Useful when you need to thread the PK through a
            /// generic `Into<SqlValue>`-bound API without knowing the
            /// concrete PK type (`i64` vs `Uuid` vs `String`).
            #[must_use]
            pub fn get_key(&self) -> #root::core::SqlValue {
                ::core::convert::Into::into(::core::clone::Clone::clone(&self.#pk_ident))
            }

        }
    });

    let insert_method = if fields.has_auto {
        let pushes = &fields.insert_pushes;
        let returning_cols = &fields.returning_cols;
        let auto_assigns = &fields.auto_assigns;
        quote! {
            /// Insert this row into its table. Skips columns whose
            /// `Auto<T>` value is `Unset` so Postgres' SERIAL/BIGSERIAL
            /// sequence fills them in, then reads each `Auto` column
            /// back via `RETURNING` and stores it on `self`.
            ///
            /// **Postgres only — prefer [`Self::insert_pool`].** This takes
            /// a driver-specific `PgPool`, so it does not exist on a build
            /// without the `postgres` feature. [`Self::insert_pool`] takes
            /// `rustango::sql::Pool` and works on all three. The naming is
            /// inverted; tracked in #1293.
            ///
            /// # Errors
            /// Returns [`#root::sql::ExecError`] for SQL-writing or
            /// driver failures.
            #[cfg(feature = "postgres")]
            pub async fn insert(
                &mut self,
                pool: &#root::sql::sqlx::PgPool,
            ) -> ::core::result::Result<(), #root::sql::ExecError> {
                #pool_to_insert_on
            }

            /// Like [`Self::insert`] but accepts any sqlx executor.
            /// See [`Self::save_on`] for tenancy-scoped rationale.
            ///
            /// # Errors
            /// As [`Self::insert`].
            #[cfg(feature = "postgres")]
            pub async fn insert_on #executor_generics (
                &mut self,
                #executor_param,
            ) -> ::core::result::Result<(), #root::sql::ExecError>
            #executor_where
            {
                let mut _columns: ::std::vec::Vec<&'static str> =
                    ::std::vec::Vec::new();
                let mut _values: ::std::vec::Vec<#root::core::SqlValue> =
                    ::std::vec::Vec::new();
                #( #pushes )*
                let query = #root::core::InsertQuery::new(
                    <Self as #root::core::Model>::SCHEMA,
                    _columns,
                    _values,
                )
                .returning(::std::vec![ #( #returning_cols ),* ]);
                let _returning_row_v = #root::sql::__macro_internals::insert_returning_on(
                    #executor_passes_to_data_write,
                    &query,
                ).await?;
                let _returning_row = &_returning_row_v;
                #( #auto_assigns )*
                #audit_insert_emit
                ::core::result::Result::Ok(())
            }

            /// Per-call audit-source override for [`Self::insert_on`].
            /// See [`Self::save_on_with`] for shape rationale.
            ///
            /// # Errors
            /// As [`Self::insert_on`].
            #[cfg(feature = "postgres")]
            pub async fn insert_on_with #executor_generics (
                &mut self,
                #executor_param,
                source: #root::audit::AuditSource,
            ) -> ::core::result::Result<(), #root::sql::ExecError>
            #executor_where
            {
                #root::audit::with_source(source, self.insert_on(_executor)).await
            }
        }
    } else {
        let insert_columns = &fields.insert_columns;
        let insert_values = &fields.insert_values;
        quote! {
            /// Insert this row into its table.
            ///
            /// # Errors
            /// Returns [`#root::sql::ExecError`] for SQL-writing or
            /// driver failures.
            #[cfg(feature = "postgres")]
            pub async fn insert(
                &self,
                pool: &#root::sql::sqlx::PgPool,
            ) -> ::core::result::Result<(), #root::sql::ExecError> {
                self.insert_on(pool).await
            }

            /// Like [`Self::insert`] but accepts any sqlx executor.
            /// See [`Self::save_on`] for tenancy-scoped rationale.
            ///
            /// # Errors
            /// As [`Self::insert`].
            #[cfg(feature = "postgres")]
            pub async fn insert_on<'_c, _E>(
                &self,
                _executor: _E,
            ) -> ::core::result::Result<(), #root::sql::ExecError>
            where
                _E: #root::sql::sqlx::Executor<'_c, Database = #root::sql::sqlx::Postgres>,
            {
                let query = #root::core::InsertQuery::new(
                    <Self as #root::core::Model>::SCHEMA,
                    ::std::vec![ #( #insert_columns ),* ],
                    ::std::vec![ #( #insert_values ),* ],
                );
                #root::sql::__macro_internals::insert_on(_executor, &query).await
            }
        }
    };

    let bulk_insert_method = if fields.has_auto {
        let cols_no_auto = &fields.bulk_columns_no_auto;
        let cols_all = &fields.bulk_columns_all;
        let pushes_no_auto = &fields.bulk_pushes_no_auto;
        let pushes_all = &fields.bulk_pushes_all;
        let returning_cols = &fields.returning_cols;
        let auto_assigns_for_row = bulk_auto_assigns_for_row(fields);
        let uniformity = &fields.bulk_auto_uniformity;
        let fill_in_place = &fields.bulk_fill_in_place;
        // Nothing to read back when every Auto field is filled Rust-side (#1934).
        let read_back = if fields.returning_cols.is_empty() {
            quote!()
        } else {
            quote! {
                if _returned.len() != rows.len() {
                    return ::core::result::Result::Err(
                        #root::sql::ExecError::Sql(
                            #root::sql::SqlError::BulkInsertReturningMismatch {
                                expected: rows.len(),
                                actual: _returned.len(),
                            }
                        )
                    );
                }
                for (_returning_row, _row_mut) in _returned.iter().zip(rows.iter_mut()) {
                    #auto_assigns_for_row
                }
            }
        };
        // The DB-filled `Auto` picks the path; Rust-filled ones fill per row (#1950).
        let first_auto_ident = fields
            .first_db_auto
            .as_ref()
            .map(|(ident, _)| ident)
            .or(fields.first_auto_ident.as_ref())
            .expect("has_auto implies first_auto_ident is Some");
        quote! {
            /// Bulk-insert `rows` in a single round-trip. Every row's
            /// `Auto<T>` PK fields must uniformly be `Auto::Unset`
            /// (sequence fills them in) or uniformly `Auto::Set(_)`
            /// (caller-supplied values). Mixed Set/Unset is rejected
            /// — call `insert` per row for that case.
            ///
            /// Empty slice is a no-op. Each row's `Auto` fields are
            /// populated from the `RETURNING` clause in input order
            /// before this returns.
            ///
            /// # Errors
            /// Returns [`#root::sql::ExecError`] for validation,
            /// SQL-writing, mixed-Auto rejection, or driver failures.
            #[cfg(feature = "postgres")]
            pub async fn bulk_insert(
                rows: &mut [Self],
                pool: &#root::sql::sqlx::PgPool,
            ) -> ::core::result::Result<(), #root::sql::ExecError> {
                #pool_to_bulk_insert_on
            }

            /// Like [`Self::bulk_insert`] but accepts any sqlx executor.
            /// See [`Self::save_on`] for tenancy-scoped rationale.
            ///
            /// # Errors
            /// As [`Self::bulk_insert`].
            #[cfg(feature = "postgres")]
            pub async fn bulk_insert_on #executor_generics (
                rows: &mut [Self],
                #executor_param,
            ) -> ::core::result::Result<(), #root::sql::ExecError>
            #executor_where
            {
                if rows.is_empty() {
                    return ::core::result::Result::Ok(());
                }
                let _first_unset = matches!(
                    rows[0].#first_auto_ident,
                    #root::sql::Auto::Unset
                );
                #( #uniformity )*
                for _row in rows.iter_mut() {
                    #( #fill_in_place )*
                }

                let mut _all_rows: ::std::vec::Vec<
                    ::std::vec::Vec<#root::core::SqlValue>,
                > = ::std::vec::Vec::with_capacity(rows.len());
                let _columns: ::std::vec::Vec<&'static str> = if _first_unset {
                    for _row in rows.iter() {
                        let mut _row_vals: ::std::vec::Vec<#root::core::SqlValue> =
                            ::std::vec::Vec::new();
                        #( #pushes_no_auto )*
                        _all_rows.push(_row_vals);
                    }
                    ::std::vec![ #( #cols_no_auto ),* ]
                } else {
                    for _row in rows.iter() {
                        let mut _row_vals: ::std::vec::Vec<#root::core::SqlValue> =
                            ::std::vec::Vec::new();
                        #( #pushes_all )*
                        _all_rows.push(_row_vals);
                    }
                    ::std::vec![ #( #cols_all ),* ]
                };

                let _query = #root::core::BulkInsertQuery::new(
                    <Self as #root::core::Model>::SCHEMA,
                    _columns,
                    _all_rows,
                )
                .returning(::std::vec![ #( #returning_cols ),* ]);
                let _returned = #root::sql::__macro_internals::bulk_insert_on(
                    #executor_passes_to_data_write,
                    &_query,
                ).await?;
                #read_back
                #audit_bulk_insert_emit
                ::core::result::Result::Ok(())
            }
        }
    } else {
        let cols_all = &fields.bulk_columns_all;
        let pushes_all = &fields.bulk_pushes_all;
        quote! {
            /// Bulk-insert `rows` in a single round-trip. Every row's
            /// fields are written verbatim — there are no `Auto<T>`
            /// fields on this model.
            ///
            /// Empty slice is a no-op.
            ///
            /// # Errors
            /// Returns [`#root::sql::ExecError`] for validation,
            /// SQL-writing, or driver failures.
            #[cfg(feature = "postgres")]
            pub async fn bulk_insert(
                rows: &[Self],
                pool: &#root::sql::sqlx::PgPool,
            ) -> ::core::result::Result<(), #root::sql::ExecError> {
                #pool_to_bulk_insert_on
            }

            /// Like [`Self::bulk_insert`] but accepts any sqlx executor.
            /// See [`Self::save_on`] for tenancy-scoped rationale.
            ///
            /// # Errors
            /// As [`Self::bulk_insert`].
            #[cfg(feature = "postgres")]
            pub async fn bulk_insert_on #executor_generics (
                rows: &[Self],
                #executor_param,
            ) -> ::core::result::Result<(), #root::sql::ExecError>
            #executor_where
            {
                if rows.is_empty() {
                    return ::core::result::Result::Ok(());
                }
                let mut _all_rows: ::std::vec::Vec<
                    ::std::vec::Vec<#root::core::SqlValue>,
                > = ::std::vec::Vec::with_capacity(rows.len());
                for _row in rows.iter() {
                    let mut _row_vals: ::std::vec::Vec<#root::core::SqlValue> =
                        ::std::vec::Vec::new();
                    #( #pushes_all )*
                    _all_rows.push(_row_vals);
                }
                let _query = #root::core::BulkInsertQuery::new(
                    <Self as #root::core::Model>::SCHEMA,
                    ::std::vec![ #( #cols_all ),* ],
                    _all_rows,
                );
                let _ = #root::sql::__macro_internals::bulk_insert_on(
                    #executor_passes_to_data_write,
                    &_query,
                ).await?;
                #audit_bulk_insert_emit
                ::core::result::Result::Ok(())
            }
        }
    };

    // Tri-dialect `bulk_upsert_pool` — issue #267 / T1.5. Always emitted
    // (no postgres-feature gate); routes through the existing
    // `bulk_insert_pool` + per-dialect conflict writer.
    //
    // Auto<T> PKs are required to be `Auto::Unset` for every row so the
    // sequence picks the PK for fresh inserts; the UPDATE branch never
    // touches the Auto column.
    // Audited models audit each written row; MySQL, with no RETURNING,
    // is refused there (#1747, #1795).
    let run_conflict_bulk_insert = match (audited_fields.is_some(), primary_key.is_some()) {
        (false, _) => quote!(#root::sql::bulk_insert_pool(pool, &_query).await),
        (true, true) => quote! {
            #root::audit::bulk_insert_with_audit::<Self>(pool, &_query, |_r: &Self, _op| {
                _r.__rustango_audit_entry(_op)
            })
            .await
        },
        (true, false) => quote! {
            ::core::result::Result::Err(#root::sql::ExecError::MissingPrimaryKey {
                table: <Self as #root::core::Model>::SCHEMA.table,
            })
        },
    };
    let bulk_upsert_pool_method = {
        let (gen_idents, gen_cols): (Vec<_>, Vec<_>) =
            fields.uuid_v7_fields.iter().cloned().unzip();
        // Pick the "no Auto" columns when the model has Auto fields,
        // else every column.
        let (upsert_cols, upsert_pushes): (Vec<_>, Vec<_>) = if fields.has_auto {
            (
                fields.bulk_columns_no_auto.clone(),
                fields.bulk_pushes_no_auto.clone(),
            )
        } else {
            (
                fields.bulk_columns_all.clone(),
                fields.bulk_pushes_all.clone(),
            )
        };
        quote! {
            /// Tri-dialect bulk insert that updates on conflict — the
            /// "import a batch idempotently" shape. Issue #267 / T1.5.
            ///
            /// Per-row values are extracted and lowered into a
            /// [`#root::core::BulkInsertQuery`] with
            /// `on_conflict = DoUpdate { target, update_columns }`. The
            /// writer dispatches per-dialect:
            /// * Postgres / SQLite: `INSERT … ON CONFLICT (target) DO UPDATE SET col = EXCLUDED.col`
            /// * MySQL: `INSERT … ON DUPLICATE KEY UPDATE col = VALUES(col)`; refused when
            ///   `target` is not the only unique key, since MySQL matches every UNIQUE index
            ///
            /// `target` names the column(s) whose unique constraint
            /// defines the conflict (typically a `unique` or
            /// `unique_together` natural-key column, NOT the `Auto<T>`
            /// PK). `update_cols` names the columns to overwrite on
            /// conflict — every other column is left untouched on the
            /// existing row.
            ///
            /// Auto-PK rows must all have `Auto::Unset` (the sequence
            /// picks the PK on insert; the update path never touches
            /// the Auto column). Auto-set rows trigger a hard error.
            /// Empty slice is a no-op. On an audited model each written
            /// row gets a `create` or `update` audit row; MySQL refuses it.
            ///
            /// # Errors
            /// Returns [`#root::sql::ExecError`] for validation,
            /// SQL-writing, or driver failures.
            pub async fn bulk_upsert_pool(
                rows: &[Self],
                target: &[&'static str],
                update_cols: &[&'static str],
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<(), #root::sql::ExecError> {
                if rows.is_empty() {
                    return ::core::result::Result::Ok(());
                }
                let mut _all_rows: ::std::vec::Vec<
                    ::std::vec::Vec<#root::core::SqlValue>,
                > = ::std::vec::Vec::with_capacity(rows.len());
                for _row in rows.iter() {
                    let mut _row_vals: ::std::vec::Vec<#root::core::SqlValue> =
                        ::std::vec::Vec::new();
                    #( #upsert_pushes )*
                    _all_rows.push(_row_vals);
                }
                #[allow(unused_mut)]
                let mut _generated: ::std::vec::Vec<&'static str> = ::std::vec::Vec::new();
                #(
                    if rows.iter().all(|_r| matches!(&_r.#gen_idents, #root::sql::Auto::Unset)) {
                        _generated.push(#gen_cols);
                    }
                )*
                let _query = #root::core::BulkInsertQuery::new(
                    <Self as #root::core::Model>::SCHEMA,
                    ::std::vec![ #( #upsert_cols ),* ],
                    _all_rows,
                )
                .on_conflict_do_update(target, update_cols)
                .generated(_generated);
                #run_conflict_bulk_insert
            }

            /// Tri-dialect `bulk_create(ignore_conflicts=True)` — silently
            /// skip rows that would violate a unique constraint. Issue
            /// #267 / T1.5. Same per-dialect dispatch as
            /// [`Self::bulk_upsert_pool`] but with `ON CONFLICT … DO
            /// NOTHING` (Postgres / SQLite) / `ON DUPLICATE KEY UPDATE
            /// <pivot> = <pivot>` (MySQL no-op write).
            ///
            /// # Errors
            /// As [`Self::bulk_upsert_pool`].
            pub async fn bulk_insert_or_ignore_pool(
                rows: &[Self],
                pool: &#root::sql::Pool,
            ) -> ::core::result::Result<(), #root::sql::ExecError> {
                if rows.is_empty() {
                    return ::core::result::Result::Ok(());
                }
                let mut _all_rows: ::std::vec::Vec<
                    ::std::vec::Vec<#root::core::SqlValue>,
                > = ::std::vec::Vec::with_capacity(rows.len());
                for _row in rows.iter() {
                    let mut _row_vals: ::std::vec::Vec<#root::core::SqlValue> =
                        ::std::vec::Vec::new();
                    #( #upsert_pushes )*
                    _all_rows.push(_row_vals);
                }
                let _query = #root::core::BulkInsertQuery::new(
                    <Self as #root::core::Model>::SCHEMA,
                    ::std::vec![ #( #upsert_cols ),* ],
                    _all_rows,
                )
                .on_conflict_do_nothing();
                #run_conflict_bulk_insert
            }
        }
    };

    // Ergonomic `Model::bulk_update(objs, fields)`.
    // The SQL/IR/executor stack
    // (`BulkUpdateQuery` + `bulk_update_pool` + the per-dialect
    // `write_bulk_update_*` writers) already existed; what was missing
    // was the per-model constructor that maps `&[Self]` + a runtime
    // column list into rows of `[pk, col_vals…]` so callers don't
    // hand-build the IR. Emitted only when the model has a primary key
    // (the PK is the join key and can't itself be updated).
    let bulk_update_rows_run = if audited_fields.is_some() {
        quote!(#root::audit::bulk_update_with_audit::<Self>(pool, &_query, |_r: &Self| {
            _r.__rustango_audit_entry(#root::audit::AuditOp::Update)
        })
        .await)
    } else {
        quote!(#root::sql::bulk_update_pool(pool, &_query).await)
    };
    let bulk_update_method = match &fields.primary_key {
        None => quote! {},
        Some((pk_ident, pk_col)) => {
            // One pair of match arms per non-PK column: a validation arm
            // resolving the runtime name to its `&'static str` column,
            // and a value arm pushing that field off the row.
            let mut col_arms: Vec<TokenStream2> = Vec::new();
            let mut val_arms: Vec<TokenStream2> = Vec::new();
            for entry in &fields.column_entries {
                if &entry.column == pk_col {
                    continue;
                }
                let col = &entry.column;
                let ident = &entry.ident;
                col_arms.push(quote! { #col => #col, });
                val_arms.push(quote! {
                    #col => _row_vals.push(
                        ::core::convert::Into::<#root::core::SqlValue>::into(
                            ::core::clone::Clone::clone(&_o.#ident)
                        )
                    ),
                });
            }
            quote! {
                /// Write per-row-different values for the named `fields`
                /// across every object in `objs`, matched by primary key.
                /// Past the backend's bind cap the rows go in batches inside
                /// one transaction, so the update is all or none.
                ///
                /// `fields` names the **columns** to update. The primary
                /// key identifies each row and cannot itself be updated
                /// (pass it and you get
                /// [`#root::core::QueryError::BulkUpdatePrimaryKey`]).
                /// Empty `objs` or `fields` is a no-op returning `0`.
                /// Objects whose PK matches no row are simply not updated.
                /// Returns the number of rows affected.
                ///
                /// Tri-dialect: lowers to a
                /// [`#root::core::BulkUpdateQuery`] and dispatches
                /// per-backend — `UPDATE … FROM (VALUES …)` on Postgres,
                /// a CTE + correlated subquery on SQLite, an inner
                /// `JOIN (VALUES …)` on MySQL.
                ///
                /// # Errors
                /// [`#root::core::QueryError::UnknownField`] for a name
                /// that isn't a column on this model,
                /// [`#root::core::QueryError::BulkUpdatePrimaryKey`] if
                /// `fields` names the PK, or [`#root::sql::ExecError`] for
                /// SQL-writing / driver failures.
                pub async fn bulk_update(
                    objs: &[Self],
                    fields: &[&str],
                    pool: &#root::sql::Pool,
                ) -> ::core::result::Result<u64, #root::sql::ExecError> {
                    if objs.is_empty() || fields.is_empty() {
                        return ::core::result::Result::Ok(0);
                    }
                    let _model_name = <Self as #root::core::Model>::SCHEMA.name;
                    let mut _update_columns: ::std::vec::Vec<&'static str> =
                        ::std::vec::Vec::with_capacity(fields.len());
                    for &_f in fields {
                        let _col: &'static str = match _f {
                            #pk_col => {
                                return ::core::result::Result::Err(
                                    ::core::convert::Into::into(
                                        #root::core::QueryError::BulkUpdatePrimaryKey {
                                            model: _model_name,
                                            field: ::std::string::ToString::to_string(_f),
                                        }
                                    )
                                );
                            }
                            #( #col_arms )*
                            _ => {
                                return ::core::result::Result::Err(
                                    ::core::convert::Into::into(
                                        #root::core::QueryError::UnknownField {
                                            model: _model_name,
                                            field: ::std::string::ToString::to_string(_f),
                                        }
                                    )
                                );
                            }
                        };
                        // A model whose only field is the primary key emits no
                        // non-PK arms, so every arm above diverges and this push
                        // is genuinely unreachable — correct, since such a model
                        // has nothing to bulk-update. Scoped to the statement
                        // rather than the fn so a real unreachability elsewhere
                        // in this body still warns. Without it every PK-only
                        // model warns in the *user's* crate, which they cannot
                        // act on (#1290).
                        #[allow(unreachable_code)]
                        _update_columns.push(_col);
                    }
                    let mut _rows: ::std::vec::Vec<
                        ::std::vec::Vec<#root::core::SqlValue>,
                    > = ::std::vec::Vec::with_capacity(objs.len());
                    for _o in objs.iter() {
                        let mut _row_vals: ::std::vec::Vec<#root::core::SqlValue> =
                            ::std::vec::Vec::with_capacity(fields.len() + 1);
                        // PK first — the writers expect `[pk, …update cols]`.
                        _row_vals.push(
                            ::core::convert::Into::<#root::core::SqlValue>::into(
                                ::core::clone::Clone::clone(&_o.#pk_ident)
                            )
                        );
                        for &_f in fields {
                            match _f {
                                #( #val_arms )*
                                // Unreachable: every name was validated
                                // against the same arm set above.
                                _ => {}
                            }
                        }
                        _rows.push(_row_vals);
                    }
                    let _query = #root::core::BulkUpdateQuery::new(
                        <Self as #root::core::Model>::SCHEMA,
                        _update_columns,
                        _rows,
                    );
                    #bulk_update_rows_run
                }
            }
        }
    };

    let pk_value_helper = primary_key.map(|(pk_ident, _)| {
        quote! {
            /// Hidden runtime accessor for the primary-key value as a
            /// [`SqlValue`]. Used by reverse-relation helpers
            /// (`<parent>::<child>_set`) emitted from sibling models'
            /// FK fields. Not part of the public API.
            #[doc(hidden)]
            pub fn __rustango_pk_value(&self) -> #root::core::SqlValue {
                ::core::convert::Into::<#root::core::SqlValue>::into(
                    ::core::clone::Clone::clone(&self.#pk_ident)
                )
            }
        }
    });

    let has_pk_value_impl = primary_key.map(|(pk_ident, _)| {
        quote! {
            impl #root::sql::HasPkValue for #struct_name {
                fn __rustango_pk_value_impl(&self) -> #root::core::SqlValue {
                    ::core::convert::Into::<#root::core::SqlValue>::into(
                        ::core::clone::Clone::clone(&self.#pk_ident)
                    )
                }
            }
        }
    });

    let fk_pk_access_impl = fk_pk_access_impl_tokens(struct_name, &fields.fk_relations);

    // Slice 17.1 — `AssignAutoPkPool` impl lets `apply_auto_pk`
    // dispatch to the right per-backend body without the macro emitting
    // any `#[cfg(feature = …)]` arm into consumer code. Always emitted
    // so audited models with non-Auto PKs (which still go through
    // `insert_one_with_audit` → `apply_auto_pk`) link.
    let assign_auto_pk_pool_impl = {
        let auto_assigns = &fields.auto_assigns;
        // SQLite ≥ 3.35 supports the same RETURNING shape as Postgres,
        // so the body is structurally identical to `auto_assigns` —
        // only the helper name swaps from `try_get_returning` to
        // `try_get_returning_sqlite` so the closure typechecks against
        // a `SqliteRow` instead of a `PgRow`.
        let auto_assigns_sqlite: Vec<TokenStream2> = fields
            .auto_field_idents
            .iter()
            .map(|(ident, column, uuid)| {
                // A UUID a column default wrote is TEXT, not the 16 bytes sqlx binds.
                if *uuid {
                    return quote! {
                        self.#ident = #root::sql::Auto::Set(#root::sql::try_get_flat_sqlite(
                            _returning_row, #column
                        )?);
                    };
                }
                quote! {
                    self.#ident = #root::sql::try_get_returning_sqlite(
                        _returning_row, #column
                    )?;
                }
            })
            .collect();
        // #1028 — decode each `generated_as` column from the same
        // RETURNING row (PG/SQLite). Plain-typed fields, so the field's
        // own type drives the decode (no `Auto<T>` wrapper).
        let generated_assigns: Vec<TokenStream2> = fields
            .generated_field_idents
            .iter()
            .map(|(ident, column)| {
                quote! {
                    self.#ident = #root::sql::try_get_returning(_returning_row, #column)?;
                }
            })
            .collect();
        let generated_assigns_sqlite: Vec<TokenStream2> = fields
            .generated_field_idents
            .iter()
            .map(|(ident, column)| {
                quote! {
                    self.#ident = #root::sql::try_get_returning_sqlite(
                        _returning_row, #column
                    )?;
                }
            })
            .collect();
        let mysql_body = if let Some((first, value_ty)) = fields.first_db_auto.as_ref() {
            // The MySQL `LAST_INSERT_ID()` is always i64. Route through
            // `MysqlAutoIdSet` so Auto<i32> narrows safely and
            // Auto<Uuid>/etc. fail to link against MySQL (intended —
            // those models can't use AUTO_INCREMENT). The trait is only
            // touched on the MySQL arm at runtime, so PG-only consumers
            // never see the bound failure.
            //
            // Pre-v0.20: models with multiple `Auto<T>` fields (e.g.
            // Auto<i64> PK + auto_now_add timestamp) errored hard at
            // runtime with "multi-column RETURNING". MySQL has no
            // multi-column RETURNING semantic and a follow-up SELECT
            // would need cross-trait plumbing. Pragmatic shape: succeed
            // with the FIRST Auto field populated from LAST_INSERT_ID();
            // any other Auto fields stay `Auto::Unset`. Callers that
            // need the DB-defaulted timestamp / UUID can re-fetch the
            // row by PK after `save_pool`. Fixes the cookbook chapter
            // 12 dialect divergence.
            quote! {
                let _converted = <#value_ty as #root::sql::MysqlAutoIdSet>
                    ::rustango_from_mysql_auto_id(_id)?;
                self.#first = #root::sql::Auto::Set(_converted);
                ::core::result::Result::Ok(())
            }
        } else {
            quote! {
                let _ = _id;
                ::core::result::Result::Ok(())
            }
        };
        quote! {
            impl #root::sql::AssignAutoPkPool for #struct_name {
                fn __rustango_assign_from_pg_row(
                    &mut self,
                    _returning_row: &#root::sql::PgReturningRow,
                ) -> ::core::result::Result<(), #root::sql::ExecError> {
                    #( #auto_assigns )*
                    #( #generated_assigns )*
                    ::core::result::Result::Ok(())
                }
                fn __rustango_assign_from_mysql_id(
                    &mut self,
                    _id: i64,
                ) -> ::core::result::Result<(), #root::sql::ExecError> {
                    #mysql_body
                }
                fn __rustango_assign_from_sqlite_row(
                    &mut self,
                    _returning_row: &#root::sql::SqliteReturningRow,
                ) -> ::core::result::Result<(), #root::sql::ExecError> {
                    #( #auto_assigns_sqlite )*
                    #( #generated_assigns_sqlite )*
                    ::core::result::Result::Ok(())
                }
            }
        }
    };

    let from_aliased_row_inits = &fields.from_aliased_row_inits;
    let aliased_row_helper = quote! {
        /// Decode a row's aliased target columns (produced by
        /// `select_related`'s LEFT JOIN) into a fresh instance of
        /// this model. Reads each column via
        /// `format!("{prefix}__{col}")`, matching the alias the
        /// SELECT writer emitted. Slice 9.0d.
        #[doc(hidden)]
        #[cfg(feature = "postgres")]
        pub fn __rustango_from_aliased_row(
            row: &#root::sql::sqlx::postgres::PgRow,
            prefix: &str,
        ) -> ::core::result::Result<Self, #root::sql::sqlx::Error> {
            ::core::result::Result::Ok(Self {
                #( #from_aliased_row_inits ),*
            })
        }
    };
    // v0.23.0-batch8 — MySQL counterpart, gated through the
    // cfg-aware macro_rules so PG-only builds expand to nothing.
    let from_aliased_row_inits_my = &fields.from_aliased_row_inits_my;
    let aliased_row_helper_my = quote! {
        #root::__impl_my_aliased_row_decoder!(#struct_name, |row, prefix| {
            #( #from_aliased_row_inits_my ),*
        });
    };

    // v0.27 Phase 3 — SQLite counterpart, same hygiene-aware closure
    // pattern + cfg gate on the `sqlite` feature.
    let aliased_row_helper_sqlite = quote! {
        #root::__impl_sqlite_aliased_row_decoder!(#struct_name, |row, prefix| {
            #( #from_aliased_row_inits ),*
        });
    };

    let load_related_impl = load_related_impl_tokens(struct_name, &fields.fk_relations);
    let load_related_impl_my = load_related_impl_my_tokens(struct_name, &fields.fk_relations);
    let load_related_impl_sqlite =
        load_related_impl_sqlite_tokens(struct_name, &fields.fk_relations);

    // Issue #289 / T2.6 — `#[rustango(manager_fn = "active")]` emits
    // extra `Self::<name>() -> QuerySet<Self>` accessors next to the
    // default `Self::objects()`. Each accessor returns a fresh
    // QuerySet that resolves any `impl <FooManagerExt> for QuerySet<Foo>`
    // methods the user defined.
    let extra_manager_fns: Vec<TokenStream2> = manager_fns
        .iter()
        .map(|fn_ident| {
            let model_name_str = struct_name.to_string();
            let fn_name_str = fn_ident.to_string();
            let doc = format!(
                "Custom-named QuerySet accessor for [`{model_name_str}`]. \
                 Generated by `#[rustango(manager_fn = \"{fn_name_str}\")]` — \
                 equivalent to `Self::objects()`. Chains with any \
                 `impl ... for QuerySet<{model_name_str}> {{ ... }}` \
                 extension methods."
            );
            quote! {
                #[doc = #doc]
                #[must_use]
                pub fn #fn_ident() -> #root::query::QuerySet<#struct_name> {
                    #root::query::QuerySet::new()
                }
            }
        })
        .collect();

    quote! {
        impl #struct_name {
            /// Start a new `QuerySet` over this model.
            #[must_use]
            pub fn objects() -> #root::query::QuerySet<#struct_name> {
                #root::query::QuerySet::new()
            }

            /// Eloquent-shape alias of [`Self::objects`]. Returns
            /// a fresh `QuerySet<Self>` ready for `.filter()` /
            /// `.where_()` / etc. Matches Laravel muscle-memory:
            ///
            /// ```ignore
            /// // Eloquent:    Post::query()->where('published', true)
            /// // rustango:    Post::query().filter("published", true)
            /// //         or:  Post::objects().filter("published", true)
            /// ```
            ///
            /// Both names point at the same underlying constructor;
            /// neither is preferred.
            #[must_use]
            pub fn query() -> #root::query::QuerySet<#struct_name> {
                #root::query::QuerySet::new()
            }

            #( #extra_manager_fns )*

            #insert_method

            #bulk_insert_method

            #bulk_upsert_pool_method

            #bulk_update_method

            #save_method

            #pk_methods

            #pk_value_helper

            #aliased_row_helper

            #column_consts
        }

        #aliased_row_helper_my

        #aliased_row_helper_sqlite

        #load_related_impl

        #load_related_impl_my

        #load_related_impl_sqlite

        #has_pk_value_impl

        #fk_pk_access_impl

        #assign_auto_pk_pool_impl
    }
}

/// Per-row Auto-field assigns for `bulk_insert` — equivalent to
/// `auto_assigns` but reading from `_returning_row` and writing to
/// `_row_mut` instead of `self`.
fn bulk_auto_assigns_for_row(fields: &CollectedFields) -> TokenStream2 {
    let root = rustango_root();
    let lines = fields.auto_field_idents.iter().map(|(ident, column, _)| {
        let col_lit = column.as_str();
        quote! {
            _row_mut.#ident = #root::sql::sqlx::Row::try_get(
                _returning_row,
                #col_lit,
            )?;
        }
    });
    quote! { #( #lines )* }
}

/// Emit `pub const id: …Id = …Id;` per field, inside the inherent impl.
fn column_const_tokens(module_ident: &syn::Ident, entries: &[ColumnEntry]) -> TokenStream2 {
    let lines = entries.iter().map(|e| {
        let ident = &e.ident;
        let col_ty = column_type_ident(ident);
        quote! {
            #[allow(non_upper_case_globals)]
            pub const #ident: #module_ident::#col_ty = #module_ident::#col_ty;
        }
    });
    quote! { #(#lines)* }
}

/// Emit a hidden per-model module carrying one zero-sized type per field,
/// each with a `Column` impl pointing back at the model.
fn column_module_tokens(
    module_ident: &syn::Ident,
    struct_name: &syn::Ident,
    entries: &[ColumnEntry],
) -> TokenStream2 {
    let root = rustango_root();
    let items = entries.iter().map(|e| {
        let col_ty = column_type_ident(&e.ident);
        let value_ty = &e.value_ty;
        let name = &e.name;
        let column = &e.column;
        let field_type_tokens = &e.field_type_tokens;
        quote! {
            #[derive(::core::clone::Clone, ::core::marker::Copy)]
            pub struct #col_ty;

            impl #root::core::Column for #col_ty {
                type Model = super::#struct_name;
                type Value = #value_ty;
                const NAME: &'static str = #name;
                const COLUMN: &'static str = #column;
                const FIELD_TYPE: #root::core::FieldType = #field_type_tokens;
            }
        }
    });
    quote! {
        #[doc(hidden)]
        #[allow(non_camel_case_types, non_snake_case)]
        pub mod #module_ident {
            // Re-import the parent scope so field types referencing
            // sibling models (e.g. `ForeignKey<Author>`) resolve
            // inside this submodule. Without this we'd hit
            // `proc_macro_derive_resolution_fallback` warnings.
            #[allow(unused_imports)]
            use super::*;
            #(#items)*
        }
    }
}

fn column_type_ident(field_ident: &syn::Ident) -> syn::Ident {
    let name = ident_name(field_ident);
    syn::Ident::new(&format!("{name}_col"), field_ident.span())
}

/// Run `body` (of type `ret`) and put the `auto_now` fields back unless
/// `keep` holds for `_saved`, so a failed or no-row write keeps the old stamp.
fn restore_auto_now_unless(
    idents: &[syn::Ident],
    ret: &TokenStream2,
    keep: &TokenStream2,
    body: &TokenStream2,
) -> TokenStream2 {
    if idents.is_empty() {
        return body.clone();
    }
    let prev: Vec<syn::Ident> = (0..idents.len())
        .map(|i| quote::format_ident!("__rustango_auto_now_prev_{}", i))
        .collect();
    quote! {
        #( let #prev = ::core::clone::Clone::clone(&self.#idents); )*
        let _saved: #ret = async { #body }.await;
        if !(#keep) {
            #( self.#idents = #prev; )*
        }
        _saved
    }
}

/// A field's name without the `r#` of a raw ident: `r#type` is `type` (#1937).
fn ident_name(ident: &syn::Ident) -> String {
    syn::ext::IdentExt::unraw(ident).to_string()
}

/// The ident for a field named `name`, raw when it is a keyword (`type` → `r#type`).
fn ident_from_name(name: &str, span: proc_macro2::Span) -> syn::Ident {
    match syn::parse_str::<syn::Ident>(name) {
        Ok(mut ident) => {
            ident.set_span(span);
            ident
        }
        Err(_) => syn::Ident::new_raw(name, span),
    }
}

fn column_module_ident(struct_name: &syn::Ident) -> syn::Ident {
    syn::Ident::new(
        &format!("__rustango_cols_{struct_name}"),
        struct_name.span(),
    )
}

fn from_row_impl_tokens(
    struct_name: &syn::Ident,
    from_row_inits: &[TokenStream2],
    from_row_inits_my: &[TokenStream2],
) -> TokenStream2 {
    let root = rustango_root();
    // The Postgres impl is always emitted — every rustango build pulls in
    // sqlx-postgres via the default `postgres` feature. The MySQL impl is
    // routed through `#root::__impl_my_from_row!`, a cfg-gated
    // macro_rules whose body collapses to nothing when rustango is built
    // without the `mysql` feature. No user-facing feature shim required.
    //
    // The macro_rules pattern expects `[ field: expr, … ]` — we need to
    // re-shape `from_row_inits` (each token is `field: row.try_get(...)`)
    // back into a comma-separated list inside square brackets. Since each
    // entry is already in `field: expr` shape, the existing tokens slot in.
    quote! {
        #[cfg(feature = "postgres")]
        impl<'r> #root::sql::sqlx::FromRow<'r, #root::sql::sqlx::postgres::PgRow>
            for #struct_name
        {
            fn from_row(
                row: &'r #root::sql::sqlx::postgres::PgRow,
            ) -> ::core::result::Result<Self, #root::sql::sqlx::Error> {
                ::core::result::Result::Ok(Self {
                    #( #from_row_inits ),*
                })
            }
        }

        #root::__impl_my_from_row!(#struct_name, |row| {
            #( #from_row_inits_my ),*
        });

        #root::__impl_sqlite_from_row!(#struct_name, |row| {
            #( #from_row_inits ),*
        });
    }
}

struct ContainerAttrs {
    table: Option<String>,
    display: Option<(String, proc_macro2::Span)>,
    /// Explicit app label from `#[rustango(app = "blog")]`.
    /// Recorded on the emitted `ModelSchema.app_label`. When unset,
    /// `ModelEntry::resolved_app_label()` infers from `module_path!()`
    /// at runtime — this attribute is the override for cases where
    /// the inference is wrong (e.g. a model that conceptually belongs
    /// to one app but is physically in another module).
    app: Option<String>,
    /// Per-model admin knobs from
    /// `#[rustango(admin(...))]`. `None` when the user didn't write the
    /// attribute — the emitted `ModelSchema.admin` becomes `None` and
    /// admin code falls back to `AdminConfig::DEFAULT`.
    admin: Option<AdminAttrs>,
    /// Per-model audit configuration from `#[rustango(audit(...))]`.
    /// `None` when the model isn't audited — write paths emit no
    /// audit entries. When present, single-row writes capture
    /// before/after for the listed fields and bulk writes batch
    /// snapshots into one INSERT into `rustango_audit_log`.
    audit: Option<AuditAttrs>,
    /// `true` when `#[rustango(permissions)]` is present. Signals that
    /// `auto_create_permissions` should seed the four CRUD codenames for
    /// this model.
    permissions: bool,
    /// Many-to-many relations declared via
    /// `#[rustango(m2m(name = "tags", to = "app_tags", through = "post_tags",
    ///                 src = "post_id", dst = "tag_id"))]`.
    m2m: Vec<M2MAttr>,
    /// Polymorphic M2M relations declared via
    /// `#[rustango(generic_m2m(name = "tags", through = "taggables",
    ///   pk_column = "taggable_id", ct_column = "taggable_type",
    ///   related_column = "tag_id"))]` (issue #818).
    generic_m2m: Vec<GenericM2MAttr>,
    /// Composite indexes declared via
    /// `#[rustango(index("col1, col2"))]` or
    /// `#[rustango(index("col1, col2", unique, name = "my_idx"))]`.
    /// Single-column indexes from `#[rustango(index)]` on fields are
    /// accumulated here during field collection.
    indexes: Vec<IndexAttr>,
    /// Table-level CHECK constraints declared via
    /// `#[rustango(check(name = "…", expr = "…"))]`.
    checks: Vec<CheckAttr>,
    /// Table-level PG `EXCLUDE` constraints declared via
    /// `#[rustango(exclude(name = "…", using = "gist", elements =
    /// "col WITH op, col WITH op", where = "…"))]`. PG-only — the
    /// migration writer renders them on Postgres and skips with a
    /// warning on MySQL/SQLite. Issue #319.
    excludes: Vec<ExcludeAttr>,
    /// Composite (multi-column) FKs declared via
    /// `#[rustango(fk_composite(name = "…", to = "…", on = (…), from = (…)))]`.
    /// Sub-slice F.2 of the v0.15.0 ContentType plan.
    composite_fks: Vec<CompositeFkAttr>,
    /// Generic ("any model") FKs declared via
    /// `#[rustango(generic_fk(name = "…", ct_column = "…", pk_column = "…"))]`.
    /// Sub-slice F.4 of the v0.15.0 ContentType plan.
    generic_fks: Vec<GenericFkAttr>,
    /// Where this model lives in a tenancy deployment, declared via
    /// `#[rustango(scope = "registry")]` or `#[rustango(scope = "tenant")]`.
    /// Defaults to `"tenant"` when unset; `makemigrations` uses this
    /// to partition diff output between registry-scoped and
    /// tenant-scoped migration files.
    scope: Option<String>,
    /// Extra QuerySet accessor names from
    /// `#[rustango(manager_fn = "active")]`. Issue #289 / T2.6.
    /// Each value adds a `pub fn <name>() -> QuerySet<Self>` next to
    /// the default `Self::objects()`. Multiple attributes allowed.
    manager_fns: Vec<syn::Ident>,
    /// Default ordering declared via `#[rustango(default_order =
    /// "-created_at, status")]`. Issue #291 / T2.5. Each entry is
    /// `(column_name, desc_flag, span_for_error_reporting)` — the
    /// `-` prefix means descending; the `+` prefix or no prefix means
    /// ascending.
    default_order: Vec<(String, bool, proc_macro2::Span)>,
    /// `true` when `#[rustango(view)]` is present. Issue #293 / T2.10.
    /// Routes the emitted schema's `is_view = true` so the migration
    /// snapshot skips this model (its underlying SQL view is operator-
    /// managed, not rustango-managed).
    is_view: bool,
    /// `#[rustango(managed = false)]` — who owns the table.
    /// Issue #321. Defaults to `true`; when explicitly set to `false`,
    /// the migration snapshot skips this model so `makemigrations` /
    /// `migrate` never emit `CREATE TABLE` / `ALTER TABLE` / `DROP
    /// TABLE` against it (operator-managed schema).
    managed: bool,
    /// Name of the model's base manager, from
    /// `#[rustango(base_manager_name = "...")]`. Threaded into
    /// `ModelSchema::base_manager_name`. Declarative-only today.
    base_manager_name: Option<String>,
    /// `#[rustango(order_with_respect_to = "...")]`. Names the FK
    /// field this model's instances are ordered relative to.
    /// Declarative-only today; threaded onto
    /// `ModelSchema::order_with_respect_to`.
    order_with_respect_to: Option<String>,
    /// `#[rustango(proxy)]` / `#[rustango(proxy = true)]`.
    /// Marks the model as a proxy that
    /// shares its DB table with another struct. Threaded into
    /// `ModelSchema::proxy` so future codegen can skip table-owning
    /// behavior for proxies.
    proxy: bool,
    /// `#[rustango(required_db_features = "json_extract,window_functions")]`.
    /// Each comma-separated capability token surfaces on
    /// `ModelSchema::required_db_features` so `manage check --deploy`
    /// can warn when the active dialect lacks one.
    required_db_features: Vec<String>,
    /// `#[rustango(required_db_vendor = "postgres|mysql|sqlite")]`.
    /// Normalized to the dialect name `manage check --deploy`
    /// compares against `Settings.database.backend`. Aliases
    /// (`postgresql` / `pg` / `mariadb` / `sqlite3`) accepted but
    /// stored under the canonical name.
    required_db_vendor: Option<String>,
    /// `#[rustango(default_related_name = "...")]`. Threaded into
    /// `ModelSchema::default_related_name`. Reverse-relation accessor
    /// name to use when an FK / M2M field doesn't override it.
    /// Today rustango doesn't auto-emit reverse managers; the
    /// metadata is the foundation for that work.
    default_related_name: Option<String>,
    /// `#[rustango(db_table_comment = "...")]`. Threaded into
    /// `ModelSchema::db_table_comment` so the DDL writer attaches the
    /// comment to the underlying table (PG: `COMMENT ON TABLE`, MySQL:
    /// inline `COMMENT='...'`, SQLite: no-op).
    db_table_comment: Option<String>,
    /// `#[rustango(get_latest_by = "created_at")]` /
    /// `#[rustango(get_latest_by = "-priority")]`. Parsed into
    /// `(column, descending)` where `descending = true` when the
    /// attribute value starts with `-`. Threaded into
    /// `ModelSchema::get_latest_by`.
    get_latest_by: Option<(String, bool)>,
    /// Extra `(codename, label)` permissions
    /// from `#[rustango(extra_permissions = "approve:Can approve,
    /// archive:Can archive")]`. Comma-separated `codename:label`
    /// pairs. Threaded into `ModelSchema::extra_permissions`.
    extra_permissions: Vec<(String, String)>,
    /// Which CRUD codenames (`"add"` / `"change"` / `"delete"` /
    /// `"view"`) the framework
    /// auto-creates. Empty `Vec` (default) means **all four**. Set via
    /// `#[rustango(default_permissions = "view,change")]` to opt out.
    /// Validated at parse time; unknown actions fail with a span-pointing
    /// error.
    default_permissions: Vec<String>,
    /// `#[rustango(verbose_name = "blog post")]` — the
    /// human-readable singular label for the model. Threaded into
    /// `ModelSchema::verbose_name` so admin section headers /
    /// breadcrumbs / "Add X" buttons can prefer the friendly caption
    /// over the Rust struct identifier.
    verbose_name: Option<String>,
    /// `#[rustango(verbose_name_plural = "blog posts")]` — explicit
    /// plural form. Threaded into `ModelSchema::verbose_name_plural`.
    /// When unset, `display_label_plural()` auto-suffixes `s`.
    verbose_name_plural: Option<String>,
    /// Eloquent-shape **global scopes** from `#[rustango(global_scope(name
    /// = "...", apply = path::to::fn))]` — issue #820. Each entry pairs
    /// a name (used by `QuerySet::without_global_scope`) with a
    /// `fn() -> WhereExpr` path that the macro emits into
    /// `ModelSchema::global_scopes`. Multiple attributes accumulate.
    global_scopes: Vec<GlobalScopeAttr>,
    /// Eloquent `hasManyThrough` / `hasOneThrough` declarations from
    /// `#[rustango(through(name, far, far_fk_column, intermediate,
    /// intermediate_fk_column, intermediate_pk_column))]` — issue
    /// [#817](https://github.com/ujeenet/rustango/issues/817). Each
    /// entry emits an inherent `<name>_through(&self)` accessor that
    /// returns a `QuerySet<Far>` filtered via a correlated subquery
    /// (`WHERE far_fk_column IN (SELECT intermediate_pk_column FROM
    /// intermediate WHERE intermediate_fk_column = <my_pk>)`).
    through_relations: Vec<ThroughAttr>,
    /// Eloquent `whereHas` / `whereDoesntHave` declarations from
    /// `#[rustango(reverse_has(name, child, child_fk_column))]` —
    /// issue [#830](https://github.com/ujeenet/rustango/issues/830).
    /// Each entry emits two associated functions on the parent —
    /// `<name>_exists_expr()` and `<name>_not_exists_expr()` —
    /// returning a `WhereExpr::Exists` / `WhereExpr::NotExists`
    /// over a correlated subquery against the child table. Users
    /// drop the result into `QuerySet::where_raw(...)`.
    reverse_has_relations: Vec<ReverseHasAttr>,
    /// `#[rustango(generic_has(...))]` reverse generic-FK declarations —
    /// issue #830. Each emits a `Model::generic_reverse_relations()`
    /// entry so the relation-existence family resolves polymorphic
    /// children by name.
    generic_has_relations: Vec<GenericHasAttr>,
}

/// Parsed `#[rustango(global_scope(name = "...", apply = fn_path))]`
/// declaration. Each entry becomes one `core::GlobalScope` in the
/// emitted schema literal; `apply` resolves at macro-expand time
/// against the consumer's scope so the function must be in scope at
/// the use site. Issue #820.
struct GlobalScopeAttr {
    name: String,
    apply: syn::Path,
}

/// Parsed `#[rustango(through(...))]` declaration. Issue
/// [#817](https://github.com/ujeenet/rustango/issues/817) — Eloquent
/// `hasManyThrough` / `hasOneThrough` parity.
///
/// `Country hasManyThrough Post via User` declares as:
///
/// ```ignore
/// #[rustango(through(
///     name                   = "posts",
///     far                    = "Post",
///     far_fk_column          = "author_id",
///     intermediate           = "User",
///     intermediate_fk_column = "country_id",
/// ))]
/// struct Country { ... }
/// ```
///
/// The macro emits `Country::posts_through(&self) -> QuerySet<Post>`
/// which returns a queryset filtered via a correlated subquery —
/// `Post WHERE author_id IN (SELECT id FROM tr_user WHERE country_id
/// = <my_pk>)`. The returned `QuerySet<Post>` is **chainable**:
/// `.filter()` / `.order_by()` / `.limit()` etc. compose normally
/// because the subquery lives inside a `WhereExpr::InSubquery` node
/// and the outer queryset's pending list stays empty.
///
/// All four required arguments use **SQL column / table names**
/// (not Rust field names) to sidestep the multi-hop-filter substrate
/// gap. Once that substrate lands, a higher-level Rust-field-name
/// shorthand can be added without breaking this surface.
struct ThroughAttr {
    /// Accessor method name. `name = "posts"` → emits `posts_through()`.
    name: String,
    /// Far model type identifier. `far = "Post"` → returns
    /// `QuerySet<Post>`. Resolved verbatim against the scope where
    /// the derive expands.
    far: syn::Ident,
    /// SQL column on the far model's table that references the
    /// intermediate model's primary key. For `Post`'s
    /// `author: ForeignKey<User>` the column is `"author_id"` (rustango's
    /// default `<field>_id` convention) or whatever the user
    /// declared via `#[rustango(db_column = "...")]`.
    far_fk_column: String,
    /// Intermediate model type identifier. Needed to look up its
    /// `SCHEMA` so the subquery's `FROM` clause points at the
    /// intermediate table. `intermediate = "User"`.
    intermediate: syn::Ident,
    /// SQL column on the intermediate's table that references the
    /// source (this) model's primary key. For `User`'s
    /// `country: ForeignKey<Country>` the column is `"country_id"`.
    intermediate_fk_column: String,
    /// SQL primary-key column on the intermediate's table — the
    /// column the subquery projects. Optional; defaults to `"id"`
    /// (rustango's default PK column name). Override when the
    /// intermediate declares a custom PK column.
    intermediate_pk_column: String,
}

/// Parsed `#[rustango(reverse_has(name = "...", child = "...",
/// child_fk_column = "..."))]` declaration. Issue
/// [#830](https://github.com/ujeenet/rustango/issues/830) — Eloquent
/// `whereHas` / `whereDoesntHave` parity.
///
/// `Post hasMany Comment` declares as:
///
/// ```ignore
/// #[rustango(reverse_has(
///     name             = "comments",
///     child            = "Comment",
///     child_fk_column  = "post_id",
/// ))]
/// struct Post { ... }
/// ```
///
/// The macro emits two associated functions on `Post`:
///
/// - `Post::comments_exists_expr() -> WhereExpr` — yields
///   `EXISTS (SELECT … FROM comment WHERE comment.post_id =
///   <outer>.<self_pk_column>)`.
/// - `Post::comments_not_exists_expr() -> WhereExpr` — same shape
///   but `NOT EXISTS`, the `whereDoesntHave` analog.
///
/// User code:
///
/// ```ignore
/// // Posts with at least one comment:
/// Post::objects().where_raw(Post::comments_exists_expr()).fetch(&pool)
/// // Posts with no comments:
/// Post::objects().where_raw(Post::comments_not_exists_expr()).fetch(&pool)
/// ```
///
/// As with #817, all column / table identifiers are **SQL names**
/// (not Rust field names) so the substrate is independent of the
/// outstanding multi-hop filter resolver gap. The emitted
/// `Expr::OuterRef("…")` resolves to the outer queryset's table at
/// SQL-emit time via the writer's scope stack.
struct ReverseHasAttr {
    /// Accessor name. `name = "comments"` → emits
    /// `comments_exists_expr()` + `comments_not_exists_expr()`.
    name: String,
    /// Child model type identifier. `child = "Comment"` — needed to
    /// look up the child's `SCHEMA` so the subquery's `FROM` clause
    /// points at the child table.
    child: syn::Ident,
    /// SQL column on the child's table that references this model's
    /// primary key. For `Comment`'s `post: ForeignKey<Post>` the
    /// column is `"post_id"`.
    child_fk_column: String,
    /// SQL primary-key column on **this** model's table — the column
    /// the `OuterRef` resolves to. Optional; defaults to `"id"`
    /// (rustango's default PK column name).
    self_pk_column: String,
}

/// Parsed `#[rustango(generic_has(name, child, ct_column, pk_column
/// [, self_pk_column]))]` — the reverse generic-FK (GFK) arm of the
/// relation-existence family (issue #830). The child is a polymorphic,
/// content-type-discriminated model; emits a `Model::
/// generic_reverse_relations()` entry the queryset resolves by name.
struct GenericHasAttr {
    /// Accessor name, e.g. `name = "tags"`.
    name: String,
    /// Child model type identifier (`child = "Tag"`) — looked up for its
    /// `SCHEMA` so the subquery's `FROM` points at the child table.
    child: syn::Ident,
    /// Column on the child table holding the parent's content-type id.
    /// Optional; defaults to `"content_type_id"`.
    ct_column: String,
    /// Column on the child table holding the parent's PK value.
    /// Optional; defaults to `"object_pk"`.
    pk_column: String,
    /// SQL primary-key column on **this** (parent) model's table.
    /// Optional; defaults to `"id"`.
    self_pk_column: String,
}

/// Parsed form of one index declaration (field-level or container-level).
struct IndexAttr {
    /// Index name; auto-derived when `None` at parse time.
    name: Option<String>,
    /// Column names in the index.
    columns: Vec<String>,
    /// `true` for `CREATE UNIQUE INDEX`.
    unique: bool,
    /// Access method token (`"btree"`, `"gin"`, `"gist"`, `"brin"`,
    /// `"spgist"`, `"hash"`, `"bloom"`). Issue #34. Defaults to
    /// `"btree"` when the attribute is absent — the DDL writer omits
    /// the `USING` clause and the backend uses its own default
    /// (btree on every supported dialect).
    method: String,
    /// Optional `WHERE <expr>` clause for partial indexes. Issue #265 /
    /// T1.3. Set via `#[rustango(unique_when(columns = "...",
    /// condition = "...", name = "..."))]`. `None` for plain indexes.
    where_clause: Option<String>,
    /// Covering-index columns (PG 11+ `INCLUDE (...)` clause).
    /// Empty `Vec` (the default) means "no covering columns".
    include: Vec<String>,
}

/// Parsed form of one `#[rustango(check(name = "…", expr = "…"))]` declaration.
struct CheckAttr {
    name: String,
    expr: String,
}

/// Parsed form of one `#[rustango(exclude(name = "…", using = "gist",
/// elements = "col WITH op, col WITH op", where = "…"))]` declaration.
/// PG-only — surfaced on every backend in the macro emit; the migration
/// writer skips the op on MySQL/SQLite. Issue #319.
struct ExcludeAttr {
    /// Constraint name (free-form Rust identifier).
    name: String,
    /// Index method — `"gist"` (default), `"btree_gist"`, `"spgist"`.
    using: String,
    /// Comma-separated `(column, operator)` pairs, in declaration
    /// order. Parsed from `"col WITH op, col WITH op"`.
    elements: Vec<(String, String)>,
    /// Optional `WHERE` predicate (raw SQL).
    where_clause: Option<String>,
}

/// Parsed form of one `#[rustango(fk_composite(name = "audit_target",
/// to = "rustango_audit_log", on = ("entity_table", "entity_pk"),
/// from = ("table_name", "row_pk")))]` declaration. Sub-slice F.2 of
/// the v0.15.0 ContentType plan — multi-column foreign keys live on
/// the model, not the field.
struct CompositeFkAttr {
    /// Logical relation name (free-form Rust identifier).
    name: String,
    /// SQL table name of the target.
    to: String,
    /// Source-side column names, in declaration order.
    from: Vec<String>,
    /// Target-side column names, same length / order as `from`.
    on: Vec<String>,
}

/// Parsed form of one `#[rustango(generic_fk(name = "target",
/// ct_column = "content_type_id", pk_column = "object_pk"))]`
/// declaration. Sub-slice F.4 of the v0.15.0 ContentType plan —
/// generic ("any model") FKs live on the model, not the field.
struct GenericFkAttr {
    /// Logical relation name (free-form Rust identifier).
    name: String,
    /// Source-side column carrying the `content_type_id` value.
    ct_column: String,
    /// Source-side column carrying the target row's primary key.
    pk_column: String,
}

/// Parsed form of one `#[rustango(m2m(...))]` declaration.
struct M2MAttr {
    /// Accessor suffix: `tags` → generates `tags_m2m()`.
    name: String,
    /// Target table (e.g. `"app_tags"`).
    to: String,
    /// Junction table (e.g. `"post_tags"`).
    through: String,
    /// Source FK column in the junction table (e.g. `"post_id"`).
    src: String,
    /// Destination FK column in the junction table (e.g. `"tag_id"`).
    dst: String,
    /// Whether the migration writer should auto-create the junction
    /// table. Default `true`. Set `auto_create = false` (#324) when
    /// the operator declares the through table as its own
    /// `#[derive(Model)]` struct with extra columns.
    auto_create: bool,
}

/// Parsed form of one `#[rustango(generic_m2m(...))]` declaration —
/// polymorphic many-to-many (Eloquent `morphToMany`, issue #818). The
/// junction carries a ContentType discriminator so unrelated models
/// share one pivot + related set.
struct GenericM2MAttr {
    /// Accessor suffix: `tags` → generates `tags_m2m()`.
    name: String,
    /// Polymorphic junction table (e.g. `"taggables"`).
    through: String,
    /// Junction column holding the owning instance PK (e.g. `"taggable_id"`).
    pk_column: String,
    /// Junction column holding the owning model's `content_type_id`
    /// discriminator (e.g. `"taggable_type"`).
    ct_column: String,
    /// Junction column holding the related model PK (e.g. `"tag_id"`).
    related_column: String,
}

/// Parsed shape of `#[rustango(audit(track = "name, body", source =
/// "user"))]`. `track` is a comma-separated list of field names whose
/// before/after values land in the JSONB `changes` column. `source`
/// is informational only — it pins a default source when the model
/// is written outside any `audit::with_source(...)` scope (rare).
#[derive(Default)]
struct AuditAttrs {
    /// Field names to capture in the `changes` JSONB. Validated
    /// against declared scalar fields at compile time. Empty means
    /// "track every scalar field".
    track: Option<(Vec<String>, proc_macro2::Span)>,
}

/// Parsed shape of `#[rustango(admin(list_display = "…", search_fields =
/// "…", list_per_page = N, ordering = "…"))]`. Field-name lists are
/// comma-separated strings; we validate each ident against the model's
/// declared fields at compile time.
#[derive(Default)]
struct AdminAttrs {
    list_display: Option<(Vec<String>, proc_macro2::Span)>,
    search_fields: Option<(Vec<String>, proc_macro2::Span)>,
    list_per_page: Option<usize>,
    ordering: Option<(Vec<(String, bool)>, proc_macro2::Span)>,
    readonly_fields: Option<(Vec<String>, proc_macro2::Span)>,
    list_filter: Option<(Vec<String>, proc_macro2::Span)>,
    /// Bulk action names. No field-validation against model fields —
    /// these are action handlers, not column references.
    actions: Option<(Vec<String>, proc_macro2::Span)>,
    /// Form fieldsets — `Vec<(title, [field_names])>`. Pipe-separated
    /// sections, comma-separated fields per section, optional
    /// `Title:` prefix. Empty title omits the `<legend>`.
    fieldsets: Option<(Vec<(String, Vec<String>)>, proc_macro2::Span)>,
    /// `admin(list_display_links = "title")`. Names
    /// from `list_display` whose cells should link to detail/edit.
    /// Issue #350.
    list_display_links: Option<(Vec<String>, proc_macro2::Span)>,
    /// `admin(search_help_text = "...")`. Short
    /// caption rendered beside the admin list view's search box.
    /// Issue #353.
    search_help_text: Option<String>,
    /// `admin(actions_on_top = false)`. Hides the
    /// action-bar above the table. Default `true`. Issue #354.
    actions_on_top: Option<bool>,
    /// `admin(actions_on_bottom = true)`. Renders an
    /// additional action-bar below the table. Default `false`.
    /// Issue #354.
    actions_on_bottom: Option<bool>,
    /// `admin(date_hierarchy = "created_at")`. Name of
    /// a date / datetime field whose values render as a clickable
    /// year / month / day drill-down strip above the list table.
    /// Empty / unset disables the strip. Issue #355.
    date_hierarchy: Option<String>,
    /// `admin(prepopulated_fields = "slug:title")`.
    /// Each entry is `target:source[+source2]`; multiple entries are
    /// comma-separated, e.g. `"slug:title,short_code:section+title"`.
    /// The admin change-form emits JS that slugifies the source values
    /// into the target field on every keystroke. Issue #356.
    prepopulated_fields: Option<(Vec<(String, Vec<String>)>, proc_macro2::Span)>,
    /// `admin(raw_id_fields = "parent, owner")`. Names
    /// of FK fields whose change-form widget renders a lookup link
    /// next to the input. Issue #357.
    raw_id_fields: Option<(Vec<String>, proc_macro2::Span)>,
    /// `admin(autocomplete_fields = "author_id")`.
    /// Names of FK fields whose change-form widget renders an
    /// Ajax-driven typeahead populated from a `__autocomplete`
    /// endpoint on the target model. Issue #358.
    autocomplete_fields: Option<(Vec<String>, proc_macro2::Span)>,
    /// `admin(list_select_related = "all" | "none" | "author, …")`
    /// — tunes the admin list view's FK auto-JOIN
    /// policy. Default `"all"` matches rustango's join-everything
    /// behavior; `"none"` opts out; CSV restricts. Issue #352.
    list_select_related: Option<String>,
    /// `admin(formfield_overrides = "field:widget, field2:widget2")`.
    /// Each entry is `field_name:widget_name`; multiple
    /// entries comma-separated. Empty / unset → no overrides. The
    /// list of widget names supported is documented on
    /// `AdminConfig::formfield_overrides`. Issue #359.
    formfield_overrides: Option<(Vec<(String, String)>, proc_macro2::Span)>,
}

fn parse_container_attrs(input: &DeriveInput) -> syn::Result<ContainerAttrs> {
    let mut out = ContainerAttrs {
        table: None,
        display: None,
        app: None,
        admin: None,
        audit: None,
        // Default `permissions = true` so every `#[derive(Model)]`
        // gets the four CRUD codenames seeded by `auto_create_permissions`
        // and is visible to non-superusers in the tenant admin without
        // manual per-model annotation. Models that intentionally don't
        // want permission rows (registry-internal types, framework
        // tables operators shouldn't manage directly) opt out via
        // `#[rustango(permissions = false)]`. v0.27.2 — fixes the
        // out-of-the-box admin invisibility regression (#62).
        permissions: true,
        m2m: Vec::new(),
        generic_m2m: Vec::new(),
        indexes: Vec::new(),
        checks: Vec::new(),
        excludes: Vec::new(),
        composite_fks: Vec::new(),
        generic_fks: Vec::new(),
        scope: None,
        manager_fns: Vec::new(),
        default_order: Vec::new(),
        is_view: false,
        managed: true,
        verbose_name: None,
        verbose_name_plural: None,
        base_manager_name: None,
        order_with_respect_to: None,
        proxy: false,
        required_db_features: Vec::new(),
        required_db_vendor: None,
        default_related_name: None,
        db_table_comment: None,
        get_latest_by: None,
        extra_permissions: Vec::new(),
        default_permissions: Vec::new(),
        global_scopes: Vec::new(),
        through_relations: Vec::new(),
        reverse_has_relations: Vec::new(),
        generic_has_relations: Vec::new(),
    };
    for attr in &input.attrs {
        if !attr.path().is_ident("rustango") {
            continue;
        }
        attr.parse_nested_meta(|meta| {
            if meta.path.is_ident("table") {
                let s: LitStr = meta.value()?.parse()?;
                let name = s.value();
                // v0.27.3 (#65) — macro-time guard against table names
                // that compile but break SQL downstream. Hyphens are
                // the common footgun: PostgreSQL accepts a quoted
                // `"intermediate-region"` in CREATE TABLE, but the
                // FK / index name derivation in `migrate::ddl`
                // emits `intermediate-region_field_fkey` unquoted,
                // which then fails the SQL parser. Same shape rule
                // as Postgres regular identifiers so the safe path
                // is the only path.
                validate_table_name(&name, s.span())?;
                out.table = Some(name);
                return Ok(());
            }
            if meta.path.is_ident("display") {
                let s: LitStr = meta.value()?.parse()?;
                out.display = Some((s.value(), s.span()));
                return Ok(());
            }
            if meta.path.is_ident("app") {
                let s: LitStr = meta.value()?.parse()?;
                out.app = Some(s.value());
                return Ok(());
            }
            if meta.path.is_ident("scope") {
                let s: LitStr = meta.value()?.parse()?;
                let val = s.value();
                if !matches!(val.to_ascii_lowercase().as_str(), "registry" | "tenant") {
                    return Err(meta.error(format!(
                        "`scope` must be \"registry\" or \"tenant\", got {val:?}"
                    )));
                }
                out.scope = Some(val);
                return Ok(());
            }
            if meta.path.is_ident("admin") {
                let mut admin = AdminAttrs::default();
                meta.parse_nested_meta(|inner| {
                    if inner.path.is_ident("list_display") {
                        let s: LitStr = inner.value()?.parse()?;
                        admin.list_display =
                            Some((split_field_list(&s.value()), s.span()));
                        return Ok(());
                    }
                    if inner.path.is_ident("search_fields") {
                        let s: LitStr = inner.value()?.parse()?;
                        admin.search_fields =
                            Some((split_field_list(&s.value()), s.span()));
                        return Ok(());
                    }
                    if inner.path.is_ident("readonly_fields") {
                        let s: LitStr = inner.value()?.parse()?;
                        admin.readonly_fields =
                            Some((split_field_list(&s.value()), s.span()));
                        return Ok(());
                    }
                    if inner.path.is_ident("list_per_page") {
                        let lit: syn::LitInt = inner.value()?.parse()?;
                        admin.list_per_page = Some(lit.base10_parse::<usize>()?);
                        return Ok(());
                    }
                    if inner.path.is_ident("ordering") {
                        let s: LitStr = inner.value()?.parse()?;
                        admin.ordering = Some((
                            parse_ordering_list(&s.value()),
                            s.span(),
                        ));
                        return Ok(());
                    }
                    if inner.path.is_ident("list_filter") {
                        let s: LitStr = inner.value()?.parse()?;
                        admin.list_filter =
                            Some((split_field_list(&s.value()), s.span()));
                        return Ok(());
                    }
                    if inner.path.is_ident("actions") {
                        let s: LitStr = inner.value()?.parse()?;
                        admin.actions =
                            Some((split_field_list(&s.value()), s.span()));
                        return Ok(());
                    }
                    if inner.path.is_ident("fieldsets") {
                        let s: LitStr = inner.value()?.parse()?;
                        admin.fieldsets =
                            Some((parse_fieldset_list(&s.value()), s.span()));
                        return Ok(());
                    }
                    if inner.path.is_ident("list_display_links") {
                        let s: LitStr = inner.value()?.parse()?;
                        admin.list_display_links =
                            Some((split_field_list(&s.value()), s.span()));
                        return Ok(());
                    }
                    if inner.path.is_ident("search_help_text") {
                        let s: LitStr = inner.value()?.parse()?;
                        admin.search_help_text = Some(s.value());
                        return Ok(());
                    }
                    if inner.path.is_ident("actions_on_top") {
                        let lit: syn::LitBool = inner.value()?.parse()?;
                        admin.actions_on_top = Some(lit.value);
                        return Ok(());
                    }
                    if inner.path.is_ident("actions_on_bottom") {
                        let lit: syn::LitBool = inner.value()?.parse()?;
                        admin.actions_on_bottom = Some(lit.value);
                        return Ok(());
                    }
                    if inner.path.is_ident("date_hierarchy") {
                        let s: LitStr = inner.value()?.parse()?;
                        admin.date_hierarchy = Some(s.value());
                        return Ok(());
                    }
                    if inner.path.is_ident("prepopulated_fields") {
                        let s: LitStr = inner.value()?.parse()?;
                        admin.prepopulated_fields =
                            Some((parse_prepopulated_list(&s.value()), s.span()));
                        return Ok(());
                    }
                    if inner.path.is_ident("raw_id_fields") {
                        let s: LitStr = inner.value()?.parse()?;
                        admin.raw_id_fields =
                            Some((split_field_list(&s.value()), s.span()));
                        return Ok(());
                    }
                    if inner.path.is_ident("autocomplete_fields") {
                        let s: LitStr = inner.value()?.parse()?;
                        admin.autocomplete_fields =
                            Some((split_field_list(&s.value()), s.span()));
                        return Ok(());
                    }
                    if inner.path.is_ident("list_select_related") {
                        let s: LitStr = inner.value()?.parse()?;
                        admin.list_select_related = Some(s.value());
                        return Ok(());
                    }
                    if inner.path.is_ident("formfield_overrides") {
                        let s: LitStr = inner.value()?.parse()?;
                        admin.formfield_overrides =
                            Some((parse_formfield_overrides(&s.value()), s.span()));
                        return Ok(());
                    }
                    Err(inner.error(
                        "unknown admin attribute (supported: \
                         `list_display`, `list_display_links`, \
                         `search_fields`, `search_help_text`, \
                         `readonly_fields`, \
                         `list_filter`, `list_per_page`, `ordering`, `actions`, \
                         `actions_on_top`, `actions_on_bottom`, \
                         `date_hierarchy`, \
                         `prepopulated_fields`, \
                         `raw_id_fields`, \
                         `autocomplete_fields`, \
                         `list_select_related`, \
                         `formfield_overrides`, \
                         `fieldsets`)",
                    ))
                })?;
                out.admin = Some(admin);
                return Ok(());
            }
            if meta.path.is_ident("manager") {
                // Its empty trait could not take methods (#2132).
                return Err(meta.error(
                    "`manager(ext = ...)` was removed (#2132): declare your own \
                     `trait FooManagerExt: Sized { … }` and implement it for `QuerySet<Foo>`",
                ));
            }
            if meta.path.is_ident("manager_fn") {
                // `#[rustango(manager_fn = "active")]` — issue #289 / T2.6.
                // Adds a `pub fn <name>() -> QuerySet<Self>` accessor
                // next to the default `Self::objects()`. Multiple
                // attributes accumulate.
                let s: LitStr = meta.value()?.parse()?;
                let name = s.value();
                if name.is_empty() {
                    return Err(meta.error("`manager_fn = \"...\"` cannot be empty"));
                }
                if name == "objects" {
                    return Err(meta.error(
                        "`manager_fn = \"objects\"` collides with the default \
                         accessor — pick a different name",
                    ));
                }
                let ident = syn::Ident::new(&name, s.span());
                if out.manager_fns.iter().any(|prev| *prev == ident) {
                    return Err(meta.error(format!(
                        "duplicate `manager_fn = \"{name}\"`"
                    )));
                }
                out.manager_fns.push(ident);
                return Ok(());
            }
            if meta.path.is_ident("default_order") {
                // `#[rustango(default_order = "-created_at, status")]`
                // — issue #291 / T2.5. Comma-separated list; `-prefix`
                // means descending, `+prefix` or bare name means ascending.
                // Per-query opt-in via `QuerySet::with_default_order()`.
                let s: LitStr = meta.value()?.parse()?;
                let raw = s.value();
                let span = s.span();
                let mut parsed: Vec<(String, bool, proc_macro2::Span)> =
                    Vec::new();
                for entry in raw.split(',') {
                    let trimmed = entry.trim();
                    if trimmed.is_empty() {
                        return Err(syn::Error::new(
                            span,
                            "`default_order = \"...\"` has an empty entry — \
                             check for a stray comma",
                        ));
                    }
                    let (desc, name) = if let Some(rest) = trimmed.strip_prefix('-') {
                        (true, rest.trim().to_owned())
                    } else if let Some(rest) = trimmed.strip_prefix('+') {
                        (false, rest.trim().to_owned())
                    } else {
                        (false, trimmed.to_owned())
                    };
                    if name.is_empty() {
                        return Err(syn::Error::new(
                            span,
                            "`default_order` entry has no column name after the prefix",
                        ));
                    }
                    if parsed.iter().any(|(n, _, _)| *n == name) {
                        return Err(syn::Error::new(
                            span,
                            format!("duplicate column `{name}` in `default_order`"),
                        ));
                    }
                    parsed.push((name, desc, span));
                }
                if parsed.is_empty() {
                    return Err(syn::Error::new(
                        span,
                        "`default_order = \"...\"` cannot be empty",
                    ));
                }
                out.default_order = parsed;
                return Ok(());
            }
            if meta.path.is_ident("global_scope") {
                // `#[rustango(global_scope(name = "active", apply =
                //  path::to::fn))]` — issue #820. The apply function
                // path resolves at macro-expand time in the consumer's
                // scope; the macro re-emits it verbatim into the
                // `ModelSchema::global_scopes` slice literal.
                let span = meta.path.span();
                let mut scope_name: Option<String> = None;
                let mut apply_path: Option<syn::Path> = None;
                meta.parse_nested_meta(|inner| {
                    if inner.path.is_ident("name") {
                        let s: LitStr = inner.value()?.parse()?;
                        let raw = s.value();
                        if raw.trim().is_empty() {
                            return Err(syn::Error::new(
                                s.span(),
                                "`global_scope(name = \"...\")` must not be empty",
                            ));
                        }
                        scope_name = Some(raw);
                        return Ok(());
                    }
                    if inner.path.is_ident("apply") {
                        let p: syn::Path = inner.value()?.parse()?;
                        apply_path = Some(p);
                        return Ok(());
                    }
                    Err(inner.error(
                        "unknown `global_scope` attribute (supported: \
                         `name`, `apply`)",
                    ))
                })?;
                let Some(name) = scope_name else {
                    return Err(syn::Error::new(
                        span,
                        "`global_scope` requires `name = \"...\"`",
                    ));
                };
                let Some(apply) = apply_path else {
                    return Err(syn::Error::new(
                        span,
                        "`global_scope` requires `apply = fn_path`",
                    ));
                };
                if out.global_scopes.iter().any(|s| s.name == name) {
                    return Err(syn::Error::new(
                        span,
                        format!(
                            "duplicate global scope name `{name}` — \
                             pick a unique identifier so \
                             `QuerySet::without_global_scope(\"{name}\")` \
                             is unambiguous"
                        ),
                    ));
                }
                out.global_scopes.push(GlobalScopeAttr { name, apply });
                return Ok(());
            }
            if meta.path.is_ident("through") {
                // `#[rustango(through(name = "posts", far = "Post",
                //  far_fk_column = "author_id", intermediate = "User",
                //  intermediate_fk_column = "country_id"
                //  [, intermediate_pk_column = "id"]))]` — issue #817.
                let span = meta.path.span();
                let mut accessor_name: Option<String> = None;
                let mut far_ident: Option<syn::Ident> = None;
                let mut far_fk_column: Option<String> = None;
                let mut intermediate_ident: Option<syn::Ident> = None;
                let mut intermediate_fk_column: Option<String> = None;
                let mut intermediate_pk_column: Option<String> = None;
                fn parse_nonempty_string(
                    inner: &syn::meta::ParseNestedMeta<'_>,
                    field: &str,
                ) -> syn::Result<String> {
                    let s: LitStr = inner.value()?.parse()?;
                    let raw = s.value();
                    let trimmed = raw.trim();
                    if trimmed.is_empty() {
                        return Err(syn::Error::new(
                            s.span(),
                            format!("`through({field} = \"...\")` must not be empty"),
                        ));
                    }
                    Ok(trimmed.to_owned())
                }
                meta.parse_nested_meta(|inner| {
                    if inner.path.is_ident("name") {
                        accessor_name = Some(parse_nonempty_string(&inner, "name")?);
                        return Ok(());
                    }
                    if inner.path.is_ident("far") {
                        // Far model name accepted as a string literal
                        // so the attribute fits inside the existing
                        // `parse_nested_meta` shape; parsed back into a
                        // `syn::Ident` so the emitted accessor can
                        // reference the type directly.
                        let s: LitStr = inner.value()?.parse()?;
                        let raw = s.value();
                        let trimmed = raw.trim();
                        if trimmed.is_empty() {
                            return Err(syn::Error::new(
                                s.span(),
                                "`through(far = \"...\")` must not be empty",
                            ));
                        }
                        far_ident = Some(syn::Ident::new(trimmed, s.span()));
                        return Ok(());
                    }
                    if inner.path.is_ident("far_fk_column") {
                        far_fk_column =
                            Some(parse_nonempty_string(&inner, "far_fk_column")?);
                        return Ok(());
                    }
                    if inner.path.is_ident("intermediate") {
                        let s: LitStr = inner.value()?.parse()?;
                        let raw = s.value();
                        let trimmed = raw.trim();
                        if trimmed.is_empty() {
                            return Err(syn::Error::new(
                                s.span(),
                                "`through(intermediate = \"...\")` must not be empty",
                            ));
                        }
                        intermediate_ident = Some(syn::Ident::new(trimmed, s.span()));
                        return Ok(());
                    }
                    if inner.path.is_ident("intermediate_fk_column") {
                        intermediate_fk_column =
                            Some(parse_nonempty_string(&inner, "intermediate_fk_column")?);
                        return Ok(());
                    }
                    if inner.path.is_ident("intermediate_pk_column") {
                        intermediate_pk_column =
                            Some(parse_nonempty_string(&inner, "intermediate_pk_column")?);
                        return Ok(());
                    }
                    Err(inner.error(
                        "unknown `through` attribute (supported: \
                         `name`, `far`, `far_fk_column`, \
                         `intermediate`, `intermediate_fk_column`, \
                         `intermediate_pk_column`)",
                    ))
                })?;
                let Some(name) = accessor_name else {
                    return Err(syn::Error::new(
                        span,
                        "`through` requires `name = \"...\"`",
                    ));
                };
                let Some(far) = far_ident else {
                    return Err(syn::Error::new(
                        span,
                        "`through` requires `far = \"FarModelType\"`",
                    ));
                };
                let Some(far_fk_column) = far_fk_column else {
                    return Err(syn::Error::new(
                        span,
                        "`through` requires `far_fk_column = \"<column>\"`",
                    ));
                };
                let Some(intermediate) = intermediate_ident else {
                    return Err(syn::Error::new(
                        span,
                        "`through` requires `intermediate = \"IntermediateModelType\"`",
                    ));
                };
                let Some(intermediate_fk_column) = intermediate_fk_column else {
                    return Err(syn::Error::new(
                        span,
                        "`through` requires `intermediate_fk_column = \"<column>\"`",
                    ));
                };
                let intermediate_pk_column =
                    intermediate_pk_column.unwrap_or_else(|| "id".to_owned());
                if out.through_relations.iter().any(|t| t.name == name) {
                    return Err(syn::Error::new(
                        span,
                        format!(
                            "duplicate `through(name = \"{name}\")` — \
                             pick a unique accessor name"
                        ),
                    ));
                }
                out.through_relations.push(ThroughAttr {
                    name,
                    far,
                    far_fk_column,
                    intermediate,
                    intermediate_fk_column,
                    intermediate_pk_column,
                });
                return Ok(());
            }
            if meta.path.is_ident("reverse_has") {
                // `#[rustango(reverse_has(name = "comments",
                //  child = "Comment", child_fk_column = "post_id"
                //  [, self_pk_column = "id"]))]` — issue #830.
                let span = meta.path.span();
                let mut accessor_name: Option<String> = None;
                let mut child_ident: Option<syn::Ident> = None;
                let mut child_fk_column: Option<String> = None;
                let mut self_pk_column: Option<String> = None;
                meta.parse_nested_meta(|inner| {
                    if inner.path.is_ident("name") {
                        let s: LitStr = inner.value()?.parse()?;
                        let raw = s.value();
                        if raw.trim().is_empty() {
                            return Err(syn::Error::new(
                                s.span(),
                                "`reverse_has(name = \"...\")` must not be empty",
                            ));
                        }
                        accessor_name = Some(raw);
                        return Ok(());
                    }
                    if inner.path.is_ident("child") {
                        let s: LitStr = inner.value()?.parse()?;
                        let raw = s.value();
                        let trimmed = raw.trim();
                        if trimmed.is_empty() {
                            return Err(syn::Error::new(
                                s.span(),
                                "`reverse_has(child = \"...\")` must not be empty",
                            ));
                        }
                        child_ident = Some(syn::Ident::new(trimmed, s.span()));
                        return Ok(());
                    }
                    if inner.path.is_ident("child_fk_column") {
                        let s: LitStr = inner.value()?.parse()?;
                        let raw = s.value();
                        let trimmed = raw.trim();
                        if trimmed.is_empty() {
                            return Err(syn::Error::new(
                                s.span(),
                                "`reverse_has(child_fk_column = \"...\")` must not be empty",
                            ));
                        }
                        child_fk_column = Some(trimmed.to_owned());
                        return Ok(());
                    }
                    if inner.path.is_ident("self_pk_column") {
                        let s: LitStr = inner.value()?.parse()?;
                        let raw = s.value();
                        let trimmed = raw.trim();
                        if trimmed.is_empty() {
                            return Err(syn::Error::new(
                                s.span(),
                                "`reverse_has(self_pk_column = \"...\")` must not be empty",
                            ));
                        }
                        self_pk_column = Some(trimmed.to_owned());
                        return Ok(());
                    }
                    Err(inner.error(
                        "unknown `reverse_has` attribute (supported: \
                         `name`, `child`, `child_fk_column`, \
                         `self_pk_column`)",
                    ))
                })?;
                let Some(name) = accessor_name else {
                    return Err(syn::Error::new(
                        span,
                        "`reverse_has` requires `name = \"...\"`",
                    ));
                };
                let Some(child) = child_ident else {
                    return Err(syn::Error::new(
                        span,
                        "`reverse_has` requires `child = \"ChildModelType\"`",
                    ));
                };
                let Some(child_fk_column) = child_fk_column else {
                    return Err(syn::Error::new(
                        span,
                        "`reverse_has` requires `child_fk_column = \"<column>\"`",
                    ));
                };
                let self_pk_column = self_pk_column.unwrap_or_else(|| "id".to_owned());
                if out.reverse_has_relations.iter().any(|r| r.name == name) {
                    return Err(syn::Error::new(
                        span,
                        format!(
                            "duplicate `reverse_has(name = \"{name}\")` — \
                             pick a unique accessor name"
                        ),
                    ));
                }
                out.reverse_has_relations.push(ReverseHasAttr {
                    name,
                    child,
                    child_fk_column,
                    self_pk_column,
                });
                return Ok(());
            }
            if meta.path.is_ident("generic_has") {
                // `#[rustango(generic_has(name = "tags",
                //  child = "Tag", ct_column = "content_type_id",
                //  pk_column = "object_pk" [, self_pk_column = "id"]))]`
                //  — issue #830, the reverse generic-FK (GFK) arm of the
                //  relation-existence family.
                let span = meta.path.span();
                let mut accessor_name: Option<String> = None;
                let mut child_ident: Option<syn::Ident> = None;
                let mut ct_column: Option<String> = None;
                let mut pk_column: Option<String> = None;
                let mut self_pk_column: Option<String> = None;
                meta.parse_nested_meta(|inner| {
                    if inner.path.is_ident("name") {
                        let s: LitStr = inner.value()?.parse()?;
                        let raw = s.value();
                        if raw.trim().is_empty() {
                            return Err(syn::Error::new(
                                s.span(),
                                "`generic_has(name = \"...\")` must not be empty",
                            ));
                        }
                        accessor_name = Some(raw);
                        return Ok(());
                    }
                    if inner.path.is_ident("child") {
                        let s: LitStr = inner.value()?.parse()?;
                        let trimmed = s.value().trim().to_owned();
                        if trimmed.is_empty() {
                            return Err(syn::Error::new(
                                s.span(),
                                "`generic_has(child = \"...\")` must not be empty",
                            ));
                        }
                        child_ident = Some(syn::Ident::new(&trimmed, s.span()));
                        return Ok(());
                    }
                    if inner.path.is_ident("ct_column") {
                        let s: LitStr = inner.value()?.parse()?;
                        let trimmed = s.value().trim().to_owned();
                        if trimmed.is_empty() {
                            return Err(syn::Error::new(
                                s.span(),
                                "`generic_has(ct_column = \"...\")` must not be empty",
                            ));
                        }
                        ct_column = Some(trimmed);
                        return Ok(());
                    }
                    if inner.path.is_ident("pk_column") {
                        let s: LitStr = inner.value()?.parse()?;
                        let trimmed = s.value().trim().to_owned();
                        if trimmed.is_empty() {
                            return Err(syn::Error::new(
                                s.span(),
                                "`generic_has(pk_column = \"...\")` must not be empty",
                            ));
                        }
                        pk_column = Some(trimmed);
                        return Ok(());
                    }
                    if inner.path.is_ident("self_pk_column") {
                        let s: LitStr = inner.value()?.parse()?;
                        let trimmed = s.value().trim().to_owned();
                        if trimmed.is_empty() {
                            return Err(syn::Error::new(
                                s.span(),
                                "`generic_has(self_pk_column = \"...\")` must not be empty",
                            ));
                        }
                        self_pk_column = Some(trimmed);
                        return Ok(());
                    }
                    Err(inner.error(
                        "unknown `generic_has` attribute (supported: \
                         `name`, `child`, `ct_column`, `pk_column`, \
                         `self_pk_column`)",
                    ))
                })?;
                let Some(name) = accessor_name else {
                    return Err(syn::Error::new(
                        span,
                        "`generic_has` requires `name = \"...\"`",
                    ));
                };
                let Some(child) = child_ident else {
                    return Err(syn::Error::new(
                        span,
                        "`generic_has` requires `child = \"ChildModelType\"`",
                    ));
                };
                let ct_column = ct_column.unwrap_or_else(|| "content_type_id".to_owned());
                let pk_column = pk_column.unwrap_or_else(|| "object_pk".to_owned());
                let self_pk_column = self_pk_column.unwrap_or_else(|| "id".to_owned());
                if out.generic_has_relations.iter().any(|r| r.name == name) {
                    return Err(syn::Error::new(
                        span,
                        format!(
                            "duplicate `generic_has(name = \"{name}\")` — \
                             pick a unique accessor name"
                        ),
                    ));
                }
                out.generic_has_relations.push(GenericHasAttr {
                    name,
                    child,
                    ct_column,
                    pk_column,
                    self_pk_column,
                });
                return Ok(());
            }
            if meta.path.is_ident("audit") {
                let mut audit = AuditAttrs::default();
                meta.parse_nested_meta(|inner| {
                    if inner.path.is_ident("track") {
                        let s: LitStr = inner.value()?.parse()?;
                        audit.track =
                            Some((split_field_list(&s.value()), s.span()));
                        return Ok(());
                    }
                    Err(inner.error(
                        "unknown audit attribute (supported: `track`)",
                    ))
                })?;
                out.audit = Some(audit);
                return Ok(());
            }
            if meta.path.is_ident("permissions") {
                // Two forms accepted:
                //   #[rustango(permissions)]          — flag form, true
                //   #[rustango(permissions = false)]  — explicit opt-out
                //   #[rustango(permissions = true)]   — explicit opt-in
                if let Ok(v) = meta.value() {
                    let lit: syn::LitBool = v.parse()?;
                    out.permissions = lit.value;
                } else {
                    out.permissions = true;
                }
                return Ok(());
            }
            if meta.path.is_ident("view") {
                // Issue #293 / T2.10. Two forms accepted, matching
                // the `permissions` flag pattern:
                //   #[rustango(view)]          — flag form, true
                //   #[rustango(view = false)]  — explicit opt-out
                //   #[rustango(view = true)]   — explicit opt-in
                if let Ok(v) = meta.value() {
                    let lit: syn::LitBool = v.parse()?;
                    out.is_view = lit.value;
                } else {
                    out.is_view = true;
                }
                return Ok(());
            }
            if meta.path.is_ident("managed") {
                // Who owns the table. Issue #321.
                //   #[rustango(managed = false)]  — operator-managed table
                //   #[rustango(managed = true)]   — rustango-managed (the default)
                // Bare-flag form is intentionally not accepted: writing
                // `#[rustango(managed)]` reads as "yes please manage it"
                // which is already the default. The opt-out is the only
                // useful state, so it must be explicit.
                let v = meta.value()?;
                let lit: syn::LitBool = v.parse()?;
                out.managed = lit.value;
                return Ok(());
            }
            if meta.path.is_ident("verbose_name") {
                let s: LitStr = meta.value()?.parse()?;
                out.verbose_name = Some(s.value());
                return Ok(());
            }
            if meta.path.is_ident("verbose_name_plural") {
                let s: LitStr = meta.value()?.parse()?;
                out.verbose_name_plural = Some(s.value());
                return Ok(());
            }
            if meta.path.is_ident("db_table_comment") {
                // Free-form table-level comment attached to the DB
                // catalog.
                let s: LitStr = meta.value()?.parse()?;
                out.db_table_comment = Some(s.value());
                return Ok(());
            }
            if meta.path.is_ident("proxy") {
                // Declarative flag
                // marking the struct as a proxy of another model that
                // shares its DB table. Stored on `ModelSchema::proxy`
                // so future codegen can skip `CreateTable` emission
                // for proxies (parent owns the table) and route
                // per-instance method resolution to the proxy class.
                //
                // Accepts `proxy` (bare → true) and `proxy = true/false`.
                let value = if meta.input.peek(syn::Token![=]) {
                    meta.value()?.parse::<syn::LitBool>()?.value
                } else {
                    true
                };
                out.proxy = value;
                return Ok(());
            }
            if meta.path.is_ident("order_with_respect_to") {
                // `order_with_respect_to = "parent_fk"` — the model's
                // instances are intrinsically ordered relative to
                // their parent FK.
                //
                // rustango stores the FK field name on
                // `ModelSchema::order_with_respect_to`. Declarative-only
                // today: the migration writer + admin surfaces still
                // treat every model identically. Future codegen will
                // key off the metadata to auto-emit the `_order`
                // column and reorder helpers.
                //
                // Validated as a Rust-shape identifier so the macro
                // can reject typos at derive time.
                let s: LitStr = meta.value()?.parse()?;
                let raw = s.value();
                if raw.is_empty() {
                    return Err(syn::Error::new(
                        s.span(),
                        "`order_with_respect_to` must be a non-empty FK field name",
                    ));
                }
                let valid = raw
                    .chars()
                    .all(|c| c == '_' || c.is_ascii_alphanumeric())
                    && !raw.chars().next().is_some_and(|c| c.is_ascii_digit());
                if !valid {
                    return Err(syn::Error::new(
                        s.span(),
                        format!(
                            "`order_with_respect_to` must be a valid Rust \
                             identifier (letters / digits / underscores, \
                             not starting with a digit); got `{raw}`"
                        ),
                    ));
                }
                out.order_with_respect_to = Some(raw);
                return Ok(());
            }
            if meta.path.is_ident("required_db_features") {
                // Capability tokens the model needs (e.g.
                // `"json_extract"`, `"window_functions"`,
                // `"row_security"`). Comma-separated.
                // `manage check --deploy` walks every model and warns
                // when the active backend doesn't advertise the
                // capability.
                //
                // rustango ships a small registry of capability tokens
                // each dialect supports — see `Dialect::supports`.
                // Unknown tokens still parse (they end up on the
                // schema and show up in the warning) so projects can
                // declare aspirational capabilities and the check
                // verb will keep nagging until the dialect implements
                // them.
                let s: LitStr = meta.value()?.parse()?;
                let raw = s.value();
                let features: Vec<String> = raw
                    .split(',')
                    .map(str::trim)
                    .filter(|s| !s.is_empty())
                    .map(str::to_owned)
                    .collect();
                if features.is_empty() {
                    return Err(syn::Error::new(
                        s.span(),
                        "`required_db_features` must list at least one \
                         comma-separated capability token",
                    ));
                }
                out.required_db_features = features;
                return Ok(());
            }
            if meta.path.is_ident("required_db_vendor") {
                // The model is only meant to run against the named DB
                // backend. `manage check --deploy` flags a mismatch so
                // ops catches "I forgot to switch DATABASE_URL" at
                // deploy time rather than runtime.
                //
                // Restricted to the three backends rustango ships
                // dialects for so the check verb can compare reliably.
                let s: LitStr = meta.value()?.parse()?;
                let raw = s.value().to_ascii_lowercase();
                match raw.as_str() {
                    "postgresql" | "postgres" | "pg" => {
                        out.required_db_vendor = Some("postgres".to_owned());
                    }
                    "mysql" | "mariadb" => {
                        out.required_db_vendor = Some("mysql".to_owned());
                    }
                    "sqlite" | "sqlite3" => {
                        out.required_db_vendor = Some("sqlite".to_owned());
                    }
                    _ => {
                        return Err(syn::Error::new(
                            s.span(),
                            format!(
                                "unknown required_db_vendor `{raw}` — \
                                 expected `postgres` (aliases: `postgresql`, `pg`), \
                                 `mysql` (alias: `mariadb`), or `sqlite` \
                                 (alias: `sqlite3`)"
                            ),
                        ));
                    }
                }
                return Ok(());
            }
            if meta.path.is_ident("base_manager_name") {
                // Name of the manager that `<instance>.<relation>_set`
                // uses when resolving reverse-relation managers.
                // Distinct from `default_manager_name` (what
                // `Self::objects()` returns). Stored on
                // `ModelSchema::base_manager_name`.
                //
                // Validated as a Rust identifier so it stays safe to
                // re-emit as code in future reverse-manager codegen.
                let s: LitStr = meta.value()?.parse()?;
                let raw = s.value();
                if raw.is_empty() {
                    return Err(syn::Error::new(
                        s.span(),
                        "`base_manager_name` must be a non-empty string",
                    ));
                }
                let valid = raw
                    .chars()
                    .all(|c| c == '_' || c.is_ascii_alphanumeric())
                    && !raw.chars().next().is_some_and(|c| c.is_ascii_digit());
                if !valid {
                    return Err(syn::Error::new(
                        s.span(),
                        format!(
                            "`base_manager_name` must be a valid Rust \
                             identifier (letters / digits / underscores, \
                             not starting with a digit); got `{raw}`"
                        ),
                    ));
                }
                out.base_manager_name = Some(raw);
                return Ok(());
            }
            if meta.path.is_ident("default_related_name") {
                // The name reverse-relation accessors use when callers
                // don't override `related_name = "..."` on the FK / M2M
                // field. Stored on `ModelSchema::default_related_name`
                // so future reverse-manager codegen / schema emit /
                // admin templates can pick the right accessor name
                // (today rustango doesn't auto-emit reverse managers;
                // the metadata is the foundation for that work).
                //
                // Enforced non-empty + ASCII identifier-shape so the
                // string is safe to use as a Rust ident later.
                let s: LitStr = meta.value()?.parse()?;
                let raw = s.value();
                if raw.is_empty() {
                    return Err(syn::Error::new(
                        s.span(),
                        "`default_related_name` must be a non-empty string",
                    ));
                }
                let valid = raw
                    .chars()
                    .all(|c| c == '_' || c.is_ascii_lowercase() || c.is_ascii_digit())
                    && !raw.chars().next().is_some_and(|c| c.is_ascii_digit());
                if !valid {
                    return Err(syn::Error::new(
                        s.span(),
                        format!(
                            "`default_related_name` must be snake_case ASCII \
                             (lowercase letters / digits / underscores, not \
                             starting with a digit); got `{raw}`"
                        ),
                    ));
                }
                out.default_related_name = Some(raw);
                return Ok(());
            }
            if meta.path.is_ident("extra_permissions") {
                // Comma-separated `codename:label` pairs.
                let s: LitStr = meta.value()?.parse()?;
                let raw = s.value();
                let mut pairs = Vec::new();
                for entry in raw.split(',') {
                    let entry = entry.trim();
                    if entry.is_empty() {
                        continue;
                    }
                    let (codename, label) = match entry.split_once(':') {
                        Some((c, l)) => (c.trim().to_owned(), l.trim().to_owned()),
                        None => (entry.to_owned(), entry.to_owned()),
                    };
                    if codename.is_empty() {
                        return Err(meta.error(
                            "`extra_permissions` entries must be `codename:label` pairs",
                        ));
                    }
                    pairs.push((codename, label));
                }
                if pairs.is_empty() {
                    return Err(meta
                        .error("`extra_permissions = \"…\"` must list at least one pair"));
                }
                out.extra_permissions = pairs;
                return Ok(());
            }
            if meta.path.is_ident("default_permissions") {
                // Comma-separated subset of the CRUD action set.
                // Empty means all four (the framework default).
                let s: LitStr = meta.value()?.parse()?;
                let raw = s.value();
                let mut actions: Vec<String> = Vec::new();
                for entry in raw.split(',') {
                    let action = entry.trim().to_ascii_lowercase();
                    if action.is_empty() {
                        continue;
                    }
                    match action.as_str() {
                        "add" | "change" | "delete" | "view" => {}
                        other => {
                            return Err(syn::Error::new(
                                s.span(),
                                format!(
                                    "unknown default_permissions action `{other}` — \
                                     expected one of `add`, `change`, `delete`, `view`"
                                ),
                            ));
                        }
                    }
                    if !actions.contains(&action) {
                        actions.push(action);
                    }
                }
                if actions.is_empty() {
                    return Err(syn::Error::new(
                        s.span(),
                        "`default_permissions = \"…\"` must list at least one action; \
                         use `permissions = false` on the container if you want NO \
                         permissions seeded for this model.",
                    ));
                }
                out.default_permissions = actions;
                return Ok(());
            }
            if meta.path.is_ident("get_latest_by") {
                // The `-` prefix selects descending order.
                let s: LitStr = meta.value()?.parse()?;
                let raw = s.value();
                let trimmed = raw.trim();
                if trimmed.is_empty() {
                    return Err(meta.error("`get_latest_by` must name a column"));
                }
                let (col, desc) = if let Some(stripped) = trimmed.strip_prefix('-') {
                    (stripped.to_owned(), true)
                } else if let Some(stripped) = trimmed.strip_prefix('+') {
                    (stripped.to_owned(), false)
                } else {
                    (trimmed.to_owned(), false)
                };
                if col.is_empty() {
                    return Err(meta.error("`get_latest_by` must name a column"));
                }
                out.get_latest_by = Some((col, desc));
                return Ok(());
            }
            if meta.path.is_ident("unique_together") {
                // Composite UNIQUE index. Two syntaxes:
                //
                //   #[rustango(unique_together = "org_id, user_id")]                       — auto-derived name
                //   #[rustango(unique_together(columns = "org_id, user_id", name = "x"))]  — explicit name
                //
                // Both produce `CREATE UNIQUE INDEX <name> ON <table>
                // (col1, col2)`, where <name> defaults to
                // `<table>_<col1>_<col2>_uq` when not supplied.
                let (columns, name) = parse_together_attr(&meta, "unique_together")?;
                out.indexes.push(IndexAttr {
                    name,
                    columns,
                    unique: true,
                    method: "btree".to_owned(),
                    where_clause: None,
                include: Vec::new(),
                });
                return Ok(());
            }
            if meta.path.is_ident("index_together") {
                // Composite (non-unique) index. Two syntaxes
                // mirroring `unique_together`.
                //
                //   #[rustango(index_together = "created_at, status")]
                //   #[rustango(index_together(columns = "created_at, status", name = "x"))]
                let (columns, name) = parse_together_attr(&meta, "index_together")?;
                out.indexes.push(IndexAttr {
                    name,
                    columns,
                    unique: false,
                    method: "btree".to_owned(),
                    where_clause: None,
                include: Vec::new(),
                });
                return Ok(());
            }
            if meta.path.is_ident("unique_when") {
                // Partial unique index. Issue #265 / T1.3.
                //
                //   #[rustango(unique_when(
                //       columns   = "email",
                //       condition = "deleted_at IS NULL",
                //       name      = "unique_active_email"
                //   ))]
                //
                // → `CREATE UNIQUE INDEX <name> ON <table> (cols) WHERE <condition>`
                // on PG / SQLite (both ship partial indexes natively).
                // MySQL falls back to a plain UNIQUE index — the
                // condition is lost; document the limitation in the
                // generated migration.
                let mut columns: Option<Vec<String>> = None;
                let mut condition: Option<String> = None;
                let mut name: Option<String> = None;
                let mut include: Vec<String> = Vec::new();
                meta.parse_nested_meta(|inner| {
                    if inner.path.is_ident("columns") {
                        let s: LitStr = inner.value()?.parse()?;
                        columns = Some(split_field_list(&s.value()));
                        return Ok(());
                    }
                    if inner.path.is_ident("condition") {
                        let s: LitStr = inner.value()?.parse()?;
                        condition = Some(s.value());
                        return Ok(());
                    }
                    if inner.path.is_ident("name") {
                        let s: LitStr = inner.value()?.parse()?;
                        name = Some(s.value());
                        return Ok(());
                    }
                    if inner.path.is_ident("include") {
                        // PG 11+ covering-index columns. Non-key columns
                        // travel with the index leaf for index-only
                        // scans. Dropped on MySQL/SQLite by the writer.
                        let s: LitStr = inner.value()?.parse()?;
                        include = split_field_list(&s.value());
                        return Ok(());
                    }
                    Err(inner.error(
                        "unknown unique_when attribute (supported: \
                         `columns = \"...\"`, `condition = \"...\"`, \
                         `name = \"...\"`, `include = \"...\"`)",
                    ))
                })?;
                let columns = columns.ok_or_else(|| {
                    meta.error("`unique_when(...)` requires `columns = \"...\"`")
                })?;
                let condition = condition.ok_or_else(|| {
                    meta.error("`unique_when(...)` requires `condition = \"...\"`")
                })?;
                if columns.is_empty() {
                    return Err(meta.error("`unique_when(columns = \"\")` is empty"));
                }
                out.indexes.push(IndexAttr {
                    name,
                    columns,
                    unique: true,
                    method: "btree".to_owned(),
                    where_clause: Some(condition),
                    include,
                });
                return Ok(());
            }
            if meta.path.is_ident("index_when") {
                // Non-unique partial index. Sibling of `unique_when`
                // (which emits `CREATE UNIQUE INDEX ... WHERE ...`).
                //
                //   #[rustango(index_when(
                //       columns   = "status, created_at",
                //       condition = "deleted_at IS NULL",
                //       name      = "active_status_created_idx"
                //   ))]
                //
                // → `CREATE INDEX <name> ON <table> (cols) WHERE <condition>`
                // on PG / SQLite (both ship partial indexes natively).
                // MySQL has no native partial-index support — the writer
                // emits a plain CREATE INDEX and the condition is lost;
                // operators wanting that selectivity on MySQL should
                // declare a covering index plus an application-level
                // filter.
                let mut columns: Option<Vec<String>> = None;
                let mut condition: Option<String> = None;
                let mut name: Option<String> = None;
                let mut method: String = "btree".to_owned();
                let mut include: Vec<String> = Vec::new();
                meta.parse_nested_meta(|inner| {
                    if inner.path.is_ident("columns") {
                        let s: LitStr = inner.value()?.parse()?;
                        columns = Some(split_field_list(&s.value()));
                        return Ok(());
                    }
                    if inner.path.is_ident("condition") {
                        let s: LitStr = inner.value()?.parse()?;
                        condition = Some(s.value());
                        return Ok(());
                    }
                    if inner.path.is_ident("name") {
                        let s: LitStr = inner.value()?.parse()?;
                        name = Some(s.value());
                        return Ok(());
                    }
                    if inner.path.is_ident("method") {
                        let s: LitStr = inner.value()?.parse()?;
                        method = s.value();
                        return Ok(());
                    }
                    if inner.path.is_ident("include") {
                        // PG 11+ covering-index columns; non-key
                        // columns travel with the index leaf. Dropped
                        // on MySQL/SQLite.
                        let s: LitStr = inner.value()?.parse()?;
                        include = split_field_list(&s.value());
                        return Ok(());
                    }
                    Err(inner.error(
                        "unknown index_when attribute (supported: \
                         `columns = \"...\"`, `condition = \"...\"`, \
                         `name = \"...\"`, `method = \"btree|gin|gist|...\"`, \
                         `include = \"...\"`)",
                    ))
                })?;
                let columns = columns
                    .ok_or_else(|| meta.error("`index_when(...)` requires `columns = \"...\"`"))?;
                let condition = condition.ok_or_else(|| {
                    meta.error("`index_when(...)` requires `condition = \"...\"`")
                })?;
                if columns.is_empty() {
                    return Err(meta.error("`index_when(columns = \"\")` is empty"));
                }
                out.indexes.push(IndexAttr {
                    name,
                    columns,
                    unique: false,
                    method,
                    where_clause: Some(condition),
                    include,
                });
                return Ok(());
            }
            if meta.path.is_ident("index") {
                // Container-level composite index. Two syntaxes:
                //   #[rustango(index = "col1, col2")]   — bare, non-unique btree
                //   #[rustango(index("col1, col2"))]    — call form (same result)
                //   #[rustango(index("col1, col2", unique, name = "my_idx", method = "gin"))]
                // The call form takes the column list as a leading string
                // literal, then optional `unique` / `name = "..."` /
                // `method = "..."` flags (a leading literal can't compose
                // under `parse_nested_meta`, so the paren body is parsed by
                // hand). `unique_together` / `index_together` remain
                // aliases for the same feature.
                let cols_lit: LitStr;
                let mut unique = false;
                let mut name: Option<String> = None;
                let mut method = "btree".to_owned();
                if meta.input.peek(syn::token::Paren) {
                    let content;
                    syn::parenthesized!(content in meta.input);
                    cols_lit = content.parse()?;
                    while content.peek(syn::Token![,]) {
                        content.parse::<syn::Token![,]>()?;
                        if content.is_empty() {
                            break;
                        }
                        let flag: syn::Ident = content.parse()?;
                        if flag == "unique" {
                            unique = true;
                        } else if flag == "name" {
                            content.parse::<syn::Token![=]>()?;
                            let s: LitStr = content.parse()?;
                            name = Some(s.value());
                        } else if flag == "method" {
                            content.parse::<syn::Token![=]>()?;
                            let s: LitStr = content.parse()?;
                            let v = s.value();
                            match v.as_str() {
                                "btree" | "gin" | "gist" | "brin" | "spgist" | "hash"
                                | "bloom" => method = v,
                                other => {
                                    return Err(syn::Error::new(
                                        s.span(),
                                        format!("unknown index method `{other}` (supported: btree, gin, gist, brin, spgist, hash, bloom)"),
                                    ));
                                }
                            }
                        } else {
                            return Err(syn::Error::new(
                                flag.span(),
                                "unknown index flag (supported: `unique`, `name`, `method`)",
                            ));
                        }
                    }
                } else {
                    cols_lit = meta.value()?.parse()?;
                }
                let columns = split_field_list(&cols_lit.value());
                out.indexes.push(IndexAttr {
                    name,
                    columns,
                    unique,
                    method,
                    where_clause: None,
                    include: Vec::new(),
                });
                return Ok(());
            }
            if meta.path.is_ident("check") {
                // #[rustango(check(name = "…", expr = "…"))]
                let mut name: Option<String> = None;
                let mut expr: Option<String> = None;
                meta.parse_nested_meta(|inner| {
                    if inner.path.is_ident("name") {
                        let s: LitStr = inner.value()?.parse()?;
                        name = Some(s.value());
                        return Ok(());
                    }
                    if inner.path.is_ident("expr") {
                        let s: LitStr = inner.value()?.parse()?;
                        expr = Some(s.value());
                        return Ok(());
                    }
                    Err(inner.error("unknown check attribute (supported: `name`, `expr`)"))
                })?;
                let name = name.ok_or_else(|| meta.error("check requires `name = \"...\"`"))?;
                let expr = expr.ok_or_else(|| meta.error("check requires `expr = \"...\"`"))?;
                out.checks.push(CheckAttr { name, expr });
                return Ok(());
            }
            if meta.path.is_ident("exclude") {
                // #[rustango(exclude(name = "…", using = "gist",
                //                    elements = "col WITH op, col WITH op",
                //                    where = "…"))]
                let mut name: Option<String> = None;
                let mut using: Option<String> = None;
                let mut elements_raw: Option<(String, proc_macro2::Span)> = None;
                let mut where_clause: Option<String> = None;
                meta.parse_nested_meta(|inner| {
                    if inner.path.is_ident("name") {
                        let s: LitStr = inner.value()?.parse()?;
                        name = Some(s.value());
                        return Ok(());
                    }
                    if inner.path.is_ident("using") {
                        let s: LitStr = inner.value()?.parse()?;
                        using = Some(s.value());
                        return Ok(());
                    }
                    if inner.path.is_ident("elements") {
                        let s: LitStr = inner.value()?.parse()?;
                        elements_raw = Some((s.value(), s.span()));
                        return Ok(());
                    }
                    if inner.path.is_ident("where") || inner.path.is_ident("where_clause") {
                        let s: LitStr = inner.value()?.parse()?;
                        where_clause = Some(s.value());
                        return Ok(());
                    }
                    Err(inner.error(
                        "unknown exclude attribute (supported: `name`, `using`, `elements`, `where`)",
                    ))
                })?;
                let name = name.ok_or_else(|| meta.error("exclude requires `name = \"...\"`"))?;
                let using = using.unwrap_or_else(|| "gist".to_owned());
                let (elements_str, elements_span) = elements_raw.ok_or_else(|| {
                    meta.error(
                        "exclude requires `elements = \"col WITH op, col WITH op\"`",
                    )
                })?;
                // Parse `col WITH op` pairs separated by commas.
                let mut elements: Vec<(String, String)> = Vec::new();
                for pair in elements_str.split(',') {
                    let pair = pair.trim();
                    if pair.is_empty() {
                        continue;
                    }
                    let mut split = pair.splitn(2, |c: char| c.is_whitespace());
                    let col = split.next().unwrap_or("").trim();
                    let rest = split.next().unwrap_or("").trim();
                    // `WITH op` — case-insensitive on `WITH`, then op.
                    let rest_lc = rest.to_ascii_lowercase();
                    let op = rest_lc
                        .strip_prefix("with")
                        .map(|r| r.trim_start())
                        .filter(|r| !r.is_empty())
                        .map(|_| {
                            // Pull the original-case op from `rest` after the
                            // `WITH ` token (5 chars).
                            rest[4..].trim_start().to_owned()
                        });
                    let Some(op) = op else {
                        return Err(syn::Error::new(
                            elements_span,
                            format!(
                                "exclude elements: `{pair}` must be `<col> WITH <op>` \
                                 (e.g. `room_id WITH =` or `during WITH &&`)"
                            ),
                        ));
                    };
                    if col.is_empty() || op.is_empty() {
                        return Err(syn::Error::new(
                            elements_span,
                            format!(
                                "exclude elements: `{pair}` must be `<col> WITH <op>` \
                                 (both sides non-empty)"
                            ),
                        ));
                    }
                    elements.push((col.to_owned(), op));
                }
                if elements.is_empty() {
                    return Err(syn::Error::new(
                        elements_span,
                        "exclude requires at least one `col WITH op` element",
                    ));
                }
                out.excludes.push(ExcludeAttr {
                    name,
                    using,
                    elements,
                    where_clause,
                });
                return Ok(());
            }
            if meta.path.is_ident("generic_fk") {
                let mut gfk = GenericFkAttr {
                    name: String::new(),
                    ct_column: String::new(),
                    pk_column: String::new(),
                };
                meta.parse_nested_meta(|inner| {
                    if inner.path.is_ident("name") {
                        let s: LitStr = inner.value()?.parse()?;
                        gfk.name = s.value();
                        return Ok(());
                    }
                    if inner.path.is_ident("ct_column") {
                        let s: LitStr = inner.value()?.parse()?;
                        gfk.ct_column = s.value();
                        return Ok(());
                    }
                    if inner.path.is_ident("pk_column") {
                        let s: LitStr = inner.value()?.parse()?;
                        gfk.pk_column = s.value();
                        return Ok(());
                    }
                    Err(inner.error(
                        "unknown generic_fk attribute (supported: `name`, `ct_column`, `pk_column`)",
                    ))
                })?;
                if gfk.name.is_empty() {
                    return Err(meta.error("generic_fk requires `name = \"...\"`"));
                }
                if gfk.ct_column.is_empty() {
                    return Err(meta.error("generic_fk requires `ct_column = \"...\"`"));
                }
                if gfk.pk_column.is_empty() {
                    return Err(meta.error("generic_fk requires `pk_column = \"...\"`"));
                }
                out.generic_fks.push(gfk);
                return Ok(());
            }
            if meta.path.is_ident("fk_composite") {
                let mut fk = CompositeFkAttr {
                    name: String::new(),
                    to: String::new(),
                    from: Vec::new(),
                    on: Vec::new(),
                };
                meta.parse_nested_meta(|inner| {
                    if inner.path.is_ident("name") {
                        let s: LitStr = inner.value()?.parse()?;
                        fk.name = s.value();
                        return Ok(());
                    }
                    if inner.path.is_ident("to") {
                        let s: LitStr = inner.value()?.parse()?;
                        fk.to = s.value();
                        return Ok(());
                    }
                    // `on = ("col1", "col2", ...)` — parse a parenthesised
                    // comma-list of string literals.
                    if inner.path.is_ident("on") || inner.path.is_ident("from") {
                        let value = inner.value()?;
                        let content;
                        syn::parenthesized!(content in value);
                        let lits: syn::punctuated::Punctuated<syn::LitStr, syn::Token![,]> =
                            content.parse_terminated(
                                |p| p.parse::<syn::LitStr>(),
                                syn::Token![,],
                            )?;
                        let cols: Vec<String> = lits.iter().map(syn::LitStr::value).collect();
                        if inner.path.is_ident("on") {
                            fk.on = cols;
                        } else {
                            fk.from = cols;
                        }
                        return Ok(());
                    }
                    Err(inner.error(
                        "unknown fk_composite attribute (supported: `name`, `to`, `on`, `from`)",
                    ))
                })?;
                if fk.name.is_empty() {
                    return Err(meta.error("fk_composite requires `name = \"...\"`"));
                }
                if fk.to.is_empty() {
                    return Err(meta.error("fk_composite requires `to = \"...\"`"));
                }
                if fk.from.is_empty() || fk.on.is_empty() {
                    return Err(meta.error(
                        "fk_composite requires non-empty `from = (...)` and `on = (...)` tuples",
                    ));
                }
                if fk.from.len() != fk.on.len() {
                    return Err(meta.error(format!(
                        "fk_composite `from` ({} cols) and `on` ({} cols) must be the same length",
                        fk.from.len(),
                        fk.on.len(),
                    )));
                }
                out.composite_fks.push(fk);
                return Ok(());
            }
            if meta.path.is_ident("m2m") {
                let mut m2m = M2MAttr {
                    name: String::new(),
                    to: String::new(),
                    through: String::new(),
                    src: String::new(),
                    dst: String::new(),
                    auto_create: true,
                };
                meta.parse_nested_meta(|inner| {
                    if inner.path.is_ident("name") {
                        let s: LitStr = inner.value()?.parse()?;
                        m2m.name = s.value();
                        return Ok(());
                    }
                    if inner.path.is_ident("to") {
                        let s: LitStr = inner.value()?.parse()?;
                        m2m.to = s.value();
                        return Ok(());
                    }
                    if inner.path.is_ident("through") {
                        let s: LitStr = inner.value()?.parse()?;
                        m2m.through = s.value();
                        return Ok(());
                    }
                    if inner.path.is_ident("src") {
                        let s: LitStr = inner.value()?.parse()?;
                        m2m.src = s.value();
                        return Ok(());
                    }
                    if inner.path.is_ident("dst") {
                        let s: LitStr = inner.value()?.parse()?;
                        m2m.dst = s.value();
                        return Ok(());
                    }
                    if inner.path.is_ident("auto_create") {
                        let lit: syn::LitBool = inner.value()?.parse()?;
                        m2m.auto_create = lit.value;
                        return Ok(());
                    }
                    Err(inner.error("unknown m2m attribute (supported: `name`, `to`, `through`, `src`, `dst`, `auto_create`)"))
                })?;
                if m2m.name.is_empty() {
                    return Err(meta.error("m2m requires `name = \"...\"`"));
                }
                if m2m.to.is_empty() {
                    return Err(meta.error("m2m requires `to = \"...\"`"));
                }
                if m2m.through.is_empty() {
                    return Err(meta.error("m2m requires `through = \"...\"`"));
                }
                if m2m.src.is_empty() {
                    return Err(meta.error("m2m requires `src = \"...\"`"));
                }
                if m2m.dst.is_empty() {
                    return Err(meta.error("m2m requires `dst = \"...\"`"));
                }
                out.m2m.push(m2m);
                return Ok(());
            }
            if meta.path.is_ident("generic_m2m") {
                let mut gm = GenericM2MAttr {
                    name: String::new(),
                    through: String::new(),
                    pk_column: String::new(),
                    ct_column: String::new(),
                    related_column: String::new(),
                };
                meta.parse_nested_meta(|inner| {
                    let field = |inner: &syn::meta::ParseNestedMeta| -> syn::Result<String> {
                        let s: LitStr = inner.value()?.parse()?;
                        Ok(s.value())
                    };
                    if inner.path.is_ident("name") {
                        gm.name = field(&inner)?;
                        return Ok(());
                    }
                    if inner.path.is_ident("through") {
                        gm.through = field(&inner)?;
                        return Ok(());
                    }
                    if inner.path.is_ident("pk_column") {
                        gm.pk_column = field(&inner)?;
                        return Ok(());
                    }
                    if inner.path.is_ident("ct_column") {
                        gm.ct_column = field(&inner)?;
                        return Ok(());
                    }
                    if inner.path.is_ident("related_column") {
                        gm.related_column = field(&inner)?;
                        return Ok(());
                    }
                    Err(inner.error("unknown generic_m2m attribute (supported: `name`, `through`, `pk_column`, `ct_column`, `related_column`)"))
                })?;
                for (val, label) in [
                    (&gm.name, "name"),
                    (&gm.through, "through"),
                    (&gm.pk_column, "pk_column"),
                    (&gm.ct_column, "ct_column"),
                    (&gm.related_column, "related_column"),
                ] {
                    if val.is_empty() {
                        return Err(meta.error(format!("generic_m2m requires `{label} = \"...\"`")));
                    }
                }
                out.generic_m2m.push(gm);
                return Ok(());
            }
            Err(meta.error("unknown rustango container attribute"))
        })?;
    }
    Ok(out)
}

/// Split a comma-separated field-name list (e.g. `"name, office"`) into
/// owned field names, trimming whitespace and skipping empty entries.
/// Field-name validation against the model is done by the caller.
fn split_field_list(raw: &str) -> Vec<String> {
    raw.split(',')
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .map(str::to_owned)
        .collect()
}

/// Shared parser for `unique_together` and `index_together` container
/// attrs. Accepts both shapes:
///
///   * `attr = "col1, col2"`              — auto-derived index name.
///   * `attr(columns = "col1, col2", name = "...")` — explicit name.
///
/// Returns `(columns, name)`.
fn parse_together_attr(
    meta: &syn::meta::ParseNestedMeta<'_>,
    attr: &str,
) -> syn::Result<(Vec<String>, Option<String>)> {
    // Disambiguate by whether the next token is `=` (key-value) or
    // `(` (parenthesized).
    if meta.input.peek(syn::Token![=]) {
        let cols_lit: LitStr = meta.value()?.parse()?;
        let columns = split_field_list(&cols_lit.value());
        check_together_columns(meta, attr, &columns)?;
        return Ok((columns, None));
    }
    let mut columns: Option<Vec<String>> = None;
    let mut name: Option<String> = None;
    meta.parse_nested_meta(|inner| {
        if inner.path.is_ident("columns") {
            let s: LitStr = inner.value()?.parse()?;
            columns = Some(split_field_list(&s.value()));
            return Ok(());
        }
        if inner.path.is_ident("name") {
            let s: LitStr = inner.value()?.parse()?;
            name = Some(s.value());
            return Ok(());
        }
        Err(inner.error("unknown sub-attribute (supported: `columns`, `name`)"))
    })?;
    let columns = columns.ok_or_else(|| {
        meta.error(format!(
            "{attr}(...) requires a `columns = \"col1, col2\"` argument",
        ))
    })?;
    check_together_columns(meta, attr, &columns)?;
    Ok((columns, name))
}

fn check_together_columns(
    meta: &syn::meta::ParseNestedMeta<'_>,
    attr: &str,
    columns: &[String],
) -> syn::Result<()> {
    if columns.len() < 2 {
        let single = if attr == "unique_together" {
            "#[rustango(unique)] on the field"
        } else {
            "#[rustango(index)] on the field"
        };
        return Err(meta.error(format!(
            "{attr} expects two or more columns; for a single-column equivalent use {single}",
        )));
    }
    Ok(())
}

/// Parse the fieldsets DSL: pipe-separated sections, optional
/// `"Title:"` prefix on each, comma-separated field names after.
/// Examples:
/// * `"name, office"` → one untitled section with two fields
/// * `"Identity: name, office | Metadata: created_at"` → two titled
///   sections
///
/// Returns `(title, fields)` pairs. Title is `""` when no prefix.
fn parse_fieldset_list(raw: &str) -> Vec<(String, Vec<String>)> {
    raw.split('|')
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .map(|section| {
            // Split off an optional `Title:` prefix (first colon).
            let (title, rest) = match section.split_once(':') {
                Some((title, rest)) if !title.contains(',') => (title.trim().to_owned(), rest),
                _ => (String::new(), section),
            };
            let fields = split_field_list(rest);
            (title, fields)
        })
        .collect()
}

/// Parse `prepopulated_fields = "target:source[+src2,...]"` — each
/// comma-separated entry maps a target field to one or more source
/// fields joined with `+`. Whitespace around tokens is trimmed.
/// Entries missing `:` or with empty target/source lists are dropped.
fn parse_prepopulated_list(raw: &str) -> Vec<(String, Vec<String>)> {
    raw.split(',')
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .filter_map(|entry| {
            let (target, sources_raw) = entry.split_once(':')?;
            let target = target.trim().to_owned();
            if target.is_empty() {
                return None;
            }
            let sources: Vec<String> = sources_raw
                .split('+')
                .map(|s| s.trim().to_owned())
                .filter(|s| !s.is_empty())
                .collect();
            if sources.is_empty() {
                return None;
            }
            Some((target, sources))
        })
        .collect()
}

/// Parse `formfield_overrides` — `"field:widget,field2:widget2"`
/// into `(field_name, widget_name)` pairs. Empty entries, missing `:`,
/// and empty halves drop silently — the macro layer only enforces shape,
/// not field-name vs. widget-name validity (those checks happen at
/// `AdminConfig` consumption time). Issue #359.
fn parse_formfield_overrides(raw: &str) -> Vec<(String, String)> {
    raw.split(',')
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .filter_map(|entry| {
            let (field, widget) = entry.split_once(':')?;
            let field = field.trim().to_owned();
            let widget = widget.trim().to_owned();
            if field.is_empty() || widget.is_empty() {
                return None;
            }
            Some((field, widget))
        })
        .collect()
}

/// Parse an ordering list — `"name"` is ASC, `"-name"` is DESC.
/// Returns `(field_name, desc)` pairs in the same order as the input.
fn parse_ordering_list(raw: &str) -> Vec<(String, bool)> {
    raw.split(',')
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .map(|spec| {
            spec.strip_prefix('-')
                .map_or((spec.to_owned(), false), |rest| {
                    (rest.trim().to_owned(), true)
                })
        })
        .collect()
}

struct FieldAttrs {
    column: Option<String>,
    primary_key: bool,
    fk: Option<String>,
    o2o: Option<String>,
    on: Option<String>,
    /// `#[rustango(on_delete = "cascade" | "restrict" | "set_null" |
    /// "set_default" | "no_action")]` — what happens to this row when
    /// the row it points at is deleted.
    /// Only meaningful on a `ForeignKey<T>` field or with `fk` / `o2o`
    /// set; the macro errors at compile time if applied to a
    /// non-FK field. Threaded into `FieldSchema::fk_on_delete`. The
    /// DDL writer renders `ON DELETE <action>` after the constraint
    /// clause when this is `Some`; `None` falls back to the database
    /// default (NO ACTION on every backend rustango supports).
    on_delete: Option<String>,
    /// `#[rustango(related_name = "...")]` — per-FK
    /// reverse-accessor override. When set, the derive emits
    /// `Parent::<related_name>[_pool]` instead of the container-level
    /// `default_related_name` or the `<child_snake>_set[_pool]`
    /// fallback. Only meaningful when `fk` / `o2o` is also set;
    /// silently ignored on non-FK fields. Follow-up to #816.
    /// `"+"` emits none, for a parent defined in another crate.
    related_name: Option<String>,
    max_length: Option<u32>,
    /// `#[rustango(vector(dims = N))]` — pgvector column dimension (#824).
    /// Threaded into `FieldType::Vector(N)` at emission. `None` → an
    /// unconstrained `vector` column.
    vector_dims: Option<u32>,
    /// `#[rustango(geometry(srid = N))]` — PostGIS geometry SRID (#443).
    /// Threaded into `FieldType::Geometry(N)` at emission. `None` → an
    /// unconstrained `geometry(Point)` column (SRID 0).
    geometry_srid: Option<u32>,
    min: Option<i64>,
    max: Option<i64>,
    default: Option<String>,
    /// `#[rustango(auto_uuid)]` — UUID PK generated by Postgres
    /// `gen_random_uuid()`. Implies `auto + primary_key + default =
    /// "gen_random_uuid()"`. The Rust field type must be
    /// `uuid::Uuid` (or `Auto<Uuid>`); the column is excluded from
    /// INSERTs so the DB DEFAULT fires.
    auto_uuid: bool,
    /// `#[rustango(default_uuid_v7)]` — backend-neutral counterpart of
    /// `auto_uuid`. The PK value is generated **Rust-side** at insert
    /// time using `uuid::Uuid::now_v7()` (time-sortable UUIDv7) when
    /// the field is `Auto::Unset`, then bound as a normal parameter
    /// rather than relying on a per-dialect DB function. Issue #823
    /// (Eloquent `HasUuids`).
    ///
    /// Field type must be `Auto<uuid::Uuid>`. Implies `primary_key`.
    /// Composes with every backend (PG / MySQL / SQLite) — no
    /// `gen_random_uuid()` requirement on the database.
    default_uuid_v7: bool,
    /// `#[rustango(auto_now_add)]` — `created_at`-shape column.
    /// Server-set on insert, immutable from app code afterwards.
    /// Implies `auto + default = "now()"`. Field type must be
    /// `DateTime<Utc>`.
    auto_now_add: bool,
    /// `#[rustango(auto_now)]` — `updated_at`-shape column. Set on
    /// every insert AND every update. Implies `auto + default =
    /// "now()"`; the macro additionally rewrites `update_on` /
    /// `save_on` to bind `chrono::Utc::now()` instead of the user's
    /// field value.
    auto_now: bool,
    /// `#[rustango(soft_delete)]` — `deleted_at`-shape column. Type
    /// must be `Option<DateTime<Utc>>`. Triggers macro emission of
    /// `soft_delete_on(executor)` and `restore_on(executor)`
    /// methods on the model.
    soft_delete: bool,
    /// `#[rustango(unique)]` — adds a `UNIQUE` constraint inline on
    /// the column in the generated DDL.
    unique: bool,
    /// `#[rustango(index)]` or `#[rustango(index(name = "…", unique))]` —
    /// generates a `CREATE INDEX` for this column. `unique` here means
    /// `CREATE UNIQUE INDEX` (distinct from the `unique` constraint above).
    index: bool,
    index_unique: bool,
    index_name: Option<String>,
    /// Index access method (`"btree"` / `"gin"` / …). Defaults to
    /// `"btree"`. Issue #34.
    index_method: String,
    /// `#[rustango(generated_as = "EXPR")]` — emit `GENERATED ALWAYS
    /// AS (EXPR) STORED` in the column DDL. Read-only from app code:
    /// the macro skips this column from every INSERT and UPDATE
    /// path, so the database always recomputes the value from
    /// `EXPR`. Backlog item #35.
    generated_as: Option<String>,
    /// `#[rustango(help_text = "…")]` — help text
    /// rendered below the admin form's input. Threaded into
    /// `FieldSchema::help_text` so admin / serializer / OpenAPI
    /// layers can read it.
    help_text: Option<String>,
    /// `#[rustango(choices = "value:Label, value:Label")]` — the
    /// enumerated allowed values. Threaded into `FieldSchema::choices`
    /// as a `&'static [(&'static str, &'static str)]` slice. When
    /// present, the admin form renders a `<select>` instead of `<input>`
    /// and the validator rejects values not in the list. Only meaningful
    /// for `FieldType::String`; the macro errors at compile time if
    /// applied to a non-string field.
    choices: Option<Vec<(String, String)>>,
    /// `#[rustango(db_comment = "…")]` — DB-side column
    /// comment. Threaded into `FieldSchema::db_comment`. MySQL inlines
    /// the comment in CREATE TABLE; Postgres emits a separate
    /// `COMMENT ON COLUMN` statement after the table is created;
    /// SQLite silently drops the value (no native column comments).
    db_comment: Option<String>,
    /// `#[rustango(verbose_name = "…")]` — human-readable
    /// label for the field. Threaded into `FieldSchema::verbose_name`
    /// so admin column headers, form labels, and other display
    /// surfaces can prefer the friendly caption over the Rust
    /// identifier. `None` means renderers fall back to the field name.
    verbose_name: Option<String>,
    /// `#[rustango(editable = false)]` — opt out of
    /// auto-generated form rendering. Defaults to `true` so existing
    /// fields keep their current admin / form behavior; setting
    /// `false` removes the field from the admin change-form entirely
    /// (the value is still visible on detail / list views, just not
    /// editable).
    editable: bool,
    /// `#[rustango(blank)]` / `#[rustango(blank = true)]` —
    /// "form may submit empty even when DB is NOT NULL". Threaded into
    /// `FieldSchema::blank`. Defaults to `false`.
    blank: bool,
    /// `#[rustango(citext)]` / `#[rustango(citext = true)]` (#344) —
    /// case-insensitive text column. Threaded into
    /// `FieldSchema::case_insensitive`. Only meaningful for `String`
    /// fields; the macro errors at derive time if applied elsewhere.
    case_insensitive: bool,
    /// `#[rustango(validators = "email,url")]` — the
    /// model-level validator chain. Comma-separated names that
    /// dispatch to the `validators::*` family in `validate_value`.
    /// Empty by default; fires on every typed INSERT/UPDATE.
    validators: Vec<String>,
}

fn parse_field_attrs(field: &syn::Field) -> syn::Result<FieldAttrs> {
    let mut out = FieldAttrs {
        column: None,
        primary_key: false,
        fk: None,
        o2o: None,
        on: None,
        on_delete: None,
        related_name: None,
        max_length: None,
        vector_dims: None,
        geometry_srid: None,
        min: None,
        max: None,
        default: None,
        auto_uuid: false,
        default_uuid_v7: false,
        auto_now_add: false,
        auto_now: false,
        soft_delete: false,
        unique: false,
        index: false,
        index_unique: false,
        index_name: None,
        index_method: "btree".to_owned(),
        generated_as: None,
        help_text: None,
        choices: None,
        db_comment: None,
        verbose_name: None,
        editable: true,
        blank: false,
        case_insensitive: false,
        validators: Vec::new(),
    };
    for attr in &field.attrs {
        if !attr.path().is_ident("rustango") {
            continue;
        }
        attr.parse_nested_meta(|meta| {
            if meta.path.is_ident("column") {
                let s: LitStr = meta.value()?.parse()?;
                let name = s.value();
                validate_sql_identifier(&name, "column", s.span())?;
                out.column = Some(name);
                return Ok(());
            }
            if meta.path.is_ident("primary_key") {
                out.primary_key = true;
                return Ok(());
            }
            if meta.path.is_ident("fk") {
                let s: LitStr = meta.value()?.parse()?;
                out.fk = Some(s.value());
                return Ok(());
            }
            if meta.path.is_ident("o2o") {
                let s: LitStr = meta.value()?.parse()?;
                out.o2o = Some(s.value());
                return Ok(());
            }
            if meta.path.is_ident("on") {
                let s: LitStr = meta.value()?.parse()?;
                out.on = Some(s.value());
                return Ok(());
            }
            if meta.path.is_ident("on_delete") {
                let s: LitStr = meta.value()?.parse()?;
                let raw = s.value();
                let normalized = raw.trim().to_ascii_lowercase();
                // Validate at parse time so the user gets a clear span
                // rather than a downstream compile error in the emit.
                match normalized.as_str() {
                    "cascade" | "restrict" | "set_null" | "set_default" | "no_action" => {}
                    _ => {
                        return Err(syn::Error::new(
                            s.span(),
                            format!(
                                "unknown on_delete action `{raw}`; expected one of \
                                 `cascade`, `restrict`, `set_null`, `set_default`, `no_action`"
                            ),
                        ));
                    }
                }
                out.on_delete = Some(normalized);
                return Ok(());
            }
            if meta.path.is_ident("related_name") {
                let s: LitStr = meta.value()?.parse()?;
                let raw = s.value();
                if raw.trim().is_empty() {
                    return Err(syn::Error::new(
                        s.span(),
                        "`related_name` must be a non-empty identifier",
                    ));
                }
                // Validate as a Rust-ident shape — the value becomes
                // a method name on the parent type. Same rule as
                // `default_related_name` so the two surfaces match.
                // `"+"` emits no accessor at all.
                let snake = raw
                    .chars()
                    .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_')
                    && !raw.starts_with(char::is_numeric);
                if !snake && raw != NO_REVERSE_ACCESSOR {
                    return Err(syn::Error::new(
                        s.span(),
                        "`related_name` must be snake_case ASCII (lowercase letters, \
                         digits, underscores; no leading digit), or \"+\" for none",
                    ));
                }
                out.related_name = Some(raw);
                return Ok(());
            }
            if meta.path.is_ident("max_length") {
                let lit: syn::LitInt = meta.value()?.parse()?;
                out.max_length = Some(lit.base10_parse::<u32>()?);
                return Ok(());
            }
            // `#[rustango(vector(dims = N))]` — pgvector column
            // dimension (#824). Nested-meta form so it reads like the
            // other typed-column attrs.
            if meta.path.is_ident("vector") {
                meta.parse_nested_meta(|inner| {
                    if inner.path.is_ident("dims") {
                        let lit: syn::LitInt = inner.value()?.parse()?;
                        out.vector_dims = Some(lit.base10_parse::<u32>()?);
                        return Ok(());
                    }
                    Err(inner.error("unknown `vector` attribute (supported: `dims`)"))
                })?;
                return Ok(());
            }
            // `#[rustango(geometry(srid = N))]` — PostGIS geometry SRID
            // (#443). Nested-meta form, mirroring `vector(dims = N)`.
            if meta.path.is_ident("geometry") {
                meta.parse_nested_meta(|inner| {
                    if inner.path.is_ident("srid") {
                        let lit: syn::LitInt = inner.value()?.parse()?;
                        out.geometry_srid = Some(lit.base10_parse::<u32>()?);
                        return Ok(());
                    }
                    Err(inner.error("unknown `geometry` attribute (supported: `srid`)"))
                })?;
                return Ok(());
            }
            if meta.path.is_ident("min") {
                out.min = Some(parse_signed_i64(&meta)?);
                return Ok(());
            }
            if meta.path.is_ident("max") {
                out.max = Some(parse_signed_i64(&meta)?);
                return Ok(());
            }
            if meta.path.is_ident("default") {
                let s: LitStr = meta.value()?.parse()?;
                out.default = Some(s.value());
                return Ok(());
            }
            if meta.path.is_ident("generated_as") {
                let s: LitStr = meta.value()?.parse()?;
                out.generated_as = Some(s.value());
                return Ok(());
            }
            if meta.path.is_ident("help_text") {
                let s: LitStr = meta.value()?.parse()?;
                out.help_text = Some(s.value());
                return Ok(());
            }
            if meta.path.is_ident("choices") {
                let s: LitStr = meta.value()?.parse()?;
                let raw = s.value();
                let mut pairs: Vec<(String, String)> = Vec::new();
                for chunk in raw.split(',') {
                    let chunk = chunk.trim();
                    if chunk.is_empty() {
                        continue;
                    }
                    let (value, label) = match chunk.split_once(':') {
                        Some((v, l)) => (v.trim().to_owned(), l.trim().to_owned()),
                        None => (chunk.to_owned(), chunk.to_owned()),
                    };
                    if value.is_empty() {
                        return Err(syn::Error::new(
                            s.span(),
                            "`choices` entry has empty value before `:`",
                        ));
                    }
                    pairs.push((value, label));
                }
                if pairs.is_empty() {
                    return Err(syn::Error::new(
                        s.span(),
                        "`choices = \"…\"` must contain at least one value",
                    ));
                }
                out.choices = Some(pairs);
                return Ok(());
            }
            if meta.path.is_ident("db_comment") {
                let s: LitStr = meta.value()?.parse()?;
                out.db_comment = Some(s.value());
                return Ok(());
            }
            if meta.path.is_ident("verbose_name") {
                let s: LitStr = meta.value()?.parse()?;
                out.verbose_name = Some(s.value());
                return Ok(());
            }
            if meta.path.is_ident("editable") {
                // Two forms accepted:
                //   #[rustango(editable = false)] / true — explicit
                //   #[rustango(editable)] — flag form (= true, the
                //   default, so harmless; included for symmetry)
                if let Ok(v) = meta.value() {
                    let lit: syn::LitBool = v.parse()?;
                    out.editable = lit.value;
                } else {
                    out.editable = true;
                }
                return Ok(());
            }
            if meta.path.is_ident("blank") {
                // Two forms accepted:
                //   #[rustango(blank)] — flag form, true
                //   #[rustango(blank = false)] / true — explicit
                if let Ok(v) = meta.value() {
                    let lit: syn::LitBool = v.parse()?;
                    out.blank = lit.value;
                } else {
                    out.blank = true;
                }
                return Ok(());
            }
            if meta.path.is_ident("citext") {
                // Case-insensitive text column (#344). Two forms:
                //   #[rustango(citext)]          — flag form, true
                //   #[rustango(citext = true)]   — explicit
                //   #[rustango(citext = false)]  — explicit opt-out
                // String-only validation lives in the field-type
                // emitter (the FieldType discriminant is computed in
                // `detect_type`); the macro records the flag and the
                // DDL writer emits dialect-specific COLLATE / CITEXT.
                if let Ok(v) = meta.value() {
                    let lit: syn::LitBool = v.parse()?;
                    out.case_insensitive = lit.value;
                } else {
                    out.case_insensitive = true;
                }
                return Ok(());
            }
            if meta.path.is_ident("validators") {
                let s: LitStr = meta.value()?.parse()?;
                let raw = s.value();
                out.validators = raw
                    .split(',')
                    .map(str::trim)
                    .filter(|s| !s.is_empty())
                    .map(str::to_owned)
                    .collect();
                if out.validators.is_empty() {
                    return Err(syn::Error::new(
                        s.span(),
                        "`validators = \"…\"` must list at least one name",
                    ));
                }
                return Ok(());
            }
            if meta.path.is_ident("auto_uuid") {
                out.auto_uuid = true;
                // Implied: PK + auto + DEFAULT gen_random_uuid().
                // Each is also explicitly settable; the explicit
                // value wins if conflicting.
                out.primary_key = true;
                if out.default.is_none() {
                    out.default = Some("gen_random_uuid()".into());
                }
                return Ok(());
            }
            if meta.path.is_ident("default_uuid_v7") {
                // Backend-neutral counterpart of `auto_uuid` — issue #823.
                // No SQL DEFAULT (the macro fills the value Rust-side
                // before binding); just mark the field as PK + Auto
                // so the insert path is the `Auto::Unset → generate`
                // branch.
                out.default_uuid_v7 = true;
                out.primary_key = true;
                return Ok(());
            }
            if meta.path.is_ident("auto_now_add") {
                out.auto_now_add = true;
                if out.default.is_none() {
                    out.default = Some("now()".into());
                }
                return Ok(());
            }
            if meta.path.is_ident("auto_now") {
                out.auto_now = true;
                if out.default.is_none() {
                    out.default = Some("now()".into());
                }
                return Ok(());
            }
            if meta.path.is_ident("soft_delete") {
                out.soft_delete = true;
                return Ok(());
            }
            if meta.path.is_ident("unique") {
                out.unique = true;
                return Ok(());
            }
            if meta.path.is_ident("index") {
                out.index = true;
                // Optional sub-attrs: #[rustango(index(unique, name = "…", method = "gin"))]
                if meta.input.peek(syn::token::Paren) {
                    meta.parse_nested_meta(|inner| {
                        if inner.path.is_ident("unique") {
                            out.index_unique = true;
                            return Ok(());
                        }
                        if inner.path.is_ident("name") {
                            let s: LitStr = inner.value()?.parse()?;
                            out.index_name = Some(s.value());
                            return Ok(());
                        }
                        if inner.path.is_ident("method") {
                            let s: LitStr = inner.value()?.parse()?;
                            let v = s.value();
                            match v.as_str() {
                                "btree" | "gin" | "gist" | "brin" | "spgist" | "hash" | "bloom" => {
                                    out.index_method = v;
                                }
                                other => {
                                    return Err(inner.error(format!(
                                        "unknown index method `{other}` (supported: btree, gin, gist, brin, spgist, hash, bloom)",
                                    )));
                                }
                            }
                            return Ok(());
                        }
                        Err(inner.error(
                            "unknown index sub-attribute (supported: `unique`, `name`, `method`)",
                        ))
                    })?;
                }
                return Ok(());
            }
            Err(meta.error("unknown rustango field attribute"))
        })?;
    }
    Ok(out)
}

/// Parse a signed integer literal, accepting optional leading `-`.
fn parse_signed_i64(meta: &syn::meta::ParseNestedMeta<'_>) -> syn::Result<i64> {
    let expr: syn::Expr = meta.value()?.parse()?;
    match expr {
        syn::Expr::Lit(syn::ExprLit {
            lit: syn::Lit::Int(lit),
            ..
        }) => lit.base10_parse::<i64>(),
        syn::Expr::Unary(syn::ExprUnary {
            op: syn::UnOp::Neg(_),
            expr,
            ..
        }) => {
            if let syn::Expr::Lit(syn::ExprLit {
                lit: syn::Lit::Int(lit),
                ..
            }) = *expr
            {
                let v: i64 = lit.base10_parse()?;
                Ok(-v)
            } else {
                Err(syn::Error::new_spanned(expr, "expected integer literal"))
            }
        }
        other => Err(syn::Error::new_spanned(
            other,
            "expected integer literal (signed)",
        )),
    }
}

struct FieldInfo<'a> {
    ident: &'a syn::Ident,
    column: String,
    primary_key: bool,
    /// `true` when the Rust type was `Auto<T>` — the INSERT path will
    /// skip this column when `Auto::Unset` and emit it under
    /// `RETURNING` so Postgres' sequence DEFAULT fills in the value.
    auto: bool,
    /// The original field type, e.g. `i64` or `Option<String>`. Emitted as
    /// the `Column::Value` associated type for typed-column tokens.
    value_ty: &'a Type,
    /// `FieldType` variant tokens (`#root::core::FieldType::I64`).
    field_type_tokens: TokenStream2,
    schema: TokenStream2,
    from_row_init: TokenStream2,
    /// Variant of [`Self::from_row_init`] that reads the column via
    /// `format!("{prefix}__{col}")` so a model can be decoded out of
    /// the aliased columns of a JOINed row. Drives slice 9.0d's
    /// `Self::__rustango_from_aliased_row(row, prefix)` per-Model
    /// helper that `select_related` calls when stitching loaded FKs.
    from_aliased_row_init: TokenStream2,
    /// MySQL twins of the two inits above. They differ only for a UUID
    /// column, which MySQL keeps as `CHAR(36)` text (#1733).
    from_row_init_my: TokenStream2,
    from_aliased_row_init_my: TokenStream2,
    /// A bare or optional `Uuid` field.
    uuid_column: bool,
    /// Inner type from a `ForeignKey<T, K>` field, if any. The reverse-
    /// relation helper emit (`Author::<child>_set`) needs to know `T`
    /// to point the generated method at the right child model.
    fk_inner: Option<Type>,
    /// `K`'s scalar kind for a `ForeignKey<T, K>` field. Mirrors
    /// `kind` (since ForeignKey detection sets `kind` to K's
    /// underlying type) but stored separately for clarity at the
    /// `FkRelation` construction site, which only sees the FK's
    /// surface fields.
    fk_pk_kind: DetectedKind,
    /// `true` when the field is `Option<ForeignKey<T, K>>` rather than
    /// the bare `ForeignKey<T, K>`. Routes the load_related and
    /// fk_pk_access emitters to wrap assignments / accessors in
    /// `Some(...)` / `as_ref().map(...)` respectively, so a nullable
    /// FK column compiles end-to-end. The DDL writer reads this off
    /// the field schema (`nullable` flag); the macro just needs to
    /// keep the Rust-side codegen consistent.
    nullable: bool,
    /// `true` when this column was marked `#[rustango(auto_now)]` —
    /// `update_on` / `save_on` bind `chrono::Utc::now()` for this
    /// column instead of the user-supplied value, so `updated_at`
    /// always reflects the latest write without the caller having
    /// to remember to set it.
    auto_now: bool,
    /// `true` when this column was marked `#[rustango(auto_now_add)]`
    /// — the column is server-set on INSERT (DB DEFAULT) and
    /// **immutable** afterwards. `update_on` / `save_on` skip the
    /// column entirely so a stale `created_at` value in memory never
    /// rewrites the persisted timestamp.
    auto_now_add: bool,
    /// `true` when this column was marked `#[rustango(soft_delete)]`.
    /// Triggers emission of `soft_delete_on(executor)` and
    /// `restore_on(executor)` on the model's inherent impl. There is
    /// at most one such column per model — emission asserts this.
    soft_delete: bool,
    /// `Some` when this column was marked
    /// `#[rustango(generated_as = "EXPR")]`. The macro skips it from
    /// every INSERT and UPDATE path; the database recomputes the
    /// value from `EXPR`. Backlog item #35.
    generated_as: Option<String>,
    /// `true` when this column was marked
    /// `#[rustango(default_uuid_v7)]`. Routes `collect_fields` to
    /// emit an `insert_push` that auto-fills an `Auto::Unset` value
    /// with `Uuid::now_v7()` before binding, so the PK is generated
    /// Rust-side and the column is always present in the INSERT
    /// statement (no DB DEFAULT requirement). Issue #823.
    default_uuid_v7: bool,
    /// `Some` when this FK field carried `#[rustango(related_name =
    /// "...")]`. Threaded into [`FkRelation::related_name`] and
    /// consumed by [`reverse_helper_tokens`] to override the default
    /// `<child_snake>_set` accessor name. Follow-up to #816.
    related_name: Option<String>,
}

/// Reject table names that won't survive SQL identifier
/// derivation downstream. Postgres' regular-identifier rule
/// (`[a-zA-Z_][a-zA-Z0-9_]*`) is the safe shape: it round-trips
/// through the framework's unquoted FK / index / constraint name
/// emission without surprises. We also disallow leading-digit and
/// the empty string for clarity.
///
/// Reserved-word collisions (`select`, `from`, …) aren't flagged
/// here — those produce a runtime error from the SQL parser,
/// which is loud enough; statically enumerating reserved words
/// across the three supported dialects is more friction than help.
///
/// Backlog item #65.
fn validate_table_name(name: &str, span: proc_macro2::Span) -> syn::Result<()> {
    validate_sql_identifier(name, "table", span)
}

/// Reject SQL identifiers that compile but break downstream SQL
/// generation. Same rule for tables and columns: `[a-zA-Z_][a-zA-Z0-9_]*`.
/// `kind` is "table" / "column" — used for the error message so users
/// see which attribute caused the failure.
fn validate_sql_identifier(name: &str, kind: &str, span: proc_macro2::Span) -> syn::Result<()> {
    if name.is_empty() {
        return Err(syn::Error::new(
            span,
            format!("`{kind} = \"\"` is not a valid SQL identifier"),
        ));
    }
    let mut chars = name.chars();
    let first = chars.next().unwrap();
    if !(first.is_ascii_alphabetic() || first == '_') {
        return Err(syn::Error::new(
            span,
            format!("{kind} name `{name}` must start with a letter or underscore (got {first:?})"),
        ));
    }
    for c in chars {
        if !(c.is_ascii_alphanumeric() || c == '_') {
            return Err(syn::Error::new(
                span,
                format!(
                    "{kind} name `{name}` contains invalid character {c:?} — \
                     SQL identifiers must match `[a-zA-Z_][a-zA-Z0-9_]*`. \
                     Hyphens in particular break FK / index name derivation \
                     downstream; use underscores instead (e.g. `{}`)",
                    name.replace(|x: char| !x.is_ascii_alphanumeric() && x != '_', "_"),
                ),
            ));
        }
    }
    Ok(())
}

fn process_field<'a>(field: &'a syn::Field, table: &str) -> syn::Result<FieldInfo<'a>> {
    let root = rustango_root();
    let attrs = parse_field_attrs(field)?;
    let ident = field
        .ident
        .as_ref()
        .ok_or_else(|| syn::Error::new(field.span(), "tuple structs are not supported"))?;
    let name = ident_name(ident);
    let column = attrs.column.clone().unwrap_or_else(|| name.clone());
    let primary_key = attrs.primary_key;
    let DetectedType {
        kind,
        nullable,
        auto: detected_auto,
        fk_inner,
    } = detect_type(&field.ty)?;
    check_bound_compatibility(field, &attrs, kind)?;
    let auto = detected_auto;
    // Mixin attributes piggyback on the existing `Auto<T>` skip-on-
    // INSERT path: the user must wrap the field in `Auto<T>`, which
    // marks the column as DB-default-supplied. The mixin attrs then
    // layer in the SQL default (`now()` / `gen_random_uuid()`) and,
    // for `auto_now`, force the value on UPDATE too.
    if attrs.auto_uuid {
        if kind != DetectedKind::Uuid {
            return Err(syn::Error::new_spanned(
                field,
                "`#[rustango(auto_uuid)]` requires the field type to be \
                 `Auto<uuid::Uuid>`",
            ));
        }
        if !detected_auto {
            return Err(syn::Error::new_spanned(
                field,
                "`#[rustango(auto_uuid)]` requires the field type to be \
                 wrapped in `Auto<...>` so the macro skips the column on \
                 INSERT and the DB DEFAULT (`gen_random_uuid()`) fires",
            ));
        }
    }
    if attrs.default_uuid_v7 {
        if kind != DetectedKind::Uuid {
            return Err(syn::Error::new_spanned(
                field,
                "`#[rustango(default_uuid_v7)]` requires the field type to be \
                 `Auto<uuid::Uuid>`",
            ));
        }
        if !detected_auto {
            return Err(syn::Error::new_spanned(
                field,
                "`#[rustango(default_uuid_v7)]` requires the field type to be \
                 wrapped in `Auto<...>` so the macro can detect the \
                 unset-vs-set state and fill a fresh UUIDv7 before INSERT",
            ));
        }
        if attrs.auto_uuid {
            return Err(syn::Error::new_spanned(
                field,
                "`#[rustango(default_uuid_v7)]` is mutually exclusive with \
                 `#[rustango(auto_uuid)]` — the former generates the UUID \
                 Rust-side, the latter relies on the DB's `gen_random_uuid()`. \
                 Pick one.",
            ));
        }
    }
    if attrs.auto_now_add || attrs.auto_now {
        if kind != DetectedKind::DateTime {
            return Err(syn::Error::new_spanned(
                field,
                "`#[rustango(auto_now_add)]` / `#[rustango(auto_now)]` require \
                 the field type to be `Auto<chrono::DateTime<chrono::Utc>>`",
            ));
        }
        if !detected_auto {
            return Err(syn::Error::new_spanned(
                field,
                "`#[rustango(auto_now_add)]` / `#[rustango(auto_now)]` require \
                 the field type to be wrapped in `Auto<...>` so the macro skips \
                 the column on INSERT and the DB DEFAULT (`now()`) fires",
            ));
        }
    }
    if attrs.soft_delete && !(kind == DetectedKind::DateTime && nullable) {
        return Err(syn::Error::new_spanned(
            field,
            "`#[rustango(soft_delete)]` requires the field type to be \
             `Option<chrono::DateTime<chrono::Utc>>`",
        ));
    }
    let is_mixin_auto =
        attrs.auto_uuid || attrs.default_uuid_v7 || attrs.auto_now_add || attrs.auto_now;
    if detected_auto && !primary_key && !is_mixin_auto {
        return Err(syn::Error::new_spanned(
            field,
            "`Auto<T>` is only valid on a `#[rustango(primary_key)]` field, \
             or on a field carrying one of `auto_uuid`, `auto_now_add`, or \
             `auto_now`",
        ));
    }
    if detected_auto && attrs.default.is_some() && !is_mixin_auto {
        return Err(syn::Error::new_spanned(
            field,
            "`#[rustango(default = \"…\")]` is redundant on an `Auto<T>` field — \
             SERIAL / BIGSERIAL already supplies a default sequence.",
        ));
    }
    if fk_inner.is_some() && primary_key {
        return Err(syn::Error::new_spanned(
            field,
            "`ForeignKey<T>` is not allowed on a primary-key field — \
             a row's PK is its own identity, not a reference to a parent.",
        ));
    }
    if attrs.generated_as.is_some() {
        if primary_key {
            return Err(syn::Error::new_spanned(
                field,
                "`#[rustango(generated_as = \"…\")]` is not allowed on a \
                 primary-key field — a PK must be writable so the row \
                 has an identity at INSERT time.",
            ));
        }
        if attrs.default.is_some() {
            return Err(syn::Error::new_spanned(
                field,
                "`#[rustango(generated_as = \"…\")]` cannot combine with \
                 `default = \"…\"` — Postgres rejects DEFAULT on \
                 generated columns. The expression IS the default.",
            ));
        }
        if detected_auto {
            return Err(syn::Error::new_spanned(
                field,
                "`#[rustango(generated_as = \"…\")]` is not allowed on \
                 an `Auto<T>` field — generated columns are computed \
                 by the DB, not server-assigned via a sequence. Use a \
                 plain Rust type (e.g. `f64`).",
            ));
        }
        if fk_inner.is_some() {
            return Err(syn::Error::new_spanned(
                field,
                "`#[rustango(generated_as = \"…\")]` is not allowed on a \
                 ForeignKey field.",
            ));
        }
    }
    let relation = relation_tokens(field, &attrs, fk_inner, table)?;
    let column_lit = column.as_str();
    // pgvector (#824): the `vector(dims = N)` attribute supplies the
    // dimension that the bare `Vector` Rust type can't carry, so emit
    // `FieldType::Vector(N)` here rather than the `variant_tokens`
    // fallback of `Vector(0)`.
    let field_type_tokens = if kind == DetectedKind::Vector {
        let root = rustango_root();
        let dims = attrs.vector_dims.unwrap_or(0);
        quote!(#root::core::FieldType::Vector(#dims))
    } else if kind == DetectedKind::Geometry {
        // PostGIS (#443): the `geometry(srid = N)` attribute supplies the
        // SRID that the bare `Point` Rust type can't carry, so emit
        // `FieldType::Geometry(N)` rather than the `Geometry(0)` fallback.
        let root = rustango_root();
        let srid = attrs.geometry_srid.unwrap_or(0);
        quote!(#root::core::FieldType::Geometry(#srid))
    } else {
        kind.variant_tokens()
    };
    let max_length = optional_u32(attrs.max_length);
    let min = optional_i64(attrs.min);
    let max = optional_i64(attrs.max);
    let default = optional_str(attrs.default.as_deref());

    let unique = attrs.unique;
    let generated_as = optional_str(attrs.generated_as.as_deref());
    let help_text = optional_str(attrs.help_text.as_deref());
    let choices = optional_choices(attrs.choices.as_deref());
    let db_comment = optional_str(attrs.db_comment.as_deref());
    let verbose_name = optional_str(attrs.verbose_name.as_deref());
    let editable = attrs.editable;
    let blank = attrs.blank;
    let case_insensitive = attrs.case_insensitive;
    let validators_lits: Vec<&str> = attrs.validators.iter().map(String::as_str).collect();
    if attrs.on_delete.is_some() && attrs.fk.is_none() && attrs.o2o.is_none() && fk_inner.is_none()
    {
        return Err(syn::Error::new_spanned(
            field,
            "`#[rustango(on_delete = \"…\")]` requires a `ForeignKey<T>` field \
             or `fk = \"<table>\"` / `o2o = \"<table>\"` on the same field — it \
             has no meaning on a non-FK column.",
        ));
    }
    if attrs.on_delete.as_deref() == Some("set_null") && !nullable {
        return Err(syn::Error::new_spanned(
            field,
            "`on_delete = \"set_null\"` needs a nullable column: use \
             `Option<ForeignKey<T>>` or `Option<…>` (spelled out; a type \
             alias for `Option` is not seen).",
        ));
    }
    let fk_on_delete = match attrs.on_delete.as_deref() {
        None => quote!(::core::option::Option::None),
        Some(action) => {
            let variant = match action {
                "cascade" => quote!(Cascade),
                "restrict" => quote!(Restrict),
                "set_null" => quote!(SetNull),
                "set_default" => quote!(SetDefault),
                "no_action" => quote!(NoAction),
                // parse_field_attrs already validated this — guard against future drift.
                other => unreachable!("on_delete `{other}` should have been rejected at parse"),
            };
            quote!(::core::option::Option::Some(
                #root::core::OnDeleteAction::#variant
            ))
        }
    };
    let auto_now_flag = attrs.auto_now;
    let schema = quote! {{
        #root::core::FieldSchema::from_parts(#root::core::FieldSchemaParts {
            name: #name,
            column: #column_lit,
            ty: #field_type_tokens,
            nullable: #nullable,
            primary_key: #primary_key,
            relation: #relation,
            max_length: #max_length,
            min: #min,
            max: #max,
            default: #default,
            auto: #auto,
            auto_now: #auto_now_flag,
            unique: #unique,
            generated_as: #generated_as,
            help_text: #help_text,
            choices: #choices,
            db_comment: #db_comment,
            verbose_name: #verbose_name,
            editable: #editable,
            blank: #blank,
            case_insensitive: #case_insensitive,
            fk_on_delete: #fk_on_delete,
            validators: &[ #(#validators_lits),* ],
        })
    }};

    let from_row_init = quote! {
        #ident: #root::sql::sqlx::Row::try_get(row, #column_lit)?
    };
    let from_aliased_row_init = quote! {
        #ident: #root::sql::sqlx::Row::try_get(
            row,
            #root::core::joins::joined_label(prefix, #column_lit).as_str(),
        )?
    };
    // `Auto<Uuid>` and `ForeignKey<_, Uuid>` decode through their own
    // MySQL impls; a bare or optional `Uuid` needs `FlatScalar`'s cell.
    let uuid_column = kind == DetectedKind::Uuid && !detected_auto && fk_inner.is_none();
    let (from_row_init_my, from_aliased_row_init_my) = if uuid_column {
        (
            quote! { #ident: #root::sql::try_get_flat_my(row, #column_lit)? },
            quote! {
                #ident: #root::sql::try_get_flat_my(
                    row,
                    #root::core::joins::joined_label(prefix, #column_lit).as_str(),
                )?
            },
        )
    } else {
        (from_row_init.clone(), from_aliased_row_init.clone())
    };

    Ok(FieldInfo {
        ident,
        column,
        primary_key,
        auto,
        value_ty: &field.ty,
        field_type_tokens,
        schema,
        from_row_init,
        from_aliased_row_init,
        from_row_init_my,
        from_aliased_row_init_my,
        uuid_column,
        fk_inner: fk_inner.cloned(),
        fk_pk_kind: kind,
        nullable,
        auto_now: attrs.auto_now,
        auto_now_add: attrs.auto_now_add,
        soft_delete: attrs.soft_delete,
        generated_as: attrs.generated_as.clone(),
        default_uuid_v7: attrs.default_uuid_v7,
        related_name: attrs.related_name.clone(),
    })
}

fn check_bound_compatibility(
    field: &syn::Field,
    attrs: &FieldAttrs,
    kind: DetectedKind,
) -> syn::Result<()> {
    if attrs.max_length.is_some() && kind != DetectedKind::String {
        return Err(syn::Error::new_spanned(
            field,
            "`max_length` is only valid on `String` fields (or `Option<String>`)",
        ));
    }
    // These were silently dropped on the wrong type (#1937).
    if attrs.case_insensitive && kind != DetectedKind::String {
        return Err(syn::Error::new_spanned(
            field,
            "`citext` is only valid on `String` fields (or `Option<String>`)",
        ));
    }
    if attrs.vector_dims.is_some() && kind != DetectedKind::Vector {
        return Err(syn::Error::new_spanned(
            field,
            "`vector(dims = …)` is only valid on a pgvector `Vector` field",
        ));
    }
    if attrs.geometry_srid.is_some() && kind != DetectedKind::Geometry {
        return Err(syn::Error::new_spanned(
            field,
            "`geometry(srid = …)` is only valid on a PostGIS `Point` field",
        ));
    }
    if attrs.choices.is_some() && kind != DetectedKind::String {
        return Err(syn::Error::new_spanned(
            field,
            "`choices` is only valid on `String` fields (or `Option<String>`) — \
             integer-valued enumerations should be modeled with a Rust enum and \
             custom (de)serializer for now",
        ));
    }
    if (attrs.min.is_some() || attrs.max.is_some()) && !kind.is_integer() {
        return Err(syn::Error::new_spanned(
            field,
            "`min` / `max` are only valid on integer fields (`i32`, `i64`, optionally Option-wrapped)",
        ));
    }
    if let (Some(min), Some(max)) = (attrs.min, attrs.max) {
        if min > max {
            return Err(syn::Error::new_spanned(
                field,
                format!("`min` ({min}) is greater than `max` ({max})"),
            ));
        }
    }
    Ok(())
}

/// A `&'static [ty]` of `const fn` results. The slice needs its own
/// `const`: a `&[..]` assigned in a statement is not extended to `'static`.
fn const_slice(ty: &TokenStream2, items: impl Iterator<Item = TokenStream2>) -> TokenStream2 {
    quote!({
        const ITEMS: &[#ty] = &[ #(#items),* ];
        ITEMS
    })
}

fn optional_u32(value: Option<u32>) -> TokenStream2 {
    if let Some(v) = value {
        quote!(::core::option::Option::Some(#v))
    } else {
        quote!(::core::option::Option::None)
    }
}

fn optional_i64(value: Option<i64>) -> TokenStream2 {
    if let Some(v) = value {
        quote!(::core::option::Option::Some(#v))
    } else {
        quote!(::core::option::Option::None)
    }
}

fn optional_str(value: Option<&str>) -> TokenStream2 {
    if let Some(v) = value {
        quote!(::core::option::Option::Some(#v))
    } else {
        quote!(::core::option::Option::None)
    }
}

fn optional_choices(pairs: Option<&[(String, String)]>) -> TokenStream2 {
    let Some(pairs) = pairs else {
        return quote!(::core::option::Option::None);
    };
    let entries = pairs.iter().map(|(v, l)| quote!((#v, #l)));
    quote!(::core::option::Option::Some(&[#(#entries),*]))
}

fn relation_tokens(
    field: &syn::Field,
    attrs: &FieldAttrs,
    fk_inner: Option<&syn::Type>,
    table: &str,
) -> syn::Result<TokenStream2> {
    let root = rustango_root();
    if let Some(inner) = fk_inner {
        if attrs.fk.is_some() || attrs.o2o.is_some() {
            return Err(syn::Error::new_spanned(
                field,
                "`ForeignKey<T>` already declares the FK target via the type parameter — \
                 remove the `fk = \"…\"` / `o2o = \"…\"` attribute.",
            ));
        }
        // No `on`: the target's PK column, which may be renamed.
        let on = match attrs.on.as_deref() {
            Some(on) => quote!(#on),
            None => quote! {
                match <#inner as #root::core::Model>::SCHEMA.pk_column() {
                    ::core::option::Option::Some(c) => c,
                    ::core::option::Option::None => "id",
                }
            },
        };
        return Ok(quote! {
            ::core::option::Option::Some(#root::core::Relation::fk(
                <#inner as #root::core::Model>::SCHEMA.table,
                #on,
            ))
        });
    }
    match (&attrs.fk, &attrs.o2o) {
        (Some(_), Some(_)) => Err(syn::Error::new_spanned(
            field,
            "`fk` and `o2o` are mutually exclusive",
        )),
        (Some(to), None) => {
            let on = attrs.on.as_deref().unwrap_or("id");
            // Self-FK sentinel — `#[rustango(fk = "self")]` resolves to
            // the model's own table. Threaded as a literal string at
            // macro-expansion time to sidestep the const-eval cycle
            // that `Self::SCHEMA.table` would create when referenced
            // inside Self::SCHEMA's own initializer.
            let resolved = if to == "self" { table } else { to };
            Ok(quote! {
                ::core::option::Option::Some(#root::core::Relation::fk(#resolved, #on))
            })
        }
        (None, Some(to)) => {
            let on = attrs.on.as_deref().unwrap_or("id");
            let resolved = if to == "self" { table } else { to };
            Ok(quote! {
                ::core::option::Option::Some(#root::core::Relation::o2o(#resolved, #on))
            })
        }
        (None, None) => {
            if attrs.on.is_some() {
                return Err(syn::Error::new_spanned(
                    field,
                    "`on` requires `fk` or `o2o`",
                ));
            }
            Ok(quote!(::core::option::Option::None))
        }
    }
}

/// Mirrors `rustango_core::FieldType`. Local copy so the macro can reason
/// about kinds without depending on `rustango-core` (which would require a
/// proc-macro/normal split it doesn't have today).
#[derive(Clone, Copy, PartialEq, Eq)]
enum DetectedKind {
    I16,
    I32,
    I64,
    F32,
    F64,
    Bool,
    String,
    DateTime,
    Date,
    Time,
    Uuid,
    Json,
    Decimal,
    Binary,
    /// `Array<String>` → PG `text[]` (#341).
    ArrayText,
    /// `Array<i32>` → PG `integer[]` (#341).
    ArrayInt,
    /// `Array<i64>` → PG `bigint[]` (#341).
    ArrayBigInt,
    /// `Range<i32>` → PG `int4range` (#343).
    RangeInt,
    /// `Range<i64>` → PG `int8range` (#343).
    RangeBigInt,
    /// `Range<Decimal>` → PG `numrange` (#343).
    RangeNumeric,
    /// `Range<NaiveDate>` → PG `daterange` (#343).
    RangeDate,
    /// `Range<DateTime<Utc>>` → PG `tstzrange` (#343).
    RangeDateTime,
    /// `HStore` → PG `hstore` (#342).
    HStore,
    /// `Vector` → pgvector `vector(N)` (#824). The dimension `N` comes
    /// from the `#[rustango(vector(dims = N))]` field attribute, threaded
    /// in at the `FieldType` emission site (not carried on this enum).
    Vector,
    /// `Point` → PostGIS `geometry(Point, srid)` (#443). The SRID comes
    /// from the `#[rustango(geometry(srid = N))]` field attribute,
    /// threaded in at the `FieldType` emission site.
    Geometry,
}

impl DetectedKind {
    fn variant_tokens(self) -> TokenStream2 {
        let root = rustango_root();
        match self {
            Self::I16 => quote!(#root::core::FieldType::I16),
            Self::I32 => quote!(#root::core::FieldType::I32),
            Self::I64 => quote!(#root::core::FieldType::I64),
            Self::F32 => quote!(#root::core::FieldType::F32),
            Self::F64 => quote!(#root::core::FieldType::F64),
            Self::Bool => quote!(#root::core::FieldType::Bool),
            Self::String => quote!(#root::core::FieldType::String),
            Self::DateTime => quote!(#root::core::FieldType::DateTime),
            Self::Date => quote!(#root::core::FieldType::Date),
            Self::Time => quote!(#root::core::FieldType::Time),
            Self::Uuid => quote!(#root::core::FieldType::Uuid),
            Self::Json => quote!(#root::core::FieldType::Json),
            Self::Decimal => quote!(#root::core::FieldType::Decimal),
            Self::Binary => quote!(#root::core::FieldType::Binary),
            Self::ArrayText => {
                quote!(#root::core::FieldType::Array(#root::core::ArrayElem::Text))
            }
            Self::ArrayInt => {
                quote!(#root::core::FieldType::Array(#root::core::ArrayElem::Int))
            }
            Self::ArrayBigInt => {
                quote!(#root::core::FieldType::Array(#root::core::ArrayElem::BigInt))
            }
            Self::RangeInt => {
                quote!(#root::core::FieldType::Range(#root::core::RangeElem::Int))
            }
            Self::RangeBigInt => {
                quote!(#root::core::FieldType::Range(#root::core::RangeElem::BigInt))
            }
            Self::RangeNumeric => {
                quote!(#root::core::FieldType::Range(#root::core::RangeElem::Numeric))
            }
            Self::RangeDate => {
                quote!(#root::core::FieldType::Range(#root::core::RangeElem::Date))
            }
            Self::RangeDateTime => {
                quote!(#root::core::FieldType::Range(#root::core::RangeElem::DateTime))
            }
            Self::HStore => quote!(#root::core::FieldType::HStore),
            // Dimension comes from the `vector(dims = N)` attribute,
            // applied at the emission site; `0` here is just a fallback.
            Self::Vector => quote!(#root::core::FieldType::Vector(0)),
            // SRID comes from the `geometry(srid = N)` attribute, applied
            // at the emission site; `0` here is just a fallback.
            Self::Geometry => quote!(#root::core::FieldType::Geometry(0)),
        }
    }

    fn is_integer(self) -> bool {
        matches!(self, Self::I16 | Self::I32 | Self::I64)
    }
}

/// Result of walking a field's Rust type. `kind` is the underlying
/// `FieldType`; `nullable` is set by an outer `Option<T>`; `auto` is
/// set by an outer `Auto<T>` (server-assigned PK); `fk_inner` is
/// `Some(<T>)` when the field was `ForeignKey<T>` (or
/// `Option<ForeignKey<T>>`), letting the codegen reach `T::SCHEMA`.
#[derive(Clone, Copy)]
struct DetectedType<'a> {
    kind: DetectedKind,
    nullable: bool,
    auto: bool,
    fk_inner: Option<&'a syn::Type>,
}

/// Extract the `T` from a `…::Auto<T>` field type. Returns `None` for
/// non-`Auto` types — the caller should already have routed Auto-only
/// codegen through this helper, so a `None` indicates a macro-internal
/// invariant break.
fn auto_inner_type(ty: &syn::Type) -> Option<&syn::Type> {
    let Type::Path(TypePath { path, qself: None }) = ty else {
        return None;
    };
    let last = path.segments.last()?;
    if last.ident != "Auto" {
        return None;
    }
    let syn::PathArguments::AngleBracketed(args) = &last.arguments else {
        return None;
    };
    args.args.iter().find_map(|a| match a {
        syn::GenericArgument::Type(t) => Some(t),
        _ => None,
    })
}

fn detect_type(ty: &syn::Type) -> syn::Result<DetectedType<'_>> {
    let Type::Path(TypePath { path, qself: None }) = ty else {
        return Err(syn::Error::new_spanned(ty, "unsupported field type"));
    };
    let last = path
        .segments
        .last()
        .ok_or_else(|| syn::Error::new_spanned(ty, "empty type path"))?;

    if last.ident == "Option" {
        let inner = generic_inner(ty, &last.arguments, "Option")?;
        let inner_det = detect_type(inner)?;
        if inner_det.nullable {
            return Err(syn::Error::new_spanned(
                ty,
                "nested Option is not supported",
            ));
        }
        if inner_det.auto {
            return Err(syn::Error::new_spanned(
                ty,
                "`Option<Auto<T>>` is not supported — Auto fields are server-assigned and cannot be NULL",
            ));
        }
        return Ok(DetectedType {
            nullable: true,
            ..inner_det
        });
    }

    if last.ident == "Auto" {
        let inner = generic_inner(ty, &last.arguments, "Auto")?;
        let inner_det = detect_type(inner)?;
        if inner_det.auto {
            return Err(syn::Error::new_spanned(ty, "nested Auto is not supported"));
        }
        if inner_det.nullable {
            return Err(syn::Error::new_spanned(
                ty,
                "`Auto<Option<T>>` is not supported — Auto fields are server-assigned and cannot be NULL",
            ));
        }
        if inner_det.fk_inner.is_some() {
            return Err(syn::Error::new_spanned(
                ty,
                "`Auto<ForeignKey<T>>` is not supported — Auto is for server-assigned PKs, ForeignKey is for parent references",
            ));
        }
        if !matches!(
            inner_det.kind,
            DetectedKind::I32 | DetectedKind::I64 | DetectedKind::Uuid | DetectedKind::DateTime
        ) {
            return Err(syn::Error::new_spanned(
                ty,
                "`Auto<T>` only supports integers (`i32` → SERIAL, `i64` → BIGSERIAL), \
                 `uuid::Uuid` (DEFAULT gen_random_uuid()), or `chrono::DateTime<chrono::Utc>` \
                 (DEFAULT now())",
            ));
        }
        return Ok(DetectedType {
            auto: true,
            ..inner_det
        });
    }

    if last.ident == "ForeignKey" {
        let (inner, key_ty) = generic_pair(ty, &last.arguments, "ForeignKey")?;
        // Resolve the FK column's underlying SQL type from `K`. When the
        // user wrote `ForeignKey<T>` without a key parameter, the type
        // alias defaults to `i64` and we keep the v0.7 BIGINT shape.
        // When the user wrote `ForeignKey<T, K>` with an explicit `K`,
        // recurse into K so the column DDL emits the right SQL type
        // (VARCHAR for String, UUID for Uuid, …) and the load_related
        // emitter knows which `SqlValue` variant to match.
        let kind = match key_ty {
            Some(k) => detect_type(k)?.kind,
            None => DetectedKind::I64,
        };
        return Ok(DetectedType {
            kind,
            nullable: false,
            auto: false,
            fk_inner: Some(inner),
        });
    }

    let kind = match last.ident.to_string().as_str() {
        "i16" => DetectedKind::I16,
        "i32" => DetectedKind::I32,
        "i64" => DetectedKind::I64,
        "f32" => DetectedKind::F32,
        "f64" => DetectedKind::F64,
        "bool" => DetectedKind::Bool,
        "String" => DetectedKind::String,
        "DateTime" => DetectedKind::DateTime,
        "NaiveDate" => DetectedKind::Date,
        "NaiveTime" => DetectedKind::Time,
        "Uuid" => DetectedKind::Uuid,
        "Value" => DetectedKind::Json,
        "Decimal" => DetectedKind::Decimal,
        // `Vec<u8>` → BYTEA / LONGBLOB / BLOB. Reject any other
        // `Vec<T>` so we don't silently accept e.g. `Vec<String>`
        // — that would emit Binary DDL and decode-fail at runtime.
        "Vec" => {
            let (inner, _) = generic_pair(ty, &last.arguments, "Vec")?;
            if let Type::Path(TypePath { path, qself: None }) = inner {
                if let Some(seg) = path.segments.last() {
                    if seg.ident == "u8" && seg.arguments.is_empty() {
                        return Ok(DetectedType {
                            kind: DetectedKind::Binary,
                            nullable: false,
                            auto: false,
                            fk_inner: None,
                        });
                    }
                }
            }
            return Err(syn::Error::new_spanned(
                ty,
                "unsupported `Vec<T>` field — only `Vec<u8>` (→ Binary) is supported; \
                 for a PostgreSQL array column use `Array<String>` / `Array<i32>` / `Array<i64>`",
            ));
        }
        // `Array<String>` / `Array<i32>` / `Array<i64>` → PG `text[]` /
        // `integer[]` / `bigint[]` (#341).
        "Array" => {
            let (inner, _) = generic_pair(ty, &last.arguments, "Array")?;
            let elem = match inner {
                Type::Path(TypePath { path, qself: None }) => {
                    path.segments.last().map(|s| s.ident.to_string())
                }
                _ => None,
            };
            let kind = match elem.as_deref() {
                Some("String") => DetectedKind::ArrayText,
                Some("i32") => DetectedKind::ArrayInt,
                Some("i64") => DetectedKind::ArrayBigInt,
                _ => {
                    return Err(syn::Error::new_spanned(
                        ty,
                        "unsupported `Array<T>` element — only `Array<String>` (→ text[]), \
                         `Array<i32>` (→ integer[]), and `Array<i64>` (→ bigint[]) are supported (#341)",
                    ));
                }
            };
            return Ok(DetectedType {
                kind,
                nullable: false,
                auto: false,
                fk_inner: None,
            });
        }
        // `Range<i32>` / `Range<i64>` / `Range<Decimal>` /
        // `Range<NaiveDate>` / `Range<DateTime<…>>` → PG `int4range` /
        // `int8range` / `numrange` / `daterange` / `tstzrange` (#343).
        "Range" => {
            let (inner, _) = generic_pair(ty, &last.arguments, "Range")?;
            let elem = match inner {
                Type::Path(TypePath { path, qself: None }) => {
                    path.segments.last().map(|s| s.ident.to_string())
                }
                _ => None,
            };
            let kind = match elem.as_deref() {
                Some("i32") => DetectedKind::RangeInt,
                Some("i64") => DetectedKind::RangeBigInt,
                Some("Decimal") => DetectedKind::RangeNumeric,
                Some("NaiveDate") => DetectedKind::RangeDate,
                Some("DateTime") => DetectedKind::RangeDateTime,
                _ => {
                    return Err(syn::Error::new_spanned(
                        ty,
                        "unsupported `Range<T>` element — only `Range<i32>` (→ int4range), \
                         `Range<i64>` (→ int8range), `Range<Decimal>` (→ numrange), \
                         `Range<NaiveDate>` (→ daterange), and `Range<DateTime<Utc>>` \
                         (→ tstzrange) are supported (#343)",
                    ));
                }
            };
            return Ok(DetectedType {
                kind,
                nullable: false,
                auto: false,
                fk_inner: None,
            });
        }
        // `Cast<C>` → attribute cast (#819). The column is plain `TEXT`
        // (the `CastValue` impl bridges logical↔stored); the field's own
        // sqlx `Decode` / `Into<SqlValue>` handle the transform, so the
        // schema just needs `FieldType::String`.
        "Cast" => {
            return Ok(DetectedType {
                kind: DetectedKind::String,
                nullable: false,
                auto: false,
                fk_inner: None,
            });
        }
        // `HStore` → PG `hstore` (#342). No generic
        // parameter — always a string→string map.
        "HStore" => {
            return Ok(DetectedType {
                kind: DetectedKind::HStore,
                nullable: false,
                auto: false,
                fk_inner: None,
            });
        }
        // `Vector` → pgvector `vector(N)` (#824). The dimension is
        // supplied by `#[rustango(vector(dims = N))]`, not the type.
        "Vector" => {
            return Ok(DetectedType {
                kind: DetectedKind::Vector,
                nullable: false,
                auto: false,
                fk_inner: None,
            });
        }
        // `Point` → PostGIS `geometry(Point, srid)` (#443). The SRID is
        // supplied by `#[rustango(geometry(srid = N))]`, not the type.
        "Point" => {
            return Ok(DetectedType {
                kind: DetectedKind::Geometry,
                nullable: false,
                auto: false,
                fk_inner: None,
            });
        }
        other => {
            return Err(syn::Error::new_spanned(
                ty,
                format!("unsupported field type `{other}`; supports i16/i32/i64/f32/f64/bool/String/DateTime/NaiveDate/NaiveTime/Uuid/serde_json::Value/Decimal/Vec<u8>, optionally wrapped in Option or Auto (Auto only on integers/Uuid/DateTime)"),
            ));
        }
    };
    Ok(DetectedType {
        kind,
        nullable: false,
        auto: false,
        fk_inner: None,
    })
}

fn generic_inner<'a>(
    ty: &'a Type,
    arguments: &'a PathArguments,
    wrapper: &str,
) -> syn::Result<&'a Type> {
    let PathArguments::AngleBracketed(args) = arguments else {
        return Err(syn::Error::new_spanned(
            ty,
            format!("{wrapper} requires a generic argument"),
        ));
    };
    args.args
        .iter()
        .find_map(|a| match a {
            GenericArgument::Type(t) => Some(t),
            _ => None,
        })
        .ok_or_else(|| {
            syn::Error::new_spanned(ty, format!("{wrapper}<T> requires a type argument"))
        })
}

/// Like [`generic_inner`] but pulls *two* type args — the first is
/// required, the second is optional. Used by the `ForeignKey<T, K>`
/// detection where K defaults to `i64` when omitted.
fn generic_pair<'a>(
    ty: &'a Type,
    arguments: &'a PathArguments,
    wrapper: &str,
) -> syn::Result<(&'a Type, Option<&'a Type>)> {
    let PathArguments::AngleBracketed(args) = arguments else {
        return Err(syn::Error::new_spanned(
            ty,
            format!("{wrapper} requires a generic argument"),
        ));
    };
    let mut types = args.args.iter().filter_map(|a| match a {
        GenericArgument::Type(t) => Some(t),
        _ => None,
    });
    let first = types.next().ok_or_else(|| {
        syn::Error::new_spanned(ty, format!("{wrapper}<T> requires a type argument"))
    })?;
    let second = types.next();
    Ok((first, second))
}

fn to_snake_case(s: &str) -> String {
    let mut out = String::with_capacity(s.len() + 4);
    for (i, ch) in s.chars().enumerate() {
        if ch.is_ascii_uppercase() {
            if i > 0 {
                out.push('_');
            }
            out.push(ch.to_ascii_lowercase());
        } else {
            out.push(ch);
        }
    }
    out
}

// ============================================================
//  #[derive(Form)]  —  slice 8.4B
// ============================================================

/// Per-field `#[form(...)]` attributes recognised by the derive.
#[derive(Default)]
struct FormFieldAttrs {
    min: Option<i64>,
    max: Option<i64>,
    min_length: Option<u32>,
    max_length: Option<u32>,
    /// `#[form(clean = "fn_name")]` — per-field clean hook.
    /// The named static method on the form struct is called after the
    /// field's typed parse + length/range checks; it gets the parsed
    /// value by reference and returns `Result<<FieldType>, String>`.
    /// On Ok, the returned value replaces the parsed one; on Err, the
    /// message is attached to the field error list. Issue #372.
    clean: Option<syn::Ident>,
}

/// Container-level `#[form(...)]` attributes. Currently only the
/// cross-field `validate` hook (issue #373).
#[derive(Default)]
struct FormContainerAttrs {
    /// `#[form(validate = "fn_name")]` — whole-form clean hook.
    /// After every per-field parse succeeds, the named method on the
    /// form struct is called with `&self` and may return
    /// `Result<(), FormErrors>`. Errors merge into the field error
    /// list. Issue #373.
    validate: Option<syn::Ident>,
}

/// Detected shape of a form field's Rust type.
#[derive(Clone, Copy)]
enum FormFieldKind {
    String,
    I16,
    I32,
    I64,
    F32,
    F64,
    Bool,
}

impl FormFieldKind {
    fn parse_method(self) -> &'static str {
        match self {
            Self::I16 => "i16",
            Self::I32 => "i32",
            Self::I64 => "i64",
            Self::F32 => "f32",
            Self::F64 => "f64",
            // String + Bool don't go through `str::parse`; the codegen
            // handles them inline.
            Self::String | Self::Bool => "",
        }
    }
}

fn expand_form(input: &DeriveInput) -> syn::Result<TokenStream2> {
    let root = rustango_root();
    let struct_name = &input.ident;

    let Data::Struct(data) = &input.data else {
        return Err(syn::Error::new_spanned(
            struct_name,
            "Form can only be derived on structs",
        ));
    };
    let Fields::Named(named) = &data.fields else {
        return Err(syn::Error::new_spanned(
            struct_name,
            "Form requires a struct with named fields",
        ));
    };

    // #373 — container-level `#[form(validate = "fn")]` hook.
    let container = parse_form_container_attrs(input)?;
    let post_field_clean: Vec<TokenStream2> = Vec::new();
    let _ = post_field_clean;

    let mut field_blocks: Vec<TokenStream2> = Vec::with_capacity(named.named.len());
    let mut field_idents: Vec<&syn::Ident> = Vec::with_capacity(named.named.len());

    for field in &named.named {
        let ident = field
            .ident
            .as_ref()
            .ok_or_else(|| syn::Error::new(field.span(), "tuple structs are not supported"))?;
        let attrs = parse_form_field_attrs(field)?;
        let (kind, nullable) = detect_form_field(&field.ty, field.span())?;
        let is_string = matches!(kind, FormFieldKind::String);
        let is_number = !is_string && !matches!(kind, FormFieldKind::Bool);
        if !is_string && (attrs.min_length.is_some() || attrs.max_length.is_some()) {
            return Err(syn::Error::new(
                field.span(),
                "`min_length` / `max_length` need a String field",
            ));
        }
        if !is_number && (attrs.min.is_some() || attrs.max.is_some()) {
            return Err(syn::Error::new(
                field.span(),
                "`min` / `max` need a numeric field",
            ));
        }

        let name_lit = ident_name(ident);
        let parse_block = render_form_field_parse(ident, &name_lit, kind, nullable, &attrs);
        // #372 — append the per-field `clean_<field>` call right after
        // the parse block when the attribute is set. The clean fn
        // takes &T and returns Result<T, String>; on Err we attach
        // the message to the field error list without aborting, so
        // the caller sees every field error at once.
        let clean_block = if let Some(clean_fn) = &attrs.clean {
            quote! {
                if __errors.fields().get(#name_lit).is_none() {
                    match Self::#clean_fn(&#ident) {
                        ::core::result::Result::Ok(__cleaned) => { #ident = __cleaned; }
                        ::core::result::Result::Err(__msg) => {
                            __errors.add(#name_lit, __msg);
                        }
                    }
                }
            }
        } else {
            quote! {}
        };
        field_blocks.push(quote! {
            #parse_block
            #clean_block
        });
        field_idents.push(ident);
    }

    // #373 — after every per-field parse + clean succeeds, call the
    // cross-field validator if declared. Errors merge into the
    // outgoing FormErrors via the existing `FormErrors::merge` helper
    // (same primitive the serializer cross-field hook uses).
    let cross_field_call = if let Some(validate_fn) = &container.validate {
        quote! {
            if __errors.is_empty() {
                let __candidate = Self { #( #field_idents ),* };
                if let ::core::result::Result::Err(__other) = Self::#validate_fn(&__candidate) {
                    __errors.merge(__other);
                }
                if !__errors.is_empty() {
                    return ::core::result::Result::Err(__errors);
                }
                return ::core::result::Result::Ok(__candidate);
            }
        }
    } else {
        quote! {}
    };

    Ok(quote! {
        impl #root::forms::Form for #struct_name {
            fn parse(
                data: &::std::collections::HashMap<::std::string::String, ::std::string::String>,
            ) -> ::core::result::Result<Self, #root::forms::FormErrors> {
                let mut __errors = #root::forms::FormErrors::default();
                #( #field_blocks )*
                #cross_field_call
                if !__errors.is_empty() {
                    return ::core::result::Result::Err(__errors);
                }
                ::core::result::Result::Ok(Self {
                    #( #field_idents ),*
                })
            }
        }
    })
}

fn parse_form_container_attrs(input: &DeriveInput) -> syn::Result<FormContainerAttrs> {
    let mut out = FormContainerAttrs::default();
    for attr in &input.attrs {
        if !attr.path().is_ident("form") {
            continue;
        }
        attr.parse_nested_meta(|meta| {
            if meta.path.is_ident("validate") {
                let s: LitStr = meta.value()?.parse()?;
                out.validate = Some(syn::Ident::new(&s.value(), s.span()));
                return Ok(());
            }
            Err(meta.error("unknown form container attribute (supported: `validate`)"))
        })?;
    }
    Ok(out)
}

fn parse_form_field_attrs(field: &syn::Field) -> syn::Result<FormFieldAttrs> {
    let mut out = FormFieldAttrs::default();
    for attr in &field.attrs {
        if !attr.path().is_ident("form") {
            continue;
        }
        attr.parse_nested_meta(|meta| {
            if meta.path.is_ident("min") {
                let lit: syn::LitInt = meta.value()?.parse()?;
                out.min = Some(lit.base10_parse::<i64>()?);
                return Ok(());
            }
            if meta.path.is_ident("max") {
                let lit: syn::LitInt = meta.value()?.parse()?;
                out.max = Some(lit.base10_parse::<i64>()?);
                return Ok(());
            }
            if meta.path.is_ident("min_length") {
                let lit: syn::LitInt = meta.value()?.parse()?;
                out.min_length = Some(lit.base10_parse::<u32>()?);
                return Ok(());
            }
            if meta.path.is_ident("max_length") {
                let lit: syn::LitInt = meta.value()?.parse()?;
                out.max_length = Some(lit.base10_parse::<u32>()?);
                return Ok(());
            }
            if meta.path.is_ident("clean") {
                let s: LitStr = meta.value()?.parse()?;
                out.clean = Some(syn::Ident::new(&s.value(), s.span()));
                return Ok(());
            }
            Err(meta.error(
                "unknown form field attribute (supported: `min`, `max`, `min_length`, `max_length`, `clean`)",
            ))
        })?;
    }
    Ok(out)
}

fn detect_form_field(ty: &Type, span: proc_macro2::Span) -> syn::Result<(FormFieldKind, bool)> {
    let Type::Path(TypePath { path, qself: None }) = ty else {
        return Err(syn::Error::new(
            span,
            "Form field must be a simple typed path (e.g. `String`, `i32`, `Option<String>`)",
        ));
    };
    let last = path
        .segments
        .last()
        .ok_or_else(|| syn::Error::new(span, "empty type path"))?;

    if last.ident == "Option" {
        let inner = generic_inner(ty, &last.arguments, "Option")?;
        let (kind, nested) = detect_form_field(inner, span)?;
        if nested {
            return Err(syn::Error::new(
                span,
                "nested Option in Form fields is not supported",
            ));
        }
        return Ok((kind, true));
    }

    let kind = match last.ident.to_string().as_str() {
        "String" => FormFieldKind::String,
        "i16" => FormFieldKind::I16,
        "i32" => FormFieldKind::I32,
        "i64" => FormFieldKind::I64,
        "f32" => FormFieldKind::F32,
        "f64" => FormFieldKind::F64,
        "bool" => FormFieldKind::Bool,
        other => {
            return Err(syn::Error::new(
                span,
                format!(
                    "Form field type `{other}` is not supported in v0.8 — use String / \
                     i16 / i32 / i64 / f32 / f64 / bool, optionally wrapped in Option<…>"
                ),
            ));
        }
    };
    Ok((kind, false))
}

#[allow(clippy::too_many_lines)]
fn render_form_field_parse(
    ident: &syn::Ident,
    name_lit: &str,
    kind: FormFieldKind,
    nullable: bool,
    attrs: &FormFieldAttrs,
) -> TokenStream2 {
    // Pull the raw &str from the payload. Uses variable name `data` to
    // match the new `Form::parse(data: &HashMap<…>)` signature.
    let lookup = quote! {
        let __raw: ::core::option::Option<&::std::string::String> = data.get(#name_lit);
    };

    let parsed_value = match kind {
        // `Option<bool>`: absent or blank is `None`, as for the other types.
        FormFieldKind::Bool if nullable => quote! {
            let __v: ::core::option::Option<bool> = match __raw {
                ::core::option::Option::None => ::core::option::Option::None,
                ::core::option::Option::Some(__s) if __s.is_empty() => {
                    ::core::option::Option::None
                }
                ::core::option::Option::Some(__s) => ::core::option::Option::Some(!matches!(
                    __s.to_ascii_lowercase().as_str(),
                    "false" | "0" | "off" | "no"
                )),
            };
        },
        FormFieldKind::Bool => quote! {
            let __v: bool = match __raw {
                ::core::option::Option::None => false,
                ::core::option::Option::Some(__s) => !matches!(
                    __s.to_ascii_lowercase().as_str(),
                    "" | "false" | "0" | "off" | "no"
                ),
            };
        },
        FormFieldKind::String => {
            if nullable {
                quote! {
                    let __v: ::core::option::Option<::std::string::String> = match __raw {
                        ::core::option::Option::None => ::core::option::Option::None,
                        ::core::option::Option::Some(__s) if __s.is_empty() => {
                            ::core::option::Option::None
                        }
                        ::core::option::Option::Some(__s) => {
                            ::core::option::Option::Some(::core::clone::Clone::clone(__s))
                        }
                    };
                }
            } else {
                quote! {
                    let __v: ::std::string::String = match __raw {
                        ::core::option::Option::Some(__s) if !__s.is_empty() => {
                            ::core::clone::Clone::clone(__s)
                        }
                        _ => {
                            __errors.add(#name_lit, "This field is required.");
                            ::std::string::String::new()
                        }
                    };
                }
            }
        }
        FormFieldKind::I16
        | FormFieldKind::I32
        | FormFieldKind::I64
        | FormFieldKind::F32
        | FormFieldKind::F64 => {
            let parse_ty = syn::Ident::new(kind.parse_method(), proc_macro2::Span::call_site());
            let ty_lit = kind.parse_method();
            let default_val = match kind {
                FormFieldKind::I16 => quote! { 0i16 },
                FormFieldKind::I32 => quote! { 0i32 },
                FormFieldKind::I64 => quote! { 0i64 },
                FormFieldKind::F32 => quote! { 0f32 },
                FormFieldKind::F64 => quote! { 0f64 },
                _ => quote! { Default::default() },
            };
            if nullable {
                quote! {
                    let __v: ::core::option::Option<#parse_ty> = match __raw {
                        ::core::option::Option::None => ::core::option::Option::None,
                        ::core::option::Option::Some(__s) if __s.is_empty() => {
                            ::core::option::Option::None
                        }
                        ::core::option::Option::Some(__s) => {
                            match __s.parse::<#parse_ty>() {
                                ::core::result::Result::Ok(__n) => {
                                    ::core::option::Option::Some(__n)
                                }
                                ::core::result::Result::Err(__e) => {
                                    __errors.add(
                                        #name_lit,
                                        ::std::format!("Enter a valid {} value: {}", #ty_lit, __e),
                                    );
                                    ::core::option::Option::None
                                }
                            }
                        }
                    };
                }
            } else {
                quote! {
                    let __v: #parse_ty = match __raw {
                        ::core::option::Option::Some(__s) if !__s.is_empty() => {
                            match __s.parse::<#parse_ty>() {
                                ::core::result::Result::Ok(__n) => __n,
                                ::core::result::Result::Err(__e) => {
                                    __errors.add(
                                        #name_lit,
                                        ::std::format!("Enter a valid {} value: {}", #ty_lit, __e),
                                    );
                                    #default_val
                                }
                            }
                        }
                        _ => {
                            __errors.add(#name_lit, "This field is required.");
                            #default_val
                        }
                    };
                }
            }
        }
    };

    let validators = render_form_validators(name_lit, kind, nullable, attrs);

    quote! {
        // `mut` so the per-field `clean` hook (#372) can rewrite the
        // parsed value in-place when it returns Ok with a normalized
        // form (e.g. trim / lowercase).
        let mut #ident = {
            #lookup
            #parsed_value
            #validators
            __v
        };
    }
}

fn render_form_validators(
    name_lit: &str,
    kind: FormFieldKind,
    nullable: bool,
    attrs: &FormFieldAttrs,
) -> TokenStream2 {
    let mut checks: Vec<TokenStream2> = Vec::new();

    let val_ref = if nullable {
        quote! { __v.as_ref() }
    } else {
        quote! { ::core::option::Option::Some(&__v) }
    };

    let is_string = matches!(kind, FormFieldKind::String);
    let is_numeric = matches!(
        kind,
        FormFieldKind::I16
            | FormFieldKind::I32
            | FormFieldKind::I64
            | FormFieldKind::F32
            | FormFieldKind::F64
    );

    if is_string {
        if let Some(min_len) = attrs.min_length {
            let min_len_usize = min_len as usize;
            checks.push(quote! {
                if let ::core::option::Option::Some(__s) = #val_ref {
                    if __s.chars().count() < #min_len_usize {
                        __errors.add(
                            #name_lit,
                            ::std::format!("Ensure this value has at least {} characters.", #min_len_usize),
                        );
                    }
                }
            });
        }
        if let Some(max_len) = attrs.max_length {
            let max_len_usize = max_len as usize;
            checks.push(quote! {
                if let ::core::option::Option::Some(__s) = #val_ref {
                    if __s.chars().count() > #max_len_usize {
                        __errors.add(
                            #name_lit,
                            ::std::format!("Ensure this value has at most {} characters.", #max_len_usize),
                        );
                    }
                }
            });
        }
    }

    if is_numeric {
        if let Some(min) = attrs.min {
            checks.push(quote! {
                if let ::core::option::Option::Some(__n) = #val_ref {
                    if (*__n as f64) < (#min as f64) {
                        __errors.add(
                            #name_lit,
                            ::std::format!("Ensure this value is greater than or equal to {}.", #min),
                        );
                    }
                }
            });
        }
        if let Some(max) = attrs.max {
            checks.push(quote! {
                if let ::core::option::Option::Some(__n) = #val_ref {
                    if (*__n as f64) > (#max as f64) {
                        __errors.add(
                            #name_lit,
                            ::std::format!("Ensure this value is less than or equal to {}.", #max),
                        );
                    }
                }
            });
        }
    }

    quote! { #( #checks )* }
}

// ============================================================
//  #[derive(ViewSet)]
// ============================================================

struct ViewSetAttrs {
    model: syn::Path,
    fields: Option<Vec<String>>,
    filter_fields: Vec<String>,
    search_fields: Vec<String>,
    /// (field_name, desc)
    ordering: Vec<(String, bool)>,
    page_size: Option<usize>,
    read_only: bool,
    allow_anonymous: bool,
    perms: ViewSetPermsAttrs,
    /// `#[viewset(serializer = SomeSerializer)]` — render list /
    /// retrieve / create responses through this `#[derive(Serializer)]`
    /// type instead of the default field-level projection (requires the
    /// `serializer` feature). Tri-dialect.
    serializer: Option<syn::Path>,
}

#[derive(Default)]
struct ViewSetPermsAttrs {
    list: Vec<String>,
    retrieve: Vec<String>,
    create: Vec<String>,
    update: Vec<String>,
    destroy: Vec<String>,
}

fn expand_viewset(input: &DeriveInput) -> syn::Result<TokenStream2> {
    let root = rustango_root();
    let struct_name = &input.ident;

    // Must be a unit struct or an empty named struct.
    match &input.data {
        Data::Struct(s) => match &s.fields {
            Fields::Unit | Fields::Named(_) => {}
            Fields::Unnamed(_) => {
                return Err(syn::Error::new_spanned(
                    struct_name,
                    "ViewSet can only be derived on a unit struct or an empty named struct",
                ));
            }
        },
        _ => {
            return Err(syn::Error::new_spanned(
                struct_name,
                "ViewSet can only be derived on a struct",
            ));
        }
    }

    let attrs = parse_viewset_attrs(input)?;
    let model_path = &attrs.model;

    // `.fields(&[...])` call — None means skip (use all scalar fields).
    let fields_call = if let Some(ref fields) = attrs.fields {
        let lits = fields.iter().map(|f| f.as_str());
        quote!(.fields(&[ #(#lits),* ]))
    } else {
        quote!()
    };

    let filter_fields_call = if attrs.filter_fields.is_empty() {
        quote!()
    } else {
        let lits = attrs.filter_fields.iter().map(|f| f.as_str());
        quote!(.filter_fields(&[ #(#lits),* ]))
    };

    let search_fields_call = if attrs.search_fields.is_empty() {
        quote!()
    } else {
        let lits = attrs.search_fields.iter().map(|f| f.as_str());
        quote!(.search_fields(&[ #(#lits),* ]))
    };

    let ordering_call = if attrs.ordering.is_empty() {
        quote!()
    } else {
        let pairs = attrs.ordering.iter().map(|(f, desc)| {
            let f = f.as_str();
            quote!((#f, #desc))
        });
        quote!(.ordering(&[ #(#pairs),* ]))
    };

    let page_size_call = if let Some(n) = attrs.page_size {
        quote!(.page_size(#n))
    } else {
        quote!()
    };

    let read_only_call = if attrs.read_only {
        quote!(.read_only())
    } else {
        quote!()
    };
    let allow_anonymous_call = if attrs.allow_anonymous {
        quote!(.allow_anonymous())
    } else {
        quote!()
    };

    // `.serializer::<S>()` — reshape responses through a derived
    // serializer. Requires the downstream crate to enable the
    // `serializer` feature (the method is gated on it).
    let serializer_call = if let Some(ref ser) = attrs.serializer {
        quote!(.serializer::<#ser>())
    } else {
        quote!()
    };

    let perms = &attrs.perms;
    let perms_call = if perms.list.is_empty()
        && perms.retrieve.is_empty()
        && perms.create.is_empty()
        && perms.update.is_empty()
        && perms.destroy.is_empty()
    {
        quote!()
    } else {
        let list_lits = perms.list.iter().map(|s| s.as_str());
        let retrieve_lits = perms.retrieve.iter().map(|s| s.as_str());
        let create_lits = perms.create.iter().map(|s| s.as_str());
        let update_lits = perms.update.iter().map(|s| s.as_str());
        let destroy_lits = perms.destroy.iter().map(|s| s.as_str());
        quote! {
            .permissions(#root::viewset::ViewSetPerms {
                list:     ::std::vec![ #(#list_lits.to_owned()),* ],
                retrieve: ::std::vec![ #(#retrieve_lits.to_owned()),* ],
                create:   ::std::vec![ #(#create_lits.to_owned()),* ],
                update:   ::std::vec![ #(#update_lits.to_owned()),* ],
                destroy:  ::std::vec![ #(#destroy_lits.to_owned()),* ],
            })
        }
    };

    Ok(quote! {
        impl #struct_name {
            /// Build an `axum::Router` with the six standard REST endpoints
            /// for this ViewSet, mounted at `prefix`.
            ///
            /// Accepts any backend's pool — a `sqlx::PgPool`,
            /// `SqlitePool`, `MySqlPool`, or the [`rustango::sql::Pool`]
            /// enum — because they all `Into<Pool>` (#1273). This is why
            /// the derive no longer names `PgPool`, which would not
            /// exist on a project built without the `postgres` feature.
            pub fn router(
                prefix: &str,
                pool: impl ::core::convert::Into<#root::sql::Pool>,
            ) -> #root::__axum::Router {
                #root::viewset::ViewSet::for_model(
                    <#model_path as #root::core::Model>::SCHEMA
                )
                    #fields_call
                    #filter_fields_call
                    #search_fields_call
                    #ordering_call
                    #page_size_call
                    #perms_call
                    #read_only_call
                    #allow_anonymous_call
                    #serializer_call
                    .router_pool(prefix, pool.into())
            }
        }
    })
}

fn parse_viewset_attrs(input: &DeriveInput) -> syn::Result<ViewSetAttrs> {
    let mut model: Option<syn::Path> = None;
    let mut fields: Option<Vec<String>> = None;
    let mut filter_fields: Vec<String> = Vec::new();
    let mut search_fields: Vec<String> = Vec::new();
    let mut ordering: Vec<(String, bool)> = Vec::new();
    let mut page_size: Option<usize> = None;
    let mut read_only = false;
    let mut allow_anonymous = false;
    let mut perms = ViewSetPermsAttrs::default();
    let mut serializer: Option<syn::Path> = None;

    for attr in &input.attrs {
        if !attr.path().is_ident("viewset") {
            continue;
        }
        attr.parse_nested_meta(|meta| {
            if meta.path.is_ident("model") {
                let path: syn::Path = meta.value()?.parse()?;
                model = Some(path);
                return Ok(());
            }
            if meta.path.is_ident("serializer") {
                let path: syn::Path = meta.value()?.parse()?;
                serializer = Some(path);
                return Ok(());
            }
            if meta.path.is_ident("fields") {
                let s: LitStr = meta.value()?.parse()?;
                fields = Some(split_field_list(&s.value()));
                return Ok(());
            }
            if meta.path.is_ident("filter_fields") {
                let s: LitStr = meta.value()?.parse()?;
                filter_fields = split_field_list(&s.value());
                return Ok(());
            }
            if meta.path.is_ident("search_fields") {
                let s: LitStr = meta.value()?.parse()?;
                search_fields = split_field_list(&s.value());
                return Ok(());
            }
            if meta.path.is_ident("ordering") {
                let s: LitStr = meta.value()?.parse()?;
                ordering = parse_ordering_list(&s.value());
                return Ok(());
            }
            if meta.path.is_ident("page_size") {
                let lit: syn::LitInt = meta.value()?.parse()?;
                page_size = Some(lit.base10_parse::<usize>()?);
                return Ok(());
            }
            if meta.path.is_ident("read_only") {
                read_only = true;
                return Ok(());
            }
            if meta.path.is_ident("allow_anonymous") {
                allow_anonymous = true;
                return Ok(());
            }
            if meta.path.is_ident("permissions") {
                meta.parse_nested_meta(|inner| {
                    let parse_codenames = |inner: &syn::meta::ParseNestedMeta| -> syn::Result<Vec<String>> {
                        let s: LitStr = inner.value()?.parse()?;
                        Ok(split_field_list(&s.value()))
                    };
                    if inner.path.is_ident("list") {
                        perms.list = parse_codenames(&inner)?;
                    } else if inner.path.is_ident("retrieve") {
                        perms.retrieve = parse_codenames(&inner)?;
                    } else if inner.path.is_ident("create") {
                        perms.create = parse_codenames(&inner)?;
                    } else if inner.path.is_ident("update") {
                        perms.update = parse_codenames(&inner)?;
                    } else if inner.path.is_ident("destroy") {
                        perms.destroy = parse_codenames(&inner)?;
                    } else {
                        return Err(inner.error(
                            "unknown permissions key (supported: list, retrieve, create, update, destroy)",
                        ));
                    }
                    Ok(())
                })?;
                return Ok(());
            }
            Err(meta.error(
                "unknown viewset attribute (supported: model, fields, filter_fields, \
                 search_fields, ordering, page_size, read_only, allow_anonymous, serializer, \
                 permissions(...))",
            ))
        })?;
    }

    let model = model.ok_or_else(|| {
        syn::Error::new_spanned(&input.ident, "`#[viewset(model = SomeModel)]` is required")
    })?;

    Ok(ViewSetAttrs {
        model,
        fields,
        filter_fields,
        search_fields,
        ordering,
        page_size,
        read_only,
        allow_anonymous,
        perms,
        serializer,
    })
}

// ============================================================ #[derive(Serializer)]

struct SerializerContainerAttrs {
    model: syn::Path,
    /// `#[serializer(validate = "fn_name")]` on the struct — the
    /// cross-field validation hook (#436). The named inherent method
    /// must take `&self` and return
    /// `Result<(), rustango::forms::FormErrors>`. The macro-emitted
    /// `validate()` runs every per-field validator first; then calls
    /// the cross-field method if declared; aggregates all errors into
    /// one `FormErrors`.
    cross_validate: Option<syn::Ident>,
}

#[derive(Default)]
struct SerializerFieldAttrs {
    read_only: bool,
    write_only: bool,
    source: Option<String>,
    skip: bool,
    /// `#[serializer(method = "fn_name")]` — computed field. The macro
    /// emits a `from_model` initializer that calls
    /// `Self::fn_name(&model)` and stores the return value.
    method: Option<String>,
    /// `#[serializer(validate = "fn_name")]` — per-field validator
    /// callable run by `Self::validate(&self)`. Must return
    /// `Result<(), String>`. Errors land in `FormErrors` keyed by
    /// the field name.
    validate: Option<String>,
    /// `#[serializer(nested)]` on a field whose type is another
    /// `Serializer` — the macro emits `from_model` initializer that
    /// reads the parent via `model.<source>.value()` then calls the
    /// child serializer's `from_model(parent)`. When the FK is
    /// unloaded the field falls back to `Default::default()` (does
    /// NOT panic) so a missing prefetch in prod degrades gracefully.
    /// Source field on the model defaults to the field name; override
    /// with `source = "..."`. Combine with `strict` to keep the v0.18.1
    /// panic-on-unloaded behavior for tests.
    nested: bool,
    /// `#[serializer(nested, strict)]` — opt back into the v0.18.1
    /// strict behavior: panic when the FK isn't loaded. Useful in
    /// test code where forgetting select_related must trip a hard
    /// failure rather than render a blank nested object.
    nested_strict: bool,
    /// `#[serializer(many = TagSerializer)]` — declare the field as
    /// a list of nested serializers. Field type must be `Vec<S>`
    /// where `S` is the inner serializer. The macro initializes the
    /// field to `Vec::new()` in `from_model` and emits a typed
    /// `set_<field>(&mut self, models: &[<S::Model>])` helper that
    /// maps each model row through `S::from_model`. Auto-load isn't
    /// possible (the M2M / one-to-many accessor is async); callers
    /// fetch the children + call the setter post-from_model.
    many: Option<syn::Type>,
    /// `#[serializer(slug = "name")]` — render a relation as one of
    /// its fields.
    /// Source field on the model must be a `ForeignKey<T>`; the
    /// macro emits `from_model` glue that walks
    /// `model.<source>.value()?.<slug>` and clones it. Field type on
    /// the serializer is typically `String` (whatever type the slug
    /// column has). When the FK is unloaded the field falls back to
    /// `Default::default()`, same graceful-degrade contract as
    /// `nested`. Source defaults to the field name; override with
    /// `source = "..."`. v0.44.
    slug: Option<String>,
    /// `#[serializer(max_length = N)]` — caps
    /// the character count of a string field on write. Overrides the
    /// model's `max_length`; when absent the model value is inherited.
    max_length: Option<u64>,
    /// `#[serializer(min_length = N)]` — minimum character count.
    /// Serializer-only (the model has no `min_length` column).
    min_length: Option<u64>,
    /// `#[serializer(min = N)]` — inclusive
    /// integer lower bound; overrides the model's `min` when given.
    min: Option<i64>,
    /// `#[serializer(max = N)]` — inclusive
    /// integer upper bound; overrides the model's `max` when given.
    max: Option<i64>,
}

fn parse_serializer_container_attrs(input: &DeriveInput) -> syn::Result<SerializerContainerAttrs> {
    let mut model: Option<syn::Path> = None;
    let mut cross_validate: Option<syn::Ident> = None;
    for attr in &input.attrs {
        if !attr.path().is_ident("serializer") {
            continue;
        }
        attr.parse_nested_meta(|meta| {
            if meta.path.is_ident("model") {
                let _eq: syn::Token![=] = meta.input.parse()?;
                model = Some(meta.input.parse()?);
                return Ok(());
            }
            if meta.path.is_ident("validate") {
                // #436 — container-level `validate = "fn_name"` for
                // cross-field validation. Field-level
                // `#[serializer(validate = "...")]` on a field is
                // parsed separately in `parse_serializer_field_attrs`.
                let s: LitStr = meta.value()?.parse()?;
                cross_validate = Some(syn::Ident::new(&s.value(), s.span()));
                return Ok(());
            }
            Err(meta.error(
                "unknown serializer container attribute \
                 (supported: `model`, `validate`)",
            ))
        })?;
    }
    let model = model.ok_or_else(|| {
        syn::Error::new_spanned(
            &input.ident,
            "`#[serializer(model = SomeModel)]` is required",
        )
    })?;
    Ok(SerializerContainerAttrs {
        model,
        cross_validate,
    })
}

fn parse_serializer_field_attrs(field: &syn::Field) -> syn::Result<SerializerFieldAttrs> {
    let mut out = SerializerFieldAttrs::default();
    for attr in &field.attrs {
        if !attr.path().is_ident("serializer") {
            continue;
        }
        attr.parse_nested_meta(|meta| {
            if meta.path.is_ident("read_only") {
                out.read_only = true;
                return Ok(());
            }
            if meta.path.is_ident("write_only") {
                out.write_only = true;
                return Ok(());
            }
            if meta.path.is_ident("skip") {
                out.skip = true;
                return Ok(());
            }
            if meta.path.is_ident("source") {
                let s: LitStr = meta.value()?.parse()?;
                out.source = Some(s.value());
                return Ok(());
            }
            if meta.path.is_ident("method") {
                let s: LitStr = meta.value()?.parse()?;
                out.method = Some(s.value());
                return Ok(());
            }
            if meta.path.is_ident("validate") {
                let s: LitStr = meta.value()?.parse()?;
                out.validate = Some(s.value());
                return Ok(());
            }
            if meta.path.is_ident("many") {
                let _eq: syn::Token![=] = meta.input.parse()?;
                out.many = Some(meta.input.parse()?);
                return Ok(());
            }
            if meta.path.is_ident("nested") {
                out.nested = true;
                // Optional strict flag inside parentheses:
                //   #[serializer(nested(strict))]
                if meta.input.peek(syn::token::Paren) {
                    meta.parse_nested_meta(|inner| {
                        if inner.path.is_ident("strict") {
                            out.nested_strict = true;
                            return Ok(());
                        }
                        Err(inner.error("unknown nested sub-attribute (supported: `strict`)"))
                    })?;
                }
                return Ok(());
            }
            if meta.path.is_ident("slug") {
                let s: LitStr = meta.value()?.parse()?;
                out.slug = Some(s.value());
                return Ok(());
            }
            if meta.path.is_ident("max_length") {
                let lit: syn::LitInt = meta.value()?.parse()?;
                out.max_length = Some(lit.base10_parse::<u64>()?);
                return Ok(());
            }
            if meta.path.is_ident("min_length") {
                let lit: syn::LitInt = meta.value()?.parse()?;
                out.min_length = Some(lit.base10_parse::<u64>()?);
                return Ok(());
            }
            if meta.path.is_ident("min") {
                let lit: syn::LitInt = meta.value()?.parse()?;
                out.min = Some(lit.base10_parse::<i64>()?);
                return Ok(());
            }
            if meta.path.is_ident("max") {
                let lit: syn::LitInt = meta.value()?.parse()?;
                out.max = Some(lit.base10_parse::<i64>()?);
                return Ok(());
            }
            Err(meta.error(
                "unknown serializer field attribute (supported: \
                 `read_only`, `write_only`, `source`, `skip`, `method`, \
                 `validate`, `nested`, `many`, `slug`, `max_length`, \
                 `min_length`, `min`, `max`)",
            ))
        })?;
    }
    // Validate: read_only + write_only is nonsensical
    if out.read_only && out.write_only {
        return Err(syn::Error::new_spanned(
            field,
            "a field cannot be both `read_only` and `write_only`",
        ));
    }
    if out.method.is_some() && out.source.is_some() {
        return Err(syn::Error::new_spanned(
            field,
            "`method` and `source` are mutually exclusive — `method` computes \
             the value from a method, `source` reads it from a different model field",
        ));
    }
    if out.slug.is_some() && (out.method.is_some() || out.nested || out.many.is_some()) {
        return Err(syn::Error::new_spanned(
            field,
            "`slug` is mutually exclusive with `method`, `nested`, and `many` \
             — pick one strategy for populating the field",
        ));
    }
    Ok(out)
}

fn expand_serializer(input: &DeriveInput) -> syn::Result<TokenStream2> {
    let root = rustango_root();
    let struct_name = &input.ident;
    let struct_name_lit = struct_name.to_string();

    let Data::Struct(data) = &input.data else {
        return Err(syn::Error::new_spanned(
            struct_name,
            "Serializer can only be derived on structs",
        ));
    };
    let Fields::Named(named) = &data.fields else {
        return Err(syn::Error::new_spanned(
            struct_name,
            "Serializer requires a struct with named fields",
        ));
    };

    let container = parse_serializer_container_attrs(input)?;
    let model_path = &container.model;

    // Classify each field. `ty` is only consumed by the
    // `#[cfg(feature = "openapi")]` block below, but we always
    // capture it to keep the field-info build a single pass.
    #[allow(dead_code)]
    struct FieldInfo {
        ident: syn::Ident,
        ty: syn::Type,
        attrs: SerializerFieldAttrs,
    }
    let mut fields_info: Vec<FieldInfo> = Vec::new();
    for field in &named.named {
        let ident = field.ident.clone().expect("named field has ident");
        let attrs = parse_serializer_field_attrs(field)?;
        fields_info.push(FieldInfo {
            ident,
            ty: field.ty.clone(),
            attrs,
        });
    }

    // Generate from_model body: struct literal with each field assigned.
    let from_model_fields = fields_info.iter().map(|fi| {
        let ident = &fi.ident;
        if let Some(_inner) = &fi.attrs.many {
            // Many — collection field. Initialize empty; caller
            // populates via the macro-emitted set_<field> helper
            // after fetching the M2M children.
            quote! { #ident: ::std::vec::Vec::new() }
        } else if let Some(method) = &fi.attrs.method {
            // SerializerMethodField: call Self::<method>(&model) to
            // compute the value. Method signature must be
            // `fn <method>(model: &T) -> <field type>`.
            let method_ident = syn::Ident::new(method, ident.span());
            quote! { #ident: Self::#method_ident(model) }
        } else if let Some(slug_field) = &fi.attrs.slug {
            // v0.44 — SlugRelatedField. Source defaults to the field
            // name on this struct; override via `source = "..."`. The
            // source field on the model is expected to be a
            // `ForeignKey<T>`; the slug field on the parent is named
            // by the attribute value. When the FK is unloaded the
            // field falls back to `Default::default()` — same
            // graceful-degrade contract as `nested`; a NULL
            // `Option<ForeignKey>` renders `None`.
            let src_name = fi
                .attrs
                .source
                .as_deref()
                .unwrap_or(&ident_name(&fi.ident))
                .to_owned();
            let src_ident = ident_from_name(&src_name, ident.span());
            let slug_ident = syn::Ident::new(slug_field, ident.span());
            quote! {
                #ident: #root::serializer::LoadedRelation::render(
                    &model.#src_ident,
                    |__loaded| ::core::clone::Clone::clone(&__loaded.#slug_ident),
                    ::core::default::Default::default,
                )
            }
        } else if fi.attrs.nested {
            // Nested serializer. Source defaults to the field name on
            // this struct; override via `source = "..."`. The source
            // field on the model is a `ForeignKey<T>` or
            // `Option<ForeignKey<T>>`, read through `LoadedRelation`.
            //
            // Behavior matrix (tweakable per-field):
            //   * FK loaded   → nested object materializes via
            //                   ChildSerializer::from_model(parent).
            //   * FK unloaded → fall back to ChildSerializer::default()
            //                   (so prod doesn't crash on a missing
            //                   prefetch — just renders a blank nested
            //                   object). Add `#[serializer(nested(
            //                   strict))]` to keep the v0.18.1
            //                   panic-on-unloaded behavior for tests
            //                   that want hard guardrails.
            //   * NULL `Option<ForeignKey>` → `None` in an `Option<Child>`
            //                   field (JSON null), strict or not.
            let src_name = fi.attrs.source.as_deref().unwrap_or(&ident_name(&fi.ident)).to_owned();
            let src_ident = ident_from_name(&src_name, ident.span());
            let unloaded = if fi.attrs.nested_strict {
                let panic_msg = format!(
                    "nested(strict) serializer for `{ident}` requires `model.{src_name}` to be loaded — \
                     call .get(&pool).await? or .select_related(\"{src_name}\") on the model first",
                );
                quote! { || ::core::panic!("{}", #panic_msg) }
            } else {
                quote! { ::core::default::Default::default }
            };
            quote! {
                #ident: #root::serializer::LoadedRelation::render(
                    &model.#src_ident,
                    |__loaded| #root::serializer::ModelSerializer::from_model(__loaded),
                    #unloaded,
                )
            }
        } else if fi.attrs.write_only || fi.attrs.skip {
            // Not read from model — use default
            quote! { #ident: ::core::default::Default::default() }
        } else if let Some(src) = &fi.attrs.source {
            let src_ident = ident_from_name(src, ident.span());
            quote! { #ident: ::core::clone::Clone::clone(&model.#src_ident) }
        } else {
            quote! { #ident: ::core::clone::Clone::clone(&model.#ident) }
        }
    });

    // is_writable predicate (also used by writable_lits /
    // writable_source_lits below).
    let is_writable = |fi: &&FieldInfo| {
        !fi.attrs.read_only
            && !fi.attrs.skip
            && fi.attrs.method.is_none()
            && !fi.attrs.nested
            && fi.attrs.many.is_none()
            && fi.attrs.slug.is_none()
    };

    // Declarative field constraints: one block
    // per writable field, run inside `validate()`. Each resolves its
    // bounds as the serializer attr when given (`#[serializer(max_length
    // = N)]`), else the model's `FieldSchema` (`max_length` / `min` /
    // `max` / `choices`), then dispatches on the field's JSON value via
    // `forms::validators::check_value` (string → length/choices, integer
    // → min/max).
    let opt_usize = |v: Option<u64>| match v {
        Some(n) => {
            let n = n as usize;
            quote!(::core::option::Option::Some(#n))
        }
        None => quote!(::core::option::Option::None),
    };
    let opt_i64 = |v: Option<i64>| match v {
        Some(n) => quote!(::core::option::Option::Some(#n)),
        None => quote!(::core::option::Option::None),
    };
    let constraint_blocks: Vec<_> = fields_info
        .iter()
        .filter(is_writable)
        .map(|fi| {
            let ident = &fi.ident;
            let fname = ident_name(ident);
            let mname = fi
                .attrs
                .source
                .clone()
                .unwrap_or_else(|| ident_name(&fi.ident));
            let attr_max_len = opt_usize(fi.attrs.max_length);
            let attr_min_len = opt_usize(fi.attrs.min_length);
            let attr_min = opt_i64(fi.attrs.min);
            let attr_max = opt_i64(fi.attrs.max);
            // A bound the field's type cannot take is a compile error, not a no-op.
            let ty = &fi.ty;
            let len_check = (fi.attrs.max_length.is_some() || fi.attrs.min_length.is_some())
                .then(|| quote! { #root::forms::validators::assert_length_bounded::<#ty>(); });
            let num_check = (fi.attrs.min.is_some() || fi.attrs.max.is_some())
                .then(|| quote! { #root::forms::validators::assert_number_bounded::<#ty>(); });
            quote! {
                #len_check
                #num_check
                if __sent(#fname) {
                    let __sf = <#model_path as #root::core::Model>::SCHEMA.field(#mname);
                    let __max_length: ::core::option::Option<usize> = #attr_max_len
                        .or_else(|| __sf.and_then(|__f| __f.max_length).map(|__n| __n as usize));
                    let __min_length: ::core::option::Option<usize> = #attr_min_len;
                    let __min: ::core::option::Option<i64> =
                        #attr_min.or_else(|| __sf.and_then(|__f| __f.min));
                    let __max: ::core::option::Option<i64> =
                        #attr_max.or_else(|| __sf.and_then(|__f| __f.max));
                    let __choices = __sf.and_then(|__f| __f.choices);
                    let __v = #root::__serde_json::to_value(&self.#ident)
                        .unwrap_or(#root::__serde_json::Value::Null);
                    #root::forms::validators::check_value(
                        #fname, &__v, __max_length, __min_length, __min, __max, __choices,
                        &mut __errors,
                    );
                }
            }
        })
        .collect();
    let has_constraints = !constraint_blocks.is_empty();

    // Per-field validators. Emit a
    // `validate(&self)` method that runs each user-defined validator
    // and aggregates errors into `FormErrors`.
    let validator_calls: Vec<_> = fields_info
        .iter()
        .filter_map(|fi| {
            let ident = &fi.ident;
            let name_lit = ident_name(ident);
            let method = fi.attrs.validate.as_ref()?;
            let method_ident = syn::Ident::new(method, ident.span());
            Some(quote! {
                if __sent(#name_lit) {
                    if let ::core::result::Result::Err(__e) = Self::#method_ident(&self.#ident) {
                        __errors.add(#name_lit.to_owned(), __e);
                    }
                }
            })
        })
        .collect();
    // #436 — cross-field `validate(&self)`. If the
    // container declared `#[serializer(validate = "fn_name")]`,
    // the macro-generated `validate(&self)` runs every per-field
    // validator first, then calls the user's cross-field method,
    // merging its `FormErrors` into the per-field errors. Either
    // alone is enough to emit the wrapper.
    let cross_validate_call = container.cross_validate.as_ref().map(|method_ident| {
        quote! {
            // Merge cross-field errors into the per-field bucket so
            // a single .validate() call surfaces both layers.
            if let ::core::result::Result::Err(__cross) = self.#method_ident() {
                __errors.merge(__cross);
            }
        }
    });
    let has_validators = !validator_calls.is_empty() || container.cross_validate.is_some();
    // Anything to run? Declarative constraints (for any writable field) +
    // per-field validators + cross-field hook.
    let has_run_validations = has_validators || has_constraints;
    // Shared body: declarative field constraints first (length / range /
    // choices, serializer-attr-or-model), then per-field validators, then
    // the cross-field hook. Field rules run only where `__sent(name)` (#1995).
    let checks = quote! {
        let mut __errors = #root::forms::FormErrors::default();
        #( #constraint_blocks )*
        #( #validator_calls )*
        #cross_validate_call
        if __errors.is_empty() {
            ::core::result::Result::Ok(())
        } else {
            ::core::result::Result::Err(__errors)
        }
    };
    let validate_body = quote! {
        let __sent = |_: &str| true;
        #checks
    };
    // PATCH: only the keys the body carries.
    let validate_patch_body = quote! {
        let __sent = |__n: &str| __obj.is_some_and(|__o| __o.contains_key(__n));
        #checks
    };
    // Inherent `validate(&self)` — kept for back-compat with direct
    // `serializer.validate()` calls that don't import `ModelSerializer`.
    // Emitted only when the serializer declares per-field/cross-field
    // validators (unchanged rule) so it never collides with a
    // hand-written inherent `validate`.
    let validate_method = if has_validators {
        quote! {
            impl #struct_name {
                /// Run the declarative field constraints, every
                /// `#[serializer(validate = "...")]` per-field validator,
                /// and (when declared) the container-level cross-field
                /// validator. Aggregates errors into `FormErrors` keyed by
                /// the field name. Returns `Ok(())` when all pass.
                pub fn validate(&self) -> ::core::result::Result<(), #root::forms::FormErrors> {
                    #validate_body
                }
            }
        }
    } else {
        quote! {}
    };
    // Trait-method override so the type-erased ViewSet write path can
    // dispatch `ModelSerializer::validate` generically. Emitted whenever
    // there's anything to run (declarative constraints inherited from the
    // model count); otherwise the trait's default no-op is used.
    let trait_validate_override = if has_run_validations {
        quote! {
            fn validate(&self) -> ::core::result::Result<(), #root::forms::FormErrors> {
                #validate_body
            }
        }
    } else {
        quote! {}
    };

    // For every `#[serializer(many = S)]` field, emit a
    // `pub fn set_<field>(&mut self, models: &[<S::Model>]) -> &mut Self`
    // helper that maps the parents through `S::from_model`.
    let many_setters: Vec<_> = fields_info
        .iter()
        .filter_map(|fi| {
            let many_ty = fi.attrs.many.as_ref()?;
            let ident = &fi.ident;
            let setter = syn::Ident::new(&format!("set_{}", ident_name(ident)), ident.span());
            Some(quote! {
                /// Populate this `many` field by mapping each parent model
                /// through the inner serializer's `from_model`. Call after
                /// fetching the M2M / one-to-many children since
                /// `from_model` itself can't await an SQL query.
                pub fn #setter(
                    &mut self,
                    models: &[<#many_ty as #root::serializer::ModelSerializer>::Model],
                ) -> &mut Self {
                    self.#ident = models.iter()
                        .map(<#many_ty as #root::serializer::ModelSerializer>::from_model)
                        .collect();
                    self
                }
            })
        })
        .collect();
    let many_setters_impl = if many_setters.is_empty() {
        quote! {}
    } else {
        quote! {
            impl #struct_name {
                #( #many_setters )*
            }
        }
    };

    // Generate custom Serialize: skip write_only fields
    let output_fields: Vec<_> = fields_info
        .iter()
        .filter(|fi| !fi.attrs.write_only)
        .collect();
    let output_field_count = output_fields.len();
    let serialize_fields = output_fields.iter().map(|fi| {
        let ident = &fi.ident;
        let name_lit = ident_name(ident);
        quote! { __state.serialize_field(#name_lit, &self.#ident)?; }
    });

    // writable_fields: normal + write_only.
    // Exclude:
    //   - `read_only` — server-computed.
    //   - `skip` — caller sets manually post-from_model.
    //   - `method` — computed from a Self::fn(&model) call; accepting
    //     it on write is meaningless.
    //   - `nested` / `many` — populated from related-model data, not
    //     from a field on the wire body.
    // v0.44 fix: pre-v0.44 the macro included `method` / `nested` /
    // `many` in `writable_fields()`, which made the ViewSet write
    // path accept those fields from the JSON body and try to bind
    // them to the SQL UPDATE — a silent no-op at best, a type
    // mismatch at worst.
    // (`is_writable` is defined above, near the constraint codegen.)
    let writable_lits: Vec<_> = fields_info
        .iter()
        .filter(is_writable)
        .map(|fi| ident_name(&fi.ident))
        .collect();

    // `writable_source_fields`: the MODEL field names of writable
    // serializer fields (source-resolved). The ViewSet write path skips
    // every model column NOT in this set, so `read_only` / `method` /
    // computed fields a client posts are ignored instead of written.
    let writable_source_lits: Vec<String> = fields_info
        .iter()
        .filter(is_writable)
        .map(|fi| {
            fi.attrs
                .source
                .clone()
                .unwrap_or_else(|| ident_name(&fi.ident))
        })
        .collect();

    // `readable_source_fields`: model columns the JSON output copies
    // straight from the model, so `?ordering=` cannot sort on a column
    // the API never shows (#1845).
    let readable_source_lits: Vec<String> = fields_info
        .iter()
        .filter(|fi| {
            !fi.attrs.write_only
                && !fi.attrs.skip
                && fi.attrs.method.is_none()
                && !fi.attrs.nested
                && fi.attrs.many.is_none()
                && fi.attrs.slug.is_none()
        })
        .map(|fi| {
            fi.attrs
                .source
                .clone()
                .unwrap_or_else(|| ident_name(&fi.ident))
        })
        .collect();

    // `from_writable_json`: build a partial instance for input
    // validation. Writable fields are parsed from the JSON body (keyed
    // by serializer field name); every other field defaults. Per-field
    // type errors collect into `FormErrors` keyed by the field name.
    // Construction is field-by-field (not `Self::default()`) so it works
    // for serializers regardless of a struct-level `Default`.
    let from_writable_json_inits: Vec<_> = fields_info
        .iter()
        .map(|fi| {
            let ident = &fi.ident;
            let fname = ident_name(ident);
            let ty = &fi.ty;
            if is_writable(&fi) {
                quote! {
                    #ident: match __obj.and_then(|__o| __o.get(#fname)) {
                        ::core::option::Option::Some(__v) => {
                            match #root::__serde_json::from_value::<#ty>(
                                ::core::clone::Clone::clone(__v),
                            ) {
                                ::core::result::Result::Ok(__x) => __x,
                                ::core::result::Result::Err(__e) => {
                                    __errors.add(#fname.to_owned(), __e.to_string());
                                    ::core::default::Default::default()
                                }
                            }
                        }
                        ::core::option::Option::None => ::core::default::Default::default(),
                    }
                }
            } else {
                quote! { #ident: ::core::default::Default::default() }
            }
        })
        .collect();
    // `validate_patch`: overlay each sent writable field on the stored row.
    let patch_overlays: Vec<_> = fields_info
        .iter()
        .filter(is_writable)
        .map(|fi| {
            let ident = &fi.ident;
            let fname = ident_name(ident);
            let ty = &fi.ty;
            quote! {
                if let ::core::option::Option::Some(__v) = __obj.and_then(|__o| __o.get(#fname)) {
                    match #root::__serde_json::from_value::<#ty>(::core::clone::Clone::clone(__v)) {
                        ::core::result::Result::Ok(__x) => __merged.#ident = __x,
                        ::core::result::Result::Err(__e) => {
                            __errors.add(#fname.to_owned(), __e.to_string());
                        }
                    }
                }
            }
        })
        .collect();
    let patch_validate_call = if has_run_validations {
        quote! { __merged.__rustango_validate_patch(__obj) }
    } else {
        quote! { let _ = &__merged; ::core::result::Result::Ok(()) }
    };
    let patch_validate_helper = if has_run_validations {
        quote! {
            impl #struct_name {
                #[doc(hidden)]
                fn __rustango_validate_patch(
                    &self,
                    __obj: ::core::option::Option<&#root::__serde_json::Map<::std::string::String, #root::__serde_json::Value>>,
                ) -> ::core::result::Result<(), #root::forms::FormErrors> {
                    #validate_patch_body
                }
            }
        }
    } else {
        quote! {}
    };

    // OpenAPI: emit `impl OpenApiSchema` when our `openapi` feature is on.
    // Only includes fields shown in JSON output (skips write_only). For each
    // `Option<T>` field, omit from `required` and add `.nullable()`.
    let openapi_impl = {
        #[cfg(feature = "openapi")]
        {
            let property_calls = output_fields.iter().map(|fi| {
                let ident = &fi.ident;
                let name_lit = ident_name(ident);
                let ty = &fi.ty;
                let nullable_call = if is_option(ty) {
                    quote! { .nullable() }
                } else {
                    quote! {}
                };
                quote! {
                    .property(
                        #name_lit,
                        <#ty as #root::openapi::OpenApiSchema>::openapi_schema()
                            #nullable_call,
                    )
                }
            });
            let required_lits: Vec<_> = output_fields
                .iter()
                .filter(|fi| !is_option(&fi.ty))
                .map(|fi| ident_name(&fi.ident))
                .collect();
            quote! {
                impl #root::openapi::OpenApiSchema for #struct_name {
                    fn openapi_schema() -> #root::openapi::Schema {
                        #root::openapi::Schema::object()
                            #( #property_calls )*
                            .required([ #( #required_lits ),* ])
                    }
                }
            }
        }
        #[cfg(not(feature = "openapi"))]
        {
            quote! {}
        }
    };

    Ok(quote! {
        impl #root::serializer::ModelSerializer for #struct_name {
            type Model = #model_path;

            fn from_model(model: &Self::Model) -> Self {
                Self {
                    #( #from_model_fields ),*
                }
            }

            fn writable_fields() -> &'static [&'static str] {
                &[ #( #writable_lits ),* ]
            }

            fn writable_source_fields() -> &'static [&'static str] {
                &[ #( #writable_source_lits ),* ]
            }

            fn readable_source_fields() -> &'static [&'static str] {
                &[ #( #readable_source_lits ),* ]
            }

            fn from_writable_json(
                __body: &#root::__serde_json::Value,
            ) -> ::core::result::Result<Self, #root::forms::FormErrors> {
                let mut __errors = #root::forms::FormErrors::default();
                let __obj = __body.as_object();
                let __out = Self {
                    #( #from_writable_json_inits ),*
                };
                if __errors.is_empty() {
                    ::core::result::Result::Ok(__out)
                } else {
                    ::core::result::Result::Err(__errors)
                }
            }

            fn validate_patch(
                __stored: &Self::Model,
                __body: &#root::__serde_json::Value,
            ) -> ::core::result::Result<(), #root::forms::FormErrors> {
                let mut __errors = #root::forms::FormErrors::default();
                let __obj = __body.as_object();
                #[allow(unused_mut)]
                let mut __merged = <Self as #root::serializer::ModelSerializer>::from_model(__stored);
                #( #patch_overlays )*
                if !__errors.is_empty() {
                    return ::core::result::Result::Err(__errors);
                }
                #patch_validate_call
            }

            #trait_validate_override
        }

        #patch_validate_helper

        impl #root::__serde::Serialize for #struct_name {
            fn serialize<S>(&self, serializer: S)
                -> ::core::result::Result<S::Ok, S::Error>
            where
                S: #root::__serde::Serializer,
            {
                use #root::__serde::ser::SerializeStruct;
                let mut __state = serializer.serialize_struct(
                    #struct_name_lit,
                    #output_field_count,
                )?;
                #( #serialize_fields )*
                __state.end()
            }
        }

        #openapi_impl

        #validate_method

        #many_setters_impl
    })
}

/// Returns true if `ty` looks like `Option<T>` (any path ending in `Option`).
/// Only used by the `openapi`-gated emission of `OpenApiSchema`; muted
/// when the feature is off.
#[cfg_attr(not(feature = "openapi"), allow(dead_code))]
fn is_option(ty: &syn::Type) -> bool {
    if let syn::Type::Path(p) = ty {
        if let Some(last) = p.path.segments.last() {
            return last.ident == "Option";
        }
    }
    false
}

#[cfg(test)]
mod main_attr_tests {
    use super::*;

    fn expand(args: &str) -> String {
        let body = quote! { async fn main() { run().await } };
        expand_main(args.parse().unwrap(), body)
            .expect("expansion failed")
            .to_string()
    }

    /// Asserts on the expansion rather than on `parse_logging`,
    /// because the defect was a subscriber reaching the output, not
    /// an argument being misread (#1465).
    #[test]
    fn logging_false_emits_no_subscriber() {
        let out = expand("logging = false");
        assert!(
            !out.contains("logging :: Setup"),
            "`logging = false` must not install a subscriber:\n{out}",
        );
        assert!(
            out.contains("block_on"),
            "the runtime must still be built:\n{out}",
        );
    }

    #[test]
    fn default_still_installs_a_subscriber() {
        // The control. Without it, an `expand_main` that dropped the
        // prologue unconditionally would pass the test above while
        // leaving every default project with no logging at all.
        let out = expand("");
        assert!(
            out.contains("logging :: Setup"),
            "the default entrypoint must still install one:\n{out}",
        );
    }

    #[test]
    fn logging_false_composes_with_flavor() {
        let out = expand("flavor = \"current_thread\", logging = false");
        assert!(!out.contains("logging :: Setup"), "{out}");
        assert!(out.contains("new_current_thread"), "{out}");
    }

    #[test]
    fn logging_true_is_the_default_shape() {
        // `logging = true` is accepted and means the default, so the
        // match must not fire on the substring `logging`.
        assert!(parse_logging(&"logging = true".parse().unwrap()));
        assert!(!parse_logging(&"logging=false".parse().unwrap()));
    }
}

#[cfg(test)]
mod embed_migrations_tests {
    use super::*;

    fn expand(path: &str) -> String {
        expand_embed_migrations(quote! { #path })
            .expect("expansion failed")
            .to_string()
    }

    #[test]
    fn missing_dir_warns() {
        let out = expand("./no_such_migrations_dir");
        assert!(out.contains("deprecated"), "missing dir must warn:\n{out}");
        assert!(out.contains("no_such_migrations_dir"), "{out}");
    }

    #[test]
    fn existing_dir_does_not_warn() {
        let out = expand("./src");
        assert!(!out.contains("deprecated"), "{out}");
    }
}

#[cfg(test)]
mod field_attr_tests {
    use super::*;

    fn error_for(field: syn::Field) -> Option<String> {
        let attrs = parse_field_attrs(&field).unwrap();
        let kind = detect_type(&field.ty).unwrap().kind;
        check_bound_compatibility(&field, &attrs, kind)
            .err()
            .map(|e| e.to_string())
    }

    /// `citext`, `vector` and `geometry` on the wrong type are errors, not no-ops (#1937).
    #[test]
    fn type_specific_attrs_reject_other_types() {
        let f: syn::FieldsNamed = syn::parse_quote!({
            #[rustango(citext)] a: i64,
            #[rustango(vector(dims = 3))] b: String,
            #[rustango(geometry(srid = 4326))] c: String,
            #[rustango(citext)] d: String,
        });
        let errs: Vec<_> = f.named.into_iter().map(error_for).collect();
        assert!(errs[0].as_deref().unwrap().contains("citext"), "{errs:?}");
        assert!(errs[1].as_deref().unwrap().contains("vector"), "{errs:?}");
        assert!(errs[2].as_deref().unwrap().contains("geometry"), "{errs:?}");
        assert_eq!(errs[3], None);
    }

    /// `manager(ext)` emitted a trait nobody could add methods to; it is refused (#2132).
    #[test]
    fn manager_ext_is_refused() {
        let input: DeriveInput = syn::parse_quote! {
            #[rustango(table = "p", manager(ext = "PostManagerExt"))]
            struct Post { id: i64 }
        };
        let err = parse_container_attrs(&input).err().expect("refused");
        assert!(err.to_string().contains("#2132"), "{err}");
    }

    /// `set_null` on a NOT NULL `ForeignKey<T>` would fail every parent delete.
    #[test]
    fn set_null_needs_an_optional_foreign_key() {
        let input: DeriveInput = syn::parse_quote! {
            #[rustango(table = "c")]
            struct Child {
                #[rustango(primary_key)] id: i64,
                #[rustango(on_delete = "set_null")] parent: ForeignKey<Parent>,
            }
        };
        let err = expand(&input).err().expect("refused");
        assert!(err.to_string().contains("set_null"), "{err}");
        let input: DeriveInput = syn::parse_quote! {
            #[rustango(table = "c")]
            struct Child {
                #[rustango(primary_key)] id: i64,
                #[rustango(on_delete = "set_null")] parent: Option<ForeignKey<Parent>>,
            }
        };
        assert!(expand(&input).is_ok());
    }

    /// The same for `fk = "…"` / `o2o = "…"` on a plain column.
    #[test]
    fn set_null_needs_a_nullable_fk_column() {
        let input: DeriveInput = syn::parse_quote! {
            #[rustango(table = "c")]
            struct Child {
                #[rustango(primary_key)] id: i64,
                #[rustango(fk = "p", on_delete = "set_null")] parent_id: i64,
                #[rustango(o2o = "q", on_delete = "set_null")] other_id: Option<i64>,
            }
        };
        let err = expand(&input).err().expect("refused");
        assert!(err.to_string().contains("set_null"), "{err}");
        let input: DeriveInput = syn::parse_quote! {
            #[rustango(table = "c")]
            struct Child {
                #[rustango(primary_key)] id: i64,
                #[rustango(fk = "p", on_delete = "set_null")] parent_id: std::option::Option<i64>,
                #[rustango(o2o = "q", on_delete = "set_null")] other_id: ::core::option::Option<i64>,
                #[rustango(on_delete = "set_null")] parent: core::option::Option<ForeignKey<Parent>>,
            }
        };
        assert!(expand(&input).is_ok());
    }

    /// Two FKs to one parent would emit the same reverse accessor twice.
    #[test]
    fn reverse_accessor_clash_names_related_name() {
        let input: DeriveInput = syn::parse_quote! {
            #[rustango(table = "m")]
            struct Message {
                #[rustango(primary_key)] id: i64,
                sender: ForeignKey<User>,
                recipient: ForeignKey<User>,
            }
        };
        let err = expand(&input).err().expect("refused");
        assert!(err.to_string().contains("related_name"), "{err}");
    }

    /// `related_name = "+"` emits no reverse accessor, so a parent from
    /// another crate, which cannot take an inherent impl, still derives.
    #[test]
    fn related_name_plus_skips_the_reverse_accessor() {
        let input: DeriveInput = syn::parse_quote! {
            #[rustango(table = "m")]
            struct Message {
                #[rustango(primary_key)] id: i64,
                sender: ForeignKey<User>,
                #[rustango(related_name = "+")] recipient: ForeignKey<User>,
                #[rustango(related_name = "+")] owner: ForeignKey<other::Account>,
            }
        };
        let out = expand(&input).expect("derives").to_string();
        assert_eq!(out.matches("message_set_pool").count(), 1, "{out}");
        assert!(!out.contains("impl other :: Account {"), "{out}");
    }

    /// A raw ident derives names without `r#`; this used to panic (#1937).
    #[test]
    fn raw_idents_derive_plain_names() {
        let ident: syn::Ident = syn::parse_quote!(r#type);
        assert_eq!(column_type_ident(&ident).to_string(), "type_col");
        assert_eq!(ident_from_name("type", ident.span()).to_string(), "r#type");
    }
}