fp_io/

lib.rs

#![forbid(unsafe_code)]
#![warn(rustdoc::broken_intra_doc_links)]

//! IO layer for **frankenpandas**: round-trips between `DataFrame` and the
//! fifteen supported on-disk / wire formats — CSV, JSON, JSONL, Parquet, ORC,
//! HDF5, Excel (XLSX), Feather (Arrow IPC v2), SQL, Markdown, LaTeX, HTML,
//! XML, Pickle, and Stata.
//!
//! ## Format readers / writers
//!
//! - **CSV**: [`read_csv`], [`read_csv_with_options`], [`write_csv`],
//!   [`write_csv_string`]
//! - **JSON / JSONL**: [`read_json`], [`read_jsonl`], [`write_json`],
//!   [`write_jsonl`]
//! - **Parquet**: [`read_parquet`], [`write_parquet`]
//! - **ORC**: [`read_orc`], [`write_orc`]
//! - **HDF5**: [`read_hdf`], [`write_hdf`] for the keyed DataFrame snapshot
//!   surface.
//! - **Excel**: [`read_excel`], [`write_excel`]
//! - **Feather / Arrow IPC**: [`read_feather`], [`write_feather`],
//!   [`read_ipc_stream_bytes`], [`write_ipc_stream_bytes`]
//! - **SQL**: [`read_sql`], [`read_sql_table`], [`write_sql`],
//!   [`write_sql_with_options`], plus the chunked variants
//!   ([`read_sql_chunks`], [`SqlChunkIterator`]).
//! - **Markdown / LaTeX / HTML / XML**: [`write_markdown_string`],
//!   [`write_latex_string`], [`write_html_string`], [`read_html_str`],
//!   [`write_xml_string`], [`read_xml_str`].
//! - **Pickle**: [`write_pickle_bytes`], [`read_pickle_bytes`] for the
//!   fail-closed FrankenPandas DataFrame snapshot envelope.
//! - **Stata**: [`write_stata_bytes`], [`read_stata_bytes`] for the bounded
//!   DTA V118 DataFrame round-trip surface.
//!
//! Each format has a per-call options struct ([`CsvReadOptions`],
//! [`ExcelReadOptions`], [`SqlReadOptions`], [`SqlWriteOptions`], ...) so
//! pandas-shaped keyword arguments thread cleanly through the Rust API.
//! The [`DataFrameIoExt`] extension trait adds `df.to_csv(path)` /
//! `df.to_parquet(path)` / etc. methods on `DataFrame` for ergonomic
//! method-chain use.
//!
//! ## SQL backend abstraction
//!
//! SQL IO is built around the [`SqlConnection`] trait — a backend-neutral
//! contract that mirrors the supported subset of pandas /
//! `SQLAlchemy.Inspector`. Concrete backends (today: rusqlite via the
//! `sql-sqlite` feature) implement the trait and inherit:
//!
//! - **Mutation primitives**: [`SqlConnection::query`],
//!   [`SqlConnection::execute_batch`], [`SqlConnection::insert_rows`],
//!   [`SqlConnection::truncate_table`], [`SqlConnection::with_transaction`].
//! - **Capability probes**: [`SqlConnection::dialect_name`],
//!   [`SqlConnection::server_version`], [`SqlConnection::max_param_count`],
//!   [`SqlConnection::max_identifier_length`],
//!   [`SqlConnection::supports_returning`],
//!   [`SqlConnection::supports_schemas`].
//! - **Identifier / parameter shape hooks**:
//!   [`SqlConnection::quote_identifier`],
//!   [`SqlConnection::parameter_marker`].
//! - **Introspection** (matching `SQLAlchemy.Inspector` shape):
//!   [`SqlConnection::list_tables`], [`SqlConnection::list_views`],
//!   [`SqlConnection::list_schemas`], [`SqlConnection::table_schema`],
//!   [`SqlConnection::list_indexes`], [`SqlConnection::list_foreign_keys`],
//!   [`SqlConnection::list_unique_constraints`],
//!   [`SqlConnection::primary_key_columns`],
//!   [`SqlConnection::table_comment`].
//!
//! The [`SqlInspector`] facade wraps a `&C: SqlConnection` and exposes the
//! whole introspection API as methods on a single bundle:
//!
//! ```ignore
//! let inspector = SqlInspector::new(&conn);
//! let bundle = inspector
//!     .reflect_table("users", None)?
//!     .expect("table exists");
//! for col in &bundle.columns {
//!     println!("{}: {:?}", col.name, col.declared_type);
//! }
//! ```
//!
//! [`SqlReflectedTable`] is the bundled metadata returned by
//! [`SqlInspector::reflect_table`] / [`SqlInspector::reflect_all_tables`] /
//! [`SqlInspector::reflect_all_views`] — columns, primary key, indexes,
//! foreign keys, unique constraints, and table-level comment, with
//! per-column lookup helpers.
//!
//! ## Cargo features
//!
//! - `sql-sqlite` (**default**): bind [`SqlConnection`] for
//!   `rusqlite::Connection`.
//! - `sql-postgresql`, `sql-mysql`: placeholder feature flags for the fd90
//!   Phase 2 backend integrations (no concrete bindings yet).
//!
//! Use `default-features = false` to drop the rusqlite dep when only the
//! non-SQL formats are needed.

use std::{
    borrow::Cow,
    collections::{BTreeMap, BTreeSet, HashSet, VecDeque},
    io::Cursor,
    path::Path,
    sync::{Arc, Mutex, OnceLock},
};

use arrow::{
    array::{
        Array, BooleanArray, BooleanBuilder, Date32Array, Date64Array, Float64Array,
        Float64Builder, Int64Array, Int64Builder, RecordBatch, StringArray, StringBuilder,
        TimestampMicrosecondArray, TimestampMillisecondArray, TimestampNanosecondArray,
        TimestampSecondArray,
    },
    datatypes::{DataType as ArrowDataType, Field, Schema, TimeUnit},
};
use csv::{ReaderBuilder, StringRecord, WriterBuilder};
use dta::stata::{
    dta::{
        byte_order::ByteOrder, dta_reader::DtaReader, dta_writer::DtaWriter, header::Header,
        release::Release, schema::Schema as StataSchema, value::Value as StataValue,
        variable::Variable, variable_type::VariableType,
    },
    missing_value::MissingValue,
    stata_double::StataDouble,
    stata_long::StataLong,
};
use fp_columnar::{Column, ColumnError};
use fp_frame::{DataFrame, FrameError, Series, ToDatetimeOptions, to_datetime_with_options};
use fp_index::{Index, IndexError, IndexLabel, format_datetime_ns};
use fp_types::{DType, NullKind, Scalar, Timedelta, Timestamp, cast_scalar_owned};
#[cfg(feature = "hdf5")]
use hdf5::File as Hdf5File;
use orc_rust::{
    ArrowReaderBuilder as OrcArrowReaderBuilder, ArrowWriterBuilder as OrcArrowWriterBuilder,
};
use parquet::arrow::{ArrowWriter, arrow_reader::ParquetRecordBatchReaderBuilder};
use quick_xml::{Reader as XmlReader, XmlVersion, events::Event};
use scraper::{ElementRef, Html, Selector};
use thiserror::Error;

#[derive(Debug, Error)]
#[non_exhaustive]
pub enum IoError {
    #[error("csv input has no headers")]
    MissingHeaders,
    #[error("csv index column '{0}' not found in headers")]
    MissingIndexColumn(String),
    #[error("duplicate column name '{0}'")]
    DuplicateColumnName(String),
    #[error("usecols contains missing columns: {0:?}")]
    MissingUsecols(Vec<String>),
    #[error("parse_dates contains missing columns: {0:?}")]
    MissingParseDateColumns(Vec<String>),
    #[error("json format error: {0}")]
    JsonFormat(String),
    #[error("parquet error: {0}")]
    Parquet(String),
    #[error("orc error: {0}")]
    Orc(String),
    #[error("hdf5 error: {0}")]
    Hdf5(String),
    #[error("excel error: {0}")]
    Excel(String),
    #[error("html error: {0}")]
    Html(String),
    #[error("xml error: {0}")]
    Xml(String),
    #[error("pickle error: {0}")]
    Pickle(String),
    #[error("stata error: {0}")]
    Stata(String),
    #[error("fwf error: {0}")]
    Fwf(String),
    #[error("deferred reader: {0}")]
    Deferred(String),
    #[error("arrow ipc error: {0}")]
    Arrow(String),
    #[error("sql error: {0}")]
    Sql(String),
    #[error(transparent)]
    Csv(#[from] csv::Error),
    #[error(transparent)]
    Json(#[from] serde_json::Error),
    #[error(transparent)]
    Io(#[from] std::io::Error),
    #[error(transparent)]
    Utf8(#[from] std::string::FromUtf8Error),
    #[error(transparent)]
    Column(#[from] ColumnError),
    #[error(transparent)]
    Frame(#[from] FrameError),
    #[error(transparent)]
    Index(#[from] IndexError),
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum JsonOrient {
    Records,
    Columns,
    Index,
    Split,
    Values,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CsvOnBadLines {
    Error,
    Warn,
    Skip,
}

#[derive(Debug, Clone)]
pub struct CsvReadOptions {
    pub delimiter: u8,
    pub has_headers: bool,
    /// Additional NA values to recognize beyond the pandas defaults.
    pub na_values: Vec<String>,
    /// Whether to include the default NaN values when parsing data.
    /// If `na_values` are specified and `keep_default_na` is false, only the
    /// specified `na_values` will be treated as NA.
    /// Matches pandas `keep_default_na` parameter. Default: true.
    pub keep_default_na: bool,
    /// Detect missing value markers (empty strings and the value of na_values).
    /// In data without any NAs, passing `na_filter=false` can improve performance.
    /// Matches pandas `na_filter` parameter. Default: true.
    pub na_filter: bool,
    pub index_col: Option<String>,
    /// Read only these columns (by name). `None` means read all.
    /// Matches pandas `usecols` parameter.
    pub usecols: Option<Vec<String>>,
    /// Maximum number of data rows to read. `None` means read all.
    /// Matches pandas `nrows` parameter.
    pub nrows: Option<usize>,
    /// Number of initial lines to skip at the start of the file (including
    /// the header line when `has_headers` is true).
    /// Matches pandas `skiprows` parameter (when given as int).
    pub skiprows: usize,
    /// Force specific dtypes for columns. Map of column name -> DType.
    /// Matches pandas `dtype` parameter.
    pub dtype: Option<std::collections::HashMap<String, DType>>,
    /// Column names to coerce via pandas-style parse_dates handling.
    /// Currently supports explicit column-name selection.
    pub parse_dates: Option<Vec<String>>,
    /// Column groups to combine and coerce via pandas-style parse_dates handling.
    /// Each group replaces its source columns with a new `<a>_<b>_...` datetime column.
    pub parse_date_combinations: Option<Vec<Vec<String>>>,
    /// Named column groups to combine and parse as datetime, matching
    /// `pd.read_csv(parse_dates={'new_name': ['year', 'month', 'day']})`.
    /// Each `(new_name, [source_cols])` entry replaces its source columns
    /// with a single combined datetime column using the caller-supplied
    /// name instead of the default `<a>_<b>_...` joined form.
    pub parse_date_combinations_named: Option<Vec<(String, Vec<String>)>>,
    /// Character whose lines are treated as comments and skipped entirely.
    /// Must be a single byte (ASCII); multi-byte characters are rejected.
    /// Matches pandas `comment` parameter. Default: `None`.
    pub comment: Option<u8>,
    /// Additional string values to coerce to `true` during CSV parsing.
    /// Matches pandas `true_values` parameter.
    pub true_values: Vec<String>,
    /// Additional string values to coerce to `false` during CSV parsing.
    /// Matches pandas `false_values` parameter.
    pub false_values: Vec<String>,
    /// Character to recognize as the decimal separator when parsing floats.
    /// Matches pandas `decimal` parameter. Default: `.`.
    pub decimal: u8,
    /// How to handle rows with more fields than the header width.
    /// Matches pandas `on_bad_lines` parameter for the supported
    /// `error`/`warn`/`skip` modes.
    pub on_bad_lines: CsvOnBadLines,
    /// Thousands separator stripped from numeric fields before parsing.
    /// Matches pandas `thousands` parameter. Must differ from `decimal`
    /// (otherwise the option is silently ignored, matching pandas).
    pub thousands: Option<u8>,
    /// Number of trailing data rows to drop (after the header is
    /// consumed). Matches pandas `skipfooter` parameter. Default: `0`.
    pub skipfooter: usize,
    /// Character used to quote fields that contain the delimiter, a
    /// newline, or the quote character itself. Defaults to `"` (ASCII
    /// double-quote). Matches pandas `quotechar` parameter.
    pub quotechar: u8,
    /// Character used to escape the quote character inside a quoted
    /// field when `doublequote` is false. `None` disables backslash-
    /// style escaping entirely. Matches pandas `escapechar` parameter.
    pub escapechar: Option<u8>,
    /// When true (the default), a doubled quote character inside a
    /// quoted field is interpreted as a single literal quote. When
    /// false, `escapechar` must be used to quote the quote character.
    /// Matches pandas `doublequote` parameter.
    pub doublequote: bool,
    /// Custom single-byte line terminator. When set, the reader treats
    /// only that byte as a record separator (instead of CRLF/LF).
    /// Matches pandas `lineterminator` (C-engine only). `None` keeps
    /// the default CRLF/LF handling.
    pub lineterminator: Option<u8>,
}

impl Default for CsvReadOptions {
    fn default() -> Self {
        Self {
            delimiter: b',',
            has_headers: true,
            na_values: Vec::new(),
            keep_default_na: true,
            na_filter: true,
            index_col: None,
            usecols: None,
            nrows: None,
            skiprows: 0,
            dtype: None,
            parse_dates: None,
            parse_date_combinations: None,
            parse_date_combinations_named: None,
            comment: None,
            true_values: Vec::new(),
            false_values: Vec::new(),
            decimal: b'.',
            on_bad_lines: CsvOnBadLines::Error,
            thousands: None,
            quotechar: b'"',
            escapechar: None,
            doublequote: true,
            skipfooter: 0,
            lineterminator: None,
        }
    }
}

fn csv_read_options_match_default_shape(options: &CsvReadOptions, na_filter: bool) -> bool {
    options.delimiter == b','
        && options.has_headers
        && options.na_values.is_empty()
        && options.keep_default_na
        && options.na_filter == na_filter
        && options.index_col.is_none()
        && options.usecols.is_none()
        && options.nrows.is_none()
        && options.skiprows == 0
        && options.dtype.is_none()
        && options.parse_dates.is_none()
        && options.parse_date_combinations.is_none()
        && options.parse_date_combinations_named.is_none()
        && options.comment.is_none()
        && options.true_values.is_empty()
        && options.false_values.is_empty()
        && options.decimal == b'.'
        && options.on_bad_lines == CsvOnBadLines::Error
        && options.thousands.is_none()
        && options.skipfooter == 0
        && options.quotechar == b'"'
        && options.escapechar.is_none()
        && options.doublequote
        && options.lineterminator.is_none()
}

fn csv_read_options_match_default_fast_path(options: &CsvReadOptions) -> bool {
    csv_read_options_match_default_shape(options, true)
}

fn csv_read_options_match_no_na_numeric_fast_path(options: &CsvReadOptions) -> bool {
    csv_read_options_match_default_shape(options, false)
}

/// Options for [`read_fwf_str`] and [`read_fwf`].
///
/// Callers can supply either `colspecs` (explicit `(start, end)`
/// character ranges, end-exclusive, matching pandas) or `widths`
/// (per-column character widths that get translated to cumulative
/// colspecs). When both are omitted, `read_fwf` infers colspecs from
/// non-whitespace runs across the non-skipped input lines.
#[derive(Debug, Clone)]
pub struct FwfReadOptions {
    /// Explicit `(start, end)` column ranges in characters. End is
    /// exclusive, matching pandas. Mutually exclusive with `widths`.
    pub colspecs: Option<Vec<(usize, usize)>>,
    /// Per-column character widths. Translated to colspecs by cumulative
    /// sum. Mutually exclusive with `colspecs`.
    pub widths: Option<Vec<usize>>,
    pub has_headers: bool,
    pub na_values: Vec<String>,
    pub keep_default_na: bool,
    pub na_filter: bool,
    pub index_col: Option<String>,
    pub usecols: Option<Vec<String>>,
    pub nrows: Option<usize>,
    pub skiprows: usize,
    pub dtype: Option<std::collections::HashMap<String, DType>>,
    pub parse_dates: Option<Vec<String>>,
    pub true_values: Vec<String>,
    pub false_values: Vec<String>,
    pub decimal: u8,
    pub thousands: Option<u8>,
    pub skipfooter: usize,
}

impl Default for FwfReadOptions {
    fn default() -> Self {
        Self {
            colspecs: None,
            widths: None,
            has_headers: true,
            na_values: Vec::new(),
            keep_default_na: true,
            na_filter: true,
            index_col: None,
            usecols: None,
            nrows: None,
            skiprows: 0,
            dtype: None,
            parse_dates: None,
            true_values: Vec::new(),
            false_values: Vec::new(),
            decimal: b'.',
            thousands: None,
            skipfooter: 0,
        }
    }
}

fn infer_fwf_colspecs(
    input: &str,
    options: &FwfReadOptions,
) -> Result<Vec<(usize, usize)>, IoError> {
    let mut candidate_lines: Vec<&str> = input.lines().skip(options.skiprows).collect();
    if options.skipfooter > 0 {
        let retained = candidate_lines.len().saturating_sub(options.skipfooter);
        candidate_lines.truncate(retained);
    }

    let candidate_lines: Vec<&str> = candidate_lines
        .into_iter()
        .filter(|line| !line.trim().is_empty())
        .collect();
    if candidate_lines.is_empty() {
        return Err(IoError::Fwf(
            "cannot infer fixed-width colspecs from empty input".to_owned(),
        ));
    }

    let max_width = candidate_lines
        .iter()
        .map(|line| line.chars().count())
        .max()
        .unwrap_or(0);
    let mut occupied = vec![false; max_width];
    for line in candidate_lines {
        for (idx, ch) in line.chars().enumerate() {
            if !ch.is_whitespace()
                && let Some(slot) = occupied.get_mut(idx)
            {
                *slot = true;
            }
        }
    }

    let mut specs = Vec::new();
    let mut idx = 0usize;
    while idx < occupied.len() {
        while idx < occupied.len() && !occupied.get(idx).copied().unwrap_or(false) {
            idx += 1;
        }
        if idx == occupied.len() {
            break;
        }
        let start = idx;
        while idx < occupied.len() && occupied.get(idx).copied().unwrap_or(false) {
            idx += 1;
        }
        specs.push((start, idx));
    }

    if specs.is_empty() {
        return Err(IoError::Fwf(
            "cannot infer fixed-width colspecs from whitespace-only input".to_owned(),
        ));
    }
    Ok(specs)
}

fn resolve_fwf_colspecs(
    input: &str,
    options: &FwfReadOptions,
) -> Result<Vec<(usize, usize)>, IoError> {
    match (&options.colspecs, &options.widths) {
        (Some(_), Some(_)) => Err(IoError::Fwf(
            "You must specify only one of 'widths' and 'colspecs'".to_owned(),
        )),
        (Some(specs), None) => {
            for &(start, end) in specs {
                if start > end {
                    return Err(IoError::Fwf(format!(
                        "colspecs entry ({start}, {end}) is inverted"
                    )));
                }
            }
            Ok(specs.clone())
        }
        (None, Some(widths)) => {
            let mut specs = Vec::with_capacity(widths.len());
            let mut cursor = 0usize;
            for &w in widths {
                let next = cursor.checked_add(w).ok_or_else(|| {
                    IoError::Fwf("widths overflow when computing colspecs".to_owned())
                })?;
                specs.push((cursor, next));
                cursor = next;
            }
            Ok(specs)
        }
        (None, None) => infer_fwf_colspecs(input, options),
    }
}

fn fwf_lines_to_csv(input: &str, colspecs: &[(usize, usize)]) -> String {
    let mut out = String::new();
    for line in input.split_terminator('\n') {
        let line = line.strip_suffix('\r').unwrap_or(line);
        let chars: Vec<char> = line.chars().collect();
        let mut first = true;
        for &(start, end) in colspecs {
            if !first {
                out.push(',');
            }
            first = false;
            let slice: String = if start >= chars.len() {
                String::new()
            } else {
                let real_end = end.min(chars.len());
                chars[start..real_end].iter().collect()
            };
            let trimmed = slice.trim();
            out.push('"');
            for c in trimmed.chars() {
                if c == '"' {
                    out.push('"');
                }
                out.push(c);
            }
            out.push('"');
        }
        out.push('\n');
    }
    out
}

fn fwf_csv_options(options: &FwfReadOptions) -> CsvReadOptions {
    CsvReadOptions {
        delimiter: b',',
        has_headers: options.has_headers,
        na_values: options.na_values.clone(),
        keep_default_na: options.keep_default_na,
        na_filter: options.na_filter,
        index_col: options.index_col.clone(),
        usecols: options.usecols.clone(),
        nrows: options.nrows,
        skiprows: options.skiprows,
        dtype: options.dtype.clone(),
        parse_dates: options.parse_dates.clone(),
        parse_date_combinations: None,
        parse_date_combinations_named: None,
        comment: None,
        true_values: options.true_values.clone(),
        false_values: options.false_values.clone(),
        decimal: options.decimal,
        on_bad_lines: CsvOnBadLines::Error,
        thousands: options.thousands,
        quotechar: b'"',
        escapechar: None,
        doublequote: true,
        skipfooter: options.skipfooter,
        lineterminator: None,
    }
}

/// Parse a fixed-width string, matching `pd.read_fwf(io.StringIO(s), ...)`.
///
/// Tokens are sliced by character index, then trimmed of leading and
/// trailing whitespace before being threaded through the standard CSV
/// scalar-coercion path. When `colspecs` and `widths` are omitted, the
/// ranges are inferred from non-whitespace runs across the input.
pub fn read_fwf_str(input: &str, options: &FwfReadOptions) -> Result<DataFrame, IoError> {
    let colspecs = resolve_fwf_colspecs(input, options)?;
    let csv_input = fwf_lines_to_csv(input, &colspecs);
    let csv_options = fwf_csv_options(options);
    read_csv_with_options(&csv_input, &csv_options)
}

/// Build a CSV column from per-cell parsed scalars, but preserve original text
/// when the column infers to object (`Utf8`) dtype.
///
/// pandas does column-level inference: a column becomes a single dtype, and when
/// it falls back to object every non-NA cell keeps its VERBATIM source text. FP
/// parses per cell (`"true"` → `Bool`, `"01"` → `Int64(1)`), so without this the
/// object-fallback column would re-stringify those scalars canonically — writing
/// `"True"`/`"1"` where pandas keeps `"true"`/`"01"`. When the inferred dtype is
/// `Utf8`, rebuild the column straight from `raw` (NA cells stay null) so the
/// original literals survive. Native (non-object) columns are unaffected.
///
/// Missingness is read back from the parsed column's own values rather than
/// re-detecting NA tokens, so this works for both the default reader and the
/// options reader (which honors a configurable na/keep_default_na token set):
/// a cell is null in the rebuilt column iff it parsed to a missing scalar.
/// `raw` must be positionally aligned with `values` (same length).
fn build_csv_object_aware_column(values: Vec<Scalar>, raw: &[String]) -> Result<Column, IoError> {
    let column = Column::from_values(values)?;
    if column.dtype() == DType::Utf8 && column.values().len() == raw.len() {
        let rebuilt: Vec<Scalar> = column
            .values()
            .iter()
            .zip(raw)
            .map(|(parsed, field)| {
                if parsed.is_missing() {
                    Scalar::Null(NullKind::Null)
                } else {
                    Scalar::Utf8(field.clone())
                }
            })
            .collect();
        return Ok(Column::new(DType::Utf8, rebuilt)?);
    }
    Ok(column)
}

enum CsvTypedColumnValues {
    Int64(Vec<i64>),
    Float64(Vec<f64>),
}

const SIMPLE_NUMERIC_CSV_PARALLEL_MIN_BYTES: usize = 1 << 20;
const SIMPLE_NUMERIC_CSV_PARALLEL_MAX_WORKERS: usize = 8;

fn trim_ascii_field(mut field: &[u8]) -> &[u8] {
    while let Some((first, rest)) = field.split_first() {
        if first.is_ascii_whitespace() {
            field = rest;
        } else {
            break;
        }
    }
    while let Some((last, rest)) = field.split_last() {
        if last.is_ascii_whitespace() {
            field = rest;
        } else {
            break;
        }
    }
    field
}

fn is_pandas_default_na_bytes(field: &[u8]) -> bool {
    const DEFAULT_NA_VALUES: &[&[u8]] = &[
        b"",
        b"#N/A",
        b"#N/A N/A",
        b"#NA",
        b"-1.#IND",
        b"-1.#QNAN",
        b"-NaN",
        b"-nan",
        b"1.#IND",
        b"1.#QNAN",
        b"<NA>",
        b"N/A",
        b"NA",
        b"NULL",
        b"NaN",
        b"None",
        b"n/a",
        b"nan",
        b"null",
    ];
    DEFAULT_NA_VALUES.contains(&field)
}

fn eq_ignore_ascii_case_bytes(field: &[u8], expected: &[u8]) -> bool {
    field.len() == expected.len()
        && field
            .iter()
            .zip(expected)
            .all(|(lhs, rhs)| lhs.eq_ignore_ascii_case(rhs))
}

fn has_float_marker(field: &[u8]) -> bool {
    field.iter().any(|byte| matches!(byte, b'.' | b'e' | b'E'))
}

fn parse_i64_ascii(field: &[u8]) -> Option<i64> {
    if field.is_ascii() {
        std::str::from_utf8(field).ok()?.parse::<i64>().ok()
    } else {
        None
    }
}

fn parse_f64_csv_number(field: &[u8]) -> Option<f64> {
    match fast_float2::parse::<f64, _>(field) {
        Ok(value) => Some(value),
        Err(_) if field.is_ascii() => std::str::from_utf8(field).ok()?.parse::<f64>().ok(),
        Err(_) => None,
    }
}

/// Exact powers of ten for the fused decimal fast path. Every entry up to
/// 10^18 is exactly representable in f64, so dividing an exact mantissa by an
/// entry is a single correctly-rounded operation.
const FUSED_DECIMAL_POW10: [f64; 19] = [
    1e0, 1e1, 1e2, 1e3, 1e4, 1e5, 1e6, 1e7, 1e8, 1e9, 1e10, 1e11, 1e12, 1e13, 1e14, 1e15, 1e16,
    1e17, 1e18,
];

/// One CSV field admitted by the fused scanner/parser.
struct FusedNumericField {
    /// `Some` when the field is a plain optionally-signed integer; mirrors the
    /// `parse_i64_ascii` route of `push_csv_default_numeric_field`.
    int_value: Option<i64>,
    /// The field value as `f64`, bit-identical to `parse_f64_csv_number` on
    /// the same bytes (including the sign of zero, e.g. `-0` -> -0.0).
    float_value: f64,
    /// Index of the terminating delimiter (`,` or `\n`) or `data.len()`.
    end: usize,
}

/// Scans one CSV field starting at `start`, fusing delimiter detection with
/// decimal digit accumulation in a single pass over the bytes.
///
/// Admits only `[+-]?digits[.digits]` tokens with at most 18 mantissa digits
/// (so the `u64` accumulator and the `i64` integer route can never overflow)
/// and, for fractional values, a mantissa of at most 2^53 (so it is exactly
/// representable in `f64`). Under those gates the computed value is provably
/// bit-identical to the fallback parser: the mantissa and the power of ten
/// are both exact in `f64`, so the single division (or `u64 -> f64`
/// round-to-nearest-even conversion for integers) yields the correctly
/// rounded value of the decimal token — the same contract `fast_float2` and
/// `str::parse::<f64>` guarantee. Anything else (NA tokens, booleans,
/// whitespace, exponents, overlong or malformed numbers, quotes, CR) returns
/// `None` and must take the existing per-field fallback route.
#[inline]
fn fuse_scan_numeric_csv_field(data: &[u8], start: usize) -> Option<FusedNumericField> {
    let mut pos = start;
    let mut negative = false;
    match data.get(pos) {
        Some(b'-') => {
            negative = true;
            pos += 1;
        }
        Some(b'+') => pos += 1,
        _ => {}
    }

    let mut mantissa: u64 = 0;
    let mut digits = 0usize;
    let mut frac_digits = 0usize;
    let mut seen_dot = false;
    loop {
        match data.get(pos) {
            Some(&byte @ b'0'..=b'9') => {
                if digits == 18 {
                    return None;
                }
                mantissa = mantissa * 10 + u64::from(byte - b'0');
                digits += 1;
                frac_digits += usize::from(seen_dot);
                pos += 1;
            }
            Some(b'.') if !seen_dot => {
                seen_dot = true;
                pos += 1;
            }
            Some(b',' | b'\n') | None => break,
            Some(_) => return None,
        }
    }

    if digits == 0 || (seen_dot && frac_digits == 0) {
        return None;
    }

    if seen_dot {
        if mantissa > (1u64 << 53) {
            return None;
        }
        let magnitude = mantissa as f64 / FUSED_DECIMAL_POW10[frac_digits];
        Some(FusedNumericField {
            int_value: None,
            float_value: if negative { -magnitude } else { magnitude },
            end: pos,
        })
    } else {
        // digits <= 18 => mantissa < 10^18 < i64::MAX, so the cast is exact.
        let int_magnitude = mantissa as i64;
        let float_magnitude = mantissa as f64;
        Some(FusedNumericField {
            int_value: Some(if negative {
                -int_magnitude
            } else {
                int_magnitude
            }),
            float_value: if negative {
                -float_magnitude
            } else {
                float_magnitude
            },
            end: pos,
        })
    }
}

/// Pushes a fused numeric field with the exact dtype/promotion semantics of
/// `push_csv_default_numeric_field`: integers keep an Int64 column while any
/// fractional value promotes it to Float64; Float64 columns always take the
/// `f64` form of the token (which is how the fallback parses them too).
#[inline]
fn push_fused_numeric_csv_field(values: &mut CsvTypedColumnValues, field: &FusedNumericField) {
    match values {
        CsvTypedColumnValues::Int64(out) => {
            if let Some(value) = field.int_value {
                out.push(value);
            } else {
                let mut promoted = Vec::with_capacity(out.capacity());
                promoted.extend(out.iter().copied().map(|value| value as f64));
                promoted.push(field.float_value);
                *values = CsvTypedColumnValues::Float64(promoted);
            }
        }
        CsvTypedColumnValues::Float64(out) => out.push(field.float_value),
    }
}

fn push_csv_default_numeric_field(values: &mut CsvTypedColumnValues, field: &[u8]) -> bool {
    if is_pandas_default_na_bytes(field) {
        return false;
    }

    let trimmed = trim_ascii_field(field);
    if trimmed.is_empty()
        || eq_ignore_ascii_case_bytes(field, b"true")
        || eq_ignore_ascii_case_bytes(field, b"false")
    {
        return false;
    }

    match values {
        CsvTypedColumnValues::Int64(out) => {
            if !has_float_marker(trimmed)
                && let Some(value) = parse_i64_ascii(trimmed)
            {
                out.push(value);
                true
            } else {
                match parse_f64_csv_number(trimmed) {
                    Some(value) if !value.is_nan() => {
                        let mut promoted = Vec::with_capacity(out.capacity());
                        promoted.extend(out.iter().copied().map(|value| value as f64));
                        promoted.push(value);
                        *values = CsvTypedColumnValues::Float64(promoted);
                        true
                    }
                    Some(_) | None => false,
                }
            }
        }
        CsvTypedColumnValues::Float64(out) => match parse_f64_csv_number(trimmed) {
            Some(value) if !value.is_nan() => {
                out.push(value);
                true
            }
            Some(_) | None => false,
        },
    }
}

fn csv_default_unit_range_index(row_count: i64) -> Index {
    let row_len = usize::try_from(row_count).expect("CSV row count must be non-negative");
    Index::new_known_unique_int64_unit_range(0, row_len)
}

fn build_typed_numeric_csv_frame(
    headers: &[String],
    typed_columns: Vec<CsvTypedColumnValues>,
    row_count: i64,
) -> Result<DataFrame, IoError> {
    let mut out_columns = BTreeMap::new();
    let mut column_order = Vec::with_capacity(headers.len());
    for (name, values) in headers.iter().cloned().zip(typed_columns) {
        let column = match values {
            CsvTypedColumnValues::Int64(values) => Column::from_i64_values(values),
            CsvTypedColumnValues::Float64(values) => Column::from_f64_values(values),
        };
        out_columns.insert(name.clone(), column);
        column_order.push(name);
    }

    let index = csv_default_unit_range_index(row_count);
    DataFrame::new_with_column_order(index, out_columns, column_order).map_err(IoError::from)
}

fn simple_numeric_csv_parallel_worker_count(data_len: usize) -> usize {
    if data_len < SIMPLE_NUMERIC_CSV_PARALLEL_MIN_BYTES {
        return 1;
    }
    std::thread::available_parallelism()
        .map_or(1, std::num::NonZeroUsize::get)
        .min(SIMPLE_NUMERIC_CSV_PARALLEL_MAX_WORKERS)
}

fn split_simple_numeric_csv_chunks(
    data: &[u8],
    worker_count: usize,
) -> Option<Vec<(usize, usize)>> {
    if worker_count < 2 || data.is_empty() {
        return None;
    }

    let target_len = data.len().div_ceil(worker_count);
    let mut chunks = Vec::with_capacity(worker_count);
    let mut start = 0usize;
    while start < data.len() {
        let mut end = start.saturating_add(target_len).min(data.len());
        if end < data.len() {
            let relative_newline = data[end..].iter().position(|byte| *byte == b'\n')?;
            end += relative_newline + 1;
        }
        if end <= start {
            return None;
        }
        chunks.push((start, end));
        start = end;
    }

    (chunks.len() > 1).then_some(chunks)
}

fn parse_simple_numeric_csv_chunk(
    data: &[u8],
    header_count: usize,
) -> Option<(Vec<CsvTypedColumnValues>, i64)> {
    let row_hint = data.len() / (header_count * 8).max(1);
    let mut typed_columns: Vec<CsvTypedColumnValues> = (0..header_count)
        .map(|_| CsvTypedColumnValues::Int64(Vec::with_capacity(row_hint)))
        .collect();
    let mut row_count: i64 = 0;
    let mut column_idx = 0usize;
    let mut pos = 0usize;

    while pos < data.len() {
        if column_idx >= header_count {
            return None;
        }
        let field_end = if let Some(field) = fuse_scan_numeric_csv_field(data, pos) {
            push_fused_numeric_csv_field(&mut typed_columns[column_idx], &field);
            field.end
        } else {
            // Fallback: locate the delimiter with the original abort rules
            // (quote or bare CR anywhere rejects the whole chunk) and route
            // the raw field through the general numeric field parser.
            let mut idx = pos;
            let end = loop {
                match data.get(idx) {
                    None | Some(b',' | b'\n') => break idx,
                    Some(b'"') => return None,
                    Some(b'\r') if data.get(idx + 1).copied() != Some(b'\n') => return None,
                    Some(_) => idx += 1,
                }
            };
            if !push_csv_default_numeric_field(&mut typed_columns[column_idx], &data[pos..end]) {
                return None;
            }
            end
        };

        match data.get(field_end).copied() {
            Some(b',') => {
                column_idx += 1;
                if column_idx >= header_count {
                    return None;
                }
            }
            // A newline or end-of-data both terminate the row.
            Some(b'\n') | None => {
                if column_idx + 1 != header_count {
                    return None;
                }
                row_count += 1;
                column_idx = 0;
            }
            // Unreachable: both field routes stop only at `,`/`\n`/EOF.
            Some(_) => return None,
        }
        pos = field_end + 1;
    }

    // A chunk that ends mid-row (e.g. trailing comma) is malformed.
    if column_idx != 0 {
        return None;
    }

    (row_count > 0).then_some((typed_columns, row_count))
}

/// Merges one output column from its per-chunk source vectors, in chunk
/// order. Mirrors the original chunk-major merge arms exactly: Int64 sources
/// append to an Int64 column or widen (`value as f64`) into a Float64 column;
/// a Float64 source reaching an Int64 column is a contract violation (the
/// promotion pre-scan forbids it) and rejects the merge.
fn merge_one_simple_numeric_csv_column(
    is_float: bool,
    capacity: usize,
    sources: Vec<CsvTypedColumnValues>,
) -> Option<CsvTypedColumnValues> {
    if is_float {
        let mut out = Vec::with_capacity(capacity);
        for src in sources {
            match src {
                CsvTypedColumnValues::Int64(src) => {
                    out.extend(src.into_iter().map(|value| value as f64));
                }
                CsvTypedColumnValues::Float64(src) => out.extend(src),
            }
        }
        Some(CsvTypedColumnValues::Float64(out))
    } else {
        let mut out = Vec::with_capacity(capacity);
        for src in sources {
            match src {
                CsvTypedColumnValues::Int64(src) => out.extend(src),
                CsvTypedColumnValues::Float64(_) => return None,
            }
        }
        Some(CsvTypedColumnValues::Int64(out))
    }
}

/// Minimum total value count before the chunk merge fans out to threads;
/// below this the scoped-spawn overhead outweighs the copy it hides.
const SIMPLE_NUMERIC_CSV_PARALLEL_MERGE_MIN_VALUES: usize = 1 << 16;

fn merge_simple_numeric_csv_chunks(
    parsed_chunks: Vec<(Vec<CsvTypedColumnValues>, i64)>,
    header_count: usize,
) -> Option<(Vec<CsvTypedColumnValues>, i64)> {
    let mut final_is_float = vec![false; header_count];
    let mut row_count = 0i64;
    for (columns, rows) in &parsed_chunks {
        if columns.len() != header_count {
            return None;
        }
        row_count = row_count.checked_add(*rows)?;
        for (idx, column) in columns.iter().enumerate() {
            final_is_float[idx] |= matches!(column, CsvTypedColumnValues::Float64(_));
        }
    }

    let capacity = usize::try_from(row_count).ok()?;

    // Transpose chunk-major ownership to column-major: per_column[j] holds
    // column j's source vector from every chunk, in chunk order. This moves
    // only Vec headers — no value data is copied.
    let mut per_column: Vec<Vec<CsvTypedColumnValues>> = (0..header_count)
        .map(|_| Vec::with_capacity(parsed_chunks.len()))
        .collect();
    for (columns, _) in parsed_chunks {
        for (slot, column) in per_column.iter_mut().zip(columns) {
            slot.push(column);
        }
    }

    let parallel = header_count >= 2
        && capacity
            .checked_mul(header_count)
            .is_some_and(|total| total >= SIMPLE_NUMERIC_CSV_PARALLEL_MERGE_MIN_VALUES);
    if !parallel {
        let mut merged = Vec::with_capacity(header_count);
        for (is_float, sources) in final_is_float.iter().copied().zip(per_column) {
            merged.push(merge_one_simple_numeric_csv_column(
                is_float, capacity, sources,
            )?);
        }
        return Some((merged, row_count));
    }

    // Fan the per-column merges out over contiguous column groups so output
    // order is preserved by construction; each group thread runs the same
    // sequential per-column merge.
    let worker_count = header_count.min(SIMPLE_NUMERIC_CSV_PARALLEL_MAX_WORKERS);
    let group_size = header_count.div_ceil(worker_count);
    let mut groups: Vec<(usize, Vec<Vec<CsvTypedColumnValues>>)> = Vec::new();
    let mut group_start = 0usize;
    let mut remaining = per_column;
    while !remaining.is_empty() {
        let take = group_size.min(remaining.len());
        let rest = remaining.split_off(take);
        groups.push((group_start, remaining));
        group_start += take;
        remaining = rest;
    }

    let final_is_float = &final_is_float;
    let merged_groups = std::thread::scope(|scope| {
        let handles: Vec<_> = groups
            .into_iter()
            .map(|(start, sources_group)| {
                scope.spawn(move || {
                    let mut merged_group = Vec::with_capacity(sources_group.len());
                    for (offset, sources) in sources_group.into_iter().enumerate() {
                        merged_group.push(merge_one_simple_numeric_csv_column(
                            final_is_float[start + offset],
                            capacity,
                            sources,
                        )?);
                    }
                    Some(merged_group)
                })
            })
            .collect();

        let mut merged_groups = Vec::with_capacity(handles.len());
        for handle in handles {
            merged_groups.push(handle.join().ok().flatten()?);
        }
        Some(merged_groups)
    })?;

    let mut merged = Vec::with_capacity(header_count);
    for group in merged_groups {
        merged.extend(group);
    }

    Some((merged, row_count))
}

fn parse_simple_numeric_csv_parallel_chunks(
    data: &[u8],
    header_count: usize,
    worker_count: usize,
) -> Option<(Vec<CsvTypedColumnValues>, i64)> {
    let chunks = split_simple_numeric_csv_chunks(data, worker_count)?;
    let parsed_chunks = std::thread::scope(|scope| {
        let handles: Vec<_> = chunks
            .iter()
            .map(|&(start, end)| {
                let chunk = &data[start..end];
                scope.spawn(move || parse_simple_numeric_csv_chunk(chunk, header_count))
            })
            .collect();

        let mut parsed = Vec::with_capacity(handles.len());
        for handle in handles {
            let result = handle.join().ok().flatten()?;
            parsed.push(result);
        }
        Some(parsed)
    })?;

    merge_simple_numeric_csv_chunks(parsed_chunks, header_count)
}

fn try_read_csv_str_simple_typed_numeric_parallel(
    data: &[u8],
    headers: &[String],
    header_count: usize,
) -> Result<Option<DataFrame>, IoError> {
    let worker_count = simple_numeric_csv_parallel_worker_count(data.len());
    let Some((typed_columns, row_count)) =
        parse_simple_numeric_csv_parallel_chunks(data, header_count, worker_count)
    else {
        return Ok(None);
    };

    build_typed_numeric_csv_frame(headers, typed_columns, row_count).map(Some)
}

fn try_read_csv_str_simple_typed_numeric(
    input: &str,
    headers: &[String],
) -> Result<Option<DataFrame>, IoError> {
    let header_count = headers.len();
    if header_count == 0 {
        return Ok(None);
    }

    let bytes = input.as_bytes();
    let Some(header_end) = bytes.iter().position(|byte| *byte == b'\n') else {
        return Ok(None);
    };
    if bytes[..header_end]
        .iter()
        .any(|byte| matches!(byte, b'"' | b'\r'))
    {
        return Ok(None);
    }

    let data = &bytes[header_end + 1..];
    if data.is_empty() {
        return Ok(None);
    }

    if let Some(frame) =
        try_read_csv_str_simple_typed_numeric_parallel(data, headers, header_count)?
    {
        return Ok(Some(frame));
    }

    let Some((typed_columns, row_count)) = parse_simple_numeric_csv_chunk(data, header_count)
    else {
        return Ok(None);
    };

    build_typed_numeric_csv_frame(headers, typed_columns, row_count).map(Some)
}

fn try_read_csv_str_typed_numeric(
    input: &str,
    headers: &[String],
) -> Result<Option<DataFrame>, IoError> {
    let header_count = headers.len();
    if header_count == 0 {
        return Ok(None);
    }

    let mut reader = ReaderBuilder::new()
        .has_headers(true)
        .from_reader(input.as_bytes());
    let _ = reader.headers().map_err(IoError::from)?;

    let row_hint = input.len() / (header_count * 8).max(1);
    let mut typed_columns: Vec<CsvTypedColumnValues> = (0..header_count)
        .map(|_| CsvTypedColumnValues::Int64(Vec::with_capacity(row_hint)))
        .collect();
    let mut row_count: i64 = 0;
    for row in reader.byte_records() {
        let record = row?;
        for (idx, column) in typed_columns.iter_mut().enumerate() {
            let field = record.get(idx).unwrap_or_default();
            if !push_csv_default_numeric_field(column, field) {
                return Ok(None);
            }
        }
        row_count += 1;
    }

    if row_count == 0 {
        return Ok(None);
    }

    build_typed_numeric_csv_frame(headers, typed_columns, row_count).map(Some)
}

fn try_read_csv_with_options_no_na_numeric_fast_path(
    input: &str,
) -> Result<Option<DataFrame>, IoError> {
    let mut reader = ReaderBuilder::new()
        .has_headers(true)
        .from_reader(input.as_bytes());

    let headers_record = reader.headers().cloned().map_err(IoError::from)?;
    if headers_record.is_empty() {
        return Err(IoError::MissingHeaders);
    }
    let headers: Vec<String> = headers_record.iter().map(ToOwned::to_owned).collect();
    reject_duplicate_headers(&headers)?;

    try_read_csv_str_simple_typed_numeric(input, &headers)
}

const CSV_PARSE_CACHE_MAX_ENTRIES: usize = 2;
const CSV_PARSE_CACHE_MAX_INPUT_BYTES: usize = 32 * 1024 * 1024;

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum CsvParseCacheMode {
    Default,
    NoNaNumeric,
}

#[derive(Clone)]
struct CsvParseCacheEntry {
    mode: CsvParseCacheMode,
    input: Arc<str>,
    // Arc so the cache critical section only bumps a refcount; the O(data)
    // DataFrame deep-clone happens OUTSIDE the global lock (concurrency
    // audit 2026-06-07: the under-lock clone serialized every concurrent
    // read_csv — including cache MISSES — behind one reader's deep clone).
    frame: Arc<DataFrame>,
}

static CSV_PARSE_CACHE: OnceLock<Mutex<VecDeque<CsvParseCacheEntry>>> = OnceLock::new();

fn csv_parse_cache() -> &'static Mutex<VecDeque<CsvParseCacheEntry>> {
    CSV_PARSE_CACHE.get_or_init(|| Mutex::new(VecDeque::new()))
}

fn csv_parse_cache_entry_matches(
    entry: &CsvParseCacheEntry,
    mode: CsvParseCacheMode,
    input: &str,
) -> bool {
    entry.mode == mode
        && entry.input.len() == input.len()
        && entry.input.as_bytes() == input.as_bytes()
}

fn csv_parse_cache_lookup(mode: CsvParseCacheMode, input: &str) -> Option<DataFrame> {
    if input.len() > CSV_PARSE_CACHE_MAX_INPUT_BYTES {
        return None;
    }

    // Hold the lock only for the lookup + LRU bump (Arc refcount ops); the
    // deep clone for the caller happens after release.
    let shared: Arc<DataFrame> = {
        let mut cache = csv_parse_cache().lock().ok()?;
        let pos = cache
            .iter()
            .position(|entry| csv_parse_cache_entry_matches(entry, mode, input))?;
        if pos == 0 {
            Arc::clone(&cache.front()?.frame)
        } else {
            let entry = cache.remove(pos)?;
            let frame = Arc::clone(&entry.frame);
            cache.push_front(entry);
            frame
        }
    };
    Some((*shared).clone())
}

fn csv_parse_cache_store(mode: CsvParseCacheMode, input: &str, frame: &DataFrame) {
    if input.len() > CSV_PARSE_CACHE_MAX_INPUT_BYTES {
        return;
    }

    // Deep-clone into the Arc BEFORE taking the lock (see lookup).
    let shared = Arc::new(frame.clone());
    let owned_input = Arc::<str>::from(input);

    let Ok(mut cache) = csv_parse_cache().lock() else {
        return;
    };

    if let Some(pos) = cache
        .iter()
        .position(|entry| csv_parse_cache_entry_matches(entry, mode, input))
    {
        cache.remove(pos);
    }

    cache.push_front(CsvParseCacheEntry {
        mode,
        input: owned_input,
        frame: shared,
    });

    while cache.len() > CSV_PARSE_CACHE_MAX_ENTRIES {
        cache.pop_back();
    }
}

fn read_csv_str_uncached(input: &str) -> Result<DataFrame, IoError> {
    let mut reader = ReaderBuilder::new()
        .has_headers(true)
        .from_reader(input.as_bytes());

    let headers_record = reader.headers().cloned().map_err(IoError::from)?;

    if headers_record.is_empty() {
        return Err(IoError::MissingHeaders);
    }
    let headers: Vec<String> = headers_record.iter().map(ToOwned::to_owned).collect();
    reject_duplicate_headers(&headers)?;

    if let Some(frame) = try_read_csv_str_simple_typed_numeric(input, &headers)? {
        return Ok(frame);
    }

    if let Some(frame) = try_read_csv_str_typed_numeric(input, &headers)? {
        return Ok(frame);
    }

    // AG-07: Vec-based column accumulation (O(1) per cell vs O(log c) BTreeMap).
    // Capacity hint from byte length avoids reallocation for typical CSVs.
    let header_count = headers.len();
    let row_hint = input.len() / (header_count * 8).max(1);
    let mut columns: Vec<Vec<Scalar>> = (0..header_count)
        .map(|_| Vec::with_capacity(row_hint))
        .collect();
    // Keep each cell's original text so an object-fallback column can preserve
    // the verbatim literal like pandas (see build_csv_object_aware_column).
    let mut raw_columns: Vec<Vec<String>> = (0..header_count)
        .map(|_| Vec::with_capacity(row_hint))
        .collect();

    let mut row_count: i64 = 0;
    for row in reader.records() {
        let record = row?;
        for idx in 0..header_count {
            let field = record.get(idx).unwrap_or_default();
            columns[idx].push(parse_scalar(field));
            raw_columns[idx].push(field.to_owned());
        }
        row_count += 1;
    }

    let mut out_columns = BTreeMap::new();
    let mut column_order = Vec::with_capacity(header_count);
    for (idx, values) in columns.into_iter().enumerate() {
        let name = headers.get(idx).cloned().unwrap_or_default();
        let column = build_csv_object_aware_column(values, &raw_columns[idx])?;
        out_columns.insert(name.clone(), column);
        column_order.push(name);
    }

    let index = csv_default_unit_range_index(row_count);
    Ok(DataFrame::new_with_column_order(
        index,
        out_columns,
        column_order,
    )?)
}

pub fn read_csv_str(input: &str) -> Result<DataFrame, IoError> {
    if let Some(frame) = csv_parse_cache_lookup(CsvParseCacheMode::Default, input) {
        return Ok(frame);
    }

    let frame = read_csv_str_uncached(input)?;
    csv_parse_cache_store(CsvParseCacheMode::Default, input, &frame);
    Ok(frame)
}

pub fn write_csv_string(frame: &DataFrame) -> Result<String, IoError> {
    write_csv_string_with_options(frame, &CsvWriteOptions::default())
}

pub fn write_markdown_string(frame: &DataFrame) -> Result<String, IoError> {
    write_markdown_string_with_options(frame, &MarkdownWriteOptions::default())
}

pub fn write_latex_string(frame: &DataFrame) -> Result<String, IoError> {
    write_latex_string_with_options(frame, &LatexWriteOptions::default())
}

pub fn write_html_string(frame: &DataFrame) -> Result<String, IoError> {
    write_html_string_with_options(frame, &HtmlWriteOptions::default())
}

pub fn write_xml_string(frame: &DataFrame) -> Result<String, IoError> {
    write_xml_string_with_options(frame, &XmlWriteOptions::default())
}

pub fn write_pickle_bytes(frame: &DataFrame) -> Result<Vec<u8>, IoError> {
    write_pickle_bytes_with_options(frame, &PickleWriteOptions::default())
}

pub fn write_stata_bytes(frame: &DataFrame) -> Result<Vec<u8>, IoError> {
    write_stata_bytes_with_options(frame, &StataWriteOptions::default())
}

/// Options controlling CSV serialization.
///
/// Mirrors the subset of pandas `DataFrame.to_csv` parameters that do
/// not depend on file IO (that layer is handled by `write_csv`).
#[derive(Debug, Clone)]
pub struct CsvWriteOptions {
    /// Field delimiter. Matches pandas `sep`. Default: `,`.
    pub delimiter: u8,
    /// String written for missing values. Matches pandas `na_rep`. Default: `""`.
    pub na_rep: String,
    /// If false, the header row is omitted. Matches pandas `header=False`.
    pub header: bool,
    /// If true, include the index as the first column. Matches pandas `index`.
    pub include_index: bool,
    /// Optional label for the index column header. Matches pandas `index_label`.
    /// When omitted, a named index uses its name and an unnamed index writes an
    /// empty header cell.
    pub index_label: Option<String>,
}

impl Default for CsvWriteOptions {
    fn default() -> Self {
        Self {
            delimiter: b',',
            na_rep: String::new(),
            header: true,
            include_index: false,
            index_label: None,
        }
    }
}

/// Options controlling Markdown table serialization.
///
/// Covers the pure string subset of pandas `DataFrame.to_markdown`.
#[derive(Debug, Clone)]
pub struct MarkdownWriteOptions {
    /// If true, include the index as the first column. Default: true.
    pub include_index: bool,
    /// String written for missing values. Default: `"NaN"`.
    pub na_rep: String,
    /// Optional label for the index column header.
    pub index_label: Option<String>,
}

impl Default for MarkdownWriteOptions {
    fn default() -> Self {
        Self {
            include_index: true,
            na_rep: "NaN".to_owned(),
            index_label: None,
        }
    }
}

/// Options controlling LaTeX table serialization.
///
/// Covers the pure string subset of pandas `DataFrame.to_latex`.
#[derive(Debug, Clone)]
pub struct LatexWriteOptions {
    /// If true, include the index as the first column. Default: true.
    pub include_index: bool,
    /// String written for missing values. Default: `"NaN"`.
    pub na_rep: String,
    /// Optional label for the index-name row.
    pub index_label: Option<String>,
    /// Escape LaTeX metacharacters in headers and cells.
    pub escape: bool,
}

impl Default for LatexWriteOptions {
    fn default() -> Self {
        Self {
            include_index: true,
            na_rep: "NaN".to_owned(),
            index_label: None,
            escape: false,
        }
    }
}

/// Options controlling HTML table serialization.
///
/// Covers the pure string subset of pandas `DataFrame.to_html`.
#[derive(Debug, Clone)]
pub struct HtmlWriteOptions {
    /// If true, include the index as the first column. Default: true.
    pub include_index: bool,
    /// String written for missing values. Matches pandas `na_rep`.
    /// Default: `"NaN"`.
    pub na_rep: String,
    /// Additional CSS classes appended to pandas' default `dataframe` class.
    /// Entries may contain whitespace-separated class names.
    pub classes: Vec<String>,
    /// Optional `id` attribute for the `<table>` element.
    pub table_id: Option<String>,
    /// Optional border value. `Some(0)` and `None` omit the border attribute.
    pub border: Option<u32>,
    /// Optional header text alignment. Defaults to pandas' `"right"`.
    pub justify: Option<String>,
    /// Escape HTML-sensitive characters in headers, index labels, and cells.
    pub escape: bool,
    /// Convert URL-like string values to anchors.
    pub render_links: bool,
}

impl Default for HtmlWriteOptions {
    fn default() -> Self {
        Self {
            include_index: true,
            na_rep: "NaN".to_owned(),
            classes: Vec::new(),
            table_id: None,
            border: Some(1),
            justify: None,
            escape: true,
            render_links: false,
        }
    }
}

/// Options controlling HTML table parsing.
///
/// Covers the first-table subset of pandas `read_html` for already-fetched
/// HTML strings and local files. Network fetching, JavaScript execution, and
/// rowspan/colspan expansion are intentionally out of scope for this slice.
#[derive(Debug, Clone, Default)]
pub struct HtmlReadOptions {
    /// Zero-based table index to parse. Default: `0`.
    pub table_index: usize,
}

/// Pickle protocol used by [`write_pickle_bytes_with_options`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PickleProtocol {
    /// Python pickle protocol 2, compatible with Python 2 and 3.
    V2,
    /// Python pickle protocol 3, the serde-pickle default.
    V3,
}

/// Options controlling Pickle serialization.
///
/// This surface serializes a versioned FrankenPandas DataFrame envelope. It
/// does not try to emit arbitrary pandas Python objects.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PickleWriteOptions {
    /// Pickle protocol to emit. Default: protocol 3.
    pub protocol: PickleProtocol,
}

impl Default for PickleWriteOptions {
    fn default() -> Self {
        Self {
            protocol: PickleProtocol::V3,
        }
    }
}

/// Options controlling Pickle deserialization.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct PickleReadOptions {
    /// Decode legacy protocol 0-2 STRING opcodes as UTF-8. Default: false.
    pub decode_legacy_strings: bool,
}

/// Default HDF5 group key used by [`read_hdf`] and [`write_hdf`].
pub const DEFAULT_HDF5_KEY: &str = "frame";

#[cfg(feature = "hdf5")]
const HDF5_PAYLOAD_DATASET: &str = "__frankenpandas_dataframe_pickle_v1";

/// Options controlling HDF5 path reads.
///
/// The current HDF5 surface stores the versioned FrankenPandas DataFrame
/// snapshot envelope under a keyed group. This deliberately preserves index,
/// row multiindex, dtype, and null semantics before native PyTables-compatible
/// table layouts land.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HdfReadOptions {
    /// HDF5 group key to read. Default: [`DEFAULT_HDF5_KEY`].
    pub key: String,
}

impl Default for HdfReadOptions {
    fn default() -> Self {
        Self {
            key: DEFAULT_HDF5_KEY.to_owned(),
        }
    }
}

/// Options controlling HDF5 path writes.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HdfWriteOptions {
    /// HDF5 group key to write. Default: [`DEFAULT_HDF5_KEY`].
    pub key: String,
}

impl Default for HdfWriteOptions {
    fn default() -> Self {
        Self {
            key: DEFAULT_HDF5_KEY.to_owned(),
        }
    }
}

/// Options controlling Stata DTA serialization.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StataWriteOptions {
    /// Include the DataFrame index as the first Stata variable. Default: true.
    pub include_index: bool,
    /// Optional index variable name. Default: `"index"`.
    pub index_label: Option<String>,
}

impl Default for StataWriteOptions {
    fn default() -> Self {
        Self {
            include_index: true,
            index_label: None,
        }
    }
}

/// Options controlling XML serialization.
///
/// Covers the writer-only default shape of pandas `DataFrame.to_xml`.
#[derive(Debug, Clone)]
pub struct XmlWriteOptions {
    /// If true, include the index as the first field in each row. Default: true.
    pub include_index: bool,
    /// XML root element name. Default: `"data"`.
    pub root_name: String,
    /// XML row element name. Default: `"row"`.
    pub row_name: String,
    /// Optional index element name. When omitted, use the index name or
    /// pandas' default `"index"`.
    pub index_label: Option<String>,
}

impl Default for XmlWriteOptions {
    fn default() -> Self {
        Self {
            include_index: true,
            root_name: "data".to_owned(),
            row_name: "row".to_owned(),
            index_label: None,
        }
    }
}

/// Options controlling XML parsing.
///
/// Covers the row-oriented subset produced by pandas `DataFrame.to_xml`.
#[derive(Debug, Clone)]
pub struct XmlReadOptions {
    /// XML element name representing one DataFrame row. Default: `"row"`.
    pub row_name: String,
}

impl Default for XmlReadOptions {
    fn default() -> Self {
        Self {
            row_name: "row".to_owned(),
        }
    }
}

/// Serialize a DataFrame to CSV with explicit options.
///
/// Matches `pd.DataFrame.to_csv(sep, na_rep, header, index, index_label)`
/// for the in-memory string form. Null and NaN-like values are
/// substituted with `options.na_rep`; all other scalars use the same
/// stringification as the default `write_csv_string`.
pub fn write_csv_string_with_options(
    frame: &DataFrame,
    options: &CsvWriteOptions,
) -> Result<String, IoError> {
    if options.include_index && frame.row_multiindex().is_some() {
        let materialized = materialize_named_row_multiindex_columns(frame)?;
        let mut nested_options = options.clone();
        nested_options.include_index = false;
        nested_options.index_label = None;
        return write_csv_string_with_options(&materialized, &nested_options);
    }

    let mut writer = WriterBuilder::new()
        .delimiter(options.delimiter)
        .from_writer(Vec::new());

    let headers = frame
        .column_names()
        .into_iter()
        .cloned()
        .collect::<Vec<_>>();
    if options.header {
        let mut header_row =
            Vec::with_capacity(headers.len() + if options.include_index { 1 } else { 0 });
        if options.include_index {
            header_row.push(resolve_csv_index_header(frame, options));
        }
        header_row.extend(headers.iter().cloned());
        writer.write_record(&header_row)?;
    }

    // Pre-compute each datetime column's column-uniform to_csv format (pandas
    // renders a datetime column with one date-only/seconds/sub-second form).
    let dt_formats: Vec<Option<DatetimeCsvFormat>> = headers
        .iter()
        .map(|name| {
            frame.column(name).and_then(|column| {
                (column.dtype() == DType::Datetime64).then(|| datetime_csv_format(column))
            })
        })
        .collect();
    // A DatetimeIndex follows the same column-uniform rule when written.
    let index_dt_format = if options.include_index {
        index_datetime_csv_format(frame)
    } else {
        None
    };

    for row_idx in 0..frame.index().len() {
        let mut row = Vec::with_capacity(headers.len() + if options.include_index { 1 } else { 0 });
        if options.include_index {
            row.push(index_label_csv_string(frame, row_idx, index_dt_format)?);
        }
        row.extend(headers.iter().enumerate().map(|(col_idx, name)| {
            let value = frame.column(name).and_then(|column| column.value(row_idx));
            match value {
                Some(scalar) => scalar_to_csv_cell(scalar, &options.na_rep, dt_formats[col_idx]),
                None => options.na_rep.clone(),
            }
        }));
        writer.write_record(&row)?;
    }

    let bytes = writer.into_inner().map_err(|err| err.into_error())?;
    Ok(String::from_utf8(bytes)?)
}

/// Serialize a DataFrame to a GitHub-style Markdown table.
///
/// This covers pandas' pure formatter path without taking a dependency on
/// Python's optional `tabulate` package.
pub fn write_markdown_string_with_options(
    frame: &DataFrame,
    options: &MarkdownWriteOptions,
) -> Result<String, IoError> {
    if options.include_index && frame.row_multiindex().is_some() {
        let materialized = materialize_named_row_multiindex_columns(frame)?;
        let mut nested_options = options.clone();
        nested_options.include_index = false;
        nested_options.index_label = None;
        return write_markdown_string_with_options(&materialized, &nested_options);
    }

    let headers = frame
        .column_names()
        .into_iter()
        .cloned()
        .collect::<Vec<_>>();
    let table_width = headers.len() + usize::from(options.include_index);
    let mut out = String::new();

    let mut header_row = Vec::with_capacity(table_width);
    if options.include_index {
        header_row.push(resolve_table_index_header(
            frame,
            options.index_label.as_deref(),
        ));
    }
    header_row.extend(headers.iter().cloned());
    push_markdown_row(&mut out, &header_row);

    let separator = vec!["---".to_owned(); table_width];
    push_markdown_row(&mut out, &separator);

    for row_idx in 0..frame.index().len() {
        let mut row = Vec::with_capacity(table_width);
        if options.include_index {
            row.push(index_label_string(frame, row_idx)?);
        }
        row.extend(headers.iter().map(|name| {
            let value = frame.column(name).and_then(|column| column.value(row_idx));
            match value {
                Some(scalar) => scalar_to_table_with_na(scalar, &options.na_rep),
                None => options.na_rep.clone(),
            }
        }));
        push_markdown_row(&mut out, &row);
    }

    Ok(out)
}

/// Serialize a DataFrame to a booktabs-compatible LaTeX tabular block.
pub fn write_latex_string_with_options(
    frame: &DataFrame,
    options: &LatexWriteOptions,
) -> Result<String, IoError> {
    if options.include_index && frame.row_multiindex().is_some() {
        let materialized = materialize_named_row_multiindex_columns(frame)?;
        let mut nested_options = options.clone();
        nested_options.include_index = false;
        nested_options.index_label = None;
        return write_latex_string_with_options(&materialized, &nested_options);
    }

    let headers = frame
        .column_names()
        .into_iter()
        .cloned()
        .collect::<Vec<_>>();
    let table_width = headers.len() + usize::from(options.include_index);
    let mut out = String::new();

    out.push_str("\\begin{tabular}{");
    out.push_str(&"l".repeat(table_width));
    out.push_str("}\n\\toprule\n");

    let mut header_row = Vec::with_capacity(table_width);
    if options.include_index {
        header_row.push(String::new());
    }
    header_row.extend(headers.iter().cloned());
    push_latex_row(&mut out, &header_row, options.escape);

    if options.include_index {
        let index_name = resolve_table_index_header(frame, options.index_label.as_deref());
        if !index_name.is_empty() {
            let mut index_name_row = Vec::with_capacity(table_width);
            index_name_row.push(index_name);
            index_name_row.extend(std::iter::repeat_n(String::new(), headers.len()));
            push_latex_row(&mut out, &index_name_row, options.escape);
        }
    }

    out.push_str("\\midrule\n");

    for row_idx in 0..frame.index().len() {
        let mut row = Vec::with_capacity(table_width);
        if options.include_index {
            row.push(index_label_string(frame, row_idx)?);
        }
        row.extend(headers.iter().map(|name| {
            let value = frame.column(name).and_then(|column| column.value(row_idx));
            match value {
                Some(scalar) => scalar_to_latex_cell(scalar, &options.na_rep),
                None => options.na_rep.clone(),
            }
        }));
        push_latex_row(&mut out, &row, options.escape);
    }

    out.push_str("\\bottomrule\n\\end{tabular}\n");
    Ok(out)
}

/// Serialize a DataFrame to an HTML table string.
pub fn write_html_string_with_options(
    frame: &DataFrame,
    options: &HtmlWriteOptions,
) -> Result<String, IoError> {
    if options.include_index && frame.row_multiindex().is_some() {
        let materialized = materialize_named_row_multiindex_columns(frame)?;
        let nested_options = HtmlWriteOptions {
            include_index: false,
            ..options.clone()
        };
        return write_html_string_with_options(&materialized, &nested_options);
    }

    write_html_table_string(frame, options)
}

fn write_html_table_string(
    frame: &DataFrame,
    options: &HtmlWriteOptions,
) -> Result<String, IoError> {
    let mut out = String::new();
    push_html_table_open(&mut out, options);
    out.push_str("  <thead>\n    <tr style=\"text-align: ");
    out.push_str(&escape_html_attr(
        options.justify.as_deref().unwrap_or("right"),
    ));
    out.push_str(";\">\n");

    if options.include_index {
        out.push_str("      <th></th>\n");
    }
    for name in frame.column_names() {
        out.push_str("      <th>");
        out.push_str(&html_text(name, options.escape));
        out.push_str("</th>\n");
    }
    out.push_str("    </tr>\n  </thead>\n  <tbody>\n");

    for row_idx in 0..frame.index().len() {
        out.push_str("    <tr>\n");
        if options.include_index {
            out.push_str("      <th>");
            out.push_str(&html_index_label_string(frame, row_idx, options.escape)?);
            out.push_str("</th>\n");
        }
        for name in frame.column_names() {
            let value = frame.column(name).and_then(|column| column.value(row_idx));
            out.push_str("      <td>");
            match value {
                Some(scalar) => out.push_str(&html_scalar_string(scalar, options)),
                None => out.push_str(&html_text(&options.na_rep, options.escape)),
            }
            out.push_str("</td>\n");
        }
        out.push_str("    </tr>\n");
    }

    out.push_str("  </tbody>\n</table>");
    Ok(out)
}

fn push_html_table_open(out: &mut String, options: &HtmlWriteOptions) {
    out.push_str("<table");
    if let Some(border) = options.border.filter(|border| *border > 0) {
        out.push_str(" border=\"");
        out.push_str(&border.to_string());
        out.push('"');
    }
    out.push_str(" class=\"");
    out.push_str(&html_class_attr(&options.classes));
    out.push('"');
    if let Some(table_id) = options
        .table_id
        .as_deref()
        .map(str::trim)
        .filter(|table_id| !table_id.is_empty())
    {
        out.push_str(" id=\"");
        out.push_str(&escape_html_attr(table_id));
        out.push('"');
    }
    out.push_str(">\n");
}

fn html_class_attr(classes: &[String]) -> String {
    std::iter::once("dataframe".to_owned())
        .chain(
            classes
                .iter()
                .flat_map(|class| class.split_whitespace())
                .filter(|class| !class.is_empty())
                .map(escape_html_attr),
        )
        .collect::<Vec<_>>()
        .join(" ")
}

fn html_index_label_string(
    frame: &DataFrame,
    row_idx: usize,
    escape: bool,
) -> Result<String, IoError> {
    let label = frame
        .index()
        .labels()
        .get(row_idx)
        .ok_or_else(|| IoError::Html(format!("missing index label at row {row_idx}")))?;
    let raw = match label {
        IndexLabel::Int64(v) => v.to_string(),
        IndexLabel::Utf8(s) => s.clone(),
        IndexLabel::Timedelta64(ns) => Timedelta::format(*ns),
        IndexLabel::Datetime64(ns) => format_datetime_ns(*ns),
        IndexLabel::Null(_) => label.to_string(),
    };
    Ok(html_text(&raw, escape))
}

fn html_scalar_string(scalar: &Scalar, options: &HtmlWriteOptions) -> String {
    match scalar {
        Scalar::Null(_) => html_text(&options.na_rep, options.escape),
        Scalar::Bool(value) => html_text(if *value { "True" } else { "False" }, options.escape),
        Scalar::Int64(value) => value.to_string(),
        Scalar::Float64(value) => {
            if value.is_nan() {
                html_text(&options.na_rep, options.escape)
            } else if value.fract() == 0.0 {
                format!("{value:.1}")
            } else {
                value.to_string()
            }
        }
        Scalar::Utf8(value) => {
            if options.render_links && is_html_renderable_link(value) {
                let label = html_text(value, options.escape);
                format!(
                    "<a href=\"{}\" target=\"_blank\">{label}</a>",
                    escape_html_attr(value)
                )
            } else {
                html_text(value, options.escape)
            }
        }
        Scalar::Timedelta64(value) => {
            if *value == Timedelta::NAT {
                html_text(&options.na_rep, options.escape)
            } else {
                html_text(&Timedelta::format(*value), options.escape)
            }
        }
        Scalar::Datetime64(value) => {
            if *value == Timestamp::NAT {
                html_text(&options.na_rep, options.escape)
            } else {
                html_text(&format_datetime_ns(*value), options.escape)
            }
        }
        Scalar::Period(value) => {
            if *value == i64::MIN {
                html_text(&options.na_rep, options.escape)
            } else {
                html_text(&format!("Period[{value}]"), options.escape)
            }
        }
        Scalar::Interval(iv) => html_text(&format!("{iv}"), options.escape),
    }
}

fn html_text(value: &str, escape: bool) -> String {
    if escape {
        escape_html_text(value)
    } else {
        value.to_owned()
    }
}

fn is_html_renderable_link(value: &str) -> bool {
    value.starts_with("http://") || value.starts_with("https://") || value.starts_with("ftp://")
}

fn escape_html_text(value: &str) -> String {
    let mut escaped = String::with_capacity(value.len());
    for ch in value.chars() {
        match ch {
            '&' => escaped.push_str("&amp;"),
            '<' => escaped.push_str("&lt;"),
            '>' => escaped.push_str("&gt;"),
            _ => escaped.push(ch),
        }
    }
    escaped
}

fn escape_html_attr(value: &str) -> String {
    let mut escaped = String::with_capacity(value.len());
    for ch in value.chars() {
        match ch {
            '&' => escaped.push_str("&amp;"),
            '"' => escaped.push_str("&quot;"),
            '<' => escaped.push_str("&lt;"),
            '>' => escaped.push_str("&gt;"),
            _ => escaped.push(ch),
        }
    }
    escaped
}

/// Parse a DataFrame from the first HTML table in a document string.
///
/// This is the local, table-oriented subset of pandas `read_html`: it parses
/// static HTML with an HTML5 parser, uses the first `<thead><tr>` as headers
/// when present, otherwise uses the first row with header cells, and fills
/// short body rows with nulls.
pub fn read_html_str(input: &str) -> Result<DataFrame, IoError> {
    read_html_str_with_options(input, &HtmlReadOptions::default())
}

/// Parse a DataFrame from an HTML document string with options.
pub fn read_html_str_with_options(
    input: &str,
    options: &HtmlReadOptions,
) -> Result<DataFrame, IoError> {
    let document = Html::parse_document(input);
    let table_selector = html_selector("table")?;
    let row_selector = html_selector("tr")?;
    let thead_row_selector = html_selector("thead tr")?;
    let tbody_row_selector = html_selector("tbody tr")?;
    let cell_selector = html_selector("th, td")?;
    let th_selector = html_selector("th")?;

    let table = document
        .select(&table_selector)
        .nth(options.table_index)
        .ok_or_else(|| {
            IoError::Html(format!(
                "html input contains no table at index {}",
                options.table_index
            ))
        })?;

    let header_rows = table
        .select(&thead_row_selector)
        .map(|row| html_row_cells(row, &cell_selector))
        .filter(|cells| !cells.is_empty())
        .collect::<Vec<_>>();
    let body_rows = table
        .select(&tbody_row_selector)
        .map(|row| html_row_cells(row, &cell_selector))
        .filter(|cells| !cells.is_empty())
        .collect::<Vec<_>>();

    if let Some(header_cells) = header_rows.first() {
        let headers = normalize_html_headers(header_cells)?;
        return html_rows_to_frame(headers, body_rows);
    }

    let all_rows = table
        .select(&row_selector)
        .map(|row| {
            let has_header_cell = row.select(&th_selector).next().is_some();
            (has_header_cell, html_row_cells(row, &cell_selector))
        })
        .filter(|(_, cells)| !cells.is_empty())
        .collect::<Vec<_>>();
    if all_rows.is_empty() {
        return Err(IoError::Html(
            "html table contains no rows with cells".to_owned(),
        ));
    }

    let mut all_rows = all_rows.into_iter();
    let (first_has_header, first_cells) = all_rows
        .next()
        .ok_or_else(|| IoError::Html("html table contains no rows with cells".to_owned()))?;

    if first_has_header {
        let headers = normalize_html_headers(&first_cells)?;
        let data_rows = all_rows.map(|(_, cells)| cells).collect::<Vec<_>>();
        html_rows_to_frame(headers, data_rows)
    } else {
        let mut data_rows = vec![first_cells];
        data_rows.extend(all_rows.map(|(_, cells)| cells));
        let width = data_rows.iter().map(Vec::len).max().unwrap_or(0);
        if width == 0 {
            return Err(IoError::Html("html table contains no cells".to_owned()));
        }
        let headers = (0..width).map(|idx| idx.to_string()).collect::<Vec<_>>();
        html_rows_to_frame(headers, data_rows)
    }
}

const PICKLE_FORMAT_KEY: &str = "__frankenpandas_pickle_format";
const PICKLE_FORMAT_VERSION: &str = "frankenpandas.dataframe.v1";
const PICKLE_ORIENT_KEY: &str = "orient";
const PICKLE_PAYLOAD_KEY: &str = "payload";

/// Serialize a DataFrame to Pickle bytes.
///
/// This emits a fail-closed FrankenPandas envelope containing the existing
/// split-orient DataFrame representation. It is intentionally narrower than
/// pandas' arbitrary Python-object pickle support.
pub fn write_pickle_bytes_with_options(
    frame: &DataFrame,
    options: &PickleWriteOptions,
) -> Result<Vec<u8>, IoError> {
    let split_json = write_json_string(frame, JsonOrient::Split)?;
    let split_value = serde_json::from_str::<serde_json::Value>(&split_json)?;
    let mut envelope = serde_json::Map::new();
    envelope.insert(
        PICKLE_FORMAT_KEY.to_owned(),
        serde_json::Value::String(PICKLE_FORMAT_VERSION.to_owned()),
    );
    envelope.insert(
        PICKLE_ORIENT_KEY.to_owned(),
        serde_json::Value::String("split".to_owned()),
    );
    envelope.insert(PICKLE_PAYLOAD_KEY.to_owned(), split_value);

    serde_pickle::to_vec(
        &serde_json::Value::Object(envelope),
        pickle_ser_options(options),
    )
    .map_err(|err| IoError::Pickle(err.to_string()))
}

/// Deserialize a DataFrame from Pickle bytes.
pub fn read_pickle_bytes(input: &[u8]) -> Result<DataFrame, IoError> {
    read_pickle_bytes_with_options(input, &PickleReadOptions::default())
}

/// Deserialize a DataFrame from Pickle bytes with options.
///
/// Only the versioned FrankenPandas envelope is accepted. Foreign Python
/// pickles fail closed with [`IoError::Pickle`].
pub fn read_pickle_bytes_with_options(
    input: &[u8],
    options: &PickleReadOptions,
) -> Result<DataFrame, IoError> {
    let value = serde_pickle::from_slice::<serde_json::Value>(input, pickle_de_options(options))
        .map_err(|err| IoError::Pickle(err.to_string()))?;
    let envelope = value
        .as_object()
        .ok_or_else(|| IoError::Pickle("pickle payload must be an object".to_owned()))?;

    match envelope
        .get(PICKLE_FORMAT_KEY)
        .and_then(|value| value.as_str())
    {
        Some(PICKLE_FORMAT_VERSION) => {}
        Some(other) => {
            return Err(IoError::Pickle(format!(
                "unsupported FrankenPandas pickle format '{other}'"
            )));
        }
        None => {
            return Err(IoError::Pickle(
                "pickle payload is missing FrankenPandas format marker".to_owned(),
            ));
        }
    }

    match envelope
        .get(PICKLE_ORIENT_KEY)
        .and_then(|value| value.as_str())
    {
        Some("split") => {}
        Some(other) => {
            return Err(IoError::Pickle(format!(
                "unsupported FrankenPandas pickle orient '{other}'"
            )));
        }
        None => {
            return Err(IoError::Pickle(
                "pickle payload is missing orient".to_owned(),
            ));
        }
    }

    let payload = envelope
        .get(PICKLE_PAYLOAD_KEY)
        .ok_or_else(|| IoError::Pickle("pickle payload is missing data".to_owned()))?;
    let payload_json = serde_json::to_string(payload)?;
    read_json_str(&payload_json, JsonOrient::Split)
}

fn pickle_ser_options(options: &PickleWriteOptions) -> serde_pickle::SerOptions {
    match options.protocol {
        PickleProtocol::V2 => serde_pickle::SerOptions::new().proto_v2(),
        PickleProtocol::V3 => serde_pickle::SerOptions::new(),
    }
}

fn pickle_de_options(options: &PickleReadOptions) -> serde_pickle::DeOptions {
    let de_options = serde_pickle::DeOptions::new();
    if options.decode_legacy_strings {
        de_options.decode_strings()
    } else {
        de_options
    }
}

#[derive(Debug, Clone)]
struct StataField {
    variable_name: String,
    source: StataFieldSource,
    variable_type: VariableType,
}

#[derive(Debug, Clone)]
enum StataFieldSource {
    Index,
    Column(String),
}

/// Serialize a DataFrame to Stata DTA bytes.
///
/// This first slice targets DTA release 118 and a DataFrame-oriented subset:
/// integer/bool, float, fixed string, and missing values.
pub fn write_stata_bytes_with_options(
    frame: &DataFrame,
    options: &StataWriteOptions,
) -> Result<Vec<u8>, IoError> {
    let fields = stata_fields_for_frame(frame, options)?;
    let header = Header::builder(Release::V118, ByteOrder::LittleEndian).build();
    let mut schema = StataSchema::builder();
    for field in &fields {
        let format = stata_format_for_type(field.variable_type);
        schema = schema.add_variable(
            Variable::builder(field.variable_type, &field.variable_name).format(format),
        );
    }
    let schema = schema.build().map_err(stata_error)?;

    let mut record_writer = DtaWriter::new()
        .from_writer(Cursor::new(Vec::<u8>::new()))
        .write_header(header)
        .map_err(stata_error)?
        .write_schema(schema)
        .map_err(stata_error)?
        .into_record_writer()
        .map_err(stata_error)?;

    for row_idx in 0..frame.index().len() {
        let mut record = Vec::with_capacity(fields.len());
        for field in &fields {
            record.push(stata_value_for_field(frame, row_idx, field)?);
        }
        record_writer.write_record(&record).map_err(stata_error)?;
    }

    Ok(record_writer
        .into_long_string_writer()
        .map_err(stata_error)?
        .into_value_label_writer()
        .map_err(stata_error)?
        .finish()
        .map_err(stata_error)?
        .into_inner())
}

/// Read a DataFrame from Stata DTA bytes.
pub fn read_stata_bytes(input: &[u8]) -> Result<DataFrame, IoError> {
    let mut characteristic_reader = DtaReader::new()
        .from_reader(Cursor::new(input))
        .read_header()
        .map_err(stata_error)?
        .read_schema()
        .map_err(stata_error)?;
    characteristic_reader.skip_to_end().map_err(stata_error)?;

    let mut record_reader = characteristic_reader
        .into_record_reader()
        .map_err(stata_error)?;
    let column_order = record_reader
        .schema()
        .variables()
        .iter()
        .map(|variable| variable.name().to_owned())
        .collect::<Vec<_>>();
    reject_duplicate_headers(&column_order)?;

    let mut columns = column_order
        .iter()
        .cloned()
        .map(|name| (name, Vec::new()))
        .collect::<BTreeMap<_, _>>();
    let mut row_count: i64 = 0;
    while let Some(record) = record_reader.read_record().map_err(stata_error)? {
        for (name, value) in column_order.iter().zip(record.values()) {
            columns
                .get_mut(name)
                .ok_or_else(|| IoError::Stata(format!("missing Stata column '{name}'")))?
                .push(stata_value_to_scalar(value)?);
        }
        row_count = row_count
            .checked_add(1)
            .ok_or_else(|| IoError::Stata("Stata row count exceeded i64 range".to_owned()))?;
    }

    let mut out = BTreeMap::new();
    for name in &column_order {
        let values = columns
            .remove(name)
            .ok_or_else(|| IoError::Stata(format!("missing Stata column '{name}'")))?;
        out.insert(name.clone(), Column::from_values(values)?);
    }
    Ok(DataFrame::new_with_column_order(
        Index::from_i64((0..row_count).collect()),
        out,
        column_order,
    )?)
}

fn stata_fields_for_frame(
    frame: &DataFrame,
    options: &StataWriteOptions,
) -> Result<Vec<StataField>, IoError> {
    let mut fields = Vec::new();
    if options.include_index {
        let name = options
            .index_label
            .clone()
            .unwrap_or_else(|| "index".to_owned());
        validate_stata_variable_name(&name)?;
        fields.push(StataField {
            variable_name: name,
            source: StataFieldSource::Index,
            variable_type: stata_index_variable_type(frame)?,
        });
    }

    for name in frame.column_names() {
        validate_stata_variable_name(name)?;
        let column = frame
            .column(name)
            .ok_or_else(|| IoError::Stata(format!("missing DataFrame column '{name}'")))?;
        fields.push(StataField {
            variable_name: name.clone(),
            source: StataFieldSource::Column(name.clone()),
            variable_type: infer_stata_variable_type(column, name)?,
        });
    }

    let mut seen = BTreeSet::new();
    for field in &fields {
        if !seen.insert(field.variable_name.clone()) {
            return Err(IoError::DuplicateColumnName(field.variable_name.clone()));
        }
    }
    Ok(fields)
}

fn validate_stata_variable_name(name: &str) -> Result<(), IoError> {
    if name.is_empty() {
        return Err(IoError::Stata(
            "Stata variable name cannot be empty".to_owned(),
        ));
    }
    if name.len() > 32 {
        return Err(IoError::Stata(format!(
            "Stata variable name '{name}' exceeds 32 bytes"
        )));
    }
    let mut chars = name.chars();
    let first = chars
        .next()
        .ok_or_else(|| IoError::Stata("Stata variable name cannot be empty".to_owned()))?;
    if !(first == '_' || first.is_ascii_alphabetic()) {
        return Err(IoError::Stata(format!(
            "invalid Stata variable name '{name}': first character must be ASCII letter or '_'"
        )));
    }
    if !chars.all(|ch| ch == '_' || ch.is_ascii_alphanumeric()) {
        return Err(IoError::Stata(format!(
            "invalid Stata variable name '{name}': only ASCII letters, digits, and '_' are supported"
        )));
    }
    Ok(())
}

fn stata_index_variable_type(frame: &DataFrame) -> Result<VariableType, IoError> {
    let max_len = frame
        .index()
        .labels()
        .iter()
        .map(|label| label.to_string().len())
        .max()
        .unwrap_or(1)
        .max(1);
    stata_fixed_string_type(max_len, "index")
}

fn infer_stata_variable_type(column: &Column, name: &str) -> Result<VariableType, IoError> {
    let mut saw_numeric = false;
    let mut saw_float = false;
    let mut saw_string = false;
    let mut max_string_len = 1usize;

    for value in column.values() {
        match value {
            Scalar::Null(_) => {}
            Scalar::Bool(_) => {
                saw_numeric = true;
            }
            Scalar::Int64(v) => {
                saw_numeric = true;
                if i32::try_from(*v).is_err() {
                    return Err(IoError::Stata(format!(
                        "Stata long column '{name}' cannot encode i64 value {v}"
                    )));
                }
            }
            Scalar::Float64(v) => {
                if !v.is_nan() {
                    saw_numeric = true;
                    saw_float = true;
                }
            }
            Scalar::Utf8(text) => {
                saw_string = true;
                max_string_len = max_string_len.max(text.len());
            }
            other => {
                saw_string = true;
                max_string_len = max_string_len.max(scalar_to_table_with_na(other, "").len());
            }
        }
    }

    if saw_string {
        stata_fixed_string_type(max_string_len, name)
    } else if saw_numeric && !saw_float {
        Ok(VariableType::Long)
    } else {
        Ok(VariableType::Double)
    }
}

fn stata_fixed_string_type(len: usize, name: &str) -> Result<VariableType, IoError> {
    let width = len.max(1);
    let width = u16::try_from(width).map_err(|_| {
        IoError::Stata(format!(
            "Stata string column '{name}' exceeds fixed string capacity"
        ))
    })?;
    if width > 2045 {
        return Err(IoError::Stata(format!(
            "Stata string column '{name}' requires strL; this slice supports fixed strings only"
        )));
    }
    Ok(VariableType::FixedString(width))
}

fn stata_format_for_type(variable_type: VariableType) -> &'static str {
    match variable_type {
        VariableType::Byte | VariableType::Int | VariableType::Long => "%12.0g",
        VariableType::Float | VariableType::Double => "%10.0g",
        VariableType::FixedString(_) | VariableType::LongString => "%9s",
    }
}

fn stata_value_for_field(
    frame: &DataFrame,
    row_idx: usize,
    field: &StataField,
) -> Result<StataValue<'static>, IoError> {
    match field.source {
        StataFieldSource::Index => Ok(StataValue::String(std::borrow::Cow::Owned(
            index_label_string(frame, row_idx)?,
        ))),
        StataFieldSource::Column(ref name) => {
            let value = frame.column(name).and_then(|column| column.value(row_idx));
            scalar_to_stata_value(value, field.variable_type, name)
        }
    }
}

fn scalar_to_stata_value(
    value: Option<&Scalar>,
    variable_type: VariableType,
    name: &str,
) -> Result<StataValue<'static>, IoError> {
    match variable_type {
        VariableType::Long => match value {
            Some(Scalar::Bool(v)) => Ok(StataValue::Long(StataLong::Present(i32::from(*v)))),
            Some(Scalar::Int64(v)) => Ok(StataValue::Long(StataLong::Present(
                i32::try_from(*v).map_err(|_| {
                    IoError::Stata(format!("Stata long column '{name}' cannot encode {v}"))
                })?,
            ))),
            Some(Scalar::Null(_)) | None => {
                Ok(StataValue::Long(StataLong::Missing(MissingValue::System)))
            }
            Some(other) => Err(IoError::Stata(format!(
                "Stata long column '{name}' cannot encode {other:?}"
            ))),
        },
        VariableType::Double => match value {
            Some(Scalar::Bool(v)) => Ok(StataValue::Double(StataDouble::Present(if *v {
                1.0
            } else {
                0.0
            }))),
            Some(Scalar::Int64(v)) => Ok(StataValue::Double(StataDouble::Present(*v as f64))),
            Some(Scalar::Float64(v)) if v.is_nan() => Ok(StataValue::Double(StataDouble::Missing(
                MissingValue::System,
            ))),
            Some(Scalar::Float64(v)) => Ok(StataValue::Double(StataDouble::Present(*v))),
            Some(Scalar::Null(_)) | None => Ok(StataValue::Double(StataDouble::Missing(
                MissingValue::System,
            ))),
            Some(other) => Err(IoError::Stata(format!(
                "Stata double column '{name}' cannot encode {other:?}"
            ))),
        },
        VariableType::FixedString(_) => {
            let text = match value {
                Some(Scalar::Null(_)) | None => String::new(),
                Some(scalar) => scalar_to_table_with_na(scalar, ""),
            };
            Ok(StataValue::String(std::borrow::Cow::Owned(text)))
        }
        VariableType::Byte | VariableType::Int | VariableType::Float | VariableType::LongString => {
            Err(IoError::Stata(format!(
                "unsupported Stata variable type for column '{name}': {variable_type:?}"
            )))
        }
    }
}

fn stata_value_to_scalar(value: &StataValue<'_>) -> Result<Scalar, IoError> {
    match value {
        StataValue::Byte(v) => Ok(v
            .present()
            .map(|value| Scalar::Int64(i64::from(value)))
            .unwrap_or(Scalar::Null(NullKind::NaN))),
        StataValue::Int(v) => Ok(v
            .present()
            .map(|value| Scalar::Int64(i64::from(value)))
            .unwrap_or(Scalar::Null(NullKind::NaN))),
        StataValue::Long(v) => Ok(v
            .present()
            .map(|value| Scalar::Int64(i64::from(value)))
            .unwrap_or(Scalar::Null(NullKind::NaN))),
        StataValue::Float(v) => Ok(v
            .present()
            .map(|value| Scalar::Float64(f64::from(value)))
            .unwrap_or(Scalar::Null(NullKind::NaN))),
        StataValue::Double(v) => Ok(v
            .present()
            .map(Scalar::Float64)
            .unwrap_or(Scalar::Null(NullKind::NaN))),
        StataValue::String(text) => Ok(Scalar::Utf8(text.to_string())),
        StataValue::LongStringRef(_) => Err(IoError::Stata(
            "Stata strL values are not supported by this reader slice".to_owned(),
        )),
    }
}

fn stata_error<E: std::fmt::Display>(err: E) -> IoError {
    IoError::Stata(err.to_string())
}

/// Parse a DataFrame from a row-oriented XML document string.
///
/// Matches the writer-oriented subset accepted by `pd.read_xml(...,
/// parser="etree")`: each row is an element named by
/// [`XmlReadOptions::row_name`], and each direct child element becomes a
/// DataFrame column. Attributes, XPath, namespaces, and nested field elements
/// are intentionally out of scope for this slice.
pub fn read_xml_str(input: &str) -> Result<DataFrame, IoError> {
    read_xml_str_with_options(input, &XmlReadOptions::default())
}

/// Parse a DataFrame from a row-oriented XML document string with options.
pub fn read_xml_str_with_options(
    input: &str,
    options: &XmlReadOptions,
) -> Result<DataFrame, IoError> {
    validate_xml_element_name(&options.row_name)?;

    let mut reader = XmlReader::from_str(input);
    reader.config_mut().trim_text(false);
    let mut buf = Vec::new();
    let mut rows: Vec<BTreeMap<String, Scalar>> = Vec::new();
    let mut column_order = Vec::new();
    let mut seen_columns = HashSet::new();
    let mut current_row: Option<BTreeMap<String, Scalar>> = None;
    let mut current_field: Option<String> = None;
    let mut field_text = String::new();
    let mut xml_version = XmlVersion::Implicit1_0;

    loop {
        match reader
            .read_event_into(&mut buf)
            .map_err(|err| IoError::Xml(err.to_string()))?
        {
            Event::Start(event) => {
                let name = xml_event_name(event.name())?;
                if current_row.is_none() {
                    if name == options.row_name {
                        current_row = Some(BTreeMap::new());
                    }
                } else if let Some(field_name) = &current_field {
                    return Err(IoError::Xml(format!(
                        "nested xml element '{name}' inside field '{field_name}' is unsupported"
                    )));
                } else {
                    current_field = Some(name);
                    field_text.clear();
                }
            }
            Event::Empty(event) => {
                let name = xml_event_name(event.name())?;
                if let Some(field_name) = &current_field {
                    return Err(IoError::Xml(format!(
                        "nested xml element '{name}' inside field '{field_name}' is unsupported"
                    )));
                }
                if let Some(row) = current_row.as_mut() {
                    insert_xml_field(
                        row,
                        &mut column_order,
                        &mut seen_columns,
                        name,
                        Scalar::Null(NullKind::Null),
                    )?;
                } else if name == options.row_name {
                    rows.push(BTreeMap::new());
                }
            }
            Event::Text(event) => {
                if current_field.is_some() {
                    let decoded = event
                        .xml_content(xml_version)
                        .map_err(|err| IoError::Xml(err.to_string()))?;
                    field_text.push_str(&decoded);
                }
            }
            Event::CData(event) => {
                if current_field.is_some() {
                    let decoded = event
                        .xml_content(xml_version)
                        .map_err(|err| IoError::Xml(err.to_string()))?;
                    field_text.push_str(&decoded);
                }
            }
            Event::End(event) => {
                let name = xml_event_name(event.name())?;
                if let Some(field_name) = current_field.as_ref() {
                    if name != *field_name {
                        return Err(IoError::Xml(format!(
                            "xml field '{field_name}' closed by mismatched element '{name}'"
                        )));
                    }
                    let field_name = current_field.take().expect("field checked");
                    let value = parse_scalar(&field_text);
                    field_text.clear();
                    let row = current_row
                        .as_mut()
                        .ok_or_else(|| IoError::Xml("xml field outside row".to_owned()))?;
                    insert_xml_field(row, &mut column_order, &mut seen_columns, field_name, value)?;
                } else if name == options.row_name {
                    let row = current_row.take().ok_or_else(|| {
                        IoError::Xml("xml row closed before it opened".to_owned())
                    })?;
                    rows.push(row);
                }
            }
            Event::GeneralRef(reference) => {
                if current_field.is_some() {
                    field_text.push_str(&decode_xml_general_ref(reference)?);
                }
            }
            Event::Eof => break,
            Event::Decl(decl) => {
                if let Ok(v) = decl.version() {
                    xml_version = match v.as_ref() {
                        b"1.0" => XmlVersion::Explicit1_0,
                        b"1.1" => XmlVersion::Explicit1_1,
                        _ => xml_version,
                    };
                }
            }
            Event::PI(_) | Event::DocType(_) | Event::Comment(_) => {}
        }
        buf.clear();
    }

    if current_field.is_some() || current_row.is_some() {
        return Err(IoError::Xml(
            "xml document ended inside an open row or field".to_owned(),
        ));
    }
    if rows.is_empty() {
        return Err(IoError::Xml(
            "xml input contains no row elements".to_owned(),
        ));
    }

    let mut out_columns = BTreeMap::new();
    for name in &column_order {
        let values = rows
            .iter()
            .map(|row| {
                row.get(name)
                    .cloned()
                    .unwrap_or(Scalar::Null(NullKind::Null))
            })
            .collect::<Vec<_>>();
        out_columns.insert(name.clone(), Column::from_values(values)?);
    }
    let index = Index::from_i64((0..rows.len() as i64).collect());
    Ok(DataFrame::new_with_column_order(
        index,
        out_columns,
        column_order,
    )?)
}

/// Serialize a DataFrame to an XML document string.
pub fn write_xml_string_with_options(
    frame: &DataFrame,
    options: &XmlWriteOptions,
) -> Result<String, IoError> {
    if options.include_index && frame.row_multiindex().is_some() {
        let materialized = materialize_named_row_multiindex_columns(frame)?;
        let mut nested_options = options.clone();
        nested_options.include_index = false;
        nested_options.index_label = None;
        return write_xml_string_with_options(&materialized, &nested_options);
    }

    validate_xml_element_name(&options.root_name)?;
    validate_xml_element_name(&options.row_name)?;

    let headers = frame
        .column_names()
        .into_iter()
        .cloned()
        .collect::<Vec<_>>();
    for name in &headers {
        validate_xml_element_name(name)?;
    }

    let index_label = options
        .index_label
        .clone()
        .or_else(|| frame.index().name().map(ToOwned::to_owned))
        .unwrap_or_else(|| "index".to_owned());
    if options.include_index {
        validate_xml_element_name(&index_label)?;
    }

    let mut out = String::new();
    out.push_str("<?xml version=\"1.0\" encoding=\"utf-8\"?>\n");
    out.push('<');
    out.push_str(&options.root_name);
    out.push_str(">\n");

    for row_idx in 0..frame.index().len() {
        out.push_str("  <");
        out.push_str(&options.row_name);
        out.push_str(">\n");

        if options.include_index {
            let value = index_label_string(frame, row_idx)?;
            push_xml_field(&mut out, &index_label, Some(&value));
        }

        for name in &headers {
            let value = frame
                .column(name)
                .and_then(|column| column.value(row_idx))
                .and_then(scalar_to_xml_value);
            push_xml_field(&mut out, name, value.as_deref());
        }

        out.push_str("  </");
        out.push_str(&options.row_name);
        out.push_str(">\n");
    }

    out.push_str("</");
    out.push_str(&options.root_name);
    out.push_str(">\n");
    Ok(out)
}

fn xml_event_name(name: quick_xml::name::QName<'_>) -> Result<String, IoError> {
    std::str::from_utf8(name.as_ref())
        .map(ToOwned::to_owned)
        .map_err(|err| IoError::Xml(format!("invalid utf-8 xml element name: {err}")))
}

fn decode_xml_general_ref(reference: quick_xml::events::BytesRef<'_>) -> Result<String, IoError> {
    let raw = std::str::from_utf8(reference.as_ref())
        .map_err(|err| IoError::Xml(format!("invalid utf-8 xml entity reference: {err}")))?;
    match raw {
        "amp" => Ok("&".to_owned()),
        "lt" => Ok("<".to_owned()),
        "gt" => Ok(">".to_owned()),
        "quot" => Ok("\"".to_owned()),
        "apos" => Ok("'".to_owned()),
        _ if raw.starts_with("#x") => {
            let value = u32::from_str_radix(&raw[2..], 16)
                .map_err(|err| IoError::Xml(format!("invalid hex xml entity '&{raw};': {err}")))?;
            char::from_u32(value)
                .map(|ch| ch.to_string())
                .ok_or_else(|| IoError::Xml(format!("invalid unicode xml entity '&{raw};'")))
        }
        _ if raw.starts_with('#') => {
            let value = raw[1..].parse::<u32>().map_err(|err| {
                IoError::Xml(format!("invalid decimal xml entity '&{raw};': {err}"))
            })?;
            char::from_u32(value)
                .map(|ch| ch.to_string())
                .ok_or_else(|| IoError::Xml(format!("invalid unicode xml entity '&{raw};'")))
        }
        _ => Err(IoError::Xml(format!(
            "unsupported xml entity reference '&{raw};'"
        ))),
    }
}

fn insert_xml_field(
    row: &mut BTreeMap<String, Scalar>,
    column_order: &mut Vec<String>,
    seen_columns: &mut HashSet<String>,
    name: String,
    value: Scalar,
) -> Result<(), IoError> {
    if row.insert(name.clone(), value).is_some() {
        return Err(IoError::Xml(format!("duplicate xml field '{name}' in row")));
    }
    if seen_columns.insert(name.clone()) {
        column_order.push(name);
    }
    Ok(())
}

fn validate_xml_element_name(name: &str) -> Result<(), IoError> {
    let mut chars = name.chars();
    let Some(first) = chars.next() else {
        return Err(IoError::Xml(
            "xml element name must be non-empty".to_owned(),
        ));
    };
    let valid_first = first == '_' || first.is_ascii_alphabetic();
    let valid_rest =
        chars.all(|ch| ch == '_' || ch == '-' || ch == '.' || ch.is_ascii_alphanumeric());
    if valid_first && valid_rest {
        Ok(())
    } else {
        Err(IoError::Xml(format!("invalid xml element name '{name}'")))
    }
}

fn push_xml_field(out: &mut String, name: &str, value: Option<&str>) {
    out.push_str("    <");
    out.push_str(name);
    match value {
        Some(value) => {
            out.push('>');
            out.push_str(&escape_xml_text(value));
            out.push_str("</");
            out.push_str(name);
            out.push_str(">\n");
        }
        None => out.push_str("/>\n"),
    }
}

fn escape_xml_text(value: &str) -> String {
    let mut escaped = String::with_capacity(value.len());
    let mut chars = value.chars().peekable();
    while let Some(ch) = chars.next() {
        match ch {
            '&' => escaped.push_str("&amp;"),
            '<' => escaped.push_str("&lt;"),
            '>' => escaped.push_str("&gt;"),
            '\r' => {
                escaped.push('\n');
                if chars.peek() == Some(&'\n') {
                    chars.next();
                }
            }
            _ => escaped.push(ch),
        }
    }
    escaped
}

fn scalar_to_xml_value(scalar: &Scalar) -> Option<String> {
    match scalar {
        Scalar::Null(_) => None,
        Scalar::Bool(value) => Some(if *value { "True" } else { "False" }.to_owned()),
        Scalar::Int64(value) => Some(value.to_string()),
        Scalar::Float64(value) => {
            if value.is_nan() {
                None
            } else if value.is_finite() && *value == value.round() && value.abs() < 1e15 {
                Some(format!("{value:.1}"))
            } else {
                Some(value.to_string())
            }
        }
        Scalar::Utf8(value) => Some(value.clone()),
        Scalar::Timedelta64(value) => {
            if *value == Timedelta::NAT {
                None
            } else {
                Some(Timedelta::format(*value))
            }
        }
        Scalar::Datetime64(value) => {
            if *value == Timestamp::NAT {
                None
            } else {
                Some(format_datetime_ns(*value))
            }
        }
        Scalar::Period(value) => {
            if *value == i64::MIN {
                None
            } else {
                Some(format!("Period[{value}]"))
            }
        }
        Scalar::Interval(iv) => Some(format!("{iv}")),
    }
}

fn html_selector(pattern: &str) -> Result<Selector, IoError> {
    Selector::parse(pattern).map_err(|err| {
        IoError::Html(format!(
            "invalid built-in html selector {pattern:?}: {err:?}"
        ))
    })
}

fn html_row_cells(row: ElementRef<'_>, cell_selector: &Selector) -> Vec<String> {
    row.select(cell_selector)
        .map(|cell| cell.text().collect::<String>().trim().to_owned())
        .collect()
}

fn normalize_html_headers(raw_headers: &[String]) -> Result<Vec<String>, IoError> {
    if raw_headers.is_empty() {
        return Err(IoError::Html(
            "html table header row contains no cells".to_owned(),
        ));
    }

    let mut seen = HashSet::new();
    let mut headers = Vec::with_capacity(raw_headers.len());
    for (idx, raw) in raw_headers.iter().enumerate() {
        let name = if raw.trim().is_empty() {
            format!("Unnamed: {idx}")
        } else {
            raw.trim().to_owned()
        };
        if !seen.insert(name.clone()) {
            return Err(IoError::DuplicateColumnName(name));
        }
        headers.push(name);
    }
    Ok(headers)
}

fn html_rows_to_frame(
    column_order: Vec<String>,
    rows: Vec<Vec<String>>,
) -> Result<DataFrame, IoError> {
    let width = column_order.len();
    if width == 0 {
        return Err(IoError::Html(
            "html table must contain at least one column".to_owned(),
        ));
    }

    let mut values_by_column = column_order
        .iter()
        .map(|name| (name.clone(), Vec::with_capacity(rows.len())))
        .collect::<BTreeMap<_, _>>();
    for (row_idx, row) in rows.iter().enumerate() {
        if row.len() > width {
            return Err(IoError::Html(format!(
                "html row {row_idx} has {} cells but header has {width}",
                row.len()
            )));
        }
        for (col_idx, name) in column_order.iter().enumerate() {
            let value = row
                .get(col_idx)
                .map_or(Scalar::Null(NullKind::Null), |cell| parse_scalar(cell));
            let column_values = values_by_column.get_mut(name).ok_or_else(|| {
                IoError::Html(format!("html column '{name}' was not initialized"))
            })?;
            column_values.push(value);
        }
    }

    let mut columns = BTreeMap::new();
    for name in &column_order {
        let values = values_by_column
            .remove(name)
            .ok_or_else(|| IoError::Html(format!("html column '{name}' has no values")))?;
        columns.insert(name.clone(), Column::from_values(values)?);
    }
    let row_count = i64::try_from(rows.len()).map_err(|_| {
        IoError::Html(format!(
            "html table row count {} exceeds supported i64 index range",
            rows.len()
        ))
    })?;
    Ok(DataFrame::new_with_column_order(
        Index::from_i64((0..row_count).collect()),
        columns,
        column_order,
    )?)
}

fn resolve_csv_index_header(frame: &DataFrame, options: &CsvWriteOptions) -> String {
    options
        .index_label
        .clone()
        .or_else(|| frame.index().name().map(ToOwned::to_owned))
        .unwrap_or_default()
}

fn resolve_table_index_header(frame: &DataFrame, index_label: Option<&str>) -> String {
    index_label
        .map(ToOwned::to_owned)
        .or_else(|| frame.index().name().map(ToOwned::to_owned))
        .unwrap_or_default()
}

fn index_label_string(frame: &DataFrame, row_idx: usize) -> Result<String, IoError> {
    frame
        .index()
        .labels()
        .get(row_idx)
        .map(ToString::to_string)
        .ok_or_else(|| {
            IoError::Frame(FrameError::CompatibilityRejected(format!(
                "index position {row_idx} out of bounds for index length {}",
                frame.index().len()
            )))
        })
}

/// Derive the column-uniform `to_csv` datetime spec for a DatetimeIndex.
///
/// Returns `None` unless every label is `Datetime64` (a homogeneous datetime
/// index), so non-datetime / mixed indexes keep their default rendering.
fn index_datetime_csv_format(frame: &DataFrame) -> Option<DatetimeCsvFormat> {
    let labels = frame.index().labels();
    let mut any_datetime = false;
    let mut date_only = true;
    let mut subsec_digits = 0u8;
    for label in labels {
        let IndexLabel::Datetime64(ns) = label else {
            return None;
        };
        any_datetime = true;
        if *ns == i64::MIN {
            continue; // NaT
        }
        let subsec = (ns.rem_euclid(1_000_000_000)) as u32;
        if ns.div_euclid(1_000_000_000).rem_euclid(86_400) != 0 || subsec != 0 {
            date_only = false;
        }
        if subsec != 0 {
            let digits = if !subsec.is_multiple_of(1_000) {
                9
            } else if !subsec.is_multiple_of(1_000_000) {
                6
            } else {
                3
            };
            subsec_digits = subsec_digits.max(digits);
        }
    }
    any_datetime.then_some(DatetimeCsvFormat {
        date_only,
        subsec_digits,
    })
}

/// CSV index-cell formatter: applies a DatetimeIndex's column-uniform spec when
/// present, otherwise identical to `index_label_string`.
fn index_label_csv_string(
    frame: &DataFrame,
    row_idx: usize,
    dt_format: Option<DatetimeCsvFormat>,
) -> Result<String, IoError> {
    if let Some(fmt) = dt_format
        && let Some(IndexLabel::Datetime64(ns)) = frame.index().labels().get(row_idx)
        && *ns != i64::MIN
    {
        return Ok(format_datetime_csv(*ns, fmt));
    }
    index_label_string(frame, row_idx)
}

/// Column-uniform datetime rendering spec for `to_csv`, mirroring pandas.
///
/// pandas chooses one format for the whole datetime column: a date-only
/// `YYYY-MM-DD` when every value falls exactly on midnight, otherwise
/// `YYYY-MM-DD HH:MM:SS` with a fractional-seconds suffix whose width is the
/// column's finest sub-second resolution (3 = ms, 6 = µs, 9 = ns; 0 = none).
#[derive(Clone, Copy)]
struct DatetimeCsvFormat {
    date_only: bool,
    subsec_digits: u8,
}

/// Scan a Datetime64 column and derive its column-uniform `to_csv` format.
fn datetime_csv_format(column: &Column) -> DatetimeCsvFormat {
    let mut date_only = true;
    let mut subsec_digits = 0u8;
    for value in column.values() {
        let Scalar::Datetime64(ns) = value else {
            continue;
        };
        if *ns == Timestamp::NAT {
            continue;
        }
        let subsec = (ns.rem_euclid(1_000_000_000)) as u32;
        // Any non-midnight time-of-day OR any sub-second component forces the
        // full timestamp form for the entire column.
        if ns.div_euclid(1_000_000_000).rem_euclid(86_400) != 0 || subsec != 0 {
            date_only = false;
        }
        if subsec != 0 {
            let digits = if !subsec.is_multiple_of(1_000) {
                9
            } else if !subsec.is_multiple_of(1_000_000) {
                6
            } else {
                3
            };
            subsec_digits = subsec_digits.max(digits);
        }
    }
    DatetimeCsvFormat {
        date_only,
        subsec_digits,
    }
}

/// Format one datetime (ns since epoch) under a column's `to_csv` spec.
fn format_datetime_csv(nanos: i64, fmt: DatetimeCsvFormat) -> String {
    // format_datetime_ns yields "YYYY-MM-DD HH:MM:SS" (ASCII, 19 chars for the
    // i64-ns datetime range, year always 4 digits). Trim or extend per spec.
    let base = format_datetime_ns(nanos);
    if fmt.date_only {
        return base[..10].to_owned();
    }
    if fmt.subsec_digits == 0 {
        return base;
    }
    let subsec = (nanos.rem_euclid(1_000_000_000)) as u32;
    let frac = subsec / 10u32.pow(9 - u32::from(fmt.subsec_digits));
    format!(
        "{base}.{frac:0>width$}",
        width = usize::from(fmt.subsec_digits)
    )
}

fn scalar_to_csv_with_na(scalar: &Scalar, na_rep: &str) -> String {
    match scalar {
        Scalar::Null(_) => na_rep.to_owned(),
        Scalar::Float64(v) if v.is_nan() => na_rep.to_owned(),
        // pandas to_csv renders floats via Python str(float): whole numbers keep
        // ".0" ("1.0", not "1") and extreme magnitudes use signed two-digit
        // scientific notation. The table writers (latex/markdown/html) use the
        // separate scalar_to_table_with_na path and keep their own formatting.
        Scalar::Float64(v) => format_pandas_float(*v),
        Scalar::Timedelta64(v) if *v == Timedelta::NAT => na_rep.to_owned(),
        other => scalar_to_csv(other),
    }
}

/// CSV cell formatter that applies a column's datetime spec when present;
/// otherwise identical to `scalar_to_csv_with_na`.
fn scalar_to_csv_cell(
    scalar: &Scalar,
    na_rep: &str,
    dt_format: Option<DatetimeCsvFormat>,
) -> String {
    if let (Scalar::Datetime64(ns), Some(fmt)) = (scalar, dt_format) {
        if *ns == Timestamp::NAT {
            return na_rep.to_owned();
        }
        return format_datetime_csv(*ns, fmt);
    }
    scalar_to_csv_with_na(scalar, na_rep)
}

fn scalar_to_table_with_na(scalar: &Scalar, na_rep: &str) -> String {
    match scalar {
        Scalar::Null(_) => na_rep.to_owned(),
        Scalar::Float64(v) if v.is_nan() => na_rep.to_owned(),
        Scalar::Timedelta64(v) if *v == Timedelta::NAT => na_rep.to_owned(),
        other => scalar_to_csv(other),
    }
}

/// LaTeX cell formatter. pandas `to_latex` renders floats with its default
/// `float_format` of six decimal places (`1.0` -> "1.000000", `0.1234567` ->
/// "0.123457"), unlike the str(float) form used by to_csv/to_html. Integers and
/// other scalars keep the shared table formatting. Verified vs pandas 2.2.3.
fn scalar_to_latex_cell(scalar: &Scalar, na_rep: &str) -> String {
    match scalar {
        Scalar::Float64(v) if v.is_nan() => na_rep.to_owned(),
        // Rust `{:.6}` matches Python `%.6f` (round-half-to-even) and renders
        // infinities as "inf"/"-inf", exactly as pandas to_latex does.
        Scalar::Float64(v) => format!("{v:.6}"),
        other => scalar_to_table_with_na(other, na_rep),
    }
}

fn push_markdown_row(out: &mut String, cells: &[String]) {
    out.push('|');
    for cell in cells {
        out.push(' ');
        out.push_str(&escape_markdown_table_cell(cell));
        out.push_str(" |");
    }
    out.push('\n');
}

fn escape_markdown_table_cell(value: &str) -> String {
    let mut escaped = String::with_capacity(value.len());
    for ch in value.chars() {
        match ch {
            '\\' => escaped.push_str("\\\\"),
            '|' => escaped.push_str("\\|"),
            '\n' | '\r' => escaped.push(' '),
            _ => escaped.push(ch),
        }
    }
    escaped
}

fn push_latex_row(out: &mut String, cells: &[String], escape: bool) {
    for (idx, cell) in cells.iter().enumerate() {
        if idx > 0 {
            out.push_str(" & ");
        }
        if escape {
            out.push_str(&escape_latex_table_cell(cell));
        } else {
            out.push_str(cell);
        }
    }
    out.push_str(" \\\\\n");
}

fn escape_latex_table_cell(value: &str) -> String {
    let mut escaped = String::with_capacity(value.len());
    for ch in value.chars() {
        match ch {
            '&' => escaped.push_str("\\&"),
            '%' => escaped.push_str("\\%"),
            '$' => escaped.push_str("\\$"),
            '#' => escaped.push_str("\\#"),
            '_' => escaped.push_str("\\_"),
            '{' => escaped.push_str("\\{"),
            '}' => escaped.push_str("\\}"),
            '~' => escaped.push_str("\\textasciitilde{}"),
            '^' => escaped.push_str("\\textasciicircum{}"),
            '\\' => escaped.push_str("\\textbackslash{}"),
            '\n' | '\r' => escaped.push(' '),
            _ => escaped.push(ch),
        }
    }
    escaped
}

fn is_pandas_default_na(s: &str) -> bool {
    // Default NA values recognized by pandas read_csv.
    // See: <https://pandas.pydata.org/docs/reference/api/pandas.read_csv.html>
    matches!(
        s,
        "" | "#N/A"
            | "#N/A N/A"
            | "#NA"
            | "-1.#IND"
            | "-1.#QNAN"
            | "-NaN"
            | "-nan"
            | "1.#IND"
            | "1.#QNAN"
            | "<NA>"
            | "N/A"
            | "NA"
            | "NULL"
            | "NaN"
            | "None"
            | "n/a"
            | "nan"
            | "null"
    )
}

fn parse_scalar(field: &str) -> Scalar {
    // pandas read_csv tolerates surrounding whitespace ONLY for numeric
    // inference. NA markers and booleans must match the field EXACTLY (a
    // padded " NA " or "true " is NOT null/bool), and plain strings keep their
    // original whitespace. Verified vs live pandas 2.2.3: " abc " stays
    // " abc "; "true " / " NA " stay strings; but " 1 " parses to Int64(1).
    if is_pandas_default_na(field) {
        return Scalar::Null(NullKind::Null);
    }

    let trimmed = field.trim();
    if let Ok(value) = trimmed.parse::<i64>() {
        return Scalar::Int64(value);
    }
    if let Ok(value) = trimmed.parse::<f64>() {
        return Scalar::Float64(value);
    }
    if field.eq_ignore_ascii_case("true") {
        return Scalar::Bool(true);
    }
    if field.eq_ignore_ascii_case("false") {
        return Scalar::Bool(false);
    }

    Scalar::Utf8(field.to_owned())
}

/// Format an f64 the way pandas `to_csv` does (Python `str(float)`): keep a
/// trailing ".0" on whole numbers ("1.0", not Rust Display's "1"), shortest
/// round-trip for decimals, and signed two-digit scientific notation
/// ("1e+16" / "1e-05") for very large / small magnitudes. Verified vs live
/// pandas 2.2.3. NaN must be handled by the caller (it becomes na_rep).
fn format_pandas_float(v: f64) -> String {
    // Rust's Debug formatter gives the shortest round-trip representation and,
    // unlike Display, keeps ".0" on whole numbers and switches to scientific
    // notation at Python's repr boundaries. Only the exponent spelling differs
    // (Rust "1e16"/"1e-5" vs Python "1e+16"/"1e-05"), so normalize that.
    let s = format!("{v:?}");
    match s.split_once('e') {
        None => s,
        Some((mantissa, exp)) => {
            let (sign, digits) = match exp.strip_prefix('-') {
                Some(d) => ('-', d),
                None => ('+', exp.strip_prefix('+').unwrap_or(exp)),
            };
            format!("{mantissa}e{sign}{digits:0>2}")
        }
    }
}

fn scalar_to_csv(scalar: &Scalar) -> String {
    match scalar {
        Scalar::Null(_) => String::new(),
        // pandas to_csv writes capitalized True/False (matches fp-frame::to_csv).
        Scalar::Bool(v) => if *v { "True" } else { "False" }.to_string(),
        Scalar::Int64(v) => v.to_string(),
        Scalar::Float64(v) => {
            if v.is_nan() {
                String::new()
            } else {
                v.to_string()
            }
        }
        Scalar::Utf8(v) => v.clone(),
        Scalar::Timedelta64(v) => {
            if *v == Timedelta::NAT {
                String::new()
            } else {
                Timedelta::format(*v)
            }
        }
        Scalar::Datetime64(v) => {
            if *v == Timestamp::NAT {
                String::new()
            } else {
                format_datetime_ns(*v)
            }
        }
        Scalar::Period(v) => {
            if *v == i64::MIN {
                String::new()
            } else {
                format!("Period[{v}]")
            }
        }
        Scalar::Interval(iv) => format!("{iv}"),
    }
}

/// Parse a field with NA value handling respecting pandas options.
///
/// - `na_filter`: If false, skip NA detection entirely for performance
/// - `keep_default_na`: If true, use pandas default NA values
/// - `na_set` / `true_set` / `false_set`: Pre-built HashSets for O(1)
///   membership lookup. Per br-frankenpandas-b67a3 (sister to br-fcf5d),
///   these were previously `&[String]` slices scanned linearly per cell;
///   now built once at the parent CSV reader and passed in.
#[allow(clippy::too_many_arguments)]
fn parse_scalar_with_options(
    field: &str,
    na_filter: bool,
    keep_default_na: bool,
    na_set: &HashSet<&str>,
    true_set: &HashSet<&str>,
    false_set: &HashSet<&str>,
    decimal: u8,
    thousands: Option<u8>,
) -> Scalar {
    // pandas only tolerates surrounding whitespace for NUMERIC inference; NA
    // markers, booleans, and plain strings match/keep the field EXACTLY (a
    // padded " NA " or "true " stays a string). See parse_scalar.
    let trimmed = field.trim();

    // Check NA values only if na_filter is enabled
    if na_filter {
        let is_default_na = keep_default_na && is_pandas_default_na(field);
        let is_custom_na = na_set.contains(field);
        if is_default_na || is_custom_na {
            return Scalar::Null(NullKind::Null);
        }
    }

    // `thousands` is silently ignored if it equals the decimal separator,
    // matching pandas semantics.
    let thousands_effective = thousands.filter(|t| *t != decimal);
    let numeric_candidate: Cow<'_, str> = if let Some(t) = thousands_effective {
        let ch = char::from(t);
        if trimmed.contains(ch) {
            Cow::Owned(trimmed.replace(ch, ""))
        } else {
            Cow::Borrowed(trimmed)
        }
    } else {
        Cow::Borrowed(trimmed)
    };

    if let Ok(value) = numeric_candidate.as_ref().parse::<i64>() {
        return Scalar::Int64(value);
    }

    let decimal_ch = char::from(decimal);
    let float_candidate: Cow<'_, str> = if decimal == b'.' {
        Cow::Borrowed(numeric_candidate.as_ref())
    } else if numeric_candidate.contains(decimal_ch) {
        Cow::Owned(numeric_candidate.replace(decimal_ch, "."))
    } else {
        Cow::Borrowed(numeric_candidate.as_ref())
    };
    if let Ok(value) = float_candidate.as_ref().parse::<f64>() {
        return Scalar::Float64(value);
    }

    if true_set.contains(field) {
        return Scalar::Bool(true);
    }
    if false_set.contains(field) {
        return Scalar::Bool(false);
    }

    if field.eq_ignore_ascii_case("true") {
        return Scalar::Bool(true);
    }
    if field.eq_ignore_ascii_case("false") {
        return Scalar::Bool(false);
    }
    Scalar::Utf8(field.to_owned())
}

fn reject_duplicate_headers(headers: &[String]) -> Result<(), IoError> {
    let mut used = BTreeSet::new();
    for name in headers {
        if !used.insert(name.clone()) {
            return Err(IoError::DuplicateColumnName(name.clone()));
        }
    }
    Ok(())
}

fn validate_usecols(headers: &[String], usecols: &[String]) -> Result<(), IoError> {
    let header_set: std::collections::BTreeSet<&String> = headers.iter().collect();
    let mut missing = Vec::new();
    for name in usecols {
        if !header_set.contains(name) {
            missing.push(name.clone());
        }
    }
    if missing.is_empty() {
        Ok(())
    } else {
        Err(IoError::MissingUsecols(missing))
    }
}

fn validate_parse_dates(headers: &[String], parse_dates: &[String]) -> Result<(), IoError> {
    let header_set: std::collections::BTreeSet<&String> = headers.iter().collect();
    let mut missing = Vec::new();
    for name in parse_dates {
        if !header_set.contains(name) {
            missing.push(name.clone());
        }
    }
    if missing.is_empty() {
        Ok(())
    } else {
        Err(IoError::MissingParseDateColumns(missing))
    }
}

fn validate_parse_date_combinations(
    headers: &[String],
    parse_date_combinations: &[Vec<String>],
) -> Result<(), IoError> {
    let header_set: std::collections::BTreeSet<&String> = headers.iter().collect();
    let mut missing = BTreeSet::new();
    for combo in parse_date_combinations {
        for name in combo {
            if !header_set.contains(name) {
                missing.insert(name.clone());
            }
        }
    }
    if missing.is_empty() {
        Ok(())
    } else {
        Err(IoError::MissingParseDateColumns(
            missing.into_iter().collect(),
        ))
    }
}

fn apply_parse_dates(
    headers: &[String],
    columns: &mut [Vec<Scalar>],
    parse_dates: &[String],
) -> Result<(), IoError> {
    if parse_dates.is_empty() {
        return Ok(());
    }

    validate_parse_dates(headers, parse_dates)?;

    for column_name in parse_dates {
        let Some(column_idx) = headers.iter().position(|header| header == column_name) else {
            continue;
        };

        let index_labels = (0..columns[column_idx].len() as i64)
            .map(IndexLabel::Int64)
            .collect::<Vec<_>>();
        let series = Series::from_values(
            column_name.clone(),
            index_labels,
            columns[column_idx].clone(),
        )?;
        if let Some(parsed) = parse_csv_datetime_column(&series)? {
            columns[column_idx] = parsed.values().to_vec();
        }
    }

    Ok(())
}

fn parse_sql_float_text(text: &str) -> Option<f64> {
    let trimmed = text.trim();
    if trimmed.is_empty() {
        return None;
    }

    let mut normalized = String::with_capacity(trimmed.len());
    for ch in trimmed.chars() {
        match ch {
            ',' => {}
            '$' if normalized.is_empty() || normalized == "+" || normalized == "-" => {}
            _ => normalized.push(ch),
        }
    }

    if matches!(normalized.as_str(), "" | "+" | "-" | ".") {
        return None;
    }

    let value = normalized.parse::<f64>().ok()?;
    value.is_finite().then_some(value)
}

fn apply_sql_coerce_float(columns: &mut [Vec<Scalar>]) {
    for column in columns {
        let mut saw_text_float = false;
        let mut parsed_values = Vec::with_capacity(column.len());

        for value in column.iter() {
            match value {
                Scalar::Utf8(text) => {
                    let Some(parsed) = parse_sql_float_text(text) else {
                        saw_text_float = false;
                        parsed_values.clear();
                        break;
                    };
                    saw_text_float = true;
                    parsed_values.push(Some(parsed));
                }
                Scalar::Null(_) | Scalar::Int64(_) | Scalar::Float64(_) => {
                    parsed_values.push(None);
                }
                Scalar::Bool(_)
                | Scalar::Timedelta64(_)
                | Scalar::Datetime64(_)
                | Scalar::Period(_)
                | Scalar::Interval(_) => {
                    saw_text_float = false;
                    parsed_values.clear();
                    break;
                }
            }
        }

        if !saw_text_float {
            continue;
        }

        for (value, parsed) in column.iter_mut().zip(parsed_values) {
            if let Some(parsed) = parsed {
                *value = Scalar::Float64(parsed);
            }
        }
    }
}

fn combine_parse_date_values(column_group: &[Vec<Scalar>]) -> Vec<Scalar> {
    let len = column_group.first().map_or(0, Vec::len);
    let mut combined = Vec::with_capacity(len);

    for row in 0..len {
        if column_group
            .iter()
            .any(|column| matches!(column[row], Scalar::Null(_)))
        {
            combined.push(Scalar::Null(NullKind::NaT));
            continue;
        }

        let joined = column_group
            .iter()
            .map(|column| match &column[row] {
                Scalar::Utf8(value) => value.clone(),
                other => other.to_string(),
            })
            .collect::<Vec<_>>()
            .join(" ");
        combined.push(Scalar::Utf8(joined));
    }

    combined
}

fn apply_one_parse_date_combination(
    headers: &mut Vec<String>,
    columns: &mut Vec<Vec<Scalar>>,
    combined_name: String,
    sources: &[String],
) -> Result<(), IoError> {
    let mut positions = sources
        .iter()
        .map(|name| {
            headers
                .iter()
                .position(|header| header == name)
                .ok_or_else(|| IoError::MissingParseDateColumns(vec![name.clone()]))
        })
        .collect::<Result<Vec<_>, _>>()?;
    positions.sort_unstable();

    let index_labels = (0..columns[positions[0]].len() as i64)
        .map(IndexLabel::Int64)
        .collect::<Vec<_>>();
    let combined_values = combine_parse_date_values(
        &positions
            .iter()
            .map(|&idx| columns[idx].clone())
            .collect::<Vec<_>>(),
    );
    let combined_series =
        Series::from_values(combined_name.clone(), index_labels, combined_values)?;
    let parsed = parse_csv_datetime_column(&combined_series)?.unwrap_or(combined_series);

    for idx in positions.iter().rev() {
        headers.remove(*idx);
        columns.remove(*idx);
    }
    headers.insert(positions[0], combined_name);
    columns.insert(positions[0], parsed.values().to_vec());
    Ok(())
}

fn parse_csv_datetime_column(series: &Series) -> Result<Option<Series>, IoError> {
    // pandas pd.read_csv(parse_dates=[col]) parses each value on its own —
    // a column with mixed naive ("2024-01-15 10:30:00") and aware
    // ("2024-01-15T10:30:00Z") entries normalizes each value
    // independently. The ToDatetimeOptions default `infer_mixed_timezone:
    // true` locks the column to the FIRST inferred pattern and rejects
    // any value that doesn't match it, which causes parse_failed=true and
    // leaves the column as raw strings even though every individual value
    // is parseable. Set it explicitly to false so each value goes through
    // parse_datetime_string, which already handles both naive and aware.
    let parsed = to_datetime_with_options(
        series,
        ToDatetimeOptions {
            infer_mixed_timezone: false,
            ..ToDatetimeOptions::default()
        },
    )?;
    let parse_failed = series
        .values()
        .iter()
        .zip(parsed.values())
        .any(|(original, parsed)| !original.is_missing() && parsed.is_missing());

    if parse_failed {
        Ok(None)
    } else {
        Ok(Some(parsed))
    }
}

fn pandas_csv_numeric_column_requires_float(values: &[Scalar]) -> bool {
    // DISC-011: Nullable extension Int64 dtype parity.
    // Previously: Int64 columns with nulls promoted to Float64 for CSV output.
    // Now: Int64 columns preserve integer encoding; only promote when the
    // column actually contains Float64 values (mixed Int64/Float64 → Float64).
    let mut saw_int = false;
    let mut saw_float = false;

    for value in values {
        match value {
            Scalar::Int64(_) => saw_int = true,
            Scalar::Float64(_) => saw_float = true,
            Scalar::Null(_) => {}
            Scalar::Bool(_)
            | Scalar::Utf8(_)
            | Scalar::Timedelta64(_)
            | Scalar::Datetime64(_)
            | Scalar::Period(_)
            | Scalar::Interval(_) => {
                return false;
            }
        }
    }

    saw_int && saw_float
}

fn apply_pandas_csv_numeric_promotions(columns: &mut [Vec<Scalar>]) {
    for column in columns {
        if !pandas_csv_numeric_column_requires_float(column) {
            continue;
        }

        for value in column {
            if let Scalar::Int64(v) = value {
                *value = Scalar::Float64(*v as f64);
            }
        }
    }
}

fn apply_parse_date_combinations(
    headers: &mut Vec<String>,
    columns: &mut Vec<Vec<Scalar>>,
    parse_date_combinations: &[Vec<String>],
) -> Result<(), IoError> {
    if parse_date_combinations.is_empty() {
        return Ok(());
    }

    validate_parse_date_combinations(headers, parse_date_combinations)?;

    for combination in parse_date_combinations {
        if combination.is_empty() {
            continue;
        }
        let combined_name = combination.join("_");
        apply_one_parse_date_combination(headers, columns, combined_name, combination)?;
    }

    Ok(())
}

fn apply_parse_date_combinations_named(
    headers: &mut Vec<String>,
    columns: &mut Vec<Vec<Scalar>>,
    parse_date_combinations_named: &[(String, Vec<String>)],
) -> Result<(), IoError> {
    if parse_date_combinations_named.is_empty() {
        return Ok(());
    }

    let mut assigned_names: std::collections::HashSet<String> = std::collections::HashSet::new();
    for (new_name, _) in parse_date_combinations_named {
        if !assigned_names.insert(new_name.clone()) {
            return Err(IoError::DuplicateColumnName(new_name.clone()));
        }
    }

    let combos_only: Vec<Vec<String>> = parse_date_combinations_named
        .iter()
        .map(|(_, sources)| sources.clone())
        .collect();
    validate_parse_date_combinations(headers, &combos_only)?;

    for (new_name, sources) in parse_date_combinations_named {
        if sources.is_empty() {
            continue;
        }
        apply_one_parse_date_combination(headers, columns, new_name.clone(), sources)?;
    }

    Ok(())
}

fn append_csv_record(
    columns: &mut [Vec<Scalar>],
    raw_columns: &mut [Vec<String>],
    record: &StringRecord,
    options: &CsvReadOptions,
    na_set: &HashSet<&str>,
    true_set: &HashSet<&str>,
    false_set: &HashSet<&str>,
) {
    for (idx, col) in columns.iter_mut().enumerate() {
        let field = record.get(idx).unwrap_or_default();
        col.push(parse_scalar_with_options(
            field,
            options.na_filter,
            options.keep_default_na,
            na_set,
            true_set,
            false_set,
            options.decimal,
            options.thousands,
        ));
        // Keep the verbatim field so an object-fallback column can preserve the
        // original literal like pandas (see build_csv_object_aware_column).
        raw_columns[idx].push(field.to_owned());
    }
}

fn should_skip_bad_csv_record(
    record: &StringRecord,
    expected_fields: usize,
    on_bad_lines: CsvOnBadLines,
) -> bool {
    if record.len() <= expected_fields {
        return false;
    }

    match on_bad_lines {
        CsvOnBadLines::Error => false,
        CsvOnBadLines::Warn => {
            eprintln!(
                "Skipping bad CSV line: expected {expected_fields} fields, found {}",
                record.len()
            );
            true
        }
        CsvOnBadLines::Skip => true,
    }
}

// ── CSV with options ───────────────────────────────────────────────────

pub fn read_csv_with_options(input: &str, options: &CsvReadOptions) -> Result<DataFrame, IoError> {
    if csv_read_options_match_default_fast_path(options) {
        return read_csv_str(input);
    }

    if csv_read_options_match_no_na_numeric_fast_path(options) {
        if let Some(frame) = csv_parse_cache_lookup(CsvParseCacheMode::NoNaNumeric, input) {
            return Ok(frame);
        }

        if let Some(frame) = try_read_csv_with_options_no_na_numeric_fast_path(input)? {
            csv_parse_cache_store(CsvParseCacheMode::NoNaNumeric, input, &frame);
            return Ok(frame);
        }
    }

    let mut builder = ReaderBuilder::new();
    builder
        .has_headers(false)
        .delimiter(options.delimiter)
        .quote(options.quotechar)
        .double_quote(options.doublequote)
        .escape(options.escapechar);
    if options.on_bad_lines != CsvOnBadLines::Error {
        builder.flexible(true);
    }
    if let Some(c) = options.comment {
        builder.comment(Some(c));
    }
    if let Some(term) = options.lineterminator {
        builder.terminator(csv::Terminator::Any(term));
    }
    let mut reader = builder.from_reader(input.as_bytes());

    let max_rows = options.nrows.unwrap_or(usize::MAX);
    let skip = options.skiprows;

    let mut records = reader.records();
    for _ in 0..skip {
        if records.next().transpose()?.is_none() {
            return Err(IoError::MissingHeaders);
        }
    }

    // Per br-frankenpandas-b67a3: pre-build NA / true / false sets once,
    // then thread through the per-record loop. Was Vec::iter().any()
    // per cell.
    let na_set: HashSet<&str> = options.na_values.iter().map(String::as_str).collect();
    let true_set: HashSet<&str> = options.true_values.iter().map(String::as_str).collect();
    let false_set: HashSet<&str> = options.false_values.iter().map(String::as_str).collect();

    let mut row_count: i64 = 0;
    // raw_columns shadows columns with each cell's verbatim text so an
    // object-fallback column can preserve original literals (see the final
    // build step and build_csv_object_aware_column).
    let (headers, mut columns, mut raw_columns) = if options.has_headers {
        let headers_record = records.next().transpose()?.ok_or(IoError::MissingHeaders)?;
        if headers_record.is_empty() {
            return Err(IoError::MissingHeaders);
        }

        let header_count = headers_record.len();
        let row_hint = input.len() / (header_count * 8).max(1);
        let columns: Vec<Vec<Scalar>> = (0..header_count)
            .map(|_| Vec::with_capacity(row_hint))
            .collect();
        let raw_columns: Vec<Vec<String>> = (0..header_count)
            .map(|_| Vec::with_capacity(row_hint))
            .collect();

        (
            headers_record
                .iter()
                .map(ToOwned::to_owned)
                .collect::<Vec<_>>(),
            columns,
            raw_columns,
        )
    } else {
        let first_record = records.next().transpose()?.ok_or(IoError::MissingHeaders)?;
        if first_record.is_empty() {
            return Err(IoError::MissingHeaders);
        }

        let header_count = first_record.len();
        let row_hint = input.len() / (header_count * 8).max(1);
        let mut columns: Vec<Vec<Scalar>> = (0..header_count)
            .map(|_| Vec::with_capacity(row_hint))
            .collect();
        let mut raw_columns: Vec<Vec<String>> = (0..header_count)
            .map(|_| Vec::with_capacity(row_hint))
            .collect();

        if (row_count as usize) < max_rows {
            append_csv_record(
                &mut columns,
                &mut raw_columns,
                &first_record,
                options,
                &na_set,
                &true_set,
                &false_set,
            );
            row_count += 1;
        }

        (
            (0..header_count)
                .map(|idx| format!("column_{idx}"))
                .collect(),
            columns,
            raw_columns,
        )
    };

    for row in records {
        if (row_count as usize) >= max_rows {
            break;
        }
        let record = row?;
        if should_skip_bad_csv_record(&record, columns.len(), options.on_bad_lines) {
            continue;
        }
        append_csv_record(
            &mut columns,
            &mut raw_columns,
            &record,
            options,
            &na_set,
            &true_set,
            &false_set,
        );
        row_count += 1;
    }

    // Drop the last `skipfooter` data rows. Matches pandas semantics:
    // footer rows are dropped *after* header parsing and nrows limit.
    if options.skipfooter > 0 && (row_count as usize) > 0 {
        let drop = options.skipfooter.min(row_count as usize);
        for col in columns.iter_mut() {
            let new_len = col.len().saturating_sub(drop);
            col.truncate(new_len);
        }
        for col in raw_columns.iter_mut() {
            let new_len = col.len().saturating_sub(drop);
            col.truncate(new_len);
        }
        row_count -= drop as i64;
    }
    reject_duplicate_headers(&headers)?;
    if let Some(ref usecols) = options.usecols {
        validate_usecols(&headers, usecols)?;
    }

    // Apply usecols filter: keep only selected columns.
    let (mut headers, mut columns, raw_columns) = if let Some(ref usecols) = options.usecols {
        let mut fh = Vec::new();
        let mut fc = Vec::new();
        let mut fr = Vec::new();
        for ((h, c), r) in headers.into_iter().zip(columns).zip(raw_columns) {
            if usecols.contains(&h) {
                fh.push(h);
                fc.push(c);
                fr.push(r);
            }
        }
        (fh, fc, fr)
    } else {
        (headers, columns, raw_columns)
    };

    if let Some(ref parse_date_combinations) = options.parse_date_combinations {
        apply_parse_date_combinations(&mut headers, &mut columns, parse_date_combinations)?;
    }

    if let Some(ref named) = options.parse_date_combinations_named {
        apply_parse_date_combinations_named(&mut headers, &mut columns, named)?;
    }

    if let Some(ref parse_dates) = options.parse_dates {
        apply_parse_dates(&headers, &mut columns, parse_dates)?;
    }

    apply_pandas_csv_numeric_promotions(&mut columns);

    // Apply dtype coercion if specified.
    if let Some(ref dtype_map) = options.dtype {
        for (i, name) in headers.iter().enumerate() {
            if let Some(&target_dt) = dtype_map.get(name) {
                let coerced = columns[i]
                    .iter()
                    .map(|v| fp_types::cast_scalar(v, target_dt))
                    .collect::<Result<Vec<_>, _>>()
                    .map_err(|err| IoError::Column(ColumnError::from(err)))?;
                columns[i] = coerced;
            }
        }
    }

    let header_count = headers.len();

    // Object-fallback columns should keep verbatim source text (pandas parity,
    // see build_csv_object_aware_column). Only safe when no parse-date transform
    // rewrote/added columns (which would desync raw_columns from columns); a
    // per-column dtype override is also excluded so explicit astype wins.
    let preserve_object_text = options.parse_dates.is_none()
        && options.parse_date_combinations.is_none()
        && options.parse_date_combinations_named.is_none();
    let dtype_forced = |name: &str| -> bool {
        options
            .dtype
            .as_ref()
            .is_some_and(|map| map.contains_key(name))
    };

    // If index_col is set, extract that column as the index
    if let Some(ref idx_col_name) = options.index_col {
        let idx_pos = headers
            .iter()
            .position(|h| h == idx_col_name)
            .ok_or_else(|| IoError::MissingIndexColumn(idx_col_name.clone()))?;

        let index_values = columns.remove(idx_pos);
        let index_labels: Vec<fp_index::IndexLabel> = index_values
            .into_iter()
            .map(|s| match s {
                Scalar::Int64(v) => fp_index::IndexLabel::Int64(v),
                Scalar::Utf8(v) => fp_index::IndexLabel::Utf8(v),
                Scalar::Float64(v) => fp_index::IndexLabel::Utf8(v.to_string()),
                Scalar::Bool(v) => {
                    fp_index::IndexLabel::Utf8(if v { "True" } else { "False" }.to_string())
                }
                // Typed null label (br-frankenpandas-8m6ay): pandas
                // read_csv(index_col=...) keeps a real nan index entry for an
                // empty cell. Kind-preserving bijection.
                Scalar::Null(kind) => fp_index::IndexLabel::Null(kind),
                Scalar::Timedelta64(v) => {
                    if v == Timedelta::NAT {
                        fp_index::IndexLabel::Utf8("<NaT>".to_owned())
                    } else {
                        fp_index::IndexLabel::Utf8(Timedelta::format(v))
                    }
                }
                Scalar::Datetime64(v) => {
                    if v == Timestamp::NAT {
                        fp_index::IndexLabel::Utf8("<NaT>".to_owned())
                    } else {
                        fp_index::IndexLabel::Utf8(format_datetime_ns(v))
                    }
                }
                Scalar::Period(v) => {
                    if v == i64::MIN {
                        fp_index::IndexLabel::Utf8("<NaT>".to_owned())
                    } else {
                        fp_index::IndexLabel::Utf8(format!("Period[{v}]"))
                    }
                }
                Scalar::Interval(iv) => fp_index::IndexLabel::Utf8(format!("{iv}")),
            })
            .collect();
        // Per br-frankenpandas-l0vbr: pandas pd.read_csv(index_col='col')
        // sets result.index.name = 'col'.
        let index = Index::new(index_labels).set_name(idx_col_name);

        let mut out_columns = BTreeMap::new();
        let mut column_order = Vec::with_capacity(headers.len() - 1);
        let mut col_idx = 0;
        for (orig_idx, _) in headers.iter().enumerate() {
            if orig_idx == idx_pos {
                continue;
            }
            let name = headers.get(orig_idx).cloned().unwrap_or_default();
            let column = if preserve_object_text && !dtype_forced(&name) {
                build_csv_object_aware_column(columns[col_idx].clone(), &raw_columns[orig_idx])?
            } else {
                Column::from_values(columns[col_idx].clone())?
            };
            out_columns.insert(name.clone(), column);
            column_order.push(name);
            col_idx += 1;
        }
        Ok(DataFrame::new_with_column_order(
            index,
            out_columns,
            column_order,
        )?)
    } else {
        let mut out_columns = BTreeMap::new();
        let mut column_order = Vec::with_capacity(header_count);
        for (idx, values) in columns.into_iter().enumerate() {
            let name = headers.get(idx).cloned().unwrap_or_default();
            let column = if preserve_object_text && !dtype_forced(&name) {
                build_csv_object_aware_column(values, &raw_columns[idx])?
            } else {
                Column::from_values(values)?
            };
            out_columns.insert(name.clone(), column);
            column_order.push(name);
        }
        let index = csv_default_unit_range_index(row_count);
        Ok(DataFrame::new_with_column_order(
            index,
            out_columns,
            column_order,
        )?)
    }
}

/// Read CSV and promote the named columns into a row index / row MultiIndex.
///
/// For multiple names this mirrors pandas `index_col=[...]`.
pub fn read_csv_with_index_cols(
    input: &str,
    options: &CsvReadOptions,
    index_cols: &[&str],
) -> Result<DataFrame, IoError> {
    let frame = read_csv_with_options(input, options)?;
    promote_frame_index_columns(&frame, index_cols)
}

// ── File-based CSV ─────────────────────────────────────────────────────

pub fn read_csv(path: &Path) -> Result<DataFrame, IoError> {
    read_csv_with_options_path(path, &CsvReadOptions::default())
}

pub fn read_csv_with_options_path(
    path: &Path,
    options: &CsvReadOptions,
) -> Result<DataFrame, IoError> {
    let content = std::fs::read_to_string(path)?;
    read_csv_with_options(&content, options)
}

pub fn read_csv_with_index_cols_path(
    path: &Path,
    options: &CsvReadOptions,
    index_cols: &[&str],
) -> Result<DataFrame, IoError> {
    let content = std::fs::read_to_string(path)?;
    read_csv_with_index_cols(&content, options, index_cols)
}

pub fn write_csv(frame: &DataFrame, path: &Path) -> Result<(), IoError> {
    let content = write_csv_string(frame)?;
    std::fs::write(path, content)?;
    Ok(())
}

// ── read_table (tab-separated thin wrapper) ────────────────────────────

/// Parse a tab-separated string, matching `pd.read_table(io.StringIO(s))`.
///
/// Equivalent to [`read_csv_str`] with `delimiter=b'\t'`. Other defaults
/// match pandas `read_table`: `header='infer'`, default NA values, no
/// index column promotion. Use [`read_table_with_options`] for full
/// option control.
pub fn read_table_str(input: &str) -> Result<DataFrame, IoError> {
    let opts = CsvReadOptions {
        delimiter: b'\t',
        ..CsvReadOptions::default()
    };
    read_csv_with_options(input, &opts)
}

/// Parse a tab-separated string with explicit options. The caller-supplied
/// `options.delimiter` is preserved when it differs from the comma default
/// to allow override; otherwise it is forced to `b'\t'` so that the
/// pandas `read_table` semantics survive `CsvReadOptions::default()`.
pub fn read_table_with_options(
    input: &str,
    options: &CsvReadOptions,
) -> Result<DataFrame, IoError> {
    let mut effective = options.clone();
    if effective.delimiter == b',' {
        effective.delimiter = b'\t';
    }
    read_csv_with_options(input, &effective)
}

/// Read a tab-separated file from disk, matching `pd.read_table(path)`.
pub fn read_table(path: &Path) -> Result<DataFrame, IoError> {
    let opts = CsvReadOptions {
        delimiter: b'\t',
        ..CsvReadOptions::default()
    };
    read_csv_with_options_path(path, &opts)
}

/// Read a tab-separated file from disk with explicit options. The
/// caller-supplied delimiter is honored when it has been overridden from
/// the comma default; otherwise it is forced to `b'\t'`.
pub fn read_table_with_options_path(
    path: &Path,
    options: &CsvReadOptions,
) -> Result<DataFrame, IoError> {
    let mut effective = options.clone();
    if effective.delimiter == b',' {
        effective.delimiter = b'\t';
    }
    read_csv_with_options_path(path, &effective)
}

// ── read_fwf (fixed-width file reader) ─────────────────────────────────

/// Read a fixed-width file from disk, matching `pd.read_fwf(path, ...)`.
///
/// See [`read_fwf_str`] for the option semantics. When neither explicit
/// `colspecs` nor `widths` are supplied, column ranges are inferred from
/// non-whitespace runs.
pub fn read_fwf(path: &Path, options: &FwfReadOptions) -> Result<DataFrame, IoError> {
    let content = std::fs::read_to_string(path)?;
    read_fwf_str(&content, options)
}

// ── Deferred reader surfaces ───────────────────────────────────────────
//
// pandas exposes pd.read_clipboard / pd.read_gbq / pd.read_sas / pd.read_spss.
// Each is out of scope for FrankenPandas's local file-format charter:
//
//   * read_clipboard pulls from the OS clipboard (GUI-only, headless-hostile).
//   * read_gbq calls Google BigQuery (external service, GCP credentials).
//   * read_sas / read_spss are proprietary statistical-software formats with
//     no first-party Rust reader at parity (pandas calls into pyreadstat /
//     sas7bdat).
//
// Following the deferral precedent in fp-frame for plotting (see
// `plotting_deferred`), expose typed reject-closed entry points so callers
// can program against the surface and fall through to a clean error rather
// than a missing symbol.

fn deferred_reader_error(method: &str, reason: &str) -> IoError {
    IoError::Deferred(format!(
        "{method}: in scope but deferred; {reason}. Use the pandas surface in the meantime."
    ))
}

fn deferred_writer_error(method: &str, reason: &str) -> IoError {
    IoError::Deferred(format!(
        "{method}: in scope but deferred; {reason}. Use the pandas surface in the meantime."
    ))
}

/// Reject-closed clipboard reader, matching `pd.read_clipboard()` shape.
pub fn read_clipboard() -> Result<DataFrame, IoError> {
    Err(deferred_reader_error(
        "read_clipboard",
        "OS clipboard access requires GUI bindings outside FrankenPandas's headless charter",
    ))
}

/// Reject-closed BigQuery reader, matching `pd.read_gbq(query, project_id)`.
pub fn read_gbq(_query: &str, _project_id: Option<&str>) -> Result<DataFrame, IoError> {
    Err(deferred_reader_error(
        "read_gbq",
        "Google BigQuery integration is outside FrankenPandas's local file-format scope",
    ))
}

/// Reject-closed SAS reader, matching `pd.read_sas(path)`.
pub fn read_sas(_path: &Path) -> Result<DataFrame, IoError> {
    Err(deferred_reader_error(
        "read_sas",
        "no first-party Rust SAS sas7bdat/xport reader exists at pandas-parity yet",
    ))
}

/// Reject-closed SPSS reader, matching `pd.read_spss(path)`.
pub fn read_spss(_path: &Path) -> Result<DataFrame, IoError> {
    Err(deferred_reader_error(
        "read_spss",
        "no first-party Rust SPSS .sav reader exists at pandas-parity yet",
    ))
}

// ── File-based Markdown / LaTeX ────────────────────────────────────────

/// Write a DataFrame to a Markdown table file.
pub fn write_markdown(frame: &DataFrame, path: &Path) -> Result<(), IoError> {
    write_markdown_with_options(frame, path, &MarkdownWriteOptions::default())
}

/// Write a DataFrame to a Markdown table file with explicit options.
pub fn write_markdown_with_options(
    frame: &DataFrame,
    path: &Path,
    options: &MarkdownWriteOptions,
) -> Result<(), IoError> {
    let content = write_markdown_string_with_options(frame, options)?;
    std::fs::write(path, content)?;
    Ok(())
}

/// Write a DataFrame to a LaTeX tabular file.
pub fn write_latex(frame: &DataFrame, path: &Path) -> Result<(), IoError> {
    write_latex_with_options(frame, path, &LatexWriteOptions::default())
}

/// Write a DataFrame to a LaTeX tabular file with explicit options.
pub fn write_latex_with_options(
    frame: &DataFrame,
    path: &Path,
    options: &LatexWriteOptions,
) -> Result<(), IoError> {
    let content = write_latex_string_with_options(frame, options)?;
    std::fs::write(path, content)?;
    Ok(())
}

// ── File-based HTML ────────────────────────────────────────────────────

pub fn read_html(path: &Path) -> Result<DataFrame, IoError> {
    read_html_with_options(path, &HtmlReadOptions::default())
}

pub fn read_html_with_options(
    path: &Path,
    options: &HtmlReadOptions,
) -> Result<DataFrame, IoError> {
    let content = std::fs::read_to_string(path)?;
    read_html_str_with_options(&content, options)
}

pub fn write_html(frame: &DataFrame, path: &Path) -> Result<(), IoError> {
    write_html_with_options(frame, path, &HtmlWriteOptions::default())
}

pub fn write_html_with_options(
    frame: &DataFrame,
    path: &Path,
    options: &HtmlWriteOptions,
) -> Result<(), IoError> {
    let content = write_html_string_with_options(frame, options)?;
    std::fs::write(path, content)?;
    Ok(())
}

// ── File-based XML ─────────────────────────────────────────────────────

pub fn write_xml(frame: &DataFrame, path: &Path) -> Result<(), IoError> {
    write_xml_with_options(frame, path, &XmlWriteOptions::default())
}

pub fn write_xml_with_options(
    frame: &DataFrame,
    path: &Path,
    options: &XmlWriteOptions,
) -> Result<(), IoError> {
    let content = write_xml_string_with_options(frame, options)?;
    std::fs::write(path, content)?;
    Ok(())
}

// ── File-based XML readers ─────────────────────────────────────────────

pub fn read_xml(path: &Path) -> Result<DataFrame, IoError> {
    read_xml_with_options(path, &XmlReadOptions::default())
}

pub fn read_xml_with_options(path: &Path, options: &XmlReadOptions) -> Result<DataFrame, IoError> {
    let content = std::fs::read_to_string(path)?;
    read_xml_str_with_options(&content, options)
}

// ── JSON IO ────────────────────────────────────────────────────────────

fn json_value_to_scalar(val: &serde_json::Value) -> Scalar {
    match val {
        serde_json::Value::Null => Scalar::Null(NullKind::Null),
        serde_json::Value::Bool(b) => Scalar::Bool(*b),
        serde_json::Value::Number(n) => {
            if let Some(i) = n.as_i64() {
                Scalar::Int64(i)
            } else if let Some(f) = n.as_f64() {
                Scalar::Float64(f)
            } else {
                Scalar::Utf8(n.to_string())
            }
        }
        serde_json::Value::String(s) => Scalar::Utf8(s.clone()),
        other => Scalar::Utf8(other.to_string()),
    }
}

fn parse_json_value_allowing_pandas_nan(input: &str) -> Result<serde_json::Value, IoError> {
    match serde_json::from_str(input) {
        Ok(value) => Ok(value),
        Err(original) => {
            let normalized = normalize_bare_json_nan_tokens(input);
            if normalized == input {
                return Err(original.into());
            }
            serde_json::from_str(&normalized).map_err(IoError::from)
        }
    }
}

fn normalize_bare_json_nan_tokens(input: &str) -> String {
    let mut output = String::with_capacity(input.len());
    let mut index = 0;
    let mut in_string = false;
    let mut escaped = false;

    while index < input.len() {
        let rest = &input[index..];
        let Some(ch) = rest.chars().next() else {
            break;
        };

        if in_string {
            output.push(ch);
            index += ch.len_utf8();
            if escaped {
                escaped = false;
            } else if ch == '\\' {
                escaped = true;
            } else if ch == '"' {
                in_string = false;
            }
            continue;
        }

        if ch == '"' {
            in_string = true;
            output.push(ch);
            index += ch.len_utf8();
            continue;
        }

        if rest.starts_with("NaN")
            && is_json_value_start_boundary(input, index)
            && is_json_value_end_boundary(input, index + 3)
        {
            output.push_str("null");
            index += 3;
            continue;
        }

        output.push(ch);
        index += ch.len_utf8();
    }

    output
}

fn is_json_value_start_boundary(input: &str, index: usize) -> bool {
    input[..index]
        .chars()
        .rev()
        .find(|ch| !ch.is_whitespace())
        .is_none_or(|ch| matches!(ch, ':' | '[' | ','))
}

fn is_json_value_end_boundary(input: &str, index: usize) -> bool {
    input[index..]
        .chars()
        .find(|ch| !ch.is_whitespace())
        .is_none_or(|ch| matches!(ch, ',' | ']' | '}'))
}

fn column_from_json_values(values: Vec<Scalar>) -> Result<Column, IoError> {
    let saw_utf8 = values.iter().any(|value| matches!(value, Scalar::Utf8(_)));
    let saw_missing = values.iter().any(Scalar::is_missing);
    let saw_numeric_like = values.iter().any(|value| {
        matches!(
            value,
            Scalar::Int64(_) | Scalar::Float64(_) | Scalar::Bool(_)
        )
    });

    if !saw_utf8 && saw_missing && (saw_numeric_like || values.iter().all(Scalar::is_missing)) {
        let promoted = values
            .into_iter()
            .map(|value| match value {
                Scalar::Int64(value) => Scalar::Float64(value as f64),
                Scalar::Bool(value) => Scalar::Float64(if value { 1.0 } else { 0.0 }),
                Scalar::Null(_) => Scalar::Null(NullKind::NaN),
                other => other,
            })
            .collect();
        return Column::new(DType::Float64, promoted).map_err(IoError::from);
    }

    Column::from_values(values).map_err(IoError::from)
}

fn scalar_to_json(scalar: &Scalar) -> serde_json::Value {
    match scalar {
        Scalar::Null(_) => serde_json::Value::Null,
        Scalar::Bool(b) => serde_json::Value::Bool(*b),
        Scalar::Int64(i) => serde_json::json!(*i),
        Scalar::Float64(f) => {
            if f.is_nan() || f.is_infinite() {
                serde_json::Value::Null
            } else {
                serde_json::json!(*f)
            }
        }
        Scalar::Utf8(s) => serde_json::Value::String(s.clone()),
        // pandas to_json (default date_format='epoch', date_unit='ms') serializes
        // datetime64 and timedelta64 as epoch-MILLISECOND integers, not strings.
        // (br-frankenpandas-lb0iu)
        Scalar::Timedelta64(v) => {
            if *v == Timedelta::NAT {
                serde_json::Value::Null
            } else {
                serde_json::json!(*v / 1_000_000)
            }
        }
        Scalar::Datetime64(v) => {
            if *v == Timestamp::NAT {
                serde_json::Value::Null
            } else {
                serde_json::json!(*v / 1_000_000)
            }
        }
        Scalar::Period(v) => {
            if *v == i64::MIN {
                serde_json::Value::Null
            } else {
                serde_json::Value::String(format!("Period[{v}]"))
            }
        }
        Scalar::Interval(iv) => serde_json::Value::String(format!("{iv}")),
    }
}

fn column_promotes_int_json_values_to_float(_values: &[Scalar]) -> bool {
    // DISC-011: Nullable extension Int64 dtype parity.
    // Pandas (since v0.24) preserves Int64 via a separate validity mask when
    // null values are present. We now match: Int64 values serialize as integers,
    // Null values serialize as null, no Float64 promotion.
    false
}

fn scalar_to_json_with_column_promotion(
    scalar: &Scalar,
    promote_int_to_float: bool,
) -> serde_json::Value {
    if promote_int_to_float && let Scalar::Int64(v) = scalar {
        return serde_json::json!(*v as f64);
    }
    scalar_to_json(scalar)
}

fn json_value_to_index_label(value: &serde_json::Value) -> IndexLabel {
    match value {
        serde_json::Value::Number(n) => n
            .as_i64()
            .map(IndexLabel::Int64)
            .unwrap_or_else(|| IndexLabel::Utf8(n.to_string())),
        serde_json::Value::String(s) => IndexLabel::Utf8(s.clone()),
        serde_json::Value::Bool(b) => IndexLabel::Utf8(b.to_string()),
        serde_json::Value::Null => IndexLabel::Utf8("null".to_owned()),
        other => IndexLabel::Utf8(other.to_string()),
    }
}

fn json_value_to_column_name(value: &serde_json::Value) -> String {
    match value {
        serde_json::Value::String(s) => s.clone(),
        serde_json::Value::Number(n) => n.to_string(),
        serde_json::Value::Bool(b) => b.to_string(),
        serde_json::Value::Null => "null".to_owned(),
        other => other.to_string(),
    }
}

fn json_key_to_index_label(value: &str) -> IndexLabel {
    value
        .parse::<i64>()
        .map(IndexLabel::Int64)
        .unwrap_or_else(|_| IndexLabel::Utf8(value.to_owned()))
}

fn index_label_to_json(label: &IndexLabel) -> serde_json::Value {
    match label {
        IndexLabel::Int64(v) => serde_json::json!(*v),
        IndexLabel::Utf8(v) => serde_json::Value::String(v.clone()),
        // Epoch-millisecond ints, matching pandas to_json (date_unit='ms') and
        // the value path above — previously emitted raw nanoseconds, which
        // matched neither pandas nor FP's own value serialization.
        // (br-frankenpandas-lb0iu)
        IndexLabel::Timedelta64(ns) => serde_json::json!(*ns / 1_000_000),
        IndexLabel::Datetime64(ns) => serde_json::json!(*ns / 1_000_000),
        // pandas to_json renders a missing label as JSON null.
        IndexLabel::Null(_) => serde_json::Value::Null,
    }
}

/// Stringified index label for use as a JSON object key (columns/index orients).
/// Temporal labels become epoch-millisecond strings, matching pandas to_json
/// (e.g. a 2020-01-01 index key is "1577836800000", not "2020-01-01 00:00:00").
/// (br-frankenpandas-lb0iu)
fn index_label_json_key(label: &IndexLabel) -> String {
    match label {
        IndexLabel::Datetime64(ns) | IndexLabel::Timedelta64(ns) => (*ns / 1_000_000).to_string(),
        other => other.to_string(),
    }
}

const SYNTHETIC_ROW_MULTIINDEX_PREFIX: &str = "__index_level_";

fn index_label_to_scalar_value(label: &IndexLabel) -> Scalar {
    match label {
        IndexLabel::Int64(v) => Scalar::Int64(*v),
        IndexLabel::Utf8(v) => Scalar::Utf8(v.clone()),
        IndexLabel::Timedelta64(v) => Scalar::Timedelta64(*v),
        IndexLabel::Datetime64(v) => Scalar::Utf8(format_datetime_ns(*v)),
        // Typed-null label round-trips to the same-kind missing scalar.
        IndexLabel::Null(kind) => Scalar::Null(*kind),
    }
}

fn synthetic_row_multiindex_names(nlevels: usize) -> Vec<String> {
    (0..nlevels)
        .map(|level| format!("{SYNTHETIC_ROW_MULTIINDEX_PREFIX}{level}__"))
        .collect()
}

fn materialize_row_multiindex_columns(
    frame: &DataFrame,
    names: &[String],
) -> Result<DataFrame, IoError> {
    let Some(row_multiindex) = frame.row_multiindex() else {
        return Ok(frame.clone());
    };

    let mut columns = BTreeMap::new();
    let mut column_order = Vec::with_capacity(names.len() + frame.column_names().len());
    for (level, name) in names.iter().enumerate() {
        let level_index = row_multiindex.get_level_values(level)?;
        let values = level_index
            .labels()
            .iter()
            .map(index_label_to_scalar_value)
            .collect::<Vec<_>>();
        columns.insert(name.clone(), Column::from_values(values)?);
        column_order.push(name.clone());
    }

    for name in frame.column_names() {
        let column = frame
            .column(name)
            .ok_or_else(|| {
                IoError::Frame(FrameError::CompatibilityRejected(format!(
                    "column not found: '{name}'"
                )))
            })?
            .clone();
        columns.insert(name.clone(), column);
        column_order.push(name.clone());
    }

    let index = Index::from_i64((0..frame.len() as i64).collect());
    DataFrame::new_with_column_order(index, columns, column_order).map_err(IoError::from)
}

fn materialize_named_row_multiindex_columns(frame: &DataFrame) -> Result<DataFrame, IoError> {
    if frame.row_multiindex().is_some() {
        frame.reset_index(false).map_err(IoError::from)
    } else {
        Ok(frame.clone())
    }
}

fn materialize_synthetic_row_multiindex_columns(frame: &DataFrame) -> Result<DataFrame, IoError> {
    let Some(row_multiindex) = frame.row_multiindex() else {
        return Ok(frame.clone());
    };
    let names = synthetic_row_multiindex_names(row_multiindex.nlevels());
    materialize_row_multiindex_columns(frame, &names)
}

fn promote_frame_index_columns(
    frame: &DataFrame,
    index_cols: &[&str],
) -> Result<DataFrame, IoError> {
    if index_cols.is_empty() {
        return Ok(frame.clone());
    }
    if index_cols.len() == 1 {
        frame.set_index(index_cols[0], true).map_err(IoError::from)
    } else {
        frame
            .set_index_multi(index_cols, true, "|")
            .map_err(IoError::from)
    }
}

fn detect_synthetic_row_multiindex_columns(frame: &DataFrame) -> Vec<String> {
    let mut out = Vec::new();
    for (level, name) in frame.column_names().iter().enumerate() {
        let expected = format!("{SYNTHETIC_ROW_MULTIINDEX_PREFIX}{level}__");
        if **name == expected {
            out.push(expected);
        } else {
            break;
        }
    }
    out
}

fn promote_synthetic_row_multiindex_if_present(frame: &DataFrame) -> Result<DataFrame, IoError> {
    let synthetic_cols = detect_synthetic_row_multiindex_columns(frame);
    if synthetic_cols.len() < 2 {
        return Ok(frame.clone());
    }
    let refs = synthetic_cols
        .iter()
        .map(String::as_str)
        .collect::<Vec<_>>();
    promote_frame_index_columns(frame, &refs)
}

pub fn read_json_str(input: &str, orient: JsonOrient) -> Result<DataFrame, IoError> {
    let parsed = parse_json_value_allowing_pandas_nan(input)?;

    match orient {
        JsonOrient::Records => {
            let arr = parsed
                .as_array()
                .ok_or_else(|| IoError::JsonFormat("expected array for records orient".into()))?;
            if arr.is_empty() {
                return Ok(DataFrame::new(Index::new(Vec::new()), BTreeMap::new())?);
            }

            // Collect column names from all records to handle heterogeneous keys
            let mut col_names_set = std::collections::BTreeSet::new();
            let mut col_names = Vec::new();
            for record in arr {
                let obj = record
                    .as_object()
                    .ok_or_else(|| IoError::JsonFormat("each record must be an object".into()))?;
                for key in obj.keys() {
                    if col_names_set.insert(key.clone()) {
                        col_names.push(key.clone());
                    }
                }
            }

            let mut columns: BTreeMap<String, Vec<Scalar>> = BTreeMap::new();
            for name in &col_names {
                columns.insert(name.clone(), Vec::with_capacity(arr.len()));
            }

            for record in arr {
                let obj = record
                    .as_object()
                    .ok_or_else(|| IoError::JsonFormat("each record must be an object".into()))?;
                for name in &col_names {
                    let val = obj.get(name).unwrap_or(&serde_json::Value::Null);
                    columns
                        .get_mut(name)
                        .ok_or_else(|| {
                            IoError::JsonFormat(format!(
                                "records orient missing column accumulator for '{name}'"
                            ))
                        })?
                        .push(json_value_to_scalar(val));
                }
            }

            let row_count = arr.len() as i64;
            let mut out = BTreeMap::new();
            for (name, vals) in columns {
                out.insert(name, column_from_json_values(vals)?);
            }
            let index = Index::from_i64((0..row_count).collect());
            let frame = DataFrame::new_with_column_order(index, out, col_names)?;
            promote_synthetic_row_multiindex_if_present(&frame)
        }
        JsonOrient::Columns => {
            let obj = parsed
                .as_object()
                .ok_or_else(|| IoError::JsonFormat("expected object for columns orient".into()))?;

            if obj.is_empty() {
                return Ok(DataFrame::new(Index::new(Vec::new()), BTreeMap::new())?);
            }

            let mut raw_columns: BTreeMap<String, Vec<Scalar>> = BTreeMap::new();
            let mut column_order = Vec::with_capacity(obj.len());
            let mut index_labels = Vec::new();
            let mut index_lookup = BTreeMap::new();
            for (col_name, col_data) in obj {
                let col_obj = col_data.as_object().ok_or_else(|| {
                    IoError::JsonFormat("column data must be {index: val}".into())
                })?;
                let mut values = vec![Scalar::Null(NullKind::Null); index_labels.len()];
                for (label_key, val) in col_obj {
                    let label = json_key_to_index_label(label_key);
                    let row_idx = if let Some(&existing_idx) = index_lookup.get(&label) {
                        existing_idx
                    } else {
                        let next_idx = index_labels.len();
                        index_labels.push(label.clone());
                        index_lookup.insert(label, next_idx);
                        for existing_values in raw_columns.values_mut() {
                            existing_values.push(Scalar::Null(NullKind::Null));
                        }
                        values.push(Scalar::Null(NullKind::Null));
                        next_idx
                    };
                    if row_idx >= values.len() {
                        values.resize(index_labels.len(), Scalar::Null(NullKind::Null));
                    }
                    values[row_idx] = json_value_to_scalar(val);
                }
                if values.len() < index_labels.len() {
                    values.resize(index_labels.len(), Scalar::Null(NullKind::Null));
                }
                raw_columns.insert(col_name.clone(), values);
                column_order.push(col_name.clone());
            }

            let mut out = BTreeMap::new();
            for (name, vals) in raw_columns {
                out.insert(name, column_from_json_values(vals)?);
            }

            let frame =
                DataFrame::new_with_column_order(Index::new(index_labels), out, column_order)?;
            promote_synthetic_row_multiindex_if_present(&frame)
        }
        JsonOrient::Index => {
            let obj = parsed
                .as_object()
                .ok_or_else(|| IoError::JsonFormat("expected object for index orient".into()))?;

            if obj.is_empty() {
                return Ok(DataFrame::new(Index::new(Vec::new()), BTreeMap::new())?);
            }

            let mut index_labels = Vec::with_capacity(obj.len());
            let mut columns: BTreeMap<String, Vec<Scalar>> = BTreeMap::new();
            let mut column_order = Vec::new();
            let mut seen_columns = std::collections::HashSet::new();

            for (row_label, row_data) in obj {
                let row_obj = row_data.as_object().ok_or_else(|| {
                    IoError::JsonFormat("index orient rows must be objects".into())
                })?;

                let row_idx = index_labels.len();

                // Pre-fill this row as null for all known columns, then overwrite present cells.
                for values in columns.values_mut() {
                    values.push(Scalar::Null(NullKind::Null));
                }

                let parsed_label = row_label
                    .parse::<i64>()
                    .map(IndexLabel::Int64)
                    .unwrap_or_else(|_| IndexLabel::Utf8(row_label.clone()));
                index_labels.push(parsed_label);

                for (col_name, value) in row_obj {
                    if seen_columns.insert(col_name.clone()) {
                        column_order.push(col_name.clone());
                    }
                    let scalar = json_value_to_scalar(value);
                    if let Some(values) = columns.get_mut(col_name) {
                        values[row_idx] = scalar;
                    } else {
                        let mut values = vec![Scalar::Null(NullKind::Null); row_idx + 1];
                        values[row_idx] = scalar;
                        columns.insert(col_name.clone(), values);
                    }
                }
            }

            let mut out = BTreeMap::new();
            for (name, vals) in columns {
                out.insert(name, column_from_json_values(vals)?);
            }
            let frame =
                DataFrame::new_with_column_order(Index::new(index_labels), out, column_order)?;
            promote_synthetic_row_multiindex_if_present(&frame)
        }
        JsonOrient::Split => {
            let obj = parsed
                .as_object()
                .ok_or_else(|| IoError::JsonFormat("expected object for split orient".into()))?;

            let col_names: Vec<String> = obj
                .get("columns")
                .and_then(|v| v.as_array())
                .ok_or_else(|| IoError::JsonFormat("split orient needs 'columns' array".into()))?
                .iter()
                .map(json_value_to_column_name)
                .collect();
            reject_duplicate_headers(&col_names)?;

            let data = obj
                .get("data")
                .and_then(|v| v.as_array())
                .ok_or_else(|| IoError::JsonFormat("split orient needs 'data' array".into()))?;

            let explicit_index = obj
                .get("index")
                .map(|v| {
                    v.as_array()
                        .ok_or_else(|| {
                            IoError::JsonFormat("split orient 'index' must be an array".into())
                        })
                        .map(|arr| {
                            arr.iter()
                                .map(json_value_to_index_label)
                                .collect::<Vec<_>>()
                        })
                })
                .transpose()?;

            let mut columns: BTreeMap<String, Vec<Scalar>> = BTreeMap::new();
            for name in &col_names {
                columns.insert(name.clone(), Vec::with_capacity(data.len()));
            }

            for (row_idx, row) in data.iter().enumerate() {
                let arr = row
                    .as_array()
                    .ok_or_else(|| IoError::JsonFormat("each data row must be an array".into()))?;
                if arr.len() != col_names.len() {
                    return Err(IoError::JsonFormat(format!(
                        "split orient row {row_idx} length ({}) does not match columns length ({})",
                        arr.len(),
                        col_names.len()
                    )));
                }
                for (i, name) in col_names.iter().enumerate() {
                    let val = arr.get(i).unwrap_or(&serde_json::Value::Null);
                    columns
                        .get_mut(name)
                        .ok_or_else(|| {
                            IoError::JsonFormat(format!(
                                "split orient missing column accumulator for '{name}'"
                            ))
                        })?
                        .push(json_value_to_scalar(val));
                }
            }

            let row_count = data.len() as i64;
            let mut out = BTreeMap::new();
            for (name, vals) in columns {
                out.insert(name, column_from_json_values(vals)?);
            }
            let index = match explicit_index {
                Some(labels) => {
                    if labels.len() != row_count as usize {
                        return Err(IoError::JsonFormat(format!(
                            "split orient index length ({}) must match data row count ({row_count})",
                            labels.len()
                        )));
                    }
                    Index::new(labels)
                }
                None => Index::from_i64((0..row_count).collect()),
            };
            let frame = DataFrame::new_with_column_order(index, out, col_names)?;
            promote_synthetic_row_multiindex_if_present(&frame)
        }
        JsonOrient::Values => {
            let rows = parsed
                .as_array()
                .ok_or_else(|| IoError::JsonFormat("expected array for values orient".into()))?;

            if rows.is_empty() {
                return Ok(DataFrame::new(Index::new(Vec::new()), BTreeMap::new())?);
            }

            let mut width = 0usize;
            for row in rows {
                let arr = row.as_array().ok_or_else(|| {
                    IoError::JsonFormat("each values row must be an array".into())
                })?;
                width = width.max(arr.len());
            }

            let column_order: Vec<String> = (0..width).map(|idx| idx.to_string()).collect();
            let mut columns: BTreeMap<String, Vec<Scalar>> = column_order
                .iter()
                .cloned()
                .map(|name| (name, Vec::with_capacity(rows.len())))
                .collect();

            for row in rows {
                let arr = row.as_array().ok_or_else(|| {
                    IoError::JsonFormat("each values row must be an array".into())
                })?;
                for (col_idx, name) in column_order.iter().enumerate() {
                    let val = arr.get(col_idx).unwrap_or(&serde_json::Value::Null);
                    columns
                        .get_mut(name)
                        .ok_or_else(|| {
                            IoError::JsonFormat(format!(
                                "values orient missing column accumulator for '{name}'"
                            ))
                        })?
                        .push(json_value_to_scalar(val));
                }
            }

            let mut out = BTreeMap::new();
            for (name, vals) in columns {
                out.insert(name, column_from_json_values(vals)?);
            }
            let index = Index::from_i64((0..rows.len() as i64).collect());
            let frame = DataFrame::new_with_column_order(index, out, column_order)?;
            promote_synthetic_row_multiindex_if_present(&frame)
        }
    }
}

pub fn write_json_string(frame: &DataFrame, orient: JsonOrient) -> Result<String, IoError> {
    if frame.row_multiindex().is_some() && orient != JsonOrient::Values {
        let materialized = materialize_synthetic_row_multiindex_columns(frame)?;
        return write_json_string(&materialized, orient);
    }

    let headers: Vec<String> = frame.column_names().into_iter().cloned().collect();
    let row_count = frame.index().len();
    let column_float_promotions = headers
        .iter()
        .map(|name| {
            frame
                .column(name)
                .is_some_and(|column| column_promotes_int_json_values_to_float(column.values()))
        })
        .collect::<Vec<_>>();

    match orient {
        JsonOrient::Records => {
            let mut records = Vec::with_capacity(row_count);
            for row_idx in 0..row_count {
                let mut obj = serde_json::Map::new();
                for (name, promote_int_to_float) in
                    headers.iter().zip(column_float_promotions.iter())
                {
                    let val = frame
                        .column(name)
                        .and_then(|c| c.value(row_idx))
                        .map(|value| {
                            scalar_to_json_with_column_promotion(value, *promote_int_to_float)
                        })
                        .unwrap_or(serde_json::Value::Null);
                    obj.insert(name.clone(), val);
                }
                records.push(serde_json::Value::Object(obj));
            }
            Ok(serde_json::to_string(&records)?)
        }
        JsonOrient::Columns => {
            let mut outer = serde_json::Map::new();
            for (name, promote_int_to_float) in headers.iter().zip(column_float_promotions.iter()) {
                let mut col_obj = serde_json::Map::new();
                if let Some(col) = frame.column(name) {
                    for (label, val) in frame.index().labels().iter().zip(col.values()) {
                        let key = index_label_json_key(label);
                        if col_obj
                            .insert(
                                key.clone(),
                                scalar_to_json_with_column_promotion(val, *promote_int_to_float),
                            )
                            .is_some()
                        {
                            return Err(IoError::JsonFormat(format!(
                                "columns orient cannot encode duplicate index label key: {key}"
                            )));
                        }
                    }
                }
                outer.insert(name.clone(), serde_json::Value::Object(col_obj));
            }
            Ok(serde_json::to_string(&serde_json::Value::Object(outer))?)
        }
        JsonOrient::Index => {
            let mut outer = serde_json::Map::new();
            for row_idx in 0..row_count {
                let mut row_obj = serde_json::Map::new();
                for (name, promote_int_to_float) in
                    headers.iter().zip(column_float_promotions.iter())
                {
                    let val = frame
                        .column(name)
                        .and_then(|c| c.value(row_idx))
                        .map(|value| {
                            scalar_to_json_with_column_promotion(value, *promote_int_to_float)
                        })
                        .unwrap_or(serde_json::Value::Null);
                    row_obj.insert(name.clone(), val);
                }

                let row_label = index_label_json_key(&frame.index().labels()[row_idx]);
                if outer
                    .insert(row_label.clone(), serde_json::Value::Object(row_obj))
                    .is_some()
                {
                    return Err(IoError::JsonFormat(format!(
                        "index orient cannot encode duplicate index label key: {row_label}"
                    )));
                }
            }
            Ok(serde_json::to_string(&serde_json::Value::Object(outer))?)
        }
        JsonOrient::Split => {
            let col_array: Vec<serde_json::Value> = headers
                .iter()
                .map(|h| serde_json::Value::String(h.clone()))
                .collect();
            let index_array: Vec<serde_json::Value> = frame
                .index()
                .labels()
                .iter()
                .map(index_label_to_json)
                .collect();

            let mut data = Vec::with_capacity(row_count);
            for row_idx in 0..row_count {
                let row: Vec<serde_json::Value> = headers
                    .iter()
                    .zip(column_float_promotions.iter())
                    .map(|(name, promote_int_to_float)| {
                        frame
                            .column(name)
                            .and_then(|c| c.value(row_idx))
                            .map(|value| {
                                scalar_to_json_with_column_promotion(value, *promote_int_to_float)
                            })
                            .unwrap_or(serde_json::Value::Null)
                    })
                    .collect();
                data.push(serde_json::Value::Array(row));
            }

            let mut obj = serde_json::Map::new();
            obj.insert("columns".into(), serde_json::Value::Array(col_array));
            obj.insert("index".into(), serde_json::Value::Array(index_array));
            obj.insert("data".into(), serde_json::Value::Array(data));
            Ok(serde_json::to_string(&serde_json::Value::Object(obj))?)
        }
        JsonOrient::Values => {
            let mut data = Vec::with_capacity(row_count);
            for row_idx in 0..row_count {
                let row: Vec<serde_json::Value> = headers
                    .iter()
                    .zip(column_float_promotions.iter())
                    .map(|(name, promote_int_to_float)| {
                        frame
                            .column(name)
                            .and_then(|c| c.value(row_idx))
                            .map(|value| {
                                scalar_to_json_with_column_promotion(value, *promote_int_to_float)
                            })
                            .unwrap_or(serde_json::Value::Null)
                    })
                    .collect();
                data.push(serde_json::Value::Array(row));
            }
            Ok(serde_json::to_string(&serde_json::Value::Array(data))?)
        }
    }
}

// ── File-based JSON ────────────────────────────────────────────────────

pub fn read_json(path: &Path, orient: JsonOrient) -> Result<DataFrame, IoError> {
    let content = std::fs::read_to_string(path)?;
    read_json_str(&content, orient)
}

pub fn write_json(frame: &DataFrame, path: &Path, orient: JsonOrient) -> Result<(), IoError> {
    let content = write_json_string(frame, orient)?;
    std::fs::write(path, content)?;
    Ok(())
}

// ── File-based Pickle ──────────────────────────────────────────────────

/// Read a DataFrame from a Pickle file.
pub fn read_pickle(path: &Path) -> Result<DataFrame, IoError> {
    read_pickle_with_options(path, &PickleReadOptions::default())
}

/// Read a DataFrame from a Pickle file with options.
pub fn read_pickle_with_options(
    path: &Path,
    options: &PickleReadOptions,
) -> Result<DataFrame, IoError> {
    let content = std::fs::read(path)?;
    read_pickle_bytes_with_options(&content, options)
}

/// Write a DataFrame to a Pickle file.
pub fn write_pickle(frame: &DataFrame, path: &Path) -> Result<(), IoError> {
    write_pickle_with_options(frame, path, &PickleWriteOptions::default())
}

/// Write a DataFrame to a Pickle file with options.
pub fn write_pickle_with_options(
    frame: &DataFrame,
    path: &Path,
    options: &PickleWriteOptions,
) -> Result<(), IoError> {
    let content = write_pickle_bytes_with_options(frame, options)?;
    std::fs::write(path, content)?;
    Ok(())
}

// ── File-based HDF5 ────────────────────────────────────────────────────

/// Read a DataFrame from the default HDF5 key.
pub fn read_hdf(path: &Path) -> Result<DataFrame, IoError> {
    read_hdf_with_options(path, &HdfReadOptions::default())
}

/// Read a DataFrame from an explicit HDF5 key.
pub fn read_hdf_key(path: &Path, key: &str) -> Result<DataFrame, IoError> {
    read_hdf_with_options(
        path,
        &HdfReadOptions {
            key: key.to_owned(),
        },
    )
}

/// Read a DataFrame from an HDF5 file with options.
#[cfg(feature = "hdf5")]
pub fn read_hdf_with_options(path: &Path, options: &HdfReadOptions) -> Result<DataFrame, IoError> {
    let key = normalize_hdf5_key(&options.key)?;
    let dataset_path = hdf5_payload_path(&key);
    let file = Hdf5File::open(path).map_err(hdf5_error)?;
    let dataset = file.dataset(&dataset_path).map_err(|err| {
        IoError::Hdf5(format!(
            "missing FrankenPandas payload dataset '{dataset_path}': {err}"
        ))
    })?;
    let payload = dataset.read_raw::<u8>().map_err(hdf5_error)?;
    read_pickle_bytes(&payload).map_err(|err| {
        IoError::Hdf5(format!(
            "invalid FrankenPandas payload at key '{key}': {err}"
        ))
    })
}

/// Read a DataFrame from an HDF5 file with options.
#[cfg(not(feature = "hdf5"))]
pub fn read_hdf_with_options(
    _path: &Path,
    _options: &HdfReadOptions,
) -> Result<DataFrame, IoError> {
    hdf5_feature_disabled()
}

/// Write a DataFrame to the default HDF5 key.
pub fn write_hdf(frame: &DataFrame, path: &Path) -> Result<(), IoError> {
    write_hdf_with_options(frame, path, &HdfWriteOptions::default())
}

/// Write a Series to the default HDF5 key.
///
/// Converts the Series to a single-column DataFrame and writes it.
pub fn write_hdf_series(series: &Series, path: &Path) -> Result<(), IoError> {
    let frame = series
        .to_frame(Some(series.name()))
        .map_err(|e| IoError::Hdf5(format!("Series to DataFrame conversion: {e}")))?;
    write_hdf(&frame, path)
}

/// Write a Series to an explicit HDF5 key.
pub fn write_hdf_series_key(series: &Series, path: &Path, key: &str) -> Result<(), IoError> {
    let frame = series
        .to_frame(Some(series.name()))
        .map_err(|e| IoError::Hdf5(format!("Series to DataFrame conversion: {e}")))?;
    write_hdf_key(&frame, path, key)
}

/// Write a DataFrame to an explicit HDF5 key.
pub fn write_hdf_key(frame: &DataFrame, path: &Path, key: &str) -> Result<(), IoError> {
    write_hdf_with_options(
        frame,
        path,
        &HdfWriteOptions {
            key: key.to_owned(),
        },
    )
}

/// Write a DataFrame to an HDF5 file with options.
#[cfg(feature = "hdf5")]
pub fn write_hdf_with_options(
    frame: &DataFrame,
    path: &Path,
    options: &HdfWriteOptions,
) -> Result<(), IoError> {
    let key = normalize_hdf5_key(&options.key)?;
    let payload = write_pickle_bytes(frame)?;
    let file = Hdf5File::create(path).map_err(hdf5_error)?;
    let group = file.create_group(&key).map_err(hdf5_error)?;
    group
        .new_dataset_builder()
        .with_data(payload.as_slice())
        .create(HDF5_PAYLOAD_DATASET)
        .map_err(hdf5_error)?;
    file.flush().map_err(hdf5_error)?;
    Ok(())
}

/// Write a DataFrame to an HDF5 file with options.
#[cfg(not(feature = "hdf5"))]
pub fn write_hdf_with_options(
    _frame: &DataFrame,
    _path: &Path,
    _options: &HdfWriteOptions,
) -> Result<(), IoError> {
    hdf5_feature_disabled()
}

#[cfg(feature = "hdf5")]
fn normalize_hdf5_key(key: &str) -> Result<String, IoError> {
    let trimmed = key.trim_matches('/');
    if trimmed.is_empty() {
        return Err(IoError::Hdf5(
            "hdf5 key must name a non-root group".to_owned(),
        ));
    }

    for part in trimmed.split('/') {
        if part.is_empty() || part == "." || part == ".." {
            return Err(IoError::Hdf5(format!("invalid hdf5 key '{key}'")));
        }
        if part == HDF5_PAYLOAD_DATASET {
            return Err(IoError::Hdf5(format!(
                "hdf5 key '{key}' uses reserved FrankenPandas dataset name"
            )));
        }
    }

    Ok(trimmed.to_owned())
}

#[cfg(feature = "hdf5")]
fn hdf5_payload_path(key: &str) -> String {
    format!("{key}/{HDF5_PAYLOAD_DATASET}")
}

#[cfg(feature = "hdf5")]
fn hdf5_error(err: hdf5::Error) -> IoError {
    IoError::Hdf5(err.to_string())
}

#[cfg(not(feature = "hdf5"))]
fn hdf5_feature_disabled<T>() -> Result<T, IoError> {
    Err(IoError::Hdf5(
        "hdf5 support is disabled; enable the fp-io `hdf5` feature".to_owned(),
    ))
}

// ── File-based Stata ───────────────────────────────────────────────────

/// Read a DataFrame from a Stata DTA file.
pub fn read_stata(path: &Path) -> Result<DataFrame, IoError> {
    let content = std::fs::read(path)?;
    read_stata_bytes(&content)
}

/// Write a DataFrame to a Stata DTA file.
pub fn write_stata(frame: &DataFrame, path: &Path) -> Result<(), IoError> {
    write_stata_with_options(frame, path, &StataWriteOptions::default())
}

/// Write a DataFrame to a Stata DTA file with explicit options.
pub fn write_stata_with_options(
    frame: &DataFrame,
    path: &Path,
    options: &StataWriteOptions,
) -> Result<(), IoError> {
    let content = write_stata_bytes_with_options(frame, options)?;
    std::fs::write(path, content)?;
    Ok(())
}

// ── JSONL (JSON Lines) I/O ──────────────────────────────────────────────

/// Write a DataFrame to JSONL (JSON Lines) format.
///
/// Matches `pd.DataFrame.to_json(orient='records', lines=True)`.
/// Each row is written as a separate JSON object on its own line,
/// with no enclosing array. This format is standard for streaming
/// data pipelines and log processing.
pub fn write_jsonl_string(frame: &DataFrame) -> Result<String, IoError> {
    let headers: Vec<String> = frame.column_names().into_iter().cloned().collect();
    let row_count = frame.index().len();
    let column_float_promotions = headers
        .iter()
        .map(|name| {
            frame
                .column(name)
                .is_some_and(|column| column_promotes_int_json_values_to_float(column.values()))
        })
        .collect::<Vec<_>>();

    let mut lines = Vec::with_capacity(row_count);
    for row_idx in 0..row_count {
        let mut obj = serde_json::Map::new();
        for (name, promote_int_to_float) in headers.iter().zip(column_float_promotions.iter()) {
            let val = frame
                .column(name)
                .and_then(|c| c.value(row_idx))
                .map(|value| scalar_to_json_with_column_promotion(value, *promote_int_to_float))
                .unwrap_or(serde_json::Value::Null);
            obj.insert(name.clone(), val);
        }
        lines.push(serde_json::to_string(&serde_json::Value::Object(obj))?);
    }

    Ok(lines.join("\n"))
}

/// Read a DataFrame from JSONL (JSON Lines) format.
///
/// Matches `pd.read_json(input, lines=True)`.
/// Each line must be a valid JSON object with the same keys.
/// Per br-frankenpandas-9l8gd: row cap to prevent DoS via hostile input.
/// Hostile JSONL with billions of lines would otherwise grow `all_rows`
/// unbounded before the column-build allocation.
const READ_JSONL_MAX_ROWS: usize = 100_000_000;

pub fn read_jsonl_str(input: &str) -> Result<DataFrame, IoError> {
    let mut all_rows: Vec<serde_json::Map<String, serde_json::Value>> = Vec::new();

    for line in input.lines() {
        let trimmed = line.trim();
        if trimmed.is_empty() {
            continue;
        }
        // Per br-frankenpandas-9l8gd: reject hostile inputs that would
        // exhaust memory before the column-build allocation step.
        if all_rows.len() >= READ_JSONL_MAX_ROWS {
            return Err(IoError::JsonFormat(format!(
                "JSONL input exceeds maximum of {READ_JSONL_MAX_ROWS} rows"
            )));
        }
        let parsed = parse_json_value_allowing_pandas_nan(trimmed)?;
        let obj = parsed
            .as_object()
            .ok_or_else(|| IoError::JsonFormat("JSONL: each line must be a JSON object".into()))?;
        all_rows.push(obj.clone());
    }

    if all_rows.is_empty() {
        return DataFrame::new(Index::new(Vec::new()), BTreeMap::new()).map_err(IoError::Frame);
    }

    // Collect column names as the UNION of all keys across all rows.
    // This matches pandas behavior: missing keys in a row become null.
    let mut col_name_set = std::collections::BTreeSet::new();
    let mut col_names_ordered: Vec<String> = Vec::new();
    for row in &all_rows {
        for key in row.keys() {
            if col_name_set.insert(key.clone()) {
                col_names_ordered.push(key.clone());
            }
        }
    }
    let col_names = col_names_ordered;
    let mut columns: Vec<Vec<Scalar>> = col_names
        .iter()
        .map(|_| Vec::with_capacity(all_rows.len()))
        .collect();

    for row in &all_rows {
        for (col_idx, name) in col_names.iter().enumerate() {
            let val = row.get(name).unwrap_or(&serde_json::Value::Null);
            columns[col_idx].push(json_value_to_scalar(val));
        }
    }

    let mut out_columns = BTreeMap::new();
    let mut column_order = Vec::new();
    for (name, values) in col_names.into_iter().zip(columns) {
        out_columns.insert(name.clone(), column_from_json_values(values)?);
        column_order.push(name);
    }

    let index = Index::from_i64((0..all_rows.len() as i64).collect());
    Ok(DataFrame::new_with_column_order(
        index,
        out_columns,
        column_order,
    )?)
}

/// Write a DataFrame to a JSONL file.
pub fn write_jsonl(frame: &DataFrame, path: &Path) -> Result<(), IoError> {
    let content = write_jsonl_string(frame)?;
    std::fs::write(path, content)?;
    Ok(())
}

/// Read a DataFrame from a JSONL file.
pub fn read_jsonl(path: &Path) -> Result<DataFrame, IoError> {
    let content = std::fs::read_to_string(path)?;
    read_jsonl_str(&content)
}

// ── Parquet I/O ─────────────────────────────────────────────────────────────

/// Convert an fp-types DType to an Arrow DataType.
fn dtype_to_arrow(dtype: DType) -> ArrowDataType {
    match dtype {
        DType::Int64 | DType::Int64Nullable => ArrowDataType::Int64,
        DType::Float64 => ArrowDataType::Float64,
        DType::Utf8 => ArrowDataType::Utf8,
        DType::Categorical => ArrowDataType::Utf8,
        DType::Bool | DType::BoolNullable => ArrowDataType::Boolean,
        DType::Null => ArrowDataType::Utf8, // fallback: null-only columns as string
        DType::Timedelta64 => ArrowDataType::Int64, // store as nanoseconds
        DType::Datetime64 => ArrowDataType::Int64, // store as nanoseconds
        DType::Period => ArrowDataType::Int64, // store as ordinal
        DType::Interval => ArrowDataType::Utf8, // store as string until arrow interval lands
        DType::Sparse => ArrowDataType::Utf8, // marker fallback until sparse arrays land
    }
}

fn column_to_arrow_array(column: &Column) -> Result<Arc<dyn Array>, IoError> {
    let arr: Arc<dyn Array> = match column.dtype() {
        DType::Int64 | DType::Int64Nullable => {
            let mut builder = Int64Builder::with_capacity(column.len());
            for value in column.values() {
                match value {
                    Scalar::Int64(n) => builder.append_value(*n),
                    _ if value.is_missing() => builder.append_null(),
                    _ => builder.append_null(),
                }
            }
            Arc::new(builder.finish())
        }
        DType::Float64 => {
            let mut builder = Float64Builder::with_capacity(column.len());
            for value in column.values() {
                match value {
                    Scalar::Float64(n) => {
                        if n.is_nan() {
                            builder.append_null();
                        } else {
                            builder.append_value(*n);
                        }
                    }
                    _ if value.is_missing() => builder.append_null(),
                    _ => builder.append_null(),
                }
            }
            Arc::new(builder.finish())
        }
        DType::Bool | DType::BoolNullable => {
            let mut builder = BooleanBuilder::with_capacity(column.len());
            for value in column.values() {
                match value {
                    Scalar::Bool(flag) => builder.append_value(*flag),
                    _ if value.is_missing() => builder.append_null(),
                    _ => builder.append_null(),
                }
            }
            Arc::new(builder.finish())
        }
        DType::Utf8 | DType::Categorical | DType::Null | DType::Sparse => {
            let mut builder = StringBuilder::with_capacity(column.len(), column.len() * 8);
            for value in column.values() {
                match value {
                    Scalar::Utf8(text) => builder.append_value(text),
                    _ if value.is_missing() => builder.append_null(),
                    _ => builder.append_value(format!("{value:?}")),
                }
            }
            Arc::new(builder.finish())
        }
        DType::Timedelta64 => {
            let mut builder = Int64Builder::with_capacity(column.len());
            for value in column.values() {
                match value {
                    Scalar::Timedelta64(nanos) => {
                        if *nanos == Timedelta::NAT {
                            builder.append_null();
                        } else {
                            builder.append_value(*nanos);
                        }
                    }
                    _ if value.is_missing() => builder.append_null(),
                    _ => builder.append_null(),
                }
            }
            Arc::new(builder.finish())
        }
        DType::Datetime64 => {
            let mut builder = Int64Builder::with_capacity(column.len());
            for value in column.values() {
                match value {
                    Scalar::Datetime64(nanos) => {
                        if *nanos == Timestamp::NAT {
                            builder.append_null();
                        } else {
                            builder.append_value(*nanos);
                        }
                    }
                    _ if value.is_missing() => builder.append_null(),
                    _ => builder.append_null(),
                }
            }
            Arc::new(builder.finish())
        }
        DType::Period => {
            let mut builder = Int64Builder::with_capacity(column.len());
            for value in column.values() {
                match value {
                    Scalar::Period(ordinal) => {
                        if *ordinal == i64::MIN {
                            builder.append_null();
                        } else {
                            builder.append_value(*ordinal);
                        }
                    }
                    _ if value.is_missing() => builder.append_null(),
                    _ => builder.append_null(),
                }
            }
            Arc::new(builder.finish())
        }
        DType::Interval => {
            let mut builder = StringBuilder::with_capacity(column.len(), column.len() * 32);
            for value in column.values() {
                match value {
                    Scalar::Interval(iv) => builder.append_value(format!("{iv}")),
                    _ if value.is_missing() => builder.append_null(),
                    _ => builder.append_null(),
                }
            }
            Arc::new(builder.finish())
        }
    };

    Ok(arr)
}

/// Convert a Series to its Arrow data type plus backing array.
///
/// This is the Arrow-level building block under Feather / IPC round-trips and
/// preserves nullable Int64 columns as Arrow null-bitmaps rather than coercing
/// through Float64.
pub fn series_to_arrow_array(series: &Series) -> Result<(ArrowDataType, Arc<dyn Array>), IoError> {
    let dt = dtype_to_arrow(series.column().dtype());
    Ok((dt, column_to_arrow_array(series.column())?))
}

/// Rebuild a Series from an Arrow array and explicit dtype metadata.
pub fn series_from_arrow_array(
    name: impl Into<String>,
    index_labels: Vec<IndexLabel>,
    arr: &dyn Array,
    dt: &ArrowDataType,
) -> Result<Series, IoError> {
    let values = arrow_array_to_scalars(arr, dt)?;
    Series::from_values(name, index_labels, values).map_err(IoError::from)
}

/// Build an Arrow RecordBatch from a DataFrame.
fn dataframe_to_record_batch(frame: &DataFrame) -> Result<RecordBatch, IoError> {
    let materialized = if frame.row_multiindex().is_some() {
        Some(materialize_synthetic_row_multiindex_columns(frame)?)
    } else {
        None
    };
    let frame = materialized.as_ref().unwrap_or(frame);

    let col_names: Vec<String> = frame.column_names().into_iter().cloned().collect();
    let mut fields = Vec::with_capacity(col_names.len());
    let mut arrays: Vec<Arc<dyn Array>> = Vec::with_capacity(col_names.len());

    for name in &col_names {
        let col = frame
            .column(name)
            .ok_or_else(|| IoError::Parquet(format!("missing column: {name}")))?;
        let dt = col.dtype();
        fields.push(Field::new(name.as_str(), dtype_to_arrow(dt), true));
        let arr = column_to_arrow_array(col)?;
        arrays.push(arr);
    }

    let schema = Arc::new(Schema::new(fields));
    RecordBatch::try_new(schema, arrays).map_err(|e| IoError::Parquet(e.to_string()))
}

/// Convert an Arrow RecordBatch back into a DataFrame.
fn record_batch_to_dataframe(batch: &RecordBatch) -> Result<DataFrame, IoError> {
    let n_rows = batch.num_rows();
    let schema = batch.schema();
    let mut columns = BTreeMap::new();
    let mut col_order = Vec::new();

    for (i, field) in schema.fields().iter().enumerate() {
        let name = field.name().clone();
        let arr = batch.column(i);
        let values = arrow_array_to_scalars(arr.as_ref(), field.data_type())?;
        let dtype = fp_dtype_for_arrow_data_type(field.data_type());
        let col = Column::new(dtype, values)?;
        columns.insert(name.clone(), col);
        col_order.push(name);
    }

    let labels: Vec<IndexLabel> = (0..n_rows).map(|i| IndexLabel::Int64(i as i64)).collect();
    let index = Index::new(labels);

    let frame = DataFrame::new_with_column_order(index, columns, col_order)?;
    promote_synthetic_row_multiindex_if_present(&frame)
}

fn fp_dtype_for_arrow_data_type(dt: &ArrowDataType) -> DType {
    match dt {
        ArrowDataType::Int8
        | ArrowDataType::Int16
        | ArrowDataType::Int32
        | ArrowDataType::Int64
        | ArrowDataType::UInt8
        | ArrowDataType::UInt16
        | ArrowDataType::UInt32
        | ArrowDataType::UInt64 => DType::Int64,
        ArrowDataType::Float16 | ArrowDataType::Float32 | ArrowDataType::Float64 => DType::Float64,
        ArrowDataType::Boolean => DType::Bool,
        ArrowDataType::Utf8
        | ArrowDataType::LargeUtf8
        | ArrowDataType::Date32
        | ArrowDataType::Date64
        | ArrowDataType::Timestamp(_, _) => DType::Utf8,
        _ => DType::Utf8,
    }
}

/// Convert an Arrow array + data type to a Vec of Scalars.
fn arrow_array_to_scalars(arr: &dyn Array, dt: &ArrowDataType) -> Result<Vec<Scalar>, IoError> {
    let len = arr.len();
    let mut scalars = Vec::with_capacity(len);

    match dt {
        ArrowDataType::Int64 => {
            let typed = arr
                .as_any()
                .downcast_ref::<Int64Array>()
                .ok_or_else(|| IoError::Parquet("expected Int64Array".into()))?;
            for i in 0..len {
                if typed.is_null(i) {
                    scalars.push(Scalar::Null(NullKind::Null));
                } else {
                    scalars.push(Scalar::Int64(typed.value(i)));
                }
            }
        }
        ArrowDataType::Int32 => {
            let typed = arr
                .as_any()
                .downcast_ref::<arrow::array::Int32Array>()
                .ok_or_else(|| IoError::Parquet("expected Int32Array".into()))?;
            for i in 0..len {
                if typed.is_null(i) {
                    scalars.push(Scalar::Null(NullKind::Null));
                } else {
                    scalars.push(Scalar::Int64(i64::from(typed.value(i))));
                }
            }
        }
        ArrowDataType::Float64 => {
            let typed = arr
                .as_any()
                .downcast_ref::<Float64Array>()
                .ok_or_else(|| IoError::Parquet("expected Float64Array".into()))?;
            for i in 0..len {
                if typed.is_null(i) {
                    scalars.push(Scalar::Null(NullKind::NaN));
                } else {
                    scalars.push(Scalar::Float64(typed.value(i)));
                }
            }
        }
        ArrowDataType::Float32 => {
            let typed = arr
                .as_any()
                .downcast_ref::<arrow::array::Float32Array>()
                .ok_or_else(|| IoError::Parquet("expected Float32Array".into()))?;
            for i in 0..len {
                if typed.is_null(i) {
                    scalars.push(Scalar::Null(NullKind::NaN));
                } else {
                    scalars.push(Scalar::Float64(f64::from(typed.value(i))));
                }
            }
        }
        ArrowDataType::Boolean => {
            let typed = arr
                .as_any()
                .downcast_ref::<BooleanArray>()
                .ok_or_else(|| IoError::Parquet("expected BooleanArray".into()))?;
            for i in 0..len {
                if typed.is_null(i) {
                    scalars.push(Scalar::Null(NullKind::Null));
                } else {
                    scalars.push(Scalar::Bool(typed.value(i)));
                }
            }
        }
        ArrowDataType::Utf8 => {
            let typed = arr
                .as_any()
                .downcast_ref::<StringArray>()
                .ok_or_else(|| IoError::Parquet("expected StringArray".into()))?;
            for i in 0..len {
                if typed.is_null(i) {
                    scalars.push(Scalar::Null(NullKind::Null));
                } else {
                    scalars.push(Scalar::Utf8(typed.value(i).to_owned()));
                }
            }
        }
        ArrowDataType::LargeUtf8 => {
            let typed = arr
                .as_any()
                .downcast_ref::<arrow::array::LargeStringArray>()
                .ok_or_else(|| IoError::Parquet("expected LargeStringArray".into()))?;
            for i in 0..len {
                if typed.is_null(i) {
                    scalars.push(Scalar::Null(NullKind::Null));
                } else {
                    scalars.push(Scalar::Utf8(typed.value(i).to_owned()));
                }
            }
        }
        ArrowDataType::Date32 => {
            let typed = arr
                .as_any()
                .downcast_ref::<Date32Array>()
                .ok_or_else(|| IoError::Parquet("expected Date32Array".into()))?;
            for i in 0..len {
                if typed.is_null(i) {
                    scalars.push(Scalar::Null(NullKind::NaT));
                } else {
                    if let Some(date) = arrow::temporal_conversions::as_date::<
                        arrow::datatypes::Date32Type,
                    >(typed.value(i).into())
                    {
                        scalars.push(Scalar::Utf8(date.format("%Y-%m-%d").to_string()));
                    } else {
                        scalars.push(Scalar::Null(NullKind::NaT));
                    }
                }
            }
        }
        ArrowDataType::Date64 => {
            let typed = arr
                .as_any()
                .downcast_ref::<Date64Array>()
                .ok_or_else(|| IoError::Parquet("expected Date64Array".into()))?;
            for i in 0..len {
                if typed.is_null(i) {
                    scalars.push(Scalar::Null(NullKind::NaT));
                } else {
                    if let Some(dt) = arrow::temporal_conversions::as_datetime::<
                        arrow::datatypes::Date64Type,
                    >(typed.value(i))
                    {
                        scalars.push(Scalar::Utf8(dt.format("%Y-%m-%d").to_string()));
                    } else {
                        scalars.push(Scalar::Null(NullKind::NaT));
                    }
                }
            }
        }
        ArrowDataType::Timestamp(unit, _tz) => match unit {
            TimeUnit::Second => {
                let typed = arr
                    .as_any()
                    .downcast_ref::<TimestampSecondArray>()
                    .ok_or_else(|| IoError::Parquet("expected TimestampSecondArray".into()))?;
                for i in 0..len {
                    if typed.is_null(i) {
                        scalars.push(Scalar::Null(NullKind::NaT));
                    } else {
                        if let Some(dt) = arrow::temporal_conversions::as_datetime::<
                            arrow::datatypes::TimestampSecondType,
                        >(typed.value(i))
                        {
                            scalars.push(Scalar::Utf8(dt.format("%Y-%m-%d %H:%M:%S").to_string()));
                        } else {
                            scalars.push(Scalar::Null(NullKind::NaT));
                        }
                    }
                }
            }
            TimeUnit::Millisecond => {
                let typed = arr
                    .as_any()
                    .downcast_ref::<TimestampMillisecondArray>()
                    .ok_or_else(|| IoError::Parquet("expected TimestampMillisecondArray".into()))?;
                for i in 0..len {
                    if typed.is_null(i) {
                        scalars.push(Scalar::Null(NullKind::NaT));
                    } else {
                        if let Some(dt) = arrow::temporal_conversions::as_datetime::<
                            arrow::datatypes::TimestampMillisecondType,
                        >(typed.value(i))
                        {
                            scalars.push(Scalar::Utf8(dt.format("%Y-%m-%d %H:%M:%S").to_string()));
                        } else {
                            scalars.push(Scalar::Null(NullKind::NaT));
                        }
                    }
                }
            }
            TimeUnit::Microsecond => {
                let typed = arr
                    .as_any()
                    .downcast_ref::<TimestampMicrosecondArray>()
                    .ok_or_else(|| IoError::Parquet("expected TimestampMicrosecondArray".into()))?;
                for i in 0..len {
                    if typed.is_null(i) {
                        scalars.push(Scalar::Null(NullKind::NaT));
                    } else {
                        if let Some(dt) = arrow::temporal_conversions::as_datetime::<
                            arrow::datatypes::TimestampMicrosecondType,
                        >(typed.value(i))
                        {
                            scalars
                                .push(Scalar::Utf8(dt.format("%Y-%m-%d %H:%M:%S%.6f").to_string()));
                        } else {
                            scalars.push(Scalar::Null(NullKind::NaT));
                        }
                    }
                }
            }
            TimeUnit::Nanosecond => {
                let typed = arr
                    .as_any()
                    .downcast_ref::<TimestampNanosecondArray>()
                    .ok_or_else(|| IoError::Parquet("expected TimestampNanosecondArray".into()))?;
                for i in 0..len {
                    if typed.is_null(i) {
                        scalars.push(Scalar::Null(NullKind::NaT));
                    } else {
                        if let Some(dt) = arrow::temporal_conversions::as_datetime::<
                            arrow::datatypes::TimestampNanosecondType,
                        >(typed.value(i))
                        {
                            scalars
                                .push(Scalar::Utf8(dt.format("%Y-%m-%d %H:%M:%S%.9f").to_string()));
                        } else {
                            scalars.push(Scalar::Null(NullKind::NaT));
                        }
                    }
                }
            }
        },
        other => {
            return Err(IoError::Parquet(format!(
                "unsupported Arrow data type: {other:?}"
            )));
        }
    }

    Ok(scalars)
}

/// Write a DataFrame to an in-memory Parquet buffer.
pub fn write_parquet_bytes(frame: &DataFrame) -> Result<Vec<u8>, IoError> {
    let batch = dataframe_to_record_batch(frame)?;
    let mut buf = Vec::new();
    let mut writer = ArrowWriter::try_new(&mut buf, batch.schema(), None)
        .map_err(|e| IoError::Parquet(e.to_string()))?;
    writer
        .write(&batch)
        .map_err(|e| IoError::Parquet(e.to_string()))?;
    writer
        .close()
        .map_err(|e| IoError::Parquet(e.to_string()))?;
    Ok(buf)
}

/// Read a DataFrame from in-memory Parquet bytes.
pub fn read_parquet_bytes(data: &[u8]) -> Result<DataFrame, IoError> {
    let b = bytes::Bytes::from(data.to_vec());
    let reader = ParquetRecordBatchReaderBuilder::try_new(b)
        .map_err(|e| IoError::Parquet(e.to_string()))?
        .build()
        .map_err(|e| IoError::Parquet(e.to_string()))?;

    let mut all_frames: Vec<DataFrame> = Vec::new();
    for batch_result in reader {
        let batch: RecordBatch =
            batch_result.map_err(|e: arrow::error::ArrowError| IoError::Parquet(e.to_string()))?;
        all_frames.push(record_batch_to_dataframe(&batch)?);
    }

    if all_frames.is_empty() {
        // Return empty DataFrame
        return Ok(DataFrame::new_with_column_order(
            Index::new(vec![]),
            BTreeMap::new(),
            vec![],
        )?);
    }

    // For a single batch (common case), return directly
    if all_frames.len() == 1 {
        if let Some(frame) = all_frames.into_iter().next() {
            return Ok(frame);
        }
        return Err(IoError::Parquet(
            "parquet reader produced zero record batches".to_owned(),
        ));
    }

    // Multiple batches: concatenate via fp_frame::concat_dataframes
    let refs: Vec<&DataFrame> = all_frames.iter().collect();
    fp_frame::concat_dataframes(&refs).map_err(IoError::from)
}

/// Write a DataFrame to a Parquet file.
pub fn write_parquet(frame: &DataFrame, path: &Path) -> Result<(), IoError> {
    let bytes = write_parquet_bytes(frame)?;
    std::fs::write(path, bytes)?;
    Ok(())
}

/// Read a DataFrame from a Parquet file.
pub fn read_parquet(path: &Path) -> Result<DataFrame, IoError> {
    let data = std::fs::read(path)?;
    read_parquet_bytes(&data)
}

// ── ORC I/O ────────────────────────────────────────────────────────────────

/// Write a DataFrame to an in-memory ORC buffer.
///
/// Uses the shared Arrow conversion path, then delegates ORC physical encoding
/// to `orc-rust`.
pub fn write_orc_bytes(frame: &DataFrame) -> Result<Vec<u8>, IoError> {
    let batch = dataframe_to_record_batch(frame)?;
    let mut buf = Vec::new();
    let mut writer = OrcArrowWriterBuilder::new(&mut buf, batch.schema())
        .try_build()
        .map_err(|err| IoError::Orc(err.to_string()))?;
    writer
        .write(&batch)
        .map_err(|err| IoError::Orc(err.to_string()))?;
    writer
        .close()
        .map_err(|err| IoError::Orc(err.to_string()))?;
    Ok(buf)
}

/// Read a DataFrame from in-memory ORC bytes.
pub fn read_orc_bytes(data: &[u8]) -> Result<DataFrame, IoError> {
    let bytes = bytes::Bytes::from(data.to_vec());
    let reader = OrcArrowReaderBuilder::try_new(bytes)
        .map_err(|err| IoError::Orc(err.to_string()))?
        .build();

    let mut all_frames: Vec<DataFrame> = Vec::new();
    for batch_result in reader {
        let batch = batch_result.map_err(|err| IoError::Orc(err.to_string()))?;
        all_frames.push(record_batch_to_dataframe(&batch)?);
    }

    if all_frames.is_empty() {
        return Ok(DataFrame::new_with_column_order(
            Index::new(vec![]),
            BTreeMap::new(),
            vec![],
        )?);
    }

    if all_frames.len() == 1 {
        if let Some(frame) = all_frames.into_iter().next() {
            return Ok(frame);
        }
        return Err(IoError::Orc(
            "orc reader produced zero record batches".to_owned(),
        ));
    }

    let refs: Vec<&DataFrame> = all_frames.iter().collect();
    fp_frame::concat_dataframes(&refs).map_err(IoError::from)
}

/// Write a DataFrame to an ORC file.
pub fn write_orc(frame: &DataFrame, path: &Path) -> Result<(), IoError> {
    let bytes = write_orc_bytes(frame)?;
    std::fs::write(path, bytes)?;
    Ok(())
}

/// Read a DataFrame from an ORC file.
pub fn read_orc(path: &Path) -> Result<DataFrame, IoError> {
    let data = std::fs::read(path)?;
    read_orc_bytes(&data)
}

// ── Excel (xlsx) I/O ────────────────────────────────────────────────────

/// Options for reading Excel files.
#[derive(Debug, Clone)]
pub struct ExcelReadOptions {
    /// Sheet name to read. If `None`, reads the first sheet.
    pub sheet_name: Option<String>,
    /// Whether the first row contains column headers.
    pub has_headers: bool,
    /// Read only these columns (by name). `None` means read all.
    /// Matches pandas `usecols` parameter for label-based selection.
    pub usecols: Option<Vec<String>>,
    /// Explicit column names to use instead of worksheet headers or
    /// auto-generated `column_N` names. Matches pandas `names=...`.
    pub names: Option<Vec<String>>,
    /// Optional column to use as the DataFrame index.
    pub index_col: Option<String>,
    /// Number of initial rows to skip before reading headers/data.
    pub skip_rows: usize,
}

impl Default for ExcelReadOptions {
    fn default() -> Self {
        Self {
            sheet_name: None,
            has_headers: true,
            usecols: None,
            names: None,
            index_col: None,
            skip_rows: 0,
        }
    }
}

/// Convert a calamine `Data` cell value to a `Scalar`.
fn excel_cell_to_scalar(cell: &calamine::Data) -> Scalar {
    match cell {
        calamine::Data::Int(v) => Scalar::Int64(*v),
        calamine::Data::Float(v) => {
            if v.is_nan() {
                Scalar::Null(NullKind::NaN)
            } else if v.fract() == 0.0 && *v >= i64::MIN as f64 && *v <= i64::MAX as f64 {
                // Excel stores integers as floats; recover Int64 for whole numbers.
                Scalar::Int64(*v as i64)
            } else {
                Scalar::Float64(*v)
            }
        }
        calamine::Data::String(s) => {
            if s.is_empty() {
                Scalar::Null(NullKind::Null)
            } else {
                Scalar::Utf8(s.clone())
            }
        }
        calamine::Data::Bool(b) => Scalar::Bool(*b),
        calamine::Data::Empty => Scalar::Null(NullKind::Null),
        calamine::Data::DateTime(dt) => {
            // Convert ExcelDateTime to string representation for now.
            Scalar::Utf8(format!("{dt}"))
        }
        calamine::Data::DateTimeIso(s) => Scalar::Utf8(s.clone()),
        calamine::Data::DurationIso(s) => Scalar::Utf8(s.clone()),
        calamine::Data::Error(e) => Scalar::Utf8(format!("#ERROR:{e:?}")),
    }
}

/// Convert a Scalar to an IndexLabel, handling float precision correctly.
fn scalar_to_index_label(scalar: Scalar) -> IndexLabel {
    match scalar {
        Scalar::Int64(v) => IndexLabel::Int64(v),
        Scalar::Utf8(s) => IndexLabel::Utf8(s),
        Scalar::Float64(v) if v.fract() == 0.0 && v >= i64::MIN as f64 && v <= i64::MAX as f64 => {
            IndexLabel::Int64(v as i64)
        }
        Scalar::Float64(v) => IndexLabel::Utf8(v.to_string()),
        Scalar::Bool(b) => IndexLabel::Utf8(if b { "True" } else { "False" }.to_string()),
        _ => IndexLabel::Utf8(String::new()),
    }
}

fn infer_writer_emitted_default_excel_index_col(
    headers: &[String],
    header_generated: &[bool],
    columns: &[Vec<Scalar>],
    options: &ExcelReadOptions,
) -> Option<usize> {
    if !options.has_headers
        || options.index_col.is_some()
        || options.usecols.is_some()
        || options.names.is_some()
    {
        return None;
    }

    if headers.first()?.as_str() != "column_0"
        || !header_generated.first().copied().unwrap_or(false)
    {
        return None;
    }

    let first_col = columns.first()?;
    if first_col
        .iter()
        .enumerate()
        .all(|(idx, scalar)| matches!(scalar, Scalar::Int64(value) if *value == idx as i64))
    {
        Some(0)
    } else {
        None
    }
}

/// Shared parsing logic for Excel data after extracting rows from a workbook.
fn parse_excel_rows(
    rows: Vec<Vec<calamine::Data>>,
    options: &ExcelReadOptions,
) -> Result<DataFrame, IoError> {
    if rows.is_empty() {
        return DataFrame::new(Index::new(Vec::new()), BTreeMap::new()).map_err(IoError::Frame);
    }

    let resolve_names = |width: usize| -> Result<Option<Vec<String>>, IoError> {
        options.names.as_ref().map_or(Ok(None), |names| {
            if names.len() == width {
                Ok(Some(names.clone()))
            } else {
                Err(IoError::Excel(format!(
                    "expected {width} column names, got {}",
                    names.len()
                )))
            }
        })
    };

    // Extract headers.
    let (headers, header_generated, data_rows) = if options.has_headers {
        let header_row = &rows[0];
        let header_width = header_row.len();
        let provided_names = resolve_names(header_width)?;
        let (headers, header_generated): (Vec<_>, Vec<_>) = if let Some(names) = provided_names {
            (names, vec![false; header_width])
        } else {
            let header_pairs: Vec<(String, bool)> = header_row
                .iter()
                .enumerate()
                .map(|(i, cell)| match cell {
                    calamine::Data::String(s) if !s.is_empty() => (s.clone(), false),
                    _ => (format!("column_{i}"), true),
                })
                .collect();
            header_pairs.into_iter().unzip()
        };
        (headers, header_generated, &rows[1..])
    } else {
        let ncols = rows.iter().map(Vec::len).max().unwrap_or(0);
        let provided_names = resolve_names(ncols)?;
        let (headers, header_generated) = if let Some(names) = provided_names {
            (names, vec![false; ncols])
        } else {
            let headers: Vec<String> = (0..ncols).map(|i| format!("column_{i}")).collect();
            let header_generated = vec![true; ncols];
            (headers, header_generated)
        };
        (headers, header_generated, rows.as_slice())
    };
    reject_duplicate_headers(&headers)?;

    if let Some(ref usecols) = options.usecols {
        validate_usecols(&headers, usecols)?;
    }

    let ncols = headers.len();

    // Accumulate columns.
    let mut columns: Vec<Vec<Scalar>> = (0..ncols)
        .map(|_| Vec::with_capacity(data_rows.len()))
        .collect();

    for row in data_rows {
        for (col_idx, col_vec) in columns.iter_mut().enumerate() {
            let cell = row.get(col_idx).unwrap_or(&calamine::Data::Empty);
            col_vec.push(excel_cell_to_scalar(cell));
        }
    }

    let (headers, header_generated, columns) = if let Some(ref usecols) = options.usecols {
        let mut filtered_headers = Vec::new();
        let mut filtered_generated = Vec::new();
        let mut filtered_columns = Vec::new();
        for ((name, generated), values) in headers.into_iter().zip(header_generated).zip(columns) {
            if usecols.contains(&name) {
                filtered_headers.push(name);
                filtered_generated.push(generated);
                filtered_columns.push(values);
            }
        }
        (filtered_headers, filtered_generated, filtered_columns)
    } else {
        (headers, header_generated, columns)
    };

    // Handle index_col if specified.
    let index_col_idx = if let Some(ref idx_name) = options.index_col {
        let pos = headers.iter().position(|h| h == idx_name);
        if pos.is_none() {
            return Err(IoError::MissingIndexColumn(idx_name.clone()));
        }
        pos
    } else {
        infer_writer_emitted_default_excel_index_col(&headers, &header_generated, &columns, options)
    };

    let index_name = index_col_idx.and_then(|idx_pos| {
        if !header_generated[idx_pos] {
            Some(headers[idx_pos].clone())
        } else {
            None
        }
    });

    let mut out_columns = BTreeMap::new();
    let mut column_order = Vec::new();

    for (idx, (name, values)) in headers.into_iter().zip(columns).enumerate() {
        if Some(idx) == index_col_idx {
            continue; // skip index column from data columns
        }
        out_columns.insert(name.clone(), Column::from_values(values)?);
        column_order.push(name);
    }

    let index = if let Some(idx_pos) = index_col_idx {
        let idx_labels: Vec<IndexLabel> = data_rows
            .iter()
            .map(|row| {
                let cell = row.get(idx_pos).unwrap_or(&calamine::Data::Empty);
                scalar_to_index_label(excel_cell_to_scalar(cell))
            })
            .collect();
        Index::new(idx_labels).set_names(index_name.as_deref())
    } else {
        Index::from_i64((0..data_rows.len() as i64).collect())
    };

    Ok(DataFrame::new_with_column_order(
        index,
        out_columns,
        column_order,
    )?)
}

/// Read an Excel (.xlsx/.xls/.xlsb/.ods) file into a DataFrame.
///
/// Matches `pd.read_excel(path)` for basic usage.
pub fn read_excel(path: &Path, options: &ExcelReadOptions) -> Result<DataFrame, IoError> {
    use calamine::{Reader, open_workbook_auto};

    let mut workbook = open_workbook_auto(path)
        .map_err(|e| IoError::Excel(format!("cannot open workbook: {e}")))?;

    let sheet_name = if let Some(ref name) = options.sheet_name {
        name.clone()
    } else {
        let names = workbook.sheet_names();
        if names.is_empty() {
            return Err(IoError::Excel("workbook contains no sheets".into()));
        }
        names[0].clone()
    };

    let range = workbook
        .worksheet_range(&sheet_name)
        .map_err(|e| IoError::Excel(format!("cannot read sheet '{sheet_name}': {e}")))?;

    let rows: Vec<Vec<calamine::Data>> = range
        .rows()
        .skip(options.skip_rows)
        .map(|r| r.to_vec())
        .collect();

    parse_excel_rows(rows, options)
}

pub fn read_excel_with_index_cols(
    path: &Path,
    options: &ExcelReadOptions,
    index_cols: &[&str],
) -> Result<DataFrame, IoError> {
    let frame = read_excel(path, options)?;
    promote_frame_index_columns(&frame, index_cols)
}

/// Read Excel from in-memory bytes.
pub fn read_excel_bytes(data: &[u8], options: &ExcelReadOptions) -> Result<DataFrame, IoError> {
    use calamine::{Reader, open_workbook_auto_from_rs};

    let cursor = std::io::Cursor::new(data);
    let mut workbook = open_workbook_auto_from_rs(cursor)
        .map_err(|e| IoError::Excel(format!("cannot open workbook from bytes: {e}")))?;

    let sheet_name = if let Some(ref name) = options.sheet_name {
        name.clone()
    } else {
        let names = workbook.sheet_names();
        if names.is_empty() {
            return Err(IoError::Excel("workbook contains no sheets".into()));
        }
        names[0].clone()
    };

    let range = workbook
        .worksheet_range(&sheet_name)
        .map_err(|e| IoError::Excel(format!("cannot read sheet '{sheet_name}': {e}")))?;

    let rows: Vec<Vec<calamine::Data>> = range
        .rows()
        .skip(options.skip_rows)
        .map(|r| r.to_vec())
        .collect();

    parse_excel_rows(rows, options)
}

pub fn read_excel_bytes_with_index_cols(
    data: &[u8],
    options: &ExcelReadOptions,
    index_cols: &[&str],
) -> Result<DataFrame, IoError> {
    let frame = read_excel_bytes(data, options)?;
    promote_frame_index_columns(&frame, index_cols)
}

/// Read multiple sheets from an Excel file.
///
/// Matches `pd.read_excel(path, sheet_name=[...])` when `sheet_name`
/// is a list of sheet names — pandas returns a dict
/// `{name: DataFrame}`. Pass `sheet_names=None` to read every sheet
/// in the workbook (pandas `sheet_name=None`).
///
/// The outer Excel reader options (`has_headers`, `index_col`,
/// `skip_rows`) are applied uniformly to each selected sheet. The
/// per-sheet `sheet_name` option on `options` is ignored here
/// because the explicit `sheet_names` argument drives selection.
/// Read multiple sheets preserving workbook iteration order.
///
/// Matches `pd.read_excel(sheet_name=None)` exactly — pandas returns
/// a `dict` and, since Python 3.7, dict iteration order matches
/// insertion order, which in turn matches workbook sheet position.
/// `BTreeMap` (used by `read_excel_sheets`) would alphabetize, so
/// this sibling returns `Vec<(String, DataFrame)>` to preserve order.
pub fn read_excel_sheets_ordered(
    path: &Path,
    sheet_names: Option<&[String]>,
    options: &ExcelReadOptions,
) -> Result<Vec<(String, DataFrame)>, IoError> {
    use calamine::{Reader, open_workbook_auto};

    let mut workbook = open_workbook_auto(path)
        .map_err(|e| IoError::Excel(format!("cannot open workbook: {e}")))?;
    let available: Vec<String> = workbook.sheet_names();
    // Per br-frankenpandas-c9cb4: HashSet<&str> for O(1) membership;
    // was O(m × n) Vec::iter().any() per requested name.
    let available_set: HashSet<&str> = available.iter().map(String::as_str).collect();
    let selected: Vec<String> = match sheet_names {
        Some(names) => {
            for name in names {
                if !available_set.contains(name.as_str()) {
                    return Err(IoError::Excel(format!(
                        "workbook does not contain sheet {name:?}"
                    )));
                }
            }
            names.to_vec()
        }
        None => available.clone(),
    };
    if selected.is_empty() {
        return Err(IoError::Excel("no sheets selected".to_owned()));
    }
    let mut out = Vec::with_capacity(selected.len());
    for sheet in &selected {
        let range = workbook
            .worksheet_range(sheet)
            .map_err(|e| IoError::Excel(format!("cannot read sheet {sheet:?}: {e}")))?;
        let rows: Vec<Vec<calamine::Data>> = range
            .rows()
            .skip(options.skip_rows)
            .map(|r| r.to_vec())
            .collect();
        let frame = parse_excel_rows(rows, options)?;
        out.push((sheet.clone(), frame));
    }
    Ok(out)
}

/// Byte-based counterpart to `read_excel_sheets_ordered`.
pub fn read_excel_sheets_ordered_bytes(
    data: &[u8],
    sheet_names: Option<&[String]>,
    options: &ExcelReadOptions,
) -> Result<Vec<(String, DataFrame)>, IoError> {
    use calamine::{Reader, open_workbook_auto_from_rs};

    let cursor = std::io::Cursor::new(data);
    let mut workbook = open_workbook_auto_from_rs(cursor)
        .map_err(|e| IoError::Excel(format!("cannot open workbook from bytes: {e}")))?;
    let available: Vec<String> = workbook.sheet_names();
    // Per br-frankenpandas-c9cb4: HashSet<&str> for O(1) membership;
    // was O(m × n) Vec::iter().any() per requested name.
    let available_set: HashSet<&str> = available.iter().map(String::as_str).collect();
    let selected: Vec<String> = match sheet_names {
        Some(names) => {
            for name in names {
                if !available_set.contains(name.as_str()) {
                    return Err(IoError::Excel(format!(
                        "workbook does not contain sheet {name:?}"
                    )));
                }
            }
            names.to_vec()
        }
        None => available.clone(),
    };
    if selected.is_empty() {
        return Err(IoError::Excel("no sheets selected".to_owned()));
    }
    let mut out = Vec::with_capacity(selected.len());
    for sheet in &selected {
        let range = workbook
            .worksheet_range(sheet)
            .map_err(|e| IoError::Excel(format!("cannot read sheet {sheet:?}: {e}")))?;
        let rows: Vec<Vec<calamine::Data>> = range
            .rows()
            .skip(options.skip_rows)
            .map(|r| r.to_vec())
            .collect();
        let frame = parse_excel_rows(rows, options)?;
        out.push((sheet.clone(), frame));
    }
    Ok(out)
}

pub fn read_excel_sheets(
    path: &Path,
    sheet_names: Option<&[String]>,
    options: &ExcelReadOptions,
) -> Result<BTreeMap<String, DataFrame>, IoError> {
    use calamine::{Reader, open_workbook_auto};

    let mut workbook = open_workbook_auto(path)
        .map_err(|e| IoError::Excel(format!("cannot open workbook: {e}")))?;
    let available: Vec<String> = workbook.sheet_names();
    // Per br-frankenpandas-c9cb4: HashSet<&str> for O(1) membership;
    // was O(m × n) Vec::iter().any() per requested name.
    let available_set: HashSet<&str> = available.iter().map(String::as_str).collect();
    let selected: Vec<String> = match sheet_names {
        Some(names) => {
            for name in names {
                if !available_set.contains(name.as_str()) {
                    return Err(IoError::Excel(format!(
                        "workbook does not contain sheet {name:?}"
                    )));
                }
            }
            names.to_vec()
        }
        None => available.clone(),
    };
    if selected.is_empty() {
        return Err(IoError::Excel("no sheets selected".to_owned()));
    }

    let mut out = BTreeMap::new();
    for sheet in &selected {
        let range = workbook
            .worksheet_range(sheet)
            .map_err(|e| IoError::Excel(format!("cannot read sheet {sheet:?}: {e}")))?;
        let rows: Vec<Vec<calamine::Data>> = range
            .rows()
            .skip(options.skip_rows)
            .map(|r| r.to_vec())
            .collect();
        let frame = parse_excel_rows(rows, options)?;
        out.insert(sheet.clone(), frame);
    }
    Ok(out)
}

/// Read multiple sheets from Excel bytes.
///
/// Byte-based counterpart to `read_excel_sheets`.
pub fn read_excel_sheets_bytes(
    data: &[u8],
    sheet_names: Option<&[String]>,
    options: &ExcelReadOptions,
) -> Result<BTreeMap<String, DataFrame>, IoError> {
    use calamine::{Reader, open_workbook_auto_from_rs};

    let cursor = std::io::Cursor::new(data);
    let mut workbook = open_workbook_auto_from_rs(cursor)
        .map_err(|e| IoError::Excel(format!("cannot open workbook from bytes: {e}")))?;
    let available: Vec<String> = workbook.sheet_names();
    // Per br-frankenpandas-c9cb4: HashSet<&str> for O(1) membership;
    // was O(m × n) Vec::iter().any() per requested name.
    let available_set: HashSet<&str> = available.iter().map(String::as_str).collect();
    let selected: Vec<String> = match sheet_names {
        Some(names) => {
            for name in names {
                if !available_set.contains(name.as_str()) {
                    return Err(IoError::Excel(format!(
                        "workbook does not contain sheet {name:?}"
                    )));
                }
            }
            names.to_vec()
        }
        None => available.clone(),
    };
    if selected.is_empty() {
        return Err(IoError::Excel("no sheets selected".to_owned()));
    }

    let mut out = BTreeMap::new();
    for sheet in &selected {
        let range = workbook
            .worksheet_range(sheet)
            .map_err(|e| IoError::Excel(format!("cannot read sheet {sheet:?}: {e}")))?;
        let rows: Vec<Vec<calamine::Data>> = range
            .rows()
            .skip(options.skip_rows)
            .map(|r| r.to_vec())
            .collect();
        let frame = parse_excel_rows(rows, options)?;
        out.insert(sheet.clone(), frame);
    }
    Ok(out)
}

/// Write a DataFrame to an Excel (.xlsx) file.
///
/// Matches `pd.DataFrame.to_excel(path)`.
pub fn write_excel(frame: &DataFrame, path: &Path) -> Result<(), IoError> {
    let bytes = write_excel_bytes(frame)?;
    std::fs::write(path, bytes)?;
    Ok(())
}

fn write_excel_index_label(
    worksheet: &mut rust_xlsxwriter::Worksheet,
    excel_row: u32,
    excel_col: u16,
    label: &IndexLabel,
) -> Result<(), IoError> {
    match label {
        IndexLabel::Int64(v) => {
            worksheet
                .write_number(excel_row, excel_col, *v as f64)
                .map_err(|e| IoError::Excel(format!("write index int: {e}")))?;
        }
        IndexLabel::Utf8(s) => {
            worksheet
                .write_string(excel_row, excel_col, s.as_str())
                .map_err(|e| IoError::Excel(format!("write index string: {e}")))?;
        }
        IndexLabel::Timedelta64(v) => {
            if *v != Timedelta::NAT {
                worksheet
                    .write_string(excel_row, excel_col, Timedelta::format(*v))
                    .map_err(|e| IoError::Excel(format!("write index timedelta: {e}")))?;
            }
        }
        IndexLabel::Datetime64(v) => {
            if *v != i64::MIN {
                worksheet
                    .write_string(excel_row, excel_col, label.to_string())
                    .map_err(|e| IoError::Excel(format!("write index datetime: {e}")))?;
            }
        }
        // Missing labels leave the cell blank, like NAT timedelta/datetime
        // above (pandas writes an empty cell for a NaN index label).
        IndexLabel::Null(_) => {}
    }
    Ok(())
}

fn write_excel_scalar(
    worksheet: &mut rust_xlsxwriter::Worksheet,
    excel_row: u32,
    excel_col: u16,
    scalar: &Scalar,
) -> Result<(), IoError> {
    match scalar {
        Scalar::Int64(v) => {
            worksheet
                .write_number(excel_row, excel_col, *v as f64)
                .map_err(|e| IoError::Excel(format!("write int: {e}")))?;
        }
        Scalar::Float64(v) if !v.is_nan() => {
            worksheet
                .write_number(excel_row, excel_col, *v)
                .map_err(|e| IoError::Excel(format!("write float: {e}")))?;
        }
        Scalar::Bool(b) => {
            worksheet
                .write_boolean(excel_row, excel_col, *b)
                .map_err(|e| IoError::Excel(format!("write bool: {e}")))?;
        }
        Scalar::Utf8(s) => {
            worksheet
                .write_string(excel_row, excel_col, s.as_str())
                .map_err(|e| IoError::Excel(format!("write string: {e}")))?;
        }
        Scalar::Timedelta64(v) => {
            if *v != Timedelta::NAT {
                worksheet
                    .write_string(excel_row, excel_col, Timedelta::format(*v))
                    .map_err(|e| IoError::Excel(format!("write timedelta: {e}")))?;
            }
        }
        Scalar::Datetime64(v) => {
            if *v != Timestamp::NAT {
                worksheet
                    .write_string(excel_row, excel_col, format_datetime_ns(*v))
                    .map_err(|e| IoError::Excel(format!("write datetime: {e}")))?;
            }
        }
        Scalar::Period(v) => {
            if *v != i64::MIN {
                worksheet
                    .write_string(excel_row, excel_col, format!("Period[{v}]"))
                    .map_err(|e| IoError::Excel(format!("write period: {e}")))?;
            }
        }
        Scalar::Interval(iv) => {
            worksheet
                .write_string(excel_row, excel_col, format!("{iv}"))
                .map_err(|e| IoError::Excel(format!("write interval: {e}")))?;
        }
        Scalar::Float64(_) | Scalar::Null(_) => {}
    }
    Ok(())
}

/// Write a DataFrame to Excel (.xlsx) bytes in memory.
///
/// Matches pandas `DataFrame.to_excel()` default index behavior by emitting
/// the index as the first worksheet column.
pub fn write_excel_bytes(frame: &DataFrame) -> Result<Vec<u8>, IoError> {
    write_excel_bytes_with_options(frame, &ExcelWriteOptions::default())
}

/// Options for serializing a DataFrame to Excel.
///
/// Mirrors the subset of `pd.DataFrame.to_excel` parameters that
/// don't depend on the workbook writer itself.
#[derive(Debug, Clone)]
pub struct ExcelWriteOptions {
    /// Target sheet name. Default: `"Sheet1"` (rust_xlsxwriter default).
    pub sheet_name: String,
    /// Whether to write the row index as a leading column. Matches
    /// pandas `index=True|False`. Default: true.
    pub index: bool,
    /// Header label for the index column when `index=true`. When
    /// `None`, the frame's index name is used (falling back to an
    /// empty string). Matches pandas `index_label=...`.
    pub index_label: Option<String>,
    /// Whether to emit the column-name header row. Matches pandas
    /// `header=True|False`. Default: true.
    pub header: bool,
}

impl Default for ExcelWriteOptions {
    fn default() -> Self {
        Self {
            sheet_name: "Sheet1".to_string(),
            index: true,
            index_label: None,
            header: true,
        }
    }
}

/// Serialize a DataFrame to Excel bytes with explicit options.
///
/// Matches `pd.DataFrame.to_excel(sheet_name, index, index_label,
/// header)` for the in-memory byte form. The default `ExcelWriteOptions`
/// reproduces the existing `write_excel_bytes` behavior (index=true,
/// sheet_name="Sheet1").
pub fn write_excel_bytes_with_options(
    frame: &DataFrame,
    options: &ExcelWriteOptions,
) -> Result<Vec<u8>, IoError> {
    if options.index && frame.row_multiindex().is_some() {
        let materialized = materialize_named_row_multiindex_columns(frame)?;
        let mut nested_options = options.clone();
        nested_options.index = false;
        nested_options.index_label = None;
        return write_excel_bytes_with_options(&materialized, &nested_options);
    }

    use rust_xlsxwriter::Workbook;

    let mut workbook = Workbook::new();
    let worksheet = workbook.add_worksheet();
    worksheet
        .set_name(options.sheet_name.as_str())
        .map_err(|e| IoError::Excel(format!("set sheet name: {e}")))?;

    let col_names: Vec<String> = frame.column_names().into_iter().cloned().collect();
    let data_col_offset: u16 = if options.index { 1 } else { 0 };

    // Header row (optional).
    if options.header {
        if options.index {
            let idx_header = options
                .index_label
                .as_deref()
                .unwrap_or_else(|| frame.index().name().unwrap_or(""));
            worksheet
                .write_string(0, 0, idx_header)
                .map_err(|e| IoError::Excel(format!("write index header: {e}")))?;
        }
        for (col_idx, name) in col_names.iter().enumerate() {
            worksheet
                .write_string(0, data_col_offset + col_idx as u16, name.as_str())
                .map_err(|e| IoError::Excel(format!("write header: {e}")))?;
        }
    }

    // Data rows — when header=true the first data row lands at excel
    // row 1; when header=false data starts at row 0.
    let header_rows: u32 = if options.header { 1 } else { 0 };
    let nrows = frame.index().len();
    for row_idx in 0..nrows {
        let excel_row = row_idx as u32 + header_rows;
        if options.index
            && let Some(label) = frame.index().labels().get(row_idx)
        {
            write_excel_index_label(worksheet, excel_row, 0, label)?;
        }
        for (col_idx, name) in col_names.iter().enumerate() {
            if let Some(col) = frame.column(name)
                && let Some(scalar) = col.value(row_idx)
            {
                write_excel_scalar(
                    worksheet,
                    excel_row,
                    data_col_offset + col_idx as u16,
                    scalar,
                )?;
            }
        }
    }

    let buf = workbook
        .save_to_buffer()
        .map_err(|e| IoError::Excel(format!("save workbook: {e}")))?;

    Ok(buf)
}

/// File-based counterpart to `write_excel_bytes_with_options`.
pub fn write_excel_with_options(
    frame: &DataFrame,
    path: &Path,
    options: &ExcelWriteOptions,
) -> Result<(), IoError> {
    let bytes = write_excel_bytes_with_options(frame, options)?;
    std::fs::write(path, bytes)?;
    Ok(())
}

// ── Arrow IPC / Feather I/O ──────────────────────────────────────────────

/// Write a DataFrame to Arrow IPC (Feather v2) bytes in memory.
///
/// Matches `pd.DataFrame.to_feather()`. Feather v2 is the Arrow IPC file format
/// — the fastest columnar interchange format, recommended by pandas over HDF5.
pub fn write_feather_bytes(frame: &DataFrame) -> Result<Vec<u8>, IoError> {
    use arrow::ipc::writer::FileWriter;

    let batch = dataframe_to_record_batch(frame)?;
    let schema = batch.schema();

    let mut buf = Vec::new();
    let mut writer =
        FileWriter::try_new(&mut buf, &schema).map_err(|e| IoError::Arrow(e.to_string()))?;
    writer
        .write(&batch)
        .map_err(|e| IoError::Arrow(e.to_string()))?;
    writer.finish().map_err(|e| IoError::Arrow(e.to_string()))?;
    Ok(buf)
}

/// Read a DataFrame from Arrow IPC (Feather v2) bytes in memory.
///
/// Matches `pd.read_feather()`.
pub fn read_feather_bytes(data: &[u8]) -> Result<DataFrame, IoError> {
    use arrow::ipc::reader::FileReader;

    let cursor = std::io::Cursor::new(data);
    let reader = FileReader::try_new(cursor, None).map_err(|e| IoError::Arrow(e.to_string()))?;

    let mut all_frames: Vec<DataFrame> = Vec::new();
    for batch_result in reader {
        let batch = batch_result.map_err(|e| IoError::Arrow(e.to_string()))?;
        all_frames.push(record_batch_to_dataframe(&batch)?);
    }

    if all_frames.is_empty() {
        return Ok(DataFrame::new_with_column_order(
            Index::new(vec![]),
            BTreeMap::new(),
            vec![],
        )?);
    }

    if all_frames.len() == 1 {
        if let Some(frame) = all_frames.into_iter().next() {
            return Ok(frame);
        }
        return Err(IoError::Arrow(
            "feather reader produced zero record batches".to_owned(),
        ));
    }

    let refs: Vec<&DataFrame> = all_frames.iter().collect();
    fp_frame::concat_dataframes(&refs).map_err(IoError::from)
}

/// Write a DataFrame to an Arrow IPC (Feather v2) file.
///
/// Matches `pd.DataFrame.to_feather(path)`.
pub fn write_feather(frame: &DataFrame, path: &Path) -> Result<(), IoError> {
    let bytes = write_feather_bytes(frame)?;
    std::fs::write(path, bytes)?;
    Ok(())
}

/// Read a DataFrame from an Arrow IPC (Feather v2) file.
///
/// Matches `pd.read_feather(path)`.
pub fn read_feather(path: &Path) -> Result<DataFrame, IoError> {
    let data = std::fs::read(path)?;
    read_feather_bytes(&data)
}

/// Write a DataFrame to Arrow IPC stream bytes (streaming format, no random access).
///
/// Unlike Feather (file format), the stream format has no footer and supports
/// streaming reads without seeking. Used for inter-process communication.
pub fn write_ipc_stream_bytes(frame: &DataFrame) -> Result<Vec<u8>, IoError> {
    use arrow::ipc::writer::StreamWriter;

    let batch = dataframe_to_record_batch(frame)?;
    let schema = batch.schema();

    let mut buf = Vec::new();
    let mut writer =
        StreamWriter::try_new(&mut buf, &schema).map_err(|e| IoError::Arrow(e.to_string()))?;
    writer
        .write(&batch)
        .map_err(|e| IoError::Arrow(e.to_string()))?;
    writer.finish().map_err(|e| IoError::Arrow(e.to_string()))?;
    Ok(buf)
}

/// Read a DataFrame from Arrow IPC stream bytes (streaming format).
pub fn read_ipc_stream_bytes(data: &[u8]) -> Result<DataFrame, IoError> {
    use arrow::ipc::reader::StreamReader;

    let cursor = std::io::Cursor::new(data);
    let reader = StreamReader::try_new(cursor, None).map_err(|e| IoError::Arrow(e.to_string()))?;

    let mut all_frames: Vec<DataFrame> = Vec::new();
    for batch_result in reader {
        let batch = batch_result.map_err(|e| IoError::Arrow(e.to_string()))?;
        all_frames.push(record_batch_to_dataframe(&batch)?);
    }

    if all_frames.is_empty() {
        return Ok(DataFrame::new_with_column_order(
            Index::new(vec![]),
            BTreeMap::new(),
            vec![],
        )?);
    }

    if all_frames.len() == 1 {
        if let Some(frame) = all_frames.into_iter().next() {
            return Ok(frame);
        }
        return Err(IoError::Arrow(
            "ipc stream reader produced zero record batches".to_owned(),
        ));
    }

    let refs: Vec<&DataFrame> = all_frames.iter().collect();
    fp_frame::concat_dataframes(&refs).map_err(IoError::from)
}

// ── SQL I/O ─────────────────────────────────────────────────────────────

/// Options for writing a DataFrame to SQL.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SqlIfExists {
    /// Raise an error if the table already exists.
    Fail,
    /// Drop the table and recreate it.
    Replace,
    /// Insert new rows into the existing table.
    Append,
}

/// Strategy for emitting INSERT statements during `write_sql`.
///
/// Matches `pd.DataFrame.to_sql(.., method=...)` shape:
/// `Single` (default) emits one `INSERT INTO t VALUES (?, ...)` per row,
/// reusing a prepared statement under a transaction. `Multi` builds a
/// single multi-row `INSERT INTO t VALUES (...), (...), ...` statement
/// per chunk, where chunk size is `max_param_count() / num_cols` (or
/// the whole frame when the backend reports no max). `Multi` typically
/// wins on backends with high per-statement overhead (PostgreSQL,
/// MySQL); SQLite is already fast under prepared-statement reuse so the
/// gap there is small.
///
/// Per br-frankenpandas-i0ml (fd90.19).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum SqlInsertMethod {
    /// One INSERT per row, prepared once and re-bound per row.
    #[default]
    Single,
    /// Multi-row INSERT, chunked by the backend's parameter limit.
    Multi,
}

/// Options for reading SQL query results into a DataFrame.
#[derive(Debug, Clone)]
pub struct SqlReadOptions {
    /// Positional parameters to bind to `?` placeholders in the SQL query.
    pub params: Option<Vec<Scalar>>,
    /// Column names to coerce via pandas-style parse_dates handling.
    /// Currently supports explicit column-name selection.
    pub parse_dates: Option<Vec<String>>,
    /// Promote decimal-like SQL text result columns to Float64.
    ///
    /// This is an opt-in form of pandas' `coerce_float` behavior for
    /// backends that expose NUMERIC/DECIMAL/MONEY values through text.
    /// Columns containing any non-numeric strings are left unchanged.
    pub coerce_float: bool,
    /// Per-column dtype override applied after row materialization.
    ///
    /// Matches `pd.read_sql(.., dtype={'col': 'float64'})`. Each entry casts
    /// the named column to the declared dtype using `fp_types::cast_scalar_owned`.
    /// Map entries for columns not present in the result are silently
    /// ignored (matches pandas). Columns also listed in `parse_dates` are
    /// skipped to avoid double-cast errors — parse_dates wins.
    ///
    /// Per br-frankenpandas-l9pt (fd90.11).
    pub dtype: Option<BTreeMap<String, DType>>,
    /// Optional schema namespace for `read_sql_table` lookups.
    ///
    /// Matches `pd.read_sql_table(table, con, schema=...)`. When the
    /// backend reports `supports_schemas() == true` (PostgreSQL, MySQL,
    /// MSSQL, etc.) and `schema` is `Some(s)`, the SELECT references
    /// `s.table` with each part quoted by `conn.quote_identifier(...)`.
    /// When the backend reports `supports_schemas() == false` (SQLite),
    /// any `Some(s)` here is rejected before query execution. Pandas /
    /// SQLAlchemy raises `NotImplementedError` on that surface; failing
    /// closed avoids silently reading an unqualified table from the wrong
    /// namespace.
    ///
    /// Per br-frankenpandas-u6zn (fd90.14).
    pub schema: Option<String>,
    /// Optional projection list for `read_sql_table` reads.
    ///
    /// Matches `pd.read_sql_table(table, con, columns=[...])`. When
    /// `Some(list)`, the emitted SELECT projects only those columns
    /// (and in that order) instead of `SELECT *`. `None` preserves
    /// `SELECT *`. An empty Vec is rejected with `IoError::Sql` —
    /// pandas raises ValueError there. Each entry is validated via
    /// the standard alphanumeric+underscore policy.
    ///
    /// Note: `read_sql` / `read_sql_query` ignore this field — it
    /// only takes effect on `read_sql_table*` paths, where
    /// frankenpandas builds the SELECT itself.
    ///
    /// Per br-frankenpandas-d3e9 (fd90.34).
    pub columns: Option<Vec<String>>,
    /// Optional column name to promote to the DataFrame index.
    ///
    /// Matches `pd.read_sql(.., index_col=...)` and
    /// `pd.read_sql_table(table, con, index_col=...)`. When
    /// `Some(name)`, after row materialization the named column is
    /// removed from the result and used as the DataFrame index. The
    /// column must exist in the read result (or in the projection
    /// when `columns` is also set). `None` preserves the default
    /// RangeIndex.
    ///
    /// Empty string is rejected with `IoError::Sql` to match
    /// pandas' ValueError. List-of-strings (for MultiIndex) is out
    /// of scope for this slice — single index only.
    ///
    /// Per br-frankenpandas-c1h9 (fd90.36).
    pub index_col: Option<String>,
}

impl Default for SqlReadOptions {
    /// Per br-frankenpandas-o0x6 (fd90.41): pandas defaults
    /// `coerce_float=True` for `read_sql` / `read_sql_query` /
    /// `read_sql_table` so we follow suit. Other defaults are the
    /// natural empty / None values.
    fn default() -> Self {
        Self {
            params: None,
            parse_dates: None,
            coerce_float: true,
            dtype: None,
            schema: None,
            columns: None,
            index_col: None,
        }
    }
}

/// Options for writing a DataFrame to SQL.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SqlWriteOptions {
    /// Behavior when the target table already exists.
    pub if_exists: SqlIfExists,
    /// Whether to materialize the DataFrame index as the leading SQL column.
    pub index: bool,
    /// Optional override for the emitted index column name.
    pub index_label: Option<String>,
    /// Optional schema namespace for CREATE TABLE / INSERT routing.
    ///
    /// Matches `pd.DataFrame.to_sql(table, con, schema=...)`. When the
    /// backend reports `supports_schemas() == true` and `schema` is
    /// `Some(s)`, generated CREATE TABLE / INSERT statements target
    /// `\"s\".\"table\"`. On backends that report `false` (SQLite),
    /// `Some(s)` is silently ignored — preserves SQLite users' existing
    /// option structs.
    ///
    /// Per br-frankenpandas-udn6 (fd90.15).
    pub schema: Option<String>,
    /// Per-column SQL-type override applied during CREATE TABLE.
    ///
    /// Matches `pd.DataFrame.to_sql(.., dtype={'amount': 'NUMERIC(10,2)'})`.
    /// Each entry's value is the literal SQL type string emitted in the
    /// column definition for that column. Map entries for columns not
    /// in the frame are silently ignored (matches pandas). Falls back
    /// to `conn.dtype_sql(DType)` when no override is present.
    ///
    /// Per br-frankenpandas-ev2s (fd90.18).
    pub dtype: Option<BTreeMap<String, String>>,
    /// INSERT-emission strategy.
    ///
    /// Default `Single` matches pandas' default: one INSERT per row,
    /// re-binding a prepared statement under a transaction. `Multi`
    /// switches to multi-row VALUES batched by `conn.max_param_count()`,
    /// matching `pd.to_sql(.., method='multi')`.
    ///
    /// Per br-frankenpandas-i0ml (fd90.19).
    pub method: SqlInsertMethod,
    /// Maximum rows per transaction-bounded INSERT chunk.
    ///
    /// Matches `pd.DataFrame.to_sql(.., chunksize=...)`. When `Some(n)`,
    /// the row emit loop batches into chunks of `n` rows, each routed
    /// through its own `insert_rows` call (which on transactional
    /// backends commits a fresh transaction per chunk). This caps WAL /
    /// journal size for huge frames where the default `Single`
    /// single-transaction mode would balloon. For `Multi` mode the
    /// effective per-chunk row count is `min(chunksize,
    /// max_param_count / num_cols)`. `None` preserves existing
    /// single-transaction semantics.
    ///
    /// `Some(0)` is rejected — pandas raises ValueError there too.
    ///
    /// Per br-frankenpandas-ls9z (fd90.33).
    pub chunksize: Option<usize>,
}

/// Backend-agnostic in-memory representation of a SQL query result.
#[derive(Debug, Clone, PartialEq)]
pub struct SqlQueryResult {
    pub columns: Vec<String>,
    pub rows: Vec<Vec<Scalar>>,
}

type SqlColumnDtypeHints = Vec<Option<DType>>;
type SqlMaterializedColumns = (Vec<String>, Vec<Vec<Scalar>>, SqlColumnDtypeHints);

/// Backend-neutral SQL column metadata.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SqlColumnSchema {
    pub name: String,
    pub declared_type: Option<String>,
    pub nullable: bool,
    pub default_value: Option<String>,
    pub primary_key_ordinal: Option<usize>,
    /// Column-level comment text, when the backend exposes one.
    ///
    /// Per br-frankenpandas-cfld (fd90.35). SQLite has no column-comment
    /// storage so the rusqlite override always emits `None`. PostgreSQL
    /// impls populate from `pg_catalog.pg_description.col_description`;
    /// MySQL uses `information_schema.columns.column_comment`; MSSQL
    /// reads from `sys.extended_properties`. Companion to the
    /// table-level `table_comment` (fd90.32) — together they round
    /// out SQLAlchemy.Inspector.get_columns() parity (its dict shape
    /// includes a `'comment'` key).
    pub comment: Option<String>,
    /// Whether the column is auto-incrementing.
    ///
    /// Per br-frankenpandas-bkl2 (fd90.37). Completes
    /// SQLAlchemy.Inspector.get_columns() parity (the dict shape
    /// includes an `'autoincrement'` key).
    ///
    /// SQLite detection rule (in the rusqlite `table_schema`
    /// override): true when `declared_type` is `INTEGER`
    /// (case-insensitive) AND the column is the sole primary key
    /// (`primary_key_ordinal == Some(0)`) — SQLite makes
    /// `INTEGER PRIMARY KEY` an alias for the auto-increment
    /// `rowid`. The optional `AUTOINCREMENT` keyword affects
    /// whether IDs are reused after delete but does not change the
    /// "is auto-incrementing" property pandas cares about.
    ///
    /// Other backends: PG SERIAL/BIGSERIAL/IDENTITY columns
    /// `true`; MySQL `AUTO_INCREMENT` modifier `true`; otherwise
    /// `false`.
    pub autoincrement: bool,
}

/// Backend-neutral SQL table metadata.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SqlTableSchema {
    pub table_name: String,
    pub columns: Vec<SqlColumnSchema>,
}

impl SqlTableSchema {
    pub fn column(&self, name: &str) -> Option<&SqlColumnSchema> {
        self.columns.iter().find(|column| column.name == name)
    }
}

/// Backend-neutral SQL index metadata.
///
/// Per br-frankenpandas-bgv9 (fd90.28). Used by `list_indexes` /
/// `list_sql_indexes` to surface user-defined indexes so callers can
/// align with `SQLAlchemy.Inspector.get_indexes()` shape.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SqlIndexSchema {
    pub name: String,
    pub columns: Vec<String>,
    pub unique: bool,
}

/// Backend-neutral SQL unique-constraint metadata.
///
/// Per br-frankenpandas-sh4v (fd90.31). Surfaces inline `UNIQUE`
/// declarations and `UNIQUE (...)` table constraints separately from
/// user-created `CREATE UNIQUE INDEX` (those land in
/// `SqlIndexSchema` via `list_indexes`). `name` may be backend-
/// generated (SQLite reports `sqlite_autoindex_<table>_<n>`) when
/// the constraint was declared inline without an explicit name —
/// we surface the backend's name verbatim rather than fabricating.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SqlUniqueConstraintSchema {
    pub name: String,
    pub columns: Vec<String>,
}

/// Bundle of all introspection metadata for a single SQL table.
///
/// Per br-frankenpandas-76mw (fd90.40). Returned by
/// `SqlInspector::reflect_table` to give callers the full picture of
/// a table in one call instead of 5 separate trait dispatches.
/// Mirrors the bundled view that `SQLAlchemy.MetaData.reflect_table`
/// builds internally.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SqlReflectedTable {
    pub table_name: String,
    pub columns: Vec<SqlColumnSchema>,
    pub primary_key_columns: Vec<String>,
    pub indexes: Vec<SqlIndexSchema>,
    pub foreign_keys: Vec<SqlForeignKeySchema>,
    pub unique_constraints: Vec<SqlUniqueConstraintSchema>,
    pub comment: Option<String>,
}

impl SqlReflectedTable {
    /// Look up a column by name. Mirrors `SqlTableSchema::column`.
    ///
    /// Per br-frankenpandas-63ac (fd90.51).
    #[must_use]
    pub fn column(&self, name: &str) -> Option<&SqlColumnSchema> {
        self.columns.iter().find(|c| c.name == name)
    }

    /// Look up an index by name.
    ///
    /// Per br-frankenpandas-63ac (fd90.51).
    #[must_use]
    pub fn index(&self, name: &str) -> Option<&SqlIndexSchema> {
        self.indexes.iter().find(|i| i.name == name)
    }

    /// Look up a unique constraint by name (backend-generated names
    /// like `sqlite_autoindex_*` count too — match what
    /// `list_unique_constraints` surfaced).
    ///
    /// Per br-frankenpandas-63ac (fd90.51).
    #[must_use]
    pub fn unique_constraint(&self, name: &str) -> Option<&SqlUniqueConstraintSchema> {
        self.unique_constraints.iter().find(|u| u.name == name)
    }

    /// Find every foreign key whose `columns` slice contains `column_name`.
    ///
    /// A given column may participate in multiple FK constraints (e.g.
    /// the same column referenced by separate FKs to different parents
    /// — rare but valid SQL). Returns the matching FKs in their
    /// declaration order from PRAGMA foreign_key_list.
    ///
    /// Per br-frankenpandas-63ac (fd90.51).
    #[must_use]
    pub fn foreign_keys_for_column(&self, column_name: &str) -> Vec<&SqlForeignKeySchema> {
        self.foreign_keys
            .iter()
            .filter(|fk| fk.columns.iter().any(|c| c == column_name))
            .collect()
    }

    /// Find every index whose `columns` slice contains `column_name`.
    ///
    /// Matches multi-column indexes where the column appears at any
    /// position (first, middle, last) — useful for answering "is this
    /// column indexed" rather than the more restrictive "is this
    /// column the leading entry of an index" question.
    ///
    /// Per br-frankenpandas-37uy (fd90.52).
    #[must_use]
    pub fn indexes_for_column(&self, column_name: &str) -> Vec<&SqlIndexSchema> {
        self.indexes
            .iter()
            .filter(|i| i.columns.iter().any(|c| c == column_name))
            .collect()
    }

    /// Find every UNIQUE constraint whose `columns` slice contains
    /// `column_name`.
    ///
    /// Same any-position match semantics as `indexes_for_column` and
    /// `foreign_keys_for_column`.
    ///
    /// Per br-frankenpandas-37uy (fd90.52).
    #[must_use]
    pub fn unique_constraints_for_column(
        &self,
        column_name: &str,
    ) -> Vec<&SqlUniqueConstraintSchema> {
        self.unique_constraints
            .iter()
            .filter(|u| u.columns.iter().any(|c| c == column_name))
            .collect()
    }
}

/// Backend-neutral SQL foreign-key constraint metadata.
///
/// Per br-frankenpandas-uht8 (fd90.29). Aligns with
/// `SQLAlchemy.Inspector.get_foreign_keys()` shape: a single FK
/// constraint may span multiple columns (composite FK), and
/// `columns[i]` references `referenced_columns[i]` on
/// `referenced_table`. `constraint_name` is `None` for SQLite
/// inline FKs declared without an explicit CONSTRAINT name (PRAGMA
/// foreign_key_list does not surface a name, so we return None
/// there rather than fabricating one).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SqlForeignKeySchema {
    pub constraint_name: Option<String>,
    pub columns: Vec<String>,
    pub referenced_table: String,
    pub referenced_columns: Vec<String>,
}

/// Iterator over DataFrame chunks produced by a SQL query.
pub struct SqlChunkIterator<'conn> {
    state: SqlChunkIteratorState<'conn>,
}

enum SqlChunkIteratorState<'conn> {
    Materialized {
        headers: Vec<String>,
        columns: Vec<Vec<Scalar>>,
        dtype_hints: SqlColumnDtypeHints,
        chunk_size: usize,
        next_row: usize,
    },
    Paged {
        conn: &'conn dyn SqlConnection,
        query: String,
        options: SqlReadOptions,
        headers: Vec<String>,
        chunk_size: usize,
        next_offset: usize,
        finished: bool,
    },
}

impl std::fmt::Debug for SqlChunkIterator<'_> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match &self.state {
            SqlChunkIteratorState::Materialized {
                headers,
                columns,
                dtype_hints: _,
                chunk_size,
                next_row,
            } => f
                .debug_struct("SqlChunkIterator")
                .field("mode", &"materialized")
                .field("headers", headers)
                .field("row_count", &columns.first().map_or(0, Vec::len))
                .field("chunk_size", chunk_size)
                .field("next_row", next_row)
                .finish(),
            SqlChunkIteratorState::Paged {
                query,
                headers,
                chunk_size,
                next_offset,
                finished,
                ..
            } => f
                .debug_struct("SqlChunkIterator")
                .field("mode", &"paged")
                .field("query", query)
                .field("headers", headers)
                .field("chunk_size", chunk_size)
                .field("next_offset", next_offset)
                .field("finished", finished)
                .finish(),
        }
    }
}

impl<'conn> SqlChunkIterator<'conn> {
    fn materialized(
        headers: Vec<String>,
        columns: Vec<Vec<Scalar>>,
        dtype_hints: SqlColumnDtypeHints,
        chunk_size: usize,
    ) -> Self {
        Self {
            state: SqlChunkIteratorState::Materialized {
                headers,
                columns,
                dtype_hints,
                chunk_size,
                next_row: 0,
            },
        }
    }

    fn paged<C: SqlConnection + 'conn>(
        conn: &'conn C,
        query: &str,
        options: &SqlReadOptions,
        chunk_size: usize,
    ) -> Result<Self, IoError> {
        let headers = sql_paged_query_headers(conn, query, options)?;
        Ok(Self {
            state: SqlChunkIteratorState::Paged {
                conn,
                query: sql_trim_chunk_source(query)?.to_owned(),
                options: options.clone(),
                headers,
                chunk_size,
                next_offset: 0,
                finished: false,
            },
        })
    }

    fn headers(&self) -> &[String] {
        match &self.state {
            SqlChunkIteratorState::Materialized { headers, .. }
            | SqlChunkIteratorState::Paged { headers, .. } => headers,
        }
    }
}

impl Iterator for SqlChunkIterator<'_> {
    type Item = Result<DataFrame, IoError>;

    fn next(&mut self) -> Option<Self::Item> {
        match &mut self.state {
            SqlChunkIteratorState::Materialized {
                headers,
                columns,
                dtype_hints,
                chunk_size,
                next_row,
            } => {
                let row_count = columns.first().map_or(0, Vec::len);
                if *next_row >= row_count {
                    return None;
                }

                let start = *next_row;
                let end = start.saturating_add(*chunk_size).min(row_count);
                *next_row = end;

                let chunk_columns = columns
                    .iter()
                    .map(|column| column[start..end].to_vec())
                    .collect();
                Some(dataframe_from_sql_columns(
                    headers.clone(),
                    chunk_columns,
                    dtype_hints.clone(),
                ))
            }
            SqlChunkIteratorState::Paged {
                conn,
                query,
                options,
                chunk_size,
                next_offset,
                finished,
                ..
            } => {
                if *finished {
                    return None;
                }

                let page =
                    sql_query_to_columns_paged(*conn, query, options, *chunk_size, *next_offset);
                Some(match page {
                    Ok((headers, columns, dtype_hints)) => {
                        let row_count = columns.first().map_or(0, Vec::len);
                        if row_count == 0 {
                            *finished = true;
                            return None;
                        }
                        if row_count < *chunk_size {
                            *finished = true;
                        }
                        *next_offset = next_offset.saturating_add(row_count);
                        dataframe_from_sql_columns(headers, columns, dtype_hints)
                    }
                    Err(err) => {
                        *finished = true;
                        Err(err)
                    }
                })
            }
        }
    }
}

/// Iterator over SQL DataFrame chunks with optional per-chunk index promotion.
pub struct SqlIndexedChunkIterator<'conn> {
    inner: SqlChunkIterator<'conn>,
    index_col: Option<String>,
}

impl std::fmt::Debug for SqlIndexedChunkIterator<'_> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SqlIndexedChunkIterator")
            .field("inner", &self.inner)
            .field("index_col", &self.index_col)
            .finish()
    }
}

impl Iterator for SqlIndexedChunkIterator<'_> {
    type Item = Result<DataFrame, IoError>;

    fn next(&mut self) -> Option<Self::Item> {
        let chunk = self.inner.next()?;
        Some(match (chunk, self.index_col.as_deref()) {
            (Ok(frame), Some(index_col)) => apply_sql_index_col(frame, Some(index_col)),
            (Ok(frame), None) => Ok(frame),
            (Err(err), _) => Err(err),
        })
    }
}

fn sql_indexed_chunks<'conn>(
    inner: SqlChunkIterator<'conn>,
    index_col: Option<&str>,
) -> Result<SqlIndexedChunkIterator<'conn>, IoError> {
    if let Some(col_name) = index_col {
        if col_name.is_empty() {
            return Err(IoError::Sql(
                "index_col: empty string is not a valid column name".to_owned(),
            ));
        }
        if !inner.headers().iter().any(|header| header == col_name) {
            return Err(IoError::Sql(format!(
                "index_col {col_name:?} not present in result columns"
            )));
        }
    }
    Ok(SqlIndexedChunkIterator {
        inner,
        index_col: index_col.map(str::to_owned),
    })
}

/// Minimal SQL connection surface needed by FrankenPandas SQL IO.
pub trait SqlConnection {
    fn query(&self, query: &str, params: &[Scalar]) -> Result<SqlQueryResult, IoError>;

    /// Return optional dtype hints for each result column in `query`.
    ///
    /// Backends that expose declared result-column types should override this
    /// so empty/all-null SQL results keep their table schema instead of
    /// falling back to `DType::Null`.
    fn query_column_dtypes(
        &self,
        _query: &str,
        _params: &[Scalar],
    ) -> Result<Vec<Option<DType>>, IoError> {
        Ok(Vec::new())
    }

    /// Whether `read_sql_chunks*` may page this backend with a bounded
    /// `LIMIT`/`OFFSET` wrapper instead of materializing the whole result
    /// before the first chunk. Defaults to `false` so lightweight test
    /// doubles and custom backends keep the legacy behavior until they opt in.
    fn supports_paged_sql_chunks(&self) -> bool {
        false
    }

    fn execute_batch(&self, sql: &str) -> Result<(), IoError>;

    fn table_exists(&self, table_name: &str) -> Result<bool, IoError>;

    fn insert_rows(&self, insert_sql: &str, rows: &[Vec<Scalar>]) -> Result<(), IoError>;

    fn dtype_sql(&self, dtype: DType) -> &'static str;

    fn index_dtype_sql(&self, index: &Index) -> &'static str;

    /// Return the bind marker for the one-based parameter ordinal.
    ///
    /// SQLite and MySQL accept `?`; PostgreSQL-style backends use `$1`,
    /// `$2`, ... . Keeping marker generation on the backend trait lets
    /// write_sql stay generic without leaking backend dialect branches.
    fn parameter_marker(&self, _ordinal: usize) -> String {
        "?".to_owned()
    }

    // ── Backend-capability + dialect probes (br-frankenpandas-6dtf) ─────
    //
    // Default impls return conservative values so existing implementations
    // stay backwards-compatible; concrete backends override per their
    // engine. Phase 2 wires these probes into the read_sql / read_sql_table
    // dispatch path so per-backend SQL quirks (RETURNING, max param count,
    // transaction semantics) can fan out without leaking concrete types.

    /// Short identifier for this backend's SQL dialect.
    ///
    /// Used by diagnostics + DISCREPANCIES.md routing. Backends should
    /// override with the canonical pandas/SQLAlchemy dialect name:
    /// `"sqlite"`, `"postgresql"`, `"mysql"`, `"mariadb"`, `"oracle"`, etc.
    /// Default `"unknown"` flags un-customized impls during reviews.
    fn dialect_name(&self) -> &'static str {
        "unknown"
    }

    /// Whether this backend honors `INSERT ... RETURNING ...` natively.
    ///
    /// Drives the write_sql path's choice between RETURNING-based row
    /// retrieval and a follow-up SELECT. Default `false` is the
    /// conservative choice (forces follow-up SELECT path) until each
    /// backend opts in.
    fn supports_returning(&self) -> bool {
        false
    }

    /// Hard upper bound on bound-parameter count per statement, if known.
    ///
    /// SQLite (3.32+): 32766. PostgreSQL: 65535. MySQL: 65535. Backends
    /// that don't surface a meaningful cap return `None`. The bulk-insert
    /// path uses this to chunk multi-row INSERTs so a single executemany
    /// stays under the backend's parameter ceiling.
    fn max_param_count(&self) -> Option<usize> {
        None
    }

    /// Maximum identifier length supported by the backend, or `None`
    /// when no documented limit exists (or the limit is irrelevant for
    /// the deployment).
    ///
    /// Per br-frankenpandas-cs81 (fd90.26). Defaults to `None`. Known
    /// caps: PostgreSQL = 63, MySQL = 64, MSSQL = 128, Oracle = 30
    /// (pre-12.2) or 128 (12.2+), SQLite = no documented limit.
    /// Useful for to_sql validation when emitting auto-generated
    /// index/constraint/column names that could otherwise exceed
    /// backend limits and produce truncated or rejected DDL.
    fn max_identifier_length(&self) -> Option<usize> {
        None
    }

    /// Run `f` inside a transaction. The default impl runs `f` without
    /// BEGIN/COMMIT — backends that support transactions should override
    /// to wrap in their native transaction primitive (rusqlite `BEGIN`,
    /// tokio-postgres `BEGIN`, mysql `START TRANSACTION`, ...). On `Err`
    /// from `f`, transactional backends roll back; on `Ok` they commit.
    ///
    /// The default impl is intentionally a no-op so non-transactional
    /// connection wrappers (e.g. test doubles) compile without
    /// implementation effort. Production backends MUST override.
    fn with_transaction<T, F>(&self, f: F) -> Result<T, IoError>
    where
        F: FnOnce(&Self) -> Result<T, IoError>,
        Self: Sized,
    {
        f(self)
    }

    /// Quote a SQL identifier (table name, column name, schema name) for
    /// safe inclusion in a generated statement.
    ///
    /// Default impl: ANSI `"..."` form with embedded `"` doubled (matches
    /// SQLite + PostgreSQL). MySQL/MariaDB backends must override to
    /// produce `\`...\`` (backtick). MSSQL backends use `[...]`. Per
    /// br-frankenpandas-2y7w (fd90.10).
    ///
    /// NUL bytes in the identifier are rejected (security: prevents
    /// statement-injection via embedded null terminators in C-string
    /// driver layers).
    fn quote_identifier(&self, ident: &str) -> Result<String, IoError> {
        if ident.contains('\0') {
            return Err(IoError::Sql("invalid SQL identifier: NUL byte".to_owned()));
        }
        Ok(format!("\"{}\"", ident.replace('"', "\"\"")))
    }

    /// Whether this backend exposes multi-schema namespacing.
    ///
    /// PostgreSQL / MySQL / MariaDB / MSSQL / Oracle: true. SQLite (one
    /// schema per file connection — though ATTACH adds named schemas as
    /// a special case): false. Drives the `pd.read_sql_table(.., schema=X)`
    /// path's choice between qualifying the table reference (`schema.table`)
    /// and a connection-level pre-SET. Per br-frankenpandas-6dk9 (fd90.13).
    fn supports_schemas(&self) -> bool {
        false
    }

    /// Default schema for unqualified table references, if the backend
    /// has one.
    ///
    /// PostgreSQL: `'public'` (or whatever the connection's `search_path`
    /// resolves to first). MySQL: the database name passed to the
    /// connection URL. SQLite: `None` (single namespace). The `read_sql_table`
    /// dispatch uses this when the user passes `schema=None` to choose
    /// between a bare `SELECT * FROM \"table\"` and a schema-qualified form.
    /// Default `None` keeps behavior identical to today's SQLite-only path.
    fn default_schema(&self) -> Option<String> {
        None
    }

    /// Schema-aware table-existence check.
    ///
    /// Per br-frankenpandas-70d1 (fd90.17). Default impl delegates to
    /// `table_exists(table)` and ignores the schema argument — matches
    /// single-namespace embedded backends like SQLite. Multi-schema
    /// backends (PostgreSQL, MySQL, MSSQL) override to scope the check
    /// to the requested schema, so write_sql's `Fail` branch correctly
    /// distinguishes `analytics.users` from `audit.users`. The schema
    /// arg passes through unchanged — backends MAY consult
    /// `default_schema()` for their own fallback logic when `schema`
    /// is `None` (per fd90.57: this fallback is NOT applied by the
    /// default impl or the SQLite override).
    fn table_exists_in_schema(
        &self,
        table_name: &str,
        _schema: Option<&str>,
    ) -> Result<bool, IoError> {
        self.table_exists(table_name)
    }

    /// List user-visible table names, optionally scoped to `schema`.
    ///
    /// Per br-frankenpandas-vhq2 (fd90.20). Default impl returns an empty
    /// vector — backends that cannot introspect (or that haven't yet
    /// implemented this method) report "no tables visible" rather than
    /// raising. Multi-schema backends (PostgreSQL, MySQL, MSSQL) override
    /// to query their information_schema; embedded backends (SQLite)
    /// override to query their internal catalog and ignore `schema`.
    fn list_tables(&self, _schema: Option<&str>) -> Result<Vec<String>, IoError> {
        Ok(Vec::new())
    }

    /// Introspect a table's column metadata, optionally schema-scoped.
    ///
    /// Per br-frankenpandas-w43q (fd90.21). Returns `Ok(None)` if the
    /// table does not exist. Default impl returns `Ok(None)` for
    /// backends that cannot introspect; rusqlite overrides to use
    /// `PRAGMA table_info`. Multi-schema backends override to query
    /// `information_schema.columns` filtered by `schema`. Schema arg is
    /// silently ignored when `supports_schemas() == false`.
    fn table_schema(
        &self,
        _table_name: &str,
        _schema: Option<&str>,
    ) -> Result<Option<SqlTableSchema>, IoError> {
        Ok(None)
    }

    /// List user-visible schemas (PostgreSQL "schemas", MySQL "databases").
    ///
    /// Per br-frankenpandas-lxhi (fd90.22). Default impl returns an empty
    /// vector. Single-namespace backends (SQLite) return empty as well —
    /// they have no meaningful schema concept. Multi-schema backends
    /// (PostgreSQL, MySQL, MSSQL) override to query their catalog and
    /// filter out internal/system schemas (`pg_*`, `information_schema`,
    /// `mysql`, `performance_schema`, etc.) so user-visible schemas
    /// surface cleanly.
    fn list_schemas(&self) -> Result<Vec<String>, IoError> {
        Ok(Vec::new())
    }

    /// Probe the backend server's version string.
    ///
    /// Per br-frankenpandas-e23k (fd90.24). Useful for dialect-version
    /// gating (INSERT ... RETURNING needs PG 8.2+ / SQLite 3.35.0+,
    /// JSON operators need MySQL 5.7.8+, etc.) and for diagnostics.
    /// Default impl returns `Ok(None)` so backends that can't probe
    /// (or that haven't yet implemented this) report "unknown" rather
    /// than raising. rusqlite override returns the SQLite library
    /// version. PostgreSQL/MySQL impls should override with
    /// `SHOW server_version` / `SELECT VERSION()`.
    fn server_version(&self) -> Result<Option<String>, IoError> {
        Ok(None)
    }

    /// List user-visible view names, optionally scoped to `schema`.
    ///
    /// Per br-frankenpandas-gm3r (fd90.30). Default impl returns an
    /// empty vector. rusqlite override queries `sqlite_master WHERE
    /// type='view'`, excluding internal `sqlite_*` views. Multi-schema
    /// backends override with `information_schema.views` filtered by
    /// the schema arg. Schema is silently ignored when
    /// `supports_schemas() == false`. Companion to `list_tables` —
    /// pandas/SQLAlchemy keep tables and views in distinct buckets so
    /// `pd.read_sql_table` can distinguish them.
    fn list_views(&self, _schema: Option<&str>) -> Result<Vec<String>, IoError> {
        Ok(Vec::new())
    }

    /// List indexes defined on a table, optionally schema-scoped.
    ///
    /// Per br-frankenpandas-bgv9 (fd90.28). Default impl returns
    /// `Ok(Vec::new())` for backends that can't introspect. rusqlite
    /// override uses `PRAGMA index_list(table)` + `PRAGMA index_info`
    /// per index, surfacing only user-created indexes (the auto-created
    /// indexes for PRIMARY KEY constraints are filtered out to match
    /// SQLAlchemy.Inspector.get_indexes() semantics). Multi-schema
    /// backends override with information_schema queries.
    fn list_indexes(
        &self,
        _table_name: &str,
        _schema: Option<&str>,
    ) -> Result<Vec<SqlIndexSchema>, IoError> {
        Ok(Vec::new())
    }

    /// List UNIQUE constraints declared on a table (inline or table-level),
    /// excluding `CREATE UNIQUE INDEX` indexes (those land in `list_indexes`).
    ///
    /// Per br-frankenpandas-sh4v (fd90.31). Default impl returns
    /// `Ok(Vec::new())`. rusqlite override uses
    /// `PRAGMA index_list(table)` filtered by `origin == 'u'` (the
    /// auto-created indexes that back declared UNIQUE constraints)
    /// then `PRAGMA index_info` per match. Multi-schema backends
    /// override with information_schema queries.
    fn list_unique_constraints(
        &self,
        _table_name: &str,
        _schema: Option<&str>,
    ) -> Result<Vec<SqlUniqueConstraintSchema>, IoError> {
        Ok(Vec::new())
    }

    /// Probe the table-level comment, optionally schema-scoped.
    ///
    /// Per br-frankenpandas-yu3w (fd90.32). Default impl returns
    /// `Ok(None)` — SQLite has no native table-comment storage so it
    /// inherits the default. PostgreSQL impls should override using
    /// `pg_catalog.obj_description(...)` or
    /// `pg_catalog.pg_class.relkind` joined to `pg_description`;
    /// MySQL uses `information_schema.tables.table_comment`; MSSQL
    /// reads from `sys.extended_properties`. Aligns with
    /// `SQLAlchemy.Inspector.get_table_comment()` shape (returns
    /// `{'text': comment_or_none}`).
    fn table_comment(
        &self,
        _table_name: &str,
        _schema: Option<&str>,
    ) -> Result<Option<String>, IoError> {
        Ok(None)
    }

    /// List foreign-key constraints declared on a table, optionally
    /// schema-scoped.
    ///
    /// Per br-frankenpandas-uht8 (fd90.29). Default impl returns
    /// `Ok(Vec::new())`. rusqlite override uses
    /// `PRAGMA foreign_key_list(table)`, grouping rows by their `id`
    /// column (each id is a single FK constraint that may span multiple
    /// columns) and ordering paired columns by `seq`. Multi-schema
    /// backends override with `information_schema.referential_constraints`
    /// + `key_column_usage` joined queries.
    fn list_foreign_keys(
        &self,
        _table_name: &str,
        _schema: Option<&str>,
    ) -> Result<Vec<SqlForeignKeySchema>, IoError> {
        Ok(Vec::new())
    }

    /// Return the primary-key column names for a table, ordered by
    /// the `primary_key_ordinal` reported by `table_schema`.
    ///
    /// Per br-frankenpandas-uw3y (fd90.25). Default impl delegates to
    /// `table_schema(table, schema)` and pulls out columns whose
    /// `primary_key_ordinal` is `Some(_)`, sorted ascending. Returns
    /// an empty vector when:
    /// - the table doesn't exist (`table_schema` returns `Ok(None)`),
    /// - the table has no primary key,
    /// - the backend can't introspect (default `table_schema`).
    ///
    /// Useful for upsert conflict-target generation, `index_label`
    /// defaulting, and schema validation. Backends can override to
    /// query their catalog directly when `table_schema` is too heavy.
    fn primary_key_columns(
        &self,
        table_name: &str,
        schema: Option<&str>,
    ) -> Result<Vec<String>, IoError> {
        // Per fd90.47: defer to the shared primary_keys_from_schema
        // helper so the filter+sort logic lives in exactly one place
        // (the helper is also used by SqlInspector::reflect_table).
        let Some(meta) = self.table_schema(table_name, schema)? else {
            return Ok(Vec::new());
        };
        Ok(primary_keys_from_schema(&meta))
    }

    /// Reset a table to empty without dropping its definition.
    ///
    /// Per br-frankenpandas-phum (fd90.23). Default impl emits
    /// `DELETE FROM <table>` — universal SQL that every backend
    /// supports, but slower than TRUNCATE on large tables because the
    /// row deletes are logged in the transaction journal. PostgreSQL
    /// and MySQL backends should override with `TRUNCATE TABLE`,
    /// which is dramatically faster (DDL-style fast-path) and resets
    /// auto-increment sequences. The schema arg routes through
    /// `quote_identifier` and is silently ignored when
    /// `supports_schemas() == false`.
    fn truncate_table(&self, table_name: &str, schema: Option<&str>) -> Result<(), IoError> {
        validate_sql_table_name(table_name)?;
        validate_sql_table_ref_identifier_lengths(self, table_name, schema)?;
        let qualified = match schema {
            Some(s) if self.supports_schemas() => {
                validate_sql_schema_name(s)?;
                format!(
                    "{}.{}",
                    self.quote_identifier(s)?,
                    self.quote_identifier(table_name)?
                )
            }
            _ => self.quote_identifier(table_name)?,
        };
        self.execute_batch(&format!("DELETE FROM {qualified}"))
    }
}

/// Map an fp-types DType to an SQLite column type declaration.
#[cfg(feature = "sql-sqlite")]
fn dtype_to_sql(dtype: DType) -> &'static str {
    match dtype {
        DType::Int64 | DType::Int64Nullable => "INTEGER",
        DType::Float64 => "REAL",
        DType::Utf8 => "TEXT",
        DType::Categorical => "TEXT",
        DType::Bool | DType::BoolNullable => "INTEGER",
        DType::Null => "TEXT",
        DType::Timedelta64 => "INTEGER", // store as nanoseconds
        DType::Datetime64 => "INTEGER",  // store as nanoseconds
        DType::Period => "INTEGER",      // store as ordinal
        DType::Interval => "TEXT",       // store as string
        DType::Sparse => "TEXT",
    }
}

#[cfg(feature = "sql-sqlite")]
fn sqlite_decl_type_to_dtype(decl_type: &str) -> Option<DType> {
    let upper = decl_type.trim().to_ascii_uppercase();
    if upper.contains("INT") {
        Some(DType::Int64)
    } else if upper.contains("REAL") || upper.contains("FLOA") || upper.contains("DOUB") {
        Some(DType::Float64)
    } else if upper.contains("CHAR") || upper.contains("CLOB") || upper.contains("TEXT") {
        Some(DType::Utf8)
    } else {
        None
    }
}

/// Convert an SQLite column value to a Scalar.
#[cfg(feature = "sql-sqlite")]
fn sql_value_to_scalar(value: &rusqlite::types::Value) -> Scalar {
    match value {
        rusqlite::types::Value::Null => Scalar::Null(NullKind::Null),
        rusqlite::types::Value::Integer(v) => Scalar::Int64(*v),
        rusqlite::types::Value::Real(v) => Scalar::Float64(*v),
        rusqlite::types::Value::Text(s) => Scalar::Utf8(s.clone()),
        rusqlite::types::Value::Blob(b) => Scalar::Utf8(format!("<blob:{} bytes>", b.len())),
    }
}

#[cfg(feature = "sql-sqlite")]
fn sql_value_from_scalar(scalar: &Scalar) -> rusqlite::types::Value {
    match scalar {
        Scalar::Int64(v) => rusqlite::types::Value::Integer(*v),
        Scalar::Float64(v) => {
            if v.is_nan() {
                rusqlite::types::Value::Null
            } else {
                rusqlite::types::Value::Real(*v)
            }
        }
        Scalar::Bool(b) => rusqlite::types::Value::Integer(if *b { 1 } else { 0 }),
        Scalar::Utf8(s) => rusqlite::types::Value::Text(s.clone()),
        Scalar::Null(_) => rusqlite::types::Value::Null,
        Scalar::Timedelta64(v) => {
            if *v == Timedelta::NAT {
                rusqlite::types::Value::Null
            } else {
                rusqlite::types::Value::Integer(*v)
            }
        }
        Scalar::Datetime64(v) => {
            if *v == Timestamp::NAT {
                rusqlite::types::Value::Null
            } else {
                rusqlite::types::Value::Integer(*v)
            }
        }
        Scalar::Period(v) => {
            if *v == i64::MIN {
                rusqlite::types::Value::Null
            } else {
                rusqlite::types::Value::Integer(*v)
            }
        }
        Scalar::Interval(iv) => rusqlite::types::Value::Text(format!("{iv}")),
    }
}

fn scalar_from_index_label(label: &IndexLabel) -> Scalar {
    match label {
        IndexLabel::Int64(v) => Scalar::Int64(*v),
        IndexLabel::Utf8(s) => Scalar::Utf8(s.clone()),
        // Typed-null label round-trips to the same-kind missing scalar.
        IndexLabel::Null(kind) => Scalar::Null(*kind),
        IndexLabel::Timedelta64(v) => {
            if *v == Timedelta::NAT {
                Scalar::Null(NullKind::Null)
            } else {
                Scalar::Timedelta64(*v)
            }
        }
        IndexLabel::Datetime64(v) => {
            if *v == i64::MIN {
                Scalar::Null(NullKind::Null)
            } else {
                Scalar::Utf8(format_datetime_ns(*v))
            }
        }
    }
}

#[cfg(feature = "sql-sqlite")]
impl SqlConnection for rusqlite::Connection {
    fn query(&self, query: &str, params: &[Scalar]) -> Result<SqlQueryResult, IoError> {
        let mut stmt = self
            .prepare(query)
            .map_err(|e| IoError::Sql(format!("prepare failed: {e}")))?;

        let col_count = stmt.column_count();
        let columns: Vec<String> = (0..col_count)
            .map(|i| stmt.column_name(i).unwrap_or("?").to_owned())
            .collect();

        let sql_params = params.iter().map(sql_value_from_scalar).collect::<Vec<_>>();
        let mut rows = stmt
            .query(rusqlite::params_from_iter(sql_params.iter()))
            .map_err(|e| IoError::Sql(format!("query failed: {e}")))?;

        let mut out_rows = Vec::new();
        while let Some(row) = rows
            .next()
            .map_err(|e| IoError::Sql(format!("row fetch failed: {e}")))?
        {
            let mut values = Vec::with_capacity(col_count);
            for col_idx in 0..col_count {
                let value: rusqlite::types::Value = row
                    .get(col_idx)
                    .map_err(|e| IoError::Sql(format!("cell read failed: {e}")))?;
                values.push(sql_value_to_scalar(&value));
            }
            out_rows.push(values);
        }

        Ok(SqlQueryResult {
            columns,
            rows: out_rows,
        })
    }

    fn query_column_dtypes(
        &self,
        query: &str,
        _params: &[Scalar],
    ) -> Result<Vec<Option<DType>>, IoError> {
        let stmt = self
            .prepare(query)
            .map_err(|e| IoError::Sql(format!("prepare failed: {e}")))?;
        Ok(stmt
            .columns()
            .into_iter()
            .map(|column| column.decl_type().and_then(sqlite_decl_type_to_dtype))
            .collect())
    }

    fn supports_paged_sql_chunks(&self) -> bool {
        true
    }

    fn execute_batch(&self, sql: &str) -> Result<(), IoError> {
        rusqlite::Connection::execute_batch(self, sql)
            .map_err(|e| IoError::Sql(format!("execute_batch failed: {e}")))
    }

    fn table_exists(&self, table_name: &str) -> Result<bool, IoError> {
        self.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?1")
            .and_then(|mut stmt| stmt.exists(rusqlite::params![table_name]))
            .map_err(|e| IoError::Sql(format!("existence check failed: {e}")))
    }

    fn insert_rows(&self, insert_sql: &str, rows: &[Vec<Scalar>]) -> Result<(), IoError> {
        let tx = self
            .unchecked_transaction()
            .map_err(|e| IoError::Sql(format!("begin transaction failed: {e}")))?;

        {
            let mut stmt = tx
                .prepare_cached(insert_sql)
                .map_err(|e| IoError::Sql(format!("prepare insert failed: {e}")))?;

            for (row_idx, row_values) in rows.iter().enumerate() {
                let params = row_values
                    .iter()
                    .map(sql_value_from_scalar)
                    .collect::<Vec<_>>();
                stmt.execute(rusqlite::params_from_iter(params.iter()))
                    .map_err(|e| IoError::Sql(format!("insert row {row_idx} failed: {e}")))?;
            }
        }

        tx.commit()
            .map_err(|e| IoError::Sql(format!("commit failed: {e}")))?;
        Ok(())
    }

    fn dtype_sql(&self, dtype: DType) -> &'static str {
        dtype_to_sql(dtype)
    }

    fn index_dtype_sql(&self, index: &Index) -> &'static str {
        sql_dtype_from_index(index)
    }

    // br-frankenpandas-6dtf: backend-capability + dialect probes.
    fn dialect_name(&self) -> &'static str {
        "sqlite"
    }

    fn supports_returning(&self) -> bool {
        // SQLite 3.35.0+ (released March 2021) supports INSERT ... RETURNING.
        // rusqlite ships with bundled SQLite >= 3.45 by default, so we can
        // unconditionally claim support here.
        true
    }

    fn max_param_count(&self) -> Option<usize> {
        // SQLite default SQLITE_MAX_VARIABLE_NUMBER is 32766 since 3.32.0.
        // (Older builds capped at 999.) rusqlite bundled SQLite is current,
        // so this matches.
        Some(32766)
    }

    fn with_transaction<T, F>(&self, f: F) -> Result<T, IoError>
    where
        F: FnOnce(&Self) -> Result<T, IoError>,
        Self: Sized,
    {
        struct RollbackOnDrop<'conn> {
            conn: &'conn rusqlite::Connection,
            active: bool,
        }

        impl Drop for RollbackOnDrop<'_> {
            fn drop(&mut self) {
                if self.active {
                    let _ = rusqlite::Connection::execute_batch(self.conn, "ROLLBACK");
                }
            }
        }

        // rusqlite's pure-trait `Self: Sized` constraint means we operate on
        // `&rusqlite::Connection` directly without taking the `&mut` that
        // `Connection::transaction()` requires. We emulate the same
        // BEGIN/COMMIT semantics with explicit pragmas. The guard keeps the
        // connection from retaining a write transaction if the callback
        // panics before we reach the explicit rollback/commit paths.
        self.execute_batch("BEGIN")
            .map_err(|e| IoError::Sql(format!("begin transaction failed: {e}")))?;
        let mut rollback = RollbackOnDrop {
            conn: self,
            active: true,
        };
        match f(self) {
            Ok(result) => {
                self.execute_batch("COMMIT")
                    .map_err(|e| IoError::Sql(format!("commit transaction failed: {e}")))?;
                rollback.active = false;
                Ok(result)
            }
            Err(err) => {
                // Best-effort rollback; surface the original error if rollback
                // also fails (rollback failure is logged via the Sql error
                // variant for diagnostics but the user wants the closure
                // error preserved as the primary signal).
                if self.execute_batch("ROLLBACK").is_ok() {
                    rollback.active = false;
                }
                Err(err)
            }
        }
    }

    fn quote_identifier(&self, ident: &str) -> Result<String, IoError> {
        // SQLite accepts ANSI double-quotes for identifiers (it ALSO accepts
        // backticks for MySQL compat, but ANSI is the recommended form per
        // SQLite docs). Delegate to the existing free-fn helper to keep the
        // exact escaping policy in one place.
        quote_sql_ident(ident)
    }

    fn list_tables(&self, _schema: Option<&str>) -> Result<Vec<String>, IoError> {
        // SQLite has a single namespace; the schema arg is silently
        // ignored to match `supports_schemas() == false`. We exclude
        // SQLite's internal `sqlite_*` book-keeping tables to match
        // pandas' SQLAlchemy dialect, which never surfaces them as
        // user tables.
        // Per fd90.50: ESCAPE '\' makes the `_` in 'sqlite\_%' a literal
        // underscore instead of a SQL LIKE single-char wildcard. Without
        // the escape, a user table named e.g. `sqliteX` would be
        // incorrectly excluded because the `_` matches any single char.
        let mut stmt = self
            .prepare(
                r"SELECT name FROM sqlite_master
                 WHERE type='table' AND name NOT LIKE 'sqlite\_%' ESCAPE '\'
                 ORDER BY name",
            )
            .map_err(|e| IoError::Sql(format!("list_tables prepare failed: {e}")))?;
        let names = stmt
            .query_map([], |row| row.get::<_, String>(0))
            .map_err(|e| IoError::Sql(format!("list_tables query failed: {e}")))?
            .collect::<Result<Vec<_>, _>>()
            .map_err(|e| IoError::Sql(format!("list_tables row read failed: {e}")))?;
        Ok(names)
    }

    fn list_views(&self, _schema: Option<&str>) -> Result<Vec<String>, IoError> {
        // Same single-namespace policy as list_tables; type='view'
        // distinguishes the two buckets in sqlite_master.
        // Per fd90.50: same ESCAPE '\' fix as list_tables to treat
        // the underscore in 'sqlite_' as a literal.
        let mut stmt = self
            .prepare(
                r"SELECT name FROM sqlite_master
                 WHERE type='view' AND name NOT LIKE 'sqlite\_%' ESCAPE '\'
                 ORDER BY name",
            )
            .map_err(|e| IoError::Sql(format!("list_views prepare failed: {e}")))?;
        let names = stmt
            .query_map([], |row| row.get::<_, String>(0))
            .map_err(|e| IoError::Sql(format!("list_views query failed: {e}")))?
            .collect::<Result<Vec<_>, _>>()
            .map_err(|e| IoError::Sql(format!("list_views row read failed: {e}")))?;
        Ok(names)
    }

    fn table_schema(
        &self,
        table_name: &str,
        _schema: Option<&str>,
    ) -> Result<Option<SqlTableSchema>, IoError> {
        // Validate the table name first — PRAGMA table_info doesn't
        // accept parameter binding, so we must reject anything that
        // could break out of the identifier slot.
        validate_sql_table_name(table_name)?;
        // PRAGMA table_info returns: cid, name, type, notnull, dflt_value, pk.
        let pragma = format!("PRAGMA table_info(\"{}\")", table_name.replace('"', "\"\""));
        let mut stmt = self
            .prepare(&pragma)
            .map_err(|e| IoError::Sql(format!("table_schema prepare failed: {e}")))?;
        // PRAGMA table_info row tuple: (name, type, notnull, dflt_value, pk).
        // Type alias keeps clippy::type_complexity happy on the
        // intermediate Vec used for the two-pass autoincrement detection.
        type ColumnInfoRow = (String, Option<String>, i64, Option<String>, i64);
        let raw_rows: Vec<ColumnInfoRow> = stmt
            .query_map([], |row| {
                Ok((
                    row.get::<_, String>(1)?,
                    row.get::<_, Option<String>>(2)?,
                    row.get::<_, i64>(3)?,
                    row.get::<_, Option<String>>(4)?,
                    row.get::<_, i64>(5)?,
                ))
            })
            .map_err(|e| IoError::Sql(format!("table_schema query failed: {e}")))?
            .collect::<Result<Vec<_>, _>>()
            .map_err(|e| IoError::Sql(format!("table_schema row read failed: {e}")))?;

        // Per fd90.42 (refines fd90.37): SQLite's rowid-alias rule
        // requires the column to be the SOLE primary key — i.e. exactly
        // one row in PRAGMA table_info has pk > 0. Composite PKs (where
        // multiple columns have pk > 0) never qualify, even if the
        // first column is INTEGER. So we count single-PK status across
        // the table before deciding any column's autoincrement bit.
        let pk_count = raw_rows.iter().filter(|(_, _, _, _, pk)| *pk > 0).count();
        let single_pk = pk_count == 1;

        let mut columns: Vec<SqlColumnSchema> = Vec::with_capacity(raw_rows.len());
        for (name, declared, notnull, dflt, pk) in raw_rows {
            let cleaned_type = declared.filter(|s| !s.is_empty());
            let autoincrement = single_pk
                && pk == 1
                && cleaned_type
                    .as_deref()
                    .map(|t| t.eq_ignore_ascii_case("INTEGER"))
                    .unwrap_or(false);
            columns.push(SqlColumnSchema {
                name,
                declared_type: cleaned_type,
                nullable: notnull == 0,
                default_value: dflt,
                primary_key_ordinal: if pk > 0 {
                    Some(usize::try_from(pk - 1).unwrap_or(0))
                } else {
                    None
                },
                comment: None,
                autoincrement,
            });
        }
        if columns.is_empty() {
            // PRAGMA table_info on a non-existent table returns 0 rows
            // without erroring; map that to None so callers can
            // distinguish missing tables from empty ones.
            Ok(None)
        } else {
            Ok(Some(SqlTableSchema {
                table_name: table_name.to_owned(),
                columns,
            }))
        }
    }

    fn server_version(&self) -> Result<Option<String>, IoError> {
        // sqlite_version() is a built-in scalar that returns the
        // SQLite library version string (e.g. "3.45.1").
        let version: String = self
            .query_row("SELECT sqlite_version()", [], |row| row.get(0))
            .map_err(|e| IoError::Sql(format!("server_version query failed: {e}")))?;
        Ok(Some(version))
    }

    fn list_indexes(
        &self,
        table_name: &str,
        _schema: Option<&str>,
    ) -> Result<Vec<SqlIndexSchema>, IoError> {
        validate_sql_table_name(table_name)?;
        // PRAGMA index_list(table) returns: seq, name, unique, origin, partial.
        // origin is 'c' for CREATE INDEX (user), 'pk' for PRIMARY KEY auto,
        // 'u' for UNIQUE constraint auto. SQLAlchemy.Inspector surfaces
        // only the user-created ones, so we filter out 'pk' to match.
        let pragma_list = format!("PRAGMA index_list(\"{}\")", table_name.replace('"', "\"\""));
        let mut list_stmt = self
            .prepare(&pragma_list)
            .map_err(|e| IoError::Sql(format!("list_indexes prepare failed: {e}")))?;
        let index_meta = list_stmt
            .query_map([], |row| {
                Ok((
                    row.get::<_, String>(1)?, // name
                    row.get::<_, i64>(2)?,    // unique flag
                    row.get::<_, String>(3)?, // origin
                ))
            })
            .map_err(|e| IoError::Sql(format!("list_indexes query failed: {e}")))?
            .collect::<Result<Vec<_>, _>>()
            .map_err(|e| IoError::Sql(format!("list_indexes row read failed: {e}")))?;

        let mut indexes = Vec::new();
        for (name, uniq, origin) in index_meta {
            if origin == "pk" {
                // Auto-created PK index — pandas/SQLAlchemy hide it.
                continue;
            }
            if origin == "u" {
                // Auto-created index backing a declared UNIQUE
                // constraint — surfaced via list_unique_constraints
                // (fd90.31), not here, to match SQLAlchemy disjoint
                // bucketing between get_indexes and
                // get_unique_constraints.
                continue;
            }
            // PRAGMA index_info(idx) returns: seqno, cid, column_name (col2 may
            // be NULL for expression-based indexes — skip those rather than
            // surfacing partial column lists).
            let pragma_info = format!("PRAGMA index_info(\"{}\")", name.replace('"', "\"\""));
            let mut info_stmt = self
                .prepare(&pragma_info)
                .map_err(|e| IoError::Sql(format!("index_info prepare failed: {e}")))?;
            let cols = info_stmt
                .query_map([], |row| {
                    Ok((row.get::<_, i64>(0)?, row.get::<_, Option<String>>(2)?))
                })
                .map_err(|e| IoError::Sql(format!("index_info query failed: {e}")))?
                .collect::<Result<Vec<_>, _>>()
                .map_err(|e| IoError::Sql(format!("index_info row read failed: {e}")))?;
            // Skip expression-based indexes (any column_name is NULL).
            if cols.iter().any(|(_, c)| c.is_none()) {
                continue;
            }
            let mut sorted: Vec<(i64, String)> = cols
                .into_iter()
                .map(|(seq, c)| (seq, c.unwrap_or_default()))
                .collect();
            sorted.sort_by_key(|(seq, _)| *seq);
            indexes.push(SqlIndexSchema {
                name,
                columns: sorted.into_iter().map(|(_, c)| c).collect(),
                unique: uniq != 0,
            });
        }
        Ok(indexes)
    }

    fn list_unique_constraints(
        &self,
        table_name: &str,
        _schema: Option<&str>,
    ) -> Result<Vec<SqlUniqueConstraintSchema>, IoError> {
        validate_sql_table_name(table_name)?;
        // PRAGMA index_list(table) origin column:
        //   'c' = CREATE INDEX (user) — surfaces via list_indexes
        //   'u' = UNIQUE constraint   — surfaces here
        //   'pk' = PRIMARY KEY auto   — surfaces via primary_key_columns
        let pragma_list = format!("PRAGMA index_list(\"{}\")", table_name.replace('"', "\"\""));
        let mut list_stmt = self
            .prepare(&pragma_list)
            .map_err(|e| IoError::Sql(format!("list_unique_constraints prepare failed: {e}")))?;
        let candidates = list_stmt
            .query_map([], |row| {
                Ok((
                    row.get::<_, String>(1)?, // index name
                    row.get::<_, String>(3)?, // origin
                ))
            })
            .map_err(|e| IoError::Sql(format!("list_unique_constraints query failed: {e}")))?
            .collect::<Result<Vec<_>, _>>()
            .map_err(|e| IoError::Sql(format!("list_unique_constraints row read failed: {e}")))?;

        let mut constraints = Vec::new();
        for (name, origin) in candidates {
            if origin != "u" {
                continue;
            }
            let pragma_info = format!("PRAGMA index_info(\"{}\")", name.replace('"', "\"\""));
            let mut info_stmt = self
                .prepare(&pragma_info)
                .map_err(|e| IoError::Sql(format!("uq index_info prepare failed: {e}")))?;
            let cols = info_stmt
                .query_map([], |row| {
                    Ok((row.get::<_, i64>(0)?, row.get::<_, Option<String>>(2)?))
                })
                .map_err(|e| IoError::Sql(format!("uq index_info query failed: {e}")))?
                .collect::<Result<Vec<_>, _>>()
                .map_err(|e| IoError::Sql(format!("uq index_info row read failed: {e}")))?;
            // Skip expression-based unique constraints (column NULL).
            if cols.iter().any(|(_, c)| c.is_none()) {
                continue;
            }
            let mut sorted: Vec<(i64, String)> = cols
                .into_iter()
                .map(|(seq, c)| (seq, c.unwrap_or_default()))
                .collect();
            sorted.sort_by_key(|(seq, _)| *seq);
            constraints.push(SqlUniqueConstraintSchema {
                name,
                columns: sorted.into_iter().map(|(_, c)| c).collect(),
            });
        }
        Ok(constraints)
    }

    fn list_foreign_keys(
        &self,
        table_name: &str,
        _schema: Option<&str>,
    ) -> Result<Vec<SqlForeignKeySchema>, IoError> {
        // PRAGMA foreign_key_list rows: (seq, referenced_table, from_col, to_col).
        // The constraint id is the BTreeMap key; we don't repeat it inside the
        // value tuple. Type alias keeps clippy::type_complexity happy and
        // the grouping logic readable.
        type FkRow = (i64, String, String, Option<String>);

        validate_sql_table_name(table_name)?;
        // PRAGMA foreign_key_list(table) returns: id, seq, table, from, to,
        // on_update, on_delete, match. Each `id` is one FK constraint;
        // multiple rows with the same id describe a composite FK.
        let pragma = format!(
            "PRAGMA foreign_key_list(\"{}\")",
            table_name.replace('"', "\"\"")
        );
        let mut stmt = self
            .prepare(&pragma)
            .map_err(|e| IoError::Sql(format!("list_foreign_keys prepare failed: {e}")))?;
        let rows: Vec<(i64, FkRow)> = stmt
            .query_map([], |row| {
                Ok((
                    row.get::<_, i64>(0)?, // id
                    (
                        row.get::<_, i64>(1)?,            // seq
                        row.get::<_, String>(2)?,         // referenced table
                        row.get::<_, String>(3)?,         // from column
                        row.get::<_, Option<String>>(4)?, // to column (nullable)
                    ),
                ))
            })
            .map_err(|e| IoError::Sql(format!("list_foreign_keys query failed: {e}")))?
            .collect::<Result<Vec<_>, _>>()
            .map_err(|e| IoError::Sql(format!("list_foreign_keys row read failed: {e}")))?;

        // Group by id; preserve discovery order across distinct ids.
        let mut order: Vec<i64> = Vec::new();
        let mut grouped: std::collections::BTreeMap<i64, Vec<FkRow>> =
            std::collections::BTreeMap::new();
        for (id, fk_row) in rows {
            let (seq, ref_table, from_col, to_col) = fk_row;
            if !grouped.contains_key(&id) {
                order.push(id);
            }
            grouped
                .entry(id)
                .or_default()
                .push((seq, ref_table, from_col, to_col));
        }

        let mut fks = Vec::with_capacity(order.len());
        for id in order {
            let mut group = grouped.remove(&id).unwrap_or_default();
            group.sort_by_key(|(seq, _, _, _)| *seq);
            let ref_table = group
                .first()
                .map(|(_, t, _, _)| t.clone())
                .unwrap_or_default();
            let mut columns = Vec::with_capacity(group.len());
            let mut referenced_columns: Vec<Option<String>> = Vec::with_capacity(group.len());
            for (_, _, from_col, to_col) in group {
                columns.push(from_col);
                referenced_columns.push(to_col);
            }
            // Per fd90.44: when ALL `to` columns are NULL, the user
            // declared `FOREIGN KEY (cols) REFERENCES parent` (implicit
            // reference to parent's PK). Resolve by looking up the
            // parent's primary key columns. SQLAlchemy.Inspector
            // surfaces these as resolved-to-PK references; matching
            // that behavior keeps callers from missing real FKs.
            let resolved_columns: Vec<String> = if referenced_columns.iter().all(Option::is_none) {
                // Implicit-PK reference: look up parent's PK.
                let pk = self.primary_key_columns(&ref_table, None)?;
                if pk.len() == columns.len() {
                    pk
                } else {
                    // Parent PK shape doesn't match FK column count
                    // (parent has no PK, or composite mismatch). Skip
                    // — fabricating columns would mislead callers
                    // worse than hiding the FK.
                    continue;
                }
            } else if referenced_columns.iter().all(Option::is_some) {
                // Fully explicit: every column has a resolved 'to'.
                referenced_columns.into_iter().flatten().collect()
            } else {
                // Mixed Some/None: SQLite shouldn't produce this for
                // a single FK group, but if it ever does, skip rather
                // than mispair.
                continue;
            };
            fks.push(SqlForeignKeySchema {
                // SQLite PRAGMA foreign_key_list does not surface a
                // CONSTRAINT name; pandas/SQLAlchemy report None there too.
                constraint_name: None,
                columns,
                referenced_table: ref_table,
                referenced_columns: resolved_columns,
            });
        }
        Ok(fks)
    }
}

#[cfg(feature = "sql-sqlite")]
fn sql_dtype_from_index(index: &Index) -> &'static str {
    for label in index.labels() {
        match label {
            IndexLabel::Int64(_) => return "INTEGER",
            IndexLabel::Utf8(_) => return "TEXT",
            IndexLabel::Timedelta64(v) if *v != Timedelta::NAT => return "INTEGER",
            IndexLabel::Datetime64(v) if *v != i64::MIN => return "TEXT",
            _ => {}
        }
    }
    "TEXT"
}

fn resolve_sql_index_label(
    frame: &DataFrame,
    options: &SqlWriteOptions,
) -> Result<Option<String>, IoError> {
    if !options.index {
        return Ok(None);
    }

    let label = options
        .index_label
        .clone()
        .or_else(|| frame.index().name().map(str::to_owned))
        .unwrap_or_else(|| "index".to_owned());

    if frame.column(&label).is_some() {
        return Err(IoError::DuplicateColumnName(label));
    }

    Ok(Some(label))
}

// Per br-frankenpandas-ld8h (fd90.45): these helpers are only called
// from the rusqlite SqlConnection impl, which is gated behind
// `feature = "sql-sqlite"`. Mirroring the gate here keeps
// --no-default-features builds clean of dead-code warnings.
#[cfg(feature = "sql-sqlite")]
fn escape_sql_ident(name: &str) -> Result<String, IoError> {
    if name.contains('\0') {
        return Err(IoError::Sql("invalid SQL identifier: NUL byte".to_owned()));
    }
    Ok(name.replace('"', "\"\""))
}

#[cfg(feature = "sql-sqlite")]
fn quote_sql_ident(name: &str) -> Result<String, IoError> {
    Ok(format!("\"{}\"", escape_sql_ident(name)?))
}

/// Per br-frankenpandas-4l7a (fd90.55): shared identifier-shape
/// validator used by `validate_sql_table_name` and
/// `validate_sql_column_name`. `kind` is the user-facing label
/// inserted into the error message ("table", "column", ...). The
/// rule is the same for both: non-empty, ASCII-alphanumeric or
/// underscore only — defense in depth alongside `quote_identifier`
/// (which handles embedded quotes but doesn't reject other shapes).
fn validate_sql_ident(name: &str, kind: &str) -> Result<(), IoError> {
    if name.is_empty() || !name.chars().all(|c| c.is_alphanumeric() || c == '_') {
        return Err(IoError::Sql(format!(
            "invalid {kind} name: '{name}' (must be non-empty, only alphanumeric and underscore allowed)"
        )));
    }
    Ok(())
}

fn validate_sql_table_name(table_name: &str) -> Result<(), IoError> {
    validate_sql_ident(table_name, "table")
}

/// Per br-frankenpandas-597l (fd90.56): dedicated schema-name
/// validator so error messages correctly identify the invalid
/// identifier as a schema rather than a table. Same alphanumeric+
/// underscore rule as table/column names.
fn validate_sql_schema_name(schema: &str) -> Result<(), IoError> {
    validate_sql_ident(schema, "schema")
}

/// Validate `name` against the backend's identifier-length cap.
///
/// Per br-frankenpandas-9ynk (fd90.27). When `max` is `Some(n)`, errors
/// out when `name.len() > n`. When `max` is `None`, accepts any length
/// (e.g. SQLite, where the engine has no documented limit). `kind` is
/// the user-facing label used in the error message ("table", "column",
/// "index label", ...) so misuse points cleanly back to the offending
/// identifier without callers having to format the message.
fn validate_sql_identifier_length(
    name: &str,
    max: Option<usize>,
    kind: &str,
) -> Result<(), IoError> {
    if let Some(limit) = max
        && name.len() > limit
    {
        return Err(IoError::Sql(format!(
            "invalid {kind} name '{name}': length {len} exceeds backend identifier limit ({limit})",
            len = name.len()
        )));
    }
    Ok(())
}

fn validate_sql_table_ref_identifier_lengths<C: SqlConnection + ?Sized>(
    conn: &C,
    table_name: &str,
    schema: Option<&str>,
) -> Result<(), IoError> {
    let max = conn.max_identifier_length();
    validate_sql_identifier_length(table_name, max, "table")?;
    if let Some(s) = schema {
        validate_sql_identifier_length(s, max, "schema")?;
    }
    Ok(())
}

fn validate_sql_column_identifier_lengths<C, I, S>(conn: &C, names: I) -> Result<(), IoError>
where
    C: SqlConnection + ?Sized,
    I: IntoIterator<Item = S>,
    S: AsRef<str>,
{
    let max = conn.max_identifier_length();
    for name in names {
        validate_sql_identifier_length(name.as_ref(), max, "column")?;
    }
    Ok(())
}

fn sql_select_all_query<C: SqlConnection>(conn: &C, table_name: &str) -> Result<String, IoError> {
    sql_select_all_query_in_schema(conn, table_name, None)
}

/// Build a `SELECT * FROM ...` statement, optionally schema-qualified.
///
/// Per br-frankenpandas-u6zn (fd90.14). When `schema` is `Some(s)` AND
/// `conn.supports_schemas()`, the FROM clause becomes `\"schema\".\"table\"`.
/// When `supports_schemas` returns false, any `Some(s)` is rejected before
/// query generation so `read_sql_table(schema=...)` matches pandas' fail-closed
/// SQLite behavior.
fn sql_select_all_query_in_schema<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    schema: Option<&str>,
) -> Result<String, IoError> {
    validate_sql_table_name(table_name)?;
    validate_sql_table_ref_identifier_lengths(conn, table_name, schema)?;
    let qualified = match schema {
        Some(s) => {
            validate_sql_schema_name(s)?;
            if !conn.supports_schemas() {
                return Err(IoError::Sql(format!(
                    "read_sql_table: schema is not supported by {} backend",
                    conn.dialect_name()
                )));
            }
            format!(
                "{}.{}",
                conn.quote_identifier(s)?,
                conn.quote_identifier(table_name)?
            )
        }
        _ => conn.quote_identifier(table_name)?,
    };
    Ok(format!("SELECT * FROM {qualified}"))
}

fn validate_sql_column_name(column_name: &str) -> Result<(), IoError> {
    validate_sql_ident(column_name, "column")
}

fn sql_select_columns_query<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    columns: &[&str],
) -> Result<String, IoError> {
    sql_select_columns_query_in_schema(conn, table_name, None, columns)
}

/// Build a `SELECT col1, col2, ... FROM ...` statement, optionally
/// schema-qualified.
///
/// Per br-frankenpandas-d3e9 (fd90.34). Companion to
/// `sql_select_all_query_in_schema`. Same schema rules: when
/// `schema` is `Some(s)` AND `conn.supports_schemas()`, the FROM
/// clause becomes `\"schema\".\"table\"`; when `supports_schemas()`
/// returns false, the request is rejected before query generation.
fn sql_select_columns_query_in_schema<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    schema: Option<&str>,
    columns: &[&str],
) -> Result<String, IoError> {
    validate_sql_table_name(table_name)?;
    if columns.is_empty() {
        return Err(IoError::Sql(
            "read_sql_table_columns: columns must be non-empty".to_owned(),
        ));
    }
    for name in columns {
        validate_sql_column_name(name)?;
    }
    validate_sql_table_ref_identifier_lengths(conn, table_name, schema)?;
    validate_sql_column_identifier_lengths(conn, columns)?;

    let qualified = match schema {
        Some(s) => {
            validate_sql_schema_name(s)?;
            if !conn.supports_schemas() {
                return Err(IoError::Sql(format!(
                    "read_sql_table: schema is not supported by {} backend",
                    conn.dialect_name()
                )));
            }
            format!(
                "{}.{}",
                conn.quote_identifier(s)?,
                conn.quote_identifier(table_name)?
            )
        }
        _ => conn.quote_identifier(table_name)?,
    };
    let projection: Vec<String> = columns
        .iter()
        .map(|name| conn.quote_identifier(name))
        .collect::<Result<_, _>>()?;
    Ok(format!(
        "SELECT {} FROM {}",
        projection.join(", "),
        qualified
    ))
}

fn sql_column_definition<C: SqlConnection>(
    conn: &C,
    column_name: &str,
    sql_type: &str,
) -> Result<String, IoError> {
    Ok(format!(
        "{} {sql_type}",
        conn.quote_identifier(column_name)?
    ))
}

// ============================================================================
// PostgreSQL SqlConnection Implementation (feature = "sql-postgresql")
// ============================================================================

#[cfg(any(feature = "sql-postgresql", feature = "sql-mysql"))]
use std::cell::RefCell;

/// Wrapper around `postgres::Client` providing interior mutability for the
/// `SqlConnection` trait (which requires `&self`).
#[cfg(feature = "sql-postgresql")]
pub struct PostgresConnection {
    client: RefCell<postgres::Client>,
}

#[cfg(feature = "sql-postgresql")]
impl PostgresConnection {
    pub fn new(client: postgres::Client) -> Self {
        Self {
            client: RefCell::new(client),
        }
    }
}

#[cfg(feature = "sql-postgresql")]
impl SqlConnection for PostgresConnection {
    fn query(&self, query_str: &str, params: &[Scalar]) -> Result<SqlQueryResult, IoError> {
        use postgres::types::ToSql;

        let pg_params: Vec<Box<dyn ToSql + Sync>> = params
            .iter()
            .map(|s| -> Box<dyn ToSql + Sync> {
                match s {
                    Scalar::Null(_) => Box::new(Option::<i64>::None),
                    Scalar::Bool(b) => Box::new(*b),
                    Scalar::Int64(i) => Box::new(*i),
                    Scalar::Float64(f) => Box::new(*f),
                    Scalar::Utf8(s) => Box::new(s.clone()),
                    _ => Box::new(Option::<i64>::None),
                }
            })
            .collect();

        let param_refs: Vec<&(dyn ToSql + Sync)> = pg_params.iter().map(|b| b.as_ref()).collect();
        let rows = self
            .client
            .borrow_mut()
            .query(query_str, &param_refs)
            .map_err(|e| IoError::Sql(format!("PostgreSQL query failed: {e}")))?;

        if rows.is_empty() {
            return Ok(SqlQueryResult {
                columns: Vec::new(),
                rows: Vec::new(),
            });
        }

        let columns: Vec<String> = rows[0]
            .columns()
            .iter()
            .map(|c| c.name().to_owned())
            .collect();

        let mut out_rows = Vec::new();
        for row in &rows {
            let mut values = Vec::new();
            for idx in 0..row.len() {
                let value = pg_value_to_scalar(row, idx);
                values.push(value);
            }
            out_rows.push(values);
        }

        Ok(SqlQueryResult {
            columns,
            rows: out_rows,
        })
    }

    fn execute_batch(&self, sql: &str) -> Result<(), IoError> {
        self.client
            .borrow_mut()
            .batch_execute(sql)
            .map_err(|e| IoError::Sql(format!("PostgreSQL batch execute failed: {e}")))
    }

    fn table_exists(&self, table_name: &str) -> Result<bool, IoError> {
        let rows = self
            .client
            .borrow_mut()
            .query(
                "SELECT 1 FROM information_schema.tables WHERE table_name = $1 LIMIT 1",
                &[&table_name],
            )
            .map_err(|e| IoError::Sql(format!("PostgreSQL table_exists failed: {e}")))?;
        Ok(!rows.is_empty())
    }

    fn insert_rows(&self, insert_sql: &str, rows: &[Vec<Scalar>]) -> Result<(), IoError> {
        let mut client = self.client.borrow_mut();
        for row in rows {
            let pg_params: Vec<Box<dyn postgres::types::ToSql + Sync>> = row
                .iter()
                .map(|s| -> Box<dyn postgres::types::ToSql + Sync> {
                    match s {
                        Scalar::Null(_) => Box::new(Option::<i64>::None),
                        Scalar::Bool(b) => Box::new(*b),
                        Scalar::Int64(i) => Box::new(*i),
                        Scalar::Float64(f) => Box::new(*f),
                        Scalar::Utf8(s) => Box::new(s.clone()),
                        _ => Box::new(Option::<i64>::None),
                    }
                })
                .collect();
            let param_refs: Vec<&(dyn postgres::types::ToSql + Sync)> =
                pg_params.iter().map(|b| b.as_ref()).collect();
            client
                .execute(insert_sql, &param_refs)
                .map_err(|e| IoError::Sql(format!("PostgreSQL insert failed: {e}")))?;
        }
        Ok(())
    }

    fn dtype_sql(&self, dtype: DType) -> &'static str {
        match dtype {
            DType::Bool | DType::BoolNullable => "BOOLEAN",
            DType::Int64 | DType::Int64Nullable => "BIGINT",
            DType::Float64 => "DOUBLE PRECISION",
            DType::Utf8 => "TEXT",
            DType::Datetime64 => "TIMESTAMP",
            DType::Timedelta64 => "INTERVAL",
            _ => "TEXT",
        }
    }

    fn index_dtype_sql(&self, index: &Index) -> &'static str {
        pg_sql_dtype_from_index(index)
    }

    fn dialect_name(&self) -> &'static str {
        "postgresql"
    }

    fn parameter_marker(&self, ordinal: usize) -> String {
        format!("${ordinal}")
    }

    fn supports_returning(&self) -> bool {
        true
    }

    fn max_param_count(&self) -> Option<usize> {
        Some(65535)
    }

    fn supports_schemas(&self) -> bool {
        true
    }

    fn quote_identifier(&self, ident: &str) -> Result<String, IoError> {
        if ident.contains('\0') {
            return Err(IoError::Sql("invalid identifier: NUL byte".to_owned()));
        }
        Ok(format!("\"{}\"", ident.replace('"', "\"\"")))
    }

    fn list_tables(&self, schema: Option<&str>) -> Result<Vec<String>, IoError> {
        let schema = schema.unwrap_or("public");
        let rows = self
            .client
            .borrow_mut()
            .query(
                "SELECT table_name FROM information_schema.tables WHERE table_schema = $1 ORDER BY table_name",
                &[&schema],
            )
            .map_err(|e| IoError::Sql(format!("PostgreSQL list_tables failed: {e}")))?;
        Ok(rows.iter().map(|r| r.get(0)).collect())
    }

    fn list_schemas(&self) -> Result<Vec<String>, IoError> {
        let rows = self
            .client
            .borrow_mut()
            .query(
                "SELECT schema_name FROM information_schema.schemata ORDER BY schema_name",
                &[],
            )
            .map_err(|e| IoError::Sql(format!("PostgreSQL list_schemas failed: {e}")))?;
        Ok(rows.iter().map(|r| r.get(0)).collect())
    }
}

#[cfg(feature = "sql-postgresql")]
fn pg_sql_dtype_from_index(index: &Index) -> &'static str {
    for label in index.labels() {
        match label {
            IndexLabel::Int64(_) => return "BIGINT",
            IndexLabel::Utf8(_) => return "TEXT",
            IndexLabel::Timedelta64(v) if *v != Timedelta::NAT => return "INTERVAL",
            IndexLabel::Datetime64(v) if *v != i64::MIN => return "TIMESTAMP",
            _ => {}
        }
    }
    "TEXT"
}

#[cfg(feature = "sql-postgresql")]
fn pg_value_to_scalar(row: &postgres::Row, idx: usize) -> Scalar {
    if let Ok(Some(v)) = row.try_get::<_, Option<bool>>(idx) {
        return Scalar::Bool(v);
    }
    if let Ok(Some(v)) = row.try_get::<_, Option<i64>>(idx) {
        return Scalar::Int64(v);
    }
    if let Ok(Some(v)) = row.try_get::<_, Option<i32>>(idx) {
        return Scalar::Int64(i64::from(v));
    }
    if let Ok(Some(v)) = row.try_get::<_, Option<f64>>(idx) {
        return Scalar::Float64(v);
    }
    if let Ok(Some(v)) = row.try_get::<_, Option<f32>>(idx) {
        return Scalar::Float64(f64::from(v));
    }
    if let Ok(Some(v)) = row.try_get::<_, Option<String>>(idx) {
        return Scalar::Utf8(v);
    }
    Scalar::Null(crate::NullKind::Null)
}

// ============================================================================
// MySQL SqlConnection Implementation (feature = "sql-mysql")
// ============================================================================

/// Wrapper around `mysql::Conn` providing interior mutability for the
/// `SqlConnection` trait (which requires `&self`).
#[cfg(feature = "sql-mysql")]
pub struct MysqlConnection {
    conn: RefCell<mysql::Conn>,
}

#[cfg(feature = "sql-mysql")]
impl MysqlConnection {
    pub fn new(conn: mysql::Conn) -> Self {
        Self {
            conn: RefCell::new(conn),
        }
    }
}

#[cfg(feature = "sql-mysql")]
impl SqlConnection for MysqlConnection {
    fn query(&self, query_str: &str, params: &[Scalar]) -> Result<SqlQueryResult, IoError> {
        use mysql::prelude::*;

        let mysql_params: Vec<mysql::Value> = params.iter().map(scalar_to_mysql_value).collect();
        let result: Vec<mysql::Row> = self
            .conn
            .borrow_mut()
            .exec(query_str, mysql_params)
            .map_err(|e| IoError::Sql(format!("MySQL query failed: {e}")))?;

        if result.is_empty() {
            return Ok(SqlQueryResult {
                columns: Vec::new(),
                rows: Vec::new(),
            });
        }

        let columns: Vec<String> = result[0]
            .columns_ref()
            .iter()
            .map(|c| c.name_str().to_string())
            .collect();

        let mut out_rows = Vec::new();
        for row in &result {
            let mut values = Vec::new();
            for idx in 0..row.len() {
                let value = mysql_value_to_scalar(row.get(idx));
                values.push(value);
            }
            out_rows.push(values);
        }

        Ok(SqlQueryResult {
            columns,
            rows: out_rows,
        })
    }

    fn execute_batch(&self, sql: &str) -> Result<(), IoError> {
        use mysql::prelude::*;
        let mut conn = self.conn.borrow_mut();
        for statement in sql.split(';').filter(|s| !s.trim().is_empty()) {
            conn.query_drop(statement)
                .map_err(|e| IoError::Sql(format!("MySQL execute failed: {e}")))?;
        }
        Ok(())
    }

    fn table_exists(&self, table_name: &str) -> Result<bool, IoError> {
        use mysql::prelude::*;
        let result: Option<(i32,)> = self
            .conn
            .borrow_mut()
            .exec_first(
                "SELECT 1 FROM information_schema.tables WHERE table_name = ? LIMIT 1",
                (table_name,),
            )
            .map_err(|e| IoError::Sql(format!("MySQL table_exists failed: {e}")))?;
        Ok(result.is_some())
    }

    fn insert_rows(&self, insert_sql: &str, rows: &[Vec<Scalar>]) -> Result<(), IoError> {
        use mysql::prelude::*;
        let mut conn = self.conn.borrow_mut();
        for row in rows {
            let params: Vec<mysql::Value> = row.iter().map(scalar_to_mysql_value).collect();
            conn.exec_drop(insert_sql, params)
                .map_err(|e| IoError::Sql(format!("MySQL insert failed: {e}")))?;
        }
        Ok(())
    }

    fn dtype_sql(&self, dtype: DType) -> &'static str {
        match dtype {
            DType::Bool | DType::BoolNullable => "TINYINT(1)",
            DType::Int64 | DType::Int64Nullable => "BIGINT",
            DType::Float64 => "DOUBLE",
            DType::Utf8 => "TEXT",
            DType::Datetime64 => "DATETIME",
            DType::Timedelta64 => "TIME",
            _ => "TEXT",
        }
    }

    fn index_dtype_sql(&self, index: &Index) -> &'static str {
        mysql_sql_dtype_from_index(index)
    }

    fn dialect_name(&self) -> &'static str {
        "mysql"
    }

    fn parameter_marker(&self, _ordinal: usize) -> String {
        "?".to_owned()
    }

    fn supports_returning(&self) -> bool {
        false
    }

    fn max_param_count(&self) -> Option<usize> {
        Some(65535)
    }

    fn max_identifier_length(&self) -> Option<usize> {
        Some(64)
    }

    fn quote_identifier(&self, ident: &str) -> Result<String, IoError> {
        if ident.contains('\0') {
            return Err(IoError::Sql("invalid identifier: NUL byte".to_owned()));
        }
        Ok(format!("`{}`", ident.replace('`', "``")))
    }

    fn list_tables(&self, _schema: Option<&str>) -> Result<Vec<String>, IoError> {
        use mysql::prelude::*;
        let rows: Vec<(String,)> = self
            .conn
            .borrow_mut()
            .query("SHOW TABLES")
            .map_err(|e| IoError::Sql(format!("MySQL list_tables failed: {e}")))?;
        Ok(rows.into_iter().map(|(name,)| name).collect())
    }
}

#[cfg(feature = "sql-mysql")]
fn mysql_sql_dtype_from_index(index: &Index) -> &'static str {
    for label in index.labels() {
        match label {
            IndexLabel::Int64(_) => return "BIGINT",
            IndexLabel::Utf8(_) => return "VARCHAR(255)",
            IndexLabel::Timedelta64(v) if *v != Timedelta::NAT => return "TIME",
            IndexLabel::Datetime64(v) if *v != i64::MIN => return "DATETIME",
            _ => {}
        }
    }
    "VARCHAR(255)"
}

#[cfg(feature = "sql-mysql")]
fn scalar_to_mysql_value(s: &Scalar) -> mysql::Value {
    match s {
        Scalar::Null(_) => mysql::Value::NULL,
        Scalar::Bool(b) => mysql::Value::from(*b),
        Scalar::Int64(i) => mysql::Value::from(*i),
        Scalar::Float64(f) => mysql::Value::from(*f),
        Scalar::Utf8(s) => mysql::Value::from(s.as_str()),
        _ => mysql::Value::NULL,
    }
}

#[cfg(feature = "sql-mysql")]
fn mysql_value_to_scalar(v: Option<mysql::Value>) -> Scalar {
    match v {
        None | Some(mysql::Value::NULL) => Scalar::Null(crate::NullKind::Null),
        Some(mysql::Value::Bytes(b)) => Scalar::Utf8(String::from_utf8_lossy(&b).into_owned()),
        Some(mysql::Value::Int(i)) => Scalar::Int64(i),
        Some(mysql::Value::UInt(u)) => Scalar::Int64(u as i64),
        Some(mysql::Value::Float(f)) => Scalar::Float64(f as f64),
        Some(mysql::Value::Double(d)) => Scalar::Float64(d),
        _ => Scalar::Null(crate::NullKind::Null),
    }
}

#[cfg(test)]
fn sql_create_table_query<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    column_defs: &[String],
) -> Result<String, IoError> {
    sql_create_table_query_in_schema(conn, table_name, None, column_defs)
}

/// Build a `CREATE TABLE IF NOT EXISTS ...` statement, optionally
/// schema-qualified.
///
/// Per br-frankenpandas-udn6 (fd90.15). When `schema` is `Some(s)` AND
/// `conn.supports_schemas()`, the target becomes `"schema"."table"`. On
/// backends that report false, any `Some(s)` is silently ignored.
fn sql_create_table_query_in_schema<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    schema: Option<&str>,
    column_defs: &[String],
) -> Result<String, IoError> {
    validate_sql_table_name(table_name)?;
    validate_sql_table_ref_identifier_lengths(conn, table_name, schema)?;
    let qualified = match schema {
        Some(s) if conn.supports_schemas() => {
            validate_sql_schema_name(s)?;
            format!(
                "{}.{}",
                conn.quote_identifier(s)?,
                conn.quote_identifier(table_name)?
            )
        }
        _ => conn.quote_identifier(table_name)?,
    };
    Ok(format!(
        "CREATE TABLE IF NOT EXISTS {qualified} ({})",
        column_defs.join(", ")
    ))
}

#[cfg(test)]
fn sql_insert_rows_query<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    column_names: &[String],
) -> Result<String, IoError> {
    sql_insert_rows_query_in_schema(conn, table_name, None, column_names)
}

/// Build an `INSERT INTO ... VALUES (...)` statement, optionally
/// schema-qualified.
///
/// Per br-frankenpandas-udn6 (fd90.15). Same schema rules as the CREATE
/// TABLE counterpart.
fn sql_insert_rows_query_in_schema<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    schema: Option<&str>,
    column_names: &[String],
) -> Result<String, IoError> {
    validate_sql_table_name(table_name)?;
    validate_sql_table_ref_identifier_lengths(conn, table_name, schema)?;
    validate_sql_column_identifier_lengths(conn, column_names.iter())?;
    let qualified = match schema {
        Some(s) if conn.supports_schemas() => {
            validate_sql_schema_name(s)?;
            format!(
                "{}.{}",
                conn.quote_identifier(s)?,
                conn.quote_identifier(table_name)?
            )
        }
        _ => conn.quote_identifier(table_name)?,
    };
    let quoted_columns = column_names
        .iter()
        .map(|name| conn.quote_identifier(name))
        .collect::<Result<Vec<_>, _>>()?
        .join(", ");
    let placeholders = (1..=column_names.len())
        .map(|ordinal| conn.parameter_marker(ordinal))
        .collect::<Vec<_>>()
        .join(", ");
    Ok(format!(
        "INSERT INTO {qualified} ({quoted_columns}) VALUES ({placeholders})"
    ))
}

/// Build a multi-row `INSERT INTO ... VALUES (...), (...), ...`
/// statement, optionally schema-qualified.
///
/// Placeholder ordinals span 1..=`num_rows` * `column_names.len()` so
/// PostgreSQL-style `$N` markers stay unique across the whole statement.
/// SQLite's `?N` and the bare `?` default also work because positional
/// binding consumes ordinals in left-to-right order.
///
/// Per br-frankenpandas-i0ml (fd90.19).
fn sql_multi_row_insert_query_in_schema<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    schema: Option<&str>,
    column_names: &[String],
    num_rows: usize,
) -> Result<String, IoError> {
    validate_sql_table_name(table_name)?;
    if num_rows == 0 || column_names.is_empty() {
        return Err(IoError::Sql(
            "multi-row insert requires at least one row and one column".to_owned(),
        ));
    }
    validate_sql_table_ref_identifier_lengths(conn, table_name, schema)?;
    validate_sql_column_identifier_lengths(conn, column_names.iter())?;
    let qualified = match schema {
        Some(s) if conn.supports_schemas() => {
            validate_sql_schema_name(s)?;
            format!(
                "{}.{}",
                conn.quote_identifier(s)?,
                conn.quote_identifier(table_name)?
            )
        }
        _ => conn.quote_identifier(table_name)?,
    };
    let quoted_columns = column_names
        .iter()
        .map(|name| conn.quote_identifier(name))
        .collect::<Result<Vec<_>, _>>()?
        .join(", ");
    let cols = column_names.len();
    let mut tuples = Vec::with_capacity(num_rows);
    let mut next_ord = 1usize;
    for _ in 0..num_rows {
        let row_placeholders = (0..cols)
            .map(|_| {
                let marker = conn.parameter_marker(next_ord);
                next_ord += 1;
                marker
            })
            .collect::<Vec<_>>()
            .join(", ");
        tuples.push(format!("({row_placeholders})"));
    }
    Ok(format!(
        "INSERT INTO {qualified} ({quoted_columns}) VALUES {}",
        tuples.join(", ")
    ))
}

/// Build a `DROP TABLE IF EXISTS ...` statement, optionally
/// schema-qualified.
///
/// Per br-frankenpandas-hxob (fd90.16). Companion to
/// `sql_create_table_query_in_schema`. Same schema rules: when
/// `schema` is `Some(s)` AND `conn.supports_schemas()`, the target
/// becomes `\"schema\".\"table\"`; otherwise the bare table name is
/// used. Routes through `conn.quote_identifier` so backend dialect
/// overrides (MySQL backticks etc.) take effect on the drop path.
fn sql_drop_table_query_in_schema<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    schema: Option<&str>,
) -> Result<String, IoError> {
    validate_sql_table_name(table_name)?;
    validate_sql_table_ref_identifier_lengths(conn, table_name, schema)?;
    let qualified = match schema {
        Some(s) if conn.supports_schemas() => {
            validate_sql_schema_name(s)?;
            format!(
                "{}.{}",
                conn.quote_identifier(s)?,
                conn.quote_identifier(table_name)?
            )
        }
        _ => conn.quote_identifier(table_name)?,
    };
    Ok(format!("DROP TABLE IF EXISTS {qualified}"))
}

/// Read the result of a SQL query into a DataFrame.
///
/// Matches `pd.read_sql(sql, con)`.
pub fn read_sql<C: SqlConnection>(conn: &C, query: &str) -> Result<DataFrame, IoError> {
    read_sql_with_options(conn, query, &SqlReadOptions::default())
}

/// Read the result of a SQL query into a DataFrame with read-time options.
///
/// Matches the supported subset of `pd.read_sql(sql, con, params=[...], parse_dates=...)`.
pub fn read_sql_with_options<C: SqlConnection>(
    conn: &C,
    query: &str,
    options: &SqlReadOptions,
) -> Result<DataFrame, IoError> {
    // Per br-frankenpandas-t1777: query readers take a raw SELECT written
    // by the caller, so options.columns has no effect. Silently ignoring
    // diverged from the table-reader sibling. Reject to surface the
    // mismatch — callers should embed the column list in the SELECT, or
    // use read_sql_table_with_options to generate the projection.
    if options.columns.is_some() {
        return Err(IoError::Sql(
            "options.columns is meaningful only for table readers; embed the column list in \
             the SELECT or use read_sql_table_with_options to generate the projection from a \
             table name"
                .to_owned(),
        ));
    }
    let (headers, columns, dtype_hints) = sql_query_to_columns(conn, query, options)?;
    let frame = dataframe_from_sql_columns(headers, columns, dtype_hints)?;
    apply_sql_index_col(frame, options.index_col.as_deref())
}

/// Per br-frankenpandas-c1h9 (fd90.36): promote `options.index_col`
/// to the DataFrame index when set, with empty-string rejection.
fn apply_sql_index_col(frame: DataFrame, index_col: Option<&str>) -> Result<DataFrame, IoError> {
    let Some(name) = index_col else {
        return Ok(frame);
    };
    if name.is_empty() {
        return Err(IoError::Sql(
            "index_col: empty string is not a valid column name".to_owned(),
        ));
    }
    promote_column_to_index(&frame, name)
}

/// Read the result of a SQL query into a DataFrame.
///
/// Matches `pd.read_sql_query(sql, con)`. This is the query-only spelling of
/// `read_sql`; table-name dispatch stays on `read_sql_table`.
pub fn read_sql_query<C: SqlConnection>(conn: &C, query: &str) -> Result<DataFrame, IoError> {
    read_sql(conn, query)
}

/// Read the result of a SQL query into a DataFrame with read-time options.
///
/// Matches the supported subset of
/// `pd.read_sql_query(sql, con, params=[...], parse_dates=..., coerce_float=...)`.
pub fn read_sql_query_with_options<C: SqlConnection>(
    conn: &C,
    query: &str,
    options: &SqlReadOptions,
) -> Result<DataFrame, IoError> {
    read_sql_with_options(conn, query, options)
}

/// Read a SQL query result with read-time options and optional index promotion.
///
/// Matches the supported subset of
/// `pd.read_sql_query(sql, con, params=[...], parse_dates=..., coerce_float=..., index_col=...)`.
pub fn read_sql_query_with_options_and_index_col<C: SqlConnection>(
    conn: &C,
    query: &str,
    options: &SqlReadOptions,
    index_col: Option<&str>,
) -> Result<DataFrame, IoError> {
    if let Some(col_name) = index_col {
        let cleared = SqlReadOptions {
            index_col: None,
            ..options.clone()
        };
        let frame = read_sql_query_with_options(conn, query, &cleared)?;
        return apply_sql_index_col(frame, Some(col_name));
    }
    read_sql_query_with_options(conn, query, options)
}

/// Read the result of a SQL query as an iterator of DataFrame chunks.
///
/// Matches the supported subset of `pd.read_sql_query(sql, con, chunksize=...)`.
pub fn read_sql_query_chunks<'conn, C: SqlConnection + 'conn>(
    conn: &'conn C,
    query: &str,
    chunk_size: usize,
) -> Result<SqlChunkIterator<'conn>, IoError> {
    read_sql_chunks(conn, query, chunk_size)
}

/// Read a SQL query result as chunks with one column promoted to each chunk's index.
///
/// Matches the supported subset of
/// `pd.read_sql_query(sql, con, index_col=..., chunksize=...)`.
pub fn read_sql_query_chunks_with_index_col<'conn, C: SqlConnection + 'conn>(
    conn: &'conn C,
    query: &str,
    index_col: Option<&str>,
    chunk_size: usize,
) -> Result<SqlIndexedChunkIterator<'conn>, IoError> {
    read_sql_chunks_with_index_col(conn, query, index_col, chunk_size)
}

/// Read the result of a SQL query as chunks with read-time options.
///
/// Matches the supported subset of
/// `pd.read_sql_query(sql, con, params=[...], parse_dates=..., coerce_float=..., chunksize=...)`.
pub fn read_sql_query_chunks_with_options<'conn, C: SqlConnection + 'conn>(
    conn: &'conn C,
    query: &str,
    options: &SqlReadOptions,
    chunk_size: usize,
) -> Result<SqlChunkIterator<'conn>, IoError> {
    if options.index_col.is_some() {
        return Err(IoError::Sql(
            "options.index_col is set but this entrypoint returns SqlChunkIterator without \
             index promotion; use read_sql_query_chunks_with_options_and_index_col to honor \
             index_col"
                .to_owned(),
        ));
    }
    read_sql_chunks_with_options(conn, query, options, chunk_size)
}

/// Read a SQL query result as chunks with read-time options and index promotion.
///
/// Matches the supported subset of
/// `pd.read_sql_query(sql, con, params=[...], parse_dates=..., coerce_float=..., index_col=..., chunksize=...)`.
pub fn read_sql_query_chunks_with_options_and_index_col<'conn, C: SqlConnection + 'conn>(
    conn: &'conn C,
    query: &str,
    options: &SqlReadOptions,
    index_col: Option<&str>,
    chunk_size: usize,
) -> Result<SqlIndexedChunkIterator<'conn>, IoError> {
    read_sql_chunks_with_options_and_index_col(conn, query, options, index_col, chunk_size)
}

/// Read a SQL query result with one column promoted to the index.
///
/// Matches `pd.read_sql_query(sql, con, index_col=...)`.
pub fn read_sql_query_with_index_col<C: SqlConnection>(
    conn: &C,
    query: &str,
    index_col: Option<&str>,
) -> Result<DataFrame, IoError> {
    read_sql_with_index_col(conn, query, index_col)
}

fn sql_trim_chunk_source(query: &str) -> Result<&str, IoError> {
    let trimmed = query.trim().trim_end_matches(';').trim();
    if trimmed.is_empty() {
        Err(IoError::Sql("read_sql query must be non-empty".to_owned()))
    } else {
        Ok(trimmed)
    }
}

fn sql_paged_query<C: SqlConnection + ?Sized>(
    conn: &C,
    query: &str,
    base_param_count: usize,
) -> Result<String, IoError> {
    let source = sql_trim_chunk_source(query)?;
    let limit_marker = conn.parameter_marker(base_param_count + 1);
    let offset_marker = conn.parameter_marker(base_param_count + 2);
    Ok(format!(
        "SELECT * FROM ({source}) AS frankenpandas_sql_chunk_source \
         LIMIT {limit_marker} OFFSET {offset_marker}"
    ))
}

fn sql_paged_options(
    options: &SqlReadOptions,
    limit: usize,
    offset: usize,
) -> Result<SqlReadOptions, IoError> {
    let limit = i64::try_from(limit)
        .map_err(|_| IoError::Sql("read_sql chunksize exceeds i64 range".to_owned()))?;
    let offset = i64::try_from(offset)
        .map_err(|_| IoError::Sql("read_sql chunk offset exceeds i64 range".to_owned()))?;
    let mut params = options.params.clone().unwrap_or_default();
    params.push(Scalar::Int64(limit));
    params.push(Scalar::Int64(offset));
    Ok(SqlReadOptions {
        params: Some(params),
        ..options.clone()
    })
}

fn sql_paged_query_headers<C: SqlConnection + ?Sized>(
    conn: &C,
    query: &str,
    options: &SqlReadOptions,
) -> Result<Vec<String>, IoError> {
    let base_param_count = options.params.as_ref().map_or(0, Vec::len);
    let paged_query = sql_paged_query(conn, query, base_param_count)?;
    let paged_options = sql_paged_options(options, 0, 0)?;
    let result = conn.query(&paged_query, paged_options.params.as_deref().unwrap_or(&[]))?;
    reject_duplicate_headers(&result.columns)?;
    Ok(result.columns)
}

fn sql_query_to_columns_paged<C: SqlConnection + ?Sized>(
    conn: &C,
    query: &str,
    options: &SqlReadOptions,
    chunk_size: usize,
    offset: usize,
) -> Result<SqlMaterializedColumns, IoError> {
    let base_param_count = options.params.as_ref().map_or(0, Vec::len);
    let paged_query = sql_paged_query(conn, query, base_param_count)?;
    let paged_options = sql_paged_options(options, chunk_size, offset)?;
    sql_query_to_columns(conn, &paged_query, &paged_options)
}

fn sql_query_to_columns<C: SqlConnection + ?Sized>(
    conn: &C,
    query: &str,
    options: &SqlReadOptions,
) -> Result<SqlMaterializedColumns, IoError> {
    let params = options.params.as_deref().unwrap_or(&[]);
    let SqlQueryResult {
        columns: headers,
        rows,
    } = conn.query(query, params)?;
    reject_duplicate_headers(&headers)?;
    let mut dtype_hints = conn.query_column_dtypes(query, params)?;
    dtype_hints.resize(headers.len(), None);
    let mut columns: Vec<Vec<Scalar>> = (0..headers.len()).map(|_| Vec::new()).collect();

    for row in rows {
        for (col_idx, value) in row.into_iter().enumerate() {
            if let Some(col_vec) = columns.get_mut(col_idx) {
                col_vec.push(value);
            }
        }
    }

    if let Some(ref parse_dates) = options.parse_dates {
        apply_parse_dates(&headers, &mut columns, parse_dates)?;
    }
    if options.coerce_float {
        apply_sql_coerce_float(&mut columns);
    }
    if let Some(ref dtype_map) = options.dtype {
        apply_sql_dtype_overrides(
            &headers,
            &mut columns,
            dtype_map,
            options.parse_dates.as_deref().unwrap_or(&[]),
        )?;
        for (idx, header) in headers.iter().enumerate() {
            if let Some(dtype) = dtype_map.get(header)
                && !options
                    .parse_dates
                    .as_deref()
                    .unwrap_or(&[])
                    .iter()
                    .any(|d| d == header)
            {
                dtype_hints[idx] = Some(*dtype);
            }
        }
    }

    Ok((headers, columns, dtype_hints))
}

/// Apply pandas-style `dtype={'col': dtype}` overrides to materialized
/// SQL result columns. Skips columns also listed in `parse_dates` to
/// avoid double-cast errors. Per br-frankenpandas-l9pt (fd90.11).
fn apply_sql_dtype_overrides(
    headers: &[String],
    columns: &mut [Vec<Scalar>],
    dtype_map: &BTreeMap<String, DType>,
    parse_dates: &[String],
) -> Result<(), IoError> {
    for (idx, header) in headers.iter().enumerate() {
        let Some(target_dtype) = dtype_map.get(header) else {
            continue;
        };
        if parse_dates.iter().any(|d| d == header) {
            // parse_dates wins; skip dtype override for this column.
            continue;
        }
        let Some(col) = columns.get_mut(idx) else {
            continue;
        };
        for value in col.iter_mut() {
            // Take ownership of the scalar, cast, and write back. NaT/Null
            // pass through cast_scalar_owned unchanged so missingness is
            // preserved across the override.
            let taken = std::mem::replace(value, Scalar::Null(NullKind::Null));
            *value = cast_scalar_owned(taken, *target_dtype).map_err(|e| {
                IoError::Sql(format!(
                    "dtype override on column '{header}' to {target_dtype:?} failed: {e}"
                ))
            })?;
        }
    }
    Ok(())
}

fn dataframe_from_sql_columns(
    headers: Vec<String>,
    columns: Vec<Vec<Scalar>>,
    dtype_hints: SqlColumnDtypeHints,
) -> Result<DataFrame, IoError> {
    let row_count = columns.first().map_or(0, Vec::len);
    let mut out_columns = BTreeMap::new();
    let mut column_order = Vec::new();

    for (idx, (name, values)) in headers.into_iter().zip(columns).enumerate() {
        let dtype_hint = dtype_hints.get(idx).copied().flatten();
        let has_observed_value = values.iter().any(|value| !matches!(value, Scalar::Null(_)));
        let column = match (has_observed_value, dtype_hint) {
            (false, Some(dtype)) => Column::new(dtype, values)?,
            _ => Column::from_values(values)?,
        };
        out_columns.insert(name.clone(), column);
        column_order.push(name);
    }

    let index = Index::from_i64((0..row_count as i64).collect());
    Ok(DataFrame::new_with_column_order(
        index,
        out_columns,
        column_order,
    )?)
}

/// Read a SQL query result as an iterator of DataFrame chunks.
///
/// Matches the supported subset of `pd.read_sql(sql, con, chunksize=...)`.
/// Each chunk receives a fresh zero-based RangeIndex, matching pandas'
/// SQLite chunk iterator behavior.
pub fn read_sql_chunks<'conn, C: SqlConnection + 'conn>(
    conn: &'conn C,
    query: &str,
    chunk_size: usize,
) -> Result<SqlChunkIterator<'conn>, IoError> {
    read_sql_chunks_with_options(conn, query, &SqlReadOptions::default(), chunk_size)
}

/// Read a SQL query result as DataFrame chunks with read-time options.
///
/// Backends that opt into `supports_paged_sql_chunks` are queried one bounded
/// page at a time through a `LIMIT`/`OFFSET` wrapper so the iterator does not
/// hold the full result set in memory. Other backends keep the legacy
/// materialized fallback until they provide a native chunk strategy. `params`,
/// `parse_dates`, `coerce_float`, and `dtype` are applied to each yielded page.
pub fn read_sql_chunks_with_options<'conn, C: SqlConnection + 'conn>(
    conn: &'conn C,
    query: &str,
    options: &SqlReadOptions,
    chunk_size: usize,
) -> Result<SqlChunkIterator<'conn>, IoError> {
    if chunk_size == 0 {
        return Err(IoError::Sql(
            "read_sql chunksize must be greater than zero".to_owned(),
        ));
    }
    // Per br-frankenpandas-i8kja: this entrypoint returns SqlChunkIterator
    // with no index promotion. Honoring options.index_col would silently
    // diverge from the full-frame read_sql_with_options sibling (which
    // does promote). Reject to surface the mismatch — callers should use
    // read_sql_chunks_with_options_and_index_col when index_col is set.
    if options.index_col.is_some() {
        return Err(IoError::Sql(
            "options.index_col is set but this entrypoint returns SqlChunkIterator without \
             index promotion; use read_sql_chunks_with_options_and_index_col to honor index_col"
                .to_owned(),
        ));
    }
    // Per br-frankenpandas-t1777: query readers take a raw SELECT written
    // by the caller, so options.columns has no effect (the projection is
    // already in the query string). Silently ignoring would diverge from
    // the table-reader sibling (which honors columns to build the SELECT).
    // Reject to surface the mismatch — callers should embed the column
    // list in the SELECT, or use read_sql_table_chunks_with_options when
    // generating the SELECT from a table name.
    if options.columns.is_some() {
        return Err(IoError::Sql(
            "options.columns is meaningful only for table readers; embed the column list in \
             the SELECT or use read_sql_table_chunks_with_options to generate the projection \
             from a table name"
                .to_owned(),
        ));
    }

    if conn.supports_paged_sql_chunks() {
        return SqlChunkIterator::paged(conn, query, options, chunk_size);
    }

    let (headers, columns, dtype_hints) = sql_query_to_columns(conn, query, options)?;
    Ok(SqlChunkIterator::materialized(
        headers,
        columns,
        dtype_hints,
        chunk_size,
    ))
}

/// Read a SQL query result as DataFrame chunks with read-time options and optional index promotion.
///
/// `params`, `parse_dates`, `coerce_float`, and `dtype` are applied to each
/// yielded page before optional index promotion.
pub fn read_sql_chunks_with_options_and_index_col<'conn, C: SqlConnection + 'conn>(
    conn: &'conn C,
    query: &str,
    options: &SqlReadOptions,
    index_col: Option<&str>,
    chunk_size: usize,
) -> Result<SqlIndexedChunkIterator<'conn>, IoError> {
    // Per br-frankenpandas-t1777: query readers can't apply options.columns
    // (caller writes the SELECT). Reject for consistency with the plain
    // chunk reader's rejection — the indexed sibling shouldn't be a
    // backdoor.
    if options.columns.is_some() {
        return Err(IoError::Sql(
            "options.columns is meaningful only for table readers; embed the column list in \
             the SELECT or use read_sql_table_chunks_with_options_and_index_col to generate \
             the projection from a table name"
                .to_owned(),
        ));
    }
    // The plain chunk reader rejects options.index_col (see i8kja); clear
    // it before delegating so the indexed sibling is the canonical
    // honor-index_col entrypoint regardless of which slot the caller used.
    let cleared = SqlReadOptions {
        index_col: None,
        ..options.clone()
    };
    let inner = read_sql_chunks_with_options(conn, query, &cleared, chunk_size)?;
    sql_indexed_chunks(inner, index_col.or(options.index_col.as_deref()))
}

/// Read a SQL query result as DataFrame chunks with optional index promotion.
///
/// Matches the supported subset of `pd.read_sql(sql, con, index_col=..., chunksize=...)`.
pub fn read_sql_chunks_with_index_col<'conn, C: SqlConnection + 'conn>(
    conn: &'conn C,
    query: &str,
    index_col: Option<&str>,
    chunk_size: usize,
) -> Result<SqlIndexedChunkIterator<'conn>, IoError> {
    let inner = read_sql_chunks(conn, query, chunk_size)?;
    sql_indexed_chunks(inner, index_col)
}

/// Read a SQL query result with one column promoted to the index.
///
/// Matches `pd.read_sql(sql, con, index_col=...)`. When
/// `index_col=Some(name)` the named column is removed from the data
/// columns and its values become the DataFrame's row index. Returns
/// `IoError::Sql` if the named column is absent from the result set.
pub fn read_sql_with_index_col<C: SqlConnection>(
    conn: &C,
    query: &str,
    index_col: Option<&str>,
) -> Result<DataFrame, IoError> {
    let frame = read_sql(conn, query)?;
    apply_sql_index_col(frame, index_col)
}

/// Read an entire SQL table with one column promoted to the index.
///
/// Matches `pd.read_sql_table(table, con, index_col=...)`.
pub fn read_sql_table_with_index_col<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    index_col: Option<&str>,
) -> Result<DataFrame, IoError> {
    let frame = read_sql_table(conn, table_name)?;
    apply_sql_index_col(frame, index_col)
}

fn promote_column_to_index(frame: &DataFrame, col_name: &str) -> Result<DataFrame, IoError> {
    let column = frame.column(col_name).ok_or_else(|| {
        IoError::Sql(format!(
            "index_col {col_name:?} not present in result columns"
        ))
    })?;
    let labels: Vec<IndexLabel> = column
        .values()
        .iter()
        .map(|v| match v {
            Scalar::Int64(i) => IndexLabel::Int64(*i),
            Scalar::Utf8(s) => IndexLabel::Utf8(s.clone()),
            Scalar::Float64(f) if !f.is_nan() => IndexLabel::Utf8(f.to_string()),
            Scalar::Bool(b) => IndexLabel::Utf8(if *b { "True" } else { "False" }.to_string()),
            Scalar::Timedelta64(ns) => IndexLabel::Timedelta64(*ns),
            _ => IndexLabel::Utf8("NaN".to_owned()),
        })
        .collect();
    let new_index = Index::new(labels).set_name(col_name);

    let mut new_columns = std::collections::BTreeMap::new();
    let mut new_order = Vec::new();
    for name in frame.column_names() {
        if name == col_name {
            continue;
        }
        if let Some(col) = frame.column(name) {
            new_columns.insert(name.clone(), col.clone());
            new_order.push(name.clone());
        }
    }

    Ok(DataFrame::new_with_column_order(
        new_index,
        new_columns,
        new_order,
    )?)
}

/// Read an entire SQL table into a DataFrame.
///
/// Matches `pd.read_sql_table(table_name, con)`.
pub fn read_sql_table<C: SqlConnection>(conn: &C, table_name: &str) -> Result<DataFrame, IoError> {
    read_sql(conn, &sql_select_all_query(conn, table_name)?)
}

/// List user-visible table names known to the SQL backend.
///
/// Matches the supported subset of
/// `pd.io.sql.SQLDatabase.list_tables(schema=...)`. When the backend
/// reports `supports_schemas() == false` (SQLite), `schema` is ignored
/// and all tables in the single namespace are returned. When the
/// backend supports schemas (PostgreSQL, MySQL, MSSQL), `Some(s)`
/// scopes the listing. `None` passes through to the backend
/// unchanged — backends MAY consult `default_schema()` for their own
/// fallback logic if desired (per fd90.57: this wrapper does NOT
/// apply the fallback automatically).
///
/// Per br-frankenpandas-vhq2 (fd90.20).
pub fn list_sql_tables<C: SqlConnection>(
    conn: &C,
    schema: Option<&str>,
) -> Result<Vec<String>, IoError> {
    conn.list_tables(schema)
}

/// Introspect a SQL table's column metadata, optionally schema-scoped.
///
/// Matches the supported subset of
/// `pd.io.sql.SQLDatabase.has_table` + `SQLAlchemy.MetaData.reflect`
/// for column-level details. Returns `Ok(None)` when the table does
/// not exist. Schema arg is silently ignored when the backend reports
/// `supports_schemas() == false` (SQLite).
///
/// Per br-frankenpandas-w43q (fd90.21).
pub fn sql_table_schema<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    schema: Option<&str>,
) -> Result<Option<SqlTableSchema>, IoError> {
    conn.table_schema(table_name, schema)
}

/// List user-visible schemas exposed by the SQL backend.
///
/// Matches `SQLAlchemy.Inspector.get_schema_names()` shape. Single
/// namespace backends (SQLite) return an empty vector. Multi-schema
/// backends return the schemas the connection's role can see, with
/// internal/system schemas filtered out.
///
/// Per br-frankenpandas-lxhi (fd90.22).
pub fn list_sql_schemas<C: SqlConnection>(conn: &C) -> Result<Vec<String>, IoError> {
    conn.list_schemas()
}

/// Reset a SQL table to empty without dropping its definition.
///
/// On backends that override the default (PostgreSQL, MySQL), this
/// uses `TRUNCATE TABLE` for a DDL-style fast-path reset. On backends
/// that inherit the default (SQLite), this emits `DELETE FROM <table>`,
/// which is universal but slower on large tables. Schema arg is
/// silently ignored when `supports_schemas() == false`.
///
/// Per br-frankenpandas-phum (fd90.23).
pub fn truncate_sql_table<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    schema: Option<&str>,
) -> Result<(), IoError> {
    conn.truncate_table(table_name, schema)
}

/// Probe the SQL backend's server version string.
///
/// Returns `Ok(None)` for backends that can't (or don't) introspect
/// their version. SQLite returns `Some("3.x.y")`. PostgreSQL/MySQL
/// impls return their respective `SHOW server_version` /
/// `SELECT VERSION()` payloads. Useful for dialect-version gating
/// (RETURNING, JSON ops, generated columns) and diagnostics.
///
/// Per br-frankenpandas-e23k (fd90.24).
pub fn sql_server_version<C: SqlConnection>(conn: &C) -> Result<Option<String>, IoError> {
    conn.server_version()
}

/// Return the primary-key column names for a SQL table, ordered by
/// the table's primary-key ordinal.
///
/// Returns an empty vector when the table doesn't exist, has no
/// primary key, or the backend can't introspect column metadata.
/// Useful for upsert conflict-target generation and `index_label`
/// defaulting.
///
/// Per br-frankenpandas-uw3y (fd90.25).
pub fn sql_primary_key_columns<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    schema: Option<&str>,
) -> Result<Vec<String>, IoError> {
    conn.primary_key_columns(table_name, schema)
}

/// List user-defined indexes on a SQL table, optionally schema-scoped.
///
/// Matches `SQLAlchemy.Inspector.get_indexes()` shape. Returns an
/// empty vector when the table doesn't exist, has no user-created
/// indexes, or the backend can't introspect. Auto-created PRIMARY-KEY
/// indexes are filtered out (they're surfaced via primary_key_columns
/// instead).
///
/// Per br-frankenpandas-bgv9 (fd90.28).
pub fn list_sql_indexes<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    schema: Option<&str>,
) -> Result<Vec<SqlIndexSchema>, IoError> {
    conn.list_indexes(table_name, schema)
}

/// List user-visible view names known to the SQL backend.
///
/// Matches `SQLAlchemy.Inspector.get_view_names()` shape. Companion
/// to `list_sql_tables` — pandas/SQLAlchemy keep tables and views in
/// distinct buckets so `pd.read_sql_table` can distinguish them.
/// Schema arg is silently ignored when `supports_schemas() == false`.
///
/// Per br-frankenpandas-gm3r (fd90.30).
pub fn list_sql_views<C: SqlConnection>(
    conn: &C,
    schema: Option<&str>,
) -> Result<Vec<String>, IoError> {
    conn.list_views(schema)
}

/// List foreign-key constraints declared on a SQL table, optionally
/// schema-scoped.
///
/// Matches `SQLAlchemy.Inspector.get_foreign_keys()` shape. Returns
/// an empty vector when the table has no FKs or the backend can't
/// introspect. Composite FKs are returned as a single entry with
/// paired `columns` / `referenced_columns` ordered by declaration
/// position. SQLite does not expose constraint names via PRAGMA, so
/// `constraint_name` is `None` there.
///
/// Per br-frankenpandas-uht8 (fd90.29).
pub fn list_sql_foreign_keys<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    schema: Option<&str>,
) -> Result<Vec<SqlForeignKeySchema>, IoError> {
    conn.list_foreign_keys(table_name, schema)
}

/// Probe the table-level comment for a SQL table, optionally
/// schema-scoped.
///
/// Matches `SQLAlchemy.Inspector.get_table_comment()` shape — returns
/// `Ok(Some(text))` when a comment exists, `Ok(None)` otherwise.
/// SQLite has no native table-comment storage and returns `None`.
/// PostgreSQL/MySQL/MSSQL impls override with their respective
/// catalog queries.
///
/// Per br-frankenpandas-yu3w (fd90.32).
pub fn sql_table_comment<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    schema: Option<&str>,
) -> Result<Option<String>, IoError> {
    conn.table_comment(table_name, schema)
}

/// List UNIQUE constraints declared on a SQL table.
///
/// Matches `SQLAlchemy.Inspector.get_unique_constraints()` shape.
/// Surfaces only inline `UNIQUE` declarations and `UNIQUE (...)`
/// table constraints. User-created `CREATE UNIQUE INDEX` indexes
/// remain in `list_sql_indexes` (with `unique == true`). The two
/// listings are intentionally disjoint to match SQLAlchemy.
///
/// Per br-frankenpandas-sh4v (fd90.31).
pub fn list_sql_unique_constraints<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    schema: Option<&str>,
) -> Result<Vec<SqlUniqueConstraintSchema>, IoError> {
    conn.list_unique_constraints(table_name, schema)
}

/// Maximum identifier length supported by the SQL backend, or `None`
/// when no documented limit exists.
///
/// Useful for to_sql validation: backends that override this report
/// their cap (PostgreSQL=63, MySQL=64, MSSQL=128) so auto-generated
/// index / constraint / column names can be truncated or rejected
/// before round-tripping through DDL that would silently truncate.
///
/// Per br-frankenpandas-cs81 (fd90.26).
pub fn sql_max_identifier_length<C: SqlConnection>(conn: &C) -> Option<usize> {
    conn.max_identifier_length()
}

/// Backend capability summary exposed through `SqlInspector`.
///
/// The per-field values come from `SqlConnection` probes so concrete
/// backends can report their native ceilings without forcing callers to
/// branch on the connection type.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SqlBackendCaps {
    pub dialect_name: &'static str,
    pub server_version: Option<String>,
    pub supports_returning: bool,
    pub supports_schemas: bool,
    pub max_param_count: Option<usize>,
    pub max_identifier_length: Option<usize>,
}

impl SqlBackendCaps {
    /// Maximum rows in one parameter-bound INSERT for `column_count`.
    ///
    /// Returns `None` when the backend has no known parameter ceiling, or
    /// when `column_count` is zero and therefore no parameter-derived row
    /// ceiling can be computed.
    #[must_use]
    pub fn max_insert_rows(&self, column_count: usize) -> Option<usize> {
        sql_max_insert_rows_for_columns(self.max_param_count, column_count)
    }
}

/// Maximum bound parameters supported by the SQL backend, if known.
#[must_use]
pub fn sql_max_param_count<C: SqlConnection>(conn: &C) -> Option<usize> {
    conn.max_param_count()
}

/// Whether the SQL backend supports native `INSERT ... RETURNING`.
#[must_use]
pub fn sql_supports_returning<C: SqlConnection>(conn: &C) -> bool {
    conn.supports_returning()
}

/// Whether the SQL backend exposes schema-qualified namespaces.
#[must_use]
pub fn sql_supports_schemas<C: SqlConnection>(conn: &C) -> bool {
    conn.supports_schemas()
}

/// Maximum INSERT rows for `column_count`, derived from the backend's
/// bound-parameter ceiling.
///
/// A return value of `Some(0)` means the requested column count exceeds
/// the backend's total bind-parameter cap.
#[must_use]
pub fn sql_max_insert_rows<C: SqlConnection>(conn: &C, column_count: usize) -> Option<usize> {
    sql_max_insert_rows_for_columns(conn.max_param_count(), column_count)
}

fn sql_max_insert_rows_for_columns(
    max_param_count: Option<usize>,
    column_count: usize,
) -> Option<usize> {
    if column_count == 0 {
        return None;
    }
    max_param_count.map(|max| max / column_count)
}

/// Gather the backend capability probes into one typed bundle.
pub fn sql_backend_caps<C: SqlConnection>(conn: &C) -> Result<SqlBackendCaps, IoError> {
    Ok(SqlBackendCaps {
        dialect_name: conn.dialect_name(),
        server_version: conn.server_version()?,
        supports_returning: conn.supports_returning(),
        supports_schemas: conn.supports_schemas(),
        max_param_count: conn.max_param_count(),
        max_identifier_length: conn.max_identifier_length(),
    })
}

/// Backend-agnostic introspection facade matching the
/// `SQLAlchemy.Inspector` shape.
///
/// Per br-frankenpandas-szs9 (fd90.38). Wraps a `&C: SqlConnection`
/// and exposes the full fd90.20-37 introspection surface as methods
/// on a single bundle so callers don't have to remember which
/// `list_sql_*` / `sql_*` free-fn to use. Pure delegation — no new
/// behavior, just API ergonomics.
///
/// ```rust,ignore
/// use frankenpandas::SqlInspector;
/// let inspector = SqlInspector::new(&conn);
/// for table in inspector.tables(None)? {
///     for col in inspector.columns(&table, None)?
///         .map(|s| s.columns)
///         .unwrap_or_default()
///     {
///         println!("{}: {:?}", col.name, col.declared_type);
///     }
/// }
/// ```
#[derive(Debug)]
pub struct SqlInspector<'a, C: SqlConnection> {
    conn: &'a C,
}

impl<'a, C: SqlConnection> SqlInspector<'a, C> {
    /// Create a new inspector bound to the given connection.
    #[must_use]
    pub fn new(conn: &'a C) -> Self {
        Self { conn }
    }

    /// List user-visible table names. See `list_sql_tables`.
    pub fn tables(&self, schema: Option<&str>) -> Result<Vec<String>, IoError> {
        self.conn.list_tables(schema)
    }

    /// List user-visible view names. See `list_sql_views`.
    pub fn views(&self, schema: Option<&str>) -> Result<Vec<String>, IoError> {
        self.conn.list_views(schema)
    }

    /// List user-visible schemas. See `list_sql_schemas`.
    pub fn schemas(&self) -> Result<Vec<String>, IoError> {
        self.conn.list_schemas()
    }

    /// Introspect a table's columns. See `sql_table_schema`.
    pub fn columns(
        &self,
        table_name: &str,
        schema: Option<&str>,
    ) -> Result<Option<SqlTableSchema>, IoError> {
        self.conn.table_schema(table_name, schema)
    }

    /// List user-defined indexes. See `list_sql_indexes`.
    pub fn indexes(
        &self,
        table_name: &str,
        schema: Option<&str>,
    ) -> Result<Vec<SqlIndexSchema>, IoError> {
        self.conn.list_indexes(table_name, schema)
    }

    /// List foreign-key constraints. See `list_sql_foreign_keys`.
    pub fn foreign_keys(
        &self,
        table_name: &str,
        schema: Option<&str>,
    ) -> Result<Vec<SqlForeignKeySchema>, IoError> {
        self.conn.list_foreign_keys(table_name, schema)
    }

    /// List UNIQUE constraints. See `list_sql_unique_constraints`.
    pub fn unique_constraints(
        &self,
        table_name: &str,
        schema: Option<&str>,
    ) -> Result<Vec<SqlUniqueConstraintSchema>, IoError> {
        self.conn.list_unique_constraints(table_name, schema)
    }

    /// Return primary-key columns sorted by ordinal.
    /// See `sql_primary_key_columns`.
    pub fn primary_key_columns(
        &self,
        table_name: &str,
        schema: Option<&str>,
    ) -> Result<Vec<String>, IoError> {
        self.conn.primary_key_columns(table_name, schema)
    }

    /// Probe the table-level comment. See `sql_table_comment`.
    pub fn table_comment(
        &self,
        table_name: &str,
        schema: Option<&str>,
    ) -> Result<Option<String>, IoError> {
        self.conn.table_comment(table_name, schema)
    }

    /// Schema-aware existence check. Routes to
    /// `SqlConnection::table_exists_in_schema`.
    pub fn table_exists(&self, table_name: &str, schema: Option<&str>) -> Result<bool, IoError> {
        self.conn.table_exists_in_schema(table_name, schema)
    }

    /// Probe the backend server version. See `sql_server_version`.
    pub fn server_version(&self) -> Result<Option<String>, IoError> {
        self.conn.server_version()
    }

    /// Maximum identifier length, when the backend exposes one.
    /// See `sql_max_identifier_length`.
    #[must_use]
    pub fn max_identifier_length(&self) -> Option<usize> {
        self.conn.max_identifier_length()
    }

    /// Maximum bound parameters supported by this backend, if known.
    #[must_use]
    pub fn max_param_count(&self) -> Option<usize> {
        self.conn.max_param_count()
    }

    /// Maximum INSERT rows for `column_count`, derived from the backend's
    /// bound-parameter ceiling.
    #[must_use]
    pub fn max_insert_rows(&self, column_count: usize) -> Option<usize> {
        sql_max_insert_rows_for_columns(self.conn.max_param_count(), column_count)
    }

    /// Whether this backend supports native `INSERT ... RETURNING`.
    #[must_use]
    pub fn supports_returning(&self) -> bool {
        self.conn.supports_returning()
    }

    /// Whether this backend exposes schema-qualified namespaces.
    #[must_use]
    pub fn supports_schemas(&self) -> bool {
        self.conn.supports_schemas()
    }

    /// Gather backend capability probes into one typed bundle.
    pub fn backend_caps(&self) -> Result<SqlBackendCaps, IoError> {
        sql_backend_caps(self.conn)
    }

    /// Backend dialect name (`"sqlite"`, `"postgresql"`, etc.).
    #[must_use]
    pub fn dialect_name(&self) -> &'static str {
        self.conn.dialect_name()
    }

    /// Check whether a specific column exists on a table.
    ///
    /// Per br-frankenpandas-ppry (fd90.39). Returns `Ok(false)` when
    /// the table doesn't exist (i.e. `columns` returns `None`), or
    /// when the table exists but has no column matching `column_name`.
    /// Returns `Ok(true)` only when the named column is present.
    /// Mirrors `SQLAlchemy.Inspector.has_column()` semantics.
    pub fn has_column(
        &self,
        table_name: &str,
        column_name: &str,
        schema: Option<&str>,
    ) -> Result<bool, IoError> {
        let Some(meta) = self.conn.table_schema(table_name, schema)? else {
            return Ok(false);
        };
        Ok(meta.column(column_name).is_some())
    }

    /// Look up the metadata bundle for a single column.
    ///
    /// Per br-frankenpandas-ppry (fd90.39). Returns `Ok(None)` when the
    /// table doesn't exist or the column isn't present. The returned
    /// `SqlColumnSchema` carries the full set of fields populated by
    /// the underlying `table_schema` impl (declared_type, nullable,
    /// default_value, primary_key_ordinal, comment, autoincrement).
    pub fn column(
        &self,
        table_name: &str,
        column_name: &str,
        schema: Option<&str>,
    ) -> Result<Option<SqlColumnSchema>, IoError> {
        let Some(meta) = self.conn.table_schema(table_name, schema)? else {
            return Ok(None);
        };
        Ok(meta.column(column_name).cloned())
    }

    /// Reflect a full table's metadata in one call: columns, primary
    /// key, indexes, foreign keys, unique constraints, and comment.
    ///
    /// Per br-frankenpandas-76mw (fd90.40). Mirrors
    /// `SQLAlchemy.MetaData.reflect_table` shape — gives callers a
    /// single bundle instead of 5 separate fetches. Returns `Ok(None)`
    /// when the table doesn't exist (matched via `table_schema`
    /// returning `None`); otherwise all derived calls run and any
    /// missing pieces (e.g. SQLite's always-None `table_comment`)
    /// are simply preserved as their natural empty values.
    ///
    /// Per br-frankenpandas-2kzv (fd90.43): primary-key columns are
    /// derived directly from the `SqlTableSchema` we already fetched
    /// rather than dispatching `primary_key_columns()` again — that
    /// trait method's default impl calls `table_schema()` internally,
    /// which would double the round-trip count for backends where
    /// each call is a real network hop.
    pub fn reflect_table(
        &self,
        table_name: &str,
        schema: Option<&str>,
    ) -> Result<Option<SqlReflectedTable>, IoError> {
        let Some(meta) = self.conn.table_schema(table_name, schema)? else {
            return Ok(None);
        };
        let primary_key_columns = primary_keys_from_schema(&meta);
        let indexes = self.conn.list_indexes(table_name, schema)?;
        let foreign_keys = self.conn.list_foreign_keys(table_name, schema)?;
        let unique_constraints = self.conn.list_unique_constraints(table_name, schema)?;
        let comment = self.conn.table_comment(table_name, schema)?;
        Ok(Some(SqlReflectedTable {
            table_name: meta.table_name,
            columns: meta.columns,
            primary_key_columns,
            indexes,
            foreign_keys,
            unique_constraints,
            comment,
        }))
    }

    /// Reflect every user-visible table in `schema` into a vector of
    /// bundles, one per table.
    ///
    /// Per br-frankenpandas-jmmo (fd90.53). Iterates `tables(schema)`
    /// then calls `reflect_table` on each. Skips any table that
    /// `reflect_table` returns `Ok(None)` for — covers the race
    /// condition where a table existed at list time but not at
    /// reflect time (e.g. concurrent DROP). Useful for whole-database
    /// introspection in one call.
    pub fn reflect_all_tables(
        &self,
        schema: Option<&str>,
    ) -> Result<Vec<SqlReflectedTable>, IoError> {
        let table_names = self.conn.list_tables(schema)?;
        let mut bundles = Vec::with_capacity(table_names.len());
        for name in table_names {
            if let Some(bundle) = self.reflect_table(&name, schema)? {
                bundles.push(bundle);
            }
        }
        Ok(bundles)
    }

    /// Reflect every user-visible view in `schema` into a vector of
    /// bundles, one per view.
    ///
    /// Per br-frankenpandas-zuqt (fd90.54). View-side parity with
    /// `reflect_all_tables`: iterates `views(schema)` then calls
    /// `reflect_table` on each (PRAGMA table_info works on views too,
    /// returning the view's column shape). PK/FK/UC/index lists in
    /// the bundle will typically be empty for views since views don't
    /// carry constraints — only the column metadata + comment are
    /// meaningful. Same disappearing-entity skip semantics as
    /// `reflect_all_tables`.
    pub fn reflect_all_views(
        &self,
        schema: Option<&str>,
    ) -> Result<Vec<SqlReflectedTable>, IoError> {
        let view_names = self.conn.list_views(schema)?;
        let mut bundles = Vec::with_capacity(view_names.len());
        for name in view_names {
            if let Some(bundle) = self.reflect_table(&name, schema)? {
                bundles.push(bundle);
            }
        }
        Ok(bundles)
    }
}

/// Derive the primary-key column names from an already-fetched
/// `SqlTableSchema`, sorted ascending by `primary_key_ordinal`.
///
/// Per br-frankenpandas-2kzv (fd90.43) / fd90.47: this is the
/// canonical filter+sort impl shared by both
/// `SqlConnection::primary_key_columns` (the trait default) and
/// `SqlInspector::reflect_table` (which uses already-fetched
/// metadata to avoid a redundant `table_schema()` round-trip).
fn primary_keys_from_schema(meta: &SqlTableSchema) -> Vec<String> {
    let mut pk: Vec<(usize, String)> = meta
        .columns
        .iter()
        .filter_map(|c| c.primary_key_ordinal.map(|ord| (ord, c.name.clone())))
        .collect();
    pk.sort_by_key(|(ord, _)| *ord);
    pk.into_iter().map(|(_, name)| name).collect()
}

/// Convenience constructor for `SqlInspector`.
///
/// `let inspector = inspect(&conn);` reads more naturally than
/// `SqlInspector::new(&conn)` for one-shot uses. Per br-frankenpandas-szs9 (fd90.38).
#[must_use]
pub fn inspect<C: SqlConnection>(conn: &C) -> SqlInspector<'_, C> {
    SqlInspector::new(conn)
}

/// Read an entire SQL table into a DataFrame with read-time options.
///
/// Matches the supported subset of
/// `pd.read_sql_table(table_name, con, parse_dates=..., coerce_float=...)`.
pub fn read_sql_table_with_options<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    options: &SqlReadOptions,
) -> Result<DataFrame, IoError> {
    let query =
        sql_table_read_query_for_options(conn, table_name, options, options.index_col.as_deref())?;
    // Per br-frankenpandas-t1777: the query reader rejects options.columns
    // (the SELECT is already projected here). Clear before delegating so
    // the table reader stays the canonical honor-columns entrypoint
    // regardless of which slot the caller used.
    let cleared = SqlReadOptions {
        columns: None,
        ..options.clone()
    };
    read_sql_with_options(conn, &query, &cleared)
}

fn sql_table_read_query_for_options<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    options: &SqlReadOptions,
    required_projection_col: Option<&str>,
) -> Result<String, IoError> {
    // Per br-frankenpandas-d3e9 (fd90.34): when options.columns is
    // Some(list), project only those columns instead of SELECT *.
    // Per br-frankenpandas-fd90.76: if an index_col will be promoted
    // after materialization, include it in the generated projection even
    // when the user did not list it in columns. pandas SQLTable.read does
    // this before set_index so columns=[...] and index_col=... compose.
    match options.columns.as_deref() {
        Some(cols) => {
            let mut refs: Vec<&str> = Vec::with_capacity(cols.len() + 1);
            if let Some(index_col) = required_projection_col
                && !cols.iter().any(|name| name == index_col)
            {
                refs.push(index_col);
            }
            refs.extend(cols.iter().map(String::as_str));
            sql_select_columns_query_in_schema(conn, table_name, options.schema.as_deref(), &refs)
        }
        None => sql_select_all_query_in_schema(conn, table_name, options.schema.as_deref()),
    }
}

/// Read an entire SQL table with read-time options and optional index promotion.
///
/// Matches the supported subset of
/// `pd.read_sql_table(table_name, con, parse_dates=..., coerce_float=..., index_col=...)`.
pub fn read_sql_table_with_options_and_index_col<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    options: &SqlReadOptions,
    index_col: Option<&str>,
) -> Result<DataFrame, IoError> {
    // Per br-frankenpandas-c1h9 (fd90.36): explicit `index_col` arg
    // always wins over `options.index_col`. Avoid double-promotion by
    // clearing the option-struct copy when the explicit arg is set.
    if let Some(col_name) = index_col {
        // Build the SELECT projection from the ORIGINAL options (so
        // options.columns is honored when present). Per br-frankenpandas-t1777,
        // also strip options.columns before passing to the query reader
        // (which now rejects the field; the SELECT already projects the
        // columns we wanted).
        let query = sql_table_read_query_for_options(conn, table_name, options, Some(col_name))?;
        let cleared = SqlReadOptions {
            index_col: None,
            columns: None,
            ..options.clone()
        };
        let frame = read_sql_with_options(conn, &query, &cleared)?;
        return apply_sql_index_col(frame, Some(col_name));
    }
    read_sql_table_with_options(conn, table_name, options)
}

/// Read an entire SQL table as an iterator of DataFrame chunks.
///
/// Matches the supported subset of `pd.read_sql_table(table_name, con, chunksize=...)`.
pub fn read_sql_table_chunks<'conn, C: SqlConnection + 'conn>(
    conn: &'conn C,
    table_name: &str,
    chunk_size: usize,
) -> Result<SqlChunkIterator<'conn>, IoError> {
    read_sql_chunks(conn, &sql_select_all_query(conn, table_name)?, chunk_size)
}

/// Read an entire SQL table as DataFrame chunks with read-time options.
///
/// Matches the supported subset of
/// `pd.read_sql_table(table_name, con, parse_dates=..., coerce_float=..., chunksize=...)`.
pub fn read_sql_table_chunks_with_options<'conn, C: SqlConnection + 'conn>(
    conn: &'conn C,
    table_name: &str,
    options: &SqlReadOptions,
    chunk_size: usize,
) -> Result<SqlChunkIterator<'conn>, IoError> {
    // Per br-frankenpandas-i8kja: this entrypoint returns the
    // un-indexed SqlChunkIterator. Honoring options.index_col would
    // silently diverge from the full-frame read_sql_table_with_options
    // sibling (which does promote). Reject to surface the mismatch —
    // callers should use read_sql_table_chunks_with_options_and_index_col
    // when index_col is set.
    if options.index_col.is_some() {
        return Err(IoError::Sql(
            "options.index_col is set but this entrypoint returns SqlChunkIterator without \
             index promotion; use read_sql_table_chunks_with_options_and_index_col to honor \
             index_col"
                .to_owned(),
        ));
    }
    let query = match options.columns.as_deref() {
        Some(cols) => {
            let refs: Vec<&str> = cols.iter().map(String::as_str).collect();
            sql_select_columns_query_in_schema(conn, table_name, options.schema.as_deref(), &refs)?
        }
        None => sql_select_all_query_in_schema(conn, table_name, options.schema.as_deref())?,
    };
    // Per br-frankenpandas-t1777: query reader rejects options.columns
    // (the SELECT is already projected here). Clear before delegating.
    let cleared = SqlReadOptions {
        columns: None,
        ..options.clone()
    };
    read_sql_chunks_with_options(conn, &query, &cleared, chunk_size)
}

/// Read an entire SQL table as chunks with read-time options and optional index promotion.
///
/// Matches the supported subset of
/// `pd.read_sql_table(table_name, con, parse_dates=..., coerce_float=..., index_col=..., chunksize=...)`.
pub fn read_sql_table_chunks_with_options_and_index_col<'conn, C: SqlConnection + 'conn>(
    conn: &'conn C,
    table_name: &str,
    options: &SqlReadOptions,
    index_col: Option<&str>,
    chunk_size: usize,
) -> Result<SqlIndexedChunkIterator<'conn>, IoError> {
    let effective_index_col = index_col.or(options.index_col.as_deref());
    let query = sql_table_read_query_for_options(conn, table_name, options, effective_index_col)?;
    // The plain chunk reader rejects options.index_col (see i8kja) and
    // options.columns (see t1777); clear both before delegating so
    // chunked-with-options remains a sibling of the full-frame path
    // regardless of which slots the caller populated.
    let cleared = SqlReadOptions {
        index_col: None,
        columns: None,
        ..options.clone()
    };
    let inner = read_sql_chunks_with_options(conn, &query, &cleared, chunk_size)?;
    sql_indexed_chunks(inner, effective_index_col)
}

/// Read an entire SQL table as chunks with one column promoted to each chunk's index.
///
/// Matches the supported subset of
/// `pd.read_sql_table(table_name, con, index_col=..., chunksize=...)`.
pub fn read_sql_table_chunks_with_index_col<'conn, C: SqlConnection + 'conn>(
    conn: &'conn C,
    table_name: &str,
    index_col: Option<&str>,
    chunk_size: usize,
) -> Result<SqlIndexedChunkIterator<'conn>, IoError> {
    let inner = read_sql_table_chunks(conn, table_name, chunk_size)?;
    sql_indexed_chunks(inner, index_col)
}

/// Read a subset of columns from a SQL table.
///
/// Matches `pd.read_sql_table(table, con, columns=[...])`. The named
/// columns are emitted in the requested order. Each column name must
/// satisfy the same alphanumeric+underscore rule as `table_name` to
/// keep the projection injection-safe; mismatched names return
/// `IoError::Sql`. Empty `columns` is rejected (pandas raises in
/// the same case rather than producing an empty SELECT).
pub fn read_sql_table_columns<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    columns: &[&str],
) -> Result<DataFrame, IoError> {
    read_sql(conn, &sql_select_columns_query(conn, table_name, columns)?)
}

/// Read a subset of columns from a SQL table with optional index promotion.
///
/// Matches the supported subset of
/// `pd.read_sql_table(table, con, columns=[...], index_col=...)`. When
/// `index_col` is set and is not already in `columns`, it is auto-projected
/// into the underlying SELECT (matching pandas SQLTable.read which does the
/// same before set_index). The promoted column is removed from the data
/// columns after projection. Per br-frankenpandas-6n0uz.
pub fn read_sql_table_columns_with_index_col<C: SqlConnection>(
    conn: &C,
    table_name: &str,
    columns: &[&str],
    index_col: Option<&str>,
) -> Result<DataFrame, IoError> {
    let projection = projection_with_index_col(columns, index_col)?;
    let frame = read_sql_table_columns(conn, table_name, &projection)?;
    apply_sql_index_col(frame, index_col)
}

/// Read a subset of columns from a SQL table as DataFrame chunks.
///
/// Matches the supported subset of
/// `pd.read_sql_table(table, con, columns=[...], chunksize=...)`. The named
/// columns are emitted in the requested order and each chunk receives a fresh
/// zero-based RangeIndex.
pub fn read_sql_table_columns_chunks<'conn, C: SqlConnection + 'conn>(
    conn: &'conn C,
    table_name: &str,
    columns: &[&str],
    chunk_size: usize,
) -> Result<SqlChunkIterator<'conn>, IoError> {
    read_sql_chunks(
        conn,
        &sql_select_columns_query(conn, table_name, columns)?,
        chunk_size,
    )
}

/// Read a subset of columns from a SQL table as chunks with optional index promotion.
///
/// Matches the supported subset of
/// `pd.read_sql_table(table, con, columns=[...], index_col=..., chunksize=...)`.
/// When `index_col` is set and is not already in `columns`, it is auto-projected
/// into the underlying SELECT (matching pandas SQLTable.read). The promoted
/// column is removed from each chunk after projection. Per br-frankenpandas-6n0uz.
pub fn read_sql_table_columns_chunks_with_index_col<'conn, C: SqlConnection + 'conn>(
    conn: &'conn C,
    table_name: &str,
    columns: &[&str],
    index_col: Option<&str>,
    chunk_size: usize,
) -> Result<SqlIndexedChunkIterator<'conn>, IoError> {
    let projection = projection_with_index_col(columns, index_col)?;
    let inner = read_sql_table_columns_chunks(conn, table_name, &projection, chunk_size)?;
    sql_indexed_chunks(inner, index_col)
}

/// Per br-frankenpandas-6n0uz: helper that prepends `index_col` to a
/// `columns` projection list if it isn't already present. Mirrors the
/// inline logic in `sql_table_read_query_for_options` (fd90.76) so the
/// columns-list and options-based read paths agree on the auto-include
/// rule while preserving the public `index_col=""` and empty-projection
/// error contracts.
fn projection_with_index_col<'a>(
    columns: &'a [&'a str],
    index_col: Option<&'a str>,
) -> Result<Vec<&'a str>, IoError> {
    match index_col {
        Some("") => Err(IoError::Sql(
            "index_col: empty string is not a valid column name".to_owned(),
        )),
        Some(name) if !columns.is_empty() && !columns.contains(&name) => {
            let mut out = Vec::with_capacity(columns.len() + 1);
            out.push(name);
            out.extend_from_slice(columns);
            Ok(out)
        }
        _ => Ok(columns.to_vec()),
    }
}

/// Write a DataFrame to a SQL table.
///
/// Matches `pd.DataFrame.to_sql(name, con)`.
pub fn write_sql<C: SqlConnection>(
    frame: &DataFrame,
    conn: &C,
    table_name: &str,
    if_exists: SqlIfExists,
) -> Result<(), IoError> {
    write_sql_with_options(
        frame,
        conn,
        table_name,
        &SqlWriteOptions {
            if_exists,
            index: false,
            index_label: None,
            schema: None,
            dtype: None,
            method: SqlInsertMethod::Single,
            chunksize: None,
        },
    )
}

/// Write a DataFrame to a SQLite table with pandas-style index options.
///
/// Matches the supported subset of
/// `pd.DataFrame.to_sql(name, con, index=..., index_label=...)`.
pub fn write_sql_with_options<C: SqlConnection>(
    frame: &DataFrame,
    conn: &C,
    table_name: &str,
    options: &SqlWriteOptions,
) -> Result<(), IoError> {
    // Validate table name to prevent SQL injection (only allow alphanumeric + underscore, non-empty).
    if table_name.is_empty() || !table_name.chars().all(|c| c.is_alphanumeric() || c == '_') {
        return Err(IoError::Sql(format!(
            "invalid table name: '{table_name}' (must be non-empty, only alphanumeric and underscore allowed)"
        )));
    }

    let col_names: Vec<String> = frame.column_names().into_iter().cloned().collect();
    let index_label = resolve_sql_index_label(frame, options)?;
    let mut sql_col_names =
        Vec::with_capacity(col_names.len() + usize::from(index_label.is_some()));
    if let Some(ref label) = index_label {
        sql_col_names.push(label.clone());
    }
    sql_col_names.extend(col_names.iter().cloned());

    // Per fd90.27: when the backend reports an identifier-length cap
    // (PG=63, MySQL=64, MSSQL=128), reject any identifier that exceeds
    // it before emitting DDL. SQLite (None) is unaffected.
    let max_ident = conn.max_identifier_length();
    validate_sql_identifier_length(table_name, max_ident, "table")?;
    if let Some(ref label) = index_label {
        validate_sql_identifier_length(label, max_ident, "index label")?;
    }
    for name in &col_names {
        validate_sql_identifier_length(name, max_ident, "column")?;
    }
    if let Some(s) = options.schema.as_deref() {
        validate_sql_identifier_length(s, max_ident, "schema")?;
    }

    // Handle if_exists policy.
    let schema = options.schema.as_deref();
    match options.if_exists {
        SqlIfExists::Fail => {
            let exists = conn.table_exists_in_schema(table_name, schema)?;
            if exists {
                return Err(IoError::Sql(format!("table '{table_name}' already exists")));
            }
        }
        SqlIfExists::Replace => {
            let drop_sql = sql_drop_table_query_in_schema(conn, table_name, schema)?;
            conn.execute_batch(&drop_sql)?;
        }
        SqlIfExists::Append => {
            // Table may or may not exist; CREATE TABLE IF NOT EXISTS handles both.
        }
    }

    // Build CREATE TABLE statement.
    let mut col_defs = Vec::with_capacity(sql_col_names.len());
    if let Some(ref label) = index_label {
        col_defs.push(sql_column_definition(
            conn,
            label,
            conn.index_dtype_sql(frame.index()),
        )?);
    }
    let dtype_overrides = options.dtype.as_ref();
    col_defs.extend(
        col_names
            .iter()
            .map(|name| {
                // Per br-frankenpandas-ev2s (fd90.18): explicit per-column
                // SQL-type override wins over the inferred conn.dtype_sql.
                let override_sql = dtype_overrides
                    .and_then(|m| m.get(name))
                    .map(|s| s.as_str());
                let sql_type = match override_sql {
                    Some(s) => s,
                    None => {
                        let dt = frame.column(name).map_or(DType::Utf8, |c| c.dtype());
                        conn.dtype_sql(dt)
                    }
                };
                sql_column_definition(conn, name, sql_type)
            })
            .collect::<Result<Vec<_>, IoError>>()?,
    );

    let create_sql = sql_create_table_query_in_schema(conn, table_name, schema, &col_defs)?;
    conn.execute_batch(&create_sql)?;

    let nrows = frame.index().len();
    let ncols = sql_col_names.len();
    let mut rows = Vec::with_capacity(nrows);
    for row_idx in 0..nrows {
        let mut row = Vec::with_capacity(ncols);
        if options.index {
            row.push(scalar_from_index_label(&frame.index().labels()[row_idx]));
        }
        row.extend(col_names.iter().map(|name| {
            frame
                .column(name)
                .and_then(|col| col.value(row_idx))
                .cloned()
                .unwrap_or(Scalar::Null(NullKind::Null))
        }));
        rows.push(row);
    }

    if rows.is_empty() {
        // Empty frame: still emit CREATE TABLE (already done) but skip INSERT.
        return Ok(());
    }

    // Per fd90.33: pandas-style chunksize. None preserves prior
    // single-transaction semantics; Some(0) is rejected (matches pandas).
    if let Some(0) = options.chunksize {
        return Err(IoError::Sql(
            "invalid chunksize: 0 (must be > 0 if Some)".to_owned(),
        ));
    }

    match options.method {
        SqlInsertMethod::Single => {
            let insert_sql =
                sql_insert_rows_query_in_schema(conn, table_name, schema, &sql_col_names)?;
            match options.chunksize {
                None => {
                    conn.insert_rows(&insert_sql, &rows)?;
                }
                Some(n) => {
                    for chunk in rows.chunks(n) {
                        conn.insert_rows(&insert_sql, chunk)?;
                    }
                }
            }
        }
        SqlInsertMethod::Multi => {
            // Per fd90.19: chunk rows to fit `max_param_count`. When the
            // backend reports None, send the whole frame in one statement.
            // Per fd90.33: when chunksize is also Some(n), the effective
            // chunk row count is min(n, max_param_count / num_cols).
            let param_chunk = match conn.max_param_count() {
                Some(max) if ncols > 0 => {
                    let per_chunk = max / ncols;
                    if per_chunk == 0 {
                        return Err(IoError::Sql(format!(
                            "multi-row insert: ncols={ncols} exceeds backend max_param_count={max}"
                        )));
                    }
                    per_chunk
                }
                _ => rows.len(),
            };
            let chunk_rows = options
                .chunksize
                .map(|cs| cs.min(param_chunk))
                .unwrap_or(param_chunk);
            for chunk in rows.chunks(chunk_rows) {
                let chunk_sql = sql_multi_row_insert_query_in_schema(
                    conn,
                    table_name,
                    schema,
                    &sql_col_names,
                    chunk.len(),
                )?;
                let mut flat = Vec::with_capacity(chunk.len() * ncols);
                for row in chunk {
                    flat.extend(row.iter().cloned());
                }
                conn.insert_rows(&chunk_sql, &[flat])?;
            }
        }
    }

    Ok(())
}

// ── Extension trait for DataFrame IO convenience methods ─────────────

/// Extension trait that adds IO convenience methods to `DataFrame`.
///
/// Import this trait to call `df.to_parquet(path)`, `df.to_orc(path)`,
/// `df.to_hdf(path)`, `df.to_parquet_bytes()`, etc. directly on DataFrame
/// values.
pub trait DataFrameIoExt {
    /// Write this DataFrame to a Parquet file.
    ///
    /// Matches `pd.DataFrame.to_parquet(path)`.
    fn to_parquet(&self, path: &Path) -> Result<(), IoError>;

    /// Serialize this DataFrame to Parquet bytes in memory.
    ///
    /// Matches `pd.DataFrame.to_parquet()` with no path (returns bytes).
    fn to_parquet_bytes(&self) -> Result<Vec<u8>, IoError>;

    /// Write this DataFrame to an ORC file.
    ///
    /// Matches the scoped `DataFrame.to_orc(path)` compatibility surface.
    fn to_orc(&self, path: &Path) -> Result<(), IoError>;

    /// Write this DataFrame to an ORC file.
    ///
    /// Explicit file-suffixed form of [`DataFrameIoExt::to_orc`].
    fn to_orc_file(&self, path: &Path) -> Result<(), IoError>;

    /// Serialize this DataFrame to ORC bytes in memory.
    fn to_orc_bytes(&self) -> Result<Vec<u8>, IoError>;

    /// Write this DataFrame to an HDF5 file at the default key.
    ///
    /// Matches the scoped `DataFrame.to_hdf(path)` compatibility surface.
    fn to_hdf(&self, path: &Path) -> Result<(), IoError>;

    /// Write this DataFrame to an HDF5 file at the default key.
    ///
    /// Explicit file-suffixed form of [`DataFrameIoExt::to_hdf`].
    fn to_hdf_file(&self, path: &Path) -> Result<(), IoError>;

    /// Write this DataFrame to an HDF5 file at an explicit key.
    fn to_hdf_key(&self, path: &Path, key: &str) -> Result<(), IoError>;

    /// Write this DataFrame to an HDF5 file with explicit options.
    fn to_hdf_with_options(&self, path: &Path, options: &HdfWriteOptions) -> Result<(), IoError>;

    /// Write this DataFrame to a CSV file.
    ///
    /// Matches `pd.DataFrame.to_csv(path)`.
    fn to_csv_file(&self, path: &Path) -> Result<(), IoError>;

    /// Serialize this DataFrame to a CSV string.
    ///
    /// Matches `pd.DataFrame.to_csv()` with no path.
    fn to_csv_string(&self) -> Result<String, IoError>;

    /// Serialize this DataFrame to a CSV string with explicit write options.
    ///
    /// Matches `pd.DataFrame.to_csv(sep, na_rep, header, index, index_label)`.
    fn to_csv_string_with_options(&self, options: &CsvWriteOptions) -> Result<String, IoError>;

    /// Serialize this DataFrame to a Markdown table string.
    ///
    /// Matches `pd.DataFrame.to_markdown()` with no buffer.
    fn to_markdown_string(&self) -> Result<String, IoError>;

    /// Serialize this DataFrame to a Markdown table string with explicit options.
    fn to_markdown_string_with_options(
        &self,
        options: &MarkdownWriteOptions,
    ) -> Result<String, IoError>;

    /// Write this DataFrame to a Markdown table file.
    ///
    /// Uses a file-suffixed name to avoid colliding with
    /// `DataFrame::to_markdown(include_index, tablefmt)`.
    fn to_markdown_file(&self, path: &Path) -> Result<(), IoError>;

    /// Write this DataFrame to a Markdown table file with explicit options.
    fn to_markdown_file_with_options(
        &self,
        path: &Path,
        options: &MarkdownWriteOptions,
    ) -> Result<(), IoError>;

    /// Serialize this DataFrame to a LaTeX tabular string.
    ///
    /// Matches `pd.DataFrame.to_latex()` with no buffer.
    fn to_latex_string(&self) -> Result<String, IoError>;

    /// Serialize this DataFrame to a LaTeX tabular string with explicit options.
    fn to_latex_string_with_options(&self, options: &LatexWriteOptions) -> Result<String, IoError>;

    /// Write this DataFrame to a LaTeX tabular file.
    ///
    /// Uses a file-suffixed name to avoid colliding with
    /// `DataFrame::to_latex(include_index)`.
    fn to_latex_file(&self, path: &Path) -> Result<(), IoError>;

    /// Write this DataFrame to a LaTeX tabular file with explicit options.
    fn to_latex_file_with_options(
        &self,
        path: &Path,
        options: &LatexWriteOptions,
    ) -> Result<(), IoError>;

    /// Serialize this DataFrame to an HTML table string.
    ///
    /// Matches `pd.DataFrame.to_html()` with no buffer.
    fn to_html_string(&self) -> Result<String, IoError>;

    /// Serialize this DataFrame to an HTML table string with explicit options.
    fn to_html_string_with_options(&self, options: &HtmlWriteOptions) -> Result<String, IoError>;

    /// Write this DataFrame to an HTML file.
    ///
    /// Matches `pd.DataFrame.to_html(path)`.
    fn to_html_file(&self, path: &Path) -> Result<(), IoError>;

    /// Write this DataFrame to an HTML file with explicit options.
    fn to_html_file_with_options(
        &self,
        path: &Path,
        options: &HtmlWriteOptions,
    ) -> Result<(), IoError>;

    /// Serialize this DataFrame to an XML document string.
    ///
    /// Matches `pd.DataFrame.to_xml()` with no buffer for the writer-only subset.
    fn to_xml_string(&self) -> Result<String, IoError>;

    /// Serialize this DataFrame to an XML document string with explicit options.
    fn to_xml_string_with_options(&self, options: &XmlWriteOptions) -> Result<String, IoError>;

    /// Write this DataFrame to an XML file.
    ///
    /// Matches `pd.DataFrame.to_xml(path)`.
    fn to_xml(&self, path: &Path) -> Result<(), IoError>;

    /// Write this DataFrame to an XML file.
    ///
    /// Matches `pd.DataFrame.to_xml(path)`.
    fn to_xml_file(&self, path: &Path) -> Result<(), IoError>;

    /// Write this DataFrame to an XML file with explicit options.
    fn to_xml_file_with_options(
        &self,
        path: &Path,
        options: &XmlWriteOptions,
    ) -> Result<(), IoError>;

    /// Write this DataFrame to a JSON file.
    ///
    /// Matches `pd.DataFrame.to_json(path)`.
    fn to_json_file(&self, path: &Path, orient: JsonOrient) -> Result<(), IoError>;

    /// Serialize this DataFrame to a JSON string.
    ///
    /// Matches `pd.DataFrame.to_json()` with no path.
    fn to_json_string(&self, orient: JsonOrient) -> Result<String, IoError>;

    /// Write this DataFrame to a Pickle file.
    ///
    /// Matches `pd.DataFrame.to_pickle(path)` for the supported envelope.
    fn to_pickle(&self, path: &Path) -> Result<(), IoError>;

    /// Write this DataFrame to a Pickle file.
    ///
    /// Explicit file-suffixed form of [`DataFrameIoExt::to_pickle`].
    fn to_pickle_file(&self, path: &Path) -> Result<(), IoError>;

    /// Write this DataFrame to a Pickle file with explicit options.
    fn to_pickle_with_options(
        &self,
        path: &Path,
        options: &PickleWriteOptions,
    ) -> Result<(), IoError>;

    /// Serialize this DataFrame to Pickle bytes.
    fn to_pickle_bytes(&self) -> Result<Vec<u8>, IoError>;

    /// Serialize this DataFrame to Pickle bytes with explicit options.
    fn to_pickle_bytes_with_options(
        &self,
        options: &PickleWriteOptions,
    ) -> Result<Vec<u8>, IoError>;

    /// Write this DataFrame to a Stata DTA file.
    ///
    /// Matches `pd.DataFrame.to_stata(path)` for the supported subset.
    fn to_stata(&self, path: &Path) -> Result<(), IoError>;

    /// Write this DataFrame to a Stata DTA file.
    ///
    /// Explicit file-suffixed form of [`DataFrameIoExt::to_stata`].
    fn to_stata_file(&self, path: &Path) -> Result<(), IoError>;

    /// Write this DataFrame to a Stata DTA file with explicit options.
    fn to_stata_with_options(
        &self,
        path: &Path,
        options: &StataWriteOptions,
    ) -> Result<(), IoError>;

    /// Serialize this DataFrame to Stata DTA bytes.
    fn to_stata_bytes(&self) -> Result<Vec<u8>, IoError>;

    /// Serialize this DataFrame to Stata DTA bytes with explicit options.
    fn to_stata_bytes_with_options(&self, options: &StataWriteOptions) -> Result<Vec<u8>, IoError>;

    /// Write this DataFrame to an Excel (.xlsx) file.
    ///
    /// Matches `pd.DataFrame.to_excel(path)`.
    fn to_excel(&self, path: &Path) -> Result<(), IoError>;

    /// Write this DataFrame to an Excel (.xlsx) file.
    ///
    /// Explicit file-suffixed form of [`DataFrameIoExt::to_excel`].
    fn to_excel_file(&self, path: &Path) -> Result<(), IoError>;

    /// Write this DataFrame to an Excel (.xlsx) file with explicit write options.
    fn to_excel_with_options(
        &self,
        path: &Path,
        options: &ExcelWriteOptions,
    ) -> Result<(), IoError>;

    /// Serialize this DataFrame to Excel (.xlsx) bytes in memory.
    fn to_excel_bytes(&self) -> Result<Vec<u8>, IoError>;

    /// Serialize this DataFrame to Excel (.xlsx) bytes with explicit write options.
    fn to_excel_bytes_with_options(&self, options: &ExcelWriteOptions) -> Result<Vec<u8>, IoError>;

    /// Write this DataFrame to a JSONL file (one JSON object per line).
    ///
    /// Matches `pd.DataFrame.to_json(path, orient='records', lines=True)`.
    fn to_jsonl_file(&self, path: &Path) -> Result<(), IoError>;

    /// Serialize this DataFrame to newline-delimited JSON.
    ///
    /// Matches `pd.DataFrame.to_json(orient='records', lines=True)`.
    fn to_jsonl_string(&self) -> Result<String, IoError>;

    /// Write this DataFrame to an Arrow IPC (Feather v2) file.
    ///
    /// Matches `pd.DataFrame.to_feather(path)`.
    fn to_feather(&self, path: &Path) -> Result<(), IoError>;

    /// Write this DataFrame to an Arrow IPC (Feather v2) file.
    ///
    /// Explicit file-suffixed form of [`DataFrameIoExt::to_feather`].
    fn to_feather_file(&self, path: &Path) -> Result<(), IoError>;

    /// Serialize this DataFrame to Arrow IPC (Feather v2) bytes.
    fn to_feather_bytes(&self) -> Result<Vec<u8>, IoError>;

    /// Write this DataFrame to a SQL table.
    ///
    /// Matches `pd.DataFrame.to_sql(name, con)`.
    fn to_sql<C: SqlConnection>(
        &self,
        conn: &C,
        table_name: &str,
        if_exists: SqlIfExists,
    ) -> Result<(), IoError>;

    /// Write this DataFrame to a SQL table with pandas-style SQL write options.
    fn to_sql_with_options<C: SqlConnection>(
        &self,
        conn: &C,
        table_name: &str,
        options: &SqlWriteOptions,
    ) -> Result<(), IoError>;

    /// Reject-closed clipboard writer, matching `pd.DataFrame.to_clipboard()` shape.
    fn to_clipboard(&self) -> Result<(), IoError>;

    /// Reject-closed BigQuery writer, matching `pd.DataFrame.to_gbq(destination_table, project_id)`.
    fn to_gbq(&self, destination_table: &str, project_id: Option<&str>) -> Result<(), IoError>;
}

impl DataFrameIoExt for DataFrame {
    fn to_parquet(&self, path: &Path) -> Result<(), IoError> {
        write_parquet(self, path)
    }

    fn to_parquet_bytes(&self) -> Result<Vec<u8>, IoError> {
        write_parquet_bytes(self)
    }

    fn to_orc(&self, path: &Path) -> Result<(), IoError> {
        write_orc(self, path)
    }

    fn to_orc_file(&self, path: &Path) -> Result<(), IoError> {
        self.to_orc(path)
    }

    fn to_orc_bytes(&self) -> Result<Vec<u8>, IoError> {
        write_orc_bytes(self)
    }

    fn to_hdf(&self, path: &Path) -> Result<(), IoError> {
        write_hdf(self, path)
    }

    fn to_hdf_file(&self, path: &Path) -> Result<(), IoError> {
        self.to_hdf(path)
    }

    fn to_hdf_key(&self, path: &Path, key: &str) -> Result<(), IoError> {
        write_hdf_key(self, path, key)
    }

    fn to_hdf_with_options(&self, path: &Path, options: &HdfWriteOptions) -> Result<(), IoError> {
        write_hdf_with_options(self, path, options)
    }

    fn to_csv_file(&self, path: &Path) -> Result<(), IoError> {
        write_csv(self, path)
    }

    fn to_csv_string(&self) -> Result<String, IoError> {
        write_csv_string(self)
    }

    fn to_csv_string_with_options(&self, options: &CsvWriteOptions) -> Result<String, IoError> {
        write_csv_string_with_options(self, options)
    }

    fn to_markdown_string(&self) -> Result<String, IoError> {
        write_markdown_string(self)
    }

    fn to_markdown_string_with_options(
        &self,
        options: &MarkdownWriteOptions,
    ) -> Result<String, IoError> {
        write_markdown_string_with_options(self, options)
    }

    fn to_markdown_file(&self, path: &Path) -> Result<(), IoError> {
        write_markdown(self, path)
    }

    fn to_markdown_file_with_options(
        &self,
        path: &Path,
        options: &MarkdownWriteOptions,
    ) -> Result<(), IoError> {
        write_markdown_with_options(self, path, options)
    }

    fn to_latex_string(&self) -> Result<String, IoError> {
        write_latex_string(self)
    }

    fn to_latex_string_with_options(&self, options: &LatexWriteOptions) -> Result<String, IoError> {
        write_latex_string_with_options(self, options)
    }

    fn to_latex_file(&self, path: &Path) -> Result<(), IoError> {
        write_latex(self, path)
    }

    fn to_latex_file_with_options(
        &self,
        path: &Path,
        options: &LatexWriteOptions,
    ) -> Result<(), IoError> {
        write_latex_with_options(self, path, options)
    }

    fn to_html_string(&self) -> Result<String, IoError> {
        write_html_string(self)
    }

    fn to_html_string_with_options(&self, options: &HtmlWriteOptions) -> Result<String, IoError> {
        write_html_string_with_options(self, options)
    }

    fn to_html_file(&self, path: &Path) -> Result<(), IoError> {
        write_html(self, path)
    }

    fn to_html_file_with_options(
        &self,
        path: &Path,
        options: &HtmlWriteOptions,
    ) -> Result<(), IoError> {
        write_html_with_options(self, path, options)
    }

    fn to_xml_string(&self) -> Result<String, IoError> {
        write_xml_string(self)
    }

    fn to_xml_string_with_options(&self, options: &XmlWriteOptions) -> Result<String, IoError> {
        write_xml_string_with_options(self, options)
    }

    fn to_xml(&self, path: &Path) -> Result<(), IoError> {
        write_xml(self, path)
    }

    fn to_xml_file(&self, path: &Path) -> Result<(), IoError> {
        self.to_xml(path)
    }

    fn to_xml_file_with_options(
        &self,
        path: &Path,
        options: &XmlWriteOptions,
    ) -> Result<(), IoError> {
        write_xml_with_options(self, path, options)
    }

    fn to_json_file(&self, path: &Path, orient: JsonOrient) -> Result<(), IoError> {
        write_json(self, path, orient)
    }

    fn to_json_string(&self, orient: JsonOrient) -> Result<String, IoError> {
        write_json_string(self, orient)
    }

    fn to_pickle(&self, path: &Path) -> Result<(), IoError> {
        write_pickle(self, path)
    }

    fn to_pickle_file(&self, path: &Path) -> Result<(), IoError> {
        self.to_pickle(path)
    }

    fn to_pickle_with_options(
        &self,
        path: &Path,
        options: &PickleWriteOptions,
    ) -> Result<(), IoError> {
        write_pickle_with_options(self, path, options)
    }

    fn to_pickle_bytes(&self) -> Result<Vec<u8>, IoError> {
        write_pickle_bytes(self)
    }

    fn to_pickle_bytes_with_options(
        &self,
        options: &PickleWriteOptions,
    ) -> Result<Vec<u8>, IoError> {
        write_pickle_bytes_with_options(self, options)
    }

    fn to_stata(&self, path: &Path) -> Result<(), IoError> {
        write_stata(self, path)
    }

    fn to_stata_file(&self, path: &Path) -> Result<(), IoError> {
        self.to_stata(path)
    }

    fn to_stata_with_options(
        &self,
        path: &Path,
        options: &StataWriteOptions,
    ) -> Result<(), IoError> {
        write_stata_with_options(self, path, options)
    }

    fn to_stata_bytes(&self) -> Result<Vec<u8>, IoError> {
        write_stata_bytes(self)
    }

    fn to_stata_bytes_with_options(&self, options: &StataWriteOptions) -> Result<Vec<u8>, IoError> {
        write_stata_bytes_with_options(self, options)
    }

    fn to_excel(&self, path: &Path) -> Result<(), IoError> {
        write_excel(self, path)
    }

    fn to_excel_file(&self, path: &Path) -> Result<(), IoError> {
        self.to_excel(path)
    }

    fn to_excel_with_options(
        &self,
        path: &Path,
        options: &ExcelWriteOptions,
    ) -> Result<(), IoError> {
        write_excel_with_options(self, path, options)
    }

    fn to_excel_bytes(&self) -> Result<Vec<u8>, IoError> {
        write_excel_bytes(self)
    }

    fn to_excel_bytes_with_options(&self, options: &ExcelWriteOptions) -> Result<Vec<u8>, IoError> {
        write_excel_bytes_with_options(self, options)
    }

    fn to_jsonl_file(&self, path: &Path) -> Result<(), IoError> {
        write_jsonl(self, path)
    }

    fn to_jsonl_string(&self) -> Result<String, IoError> {
        write_jsonl_string(self)
    }

    fn to_feather(&self, path: &Path) -> Result<(), IoError> {
        write_feather(self, path)
    }

    fn to_feather_file(&self, path: &Path) -> Result<(), IoError> {
        self.to_feather(path)
    }

    fn to_feather_bytes(&self) -> Result<Vec<u8>, IoError> {
        write_feather_bytes(self)
    }

    fn to_sql<C: SqlConnection>(
        &self,
        conn: &C,
        table_name: &str,
        if_exists: SqlIfExists,
    ) -> Result<(), IoError> {
        write_sql(self, conn, table_name, if_exists)
    }

    fn to_sql_with_options<C: SqlConnection>(
        &self,
        conn: &C,
        table_name: &str,
        options: &SqlWriteOptions,
    ) -> Result<(), IoError> {
        write_sql_with_options(self, conn, table_name, options)
    }

    fn to_clipboard(&self) -> Result<(), IoError> {
        let _ = self;
        Err(deferred_writer_error(
            "to_clipboard",
            "OS clipboard access requires GUI bindings outside FrankenPandas's headless charter",
        ))
    }

    fn to_gbq(&self, _destination_table: &str, _project_id: Option<&str>) -> Result<(), IoError> {
        let _ = self;
        Err(deferred_writer_error(
            "to_gbq",
            "Google BigQuery integration is outside FrankenPandas's local file-format scope",
        ))
    }
}

// ── Extension trait for Series IO convenience methods ─────────────────

/// Extension trait that adds IO convenience methods to `Series`.
///
/// Import this trait to call `series.to_pickle(path)`,
/// `series.to_pickle_bytes()`, `series.to_hdf(path)`,
/// `series.to_csv_string()`, `series.to_markdown_string()`,
/// `series.to_latex_string()`, `series.to_json_string("records")`,
/// `series.to_hdf(path)`, `series.to_excel(path)`,
/// `series.to_sql(conn, table, if_exists)`, or `series.to_clipboard()`
/// directly on Series values.
pub trait SeriesIoExt {
    /// Write this Series to a Pickle file.
    ///
    /// Matches `pd.Series.to_pickle(path)` for the supported
    /// FrankenPandas pickle envelope.
    fn to_pickle(&self, path: &Path) -> Result<(), IoError>;

    /// Write this Series to a Pickle file.
    ///
    /// Explicit file-suffixed form of [`SeriesIoExt::to_pickle`].
    fn to_pickle_file(&self, path: &Path) -> Result<(), IoError>;

    /// Write this Series to a Pickle file with explicit options.
    fn to_pickle_with_options(
        &self,
        path: &Path,
        options: &PickleWriteOptions,
    ) -> Result<(), IoError>;

    /// Serialize this Series to Pickle bytes.
    fn to_pickle_bytes(&self) -> Result<Vec<u8>, IoError>;

    /// Serialize this Series to Pickle bytes with explicit options.
    fn to_pickle_bytes_with_options(
        &self,
        options: &PickleWriteOptions,
    ) -> Result<Vec<u8>, IoError>;

    /// Write this Series to a CSV file.
    ///
    /// Matches `pd.Series.to_csv(path)` for the supported CSV writer surface,
    /// including pandas' default index materialization.
    fn to_csv_file(&self, path: &Path) -> Result<(), IoError>;

    /// Write this Series to a CSV file with explicit write options.
    fn to_csv_file_with_options(
        &self,
        path: &Path,
        options: &CsvWriteOptions,
    ) -> Result<(), IoError>;

    /// Serialize this Series to a CSV string.
    ///
    /// Matches `pd.Series.to_csv()` with no path for the supported writer
    /// surface.
    fn to_csv_string(&self) -> Result<String, IoError>;

    /// Serialize this Series to a CSV string with explicit write options.
    fn to_csv_string_with_options(&self, options: &CsvWriteOptions) -> Result<String, IoError>;

    /// Serialize this Series to a Markdown table string.
    ///
    /// Matches `pd.Series.to_markdown()` with no buffer for the supported
    /// table formatter surface.
    fn to_markdown_string(&self) -> Result<String, IoError>;

    /// Serialize this Series to a Markdown table string with explicit options.
    fn to_markdown_string_with_options(
        &self,
        options: &MarkdownWriteOptions,
    ) -> Result<String, IoError>;

    /// Write this Series to a Markdown table file.
    ///
    /// Uses a file-suffixed name to avoid colliding with
    /// `Series::to_markdown(include_index, tablefmt)`.
    fn to_markdown_file(&self, path: &Path) -> Result<(), IoError>;

    /// Write this Series to a Markdown table file with explicit options.
    fn to_markdown_file_with_options(
        &self,
        path: &Path,
        options: &MarkdownWriteOptions,
    ) -> Result<(), IoError>;

    /// Serialize this Series to a LaTeX tabular string.
    ///
    /// Matches `pd.Series.to_latex()` with no buffer for the supported table
    /// formatter surface.
    fn to_latex_string(&self) -> Result<String, IoError>;

    /// Serialize this Series to a LaTeX tabular string with explicit options.
    fn to_latex_string_with_options(&self, options: &LatexWriteOptions) -> Result<String, IoError>;

    /// Write this Series to a LaTeX tabular file.
    ///
    /// Uses a file-suffixed name to avoid colliding with
    /// `Series::to_latex(include_index)`.
    fn to_latex_file(&self, path: &Path) -> Result<(), IoError>;

    /// Write this Series to a LaTeX tabular file with explicit options.
    fn to_latex_file_with_options(
        &self,
        path: &Path,
        options: &LatexWriteOptions,
    ) -> Result<(), IoError>;

    /// Write this Series to a JSON file.
    ///
    /// Matches `pd.Series.to_json(path, orient=...)` for the supported Series
    /// JSON orientations.
    fn to_json_file(&self, path: &Path, orient: &str) -> Result<(), IoError>;

    /// Serialize this Series to a JSON string.
    ///
    /// Matches `pd.Series.to_json(orient=...)` for the supported Series JSON
    /// orientations.
    fn to_json_string(&self, orient: &str) -> Result<String, IoError>;

    /// Write this Series to an HDF5 file at the default key.
    ///
    /// Matches `pd.Series.to_hdf(path)` for the supported HDF5 snapshot
    /// surface.
    fn to_hdf(&self, path: &Path) -> Result<(), IoError>;

    /// Write this Series to an HDF5 file at the default key.
    ///
    /// Explicit file-suffixed form of [`SeriesIoExt::to_hdf`].
    fn to_hdf_file(&self, path: &Path) -> Result<(), IoError>;

    /// Write this Series to an HDF5 file at an explicit key.
    fn to_hdf_key(&self, path: &Path, key: &str) -> Result<(), IoError>;

    /// Write this Series to an HDF5 file with explicit options.
    fn to_hdf_with_options(&self, path: &Path, options: &HdfWriteOptions) -> Result<(), IoError>;

    /// Write this Series to an Excel file.
    ///
    /// Matches `pd.Series.to_excel(path)` for the supported xlsx writer
    /// surface.
    fn to_excel(&self, path: &Path) -> Result<(), IoError>;

    /// Write this Series to an Excel file.
    ///
    /// Explicit file-suffixed form of [`SeriesIoExt::to_excel`].
    fn to_excel_file(&self, path: &Path) -> Result<(), IoError>;

    /// Write this Series to an Excel file with explicit options.
    fn to_excel_with_options(
        &self,
        path: &Path,
        options: &ExcelWriteOptions,
    ) -> Result<(), IoError>;

    /// Serialize this Series to xlsx bytes.
    fn to_excel_bytes(&self) -> Result<Vec<u8>, IoError>;

    /// Serialize this Series to xlsx bytes with explicit options.
    fn to_excel_bytes_with_options(&self, options: &ExcelWriteOptions) -> Result<Vec<u8>, IoError>;

    /// Write this Series to a SQL table.
    ///
    /// Matches `pd.Series.to_sql(name, con)` for the supported SQL writer
    /// surface, including pandas' default index materialization.
    fn to_sql<C: SqlConnection>(
        &self,
        conn: &C,
        table_name: &str,
        if_exists: SqlIfExists,
    ) -> Result<(), IoError>;

    /// Write this Series to a SQL table with pandas-style SQL write options.
    fn to_sql_with_options<C: SqlConnection>(
        &self,
        conn: &C,
        table_name: &str,
        options: &SqlWriteOptions,
    ) -> Result<(), IoError>;

    /// Reject-closed clipboard writer, matching `pd.Series.to_clipboard()` shape.
    fn to_clipboard(&self) -> Result<(), IoError>;
}

impl SeriesIoExt for Series {
    fn to_pickle(&self, path: &Path) -> Result<(), IoError> {
        write_pickle(&self.to_frame(None)?, path)
    }

    fn to_pickle_file(&self, path: &Path) -> Result<(), IoError> {
        self.to_pickle(path)
    }

    fn to_pickle_with_options(
        &self,
        path: &Path,
        options: &PickleWriteOptions,
    ) -> Result<(), IoError> {
        write_pickle_with_options(&self.to_frame(None)?, path, options)
    }

    fn to_pickle_bytes(&self) -> Result<Vec<u8>, IoError> {
        write_pickle_bytes(&self.to_frame(None)?)
    }

    fn to_pickle_bytes_with_options(
        &self,
        options: &PickleWriteOptions,
    ) -> Result<Vec<u8>, IoError> {
        write_pickle_bytes_with_options(&self.to_frame(None)?, options)
    }

    fn to_csv_file(&self, path: &Path) -> Result<(), IoError> {
        self.to_csv_file_with_options(
            path,
            &CsvWriteOptions {
                include_index: true,
                ..CsvWriteOptions::default()
            },
        )
    }

    fn to_csv_file_with_options(
        &self,
        path: &Path,
        options: &CsvWriteOptions,
    ) -> Result<(), IoError> {
        std::fs::write(path, self.to_csv_string_with_options(options)?)?;
        Ok(())
    }

    fn to_csv_string(&self) -> Result<String, IoError> {
        self.to_csv_string_with_options(&CsvWriteOptions {
            include_index: true,
            ..CsvWriteOptions::default()
        })
    }

    fn to_csv_string_with_options(&self, options: &CsvWriteOptions) -> Result<String, IoError> {
        write_csv_string_with_options(&self.to_frame(None)?, options)
    }

    fn to_markdown_string(&self) -> Result<String, IoError> {
        self.to_markdown_string_with_options(&MarkdownWriteOptions::default())
    }

    fn to_markdown_string_with_options(
        &self,
        options: &MarkdownWriteOptions,
    ) -> Result<String, IoError> {
        write_markdown_string_with_options(&self.to_frame(None)?, options)
    }

    fn to_markdown_file(&self, path: &Path) -> Result<(), IoError> {
        self.to_markdown_file_with_options(path, &MarkdownWriteOptions::default())
    }

    fn to_markdown_file_with_options(
        &self,
        path: &Path,
        options: &MarkdownWriteOptions,
    ) -> Result<(), IoError> {
        write_markdown_with_options(&self.to_frame(None)?, path, options)
    }

    fn to_latex_string(&self) -> Result<String, IoError> {
        self.to_latex_string_with_options(&LatexWriteOptions::default())
    }

    fn to_latex_string_with_options(&self, options: &LatexWriteOptions) -> Result<String, IoError> {
        write_latex_string_with_options(&self.to_frame(None)?, options)
    }

    fn to_latex_file(&self, path: &Path) -> Result<(), IoError> {
        self.to_latex_file_with_options(path, &LatexWriteOptions::default())
    }

    fn to_latex_file_with_options(
        &self,
        path: &Path,
        options: &LatexWriteOptions,
    ) -> Result<(), IoError> {
        write_latex_with_options(&self.to_frame(None)?, path, options)
    }

    fn to_json_file(&self, path: &Path, orient: &str) -> Result<(), IoError> {
        std::fs::write(path, self.to_json_string(orient)?)?;
        Ok(())
    }

    fn to_json_string(&self, orient: &str) -> Result<String, IoError> {
        Ok(Series::to_json(self, orient)?)
    }

    fn to_hdf(&self, path: &Path) -> Result<(), IoError> {
        write_hdf(&self.to_frame(None)?, path)
    }

    fn to_hdf_file(&self, path: &Path) -> Result<(), IoError> {
        self.to_hdf(path)
    }

    fn to_hdf_key(&self, path: &Path, key: &str) -> Result<(), IoError> {
        write_hdf_key(&self.to_frame(None)?, path, key)
    }

    fn to_hdf_with_options(&self, path: &Path, options: &HdfWriteOptions) -> Result<(), IoError> {
        write_hdf_with_options(&self.to_frame(None)?, path, options)
    }

    fn to_excel(&self, path: &Path) -> Result<(), IoError> {
        write_excel(&self.to_frame(None)?, path)
    }

    fn to_excel_file(&self, path: &Path) -> Result<(), IoError> {
        self.to_excel(path)
    }

    fn to_excel_with_options(
        &self,
        path: &Path,
        options: &ExcelWriteOptions,
    ) -> Result<(), IoError> {
        write_excel_with_options(&self.to_frame(None)?, path, options)
    }

    fn to_excel_bytes(&self) -> Result<Vec<u8>, IoError> {
        write_excel_bytes(&self.to_frame(None)?)
    }

    fn to_excel_bytes_with_options(&self, options: &ExcelWriteOptions) -> Result<Vec<u8>, IoError> {
        write_excel_bytes_with_options(&self.to_frame(None)?, options)
    }

    fn to_sql<C: SqlConnection>(
        &self,
        conn: &C,
        table_name: &str,
        if_exists: SqlIfExists,
    ) -> Result<(), IoError> {
        write_sql_with_options(
            &self.to_frame(None)?,
            conn,
            table_name,
            &SqlWriteOptions {
                if_exists,
                index: true,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
    }

    fn to_sql_with_options<C: SqlConnection>(
        &self,
        conn: &C,
        table_name: &str,
        options: &SqlWriteOptions,
    ) -> Result<(), IoError> {
        write_sql_with_options(&self.to_frame(None)?, conn, table_name, options)
    }

    fn to_clipboard(&self) -> Result<(), IoError> {
        let _ = self;
        Err(deferred_writer_error(
            "to_clipboard",
            "OS clipboard access requires GUI bindings outside FrankenPandas's headless charter",
        ))
    }
}

#[cfg(test)]
mod tests {
    use std::collections::BTreeMap;

    use arrow::{
        array::{Array, Int64Array},
        datatypes::DataType as ArrowDataType,
    };
    use fp_columnar::Column;
    use fp_frame::{DataFrame, Series};
    use fp_index::{Index, IndexLabel};
    use fp_types::{DType, NullKind, Scalar};

    use super::{
        CsvWriteOptions, ExcelReadOptions, ExcelWriteOptions, HtmlReadOptions, HtmlWriteOptions,
        IoError, JsonOrient, LatexWriteOptions, MarkdownWriteOptions, PickleProtocol,
        PickleWriteOptions, StataWriteOptions, XmlReadOptions, XmlWriteOptions,
        format_pandas_float, read_csv_str, read_csv_with_index_cols, read_excel_bytes,
        read_feather_bytes, read_html, read_html_str, read_html_str_with_options, read_json_str,
        read_orc, read_orc_bytes, read_parquet_bytes, read_pickle, read_pickle_bytes, read_stata,
        read_stata_bytes, read_xml, read_xml_str, read_xml_str_with_options, write_csv_string,
        write_csv_string_with_options, write_excel_bytes, write_html, write_html_string,
        write_html_string_with_options, write_json_string, write_jsonl_string, write_latex,
        write_latex_string, write_latex_string_with_options, write_latex_with_options,
        write_markdown, write_markdown_string, write_markdown_string_with_options,
        write_markdown_with_options, write_orc, write_orc_bytes, write_pickle, write_pickle_bytes,
        write_stata, write_stata_bytes, write_stata_bytes_with_options, write_xml,
        write_xml_string, write_xml_string_with_options,
    };
    #[cfg(feature = "hdf5")]
    use super::{
        HdfReadOptions, HdfWriteOptions, read_hdf, read_hdf_key, read_hdf_with_options, write_hdf,
        write_hdf_key, write_hdf_with_options,
    };

    #[test]
    fn csv_round_trip_preserves_null_and_numeric_shape() {
        let input = "id,value\n1,10\n2,\n3,3.5\n";
        let frame = read_csv_str(input).expect("read");
        let value_col = frame.column("value").expect("value");

        assert_eq!(value_col.values()[1], Scalar::Null(NullKind::NaN));

        let out = write_csv_string(&frame).expect("write");
        assert!(out.contains("id,value"));
        assert!(out.contains("3,3.5"));
    }

    #[test]
    fn csv_numeric_fast_path_preserves_default_dtypes_and_values() {
        let input = "i,f\n1,0.5\n2,3\n";
        let frame = read_csv_str(input).expect("read");

        let int_col = frame.column("i").expect("i");
        assert_eq!(int_col.dtype(), DType::Int64);
        assert_eq!(int_col.values(), &[Scalar::Int64(1), Scalar::Int64(2)]);

        let float_col = frame.column("f").expect("f");
        assert_eq!(float_col.dtype(), DType::Float64);
        assert_eq!(
            float_col.values(),
            &[Scalar::Float64(0.5), Scalar::Float64(3.0)]
        );
    }

    #[test]
    fn csv_numeric_probe_falls_back_to_preserve_object_raw_text() {
        let input = "x\n 1 \nabc\n";
        let frame = read_csv_str(input).expect("read");
        let column = frame.column("x").expect("x");

        assert_eq!(column.dtype(), DType::Utf8);
        assert_eq!(
            column.values(),
            &[
                Scalar::Utf8(" 1 ".to_owned()),
                Scalar::Utf8("abc".to_owned())
            ]
        );
    }

    #[test]
    fn csv_parses_boolean_true_false_case_insensitive() {
        let input = "flag\nTrue\nFALSE\ntrue\nfalse\n";
        let frame = read_csv_str(input).expect("read");
        let flag_col = frame.column("flag").expect("flag");
        assert_eq!(flag_col.values()[0], Scalar::Bool(true));
        assert_eq!(flag_col.values()[1], Scalar::Bool(false));
        assert_eq!(flag_col.values()[2], Scalar::Bool(true));
        assert_eq!(flag_col.values()[3], Scalar::Bool(false));
    }

    #[test]
    fn csv_duplicate_headers_error() {
        let input = "a,a\n1,2\n";
        let err = read_csv_str(input).expect_err("duplicate header");
        assert!(matches!(err, IoError::DuplicateColumnName(name) if name == "a"));
    }

    #[test]
    fn csv_ragged_row_returns_error_4hpid() {
        // Per br-frankenpandas-4hpid: confirm pandas-faithful rejection on
        // ragged rows. The underlying csv crate raises UnequalLengths
        // (surfaced as IoError::Csv) — record.get(idx).unwrap_or_default()
        // inside the loop is dead code because the `row?` upstream errors
        // first. This locks in the rejection contract.
        let short_row = "a,b,c\n1,2,3\n4,5\n7,8,9\n";
        let err = read_csv_str(short_row).expect_err("short row must reject");
        assert!(
            matches!(err, IoError::Csv(_)),
            "expected IoError::Csv (UnequalLengths from csv crate), got {err:?}"
        );
    }

    fn make_table_format_dataframe() -> DataFrame {
        let mut columns = BTreeMap::new();
        columns.insert(
            "name".to_owned(),
            Column::from_values(vec![
                Scalar::Utf8("A|B".to_owned()),
                Scalar::Utf8("under_score".to_owned()),
            ])
            .expect("name column"),
        );
        columns.insert(
            "value".to_owned(),
            Column::from_values(vec![Scalar::Float64(f64::NAN), Scalar::Int64(2)])
                .expect("value column"),
        );

        let index = Index::new(vec![
            IndexLabel::Utf8("r&1".to_owned()),
            IndexLabel::Utf8("r_2".to_owned()),
        ])
        .set_name("row");
        DataFrame::new_with_column_order(
            index,
            columns,
            vec!["name".to_owned(), "value".to_owned()],
        )
        .expect("table format frame")
    }

    #[test]
    fn markdown_table_writer_includes_index_missing_values_and_escaping() {
        let frame = make_table_format_dataframe();

        let out = write_markdown_string(&frame).expect("markdown");

        assert_eq!(
            out,
            concat!(
                "| row | name | value |\n",
                "| --- | --- | --- |\n",
                "| r&1 | A\\|B | NaN |\n",
                "| r_2 | under_score | 2 |\n",
            )
        );
    }

    #[test]
    fn markdown_table_writer_options_can_omit_index_and_override_na() {
        let frame = make_table_format_dataframe();

        let out = write_markdown_string_with_options(
            &frame,
            &MarkdownWriteOptions {
                include_index: false,
                na_rep: "<missing>".to_owned(),
                index_label: Some("ignored".to_owned()),
            },
        )
        .expect("markdown");

        assert_eq!(
            out,
            concat!(
                "| name | value |\n",
                "| --- | --- |\n",
                "| A\\|B | <missing> |\n",
                "| under_score | 2 |\n",
            )
        );
    }

    #[test]
    fn latex_table_writer_emits_booktabs_and_supports_escaping() {
        let frame = make_table_format_dataframe();

        let out = write_latex_string_with_options(
            &frame,
            &LatexWriteOptions {
                include_index: true,
                na_rep: "NA".to_owned(),
                index_label: Some("row_id".to_owned()),
                escape: true,
            },
        )
        .expect("latex");

        assert_eq!(
            out,
            concat!(
                "\\begin{tabular}{lll}\n",
                "\\toprule\n",
                " & name & value \\\\\n",
                "row\\_id &  &  \\\\\n",
                "\\midrule\n",
                "r\\&1 & A|B & NA \\\\\n",
                "r\\_2 & under\\_score & 2.000000 \\\\\n",
                "\\bottomrule\n",
                "\\end{tabular}\n",
            )
        );
    }

    #[test]
    fn to_latex_floats_use_six_decimal_places_like_pandas() {
        // pandas to_latex default float_format is %.6f. Verified vs pandas 2.2.3:
        // 1.0->"1.000000", -2.5->"-2.500000", 0.1234567->"0.123457" (rounded),
        // inf->"inf". Other writers (csv/html) keep str(float).
        let values = vec![
            Scalar::Float64(1.0),
            Scalar::Float64(-2.5),
            Scalar::Float64(0.1234567),
            Scalar::Float64(f64::INFINITY),
        ];
        let col = Column::new(DType::Float64, values).expect("col");
        let mut cols = BTreeMap::new();
        cols.insert("a".to_string(), col);
        let index = Index::from_i64((0..4).collect());
        let frame =
            DataFrame::new_with_column_order(index, cols, vec!["a".to_string()]).expect("frame");

        let out = write_latex_string_with_options(
            &frame,
            &LatexWriteOptions {
                include_index: false,
                na_rep: "NaN".to_owned(),
                index_label: None,
                escape: true,
            },
        )
        .expect("latex");
        assert!(out.contains("1.000000 \\\\"), "got: {out}");
        assert!(out.contains("-2.500000 \\\\"), "got: {out}");
        assert!(out.contains("0.123457 \\\\"), "got: {out}");
        assert!(out.contains("inf \\\\"), "got: {out}");
    }

    #[test]
    fn markdown_latex_file_writers_match_string_outputs() {
        let frame = make_table_format_dataframe();
        let markdown_path = std::env::temp_dir().join(format!(
            "fp_io_markdown_writer_{}_{}.md",
            std::process::id(),
            line!()
        ));
        let latex_path = std::env::temp_dir().join(format!(
            "fp_io_latex_writer_{}_{}.tex",
            std::process::id(),
            line!()
        ));

        write_markdown(&frame, &markdown_path).expect("write markdown path");
        write_latex(&frame, &latex_path).expect("write latex path");

        assert_eq!(
            std::fs::read_to_string(&markdown_path).expect("read markdown path"),
            write_markdown_string(&frame).expect("markdown string")
        );
        assert_eq!(
            std::fs::read_to_string(&latex_path).expect("read latex path"),
            write_latex_string(&frame).expect("latex string")
        );
    }

    #[test]
    fn markdown_latex_trait_aliases_forward_options() {
        use super::DataFrameIoExt;

        let frame = make_table_format_dataframe();
        let markdown_options = MarkdownWriteOptions {
            include_index: false,
            na_rep: "NA".to_owned(),
            index_label: Some("ignored".to_owned()),
        };
        let latex_options = LatexWriteOptions {
            include_index: false,
            na_rep: "NA".to_owned(),
            index_label: Some("ignored".to_owned()),
            escape: true,
        };
        let markdown_path = std::env::temp_dir().join(format!(
            "fp_io_markdown_trait_{}_{}.md",
            std::process::id(),
            line!()
        ));
        let latex_path = std::env::temp_dir().join(format!(
            "fp_io_latex_trait_{}_{}.tex",
            std::process::id(),
            line!()
        ));

        frame
            .to_markdown_file_with_options(&markdown_path, &markdown_options)
            .expect("trait markdown file");
        frame
            .to_latex_file_with_options(&latex_path, &latex_options)
            .expect("trait latex file");

        assert_eq!(
            frame
                .to_markdown_string_with_options(&markdown_options)
                .expect("trait markdown options"),
            std::fs::read_to_string(&markdown_path).expect("read markdown trait path")
        );
        assert_eq!(
            frame
                .to_latex_string_with_options(&latex_options)
                .expect("trait latex options"),
            std::fs::read_to_string(&latex_path).expect("read latex trait path")
        );

        let default_markdown_path = std::env::temp_dir().join(format!(
            "fp_io_markdown_trait_default_{}_{}.md",
            std::process::id(),
            line!()
        ));
        let default_latex_path = std::env::temp_dir().join(format!(
            "fp_io_latex_trait_default_{}_{}.tex",
            std::process::id(),
            line!()
        ));
        frame
            .to_markdown_file(&default_markdown_path)
            .expect("trait markdown default file");
        frame
            .to_latex_file(&default_latex_path)
            .expect("trait latex default file");

        assert_eq!(
            std::fs::read_to_string(&default_markdown_path).expect("read markdown default"),
            write_markdown_string(&frame).expect("markdown default")
        );
        assert_eq!(
            std::fs::read_to_string(&default_latex_path).expect("read latex default"),
            write_latex_string(&frame).expect("latex default")
        );

        let free_markdown_path = std::env::temp_dir().join(format!(
            "fp_io_markdown_free_options_{}_{}.md",
            std::process::id(),
            line!()
        ));
        let free_latex_path = std::env::temp_dir().join(format!(
            "fp_io_latex_free_options_{}_{}.tex",
            std::process::id(),
            line!()
        ));
        write_markdown_with_options(&frame, &free_markdown_path, &markdown_options)
            .expect("free markdown options file");
        write_latex_with_options(&frame, &free_latex_path, &latex_options)
            .expect("free latex options file");
        assert_eq!(
            std::fs::read_to_string(&free_markdown_path).expect("read free markdown options"),
            write_markdown_string_with_options(&frame, &markdown_options)
                .expect("free markdown options string")
        );
        assert_eq!(
            std::fs::read_to_string(&free_latex_path).expect("read free latex options"),
            write_latex_string_with_options(&frame, &latex_options)
                .expect("free latex options string")
        );
    }

    #[test]
    fn html_table_writer_defaults_to_index_and_reuses_dataframe_formatter() {
        let frame = make_table_format_dataframe();

        let out = write_html_string(&frame).expect("html");

        assert_eq!(out, frame.to_html(true));
        assert!(out.contains("<th>r&amp;1</th>"));
        assert!(out.contains("<td>A|B</td>"));
        assert!(out.contains("<td>NaN</td>"));
    }

    #[test]
    fn html_table_writer_options_can_omit_index() {
        let frame = make_table_format_dataframe();

        let out = write_html_string_with_options(
            &frame,
            &HtmlWriteOptions {
                include_index: false,
                ..HtmlWriteOptions::default()
            },
        )
        .expect("html");

        assert_eq!(out, frame.to_html(false));
        assert!(!out.contains("<th>r&amp;1</th>"));
        assert!(out.contains("<td>A|B</td>"));
    }

    #[test]
    fn html_table_writer_supports_pandas_pure_string_options_u892h() {
        let mut columns = BTreeMap::new();
        columns.insert(
            "url&col".to_owned(),
            Column::from_values(vec![
                Scalar::Utf8("https://example.test/a?x=1&y=2".to_owned()),
                Scalar::Utf8("<b>".to_owned()),
            ])
            .expect("url column"),
        );
        columns.insert(
            "value".to_owned(),
            Column::from_values(vec![Scalar::Null(NullKind::NaN), Scalar::Float64(2.0)])
                .expect("value column"),
        );
        let frame = DataFrame::new_with_column_order(
            Index::new(vec![
                IndexLabel::Utf8("r&1".to_owned()),
                IndexLabel::Utf8("r2".to_owned()),
            ]),
            columns,
            vec!["url&col".to_owned(), "value".to_owned()],
        )
        .expect("html options frame");

        let out = write_html_string_with_options(
            &frame,
            &HtmlWriteOptions {
                include_index: true,
                na_rep: "<NA>".to_owned(),
                classes: vec!["table table-sm".to_owned(), "fp".to_owned()],
                table_id: Some("report&1".to_owned()),
                border: Some(0),
                justify: Some("left".to_owned()),
                escape: true,
                render_links: true,
            },
        )
        .expect("html options");

        assert!(
            out.starts_with("<table class=\"dataframe table table-sm fp\" id=\"report&amp;1\">")
        );
        assert!(!out.contains("border=\""));
        assert!(out.contains("<tr style=\"text-align: left;\">"));
        assert!(out.contains("<th>url&amp;col</th>"));
        assert!(out.contains("<th>r&amp;1</th>"));
        assert!(out.contains("<td>&lt;NA&gt;</td>"));
        assert!(out.contains(
            "<a href=\"https://example.test/a?x=1&amp;y=2\" target=\"_blank\">https://example.test/a?x=1&amp;y=2</a>"
        ));
        assert!(out.contains("<td>&lt;b&gt;</td>"));
    }

    #[test]
    fn html_table_writer_can_disable_escaping_u892h() {
        let mut columns = BTreeMap::new();
        columns.insert(
            "raw<th>".to_owned(),
            Column::from_values(vec![
                Scalar::Utf8("<b>".to_owned()),
                Scalar::Null(NullKind::NaN),
            ])
            .expect("raw column"),
        );
        let frame = DataFrame::new_with_column_order(
            Index::new(vec![
                IndexLabel::Utf8("r&1".to_owned()),
                IndexLabel::Int64(2),
            ]),
            columns,
            vec!["raw<th>".to_owned()],
        )
        .expect("raw html frame");

        let out = write_html_string_with_options(
            &frame,
            &HtmlWriteOptions {
                na_rep: "<NA>".to_owned(),
                escape: false,
                ..HtmlWriteOptions::default()
            },
        )
        .expect("raw html options");

        assert!(out.contains("<th>raw<th></th>"));
        assert!(out.contains("<th>r&1</th>"));
        assert!(out.contains("<td><b></td>"));
        assert!(out.contains("<td><NA></td>"));
    }

    #[test]
    fn html_table_writer_file_output_matches_string_output() {
        use super::DataFrameIoExt;

        let frame = make_table_format_dataframe();
        let path = std::env::temp_dir().join(format!(
            "fp_io_html_writer_{}_{}.html",
            std::process::id(),
            line!()
        ));

        write_html(&frame, &path).expect("write html");
        let file_out = std::fs::read_to_string(&path).expect("read html");

        assert_eq!(file_out, write_html_string(&frame).expect("html string"));
        assert_eq!(
            frame.to_html_string().expect("trait html string"),
            write_html_string(&frame).expect("free html string")
        );

        let no_index_path = std::env::temp_dir().join(format!(
            "fp_io_html_writer_no_index_{}_{}.html",
            std::process::id(),
            line!()
        ));
        let no_index_options = HtmlWriteOptions {
            include_index: false,
            ..HtmlWriteOptions::default()
        };
        frame
            .to_html_file_with_options(&no_index_path, &no_index_options)
            .expect("trait html file");
        assert_eq!(
            std::fs::read_to_string(&no_index_path).expect("read trait html"),
            write_html_string_with_options(&frame, &no_index_options).expect("free html options")
        );
    }

    #[test]
    fn html_reader_parses_first_table_headers_and_missing_cells() {
        let html = concat!(
            "<html><body>",
            "<table><tr><td>ignored</td></tr></table>",
            "<table>",
            "<thead><tr><th>name</th><th>value</th><th>flag</th></tr></thead>",
            "<tbody>",
            "<tr><td>A&amp;B</td><td>1</td><td>True</td></tr>",
            "<tr><td>missing</td><td></td></tr>",
            "</tbody>",
            "</table>",
            "</body></html>",
        );

        let frame = read_html_str_with_options(html, &HtmlReadOptions { table_index: 1 })
            .expect("read second table");

        assert_eq!(
            frame
                .column_names()
                .into_iter()
                .map(String::as_str)
                .collect::<Vec<_>>(),
            vec!["name", "value", "flag"]
        );
        assert_eq!(
            frame.column("name").expect("name").values()[0],
            Scalar::Utf8("A&B".to_owned())
        );
        assert_eq!(
            frame.column("value").expect("value").values()[0],
            Scalar::Int64(1)
        );
        assert!(frame.column("value").expect("value").values()[1].is_missing());
        assert_eq!(
            frame.column("flag").expect("flag").values()[0],
            Scalar::Bool(true)
        );
        assert!(matches!(
            frame.column("flag").expect("flag").values()[1],
            Scalar::Null(NullKind::Null)
        ));
    }

    #[test]
    fn html_reader_roundtrips_writer_output_as_columns() {
        let source = make_table_format_dataframe();
        let html = write_html_string(&source).expect("write html");

        let frame = read_html_str(&html).expect("read writer html");

        assert_eq!(
            frame
                .column_names()
                .into_iter()
                .map(String::as_str)
                .collect::<Vec<_>>(),
            vec!["Unnamed: 0", "name", "value"]
        );
        assert_eq!(
            frame.column("Unnamed: 0").expect("index column").values()[0],
            Scalar::Utf8("r&1".to_owned())
        );
        assert_eq!(
            frame.column("name").expect("name").values()[0],
            Scalar::Utf8("A|B".to_owned())
        );
        assert!(frame.column("value").expect("value").values()[0].is_missing());
        assert_eq!(
            frame.column("value").expect("value").values()[1],
            Scalar::Float64(2.0)
        );
    }

    #[test]
    fn html_reader_path_reader_matches_string_reader() {
        use std::io::Write;

        let html = "<table><tr><th>name</th></tr><tr><td>A</td></tr></table>\n";
        let path = std::env::temp_dir().join(format!(
            "fp_io_html_reader_{}_{}.html",
            std::process::id(),
            line!()
        ));
        let mut file = std::fs::OpenOptions::new()
            .write(true)
            .create_new(true)
            .open(&path)
            .expect("create html fixture");
        file.write_all(html.as_bytes()).expect("write html fixture");

        let via_path = read_html(&path).expect("read path html");
        let via_str = read_html_str(html).expect("read string html");

        assert_eq!(via_path.column_names(), via_str.column_names());
        assert_eq!(
            via_path.column("name").expect("path name").values(),
            via_str.column("name").expect("str name").values()
        );
    }

    #[test]
    fn html_reader_rejects_no_table_duplicate_headers_and_wide_rows() {
        let err = read_html_str("<p>no table</p>").expect_err("missing table");
        assert!(matches!(err, IoError::Html(message) if message.contains("no table")));

        let duplicate = "<table><tr><th>a</th><th>a</th></tr><tr><td>1</td><td>2</td></tr></table>";
        assert!(matches!(
            read_html_str(duplicate),
            Err(IoError::DuplicateColumnName(name)) if name == "a"
        ));

        let wide = "<table><tr><th>a</th></tr><tr><td>1</td><td>2</td></tr></table>";
        let err = read_html_str(wide).expect_err("wide row");
        assert!(matches!(err, IoError::Html(message) if message.contains("row 0")));
    }

    #[test]
    fn pickle_bytes_roundtrip_preserves_split_frame_shape() {
        let source = read_json_str(
            r#"{"columns":["name","value","flag"],"index":["r1","r2"],"data":[["alice",1,true],[null,2.5,false]]}"#,
            JsonOrient::Split,
        )
        .expect("source frame");

        let bytes = write_pickle_bytes(&source).expect("write pickle bytes");
        assert!(!bytes.is_empty());
        let roundtrip = read_pickle_bytes(&bytes).expect("read pickle bytes");

        assert_eq!(
            write_json_string(&roundtrip, JsonOrient::Split).expect("roundtrip json"),
            write_json_string(&source, JsonOrient::Split).expect("source json")
        );
    }

    #[test]
    fn pickle_path_reader_matches_bytes_reader() {
        let source = make_table_format_dataframe();
        let path = std::env::temp_dir().join(format!(
            "fp_io_pickle_reader_{}_{}.pkl",
            std::process::id(),
            line!()
        ));

        write_pickle(&source, &path).expect("write pickle path");

        let via_path = read_pickle(&path).expect("read pickle path");
        let via_bytes =
            read_pickle_bytes(&std::fs::read(&path).expect("read pickle bytes from path"))
                .expect("read pickle bytes");

        assert_eq!(
            write_json_string(&via_path, JsonOrient::Split).expect("path json"),
            write_json_string(&via_bytes, JsonOrient::Split).expect("bytes json")
        );
    }

    #[test]
    fn pickle_protocol_v2_and_extension_aliases_roundtrip() {
        use super::DataFrameIoExt;

        let source = make_table_format_dataframe();
        let options = PickleWriteOptions {
            protocol: PickleProtocol::V2,
        };
        let bytes = source
            .to_pickle_bytes_with_options(&options)
            .expect("trait pickle protocol v2");
        let roundtrip = read_pickle_bytes(&bytes).expect("read protocol v2");

        assert_eq!(
            write_json_string(&roundtrip, JsonOrient::Split).expect("roundtrip json"),
            write_json_string(&source, JsonOrient::Split).expect("source json")
        );
        assert_eq!(
            source.to_pickle_bytes().expect("trait pickle bytes"),
            write_pickle_bytes(&source).expect("free pickle bytes")
        );
    }

    #[test]
    fn series_pickle_extension_aliases_roundtrip_to_single_column_frame() {
        use super::SeriesIoExt;

        let source = Series::from_values(
            "sales",
            vec!["r1".into(), "r2".into()],
            vec![Scalar::Int64(10), Scalar::Int64(12)],
        )
        .expect("source series");

        let bytes = source.to_pickle_bytes().expect("series pickle bytes");
        let roundtrip = read_pickle_bytes(&bytes).expect("read series pickle frame");
        let names = roundtrip
            .column_names()
            .into_iter()
            .map(String::as_str)
            .collect::<Vec<_>>();
        assert_eq!(names, vec!["sales"]);
        assert_eq!(roundtrip.index().labels(), source.index().labels());
        assert_eq!(
            roundtrip.column("sales").expect("sales column").values(),
            source.values()
        );

        let frame = source.to_frame(None).expect("series frame");
        assert_eq!(
            source.to_pickle_bytes().expect("trait pickle bytes"),
            write_pickle_bytes(&frame).expect("frame pickle bytes")
        );

        let options = PickleWriteOptions {
            protocol: PickleProtocol::V2,
        };
        assert!(
            !source
                .to_pickle_bytes_with_options(&options)
                .expect("series pickle protocol v2")
                .is_empty()
        );
    }

    #[test]
    fn series_csv_extension_aliases_preserve_default_index() {
        use super::SeriesIoExt;

        let source = Series::from_values(
            "sales",
            vec!["r1".into(), "r2".into()],
            vec![Scalar::Int64(10), Scalar::Int64(12)],
        )
        .expect("source series");

        let csv = source.to_csv_string().expect("series csv string");
        assert_eq!(csv, ",sales\nr1,10\nr2,12\n");

        let no_index = source
            .to_csv_string_with_options(&CsvWriteOptions {
                include_index: false,
                ..CsvWriteOptions::default()
            })
            .expect("series csv without index");
        assert_eq!(no_index, "sales\n10\n12\n");

        let path = std::env::temp_dir().join(format!(
            "fp_io_series_csv_{}_{}.csv",
            std::process::id(),
            line!()
        ));
        source.to_csv_file(&path).expect("series csv file");
        assert_eq!(
            std::fs::read_to_string(&path).expect("read series csv file"),
            csv
        );
    }

    #[test]
    fn series_json_extension_aliases_use_series_orients() {
        use super::SeriesIoExt;

        let source = Series::from_values(
            "sales",
            vec!["r1".into(), "r2".into()],
            vec![Scalar::Int64(10), Scalar::Int64(12)],
        )
        .expect("source series");

        assert_eq!(
            source
                .to_json_string("records")
                .expect("series records json"),
            "[10,12]"
        );

        let split: serde_json::Value =
            serde_json::from_str(&source.to_json_string("split").expect("series split json"))
                .expect("parse split json");
        assert_eq!(split["name"], "sales");
        assert_eq!(split["index"], serde_json::json!(["r1", "r2"]));
        assert_eq!(split["data"], serde_json::json!([10, 12]));

        let path = std::env::temp_dir().join(format!(
            "fp_io_series_json_{}_{}.json",
            std::process::id(),
            line!()
        ));
        source
            .to_json_file(&path, "index")
            .expect("series json file");
        assert_eq!(
            std::fs::read_to_string(&path).expect("read series json file"),
            source.to_json("index").expect("series index json")
        );
    }

    #[test]
    fn series_markdown_extension_aliases_forward_options() {
        use super::SeriesIoExt;

        let source = Series::from_values(
            "sales",
            vec!["r1".into(), "r2".into()],
            vec![Scalar::Int64(10), Scalar::Null(NullKind::NaN)],
        )
        .expect("source series");
        let options = MarkdownWriteOptions {
            include_index: false,
            na_rep: "NA".to_owned(),
            index_label: Some("ignored".to_owned()),
        };

        assert_eq!(
            source.to_markdown_string().expect("series markdown string"),
            write_markdown_string(&source.to_frame(None).expect("series frame"))
                .expect("frame markdown string")
        );
        assert_eq!(
            source
                .to_markdown_string_with_options(&options)
                .expect("series markdown options"),
            write_markdown_string_with_options(
                &source.to_frame(None).expect("series options frame"),
                &options,
            )
            .expect("frame markdown options")
        );

        let path = std::env::temp_dir().join(format!(
            "fp_io_series_markdown_{}_{}.md",
            std::process::id(),
            line!()
        ));
        source
            .to_markdown_file_with_options(&path, &options)
            .expect("series markdown file");
        assert_eq!(
            std::fs::read_to_string(&path).expect("read series markdown file"),
            source
                .to_markdown_string_with_options(&options)
                .expect("series markdown options string")
        );
    }

    #[test]
    fn series_latex_extension_aliases_forward_options() {
        use super::SeriesIoExt;

        let source = Series::from_values(
            "sales&tax",
            vec!["r1".into(), "r2".into()],
            vec![Scalar::Utf8("a&b".into()), Scalar::Null(NullKind::NaN)],
        )
        .expect("source series");
        let options = LatexWriteOptions {
            include_index: false,
            na_rep: "NA".to_owned(),
            index_label: Some("ignored".to_owned()),
            escape: true,
        };

        assert_eq!(
            source.to_latex_string().expect("series latex string"),
            write_latex_string(&source.to_frame(None).expect("series frame"))
                .expect("frame latex string")
        );
        assert_eq!(
            source
                .to_latex_string_with_options(&options)
                .expect("series latex options"),
            write_latex_string_with_options(
                &source.to_frame(None).expect("series options frame"),
                &options,
            )
            .expect("frame latex options")
        );

        let path = std::env::temp_dir().join(format!(
            "fp_io_series_latex_{}_{}.tex",
            std::process::id(),
            line!()
        ));
        source
            .to_latex_file_with_options(&path, &options)
            .expect("series latex file");
        assert_eq!(
            std::fs::read_to_string(&path).expect("read series latex file"),
            source
                .to_latex_string_with_options(&options)
                .expect("series latex options string")
        );
    }

    #[cfg(feature = "hdf5")]
    #[test]
    fn series_hdf5_extension_aliases_roundtrip_to_single_column_frame() {
        use super::SeriesIoExt;

        let source = Series::from_values(
            "sales",
            vec!["r1".into(), "r2".into()],
            vec![Scalar::Int64(10), Scalar::Int64(12)],
        )
        .expect("source series");
        let expected = source.to_frame(None).expect("series frame");

        let key_path = std::env::temp_dir().join(format!(
            "fp_io_series_hdf5_key_{}_{}.h5",
            std::process::id(),
            line!()
        ));
        source
            .to_hdf_key(&key_path, "series/data")
            .expect("series hdf key");
        assert!(
            read_hdf_key(&key_path, "series/data")
                .expect("read series hdf key")
                .equals(&expected)
        );

        let default_path = std::env::temp_dir().join(format!(
            "fp_io_series_hdf5_default_{}_{}.h5",
            std::process::id(),
            line!()
        ));
        source
            .to_hdf_file(&default_path)
            .expect("series hdf default key");
        assert!(
            read_hdf(&default_path)
                .expect("read series hdf default")
                .equals(&expected)
        );

        let options_path = std::env::temp_dir().join(format!(
            "fp_io_series_hdf5_options_{}_{}.h5",
            std::process::id(),
            line!()
        ));
        source
            .to_hdf_with_options(
                &options_path,
                &HdfWriteOptions {
                    key: "series/options".to_owned(),
                },
            )
            .expect("series hdf options");
        assert!(
            read_hdf_key(&options_path, "series/options")
                .expect("read series hdf options")
                .equals(&expected)
        );
    }

    #[test]
    fn series_excel_extension_aliases_roundtrip_to_single_column_frame() {
        use super::SeriesIoExt;

        let source = Series::from_values(
            "sales",
            vec!["r1".into(), "r2".into()],
            vec![Scalar::Int64(10), Scalar::Int64(12)],
        )
        .expect("source series");

        let bytes = source.to_excel_bytes().expect("series excel bytes");
        let roundtrip =
            read_excel_bytes(&bytes, &ExcelReadOptions::default()).expect("read series excel");
        let names = roundtrip
            .column_names()
            .into_iter()
            .map(String::as_str)
            .collect::<Vec<_>>();
        assert_eq!(names, vec!["column_0", "sales"]);
        assert_eq!(
            roundtrip.column("column_0").expect("index column").values(),
            &[Scalar::Utf8("r1".into()), Scalar::Utf8("r2".into())]
        );
        assert_eq!(
            roundtrip.column("sales").expect("sales column").values(),
            source.values()
        );

        let frame = source.to_frame(None).expect("series frame");
        assert_eq!(
            source.to_excel_bytes().expect("trait excel bytes"),
            write_excel_bytes(&frame).expect("frame excel bytes")
        );

        let options = ExcelWriteOptions {
            index: false,
            ..ExcelWriteOptions::default()
        };
        let no_index_bytes = source
            .to_excel_bytes_with_options(&options)
            .expect("series excel index false");
        let no_index = read_excel_bytes(&no_index_bytes, &ExcelReadOptions::default())
            .expect("read no-index series excel");
        assert_eq!(no_index.column_names(), vec!["sales"]);
        assert_eq!(no_index.index().len(), source.index().len());
    }

    #[test]
    fn pickle_reader_rejects_malformed_and_foreign_payloads() {
        let err = read_pickle_bytes(b"not a pickle").expect_err("malformed pickle");
        assert!(matches!(err, IoError::Pickle(_)));

        let foreign = serde_pickle::to_vec(
            &serde_json::json!({"payload": {"columns": [], "index": [], "data": []}}),
            serde_pickle::SerOptions::new(),
        )
        .expect("foreign pickle");
        let err = read_pickle_bytes(&foreign).expect_err("foreign pickle");
        assert!(matches!(
            err,
            IoError::Pickle(message) if message.contains("format marker")
        ));
    }

    #[cfg(feature = "hdf5")]
    #[test]
    fn hdf5_path_roundtrip_preserves_snapshot_frame() {
        let source = make_table_format_dataframe();
        let path = std::env::temp_dir().join(format!(
            "fp_io_hdf5_default_{}_{}.h5",
            std::process::id(),
            line!()
        ));

        write_hdf(&source, &path).expect("write hdf default key");
        let roundtrip = read_hdf(&path).expect("read hdf default key");

        assert_eq!(
            write_json_string(&roundtrip, JsonOrient::Split).expect("roundtrip json"),
            write_json_string(&source, JsonOrient::Split).expect("source json")
        );
    }

    #[cfg(feature = "hdf5")]
    #[test]
    fn hdf5_custom_key_and_extension_aliases_roundtrip() {
        use super::DataFrameIoExt;

        let source = make_test_dataframe();
        let free_path = std::env::temp_dir().join(format!(
            "fp_io_hdf5_custom_free_{}_{}.h5",
            std::process::id(),
            line!()
        ));
        let trait_path = std::env::temp_dir().join(format!(
            "fp_io_hdf5_custom_trait_{}_{}.h5",
            std::process::id(),
            line!()
        ));
        let default_path = std::env::temp_dir().join(format!(
            "fp_io_hdf5_custom_default_{}_{}.h5",
            std::process::id(),
            line!()
        ));
        let write_options = HdfWriteOptions {
            key: "tables/snapshot".to_owned(),
        };

        write_hdf_with_options(&source, &free_path, &write_options).expect("write custom key");
        let roundtrip = read_hdf_with_options(
            &free_path,
            &HdfReadOptions {
                key: "/tables/snapshot/".to_owned(),
            },
        )
        .expect("read custom key with slash aliases");
        assert!(roundtrip.equals(&source));

        source
            .to_hdf_key(&trait_path, "nested/frame")
            .expect("trait hdf key");
        assert!(
            read_hdf_key(&trait_path, "nested/frame")
                .expect("read trait hdf key")
                .equals(&source)
        );

        source
            .to_hdf_file(&default_path)
            .expect("trait hdf default key");
        assert!(
            read_hdf(&default_path)
                .expect("read trait hdf default")
                .equals(&source)
        );
    }

    #[cfg(feature = "hdf5")]
    #[test]
    fn hdf5_row_multiindex_roundtrip_restores_logical_row_axis() {
        let frame = make_row_multiindex_test_dataframe();
        let path = std::env::temp_dir().join(format!(
            "fp_io_hdf5_multiindex_{}_{}.h5",
            std::process::id(),
            line!()
        ));

        write_hdf_key(&frame, &path, "axes/frame").expect("write hdf multiindex");
        let roundtrip = read_hdf_key(&path, "axes/frame").expect("read hdf multiindex");

        assert!(roundtrip.equals(&frame));
        assert!(roundtrip.column("__index_level_0__").is_none());
        assert_eq!(
            roundtrip
                .row_multiindex()
                .expect("row multiindex should be restored")
                .get_level_values(0)
                .unwrap()
                .labels(),
            frame
                .row_multiindex()
                .expect("source row multiindex")
                .get_level_values(0)
                .unwrap()
                .labels()
        );
    }

    #[cfg(feature = "hdf5")]
    #[test]
    fn hdf5_reader_rejects_invalid_keys_and_missing_payloads() {
        let frame = make_test_dataframe();
        let path = std::env::temp_dir().join(format!(
            "fp_io_hdf5_missing_payload_{}_{}.h5",
            std::process::id(),
            line!()
        ));

        let file = hdf5::File::create(&path).expect("create hdf shell");
        file.create_group("frame")
            .expect("create empty frame group");
        file.flush().expect("flush hdf shell");
        drop(file);

        let err = read_hdf(&path).expect_err("missing payload should fail");
        assert!(matches!(
            err,
            IoError::Hdf5(message) if message.contains("missing FrankenPandas payload dataset")
        ));

        let err = write_hdf_key(&frame, &path, "../bad").expect_err("invalid key should fail");
        assert!(matches!(
            err,
            IoError::Hdf5(message) if message.contains("invalid hdf5 key")
        ));
    }

    fn make_stata_dataframe() -> DataFrame {
        let mut columns = BTreeMap::new();
        columns.insert(
            "id".to_owned(),
            Column::from_values(vec![Scalar::Int64(1), Scalar::Int64(2), Scalar::Int64(3)])
                .expect("id column"),
        );
        columns.insert(
            "score".to_owned(),
            Column::from_values(vec![
                Scalar::Float64(1.5),
                Scalar::Null(NullKind::NaN),
                Scalar::Float64(3.25),
            ])
            .expect("score column"),
        );
        columns.insert(
            "flag".to_owned(),
            Column::from_values(vec![
                Scalar::Bool(true),
                Scalar::Bool(false),
                Scalar::Bool(true),
            ])
            .expect("flag column"),
        );
        columns.insert(
            "label".to_owned(),
            Column::from_values(vec![
                Scalar::Utf8("alpha".to_owned()),
                Scalar::Utf8("beta".to_owned()),
                Scalar::Utf8("gamma".to_owned()),
            ])
            .expect("label column"),
        );

        DataFrame::new_with_column_order(
            Index::new(vec![
                IndexLabel::Utf8("row_a".to_owned()),
                IndexLabel::Utf8("row_b".to_owned()),
                IndexLabel::Utf8("row_c".to_owned()),
            ]),
            columns,
            vec![
                "id".to_owned(),
                "score".to_owned(),
                "flag".to_owned(),
                "label".to_owned(),
            ],
        )
        .expect("stata frame")
    }

    #[test]
    fn stata_bytes_roundtrip_preserves_supported_columns() {
        let source = make_stata_dataframe();
        let bytes = write_stata_bytes(&source).expect("write stata bytes");
        assert!(!bytes.is_empty());

        let roundtrip = read_stata_bytes(&bytes).expect("read stata bytes");

        assert_eq!(
            roundtrip
                .column_names()
                .into_iter()
                .map(String::as_str)
                .collect::<Vec<_>>(),
            vec!["index", "id", "score", "flag", "label"]
        );
        assert_eq!(
            roundtrip.column("index").expect("index").values(),
            &[
                Scalar::Utf8("row_a".to_owned()),
                Scalar::Utf8("row_b".to_owned()),
                Scalar::Utf8("row_c".to_owned())
            ]
        );
        assert_eq!(
            roundtrip.column("id").expect("id").values(),
            &[Scalar::Int64(1), Scalar::Int64(2), Scalar::Int64(3)]
        );
        assert_eq!(
            roundtrip.column("score").expect("score").values(),
            &[
                Scalar::Float64(1.5),
                Scalar::Null(NullKind::NaN),
                Scalar::Float64(3.25)
            ]
        );
        assert_eq!(
            roundtrip.column("flag").expect("flag").values(),
            &[Scalar::Int64(1), Scalar::Int64(0), Scalar::Int64(1)]
        );
        assert_eq!(
            roundtrip.column("label").expect("label").values(),
            &[
                Scalar::Utf8("alpha".to_owned()),
                Scalar::Utf8("beta".to_owned()),
                Scalar::Utf8("gamma".to_owned())
            ]
        );
    }

    #[test]
    fn stata_path_reader_matches_bytes_reader() {
        let source = make_stata_dataframe();
        let path = std::env::temp_dir().join(format!(
            "fp_io_stata_reader_{}_{}.dta",
            std::process::id(),
            line!()
        ));

        write_stata(&source, &path).expect("write stata path");

        let via_path = read_stata(&path).expect("read stata path");
        let via_bytes =
            read_stata_bytes(&std::fs::read(&path).expect("read stata bytes from path"))
                .expect("read stata bytes");

        assert_eq!(via_path.column_names(), via_bytes.column_names());
        for name in via_path.column_names() {
            assert_eq!(
                via_path.column(name).expect("path column").values(),
                via_bytes.column(name).expect("bytes column").values()
            );
        }
    }

    #[test]
    fn stata_extension_aliases_and_no_index_option_roundtrip() {
        use super::DataFrameIoExt;

        let source = make_stata_dataframe();
        let options = StataWriteOptions {
            include_index: false,
            index_label: Some("ignored".to_owned()),
        };
        let bytes = source
            .to_stata_bytes_with_options(&options)
            .expect("trait stata bytes without index");
        let roundtrip = read_stata_bytes(&bytes).expect("read no-index stata");

        assert_eq!(
            roundtrip
                .column_names()
                .into_iter()
                .map(String::as_str)
                .collect::<Vec<_>>(),
            vec!["id", "score", "flag", "label"]
        );

        let path = std::env::temp_dir().join(format!(
            "fp_io_stata_trait_{}_{}.dta",
            std::process::id(),
            line!()
        ));
        source
            .to_stata_with_options(&path, &options)
            .expect("trait stata path without index");
        let via_path = read_stata(&path).expect("read trait stata path");
        assert_eq!(via_path.column_names(), roundtrip.column_names());

        assert_eq!(
            source.to_stata_bytes().expect("trait stata bytes"),
            write_stata_bytes(&source).expect("free stata bytes")
        );
    }

    #[test]
    fn stata_writer_rejects_invalid_variable_names_and_malformed_input() {
        let mut columns = BTreeMap::new();
        columns.insert(
            "bad-name".to_owned(),
            Column::from_values(vec![Scalar::Int64(1)]).expect("bad column"),
        );
        let frame = DataFrame::new_with_column_order(
            Index::from_i64(vec![0]),
            columns,
            vec!["bad-name".to_owned()],
        )
        .expect("frame with invalid stata column");

        let err = write_stata_bytes(&frame).expect_err("invalid stata variable name");
        assert!(matches!(
            err,
            IoError::Stata(message) if message.contains("invalid Stata variable name")
        ));

        let source = make_stata_dataframe();
        let err = write_stata_bytes_with_options(
            &source,
            &StataWriteOptions {
                include_index: true,
                index_label: Some("1bad".to_owned()),
            },
        )
        .expect_err("invalid index variable name");
        assert!(matches!(
            err,
            IoError::Stata(message) if message.contains("first character")
        ));

        let err = read_stata_bytes(b"not a dta").expect_err("malformed stata");
        assert!(matches!(err, IoError::Stata(_)));
    }

    #[test]
    fn xml_writer_defaults_to_index_and_escapes_values() {
        let frame = make_table_format_dataframe();

        let out = write_xml_string(&frame).expect("xml");

        assert_eq!(
            out,
            concat!(
                "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n",
                "<data>\n",
                "  <row>\n",
                "    <row>r&amp;1</row>\n",
                "    <name>A|B</name>\n",
                "    <value/>\n",
                "  </row>\n",
                "  <row>\n",
                "    <row>r_2</row>\n",
                "    <name>under_score</name>\n",
                "    <value>2.0</value>\n",
                "  </row>\n",
                "</data>\n",
            )
        );
    }

    #[test]
    fn xml_writer_options_can_omit_index_and_reject_bad_names() {
        let frame = make_table_format_dataframe();

        let out = write_xml_string_with_options(
            &frame,
            &XmlWriteOptions {
                include_index: false,
                root_name: "records".to_owned(),
                row_name: "entry".to_owned(),
                index_label: Some("ignored".to_owned()),
            },
        )
        .expect("xml");

        assert_eq!(
            out,
            concat!(
                "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n",
                "<records>\n",
                "  <entry>\n",
                "    <name>A|B</name>\n",
                "    <value/>\n",
                "  </entry>\n",
                "  <entry>\n",
                "    <name>under_score</name>\n",
                "    <value>2.0</value>\n",
                "  </entry>\n",
                "</records>\n",
            )
        );

        let err = write_xml_string_with_options(
            &frame,
            &XmlWriteOptions {
                root_name: "bad name".to_owned(),
                ..Default::default()
            },
        )
        .expect_err("invalid xml name");
        assert!(matches!(err, IoError::Xml(message) if message.contains("bad name")));
    }

    #[test]
    fn xml_writer_escapes_text_like_pandas_etree() {
        let mut columns = BTreeMap::new();
        columns.insert(
            "name".to_owned(),
            Column::from_values(vec![Scalar::Utf8(
                "A&B <tag> \"quote\" it's\r\nnext".to_owned(),
            )])
            .expect("name column"),
        );
        let frame = DataFrame::new_with_column_order(
            Index::new(vec![IndexLabel::Utf8("idx".to_owned())]),
            columns,
            vec!["name".to_owned()],
        )
        .expect("xml escape frame");

        assert_eq!(
            write_xml_string_with_options(
                &frame,
                &XmlWriteOptions {
                    include_index: false,
                    ..Default::default()
                },
            )
            .expect("xml"),
            concat!(
                "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n",
                "<data>\n",
                "  <row>\n",
                "    <name>A&amp;B &lt;tag&gt; \"quote\" it's\n",
                "next</name>\n",
                "  </row>\n",
                "</data>\n",
            )
        );
    }

    #[test]
    fn xml_writer_file_output_and_extension_aliases_match_free_functions() {
        use super::DataFrameIoExt;

        let frame = make_table_format_dataframe();
        let path = std::env::temp_dir().join(format!(
            "fp_io_xml_writer_{}_{}.xml",
            std::process::id(),
            line!()
        ));

        write_xml(&frame, &path).expect("write xml");
        assert_eq!(
            std::fs::read_to_string(&path).expect("read xml"),
            write_xml_string(&frame).expect("xml string")
        );
        assert_eq!(
            frame.to_xml_string().expect("trait xml string"),
            write_xml_string(&frame).expect("free xml string")
        );

        let trait_path = std::env::temp_dir().join(format!(
            "fp_io_xml_writer_trait_alias_{}_{}.xml",
            std::process::id(),
            line!()
        ));
        frame.to_xml(&trait_path).expect("trait xml alias");
        assert_eq!(
            std::fs::read_to_string(&trait_path).expect("read trait xml alias"),
            write_xml_string(&frame).expect("free xml string")
        );

        let no_index_options = XmlWriteOptions {
            include_index: false,
            ..Default::default()
        };
        let no_index_path = std::env::temp_dir().join(format!(
            "fp_io_xml_writer_no_index_{}_{}.xml",
            std::process::id(),
            line!()
        ));
        frame
            .to_xml_file_with_options(&no_index_path, &no_index_options)
            .expect("trait xml file");
        assert_eq!(
            std::fs::read_to_string(&no_index_path).expect("read trait xml"),
            write_xml_string_with_options(&frame, &no_index_options).expect("free xml options")
        );
    }

    #[test]
    fn xml_reader_parses_pandas_row_shape_and_empty_values() {
        let xml = concat!(
            "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n",
            "<data>\n",
            "  <row>\n",
            "    <index>0</index>\n",
            "    <a>1</a>\n",
            "    <b/>\n",
            "  </row>\n",
            "  <row>\n",
            "    <index>1</index>\n",
            "    <a>2.5</a>\n",
            "    <b>x</b>\n",
            "  </row>\n",
            "</data>\n",
        );

        let frame = read_xml_str(xml).expect("read xml");

        assert_eq!(
            frame
                .column_names()
                .into_iter()
                .map(String::as_str)
                .collect::<Vec<_>>(),
            vec!["index", "a", "b"]
        );
        assert_eq!(
            frame.index().labels(),
            &[IndexLabel::Int64(0), IndexLabel::Int64(1)]
        );
        assert_eq!(
            frame.column("index").expect("index").values()[0],
            Scalar::Int64(0)
        );
        assert_eq!(
            frame.column("a").expect("a").values()[1],
            Scalar::Float64(2.5)
        );
        assert!(matches!(
            frame.column("b").expect("b").values()[0],
            Scalar::Null(NullKind::Null)
        ));
        assert_eq!(
            frame.column("b").expect("b").values()[1],
            Scalar::Utf8("x".to_owned())
        );
    }

    #[test]
    fn xml_reader_roundtrips_writer_output_as_columns() {
        let source = make_table_format_dataframe();
        let xml = write_xml_string(&source).expect("write xml");

        let frame = read_xml_str(&xml).expect("read writer xml");

        assert_eq!(
            frame
                .column_names()
                .into_iter()
                .map(String::as_str)
                .collect::<Vec<_>>(),
            vec!["row", "name", "value"]
        );
        assert_eq!(
            frame.column("row").expect("row").values()[0],
            Scalar::Utf8("r&1".to_owned())
        );
        assert_eq!(
            frame.column("name").expect("name").values()[0],
            Scalar::Utf8("A|B".to_owned())
        );
        assert!(frame.column("value").expect("value").values()[0].is_missing());
        assert_eq!(
            frame.column("value").expect("value").values()[1],
            Scalar::Float64(2.0)
        );
    }

    #[test]
    fn xml_reader_unescapes_text_and_supports_custom_row_names() {
        let xml = concat!(
            "<records>\n",
            "  <entry><name>A&amp;B &lt;tag&gt; \"quote\" it's</name><flag>True</flag></entry>\n",
            "  <entry><name>line\n",
            "next</name><flag>false</flag></entry>\n",
            "</records>\n",
        );

        let frame = read_xml_str_with_options(
            xml,
            &XmlReadOptions {
                row_name: "entry".to_owned(),
            },
        )
        .expect("read custom xml");

        assert_eq!(
            frame.column("name").expect("name").values()[0],
            Scalar::Utf8("A&B <tag> \"quote\" it's".to_owned())
        );
        assert_eq!(
            frame.column("name").expect("name").values()[1],
            Scalar::Utf8("line\nnext".to_owned())
        );
        assert_eq!(
            frame.column("flag").expect("flag").values()[0],
            Scalar::Bool(true)
        );
        assert_eq!(
            frame.column("flag").expect("flag").values()[1],
            Scalar::Bool(false)
        );
    }

    #[test]
    fn xml_reader_path_reader_matches_string_reader() {
        use std::io::Write;

        let xml = "<data><row><name>A</name></row></data>\n";
        let path = std::env::temp_dir().join(format!(
            "fp_io_xml_reader_{}_{}.xml",
            std::process::id(),
            line!()
        ));
        let mut file = std::fs::OpenOptions::new()
            .write(true)
            .create_new(true)
            .open(&path)
            .expect("create xml fixture");
        file.write_all(xml.as_bytes()).expect("write xml fixture");

        let via_path = read_xml(&path).expect("read path xml");
        let via_str = read_xml_str(xml).expect("read string xml");

        assert_eq!(via_path.column_names(), via_str.column_names());
        assert_eq!(
            via_path.column("name").expect("path name").values(),
            via_str.column("name").expect("str name").values()
        );
    }

    #[test]
    fn xml_reader_rejects_malformed_nested_and_duplicate_fields() {
        let malformed = "<data><row><name>A</row></data>";
        assert!(matches!(read_xml_str(malformed), Err(IoError::Xml(_))));

        let nested = "<data><row><name><inner>A</inner></name></row></data>";
        let err = read_xml_str(nested).expect_err("nested field error");
        assert!(matches!(err, IoError::Xml(message) if message.contains("nested xml element")));

        let duplicate = "<data><row><name>A</name><name>B</name></row></data>";
        let err = read_xml_str(duplicate).expect_err("duplicate field error");
        assert!(matches!(err, IoError::Xml(message) if message.contains("duplicate xml field")));
    }

    // === AG-07-T: CSV Parser Optimization Tests ===

    #[test]
    fn test_csv_vec_based_column_order() {
        // Verify Vec-based parser preserves header-to-data mapping exactly.
        // BTreeMap sorts alphabetically, so we use alpha-ordered headers.
        let input = "alpha,bravo,charlie\n1,2,3\n4,5,6\n";
        let frame = read_csv_str(input).expect("parse");
        let keys: Vec<&String> = frame.columns().keys().collect();
        assert_eq!(keys, &["alpha", "bravo", "charlie"]);
        assert_eq!(frame.column("alpha").unwrap().values()[0], Scalar::Int64(1));
        assert_eq!(frame.column("bravo").unwrap().values()[0], Scalar::Int64(2));
        assert_eq!(
            frame.column("charlie").unwrap().values()[1],
            Scalar::Int64(6)
        );
        eprintln!("[TEST] test_csv_vec_based_column_order | rows=2 cols=3 parse_ok=true | PASS");
    }

    #[test]
    fn read_csv_object_fallback_preserves_original_text() {
        // pandas does column-level inference: when a column falls back to object
        // dtype, every non-NA cell keeps its VERBATIM source text. A bool-like
        // token in non-canonical case ("true") or a zero-padded number ("01")
        // must survive unchanged once the column is object. Verified vs live
        // pandas 2.2.3: read_csv('c\ntrue\nfalse\nmaybe\n')['c'] is
        // ['true','false','maybe'] (object), and '01'/'02' stay '01'/'02'.
        let cases: &[(&str, &str)] = &[
            // Uniform native columns are unaffected.
            ("c\n1\n2\n3\n", "c\n1\n2\n3\n"),
            ("c\ntrue\nfalse\n", "c\nTrue\nFalse\n"), // pure bool -> bool dtype
            // Object fallbacks keep original literals.
            ("c\n1\n2\nabc\n", "c\n1\n2\nabc\n"),
            ("c\ntrue\nfalse\nmaybe\n", "c\ntrue\nfalse\nmaybe\n"),
            ("c\nTrue\nFalse\nmaybe\n", "c\nTrue\nFalse\nmaybe\n"),
            ("c\n01\n02\nabc\n", "c\n01\n02\nabc\n"),
        ];
        for (input, expected_csv) in cases {
            let frame = read_csv_str(input).expect("read");
            let out = write_csv_string(&frame).expect("write");
            assert_eq!(
                &out, expected_csv,
                "round-trip mismatch for input {input:?}"
            );
        }
    }

    #[test]
    fn read_csv_typed_numeric_fast_path_promotes_in_one_pass() {
        let input = "i,f\n1,0\n2,0.5\n3,1.25\n";
        let headers = vec!["i".to_owned(), "f".to_owned()];

        let fast = super::try_read_csv_str_typed_numeric(input, &headers)
            .expect("typed parse")
            .expect("numeric fast path");
        assert_eq!(fast.column("i").expect("i").dtype(), DType::Int64);
        assert_eq!(fast.column("f").expect("f").dtype(), DType::Float64);
        assert_eq!(fast.column("i").expect("i").values()[2], Scalar::Int64(3));
        assert_eq!(
            fast.column("f").expect("f").values()[2],
            Scalar::Float64(1.25)
        );

        let object_input = "c\n01\nabc\n";
        let object_headers = vec!["c".to_owned()];
        assert!(
            super::try_read_csv_str_typed_numeric(object_input, &object_headers)
                .expect("object probe")
                .is_none()
        );
        let object_frame = read_csv_str(object_input).expect("fallback read");
        assert_eq!(object_frame.index().int64_unit_range_labels(), Some((0, 2)));
        assert_eq!(
            write_csv_string(&object_frame).expect("fallback write"),
            object_input
        );
    }

    #[test]
    fn read_csv_simple_typed_numeric_fast_path_builds_typed_columns() {
        let input = "i,f\n1,0\n2,0.5\n3,1.25\n";
        let headers = vec!["i".to_owned(), "f".to_owned()];

        let fast = super::try_read_csv_str_simple_typed_numeric(input, &headers)
            .expect("simple typed parse")
            .expect("simple numeric fast path");

        assert_eq!(fast.column("i").expect("i").dtype(), DType::Int64);
        assert_eq!(fast.column("f").expect("f").dtype(), DType::Float64);
        assert_eq!(fast.index().int64_unit_range_labels(), Some((0, 3)));
        assert_eq!(fast.index().labels()[2], IndexLabel::Int64(2));
        assert_eq!(fast.column("i").expect("i").values()[2], Scalar::Int64(3));
        assert_eq!(
            fast.column("f").expect("f").values()[2],
            Scalar::Float64(1.25)
        );
    }

    #[test]
    fn read_csv_simple_typed_numeric_fast_path_rejects_quoted_fields() {
        let input = "x\n\"1.5\"\n";
        let headers = vec!["x".to_owned()];

        assert!(
            super::try_read_csv_str_simple_typed_numeric(input, &headers)
                .expect("simple probe")
                .is_none()
        );

        let frame = read_csv_str(input).expect("fallback read");
        assert_eq!(frame.column("x").expect("x").dtype(), DType::Float64);
        assert_eq!(
            frame.column("x").expect("x").values(),
            &[Scalar::Float64(1.5)]
        );
    }

    #[test]
    fn read_csv_simple_typed_numeric_fast_path_accepts_crlf_rows() {
        let input = "i,f\n1,0\r\n2,0.5\r\n";
        let headers = vec!["i".to_owned(), "f".to_owned()];

        let fast = super::try_read_csv_str_simple_typed_numeric(input, &headers)
            .expect("simple typed parse")
            .expect("simple numeric fast path");

        assert_eq!(fast.len(), 2);
        assert_eq!(fast.column("i").expect("i").values()[1], Scalar::Int64(2));
        assert_eq!(
            fast.column("f").expect("f").values()[1],
            Scalar::Float64(0.5)
        );
    }

    #[test]
    fn read_csv_simple_parallel_chunks_preserve_order_and_promotion() {
        use std::fmt::Write as _;

        let headers = vec!["i".to_owned(), "f".to_owned()];
        let mut data = String::new();
        for row in 0..32 {
            let float_value = row as f64 * 0.25;
            writeln!(data, "{row},{float_value}").expect("write row");
        }

        let (columns, row_count) =
            super::parse_simple_numeric_csv_parallel_chunks(data.as_bytes(), headers.len(), 3)
                .expect("parallel chunk parse");
        let frame = super::build_typed_numeric_csv_frame(&headers, columns, row_count)
            .expect("frame build");

        assert_eq!(frame.len(), 32);
        assert_eq!(frame.column("i").expect("i").dtype(), DType::Int64);
        assert_eq!(frame.column("f").expect("f").dtype(), DType::Float64);
        assert_eq!(frame.column("i").expect("i").values()[0], Scalar::Int64(0));
        assert_eq!(
            frame.column("i").expect("i").values()[31],
            Scalar::Int64(31)
        );
        assert_eq!(
            frame.column("f").expect("f").values()[31],
            Scalar::Float64(7.75)
        );
    }

    #[test]
    fn read_csv_typed_numeric_fast_path_rejects_non_all_valid_numeric_semantics() {
        let headers = vec!["x".to_owned()];
        for input in [
            "x\nNaN\n1.0\n",
            "x\nNAN\n1.0\n",
            "x\n+NaN\n1.0\n",
            "x\n NaN \n1.0\n",
            "x\n\"NAN\"\n1.0\n",
            "x\ntrue\nfalse\n",
            "x\n \n1\n",
        ] {
            assert!(
                super::try_read_csv_str_typed_numeric(input, &headers)
                    .expect("probe")
                    .is_none(),
                "fast path must reject {input:?}"
            );
        }

        let nan_frame = read_csv_str("x\nNaN\n1.0\n").expect("fallback nan");
        assert_eq!(
            nan_frame.column("x").expect("x").values(),
            &[Scalar::Null(NullKind::NaN), Scalar::Float64(1.0)]
        );

        let bool_frame = read_csv_str("x\ntrue\nfalse\n").expect("fallback bool");
        assert_eq!(
            bool_frame.column("x").expect("x").values(),
            &[Scalar::Bool(true), Scalar::Bool(false)]
        );

        let padded_nan_frame = read_csv_str("x\n NaN \n1.0\n").expect("fallback padded nan");
        let padded_nan_column = padded_nan_frame.column("x").expect("x");
        assert!(padded_nan_column.has_nulls());
        assert!(!padded_nan_column.validity().get(0));
        assert!(padded_nan_column.values()[0].is_missing());
    }

    #[test]
    fn read_csv_typed_numeric_fast_path_keeps_all_valid_float_edges() {
        let input = "x\n-0.0\ninf\n-inf\n1\n";
        let headers = vec!["x".to_owned()];
        let frame = super::try_read_csv_str_typed_numeric(input, &headers)
            .expect("typed parse")
            .expect("numeric fast path");
        let column = frame.column("x").expect("x");

        assert_eq!(column.dtype(), DType::Float64);
        assert!(!column.has_nulls());
        assert!(column.validity().all());
        let values = column.values();
        assert_eq!(
            values,
            &[
                Scalar::Float64(-0.0),
                Scalar::Float64(f64::INFINITY),
                Scalar::Float64(f64::NEG_INFINITY),
                Scalar::Float64(1.0)
            ]
        );
        let negative_zero_bits = match values[0] {
            Scalar::Float64(value) => Some(value.to_bits()),
            _ => None,
        };
        assert_eq!(negative_zero_bits, Some((-0.0f64).to_bits()));
    }

    #[test]
    fn read_csv_typed_numeric_fast_path_preserves_ragged_row_errors() {
        let long_row = "a,b\n1,2,3\n";
        let err = read_csv_str(long_row).expect_err("long row must reject");
        assert!(matches!(err, IoError::Csv(_)), "got {err:?}");
    }

    #[test]
    fn to_csv_datetime_is_column_uniform_like_pandas() {
        // pandas to_csv renders a datetime column with ONE format: date-only
        // when all values are midnight, else YYYY-MM-DD HH:MM:SS with a
        // sub-second suffix sized to the column's finest resolution. Verified
        // vs live pandas 2.2.3. (Previously format_datetime_ns dropped the
        // sub-second component and always wrote 00:00:00.)
        fn dt_frame(nanos: &[i64]) -> DataFrame {
            let values: Vec<Scalar> = nanos.iter().map(|&n| Scalar::Datetime64(n)).collect();
            let col = Column::new(DType::Datetime64, values).expect("col");
            let mut cols = BTreeMap::new();
            cols.insert("d".to_string(), col);
            let index = Index::from_i64((0..nanos.len() as i64).collect());
            DataFrame::new_with_column_order(index, cols, vec!["d".to_string()]).expect("frame")
        }
        const MIDNIGHT_JAN1: i64 = 1_577_836_800_000_000_000; // 2020-01-01 00:00:00Z
        const MIDNIGHT_JAN2: i64 = 1_577_923_200_000_000_000; // 2020-01-02 00:00:00Z
        const JAN2_0300: i64 = 1_577_934_000_000_000_000; // 2020-01-02 03:00:00Z
        const JAN1_HALF: i64 = 1_577_836_800_500_000_000; // 2020-01-01 00:00:00.5Z

        // All midnight -> date only.
        assert_eq!(
            write_csv_string(&dt_frame(&[MIDNIGHT_JAN1, MIDNIGHT_JAN2])).expect("w"),
            "d\n2020-01-01\n2020-01-02\n"
        );
        // Sub-second present -> whole column gets .fff (millis), incl. .000.
        assert_eq!(
            write_csv_string(&dt_frame(&[JAN1_HALF, MIDNIGHT_JAN1])).expect("w"),
            "d\n2020-01-01 00:00:00.500\n2020-01-01 00:00:00.000\n"
        );
        // Time present, no sub-second -> HH:MM:SS for all (midnight -> 00:00:00).
        assert_eq!(
            write_csv_string(&dt_frame(&[JAN2_0300, MIDNIGHT_JAN1])).expect("w"),
            "d\n2020-01-02 03:00:00\n2020-01-01 00:00:00\n"
        );
        // NaT in an otherwise date-only column -> date only, NaT -> quoted "".
        assert_eq!(
            write_csv_string(&dt_frame(&[MIDNIGHT_JAN1, i64::MIN])).expect("w"),
            "d\n2020-01-01\n\"\"\n"
        );
    }

    #[test]
    fn to_csv_datetime_index_is_column_uniform_like_pandas() {
        use super::{CsvWriteOptions, write_csv_string_with_options};
        // A DatetimeIndex written with index=True follows the same column-
        // uniform rule as a datetime column. Verified vs live pandas 2.2.3.
        fn dt_index_frame(nanos: &[i64]) -> DataFrame {
            let labels: Vec<IndexLabel> =
                nanos.iter().map(|&n| IndexLabel::Datetime64(n)).collect();
            let index = Index::new(labels);
            let values: Vec<Scalar> = (0..nanos.len() as i64).map(Scalar::Int64).collect();
            let col = Column::new(DType::Int64, values).expect("col");
            let mut cols = BTreeMap::new();
            cols.insert("v".to_string(), col);
            DataFrame::new_with_column_order(index, cols, vec!["v".to_string()]).expect("frame")
        }
        let opts = CsvWriteOptions {
            include_index: true,
            ..Default::default()
        };
        // All midnight -> date only.
        assert_eq!(
            write_csv_string_with_options(
                &dt_index_frame(&[1_577_836_800_000_000_000, 1_577_923_200_000_000_000]),
                &opts
            )
            .expect("w"),
            ",v\n2020-01-01,0\n2020-01-02,1\n"
        );
        // Sub-second (ms) -> .fff on every label.
        assert_eq!(
            write_csv_string_with_options(
                &dt_index_frame(&[1_577_836_800_500_000_000, 1_577_836_800_250_000_000]),
                &opts
            )
            .expect("w"),
            ",v\n2020-01-01 00:00:00.500,0\n2020-01-01 00:00:00.250,1\n"
        );
    }

    #[test]
    fn read_csv_with_options_object_fallback_preserves_text() {
        use super::{CsvReadOptions, read_csv_with_options};
        // Same pandas object-fallback rule on the options reader (custom
        // delimiter / na_values etc.): non-canonical bool casing and zero-padded
        // numbers survive once the column is object. Verified vs pandas 2.2.3.
        let tsv = CsvReadOptions {
            delimiter: b'\t',
            ..Default::default()
        };
        let frame = read_csv_with_options("c\ntrue\nfalse\nmaybe\n", &tsv).expect("read");
        assert_eq!(frame.index().int64_unit_range_labels(), Some((0, 3)));
        let out = write_csv_string(&frame).expect("write");
        assert_eq!(out, "c\ntrue\nfalse\nmaybe\n");

        let frame2 = read_csv_with_options("c\n01\n02\nabc\n", &tsv).expect("read");
        let out2 = write_csv_string(&frame2).expect("write");
        assert_eq!(out2, "c\n01\n02\nabc\n");

        // Pure-bool column still infers bool dtype (writes True/False).
        let frame3 = read_csv_with_options("c\ntrue\nfalse\n", &tsv).expect("read");
        let out3 = write_csv_string(&frame3).expect("write");
        assert_eq!(out3, "c\nTrue\nFalse\n");

        // Custom na_values: an NA cell in an object column stays missing while
        // the surrounding original literals are preserved.
        let na_opts = CsvReadOptions {
            delimiter: b'\t',
            na_values: vec!["MISSING".to_string()],
            ..Default::default()
        };
        let frame4 = read_csv_with_options("c\ntrue\nMISSING\nmaybe\n", &na_opts).expect("read");
        let out4 = write_csv_string(&frame4).expect("write");
        // The lone empty NaN field in a single-column object frame is quoted "".
        assert_eq!(out4, "c\ntrue\n\"\"\nmaybe\n");
    }

    #[test]
    fn to_csv_float_format_matches_pandas_str() {
        // pandas to_csv writes floats via Python str(float): whole numbers keep
        // ".0", decimals use the shortest round-trip, and extreme magnitudes use
        // signed two-digit scientific notation. Verified vs live pandas 2.2.3.
        let cases: &[(f64, &str)] = &[
            (1.0, "1.0"),
            (3.0, "3.0"),
            (100.0, "100.0"),
            (-7.0, "-7.0"),
            (2.5, "2.5"),
            (0.5, "0.5"),
            (0.1, "0.1"),
            (1.0 / 3.0, "0.3333333333333333"),
            (1234567890123456.0, "1234567890123456.0"),
            (1e16, "1e+16"),
            (1e20, "1e+20"),
            (1e-5, "1e-05"),
            (0.0001, "0.0001"),
            (1e-7, "1e-07"),
            (f64::INFINITY, "inf"),
            (f64::NEG_INFINITY, "-inf"),
        ];
        for (v, expected) in cases {
            assert_eq!(
                &format_pandas_float(*v),
                expected,
                "format_pandas_float({v})"
            );
        }
    }

    #[test]
    fn to_csv_single_column_nan_quotes_empty_and_keeps_float_repr() {
        // The lone empty NaN field is already quoted as "" by the csv writer so
        // read_csv doesn't drop it (NOT a blank line). The real fix here is the
        // float repr: 1.0/3.0 must stay "1.0"/"3.0", not collapse to "1"/"3".
        let frame = read_csv_str("x\n1.0\nNaN\n3.0\n").expect("read");
        assert!(frame.column("x").unwrap().values()[1].is_missing());
        let out = write_csv_string(&frame).expect("write");
        assert_eq!(out, "x\n1.0\n\"\"\n3.0\n");
    }

    #[test]
    fn test_csv_capacity_hint_reasonable() {
        // Generate a ~1MB CSV and verify it parses correctly.
        // The capacity hint (input.len / (cols*8)) should avoid excessive reallocs.
        let mut csv = String::with_capacity(1_100_000);
        csv.push_str("a,b,c,d,e\n");
        let target_rows = 50_000; // ~20 bytes/row * 50k ≈ 1MB
        for i in 0..target_rows {
            csv.push_str(&format!("{},{},{},{},{}\n", i, i * 2, i * 3, i * 4, i * 5));
        }
        assert!(csv.len() > 500_000, "CSV should be large");

        let frame = read_csv_str(&csv).expect("parse large CSV");
        assert_eq!(frame.index().len(), target_rows);
        assert_eq!(frame.columns().len(), 5);
        // Spot-check last row
        assert_eq!(
            frame.column("a").unwrap().values()[target_rows - 1],
            Scalar::Int64((target_rows - 1) as i64)
        );
        eprintln!(
            "[TEST] test_csv_capacity_hint_reasonable | rows={target_rows} cols=5 parse_ok=true | PASS"
        );
    }

    #[test]
    fn test_csv_empty_columns() {
        // CSV with headers but no data rows -> empty DataFrame with correct column names.
        let input = "x,y,z\n";
        let frame = read_csv_str(input).expect("parse");
        assert_eq!(frame.index().len(), 0);
        let keys: Vec<&String> = frame.columns().keys().collect();
        assert_eq!(keys, &["x", "y", "z"]);
        for col in frame.columns().values() {
            assert!(col.is_empty());
        }
        eprintln!("[TEST] test_csv_empty_columns | rows=0 cols=3 parse_ok=true | PASS");
    }

    #[test]
    fn test_csv_comment_skips_lines() {
        let input = "# header comment\nname,age\n# inline comment\nalice,30\nbob,25\n";
        let options = CsvReadOptions {
            comment: Some(b'#'),
            ..CsvReadOptions::default()
        };
        let frame = read_csv_with_options(input, &options).expect("parse");
        assert_eq!(frame.index().len(), 2);
        let names: Vec<&String> = frame.column_names().into_iter().collect();
        assert_eq!(names, vec!["name", "age"]);
        assert_eq!(
            frame.column("name").unwrap().values()[0],
            Scalar::Utf8("alice".to_string())
        );
        assert_eq!(frame.column("age").unwrap().values()[1], Scalar::Int64(25));
    }

    #[test]
    fn test_csv_comment_none_preserves_comment_lines() {
        // Without comment set, a leading "#"-line should become part of parsing
        // (and fail as duplicate/missing-headers or be treated as data).
        let input = "name,age\nalice,30\n";
        let frame = read_csv_with_options(input, &CsvReadOptions::default()).expect("parse");
        assert_eq!(frame.index().len(), 1);
    }

    #[test]
    fn read_csv_with_default_options_matches_read_csv_str() {
        for input in [
            "i,f,s\n1,2.5,abc\n3,4.0,def\n",
            "flag\ntrue\nfalse\nmaybe\n",
        ] {
            let expected = read_csv_str(input).expect("default read");
            let actual =
                read_csv_with_options(input, &CsvReadOptions::default()).expect("options read");

            assert_eq!(actual.index().len(), expected.index().len());
            assert_eq!(actual.column_names(), expected.column_names());
            for name in expected.column_names() {
                let expected_col = expected.column(name).expect("expected column");
                let actual_col = actual.column(name).expect("actual column");
                assert_eq!(actual_col.dtype(), expected_col.dtype());
                assert_eq!(actual_col.values(), expected_col.values());
            }
        }
    }

    #[test]
    fn read_csv_str_cache_reuses_exact_successful_input() {
        let input = "x,y\n1,2.5\n3,4.5\n";

        let first = read_csv_str(input).expect("first parse");
        let second = read_csv_str(input).expect("cached parse");

        assert_eq!(second.index().len(), first.index().len());
        assert_eq!(second.column_names(), first.column_names());
        for name in first.column_names() {
            let first_col = first.column(name).expect("first column");
            let second_col = second.column(name).expect("second column");
            assert_eq!(second_col.dtype(), first_col.dtype());
            assert_eq!(second_col.values(), first_col.values());
        }
    }

    #[test]
    fn read_csv_str_cache_is_content_addressed() {
        let mut input = String::from("x\n1\n2\n");
        let first = read_csv_str(&input).expect("first parse");
        assert_eq!(first.column("x").unwrap().values()[0], Scalar::Int64(1));

        input.clear();
        input.push_str("x\n9\n10\n");
        let second = read_csv_str(&input).expect("changed-content parse");

        assert_eq!(second.index().len(), 2);
        assert_eq!(second.column("x").unwrap().values()[0], Scalar::Int64(9));
        assert_eq!(second.column("x").unwrap().values()[1], Scalar::Int64(10));
    }

    #[test]
    fn read_csv_no_na_cache_reuses_exact_successful_input() {
        let options = CsvReadOptions {
            na_filter: false,
            ..CsvReadOptions::default()
        };
        let input = "x,y\n1,2.5\n3,4.5\n";

        let first = read_csv_with_options(input, &options).expect("first no-na parse");
        let second = read_csv_with_options(input, &options).expect("cached no-na parse");

        assert_eq!(second.index().len(), first.index().len());
        assert_eq!(second.column_names(), first.column_names());
        for name in first.column_names() {
            let first_col = first.column(name).expect("first column");
            let second_col = second.column(name).expect("second column");
            assert_eq!(second_col.dtype(), first_col.dtype());
            assert_eq!(second_col.values(), first_col.values());
        }
    }

    #[test]
    fn csv_parse_cache_keeps_default_and_no_na_modes_separate() {
        let input = "mode_sep_a,mode_sep_b\n11,12.5\n13,14.5\n";
        let no_na_options = CsvReadOptions {
            na_filter: false,
            ..CsvReadOptions::default()
        };

        let no_na_frame = read_csv_with_options(input, &no_na_options).expect("no-na parse");
        assert!(super::csv_parse_cache_lookup(super::CsvParseCacheMode::Default, input).is_none());
        assert!(
            super::csv_parse_cache_lookup(super::CsvParseCacheMode::NoNaNumeric, input).is_some()
        );

        let default_frame = read_csv_str(input).expect("default parse");
        let default_cached =
            super::csv_parse_cache_lookup(super::CsvParseCacheMode::Default, input)
                .expect("default cache entry");
        let no_na_cached =
            super::csv_parse_cache_lookup(super::CsvParseCacheMode::NoNaNumeric, input)
                .expect("no-na cache entry");

        assert_eq!(default_cached.column_names(), default_frame.column_names());
        assert_eq!(no_na_cached.column_names(), no_na_frame.column_names());
        assert_eq!(
            default_cached.column("mode_sep_b").unwrap().values(),
            default_frame.column("mode_sep_b").unwrap().values()
        );
        assert_eq!(
            no_na_cached.column("mode_sep_b").unwrap().values(),
            no_na_frame.column("mode_sep_b").unwrap().values()
        );
    }

    #[test]
    fn csv_default_options_fast_path_excludes_behavioral_options() {
        assert!(super::csv_read_options_match_default_fast_path(
            &CsvReadOptions::default()
        ));

        for options in [
            CsvReadOptions {
                delimiter: b'\t',
                ..CsvReadOptions::default()
            },
            CsvReadOptions {
                na_filter: false,
                ..CsvReadOptions::default()
            },
            CsvReadOptions {
                nrows: Some(1),
                ..CsvReadOptions::default()
            },
            CsvReadOptions {
                comment: Some(b'#'),
                ..CsvReadOptions::default()
            },
            CsvReadOptions {
                thousands: Some(b','),
                ..CsvReadOptions::default()
            },
        ] {
            assert!(!super::csv_read_options_match_default_fast_path(&options));
        }
    }

    #[test]
    fn read_csv_no_na_filter_numeric_fast_path_preserves_numeric_columns() {
        let options = CsvReadOptions {
            na_filter: false,
            ..CsvReadOptions::default()
        };
        assert!(super::csv_read_options_match_no_na_numeric_fast_path(
            &options
        ));

        let frame = read_csv_with_options("i,f\n1,2.5\n3,4\n", &options).expect("parse");
        assert_eq!(frame.len(), 2);
        assert_eq!(frame.column("i").expect("i").dtype(), DType::Int64);
        assert_eq!(frame.column("f").expect("f").dtype(), DType::Float64);
        assert_eq!(frame.column("i").expect("i").values()[1], Scalar::Int64(3));
        assert_eq!(
            frame.column("f").expect("f").values()[0],
            Scalar::Float64(2.5)
        );
    }

    #[test]
    fn read_csv_no_na_filter_fast_path_falls_back_for_empty_field() {
        let options = CsvReadOptions {
            na_filter: false,
            ..CsvReadOptions::default()
        };
        let frame = read_csv_with_options("x,y\n1,\n2,3\n", &options).expect("parse");
        let y = frame.column("y").expect("y");

        assert_eq!(y.dtype(), DType::Utf8);
        assert_eq!(y.values()[0], Scalar::Utf8(String::new()));
        assert_eq!(y.values()[1], Scalar::Utf8("3".to_owned()));
    }

    #[test]
    fn test_csv_comment_custom_char() {
        let input = "% this is ignored\nname,age\nalice,30\n";
        let options = CsvReadOptions {
            comment: Some(b'%'),
            ..CsvReadOptions::default()
        };
        let frame = read_csv_with_options(input, &options).expect("parse");
        assert_eq!(frame.index().len(), 1);
        assert_eq!(
            frame.column("name").unwrap().values()[0],
            Scalar::Utf8("alice".to_string())
        );
    }

    #[test]
    fn test_csv_thousands_strips_int_separator() {
        let input = "amount\n\"1,234,567\"\n\"42\"\n";
        let options = CsvReadOptions {
            thousands: Some(b','),
            ..CsvReadOptions::default()
        };
        let frame = read_csv_with_options(input, &options).expect("parse");
        assert_eq!(
            frame.column("amount").unwrap().values()[0],
            Scalar::Int64(1234567)
        );
        assert_eq!(
            frame.column("amount").unwrap().values()[1],
            Scalar::Int64(42)
        );
    }

    #[test]
    fn test_csv_thousands_strips_float_with_custom_decimal() {
        // European convention: '.' as thousands, ',' as decimal.
        let input = "price\n\"1.234,56\"\n";
        let options = CsvReadOptions {
            thousands: Some(b'.'),
            decimal: b',',
            ..CsvReadOptions::default()
        };
        let frame = read_csv_with_options(input, &options).expect("parse");
        let v = frame.column("price").unwrap().values()[0].clone();
        assert!(matches!(v, Scalar::Float64(_)), "expected Float64");
        let Scalar::Float64(f) = v else { return };
        assert!((f - 1234.56).abs() < 1e-9);
    }

    #[test]
    fn test_csv_thousands_none_keeps_separator_as_string() {
        // Without thousands set, "1,234" in a single field stays Utf8.
        let input = "amount\n\"1,234\"\n";
        let frame = read_csv_with_options(input, &CsvReadOptions::default()).expect("parse");
        assert_eq!(
            frame.column("amount").unwrap().values()[0],
            Scalar::Utf8("1,234".to_string())
        );
    }

    #[test]
    fn test_csv_thousands_equal_to_decimal_is_ignored() {
        // pandas silently ignores thousands if it equals decimal.
        let input = "v\n\"1.234\"\n";
        let options = CsvReadOptions {
            thousands: Some(b'.'),
            decimal: b'.',
            ..CsvReadOptions::default()
        };
        let frame = read_csv_with_options(input, &options).expect("parse");
        let v = frame.column("v").unwrap().values()[0].clone();
        // thousands ignored → "1.234" parses as float 1.234
        assert!(matches!(v, Scalar::Float64(_)), "expected Float64");
        let Scalar::Float64(f) = v else { return };
        assert!((f - 1.234).abs() < 1e-9);
    }

    #[test]
    fn test_csv_thousands_does_not_affect_non_numeric() {
        let input = "name\n\"a,b\"\n";
        let options = CsvReadOptions {
            thousands: Some(b','),
            ..CsvReadOptions::default()
        };
        let frame = read_csv_with_options(input, &options).expect("parse");
        assert_eq!(
            frame.column("name").unwrap().values()[0],
            Scalar::Utf8("a,b".to_string())
        );
    }

    #[test]
    fn test_csv_quotechar_custom_single_quote() {
        let input = "name,remark\n'alice','loves, cats'\n";
        let options = CsvReadOptions {
            quotechar: b'\'',
            ..CsvReadOptions::default()
        };
        let frame = read_csv_with_options(input, &options).expect("parse");
        assert_eq!(
            frame.column("name").unwrap().values()[0],
            Scalar::Utf8("alice".to_string())
        );
        assert_eq!(
            frame.column("remark").unwrap().values()[0],
            Scalar::Utf8("loves, cats".to_string())
        );
    }

    #[test]
    fn test_csv_doublequote_true_collapses_doubled_quotes() {
        // The field is `she said ""hi""` with doubled inner quotes.
        let input = "text\n\"she said \"\"hi\"\"\"\n";
        let frame = read_csv_with_options(input, &CsvReadOptions::default()).expect("parse");
        assert_eq!(
            frame.column("text").unwrap().values()[0],
            Scalar::Utf8("she said \"hi\"".to_string())
        );
    }

    #[test]
    fn test_csv_doublequote_false_requires_escapechar() {
        // With doublequote=false and escapechar=\, \" escapes the quote.
        let input = "text\n\"hi\\\"there\"\n";
        let options = CsvReadOptions {
            doublequote: false,
            escapechar: Some(b'\\'),
            ..CsvReadOptions::default()
        };
        let frame = read_csv_with_options(input, &options).expect("parse");
        assert_eq!(
            frame.column("text").unwrap().values()[0],
            Scalar::Utf8("hi\"there".to_string())
        );
    }

    #[test]
    fn test_csv_lineterminator_semicolon() {
        // Single-byte record separator '|'. No newlines in the data.
        let input = "a,b|1,x|2,y|3,z";
        let options = CsvReadOptions {
            lineterminator: Some(b'|'),
            ..CsvReadOptions::default()
        };
        let frame = read_csv_with_options(input, &options).expect("parse");
        assert_eq!(frame.index().len(), 3);
        assert_eq!(frame.column_names(), vec!["a", "b"]);
        assert_eq!(frame.column("a").unwrap().values()[2], Scalar::Int64(3));
    }

    #[test]
    fn test_csv_lineterminator_default_none_accepts_crlf() {
        let input = "a,b\r\n1,x\r\n2,y\r\n";
        let frame = read_csv_with_options(input, &CsvReadOptions::default()).expect("parse");
        assert_eq!(frame.index().len(), 2);
    }

    #[test]
    fn test_csv_lineterminator_interacts_with_skipfooter() {
        let input = "a|1|2|3|4|FOOTER";
        let options = CsvReadOptions {
            lineterminator: Some(b'|'),
            skipfooter: 1,
            ..CsvReadOptions::default()
        };
        let frame = read_csv_with_options(input, &options).expect("parse");
        // 5 data rows after header, footer drops 1 → 4 rows.
        assert_eq!(frame.index().len(), 4);
    }

    #[test]
    fn test_csv_skipfooter_drops_trailing_rows() {
        let input = "a,b\n1,x\n2,y\n3,z\nTOTAL,summary\n";
        let options = CsvReadOptions {
            skipfooter: 1,
            ..CsvReadOptions::default()
        };
        let frame = read_csv_with_options(input, &options).expect("parse");
        assert_eq!(frame.index().len(), 3);
        assert_eq!(frame.column("a").unwrap().values()[2], Scalar::Int64(3));
    }

    #[test]
    fn test_csv_skipfooter_zero_is_noop() {
        let input = "a,b\n1,x\n2,y\n";
        let frame_default =
            read_csv_with_options(input, &CsvReadOptions::default()).expect("parse");
        let options = CsvReadOptions {
            skipfooter: 0,
            ..CsvReadOptions::default()
        };
        let frame_zero = read_csv_with_options(input, &options).expect("parse");
        assert_eq!(frame_default.index().len(), frame_zero.index().len());
    }

    #[test]
    fn test_csv_skipfooter_larger_than_data_clears_rows() {
        let input = "a,b\n1,x\n2,y\n";
        let options = CsvReadOptions {
            skipfooter: 10,
            ..CsvReadOptions::default()
        };
        let frame = read_csv_with_options(input, &options).expect("parse");
        assert_eq!(frame.index().len(), 0);
        // Columns and headers are still preserved.
        assert_eq!(frame.column_names().len(), 2);
    }

    #[test]
    fn test_csv_skipfooter_with_nrows() {
        // nrows caps read to 4, then skipfooter drops last 1 → 3 rows.
        let input = "a\n1\n2\n3\n4\n5\n";
        let options = CsvReadOptions {
            nrows: Some(4),
            skipfooter: 1,
            ..CsvReadOptions::default()
        };
        let frame = read_csv_with_options(input, &options).expect("parse");
        assert_eq!(frame.index().len(), 3);
    }

    #[test]
    fn test_csv_escapechar_none_default_keeps_backslash_literal() {
        // Without escapechar set, backslash is just a normal character.
        let input = "text\n\"foo\\bar\"\n";
        let frame = read_csv_with_options(input, &CsvReadOptions::default()).expect("parse");
        assert_eq!(
            frame.column("text").unwrap().values()[0],
            Scalar::Utf8("foo\\bar".to_string())
        );
    }

    #[test]
    fn test_csv_single_column() {
        // CSV with one column, many rows -> correct parsing.
        let mut csv = String::from("value\n");
        for i in 0..500 {
            csv.push_str(&format!("{}\n", i));
        }
        let frame = read_csv_str(&csv).expect("parse");
        assert_eq!(frame.index().len(), 500);
        assert_eq!(frame.columns().len(), 1);
        assert_eq!(
            frame.column("value").unwrap().values()[499],
            Scalar::Int64(499)
        );
        eprintln!("[TEST] test_csv_single_column | rows=500 cols=1 parse_ok=true | PASS");
    }

    #[test]
    fn test_csv_many_columns() {
        // CSV with 100+ columns -> all columns present, correct values.
        let col_count = 120;
        let headers: Vec<String> = (0..col_count).map(|i| format!("c{i:03}")).collect();
        let mut csv = headers.join(",");
        csv.push('\n');
        // 3 data rows
        for row in 0..3 {
            let vals: Vec<String> = (0..col_count)
                .map(|c| format!("{}", row * 1000 + c))
                .collect();
            csv.push_str(&vals.join(","));
            csv.push('\n');
        }
        let frame = read_csv_str(&csv).expect("parse");
        assert_eq!(frame.columns().len(), col_count);
        assert_eq!(frame.index().len(), 3);
        // Spot-check: c000 row 0 = 0, c119 row 2 = 2119
        assert_eq!(frame.column("c000").unwrap().values()[0], Scalar::Int64(0));
        assert_eq!(
            frame.column("c119").unwrap().values()[2],
            Scalar::Int64(2119)
        );
        eprintln!("[TEST] test_csv_many_columns | rows=3 cols={col_count} parse_ok=true | PASS");
    }

    #[test]
    fn test_csv_mixed_dtypes() {
        // Columns with uniform int/float/string/bool/null -> correct type inference.
        let input = "ints,floats,strings,bools,nulls\n\
                     1,1.5,hello,true,\n\
                     2,2.7,world,false,\n\
                     3,3.14,foo,true,\n";
        let frame = read_csv_str(input).expect("parse");

        let ints = frame.column("ints").unwrap();
        assert_eq!(ints.values()[0], Scalar::Int64(1));

        let floats = frame.column("floats").unwrap();
        assert_eq!(floats.values()[1], Scalar::Float64(2.7));

        let strings = frame.column("strings").unwrap();
        assert_eq!(strings.values()[2], Scalar::Utf8("foo".to_owned()));

        let bools = frame.column("bools").unwrap();
        assert_eq!(bools.values()[0], Scalar::Bool(true));
        assert_eq!(bools.values()[1], Scalar::Bool(false));

        // "nulls" column is all empty -> all null/NaN
        let nulls = frame.column("nulls").unwrap();
        for v in nulls.values() {
            assert!(v.is_missing(), "null column values should be missing");
        }
        eprintln!(
            "[TEST] test_csv_mixed_dtypes | rows=3 cols=5 parse_ok=true | dtype_per_col=[int64,float64,utf8,bool,null] | PASS"
        );
    }

    #[test]
    fn test_csv_unicode_headers() {
        // CSV with unicode header names -> correct column names.
        let input = "名前,Größe,café\nAlice,170,latte\nBob,180,espresso\n";
        let frame = read_csv_str(input).expect("parse");
        assert!(frame.column("名前").is_some());
        assert!(frame.column("Größe").is_some());
        assert!(frame.column("café").is_some());
        assert_eq!(
            frame.column("名前").unwrap().values()[0],
            Scalar::Utf8("Alice".to_owned())
        );
        eprintln!("[TEST] test_csv_unicode_headers | rows=2 cols=3 parse_ok=true | PASS");
    }

    #[test]
    fn test_csv_quoted_fields() {
        // CSV with quoted fields containing commas and newlines -> correct parsing.
        let input =
            "name,address\n\"Smith, John\",\"123 Main St\nApt 4\"\nJane,\"456 Oak, Suite 1\"\n";
        let frame = read_csv_str(input).expect("parse");
        assert_eq!(frame.index().len(), 2);
        assert_eq!(
            frame.column("name").unwrap().values()[0],
            Scalar::Utf8("Smith, John".to_owned())
        );
        // Quoted field with embedded newline
        let addr0 = &frame.column("address").unwrap().values()[0];
        assert!(
            matches!(addr0, Scalar::Utf8(s) if s.contains('\n')),
            "expected Utf8 containing embedded newline, got {addr0:?}"
        );
        eprintln!("[TEST] test_csv_quoted_fields | rows=2 cols=2 parse_ok=true | PASS");
    }

    #[test]
    fn test_csv_trailing_newline() {
        // CSV with/without trailing newline -> identical DataFrame.
        let with = "a,b\n1,2\n3,4\n";
        let without = "a,b\n1,2\n3,4";
        let f1 = read_csv_str(with).expect("with newline");
        let f2 = read_csv_str(without).expect("without newline");

        assert_eq!(f1.index().len(), f2.index().len());
        assert_eq!(f1.columns().len(), f2.columns().len());
        for key in f1.columns().keys() {
            let c1 = f1.column(key).unwrap();
            let c2 = f2.column(key).unwrap();
            assert_eq!(c1.values(), c2.values(), "column {key} mismatch");
        }
        eprintln!("[TEST] test_csv_trailing_newline | rows=2 cols=2 parse_ok=true | PASS");
    }

    #[test]
    fn test_csv_round_trip_unchanged() {
        // read_csv_str then write_csv_string produces semantically equivalent output.
        let input = "id,name,score\n1,Alice,95.5\n2,Bob,87\n3,,100\n";
        let frame = read_csv_str(input).expect("read");
        let output = write_csv_string(&frame).expect("write");
        // Re-parse the output and compare
        let frame2 = read_csv_str(&output).expect("re-read");
        assert_eq!(frame.index().len(), frame2.index().len());
        for key in frame.columns().keys() {
            let c1 = frame.column(key).unwrap();
            let c2 = frame2.column(key).unwrap();
            assert!(
                c1.semantic_eq(c2),
                "column {key} not semantically equal after round-trip"
            );
        }
        eprintln!("[TEST] test_csv_round_trip_unchanged | rows=3 cols=3 parse_ok=true | PASS");
    }

    #[test]
    fn test_write_csv_options_custom_delimiter() {
        let input = "a,b\n1,x\n2,y\n";
        let frame = read_csv_str(input).expect("read");
        let output = write_csv_string_with_options(
            &frame,
            &CsvWriteOptions {
                delimiter: b';',
                ..CsvWriteOptions::default()
            },
        )
        .expect("write");
        assert!(output.starts_with("a;b\n"));
        assert!(output.contains("1;x\n"));
        assert!(output.contains("2;y\n"));
    }

    #[test]
    fn test_write_csv_options_na_rep_replaces_nulls() {
        let input = "id,name\n1,Alice\n2,\n";
        let frame = read_csv_str(input).expect("read");
        let output = write_csv_string_with_options(
            &frame,
            &CsvWriteOptions {
                na_rep: "NA".to_string(),
                ..CsvWriteOptions::default()
            },
        )
        .expect("write");
        // Second data row's name should render as NA, not empty.
        assert!(output.contains("2,NA\n"));
        assert!(!output.contains("2,\n"));
    }

    #[test]
    fn test_write_csv_options_header_false_omits_header_row() {
        let input = "a,b\n1,2\n";
        let frame = read_csv_str(input).expect("read");
        let output = write_csv_string_with_options(
            &frame,
            &CsvWriteOptions {
                header: false,
                ..CsvWriteOptions::default()
            },
        )
        .expect("write");
        assert_eq!(output, "1,2\n");
    }

    #[test]
    fn test_write_csv_options_include_index_and_index_label() {
        let input = "a,b\n1,2\n3,4\n";
        let frame = read_csv_str(input).expect("read");
        let output = write_csv_string_with_options(
            &frame,
            &CsvWriteOptions {
                include_index: true,
                index_label: Some("row_id".to_string()),
                ..CsvWriteOptions::default()
            },
        )
        .expect("write");

        assert_eq!(output, "row_id,a,b\n0,1,2\n1,3,4\n");
    }

    #[test]
    fn test_write_csv_options_include_index_uses_named_index_when_label_omitted() {
        let mut cols = std::collections::BTreeMap::new();
        cols.insert(
            "a".to_string(),
            Column::from_values(vec![Scalar::Int64(10), Scalar::Int64(20)]).unwrap(),
        );
        let frame = DataFrame::new_with_column_order(
            Index::from_i64(vec![100, 200]).set_name("sample_id"),
            cols,
            vec!["a".to_string()],
        )
        .unwrap();

        let output = write_csv_string_with_options(
            &frame,
            &CsvWriteOptions {
                include_index: true,
                ..CsvWriteOptions::default()
            },
        )
        .expect("write");

        assert_eq!(output, "sample_id,a\n100,10\n200,20\n");
    }

    #[test]
    fn test_write_csv_options_include_index_label_overrides_index_name() {
        let mut cols = std::collections::BTreeMap::new();
        cols.insert(
            "a".to_string(),
            Column::from_values(vec![Scalar::Int64(10), Scalar::Int64(20)]).unwrap(),
        );
        let frame = DataFrame::new_with_column_order(
            Index::from_i64(vec![100, 200]).set_name("sample_id"),
            cols,
            vec!["a".to_string()],
        )
        .unwrap();

        let output = write_csv_string_with_options(
            &frame,
            &CsvWriteOptions {
                include_index: true,
                index_label: Some("row".to_string()),
                ..CsvWriteOptions::default()
            },
        )
        .expect("write");

        assert_eq!(output, "row,a\n100,10\n200,20\n");
    }

    #[test]
    fn test_csv_multiindex_roundtrip_with_explicit_index_cols() {
        let frame = make_row_multiindex_test_dataframe();
        let csv = write_csv_string_with_options(
            &frame,
            &CsvWriteOptions {
                include_index: true,
                ..CsvWriteOptions::default()
            },
        )
        .expect("write");

        let roundtrip = read_csv_with_index_cols(
            &csv,
            &CsvReadOptions::default(),
            &["region", "product", "year"],
        )
        .expect("read");

        assert!(roundtrip.equals(&frame));
        assert_eq!(roundtrip.row_multiindex(), frame.row_multiindex());
    }

    #[test]
    fn test_write_csv_options_default_matches_write_csv_string() {
        let input = "a,b\n1,2\n3,4\n";
        let frame = read_csv_str(input).expect("read");
        let default_output = write_csv_string(&frame).expect("write");
        let options_output =
            write_csv_string_with_options(&frame, &CsvWriteOptions::default()).expect("write");
        assert_eq!(default_output, options_output);
    }

    #[test]
    fn test_write_csv_options_na_rep_with_float_nan() {
        // Generate a frame with an explicit NaN float.
        use fp_columnar::Column;
        let mut cols = std::collections::BTreeMap::new();
        cols.insert(
            "score".to_string(),
            Column::from_values(vec![Scalar::Float64(1.5), Scalar::Float64(f64::NAN)]).unwrap(),
        );
        let frame = DataFrame::new_with_column_order(
            Index::from_i64(vec![0, 1]),
            cols,
            vec!["score".to_string()],
        )
        .unwrap();
        let output = write_csv_string_with_options(
            &frame,
            &CsvWriteOptions {
                na_rep: "NaN".to_string(),
                ..CsvWriteOptions::default()
            },
        )
        .expect("write");
        assert!(output.contains("NaN"));
    }

    #[test]
    fn test_csv_large_file_perf() {
        // 100K-row, 10-column CSV -> parse completes, correct row/column counts.
        let col_count = 10;
        let row_count = 100_000;
        let headers: Vec<String> = (0..col_count).map(|i| format!("col{i}")).collect();
        let mut csv = String::with_capacity(row_count * 50);
        csv.push_str(&headers.join(","));
        csv.push('\n');
        for r in 0..row_count {
            for c in 0..col_count {
                if c > 0 {
                    csv.push(',');
                }
                csv.push_str(&(r * col_count + c).to_string());
            }
            csv.push('\n');
        }

        let frame = read_csv_str(&csv).expect("parse 100K rows");
        assert_eq!(frame.index().len(), row_count);
        assert_eq!(frame.columns().len(), col_count);
        // Spot-check first and last rows
        assert_eq!(frame.column("col0").unwrap().values()[0], Scalar::Int64(0));
        assert_eq!(
            frame.column("col9").unwrap().values()[row_count - 1],
            Scalar::Int64(((row_count - 1) * col_count + 9) as i64)
        );
        eprintln!(
            "[TEST] test_csv_large_file_perf | rows={row_count} cols={col_count} parse_ok=true | PASS"
        );
    }

    #[test]
    fn test_csv_golden_output() {
        // Fixed CSV input -> write_csv_string output matches golden reference exactly.
        let input = "a,b,c\n1,hello,3.14\n2,,true\n3,world,\n";
        let frame = read_csv_str(input).expect("parse");
        let output = write_csv_string(&frame).expect("write");

        // Golden reference: columns in BTreeMap order; Bool(true) coerced to Float64
        // in column c (which has Float64 + Bool → Float64), so true → 1.0. A Float64
        // column writes whole values with a trailing ".0" like pandas (str(float)).
        let expected = "a,b,c\n1,hello,3.14\n2,,1.0\n3,world,\n";
        assert_eq!(
            output, expected,
            "output does not match golden reference.\nGot:\n{output}\nExpected:\n{expected}"
        );
        eprintln!("[TEST] test_csv_golden_output | golden_match=true | PASS");
    }

    // === bd-2gi.19: IO Complete Contract Tests ===

    use super::{CsvOnBadLines, CsvReadOptions, read_csv_with_options};

    #[test]
    fn csv_with_custom_delimiter() {
        let input = "a\tb\tc\n1\t2\t3\n4\t5\t6\n";
        let opts = CsvReadOptions {
            delimiter: b'\t',
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse tsv");
        assert_eq!(frame.index().len(), 2);
        assert_eq!(frame.column("a").unwrap().values()[0], Scalar::Int64(1));
    }

    #[test]
    fn csv_without_headers_generates_default_names_and_keeps_first_row() {
        let input = "1,2\n3,4\n";
        let opts = CsvReadOptions {
            has_headers: false,
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        assert_eq!(frame.index().len(), 2);
        assert_eq!(
            frame.column("column_0").unwrap().values()[0],
            Scalar::Int64(1)
        );
        assert_eq!(
            frame.column("column_1").unwrap().values()[0],
            Scalar::Int64(2)
        );
        assert_eq!(
            frame.column("column_0").unwrap().values()[1],
            Scalar::Int64(3)
        );
        assert_eq!(
            frame.column("column_1").unwrap().values()[1],
            Scalar::Int64(4)
        );
    }

    #[test]
    fn csv_usecols_missing_column_errors() {
        let input = "a,b\n1,2\n";
        let opts = CsvReadOptions {
            usecols: Some(vec!["c".to_string()]),
            ..Default::default()
        };
        let err = read_csv_with_options(input, &opts).expect_err("missing usecols");
        assert!(
            matches!(err, IoError::MissingUsecols(missing) if missing == vec!["c".to_string()])
        );
    }

    #[test]
    fn csv_without_headers_supports_generated_index_col_name() {
        let input = "10,alpha\n20,beta\n";
        let opts = CsvReadOptions {
            has_headers: false,
            index_col: Some("column_0".into()),
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        assert_eq!(frame.index().len(), 2);
        assert_eq!(frame.index().labels()[0], IndexLabel::Int64(10));
        assert_eq!(frame.index().labels()[1], IndexLabel::Int64(20));
        assert!(frame.column("column_0").is_none());
        assert_eq!(
            frame.column("column_1").unwrap().values()[0],
            Scalar::Utf8("alpha".into())
        );
        assert_eq!(
            frame.column("column_1").unwrap().values()[1],
            Scalar::Utf8("beta".into())
        );
    }

    #[test]
    fn csv_with_na_values() {
        let input = "a,b\n1,NA\n2,n/a\n3,valid\n";
        let opts = CsvReadOptions {
            na_values: vec!["NA".into(), "n/a".into()],
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        let b = frame.column("b").unwrap();
        assert!(b.values()[0].is_missing());
        assert!(b.values()[1].is_missing());
        assert_eq!(b.values()[2], Scalar::Utf8("valid".into()));
    }

    #[test]
    fn csv_none_is_default_na() {
        // "None" is a pandas default NA value (Python's None)
        let input = "a,b\n1,None\n2,valid\n";
        let frame = read_csv_str(input).expect("parse");
        let b = frame.column("b").unwrap();
        assert!(b.values()[0].is_missing(), "None should be parsed as NA");
        assert_eq!(b.values()[1], Scalar::Utf8("valid".into()));
    }

    #[test]
    fn csv_scalar_inference_matches_pandas_2_2_3() {
        // Per-cell type inference verified against pandas 2.2.3 read_csv.
        let cell = |csv: &str| {
            let frame = read_csv_str(&format!("x\n{csv}\n")).expect("parse");
            frame.column("x").unwrap().values()[0].clone()
        };
        // Signed / leading-zero integers parse as Int64 (Rust + pandas agree).
        assert_eq!(cell("+1"), Scalar::Int64(1));
        assert_eq!(cell("01"), Scalar::Int64(1));
        assert_eq!(cell("-5"), Scalar::Int64(-5));
        // Scientific notation is float64 in pandas.
        assert_eq!(cell("1e3"), Scalar::Float64(1000.0));
        // inf / -inf are float values (NOT default-NA tokens, unlike nan).
        assert_eq!(cell("inf"), Scalar::Float64(f64::INFINITY));
        assert_eq!(cell("-inf"), Scalar::Float64(f64::NEG_INFINITY));
        // Bool inference is case-insensitive in pandas 2.2.3.
        assert_eq!(cell("TRUE"), Scalar::Bool(true));
        assert_eq!(cell("true"), Scalar::Bool(true));
        assert_eq!(cell("False"), Scalar::Bool(false));
        // Surrounding whitespace is trimmed ONLY for numeric inference.
        assert_eq!(cell(" 1 "), Scalar::Int64(1));
        assert_eq!(cell("  3.5  "), Scalar::Float64(3.5));
        // Non-numeric, non-bool stays Utf8.
        assert_eq!(cell("hello"), Scalar::Utf8("hello".into()));
        // NA markers, booleans, and plain strings keep their surrounding
        // whitespace — a padded value is a STRING, not null/bool. Verified vs
        // live pandas 2.2.3: " abc "/"true "/" NA " all stay object strings.
        assert_eq!(cell(" abc "), Scalar::Utf8(" abc ".into()));
        assert_eq!(cell("true "), Scalar::Utf8("true ".into()));
        assert_eq!(cell(" True "), Scalar::Utf8(" True ".into()));
        assert_eq!(cell(" NA "), Scalar::Utf8(" NA ".into()));
        assert!(!matches!(cell(" NA "), Scalar::Null(_)));
    }

    #[test]
    fn json_write_non_finite_floats_as_null_like_pandas() {
        // pandas to_json(orient="records") converts inf / -inf / NaN to JSON
        // `null` (JSON has no inf/nan literals). Verified vs pandas 2.2.3:
        // read_csv("x\n1.5\ninf\n-inf\n").to_json(orient="records")
        //   == [{"x":1.5},{"x":null},{"x":null}]
        let frame = read_csv_str("x\n1.5\ninf\n-inf\n").expect("parse");
        let json = write_json_string(&frame, JsonOrient::Records).expect("json");
        assert_eq!(json, r#"[{"x":1.5},{"x":null},{"x":null}]"#);
    }

    #[test]
    fn csv_default_na_token_set_matches_pandas_table() {
        let default_tokens = [
            "", "#N/A", "#N/A N/A", "#NA", "-1.#IND", "-1.#QNAN", "-NaN", "-nan", "1.#IND",
            "1.#QNAN", "<NA>", "N/A", "NA", "NULL", "NaN", "None", "n/a", "nan", "null",
        ];
        for token in default_tokens {
            assert!(super::is_pandas_default_na(token), "{token:?}");
        }

        for token in ["none", "NAN", "n/a ", " NULL", "0", "false"] {
            assert!(!super::is_pandas_default_na(token), "{token:?}");
        }
    }

    #[test]
    fn csv_keep_default_na_false() {
        // With keep_default_na=false, only custom na_values are recognized
        let input = "a,b\n1,NA\n2,CUSTOM\n3,valid\n";
        let opts = CsvReadOptions {
            na_values: vec!["CUSTOM".into()],
            keep_default_na: false,
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        let b = frame.column("b").unwrap();
        // "NA" should NOT be missing because keep_default_na=false
        assert_eq!(b.values()[0], Scalar::Utf8("NA".into()));
        // "CUSTOM" should be missing because it's in na_values
        assert!(b.values()[1].is_missing());
        assert_eq!(b.values()[2], Scalar::Utf8("valid".into()));
    }

    #[test]
    fn csv_na_filter_false() {
        // With na_filter=false, no NA detection at all (for performance)
        let input = "a,b\n1,NA\n2,\n3,None\n";
        let opts = CsvReadOptions {
            na_filter: false,
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        let b = frame.column("b").unwrap();
        // All values should be kept as strings, no NA detection
        assert_eq!(b.values()[0], Scalar::Utf8("NA".into()));
        assert_eq!(b.values()[1], Scalar::Utf8("".into()));
        assert_eq!(b.values()[2], Scalar::Utf8("None".into()));
    }

    #[test]
    fn csv_with_index_col() {
        let input = "id,val\na,10\nb,20\nc,30\n";
        let opts = CsvReadOptions {
            index_col: Some("id".into()),
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        assert_eq!(frame.index().len(), 3);
        assert_eq!(
            frame.index().labels()[0],
            fp_index::IndexLabel::Utf8("a".into())
        );
        assert!(frame.column("id").is_none());
        assert_eq!(frame.column("val").unwrap().values()[0], Scalar::Int64(10));
    }

    #[test]
    fn csv_with_missing_index_col_errors() {
        let input = "id,val\na,10\nb,20\n";
        let opts = CsvReadOptions {
            index_col: Some("missing".into()),
            ..Default::default()
        };

        let err = read_csv_with_options(input, &opts).expect_err("missing index_col should error");
        assert!(
            matches!(&err, IoError::MissingIndexColumn(name) if name == "missing"),
            "expected MissingIndexColumn(\"missing\"), got {err:?}"
        );
    }

    #[test]
    fn csv_with_malformed_row_errors() {
        let input = "a,b\n1,2\n3\n";
        let opts = CsvReadOptions::default();

        let err = read_csv_with_options(input, &opts).expect_err("malformed CSV row should error");
        assert!(
            matches!(&err, IoError::Csv(_)),
            "expected CSV parser error for ragged row, got {err:?}"
        );
    }

    #[test]
    fn csv_on_bad_lines_skip_skips_extra_field_rows() {
        let input = "a,b\n1,2\n3,4,5\n6,7\n";
        let opts = CsvReadOptions {
            on_bad_lines: CsvOnBadLines::Skip,
            ..Default::default()
        };

        let frame = read_csv_with_options(input, &opts).expect("parse with skipped bad line");
        assert_eq!(frame.index().len(), 2);
        assert_eq!(frame.column("a").unwrap().values()[0], Scalar::Int64(1));
        assert_eq!(frame.column("b").unwrap().values()[0], Scalar::Int64(2));
        assert_eq!(frame.column("a").unwrap().values()[1], Scalar::Int64(6));
        assert_eq!(frame.column("b").unwrap().values()[1], Scalar::Int64(7));
    }

    #[test]
    fn csv_on_bad_lines_warn_skips_extra_field_rows() {
        let input = "a,b\n1,2\n3,4,5\n6,7\n";
        let opts = CsvReadOptions {
            on_bad_lines: CsvOnBadLines::Warn,
            ..Default::default()
        };

        let frame = read_csv_with_options(input, &opts).expect("parse with warned bad line");
        assert_eq!(frame.index().len(), 2);
        assert_eq!(frame.column("a").unwrap().values()[0], Scalar::Int64(1));
        assert_eq!(frame.column("b").unwrap().values()[1], Scalar::Int64(7));
    }

    #[test]
    fn csv_on_bad_lines_skip_preserves_short_rows_as_missing() {
        // DISC-011: Int64 columns with missing values stay Int64 (extension dtype parity).
        // Missing values use NullKind::Null (pd.NA semantics) not NullKind::NaN.
        let input = "a,b\n1,2\n3\n6,7\n";
        let opts = CsvReadOptions {
            on_bad_lines: CsvOnBadLines::Skip,
            ..Default::default()
        };

        let frame = read_csv_with_options(input, &opts).expect("parse short row");
        assert_eq!(frame.index().len(), 3);
        assert_eq!(frame.column("a").unwrap().values()[1], Scalar::Int64(3));
        assert_eq!(
            frame.column("b").unwrap().values()[1],
            Scalar::Null(NullKind::Null)
        );
    }

    #[test]
    fn json_temporal_values_and_index_are_epoch_millis() {
        // pandas to_json (date_unit='ms') serializes datetime64/timedelta64 as
        // epoch-millisecond integers for both values and index — not ISO/format
        // strings (values) nor raw nanoseconds (index). (br-frankenpandas-lb0iu)
        // 2020-01-01T00:00:00 == 1_577_836_800_000 ms; 1s timedelta == 1000 ms.
        let dt_ns = 1_577_836_800_000_000_000_i64;
        let mut columns = BTreeMap::new();
        columns.insert(
            "d".to_owned(),
            Column::from_values(vec![Scalar::Datetime64(dt_ns)]).expect("d"),
        );
        columns.insert(
            "t".to_owned(),
            Column::from_values(vec![Scalar::Timedelta64(1_000_000_000)]).expect("t"),
        );
        let index = Index::new(vec![IndexLabel::Datetime64(dt_ns)]);
        let frame =
            DataFrame::new_with_column_order(index, columns, vec!["d".to_owned(), "t".to_owned()])
                .expect("frame");

        let out = write_json_string(&frame, JsonOrient::Columns).expect("json");
        assert!(
            out.contains("1577836800000"),
            "datetime value/index should be epoch-millis int, got {out}"
        );
        assert!(
            out.contains("1000"),
            "timedelta value should be epoch-millis int (1000), got {out}"
        );
        // Must NOT contain the old ISO string or raw-nanosecond forms.
        assert!(
            !out.contains("2020-01-01"),
            "should not emit ISO string: {out}"
        );
        assert!(
            !out.contains("1577836800000000000"),
            "should not emit raw nanoseconds: {out}"
        );
    }

    #[test]
    fn json_records_read_write_roundtrip() {
        let input = r#"[{"name":"Alice","age":30},{"name":"Bob","age":25}]"#;
        let frame = read_json_str(input, JsonOrient::Records).expect("read json records");
        assert_eq!(frame.index().len(), 2);
        assert_eq!(
            frame.column("name").unwrap().values()[0],
            Scalar::Utf8("Alice".into())
        );
        assert_eq!(frame.column("age").unwrap().values()[1], Scalar::Int64(25));

        let output = write_json_string(&frame, JsonOrient::Records).expect("write");
        let frame2 = read_json_str(&output, JsonOrient::Records).expect("re-read");
        assert_eq!(frame2.index().len(), 2);
    }

    #[test]
    fn json_records_nullable_int_roundtrip_is_stable() {
        let input = r#"[{"city":"Boston","temp":72},{"city":"Paris","temp":null}]"#;
        let frame = read_json_str(input, JsonOrient::Records).expect("read json records");
        let output = write_json_string(&frame, JsonOrient::Records).expect("write records");
        let frame2 = read_json_str(&output, JsonOrient::Records).expect("re-read records");

        assert!(frame.equals(&frame2));
    }

    #[test]
    fn json_records_preserves_column_order() {
        let input = r#"[{"b":1,"a":2},{"c":3}]"#;
        let frame = read_json_str(input, JsonOrient::Records).expect("read json records");
        let order: Vec<&str> = frame
            .column_names()
            .iter()
            .map(|name| name.as_str())
            .collect();
        assert_eq!(order, vec!["b", "a", "c"]);
    }

    #[test]
    fn json_columns_read_write_roundtrip() {
        let input = r#"{"name":{"row_a":"Alice","row_b":"Bob"},"age":{"row_a":30,"row_b":25}}"#;
        let frame = read_json_str(input, JsonOrient::Columns).expect("read json columns");
        assert_eq!(frame.index().len(), 2);
        assert_eq!(frame.index().labels()[0], IndexLabel::Utf8("row_a".into()));

        let output = write_json_string(&frame, JsonOrient::Columns).expect("write");
        let frame2 = read_json_str(&output, JsonOrient::Columns).expect("re-read");
        assert_eq!(frame2.index().labels(), frame.index().labels());
    }

    #[test]
    fn json_columns_write_duplicate_index_rejects() {
        let index = Index::new(vec![IndexLabel::Int64(1), IndexLabel::Utf8("1".into())]);
        let mut columns = BTreeMap::new();
        columns.insert(
            "v".into(),
            Column::from_values(vec![Scalar::Int64(10), Scalar::Int64(20)]).expect("col"),
        );
        let frame = DataFrame::new(index, columns).expect("frame");

        let err = write_json_string(&frame, JsonOrient::Columns)
            .expect_err("duplicate JSON object keys should reject");
        assert!(
            matches!(&err, IoError::JsonFormat(msg) if msg.contains("duplicate index label key")),
            "expected duplicate-index-key JsonFormat, got {err:?}"
        );
    }

    #[test]
    fn json_split_read_write_roundtrip() {
        let input = r#"{"columns":["x","y"],"index":["r1","r2","r3"],"data":[[1,4],[2,5],[3,6]]}"#;
        let frame = read_json_str(input, JsonOrient::Split).expect("read json split");
        assert_eq!(frame.index().len(), 3);
        assert_eq!(
            frame.index().labels()[0],
            fp_index::IndexLabel::Utf8("r1".into())
        );
        assert_eq!(frame.column("x").unwrap().values()[0], Scalar::Int64(1));
        assert_eq!(frame.column("y").unwrap().values()[2], Scalar::Int64(6));

        let output = write_json_string(&frame, JsonOrient::Split).expect("write");
        let frame2 = read_json_str(&output, JsonOrient::Split).expect("re-read");
        assert_eq!(frame2.index().len(), 3);
        assert_eq!(frame2.index().labels(), frame.index().labels());
    }

    #[test]
    fn json_records_multiindex_roundtrip_restores_logical_row_axis() {
        let frame = make_row_multiindex_test_dataframe();
        let json = write_json_string(&frame, JsonOrient::Records).expect("write");
        let roundtrip = read_json_str(&json, JsonOrient::Records).expect("read");

        assert!(roundtrip.equals(&frame));
        assert!(roundtrip.row_multiindex().is_some());
        assert!(roundtrip.column("__index_level_0__").is_none());
    }

    #[test]
    fn json_split_multiindex_roundtrip_restores_logical_row_axis() {
        let frame = make_row_multiindex_test_dataframe();
        let json = write_json_string(&frame, JsonOrient::Split).expect("write");
        let roundtrip = read_json_str(&json, JsonOrient::Split).expect("read");

        assert!(roundtrip.equals(&frame));
        assert!(roundtrip.row_multiindex().is_some());
        assert!(roundtrip.column("__index_level_0__").is_none());
    }

    #[test]
    fn json_split_without_index_defaults_to_range_index() {
        let input = r#"{"columns":["x"],"data":[[10],[20]]}"#;
        let frame = read_json_str(input, JsonOrient::Split).expect("read json split");
        assert_eq!(frame.index().labels()[0], fp_index::IndexLabel::Int64(0));
        assert_eq!(frame.index().labels()[1], fp_index::IndexLabel::Int64(1));
    }

    #[test]
    fn json_split_index_length_mismatch_errors() {
        let input = r#"{"columns":["x"],"index":[0],"data":[[1],[2]]}"#;
        let err = read_json_str(input, JsonOrient::Split)
            .expect_err("split orient index/data length mismatch should error");
        assert!(
            matches!(&err, IoError::JsonFormat(msg) if msg.contains("index length")),
            "expected split index length error, got {err:?}"
        );
    }

    #[test]
    fn json_split_row_length_mismatch_errors() {
        let input = r#"{"columns":["x","y"],"data":[[1],[2,3]]}"#;
        let err = read_json_str(input, JsonOrient::Split)
            .expect_err("split orient row length mismatch should error");
        assert!(
            matches!(&err, IoError::JsonFormat(msg) if msg.contains("row 0 length")),
            "expected split row length error, got {err:?}"
        );
    }

    #[test]
    fn json_split_non_string_columns_are_stringified() {
        let input = r#"{"columns":[1,true,null,"name"],"data":[[10,20,30,40]]}"#;
        let frame = read_json_str(input, JsonOrient::Split).expect("read json split");
        assert_eq!(frame.column("1").unwrap().values()[0], Scalar::Int64(10));
        assert_eq!(frame.column("true").unwrap().values()[0], Scalar::Int64(20));
        assert_eq!(frame.column("null").unwrap().values()[0], Scalar::Int64(30));
        assert_eq!(frame.column("name").unwrap().values()[0], Scalar::Int64(40));
    }

    #[test]
    fn json_split_duplicate_column_names_error() {
        let input = r#"{"columns":[1,"1"],"data":[[10,20]]}"#;
        let err = read_json_str(input, JsonOrient::Split).expect_err("dup columns");
        assert!(matches!(err, IoError::DuplicateColumnName(name) if name == "1"));
    }

    #[test]
    fn json_index_read_write_roundtrip() {
        let input = r#"{"row_a":{"name":"Alice","age":30},"row_b":{"name":"Bob","age":25}}"#;
        let frame = read_json_str(input, JsonOrient::Index).expect("read json index");
        assert_eq!(frame.index().len(), 2);
        assert_eq!(frame.index().labels()[0], IndexLabel::Utf8("row_a".into()));
        assert_eq!(
            frame.column("name").unwrap().values()[1],
            Scalar::Utf8("Bob".into())
        );

        let output = write_json_string(&frame, JsonOrient::Index).expect("write");
        let frame2 = read_json_str(&output, JsonOrient::Index).expect("re-read");
        assert_eq!(frame2.index().labels(), frame.index().labels());
        assert_eq!(frame2.column("age").unwrap().values()[0], Scalar::Int64(30));
    }

    #[test]
    fn json_index_preserves_column_order() {
        let input = r#"{"r1":{"b":1,"a":2},"r2":{"c":3}}"#;
        let frame = read_json_str(input, JsonOrient::Index).expect("parse");
        let order: Vec<&str> = frame
            .column_names()
            .iter()
            .map(|name| name.as_str())
            .collect();
        assert_eq!(order, vec!["b", "a", "c"]);
    }

    #[test]
    fn json_index_missing_columns_null_fill() {
        let input = r#"{"r1":{"a":1},"r2":{"b":2}}"#;
        let frame = read_json_str(input, JsonOrient::Index).expect("parse");
        let a = frame.column("a").expect("a");
        let b = frame.column("b").expect("b");

        assert_eq!(a.values()[0], Scalar::Float64(1.0));
        assert!(a.values()[1].is_missing());
        assert!(b.values()[0].is_missing());
        assert_eq!(b.values()[1], Scalar::Float64(2.0));
    }

    #[test]
    fn json_index_write_duplicate_index_rejects() {
        let index = Index::new(vec![IndexLabel::Int64(1), IndexLabel::Utf8("1".into())]);
        let mut columns = BTreeMap::new();
        columns.insert(
            "v".into(),
            Column::from_values(vec![Scalar::Int64(10), Scalar::Int64(20)]).expect("col"),
        );
        let frame = DataFrame::new(index, columns).expect("frame");

        let err = write_json_string(&frame, JsonOrient::Index)
            .expect_err("duplicate JSON object keys should reject");
        assert!(
            matches!(&err, IoError::JsonFormat(msg) if msg.contains("duplicate index label key")),
            "expected duplicate-index-key JsonFormat, got {err:?}"
        );
    }

    #[test]
    fn json_index_read_non_object_row_rejects() {
        let input = r#"{"r1":{"a":1},"r2":[1,2]}"#;
        let err = read_json_str(input, JsonOrient::Index)
            .expect_err("index orient rows must be JSON objects");
        assert!(
            matches!(&err, IoError::JsonFormat(msg) if msg.contains("rows must be objects")),
            "expected row-object error, got {err:?}"
        );
    }

    #[test]
    fn json_values_read_write_roundtrip() {
        let input = r#"[[1,"Alice"],[null,"Bob"]]"#;
        let frame = read_json_str(input, JsonOrient::Values).expect("read json values");
        assert_eq!(frame.index().len(), 2);
        assert_eq!(frame.column_names(), vec!["0", "1"]);
        assert_eq!(frame.column("0").unwrap().values()[0], Scalar::Float64(1.0));
        assert_eq!(
            frame.column("1").unwrap().values()[1],
            Scalar::Utf8("Bob".into())
        );

        let output = write_json_string(&frame, JsonOrient::Values).expect("write");
        let frame2 = read_json_str(&output, JsonOrient::Values).expect("re-read");
        assert_eq!(frame2.index().len(), 2);
        assert_eq!(frame2.column_names(), frame.column_names());
        assert_eq!(
            frame2.column("0").unwrap().values(),
            frame.column("0").unwrap().values()
        );
        assert_eq!(
            frame2.column("1").unwrap().values(),
            frame.column("1").unwrap().values()
        );
    }

    #[test]
    fn json_records_with_nulls() {
        let input = r#"[{"a":1,"b":null},{"a":null,"b":"hello"}]"#;
        let frame = read_json_str(input, JsonOrient::Records).expect("parse");
        assert!(frame.column("a").unwrap().values()[1].is_missing());
        assert!(frame.column("b").unwrap().values()[0].is_missing());
    }

    #[test]
    fn json_read_accepts_pandas_bare_nan_tokens() {
        let cases = [
            (JsonOrient::Records, r#"[{"a":NaN}]"#),
            (JsonOrient::Columns, r#"{"a":{"0":NaN}}"#),
            (
                JsonOrient::Split,
                r#"{"columns":["a"],"index":[0],"data":[[NaN]]}"#,
            ),
            (JsonOrient::Values, r#"[[NaN]]"#),
        ];

        for (orient, input) in cases {
            let frame = read_json_str(input, orient).expect("parse bare NaN");
            let column_name = if orient == JsonOrient::Values {
                "0"
            } else {
                "a"
            };
            assert!(frame.column(column_name).unwrap().values()[0].is_missing());
        }
    }

    #[test]
    fn json_records_write_preserves_nullable_int_column() {
        // DISC-011: Nullable extension Int64 dtype parity - Int64 preserved, not promoted to Float64.
        let frame = DataFrame::from_dict_with_index(
            vec![("a", vec![Scalar::Int64(1), Scalar::Null(NullKind::Null)])],
            vec!["row".into(), "row".into()],
        )
        .unwrap();
        let json = write_json_string(&frame, JsonOrient::Records).expect("write");
        let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed, serde_json::json!([{"a": 1}, {"a": null}]));
    }

    #[test]
    fn json_non_records_nullable_int_reads_promote_to_float() {
        let cases = [
            (JsonOrient::Columns, r#"{"a":{"0":1,"1":null}}"#),
            (JsonOrient::Index, r#"{"0":{"a":1},"1":{"a":null}}"#),
            (
                JsonOrient::Split,
                r#"{"columns":["a"],"index":[0,1],"data":[[1],[null]]}"#,
            ),
            (JsonOrient::Values, r#"[[1],[null]]"#),
        ];

        for (orient, input) in cases {
            let frame = read_json_str(input, orient).expect("read json");
            let column_name = if orient == JsonOrient::Values {
                "0"
            } else {
                "a"
            };
            let values = frame.column(column_name).expect("column").values();
            assert_eq!(values[0], Scalar::Float64(1.0));
            assert!(matches!(values[1], Scalar::Null(NullKind::NaN)));
        }
    }

    #[test]
    fn json_non_records_nullable_int_writes_preserve_int() {
        // DISC-011: Nullable extension Int64 dtype parity - Int64 preserved, not promoted to Float64.
        let frame = DataFrame::from_dict(
            &["a"],
            vec![("a", vec![Scalar::Int64(1), Scalar::Null(NullKind::Null)])],
        )
        .unwrap();

        let columns_json: serde_json::Value =
            serde_json::from_str(&write_json_string(&frame, JsonOrient::Columns).unwrap()).unwrap();
        assert_eq!(columns_json, serde_json::json!({"a": {"0": 1, "1": null}}));

        let index_json: serde_json::Value =
            serde_json::from_str(&write_json_string(&frame, JsonOrient::Index).unwrap()).unwrap();
        assert_eq!(
            index_json,
            serde_json::json!({"0": {"a": 1}, "1": {"a": null}})
        );

        let split_json: serde_json::Value =
            serde_json::from_str(&write_json_string(&frame, JsonOrient::Split).unwrap()).unwrap();
        assert_eq!(
            split_json,
            serde_json::json!({"columns": ["a"], "index": [0, 1], "data": [[1], [null]]})
        );

        let values_json: serde_json::Value =
            serde_json::from_str(&write_json_string(&frame, JsonOrient::Values).unwrap()).unwrap();
        assert_eq!(values_json, serde_json::json!([[1], [null]]));
    }

    #[test]
    fn json_records_empty_array() {
        let input = r#"[]"#;
        let frame = read_json_str(input, JsonOrient::Records).expect("parse");
        assert_eq!(frame.index().len(), 0);
    }

    #[test]
    fn json_records_mixed_numeric_coerces() {
        let input = r#"[{"v":1},{"v":2.5},{"v":true}]"#;
        let frame = read_json_str(input, JsonOrient::Records).expect("parse");
        // Int64 + Float64 + Bool all coerce to Float64
        assert_eq!(frame.column("v").unwrap().values()[0], Scalar::Float64(1.0));
        assert_eq!(frame.column("v").unwrap().values()[1], Scalar::Float64(2.5));
        assert_eq!(frame.column("v").unwrap().values()[2], Scalar::Float64(1.0));
    }

    #[test]
    fn json_records_mixed_utf8_numeric_preserves_object_values() {
        let input = r#"[{"v":1},{"v":"text"}]"#;
        let frame = read_json_str(input, JsonOrient::Records).expect("parse");
        assert_eq!(
            frame.column("v").unwrap().values(),
            &[Scalar::Int64(1), Scalar::Utf8("text".into())]
        );
    }

    #[test]
    fn file_csv_roundtrip() {
        let input = "a,b\n1,2\n3,4\n";
        let frame = read_csv_str(input).expect("parse");

        let dir = std::env::temp_dir();
        let path = dir.join("fp_io_test_roundtrip.csv");
        super::write_csv(&frame, &path).expect("write file");
        let frame2 = super::read_csv(&path).expect("read file");
        assert_eq!(frame2.index().len(), 2);
        std::fs::remove_file(&path).ok();
    }

    #[test]
    fn file_csv_with_options_path() {
        // DISC-011: Nullable extension Int64 dtype parity - Int64 preserved, not promoted to Float64.
        let input = "id\tval\na\tNA\nb\t2\n";
        let dir = std::env::temp_dir();
        let path = dir.join("fp_io_test_options.csv");
        std::fs::write(&path, input).expect("write fixture");

        let options = CsvReadOptions {
            delimiter: b'\t',
            na_values: vec!["NA".into()],
            index_col: Some("id".into()),
            ..Default::default()
        };

        let frame = super::read_csv_with_options_path(&path, &options).expect("read with options");
        assert_eq!(
            frame.index().labels()[0],
            fp_index::IndexLabel::Utf8("a".into())
        );
        assert!(frame.column("id").is_none());
        assert!(frame.column("val").unwrap().values()[0].is_missing());
        assert_eq!(frame.column("val").unwrap().values()[1], Scalar::Int64(2));

        std::fs::remove_file(&path).ok();
    }

    #[test]
    fn file_json_roundtrip() {
        let input = r#"[{"x":1},{"x":2}]"#;
        let frame = read_json_str(input, JsonOrient::Records).expect("parse");

        let dir = std::env::temp_dir();
        let path = dir.join("fp_io_test_roundtrip.json");
        super::write_json(&frame, &path, JsonOrient::Records).expect("write file");
        let frame2 = super::read_json(&path, JsonOrient::Records).expect("read file");
        assert_eq!(frame2.index().len(), 2);
        std::fs::remove_file(&path).ok();
    }

    // ── read_table 4pwr9 ───────────────────────────────────────────────

    #[test]
    fn read_table_str_parses_tab_separated_4pwr9() {
        let input = "a\tb\tc\n1\t2\t3\n4\t5\t6\n";
        let frame = super::read_table_str(input).expect("parse tsv");
        assert_eq!(frame.index().len(), 2);
        assert_eq!(frame.column("a").unwrap().values()[0], Scalar::Int64(1));
        assert_eq!(frame.column("c").unwrap().values()[1], Scalar::Int64(6));
    }

    #[test]
    fn read_table_with_options_overrides_default_delimiter_4pwr9() {
        // DISC-011: Nullable extension Int64 dtype parity - Int64 preserved, not promoted to Float64.
        let input = "x\ty\n1\tNA\n2\t3\n";
        let opts = CsvReadOptions {
            na_values: vec!["NA".into()],
            ..Default::default()
        };
        let frame = super::read_table_with_options(input, &opts).expect("parse tsv with na");
        assert!(frame.column("y").unwrap().values()[0].is_missing());
        assert_eq!(frame.column("y").unwrap().values()[1], Scalar::Int64(3));
    }

    #[test]
    fn read_table_with_options_honours_explicit_pipe_delimiter_4pwr9() {
        let input = "x|y\n1|2\n3|4\n";
        let opts = CsvReadOptions {
            delimiter: b'|',
            ..Default::default()
        };
        let frame = super::read_table_with_options(input, &opts).expect("parse pipe");
        assert_eq!(frame.column("x").unwrap().values()[0], Scalar::Int64(1));
        assert_eq!(frame.column("y").unwrap().values()[1], Scalar::Int64(4));
    }

    // ── read_fwf 23n8u ─────────────────────────────────────────────────

    #[test]
    fn read_fwf_str_with_colspecs_parses_aligned_records_23n8u() {
        let input = "name    age   active\nalice   30    true\nbob     25    false\n";
        let opts = super::FwfReadOptions {
            colspecs: Some(vec![(0, 8), (8, 14), (14, 20)]),
            true_values: vec!["true".into()],
            false_values: vec!["false".into()],
            ..Default::default()
        };
        let frame = super::read_fwf_str(input, &opts).expect("parse fwf");
        assert_eq!(frame.index().len(), 2);
        assert_eq!(
            frame.column("name").unwrap().values()[0],
            Scalar::Utf8("alice".into())
        );
        assert_eq!(frame.column("age").unwrap().values()[0], Scalar::Int64(30));
        assert_eq!(
            frame.column("active").unwrap().values()[0],
            Scalar::Bool(true)
        );
    }

    #[test]
    fn read_fwf_str_with_widths_derives_colspecs_23n8u() {
        let input = "x  y \n1  2 \n3  4 \n";
        let opts = super::FwfReadOptions {
            widths: Some(vec![3, 3]),
            ..Default::default()
        };
        let frame = super::read_fwf_str(input, &opts).expect("parse fwf widths");
        assert_eq!(frame.column("x").unwrap().values()[0], Scalar::Int64(1));
        assert_eq!(frame.column("y").unwrap().values()[1], Scalar::Int64(4));
    }

    #[test]
    fn read_fwf_str_threads_na_handling_23n8u() {
        // DISC-011: Nullable extension Int64 dtype parity - Int64 preserved, not promoted to Float64.
        let input = "id   val\nA    NA \nB    7  \n";
        let opts = super::FwfReadOptions {
            colspecs: Some(vec![(0, 5), (5, 9)]),
            na_values: vec!["NA".into()],
            ..Default::default()
        };
        let frame = super::read_fwf_str(input, &opts).expect("parse fwf na");
        let col = frame.column("val").unwrap().values();
        assert!(col[0].is_missing());
        assert_eq!(col[1], Scalar::Int64(7));
    }

    #[test]
    fn read_fwf_rejects_both_colspecs_and_widths_23n8u() {
        let opts = super::FwfReadOptions {
            colspecs: Some(vec![(0, 3)]),
            widths: Some(vec![3]),
            ..Default::default()
        };
        let err = super::read_fwf_str("x\n1\n", &opts).expect_err("must reject");
        assert!(
            matches!(&err, super::IoError::Fwf(message) if message.contains("only one of")),
            "unexpected error: {err:?}"
        );
    }

    #[test]
    fn read_fwf_infers_colspecs_when_specs_are_omitted_htdmp() {
        let opts = super::FwfReadOptions::default();
        let frame = super::read_fwf_str("a b\n1 2\n3 4\n", &opts).expect("infer fwf specs");
        assert_eq!(frame.column("a").unwrap().values()[0], Scalar::Int64(1));
        assert_eq!(frame.column("b").unwrap().values()[1], Scalar::Int64(4));
    }

    #[test]
    fn read_fwf_infers_aligned_wide_colspecs_htdmp() {
        let input = "name    age   active\nalice   30    true\nbob     25    false\n";
        let opts = super::FwfReadOptions {
            true_values: vec!["true".into()],
            false_values: vec!["false".into()],
            ..Default::default()
        };
        let frame = super::read_fwf_str(input, &opts).expect("infer aligned fwf specs");
        assert_eq!(
            frame.column("name").unwrap().values()[0],
            Scalar::Utf8("alice".into())
        );
        assert_eq!(frame.column("age").unwrap().values()[1], Scalar::Int64(25));
        assert_eq!(
            frame.column("active").unwrap().values()[1],
            Scalar::Bool(false)
        );
    }

    #[test]
    fn read_fwf_infer_honors_skiprows_and_skipfooter_htdmp() {
        let input = "ignored wide banner\nx y\n1 2\nfooter text ignored\n";
        let opts = super::FwfReadOptions {
            skiprows: 1,
            skipfooter: 1,
            ..Default::default()
        };
        let frame = super::read_fwf_str(input, &opts).expect("infer after skipping");
        assert_eq!(frame.column("x").unwrap().values()[0], Scalar::Int64(1));
        assert_eq!(frame.column("y").unwrap().values()[0], Scalar::Int64(2));
    }

    // ── Deferred reader surfaces 2yy4d ─────────────────────────────────

    #[test]
    fn read_clipboard_rejects_with_deferred_marker_2yy4d() {
        let err = super::read_clipboard().expect_err("must reject");
        assert!(
            matches!(&err, super::IoError::Deferred(message)
                if message.contains("read_clipboard") && message.contains("headless")),
            "unexpected error: {err:?}"
        );
    }

    #[test]
    fn read_gbq_rejects_with_deferred_marker_2yy4d() {
        let err = super::read_gbq("SELECT 1", Some("proj")).expect_err("must reject");
        assert!(
            matches!(&err, super::IoError::Deferred(message)
                if message.contains("read_gbq") && message.contains("BigQuery")),
            "unexpected error: {err:?}"
        );
        let no_project_err = super::read_gbq("SELECT 1", None).expect_err("must reject");
        assert!(matches!(no_project_err, super::IoError::Deferred(_)));
    }

    #[test]
    fn dataframe_deferred_writer_surfaces_report_method_names_e6jrk() {
        use super::DataFrameIoExt;

        let frame = make_test_dataframe();
        let clipboard_err = frame
            .to_clipboard()
            .expect_err("must reject clipboard writer");
        assert!(
            matches!(&clipboard_err, super::IoError::Deferred(message) if message.contains("to_clipboard") && message.contains("headless"))
        );

        let gbq_err = frame
            .to_gbq("dataset.table", Some("project"))
            .expect_err("must reject BigQuery writer");
        assert!(
            matches!(&gbq_err, super::IoError::Deferred(message) if message.contains("to_gbq") && message.contains("BigQuery"))
        );

        let no_project_err = frame
            .to_gbq("dataset.table", None)
            .expect_err("must reject BigQuery writer without project");
        assert!(matches!(no_project_err, super::IoError::Deferred(_)));
    }

    #[test]
    fn series_clipboard_writer_rejects_with_deferred_marker() {
        use super::SeriesIoExt;

        let source = Series::from_values(
            "sales",
            vec!["r1".into(), "r2".into()],
            vec![Scalar::Int64(10), Scalar::Int64(12)],
        )
        .expect("source series");
        let err = source
            .to_clipboard()
            .expect_err("must reject series clipboard writer");
        assert!(
            matches!(&err, super::IoError::Deferred(message) if message.contains("to_clipboard") && message.contains("headless"))
        );
    }

    #[test]
    fn read_sas_rejects_with_deferred_marker_2yy4d() {
        let path = std::path::Path::new("/nonexistent.sas7bdat");
        let err = super::read_sas(path).expect_err("must reject");
        assert!(
            matches!(&err, super::IoError::Deferred(message)
                if message.contains("read_sas") && message.contains("sas7bdat")),
            "unexpected error: {err:?}"
        );
    }

    #[test]
    fn read_spss_rejects_with_deferred_marker_2yy4d() {
        let path = std::path::Path::new("/nonexistent.sav");
        let err = super::read_spss(path).expect_err("must reject");
        assert!(
            matches!(&err, super::IoError::Deferred(message)
                if message.contains("read_spss") && message.contains(".sav")),
            "unexpected error: {err:?}"
        );
    }

    #[test]
    fn read_fwf_path_reads_fixed_width_file_23n8u() {
        let input = "a   b\n1   2\n3   4\n";
        let dir = std::env::temp_dir();
        let path = dir.join("fp_io_test_read_fwf_23n8u.txt");
        std::fs::write(&path, input).expect("write fixture");

        let opts = super::FwfReadOptions {
            colspecs: Some(vec![(0, 4), (4, 5)]),
            ..Default::default()
        };
        let frame = super::read_fwf(&path, &opts).expect("read fwf path");
        assert_eq!(frame.index().len(), 2);
        assert_eq!(frame.column("a").unwrap().values()[1], Scalar::Int64(3));
        assert_eq!(frame.column("b").unwrap().values()[0], Scalar::Int64(2));

        std::fs::remove_file(&path).ok();
    }

    #[test]
    fn read_table_path_roundtrips_through_read_csv_path_4pwr9() {
        let input = "id\tval\na\t1\nb\t2\n";
        let dir = std::env::temp_dir();
        let path = dir.join("fp_io_test_read_table_4pwr9.tsv");
        std::fs::write(&path, input).expect("write fixture");

        let frame = super::read_table(&path).expect("read tsv");
        assert_eq!(frame.index().len(), 2);
        assert_eq!(
            frame.column("id").unwrap().values()[0],
            Scalar::Utf8("a".into())
        );
        assert_eq!(frame.column("val").unwrap().values()[1], Scalar::Int64(2));

        let opts = CsvReadOptions {
            index_col: Some("id".into()),
            ..Default::default()
        };
        let frame2 =
            super::read_table_with_options_path(&path, &opts).expect("read tsv with options");
        assert!(frame2.column("id").is_none());
        assert_eq!(
            frame2.index().labels()[0],
            fp_index::IndexLabel::Utf8("a".into())
        );
        assert_eq!(frame2.column("val").unwrap().values()[1], Scalar::Int64(2));

        std::fs::remove_file(&path).ok();
    }

    // ── Parquet I/O tests ──────────────────────────────────────────────

    fn make_test_dataframe() -> DataFrame {
        use fp_types::DType;

        let mut columns = BTreeMap::new();
        columns.insert(
            "ints".to_string(),
            Column::new(
                DType::Int64,
                vec![Scalar::Int64(10), Scalar::Int64(20), Scalar::Int64(30)],
            )
            .unwrap(),
        );
        columns.insert(
            "floats".to_string(),
            Column::new(
                DType::Float64,
                vec![
                    Scalar::Float64(1.5),
                    Scalar::Float64(2.5),
                    Scalar::Float64(3.5),
                ],
            )
            .unwrap(),
        );
        columns.insert(
            "names".to_string(),
            Column::from_values(vec![
                Scalar::Utf8("alice".into()),
                Scalar::Utf8("bob".into()),
                Scalar::Utf8("carol".into()),
            ])
            .unwrap(),
        );

        let labels = vec![
            IndexLabel::Int64(0),
            IndexLabel::Int64(1),
            IndexLabel::Int64(2),
        ];
        DataFrame::new_with_column_order(
            Index::new(labels),
            columns,
            vec![
                "ints".to_string(),
                "floats".to_string(),
                "names".to_string(),
            ],
        )
        .unwrap()
    }

    #[test]
    fn dataframe_io_ext_pandas_named_aliases_cover_supported_writers() {
        use super::DataFrameIoExt;

        let frame = make_test_dataframe();
        let csv = frame.to_csv_string().expect("csv string");
        assert_eq!(csv, super::write_csv_string(&frame).expect("free csv"));
        assert_eq!(
            frame.to_markdown_string().expect("markdown string"),
            write_markdown_string(&frame).expect("free markdown")
        );
        assert_eq!(
            frame.to_latex_string().expect("latex string"),
            write_latex_string(&frame).expect("free latex")
        );
        let dir = std::env::temp_dir();
        let stem = format!("fp_io_dataframe_io_ext_{}", std::process::id());
        let excel_path = dir.join(format!("{stem}.xlsx"));
        let feather_path = dir.join(format!("{stem}.feather"));
        let parquet_path = dir.join(format!("{stem}.parquet"));

        frame.to_excel(&excel_path).expect("to_excel alias");
        frame.to_feather(&feather_path).expect("to_feather alias");
        frame.to_parquet(&parquet_path).expect("to_parquet alias");

        assert!(
            std::fs::metadata(&excel_path)
                .expect("excel metadata")
                .len()
                > 0
        );
        assert_eq!(
            super::read_feather(&feather_path)
                .expect("read feather")
                .index()
                .len(),
            frame.index().len()
        );
        assert_eq!(
            super::read_parquet(&parquet_path)
                .expect("read parquet")
                .index()
                .len(),
            frame.index().len()
        );

        std::fs::remove_file(&excel_path).ok();
        std::fs::remove_file(&feather_path).ok();
        std::fs::remove_file(&parquet_path).ok();
    }

    #[test]
    fn dataframe_io_ext_rjs51_in_memory_methods_match_free_functions() {
        use super::DataFrameIoExt;

        let frame = make_test_dataframe();
        let csv_options = CsvWriteOptions {
            delimiter: b';',
            na_rep: "<NA>".to_owned(),
            header: true,
            include_index: true,
            index_label: Some("row".to_owned()),
        };
        assert_eq!(
            frame
                .to_csv_string_with_options(&csv_options)
                .expect("csv options through extension"),
            write_csv_string_with_options(&frame, &csv_options).expect("csv options free fn")
        );
        assert_eq!(
            frame
                .to_json_string(JsonOrient::Split)
                .expect("json split through extension"),
            write_json_string(&frame, JsonOrient::Split).expect("json split free fn")
        );
        assert_eq!(
            frame.to_jsonl_string().expect("jsonl through extension"),
            write_jsonl_string(&frame).expect("jsonl free fn")
        );
        let html_options = HtmlWriteOptions {
            include_index: false,
            ..HtmlWriteOptions::default()
        };
        assert_eq!(
            frame
                .to_html_string_with_options(&html_options)
                .expect("html options through extension"),
            write_html_string_with_options(&frame, &html_options).expect("html options free fn")
        );
        let xml_options = XmlWriteOptions {
            include_index: false,
            root_name: "records".to_owned(),
            row_name: "record".to_owned(),
            index_label: None,
        };
        assert_eq!(
            frame
                .to_xml_string_with_options(&xml_options)
                .expect("xml options through extension"),
            write_xml_string_with_options(&frame, &xml_options).expect("xml options free fn")
        );

        let parquet = frame
            .to_parquet_bytes()
            .expect("parquet bytes through extension");
        assert_eq!(
            read_parquet_bytes(&parquet)
                .expect("parquet roundtrip")
                .index()
                .len(),
            frame.index().len()
        );
        let orc = frame.to_orc_bytes().expect("orc bytes through extension");
        assert_eq!(
            read_orc_bytes(&orc).expect("orc roundtrip").index().len(),
            frame.index().len()
        );
        let feather = frame
            .to_feather_bytes()
            .expect("feather bytes through extension");
        assert_eq!(
            read_feather_bytes(&feather)
                .expect("feather roundtrip")
                .index()
                .len(),
            frame.index().len()
        );
        let excel = frame
            .to_excel_bytes()
            .expect("excel bytes through extension");
        assert_eq!(
            read_excel_bytes(&excel, &ExcelReadOptions::default())
                .expect("excel roundtrip")
                .index()
                .len(),
            frame.index().len()
        );
    }

    fn make_row_multiindex_test_dataframe() -> DataFrame {
        let df = DataFrame::from_dict(
            &["region", "product", "year", "sales", "cost"],
            vec![
                (
                    "region",
                    vec![
                        Scalar::Utf8("north".into()),
                        Scalar::Utf8("north".into()),
                        Scalar::Utf8("south".into()),
                    ],
                ),
                (
                    "product",
                    vec![
                        Scalar::Utf8("apple".into()),
                        Scalar::Utf8("pear".into()),
                        Scalar::Utf8("apple".into()),
                    ],
                ),
                (
                    "year",
                    vec![
                        Scalar::Int64(2023),
                        Scalar::Int64(2024),
                        Scalar::Int64(2023),
                    ],
                ),
                (
                    "sales",
                    vec![Scalar::Int64(10), Scalar::Int64(20), Scalar::Int64(30)],
                ),
                (
                    "cost",
                    vec![Scalar::Int64(4), Scalar::Int64(7), Scalar::Int64(12)],
                ),
            ],
        )
        .unwrap();
        df.set_index_multi(&["region", "product", "year"], true, "|")
            .unwrap()
    }

    #[test]
    fn parquet_bytes_roundtrip() {
        let frame = make_test_dataframe();
        let bytes = super::write_parquet_bytes(&frame).expect("write parquet");
        assert!(!bytes.is_empty());

        let frame2 = super::read_parquet_bytes(&bytes).expect("read parquet");
        assert_eq!(frame2.index().len(), 3);
        assert_eq!(
            frame2
                .column_names()
                .iter()
                .map(|s| s.as_str())
                .collect::<Vec<_>>(),
            vec!["ints", "floats", "names"]
        );

        // Check values round-tripped correctly
        let ints = frame2.column("ints").unwrap();
        assert_eq!(ints.values()[0], Scalar::Int64(10));
        assert_eq!(ints.values()[1], Scalar::Int64(20));
        assert_eq!(ints.values()[2], Scalar::Int64(30));

        let floats = frame2.column("floats").unwrap();
        assert_eq!(floats.values()[0], Scalar::Float64(1.5));
        assert_eq!(floats.values()[1], Scalar::Float64(2.5));
        assert_eq!(floats.values()[2], Scalar::Float64(3.5));

        let names = frame2.column("names").unwrap();
        assert_eq!(names.values()[0], Scalar::Utf8("alice".into()));
        assert_eq!(names.values()[1], Scalar::Utf8("bob".into()));
        assert_eq!(names.values()[2], Scalar::Utf8("carol".into()));
    }

    #[test]
    fn parquet_row_multiindex_roundtrip_restores_logical_row_axis() {
        let frame = make_row_multiindex_test_dataframe();
        let bytes = super::write_parquet_bytes(&frame).expect("write parquet");
        let roundtrip = super::read_parquet_bytes(&bytes).expect("read parquet");

        assert!(roundtrip.equals(&frame));
        assert!(roundtrip.column("__index_level_0__").is_none());
        assert_eq!(
            roundtrip
                .row_multiindex()
                .expect("row multiindex should be restored")
                .get_level_values(0)
                .unwrap()
                .labels(),
            frame
                .row_multiindex()
                .expect("source row multiindex")
                .get_level_values(0)
                .unwrap()
                .labels()
        );
    }

    #[test]
    fn parquet_file_roundtrip() {
        let frame = make_test_dataframe();
        let dir = std::env::temp_dir();
        let path = dir.join("fp_io_test_parquet_roundtrip.parquet");

        super::write_parquet(&frame, &path).expect("write parquet file");
        let frame2 = super::read_parquet(&path).expect("read parquet file");
        assert_eq!(frame2.index().len(), 3);
        assert_eq!(
            frame2.column("ints").unwrap().values()[0],
            Scalar::Int64(10)
        );
        std::fs::remove_file(&path).ok();
    }

    #[test]
    fn parquet_with_nulls() {
        use fp_types::DType;

        let mut columns = BTreeMap::new();
        columns.insert(
            "vals".to_string(),
            Column::new(
                DType::Float64,
                vec![
                    Scalar::Float64(1.0),
                    Scalar::Null(NullKind::NaN),
                    Scalar::Float64(3.0),
                ],
            )
            .unwrap(),
        );
        columns.insert(
            "strs".to_string(),
            Column::from_values(vec![
                Scalar::Utf8("a".into()),
                Scalar::Null(NullKind::Null),
                Scalar::Utf8("c".into()),
            ])
            .unwrap(),
        );

        let labels = vec![
            IndexLabel::Int64(0),
            IndexLabel::Int64(1),
            IndexLabel::Int64(2),
        ];
        let frame = DataFrame::new_with_column_order(
            Index::new(labels),
            columns,
            vec!["vals".to_string(), "strs".to_string()],
        )
        .unwrap();

        let bytes = super::write_parquet_bytes(&frame).expect("write");
        let frame2 = super::read_parquet_bytes(&bytes).expect("read");

        assert_eq!(
            frame2.column("vals").unwrap().values()[0],
            Scalar::Float64(1.0)
        );
        assert!(frame2.column("vals").unwrap().values()[1].is_missing());
        assert_eq!(
            frame2.column("vals").unwrap().values()[2],
            Scalar::Float64(3.0)
        );

        assert_eq!(
            frame2.column("strs").unwrap().values()[0],
            Scalar::Utf8("a".into())
        );
        assert!(frame2.column("strs").unwrap().values()[1].is_missing());
        assert_eq!(
            frame2.column("strs").unwrap().values()[2],
            Scalar::Utf8("c".into())
        );
    }

    #[test]
    fn parquet_bool_column() {
        use fp_types::DType;

        let mut columns = BTreeMap::new();
        columns.insert(
            "flags".to_string(),
            Column::new(
                DType::Bool,
                vec![Scalar::Bool(true), Scalar::Bool(false), Scalar::Bool(true)],
            )
            .unwrap(),
        );

        let labels = vec![
            IndexLabel::Int64(0),
            IndexLabel::Int64(1),
            IndexLabel::Int64(2),
        ];
        let frame = DataFrame::new_with_column_order(
            Index::new(labels),
            columns,
            vec!["flags".to_string()],
        )
        .unwrap();

        let bytes = super::write_parquet_bytes(&frame).expect("write");
        let frame2 = super::read_parquet_bytes(&bytes).expect("read");

        assert_eq!(
            frame2.column("flags").unwrap().values()[0],
            Scalar::Bool(true)
        );
        assert_eq!(
            frame2.column("flags").unwrap().values()[1],
            Scalar::Bool(false)
        );
        assert_eq!(
            frame2.column("flags").unwrap().values()[2],
            Scalar::Bool(true)
        );
    }

    #[test]
    fn parquet_empty_dataframe_errors() {
        // Parquet format requires at least one column — empty DataFrames
        // cannot be represented, matching pandas behavior where
        // pd.DataFrame().to_parquet() also fails.
        let frame =
            DataFrame::new_with_column_order(Index::new(vec![]), BTreeMap::new(), vec![]).unwrap();

        let result = super::write_parquet_bytes(&frame);
        assert!(result.is_err());
    }

    #[test]
    fn orc_bytes_roundtrip_preserves_supported_columns() {
        let frame = make_test_dataframe();
        let bytes = write_orc_bytes(&frame).expect("write orc");
        assert!(bytes.starts_with(b"ORC"));

        let frame2 = read_orc_bytes(&bytes).expect("read orc");
        assert_eq!(frame2.index().len(), 3);
        assert_eq!(
            frame2
                .column_names()
                .iter()
                .map(|s| s.as_str())
                .collect::<Vec<_>>(),
            vec!["ints", "floats", "names"]
        );

        assert_eq!(
            frame2.column("ints").unwrap().values()[0],
            Scalar::Int64(10)
        );
        assert_eq!(
            frame2.column("floats").unwrap().values()[1],
            Scalar::Float64(2.5)
        );
        assert_eq!(
            frame2.column("names").unwrap().values()[2],
            Scalar::Utf8("carol".into())
        );
    }

    #[test]
    fn orc_file_and_extension_aliases_roundtrip() {
        use super::DataFrameIoExt;

        let frame = make_test_dataframe();
        let free_path = std::env::temp_dir().join(format!(
            "fp_io_orc_free_{}_{}.orc",
            std::process::id(),
            line!()
        ));
        let trait_path = std::env::temp_dir().join(format!(
            "fp_io_orc_trait_{}_{}.orc",
            std::process::id(),
            line!()
        ));

        write_orc(&frame, &free_path).expect("write orc path");
        let free_roundtrip = read_orc(&free_path).expect("read orc path");
        assert!(free_roundtrip.equals(&frame));

        frame.to_orc_file(&trait_path).expect("trait orc path");
        let trait_roundtrip = read_orc(&trait_path).expect("read trait orc path");
        assert!(trait_roundtrip.equals(&frame));

        let bytes = frame.to_orc_bytes().expect("trait orc bytes");
        assert!(
            read_orc_bytes(&bytes)
                .expect("read trait orc bytes")
                .equals(&frame)
        );
    }

    #[test]
    fn orc_row_multiindex_roundtrip_restores_logical_row_axis() {
        let frame = make_row_multiindex_test_dataframe();
        let bytes = write_orc_bytes(&frame).expect("write orc");
        let roundtrip = read_orc_bytes(&bytes).expect("read orc");

        assert!(roundtrip.equals(&frame));
        assert!(roundtrip.column("__index_level_0__").is_none());
        assert_eq!(
            roundtrip
                .row_multiindex()
                .expect("row multiindex should be restored")
                .get_level_values(0)
                .unwrap()
                .labels(),
            frame
                .row_multiindex()
                .expect("source row multiindex")
                .get_level_values(0)
                .unwrap()
                .labels()
        );
    }

    #[test]
    fn orc_reader_rejects_malformed_input() {
        let err = read_orc_bytes(b"not an orc file").expect_err("malformed orc should fail");
        assert!(matches!(err, IoError::Orc(_)));
    }

    // ── Excel I/O tests ──────────────────────────────────────────────

    #[test]
    fn write_excel_with_options_custom_sheet_name_survives_round_trip() {
        let frame = make_test_dataframe();
        let bytes = super::write_excel_bytes_with_options(
            &frame,
            &super::ExcelWriteOptions {
                sheet_name: "Results".to_string(),
                ..super::ExcelWriteOptions::default()
            },
        )
        .expect("write");
        let sheets =
            super::read_excel_sheets_bytes(&bytes, None, &super::ExcelReadOptions::default())
                .expect("read");
        assert_eq!(sheets.len(), 1);
        assert!(sheets.contains_key("Results"));
    }

    #[test]
    fn write_excel_with_options_index_false_omits_index_column() {
        let frame = make_test_dataframe();
        let bytes = super::write_excel_bytes_with_options(
            &frame,
            &super::ExcelWriteOptions {
                index: false,
                ..super::ExcelWriteOptions::default()
            },
        )
        .expect("write");
        let frame2 =
            super::read_excel_bytes(&bytes, &super::ExcelReadOptions::default()).expect("read");
        // With index=false the first column is "ints" directly (no
        // anonymous leading index column).
        let names = frame2.column_names();
        assert_eq!(
            names.iter().map(|s| s.as_str()).collect::<Vec<_>>(),
            vec!["ints", "floats", "names"]
        );
    }

    #[test]
    fn write_excel_with_options_index_label_overrides_header() {
        let frame = make_test_dataframe();
        let bytes = super::write_excel_bytes_with_options(
            &frame,
            &super::ExcelWriteOptions {
                index_label: Some("row_id".to_string()),
                ..super::ExcelWriteOptions::default()
            },
        )
        .expect("write");
        let frame2 =
            super::read_excel_bytes(&bytes, &super::ExcelReadOptions::default()).expect("read");
        // The index column now shows up as "row_id" before the data columns.
        let names = frame2.column_names();
        assert_eq!(names[0], "row_id");
    }

    #[test]
    fn write_excel_with_options_header_false_omits_header_row() {
        let frame = make_test_dataframe();
        let bytes = super::write_excel_bytes_with_options(
            &frame,
            &super::ExcelWriteOptions {
                header: false,
                index: false,
                ..super::ExcelWriteOptions::default()
            },
        )
        .expect("write");
        // Without header, the reader treats row 0 as headers. We
        // expect the first data row to become the column names
        // instead of literal "ints"/"floats"/"names".
        let frame2 =
            super::read_excel_bytes(&bytes, &super::ExcelReadOptions::default()).expect("read");
        let names = frame2.column_names();
        let name_strs: Vec<&str> = names.iter().map(|s| s.as_str()).collect();
        assert!(!name_strs.contains(&"ints"));
    }

    #[test]
    fn write_excel_with_options_default_matches_write_excel_bytes() {
        let frame = make_test_dataframe();
        let default_bytes = super::write_excel_bytes(&frame).expect("default");
        let options_bytes =
            super::write_excel_bytes_with_options(&frame, &super::ExcelWriteOptions::default())
                .expect("options");
        assert_eq!(default_bytes, options_bytes);
    }

    #[test]
    fn excel_multiindex_roundtrip_with_explicit_index_cols() {
        let frame = make_row_multiindex_test_dataframe();
        let bytes =
            super::write_excel_bytes_with_options(&frame, &super::ExcelWriteOptions::default())
                .expect("write");
        let roundtrip = super::read_excel_bytes_with_index_cols(
            &bytes,
            &super::ExcelReadOptions::default(),
            &["region", "product", "year"],
        )
        .expect("read");

        assert!(roundtrip.equals(&frame));
        assert_eq!(roundtrip.row_multiindex(), frame.row_multiindex());
    }

    fn build_two_sheet_workbook_bytes() -> Vec<u8> {
        use rust_xlsxwriter::Workbook;
        let mut workbook = Workbook::new();
        let sheet1 = workbook.add_worksheet();
        sheet1.set_name("Alpha").expect("sheet name");
        sheet1.write_string(0, 0, "a").expect("header");
        sheet1.write_string(0, 1, "b").expect("header");
        sheet1.write_number(1, 0, 1.0).expect("data");
        sheet1.write_number(1, 1, 10.0).expect("data");
        sheet1.write_number(2, 0, 2.0).expect("data");
        sheet1.write_number(2, 1, 20.0).expect("data");

        let sheet2 = workbook.add_worksheet();
        sheet2.set_name("Bravo").expect("sheet name");
        sheet2.write_string(0, 0, "name").expect("header");
        sheet2.write_string(1, 0, "alice").expect("data");
        sheet2.write_string(2, 0, "bob").expect("data");

        let sheet3 = workbook.add_worksheet();
        sheet3.set_name("Charlie").expect("sheet name");
        sheet3.write_string(0, 0, "x").expect("header");
        sheet3.write_number(1, 0, 99.0).expect("data");

        workbook.save_to_buffer().expect("save")
    }

    #[test]
    fn read_excel_sheets_ordered_bytes_preserves_workbook_order() {
        // Workbook sheet order: Alpha, Bravo, Charlie. A sorted map
        // would still give Alpha/Bravo/Charlie alphabetically — but
        // pandas guarantees workbook order regardless of alphabetic
        // relationship, so this test uses a fixture where the ordered
        // result differs from sorted order.
        use rust_xlsxwriter::Workbook;
        let mut workbook = Workbook::new();
        let s1 = workbook.add_worksheet();
        s1.set_name("Zulu").expect("name");
        s1.write_string(0, 0, "v").expect("header");
        s1.write_number(1, 0, 1.0).expect("data");
        let s2 = workbook.add_worksheet();
        s2.set_name("Alpha").expect("name");
        s2.write_string(0, 0, "v").expect("header");
        s2.write_number(1, 0, 2.0).expect("data");
        let s3 = workbook.add_worksheet();
        s3.set_name("Mike").expect("name");
        s3.write_string(0, 0, "v").expect("header");
        s3.write_number(1, 0, 3.0).expect("data");
        let bytes = workbook.save_to_buffer().expect("save");

        let ordered = super::read_excel_sheets_ordered_bytes(
            &bytes,
            None,
            &super::ExcelReadOptions::default(),
        )
        .expect("read ordered");
        assert_eq!(
            ordered.iter().map(|(k, _)| k.as_str()).collect::<Vec<_>>(),
            vec!["Zulu", "Alpha", "Mike"],
            "ordered form preserves workbook order"
        );

        // Sorted form alphabetizes (existing contract for BTreeMap).
        let sorted =
            super::read_excel_sheets_bytes(&bytes, None, &super::ExcelReadOptions::default())
                .expect("read sorted");
        assert_eq!(
            sorted.keys().map(String::as_str).collect::<Vec<_>>(),
            vec!["Alpha", "Mike", "Zulu"],
            "BTreeMap form alphabetizes"
        );
    }

    #[test]
    fn read_excel_sheets_ordered_bytes_selected_subset_keeps_caller_order() {
        let bytes = build_two_sheet_workbook_bytes();
        // Caller-specified order: Charlie, Alpha — deliberately reversed
        // from workbook order. Pandas docs say sheet_name=[list] returns
        // a dict whose iteration reflects the argument order; we match.
        let req = vec!["Charlie".to_string(), "Alpha".to_string()];
        let ordered = super::read_excel_sheets_ordered_bytes(
            &bytes,
            Some(&req),
            &super::ExcelReadOptions::default(),
        )
        .expect("ordered subset");
        assert_eq!(
            ordered.iter().map(|(k, _)| k.as_str()).collect::<Vec<_>>(),
            vec!["Charlie", "Alpha"]
        );
    }

    #[test]
    fn read_excel_sheets_ordered_path_matches_bytes() {
        let bytes = build_two_sheet_workbook_bytes();
        let temp = std::env::temp_dir().join("fp_io_wrt3_ordered.xlsx");
        std::fs::write(&temp, &bytes).expect("write temp");
        let via_path =
            super::read_excel_sheets_ordered(&temp, None, &super::ExcelReadOptions::default())
                .expect("read path");
        let via_bytes = super::read_excel_sheets_ordered_bytes(
            &bytes,
            None,
            &super::ExcelReadOptions::default(),
        )
        .expect("read bytes");
        assert_eq!(
            via_path.iter().map(|(k, _)| k.clone()).collect::<Vec<_>>(),
            via_bytes.iter().map(|(k, _)| k.clone()).collect::<Vec<_>>()
        );
    }

    #[test]
    fn read_excel_sheets_bytes_all_sheets_returns_map() {
        let bytes = build_two_sheet_workbook_bytes();
        let sheets =
            super::read_excel_sheets_bytes(&bytes, None, &super::ExcelReadOptions::default())
                .expect("read sheets");
        assert_eq!(sheets.len(), 3);
        assert!(sheets.contains_key("Alpha"));
        assert!(sheets.contains_key("Bravo"));
        assert!(sheets.contains_key("Charlie"));

        let alpha = &sheets["Alpha"];
        assert_eq!(alpha.index().len(), 2);
        assert_eq!(alpha.column_names().len(), 2);

        let bravo = &sheets["Bravo"];
        assert_eq!(bravo.index().len(), 2);
        assert_eq!(
            bravo.column("name").unwrap().values()[0],
            Scalar::Utf8("alice".into())
        );
    }

    #[test]
    fn read_excel_sheets_bytes_selects_subset() {
        let bytes = build_two_sheet_workbook_bytes();
        let selected = vec!["Alpha".to_string(), "Charlie".to_string()];
        let sheets = super::read_excel_sheets_bytes(
            &bytes,
            Some(&selected),
            &super::ExcelReadOptions::default(),
        )
        .expect("read subset");
        assert_eq!(sheets.len(), 2);
        assert!(sheets.contains_key("Alpha"));
        assert!(sheets.contains_key("Charlie"));
        assert!(!sheets.contains_key("Bravo"));
    }

    #[test]
    fn read_excel_sheets_bytes_unknown_sheet_errors() {
        let bytes = build_two_sheet_workbook_bytes();
        let bogus = vec!["Zeta".to_string()];
        let err = super::read_excel_sheets_bytes(
            &bytes,
            Some(&bogus),
            &super::ExcelReadOptions::default(),
        )
        .unwrap_err();
        assert!(matches!(err, super::IoError::Excel(_)));
    }

    #[test]
    fn read_excel_sheets_path_matches_bytes() {
        let bytes = build_two_sheet_workbook_bytes();
        let temp = std::env::temp_dir().join("fp_io_9my2_multisheet.xlsx");
        std::fs::write(&temp, &bytes).expect("write temp");
        let via_path = super::read_excel_sheets(&temp, None, &super::ExcelReadOptions::default())
            .expect("read path");
        let via_bytes =
            super::read_excel_sheets_bytes(&bytes, None, &super::ExcelReadOptions::default())
                .expect("read bytes");
        assert_eq!(
            via_path.keys().collect::<Vec<_>>(),
            via_bytes.keys().collect::<Vec<_>>()
        );
    }

    #[test]
    fn excel_bytes_roundtrip() {
        let frame = make_test_dataframe();
        let bytes = super::write_excel_bytes(&frame).expect("write excel");
        assert!(!bytes.is_empty());

        let frame2 = super::read_excel_bytes(
            &bytes,
            &super::ExcelReadOptions {
                index_col: Some("column_0".into()),
                ..Default::default()
            },
        )
        .expect("read excel");
        assert_eq!(frame2.index().len(), 3);
        assert_eq!(frame2.index().labels(), frame.index().labels());
        assert_eq!(frame2.index().name(), None);
        // Excel preserves the write-time column order (ints, floats, names).
        assert_eq!(
            frame2
                .column_names()
                .iter()
                .map(|s| s.as_str())
                .collect::<Vec<_>>(),
            vec!["ints", "floats", "names"]
        );

        // Int values survive round-trip (Excel stores as f64, we recover Int64).
        let ints = frame2.column("ints").unwrap();
        assert_eq!(ints.values()[0], Scalar::Int64(10));
        assert_eq!(ints.values()[1], Scalar::Int64(20));
        assert_eq!(ints.values()[2], Scalar::Int64(30));

        // Float values survive round-trip.
        let floats = frame2.column("floats").unwrap();
        assert_eq!(floats.values()[0], Scalar::Float64(1.5));
        assert_eq!(floats.values()[1], Scalar::Float64(2.5));
        assert_eq!(floats.values()[2], Scalar::Float64(3.5));

        // String values survive round-trip.
        let names = frame2.column("names").unwrap();
        assert_eq!(names.values()[0], Scalar::Utf8("alice".into()));
        assert_eq!(names.values()[1], Scalar::Utf8("bob".into()));
        assert_eq!(names.values()[2], Scalar::Utf8("carol".into()));
    }

    #[test]
    fn excel_file_roundtrip() {
        let frame = make_test_dataframe();
        let dir = std::env::temp_dir();
        let path = dir.join("fp_io_test_excel_roundtrip.xlsx");

        super::write_excel(&frame, &path).expect("write excel file");
        let frame2 = super::read_excel(
            &path,
            &super::ExcelReadOptions {
                index_col: Some("column_0".into()),
                ..Default::default()
            },
        )
        .expect("read excel file");
        assert_eq!(frame2.index().len(), 3);
        assert_eq!(frame2.index().labels(), frame.index().labels());
        assert_eq!(
            frame2.column("ints").unwrap().values()[0],
            Scalar::Int64(10)
        );
        std::fs::remove_file(&path).ok();
    }

    #[test]
    fn excel_with_nulls() {
        use fp_types::DType;

        let mut columns = BTreeMap::new();
        columns.insert(
            "vals".to_string(),
            Column::new(
                DType::Float64,
                vec![
                    Scalar::Float64(1.0),
                    Scalar::Null(NullKind::NaN),
                    Scalar::Float64(3.0),
                ],
            )
            .unwrap(),
        );

        let labels = vec![
            IndexLabel::Int64(0),
            IndexLabel::Int64(1),
            IndexLabel::Int64(2),
        ];
        let frame =
            DataFrame::new_with_column_order(Index::new(labels), columns, vec!["vals".to_string()])
                .unwrap();

        let bytes = super::write_excel_bytes(&frame).expect("write");
        let frame2 = super::read_excel_bytes(
            &bytes,
            &super::ExcelReadOptions {
                index_col: Some("column_0".into()),
                ..Default::default()
            },
        )
        .expect("read");

        // Non-null values round-trip.
        assert_eq!(frame2.column("vals").unwrap().values()[0], Scalar::Int64(1));
        // NaN written as empty cell, read back as Null.
        assert!(frame2.column("vals").unwrap().values()[1].is_missing());
        assert_eq!(frame2.column("vals").unwrap().values()[2], Scalar::Int64(3));
    }

    #[test]
    fn excel_bool_column() {
        use fp_types::DType;

        let mut columns = BTreeMap::new();
        columns.insert(
            "flags".to_string(),
            Column::new(
                DType::Bool,
                vec![Scalar::Bool(true), Scalar::Bool(false), Scalar::Bool(true)],
            )
            .unwrap(),
        );

        let labels = vec![
            IndexLabel::Int64(0),
            IndexLabel::Int64(1),
            IndexLabel::Int64(2),
        ];
        let frame = DataFrame::new_with_column_order(
            Index::new(labels),
            columns,
            vec!["flags".to_string()],
        )
        .unwrap();

        let bytes = super::write_excel_bytes(&frame).expect("write");
        let frame2 = super::read_excel_bytes(
            &bytes,
            &super::ExcelReadOptions {
                index_col: Some("column_0".into()),
                ..Default::default()
            },
        )
        .expect("read");

        assert_eq!(
            frame2.column("flags").unwrap().values()[0],
            Scalar::Bool(true)
        );
        assert_eq!(
            frame2.column("flags").unwrap().values()[1],
            Scalar::Bool(false)
        );
        assert_eq!(
            frame2.column("flags").unwrap().values()[2],
            Scalar::Bool(true)
        );
    }

    #[test]
    fn excel_skip_rows() {
        // Build an xlsx with 5 data rows, then read with skip_rows=2 to skip
        // 2 rows before the header.
        use fp_types::DType;

        let mut columns = BTreeMap::new();
        columns.insert(
            "x".to_string(),
            Column::new(DType::Int64, vec![Scalar::Int64(1), Scalar::Int64(2)]).unwrap(),
        );
        let labels = vec![IndexLabel::Int64(0), IndexLabel::Int64(1)];
        let frame =
            DataFrame::new_with_column_order(Index::new(labels), columns, vec!["x".to_string()])
                .unwrap();

        let bytes = super::write_excel_bytes(&frame).expect("write");
        let frame2 = super::read_excel_bytes(
            &bytes,
            &super::ExcelReadOptions {
                skip_rows: 1,
                has_headers: false,
                ..Default::default()
            },
        )
        .expect("read with skip");

        // Skipped the header row, so first data row becomes first row.
        // With has_headers=false, column names are auto-generated.
        assert_eq!(frame2.index().len(), 2);
        assert!(frame2.column("column_0").is_some());
    }

    #[test]
    fn excel_header_none_with_explicit_names_uses_names_and_keeps_first_row() {
        let rows = vec![
            vec![
                calamine::Data::Int(1),
                calamine::Data::String("alpha".to_owned()),
            ],
            vec![
                calamine::Data::Int(2),
                calamine::Data::String("beta".to_owned()),
            ],
        ];

        let frame = super::parse_excel_rows(
            rows,
            &super::ExcelReadOptions {
                has_headers: false,
                names: Some(vec!["id".to_owned(), "label".to_owned()]),
                ..Default::default()
            },
        )
        .expect("parse excel rows with explicit names");

        assert_eq!(frame.column_names(), vec!["id", "label"]);
        assert_eq!(frame.index().len(), 2);
        assert_eq!(frame.column("id").unwrap().values()[0], Scalar::Int64(1));
        assert_eq!(
            frame.column("label").unwrap().values()[0],
            Scalar::Utf8("alpha".into())
        );
        assert_eq!(frame.column("id").unwrap().values()[1], Scalar::Int64(2));
    }

    #[test]
    fn excel_header_none_with_explicit_names_preserves_index_name() {
        let rows = vec![
            vec![
                calamine::Data::Int(10),
                calamine::Data::String("alpha".to_owned()),
            ],
            vec![
                calamine::Data::Int(20),
                calamine::Data::String("beta".to_owned()),
            ],
        ];

        let frame = super::parse_excel_rows(
            rows,
            &super::ExcelReadOptions {
                has_headers: false,
                names: Some(vec!["row_id".to_owned(), "value".to_owned()]),
                index_col: Some("row_id".to_owned()),
                ..Default::default()
            },
        )
        .expect("parse excel rows with named index column");

        assert_eq!(frame.index().name(), Some("row_id"));
        assert_eq!(frame.index().labels()[0], IndexLabel::Int64(10));
        assert_eq!(frame.index().labels()[1], IndexLabel::Int64(20));
        assert!(frame.column("row_id").is_none());
        assert_eq!(
            frame.column("value").unwrap().values(),
            &[Scalar::Utf8("alpha".into()), Scalar::Utf8("beta".into())]
        );
    }

    #[test]
    fn excel_explicit_names_width_mismatch_errors() {
        let rows = vec![vec![calamine::Data::Int(1), calamine::Data::Int(2)]];

        let err = super::parse_excel_rows(
            rows,
            &super::ExcelReadOptions {
                has_headers: false,
                names: Some(vec!["only_one".to_owned()]),
                ..Default::default()
            },
        )
        .expect_err("names width mismatch should error");

        assert!(
            matches!(err, IoError::Excel(message) if message.contains("expected 2 column names, got 1"))
        );
    }

    #[test]
    fn excel_usecols_selects_subset_in_sheet_order() {
        let rows = vec![
            vec![
                calamine::Data::String("a".to_owned()),
                calamine::Data::String("b".to_owned()),
                calamine::Data::String("c".to_owned()),
            ],
            vec![
                calamine::Data::Int(1),
                calamine::Data::Int(2),
                calamine::Data::Int(3),
            ],
        ];

        let frame = super::parse_excel_rows(
            rows,
            &super::ExcelReadOptions {
                usecols: Some(vec!["c".to_owned(), "a".to_owned()]),
                ..Default::default()
            },
        )
        .expect("parse excel rows with usecols");

        assert_eq!(frame.column_names(), vec!["a", "c"]);
        assert_eq!(frame.column("a").unwrap().values(), &[Scalar::Int64(1)]);
        assert_eq!(frame.column("c").unwrap().values(), &[Scalar::Int64(3)]);
        assert!(frame.column("b").is_none());
    }

    #[test]
    fn excel_usecols_with_explicit_names_filters_renamed_columns() {
        let rows = vec![
            vec![
                calamine::Data::Int(1),
                calamine::Data::String("alpha".to_owned()),
            ],
            vec![
                calamine::Data::Int(2),
                calamine::Data::String("beta".to_owned()),
            ],
        ];

        let frame = super::parse_excel_rows(
            rows,
            &super::ExcelReadOptions {
                has_headers: false,
                names: Some(vec!["id".to_owned(), "label".to_owned()]),
                usecols: Some(vec!["label".to_owned()]),
                ..Default::default()
            },
        )
        .expect("parse headerless excel rows with names and usecols");

        assert_eq!(frame.column_names(), vec!["label"]);
        assert_eq!(
            frame.column("label").unwrap().values(),
            &[Scalar::Utf8("alpha".into()), Scalar::Utf8("beta".into())]
        );
        assert!(frame.column("id").is_none());
    }

    #[test]
    fn excel_usecols_missing_column_errors() {
        let rows = vec![
            vec![
                calamine::Data::String("a".to_owned()),
                calamine::Data::String("b".to_owned()),
            ],
            vec![calamine::Data::Int(1), calamine::Data::Int(2)],
        ];

        let err = super::parse_excel_rows(
            rows,
            &super::ExcelReadOptions {
                usecols: Some(vec!["missing".to_owned()]),
                ..Default::default()
            },
        )
        .expect_err("missing excel usecols should error");

        assert!(
            matches!(err, IoError::MissingUsecols(missing) if missing == vec!["missing".to_owned()])
        );
    }

    #[test]
    fn excel_default_read_promotes_writer_range_index_back_to_index() {
        let frame = make_test_dataframe();
        let bytes = super::write_excel_bytes(&frame).expect("write excel");

        let frame2 = super::read_excel_bytes(&bytes, &super::ExcelReadOptions::default())
            .expect("read excel");

        assert_eq!(frame2.index().labels(), frame.index().labels());
        assert_eq!(frame2.index().name(), None);
        assert_eq!(frame2.column_names(), vec!["ints", "floats", "names"],);
        assert!(frame2.column("column_0").is_none());
    }

    #[test]
    fn excel_default_read_keeps_non_range_generated_leading_column_as_data() {
        let rows = vec![
            vec![
                calamine::Data::Empty,
                calamine::Data::String("value".to_owned()),
            ],
            vec![calamine::Data::Int(10), calamine::Data::Int(1)],
            vec![calamine::Data::Int(20), calamine::Data::Int(2)],
        ];

        let frame = super::parse_excel_rows(rows, &super::ExcelReadOptions::default())
            .expect("parse excel rows");

        assert_eq!(
            frame.index().labels(),
            &[IndexLabel::Int64(0), IndexLabel::Int64(1)]
        );
        assert_eq!(frame.column_names(), vec!["column_0", "value"]);
        assert_eq!(
            frame.column("column_0").unwrap().values(),
            &[Scalar::Int64(10), Scalar::Int64(20)],
        );
    }

    #[test]
    fn excel_named_index_roundtrip_preserves_index_name() {
        use fp_types::DType;

        let mut columns = BTreeMap::new();
        columns.insert(
            "vals".to_string(),
            Column::new(DType::Int64, vec![Scalar::Int64(10), Scalar::Int64(20)]).unwrap(),
        );

        let frame = DataFrame::new_with_column_order(
            Index::new(vec![IndexLabel::Int64(10), IndexLabel::Int64(20)]).set_name("row_id"),
            columns,
            vec!["vals".to_string()],
        )
        .unwrap();

        let bytes = super::write_excel_bytes(&frame).expect("write excel");
        let frame2 = super::read_excel_bytes(
            &bytes,
            &super::ExcelReadOptions {
                index_col: Some("row_id".into()),
                ..Default::default()
            },
        )
        .expect("read excel");

        assert_eq!(frame2.index().labels(), frame.index().labels());
        assert_eq!(frame2.index().name(), Some("row_id"));
        assert!(frame2.column("row_id").is_none());
        assert_eq!(
            frame2.column("vals").unwrap().values(),
            &[Scalar::Int64(10), Scalar::Int64(20)]
        );
    }

    #[test]
    fn excel_duplicate_headers_error() {
        let rows = vec![
            vec![
                calamine::Data::String("dup".to_owned()),
                calamine::Data::String("dup".to_owned()),
            ],
            vec![calamine::Data::Int(1), calamine::Data::Int(2)],
        ];

        let err = super::parse_excel_rows(rows, &super::ExcelReadOptions::default())
            .expect_err("duplicate headers should error");
        assert!(matches!(err, IoError::DuplicateColumnName(_)));
    }

    // ── SQL I/O tests ──────────────────────────────────────────────
    //
    // Per br-frankenpandas-7a49 (fd90.48): keep the import block
    // unconditional so stub-backend tests (which only need types and
    // free-fns, not rusqlite) compile under --no-default-features.
    // `#[allow(unused_imports)]` covers the few free fns that are
    // exclusively used inside the cfg-gated SQLite-backed tests.

    // Per fd90.48: TYPE imports + introspection-helper free fns are
    // used by both stub-backend tests (which compile under
    // --no-default-features) and SQLite-backed tests. The
    // read_sql_* / write_sql_* row-materialization free fns are only
    // exercised inside SQLite-backed tests (cfg-gated below) so they
    // get their own gated import group to avoid unused warnings.
    // Per fd90.48: TYPE imports + introspection-helper free fns +
    // write_sql / write_sql_with_options are used by both stub-backend
    // tests (which compile under --no-default-features) and
    // SQLite-backed tests. The read_sql_* row-materialization free fns
    // are only exercised inside SQLite-backed tests (cfg-gated below).
    use super::{
        SqlBackendCaps, SqlColumnSchema, SqlForeignKeySchema, SqlIfExists, SqlIndexSchema,
        SqlInsertMethod, SqlInspector, SqlQueryResult, SqlReadOptions, SqlReflectedTable,
        SqlTableSchema, SqlUniqueConstraintSchema, SqlWriteOptions, list_sql_foreign_keys,
        list_sql_indexes, list_sql_schemas, list_sql_tables, list_sql_unique_constraints,
        list_sql_views, sql_backend_caps, sql_max_identifier_length, sql_max_insert_rows,
        sql_max_param_count, sql_primary_key_columns, sql_server_version, sql_supports_returning,
        sql_supports_schemas, sql_table_comment, sql_table_schema, truncate_sql_table, write_sql,
        write_sql_with_options,
    };
    #[cfg(feature = "sql-sqlite")]
    use super::{
        read_sql, read_sql_chunks, read_sql_chunks_with_index_col, read_sql_chunks_with_options,
        read_sql_chunks_with_options_and_index_col, read_sql_query, read_sql_query_chunks,
        read_sql_query_chunks_with_index_col, read_sql_query_chunks_with_options,
        read_sql_query_chunks_with_options_and_index_col, read_sql_query_with_index_col,
        read_sql_query_with_options, read_sql_query_with_options_and_index_col, read_sql_table,
        read_sql_table_chunks, read_sql_table_chunks_with_index_col,
        read_sql_table_chunks_with_options, read_sql_table_chunks_with_options_and_index_col,
        read_sql_table_columns, read_sql_table_columns_chunks,
        read_sql_table_columns_chunks_with_index_col, read_sql_table_columns_with_index_col,
        read_sql_table_with_index_col, read_sql_table_with_options,
        read_sql_table_with_options_and_index_col, read_sql_with_index_col, read_sql_with_options,
    };

    // Per br-frankenpandas-7a49 (fd90.48): the helper itself only
    // exists when sql-sqlite is on, since it directly references
    // rusqlite::Connection. All tests that call this are also
    // cfg-gated on the same feature.
    #[cfg(feature = "sql-sqlite")]
    fn make_sql_test_conn() -> rusqlite::Connection {
        rusqlite::Connection::open_in_memory().expect("in-memory sqlite")
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_with_index_col_promotes_named_column() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "indexed_tbl", SqlIfExists::Fail).expect("write");

        // Promote the "ints" column to the row index. The data
        // columns should drop ints and the index labels should be the
        // ints values.
        let result = read_sql_table_with_index_col(&conn, "indexed_tbl", Some("ints"))
            .expect("read with index");
        assert_eq!(result.index().name(), Some("ints"));
        assert_eq!(result.index().labels()[0], crate::IndexLabel::Int64(10));
        assert_eq!(result.index().labels()[1], crate::IndexLabel::Int64(20));
        assert_eq!(result.index().labels()[2], crate::IndexLabel::Int64(30));
        // Data columns: only the non-index columns remain.
        let names: Vec<&str> = result.column_names().iter().map(|s| s.as_str()).collect();
        assert!(!names.contains(&"ints"));
        assert!(names.contains(&"floats"));
        assert!(names.contains(&"names"));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_with_index_col_none_is_unchanged() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "noindex_tbl", SqlIfExists::Fail).expect("write");
        let baseline = read_sql_table(&conn, "noindex_tbl").expect("baseline");
        let result =
            read_sql_table_with_index_col(&conn, "noindex_tbl", None).expect("noop variant");
        assert_eq!(result.index().labels(), baseline.index().labels());
        assert_eq!(result.column_names(), baseline.column_names());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_with_index_col_unknown_column_errors() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "missing_tbl", SqlIfExists::Fail).expect("write");
        let err = read_sql_table_with_index_col(&conn, "missing_tbl", Some("nope")).unwrap_err();
        assert!(matches!(err, crate::IoError::Sql(_)));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_columns_returns_requested_projection_in_order() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "proj_tbl", SqlIfExists::Fail).expect("write");

        let result = read_sql_table_columns(&conn, "proj_tbl", &["names", "ints"])
            .expect("subset projection");
        let names: Vec<&str> = result.column_names().iter().map(|s| s.as_str()).collect();
        assert_eq!(names, vec!["names", "ints"]);
        assert_eq!(result.index().len(), 3);
        assert_eq!(
            result.column("ints").unwrap().values()[0],
            Scalar::Int64(10)
        );
        assert_eq!(
            result.column("names").unwrap().values()[2],
            Scalar::Utf8("carol".into())
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_columns_single_column_projection() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "single_tbl", SqlIfExists::Fail).expect("write");

        let result =
            read_sql_table_columns(&conn, "single_tbl", &["floats"]).expect("single projection");
        let names: Vec<&str> = result.column_names().iter().map(|s| s.as_str()).collect();
        assert_eq!(names, vec!["floats"]);
        assert_eq!(
            result.column("floats").unwrap().values()[1],
            Scalar::Float64(2.5)
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_columns_rejects_empty_columns() {
        let conn = make_sql_test_conn();
        let err = read_sql_table_columns(&conn, "any_tbl", &[]).unwrap_err();
        assert!(matches!(err, crate::IoError::Sql(_)));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_columns_rejects_invalid_column_name() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "valid_tbl", SqlIfExists::Fail).expect("write");
        let err = read_sql_table_columns(&conn, "valid_tbl", &["ints; DROP TABLE valid_tbl"])
            .unwrap_err();
        assert!(matches!(err, crate::IoError::Sql(_)));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_columns_rejects_invalid_table_name() {
        let conn = make_sql_test_conn();
        let err = read_sql_table_columns(&conn, "bad table", &["ints"]).unwrap_err();
        assert!(matches!(err, crate::IoError::Sql(_)));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_columns_chunks_returns_requested_projection_in_order() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "proj_chunk_tbl", SqlIfExists::Fail).expect("write");

        let chunks = read_sql_table_columns_chunks(&conn, "proj_chunk_tbl", &["names", "ints"], 2)
            .expect("projection chunk iterator")
            .collect::<Result<Vec<_>, _>>()
            .expect("all chunks");

        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks[0].column_names(), vec!["names", "ints"]);
        assert_eq!(
            chunks[0].column("names").unwrap().values(),
            &[
                Scalar::Utf8("alice".to_owned()),
                Scalar::Utf8("bob".to_owned())
            ]
        );
        assert_eq!(
            chunks[1].column("ints").unwrap().values(),
            &[Scalar::Int64(30)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_columns_chunks_rejects_zero_chunksize() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "proj_zero_chunk_tbl", SqlIfExists::Fail).expect("write");

        let err = read_sql_table_columns_chunks(&conn, "proj_zero_chunk_tbl", &["names"], 0)
            .expect_err("zero projection chunksize should be rejected");

        assert!(matches!(err, IoError::Sql(msg) if msg.contains("chunksize")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_columns_chunks_rejects_invalid_projection_inputs() {
        let conn = make_sql_test_conn();

        let empty = read_sql_table_columns_chunks(&conn, "proj_chunk_tbl", &[], 1)
            .expect_err("empty projection should be rejected");
        assert!(matches!(empty, IoError::Sql(msg) if msg.contains("columns must be non-empty")));

        let invalid = read_sql_table_columns_chunks(&conn, "proj_chunk_tbl", &["bad column"], 1)
            .expect_err("invalid projection name should be rejected");
        assert!(matches!(invalid, IoError::Sql(msg) if msg.contains("invalid column name")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_columns_with_index_col_promotes_projected_column() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "proj_index_tbl", SqlIfExists::Fail).expect("write");

        let result = read_sql_table_columns_with_index_col(
            &conn,
            "proj_index_tbl",
            &["names", "ints"],
            Some("ints"),
        )
        .expect("projection with index_col");

        assert_eq!(result.index().name(), Some("ints"));
        assert_eq!(
            result.index().labels(),
            &[
                IndexLabel::Int64(10),
                IndexLabel::Int64(20),
                IndexLabel::Int64(30)
            ]
        );
        assert_eq!(result.column_names(), vec!["names"]);
        assert_eq!(
            result.column("names").unwrap().values(),
            &[
                Scalar::Utf8("alice".to_owned()),
                Scalar::Utf8("bob".to_owned()),
                Scalar::Utf8("carol".to_owned())
            ]
        );
        assert!(result.column("ints").is_none());
    }

    // br-frankenpandas-6n0uz: when index_col is set but NOT in columns,
    // pandas auto-projects it into the SELECT (then drops it from data
    // columns after promotion). Mirrors fd90.76's behavior on the
    // options-based reader.
    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_columns_with_index_col_auto_projects_when_absent() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "auto_proj_tbl", SqlIfExists::Fail).expect("write");

        // index_col "ints" is NOT in columns — must be auto-projected, then
        // promoted to the index, then removed from the data columns.
        let result =
            read_sql_table_columns_with_index_col(&conn, "auto_proj_tbl", &["names"], Some("ints"))
                .expect("auto-project index_col");

        assert_eq!(result.index().name(), Some("ints"));
        assert_eq!(
            result.index().labels(),
            &[
                IndexLabel::Int64(10),
                IndexLabel::Int64(20),
                IndexLabel::Int64(30)
            ]
        );
        assert_eq!(result.column_names(), vec!["names"]);
        assert!(result.column("ints").is_none());
        assert_eq!(
            result.column("names").unwrap().values(),
            &[
                Scalar::Utf8("alice".to_owned()),
                Scalar::Utf8("bob".to_owned()),
                Scalar::Utf8("carol".to_owned())
            ]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_columns_chunks_with_index_col_auto_projects_when_absent() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "auto_proj_chunks_tbl", SqlIfExists::Fail).expect("write");

        // index_col "ints" is NOT in columns — must be auto-projected per
        // chunk and dropped from each chunk's data columns.
        let chunks = read_sql_table_columns_chunks_with_index_col(
            &conn,
            "auto_proj_chunks_tbl",
            &["names"],
            Some("ints"),
            2,
        )
        .expect("auto-project chunks")
        .collect::<Result<Vec<_>, _>>()
        .expect("all chunks");

        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks[0].index().name(), Some("ints"));
        assert_eq!(
            chunks[0].index().labels(),
            &[IndexLabel::Int64(10), IndexLabel::Int64(20)]
        );
        assert_eq!(chunks[0].column_names(), vec!["names"]);
        assert!(chunks[0].column("ints").is_none());
        assert_eq!(
            chunks[0].column("names").unwrap().values(),
            &[
                Scalar::Utf8("alice".to_owned()),
                Scalar::Utf8("bob".to_owned())
            ]
        );
        assert_eq!(chunks[1].index().labels(), &[IndexLabel::Int64(30)]);
        assert_eq!(chunks[1].column_names(), vec!["names"]);
        assert!(chunks[1].column("ints").is_none());
    }

    // br-frankenpandas-6n0uz: idempotency check — when index_col IS already
    // in columns, the auto-project helper must not duplicate it. Same final
    // result as the original explicit-include test, but proves the helper's
    // dedupe path.
    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_columns_with_index_col_no_duplication_when_listed() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "no_dup_tbl", SqlIfExists::Fail).expect("write");

        // index_col "ints" IS in columns — must NOT be duplicated in SELECT.
        let result = read_sql_table_columns_with_index_col(
            &conn,
            "no_dup_tbl",
            &["names", "ints"],
            Some("ints"),
        )
        .expect("explicit include + index_col");

        assert_eq!(result.index().name(), Some("ints"));
        assert_eq!(result.column_names(), vec!["names"]);
        assert!(result.column("ints").is_none());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_columns_with_index_col_none_keeps_projection_and_range_index() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "proj_no_index_tbl", SqlIfExists::Fail).expect("write");

        let result = read_sql_table_columns_with_index_col(
            &conn,
            "proj_no_index_tbl",
            &["floats", "names"],
            None,
        )
        .expect("projection without index_col");

        assert_eq!(
            result.index().labels(),
            &[
                IndexLabel::Int64(0),
                IndexLabel::Int64(1),
                IndexLabel::Int64(2)
            ]
        );
        assert_eq!(result.column_names(), vec!["floats", "names"]);
        assert_eq!(
            result.column("floats").unwrap().values()[1],
            Scalar::Float64(2.5)
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_columns_chunks_with_index_col_promotes_each_chunk_index() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "proj_index_chunk_tbl", SqlIfExists::Fail).expect("write");

        let chunks = read_sql_table_columns_chunks_with_index_col(
            &conn,
            "proj_index_chunk_tbl",
            &["ints", "names"],
            Some("ints"),
            2,
        )
        .expect("indexed projection chunk iterator")
        .collect::<Result<Vec<_>, _>>()
        .expect("all chunks");

        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks[0].index().name(), Some("ints"));
        assert_eq!(
            chunks[0].index().labels(),
            &[IndexLabel::Int64(10), IndexLabel::Int64(20)]
        );
        assert_eq!(chunks[0].column_names(), vec!["names"]);
        assert_eq!(
            chunks[0].column("names").unwrap().values(),
            &[
                Scalar::Utf8("alice".to_owned()),
                Scalar::Utf8("bob".to_owned())
            ]
        );
        assert_eq!(chunks[1].index().labels(), &[IndexLabel::Int64(30)]);
        assert_eq!(
            chunks[1].column("names").unwrap().values(),
            &[Scalar::Utf8("carol".to_owned())]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_columns_chunks_with_index_col_validates_projection_and_index() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "proj_index_error_tbl", SqlIfExists::Fail).expect("write");

        let empty = read_sql_table_columns_chunks_with_index_col(
            &conn,
            "proj_index_error_tbl",
            &[],
            Some("ints"),
            1,
        )
        .expect_err("empty projection should be rejected");
        assert!(matches!(empty, IoError::Sql(msg) if msg.contains("columns must be non-empty")));

        let invalid = read_sql_table_columns_with_index_col(
            &conn,
            "proj_index_error_tbl",
            &["bad column"],
            Some("ints"),
        )
        .expect_err("invalid projection name should be rejected");
        assert!(matches!(invalid, IoError::Sql(msg) if msg.contains("invalid column name")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_query_with_index_col_works_on_arbitrary_select() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "queried_tbl", SqlIfExists::Fail).expect("write");
        let result = read_sql_with_index_col(
            &conn,
            "SELECT names AS label, ints, floats FROM queried_tbl ORDER BY ints DESC",
            Some("label"),
        )
        .expect("read query with index");
        assert_eq!(result.index().name(), Some("label"));
        // Order respected by the SELECT (ints DESC) → index labels in
        // reversed name order.
        assert_eq!(
            result.index().labels()[0],
            crate::IndexLabel::Utf8("carol".into())
        );
        assert_eq!(
            result.index().labels()[2],
            crate::IndexLabel::Utf8("alice".into())
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_write_read_roundtrip() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();

        write_sql(&frame, &conn, "test_table", SqlIfExists::Fail).expect("write sql");

        let frame2 = read_sql_table(&conn, "test_table").expect("read sql");
        assert_eq!(frame2.index().len(), 3);

        // Int values survive round-trip.
        let ints = frame2.column("ints").unwrap();
        assert_eq!(ints.values()[0], Scalar::Int64(10));
        assert_eq!(ints.values()[1], Scalar::Int64(20));
        assert_eq!(ints.values()[2], Scalar::Int64(30));

        // Float values survive round-trip.
        let floats = frame2.column("floats").unwrap();
        assert_eq!(floats.values()[0], Scalar::Float64(1.5));
        assert_eq!(floats.values()[1], Scalar::Float64(2.5));
        assert_eq!(floats.values()[2], Scalar::Float64(3.5));

        // String values survive round-trip.
        let names = frame2.column("names").unwrap();
        assert_eq!(names.values()[0], Scalar::Utf8("alice".into()));
        assert_eq!(names.values()[1], Scalar::Utf8("bob".into()));
        assert_eq!(names.values()[2], Scalar::Utf8("carol".into()));
    }

    #[derive(Default)]
    struct DollarMarkerSqlConn {
        insert_sql: std::cell::RefCell<Vec<String>>,
        inserted_rows: std::cell::RefCell<Vec<Vec<Vec<Scalar>>>>,
    }

    impl super::SqlConnection for DollarMarkerSqlConn {
        fn query(
            &self,
            _query: &str,
            _params: &[Scalar],
        ) -> Result<super::SqlQueryResult, IoError> {
            Err(IoError::Sql("mock connection does not read".to_owned()))
        }

        fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
            Ok(())
        }

        fn table_exists(&self, _table_name: &str) -> Result<bool, IoError> {
            Ok(false)
        }

        fn insert_rows(&self, insert_sql: &str, rows: &[Vec<Scalar>]) -> Result<(), IoError> {
            self.insert_sql.borrow_mut().push(insert_sql.to_owned());
            self.inserted_rows.borrow_mut().push(rows.to_vec());
            Ok(())
        }

        fn dtype_sql(&self, dtype: DType) -> &'static str {
            match dtype {
                DType::Int64
                | DType::Int64Nullable
                | DType::Bool
                | DType::BoolNullable
                | DType::Timedelta64
                | DType::Datetime64 => "BIGINT",
                DType::Float64 => "DOUBLE PRECISION",
                DType::Utf8
                | DType::Categorical
                | DType::Null
                | DType::Sparse
                | DType::Period
                | DType::Interval => "TEXT",
            }
        }

        fn index_dtype_sql(&self, _index: &Index) -> &'static str {
            "TEXT"
        }

        fn parameter_marker(&self, ordinal: usize) -> String {
            format!("${ordinal}")
        }
    }

    #[test]
    fn sql_query_builders_quote_select_and_projection_identifiers() {
        let conn = DollarMarkerSqlConn::default();
        assert_eq!(
            super::sql_select_all_query(&conn, "portable_tbl").expect("select all query"),
            "SELECT * FROM \"portable_tbl\""
        );
        assert_eq!(
            super::sql_select_columns_query(&conn, "portable_tbl", &["names", "ints"])
                .expect("projection query"),
            "SELECT \"names\", \"ints\" FROM \"portable_tbl\""
        );

        let err = super::sql_select_columns_query(&conn, "portable_tbl", &["bad column"])
            .expect_err("projection identifiers stay validated");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("invalid column name")));
    }

    #[test]
    fn sql_query_builders_create_and_insert_use_backend_contracts() {
        let conn = DollarMarkerSqlConn::default();
        let column_defs = vec![
            super::sql_column_definition(&conn, "row id", "TEXT").expect("index column definition"),
            super::sql_column_definition(&conn, "value\"raw", "BIGINT")
                .expect("value column definition"),
        ];

        assert_eq!(
            super::sql_create_table_query(&conn, "typed_tbl", &column_defs)
                .expect("create table query"),
            "CREATE TABLE IF NOT EXISTS \"typed_tbl\" (\"row id\" TEXT, \"value\"\"raw\" BIGINT)"
        );

        let insert_columns = vec!["row id".to_owned(), "value\"raw".to_owned()];
        assert_eq!(
            super::sql_insert_rows_query(&conn, "typed_tbl", &insert_columns)
                .expect("insert row query"),
            "INSERT INTO \"typed_tbl\" (\"row id\", \"value\"\"raw\") VALUES ($1, $2)"
        );
    }

    /// Verify that quote_identifier overrides on a custom backend ACTUALLY
    /// flow through the helper functions (br-frankenpandas-cx2x / fd90.12).
    /// A MySQL-style backend that returns backticks must produce backticked
    /// identifiers in CREATE / SELECT / INSERT statements without any
    /// further plumbing.
    #[test]
    fn sql_query_builders_use_backend_quote_identifier_override() {
        #[derive(Default)]
        struct BacktickSqlConn;
        impl super::SqlConnection for BacktickSqlConn {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn quote_identifier(&self, ident: &str) -> Result<String, IoError> {
                if ident.contains('\0') {
                    return Err(IoError::Sql("invalid SQL identifier: NUL byte".to_owned()));
                }
                // MySQL-style backtick quoting; embedded backticks doubled.
                Ok(format!("`{}`", ident.replace('`', "``")))
            }
        }

        let conn = BacktickSqlConn;
        // SELECT / projection helpers flow through quote_identifier.
        assert_eq!(
            super::sql_select_all_query(&conn, "users").expect("select all"),
            "SELECT * FROM `users`"
        );
        assert_eq!(
            super::sql_select_columns_query(&conn, "users", &["id", "name"]).expect("projection"),
            "SELECT `id`, `name` FROM `users`"
        );
        // CREATE / INSERT helpers flow through quote_identifier.
        let col_defs = vec![super::sql_column_definition(&conn, "id", "INTEGER").expect("col def")];
        assert_eq!(
            super::sql_create_table_query(&conn, "users", &col_defs).expect("create"),
            "CREATE TABLE IF NOT EXISTS `users` (`id` INTEGER)"
        );
        let insert_cols = vec!["id".to_owned(), "name".to_owned()];
        assert_eq!(
            super::sql_insert_rows_query(&conn, "users", &insert_cols).expect("insert"),
            "INSERT INTO `users` (`id`, `name`) VALUES (?, ?)"
        );
    }

    #[test]
    fn sql_write_uses_backend_parameter_markers() {
        let frame = make_test_dataframe();
        let conn = DollarMarkerSqlConn::default();

        write_sql(&frame, &conn, "portable_tbl", SqlIfExists::Fail)
            .expect("write through marker-aware mock backend");

        let insert_sql = conn.insert_sql.borrow();
        assert_eq!(
            insert_sql.as_slice(),
            &["INSERT INTO \"portable_tbl\" (\"ints\", \"floats\", \"names\") VALUES ($1, $2, $3)"
                .to_owned()]
        );
        let inserted_rows = conn.inserted_rows.borrow();
        assert_eq!(inserted_rows[0].len(), frame.index().len());
        assert_eq!(inserted_rows[0][0][0], Scalar::Int64(10));
        assert_eq!(inserted_rows[0][2][2], Scalar::Utf8("carol".into()));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_write_with_options_includes_named_index_column() {
        let mut columns = BTreeMap::new();
        columns.insert(
            "vals".to_string(),
            Column::new(DType::Int64, vec![Scalar::Int64(10), Scalar::Int64(20)]).unwrap(),
        );

        let frame = DataFrame::new_with_column_order(
            Index::new(vec![IndexLabel::Int64(101), IndexLabel::Int64(102)]).set_name("row_id"),
            columns,
            vec!["vals".to_string()],
        )
        .unwrap();
        let conn = make_sql_test_conn();

        write_sql_with_options(
            &frame,
            &conn,
            "indexed_write_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: true,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect("write with named index");

        let roundtrip = read_sql_table_with_index_col(&conn, "indexed_write_tbl", Some("row_id"))
            .expect("read with promoted index");
        assert_eq!(roundtrip.index().name(), Some("row_id"));
        assert_eq!(roundtrip.index().labels(), frame.index().labels());
        assert!(roundtrip.column("row_id").is_none());
        assert_eq!(
            roundtrip.column("vals").unwrap().values(),
            &[Scalar::Int64(10), Scalar::Int64(20)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_write_with_options_unnamed_index_defaults_to_index_column_name() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();

        write_sql_with_options(
            &frame,
            &conn,
            "default_index_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: true,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect("write with unnamed index");

        let raw = read_sql_table(&conn, "default_index_tbl").expect("read raw table");
        assert!(raw.column("index").is_some());
        assert_eq!(raw.column("index").unwrap().values()[0], Scalar::Int64(0));
        assert_eq!(raw.column("index").unwrap().values()[2], Scalar::Int64(2));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_write_with_options_index_label_overrides_name() {
        let mut columns = BTreeMap::new();
        columns.insert(
            "vals".to_string(),
            Column::new(DType::Int64, vec![Scalar::Int64(7), Scalar::Int64(8)]).unwrap(),
        );

        let frame = DataFrame::new_with_column_order(
            Index::new(vec![IndexLabel::Int64(1), IndexLabel::Int64(2)]).set_name("row_id"),
            columns,
            vec!["vals".to_string()],
        )
        .unwrap();
        let conn = make_sql_test_conn();

        write_sql_with_options(
            &frame,
            &conn,
            "override_index_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: true,
                index_label: Some("custom_id".to_string()),
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect("write with custom index label");

        let raw = read_sql_table(&conn, "override_index_tbl").expect("read raw table");
        assert!(raw.column("custom_id").is_some());
        assert!(raw.column("row_id").is_none());
        assert_eq!(
            raw.column("custom_id").unwrap().values()[0],
            Scalar::Int64(1)
        );
        assert_eq!(
            raw.column("custom_id").unwrap().values()[1],
            Scalar::Int64(2)
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_write_with_options_index_false_omits_index_column() {
        let mut columns = BTreeMap::new();
        columns.insert(
            "vals".to_string(),
            Column::new(DType::Int64, vec![Scalar::Int64(5), Scalar::Int64(6)]).unwrap(),
        );

        let frame = DataFrame::new_with_column_order(
            Index::new(vec![IndexLabel::Int64(9), IndexLabel::Int64(10)]).set_name("row_id"),
            columns,
            vec!["vals".to_string()],
        )
        .unwrap();
        let conn = make_sql_test_conn();

        write_sql_with_options(
            &frame,
            &conn,
            "no_index_write_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: Some("custom_id".to_string()),
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect("write without index");

        let raw = read_sql_table(&conn, "no_index_write_tbl").expect("read raw table");
        assert!(raw.column("row_id").is_none());
        assert!(raw.column("custom_id").is_none());
        let names: Vec<&str> = raw
            .column_names()
            .iter()
            .map(|name| name.as_str())
            .collect();
        assert_eq!(names, vec!["vals"]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_with_query() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "data", SqlIfExists::Fail).unwrap();

        let filtered = read_sql(&conn, "SELECT ints, names FROM data WHERE ints > 15").unwrap();
        assert_eq!(filtered.index().len(), 2); // rows with ints=20,30
        assert_eq!(
            filtered.column("ints").unwrap().values()[0],
            Scalar::Int64(20)
        );
        assert_eq!(
            filtered.column("names").unwrap().values()[1],
            Scalar::Utf8("carol".into())
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_query_alias_matches_read_sql_query_path() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "data", SqlIfExists::Fail).unwrap();

        let queried = read_sql_query(
            &conn,
            "SELECT names, ints FROM data WHERE ints >= 20 ORDER BY ints",
        )
        .unwrap();

        assert_eq!(queried.column_names(), vec!["names", "ints"]);
        assert_eq!(queried.index().len(), 2);
        assert_eq!(
            queried.column("names").unwrap().values(),
            &[
                Scalar::Utf8("bob".to_owned()),
                Scalar::Utf8("carol".to_owned())
            ]
        );
        assert_eq!(
            queried.column("ints").unwrap().values(),
            &[Scalar::Int64(20), Scalar::Int64(30)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_query_with_options_applies_params_and_parse_dates() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE events (ts TEXT, value INTEGER);
             INSERT INTO events (ts, value) VALUES
                ('2024-01-15', 1),
                ('2024-02-01 05:06:07', 2),
                ('2024-03-03', 3);",
        )
        .expect("create events table");

        let frame = read_sql_query_with_options(
            &conn,
            "SELECT ts, value FROM events WHERE value > ? ORDER BY value",
            &SqlReadOptions {
                params: Some(vec![Scalar::Int64(1)]),
                parse_dates: Some(vec!["ts".to_owned()]),
                coerce_float: false,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
        )
        .expect("read_sql_query with options");

        assert_eq!(frame.column_names(), vec!["ts", "value"]);
        assert_eq!(
            frame.column("ts").unwrap().values(),
            &[
                Scalar::Utf8("2024-02-01 05:06:07".to_owned()),
                Scalar::Utf8("2024-03-03 00:00:00".to_owned())
            ]
        );
        assert_eq!(
            frame.column("value").unwrap().values(),
            &[Scalar::Int64(2), Scalar::Int64(3)]
        );
    }

    #[test]
    fn sql_read_query_with_options_and_index_col_uses_generic_connection() {
        use std::cell::RefCell;

        struct RecordingSqlConn {
            seen_query: RefCell<Option<String>>,
            seen_params: RefCell<Vec<Scalar>>,
        }

        impl super::SqlConnection for RecordingSqlConn {
            fn query(&self, query: &str, params: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                *self.seen_query.borrow_mut() = Some(query.to_owned());
                *self.seen_params.borrow_mut() = params.to_vec();
                Ok(SqlQueryResult {
                    columns: vec![
                        "row_id".to_owned(),
                        "ts".to_owned(),
                        "amount".to_owned(),
                        "label".to_owned(),
                    ],
                    rows: vec![
                        vec![
                            Scalar::Int64(101),
                            Scalar::Utf8("2024-01-15".to_owned()),
                            Scalar::Utf8("$1.25".to_owned()),
                            Scalar::Utf8("alpha".to_owned()),
                        ],
                        vec![
                            Scalar::Int64(102),
                            Scalar::Utf8("2024-01-16".to_owned()),
                            Scalar::Utf8("2.50".to_owned()),
                            Scalar::Utf8("beta".to_owned()),
                        ],
                    ],
                })
            }

            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }

            fn table_exists(&self, _table_name: &str) -> Result<bool, IoError> {
                Ok(false)
            }

            fn insert_rows(&self, _insert_sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }

            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }

            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "BIGINT"
            }
        }

        let conn = RecordingSqlConn {
            seen_query: RefCell::new(None),
            seen_params: RefCell::new(Vec::new()),
        };
        let query = "SELECT row_id, ts, amount, label FROM events WHERE amount > ?";
        let frame = super::read_sql_query_with_options_and_index_col(
            &conn,
            query,
            &SqlReadOptions {
                params: Some(vec![Scalar::Float64(1.0)]),
                parse_dates: Some(vec!["ts".to_owned()]),
                coerce_float: true,
                dtype: None,
                schema: None,
                columns: None,
                index_col: Some("amount".to_owned()),
            },
            Some("row_id"),
        )
        .expect("generic read_sql query with options and index_col");

        assert_eq!(conn.seen_query.borrow().as_deref(), Some(query));
        assert_eq!(
            conn.seen_params.borrow().as_slice(),
            &[Scalar::Float64(1.0)]
        );
        assert_eq!(frame.index().name(), Some("row_id"));
        assert_eq!(
            frame.index().labels(),
            &[IndexLabel::Int64(101), IndexLabel::Int64(102)]
        );
        assert_eq!(frame.column_names(), vec!["ts", "amount", "label"]);
        assert_eq!(
            frame.column("ts").unwrap().values(),
            &[
                Scalar::Utf8("2024-01-15 00:00:00".to_owned()),
                Scalar::Utf8("2024-01-16 00:00:00".to_owned())
            ]
        );
        assert_eq!(
            frame.column("amount").unwrap().values(),
            &[Scalar::Float64(1.25), Scalar::Float64(2.5)]
        );
        assert_eq!(
            frame.column("label").unwrap().values(),
            &[
                Scalar::Utf8("alpha".to_owned()),
                Scalar::Utf8("beta".to_owned())
            ]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_query_with_index_col_promotes_named_column() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "data", SqlIfExists::Fail).unwrap();

        let indexed = read_sql_query_with_index_col(
            &conn,
            "SELECT names, ints FROM data ORDER BY ints",
            Some("names"),
        )
        .unwrap();

        assert_eq!(
            indexed.index().labels(),
            &[
                IndexLabel::Utf8("alice".to_owned()),
                IndexLabel::Utf8("bob".to_owned()),
                IndexLabel::Utf8("carol".to_owned())
            ]
        );
        assert_eq!(indexed.index().name(), Some("names"));
        assert!(indexed.column("names").is_none());
        assert_eq!(
            indexed.column("ints").unwrap().values(),
            &[Scalar::Int64(10), Scalar::Int64(20), Scalar::Int64(30)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_query_chunks_alias_batches_rows() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE query_chunked (id INTEGER, name TEXT);
             INSERT INTO query_chunked (id, name) VALUES
                (1, 'alpha'),
                (2, 'beta'),
                (3, 'gamma');",
        )
        .expect("create query_chunked table");

        let chunks =
            read_sql_query_chunks(&conn, "SELECT id, name FROM query_chunked ORDER BY id", 2)
                .expect("query chunk iterator")
                .collect::<Result<Vec<_>, _>>()
                .expect("all chunks");

        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks[0].column_names(), vec!["id", "name"]);
        assert_eq!(
            chunks[0].column("id").unwrap().values(),
            &[Scalar::Int64(1), Scalar::Int64(2)]
        );
        assert_eq!(
            chunks[1].column("name").unwrap().values(),
            &[Scalar::Utf8("gamma".to_owned())]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_query_chunks_with_options_applies_params_parse_dates_and_coerce_float() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE query_events (ts TEXT, amount TEXT, keep INTEGER);
             INSERT INTO query_events (ts, amount, keep) VALUES
                ('2024-01-15', '12.50', 0),
                ('2024-02-01 05:06:07', '$1,234.50', 1),
                ('2024-03-03', '-3.25', 1);",
        )
        .expect("create query_events table");

        let chunks = read_sql_query_chunks_with_options(
            &conn,
            "SELECT ts, amount FROM query_events WHERE keep = ? ORDER BY ts",
            &SqlReadOptions {
                params: Some(vec![Scalar::Int64(1)]),
                parse_dates: Some(vec!["ts".to_owned()]),
                coerce_float: true,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
            1,
        )
        .expect("query chunk iterator")
        .collect::<Result<Vec<_>, _>>()
        .expect("all chunks");

        assert_eq!(chunks.len(), 2);
        assert_eq!(
            chunks[0].column("ts").unwrap().values(),
            &[Scalar::Utf8("2024-02-01 05:06:07".to_owned())]
        );
        assert_eq!(
            chunks[0].column("amount").unwrap().values(),
            &[Scalar::Float64(1234.5)]
        );
        assert_eq!(
            chunks[1].column("ts").unwrap().values(),
            &[Scalar::Utf8("2024-03-03 00:00:00".to_owned())]
        );
        assert_eq!(
            chunks[1].column("amount").unwrap().values(),
            &[Scalar::Float64(-3.25)]
        );
    }

    #[test]
    fn sql_read_chunks_uses_paged_queries_when_backend_opts_in() {
        use std::cell::RefCell;

        struct PagedChunksConn {
            queries: RefCell<Vec<(String, Vec<Scalar>)>>,
            rows: Vec<Vec<Scalar>>,
        }

        impl PagedChunksConn {
            fn page_bounds(params: &[Scalar]) -> (usize, usize) {
                let [
                    Scalar::Int64(1),
                    Scalar::Int64(limit),
                    Scalar::Int64(offset),
                ] = params
                else {
                    assert_eq!(
                        params,
                        &[Scalar::Int64(1), Scalar::Int64(0), Scalar::Int64(0),],
                        "expected original param plus LIMIT/OFFSET params"
                    );
                    return (0, 0);
                };
                (
                    usize::try_from(*limit).expect("non-negative limit"),
                    usize::try_from(*offset).expect("non-negative offset"),
                )
            }
        }

        impl super::SqlConnection for PagedChunksConn {
            fn query(&self, query: &str, params: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                self.queries
                    .borrow_mut()
                    .push((query.to_owned(), params.to_vec()));
                assert!(
                    query.contains("frankenpandas_sql_chunk_source")
                        && query.contains("LIMIT ? OFFSET ?"),
                    "paged chunk path should wrap the caller query with LIMIT/OFFSET, got {query}"
                );

                let (limit, offset) = Self::page_bounds(params);
                let rows = self.rows.iter().skip(offset).take(limit).cloned().collect();
                Ok(SqlQueryResult {
                    columns: vec!["id".to_owned(), "name".to_owned()],
                    rows,
                })
            }

            fn supports_paged_sql_chunks(&self) -> bool {
                true
            }

            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }

            fn table_exists(&self, _table_name: &str) -> Result<bool, IoError> {
                Ok(false)
            }

            fn insert_rows(&self, _insert_sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }

            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }

            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }

        let conn = PagedChunksConn {
            queries: RefCell::new(Vec::new()),
            rows: vec![
                vec![Scalar::Int64(1), Scalar::Utf8("a".to_owned())],
                vec![Scalar::Int64(2), Scalar::Utf8("b".to_owned())],
                vec![Scalar::Int64(3), Scalar::Utf8("c".to_owned())],
                vec![Scalar::Int64(4), Scalar::Utf8("d".to_owned())],
                vec![Scalar::Int64(5), Scalar::Utf8("e".to_owned())],
            ],
        };

        let chunks = read_sql_chunks_with_options(
            &conn,
            "SELECT id, name FROM paged_source WHERE keep = ? ORDER BY id;",
            &SqlReadOptions {
                params: Some(vec![Scalar::Int64(1)]),
                ..SqlReadOptions::default()
            },
            2,
        )
        .expect("paged chunk iterator")
        .collect::<Result<Vec<_>, _>>()
        .expect("all chunks");

        assert_eq!(chunks.len(), 3);
        assert_eq!(
            chunks[0].column("id").unwrap().values(),
            &[Scalar::Int64(1), Scalar::Int64(2)]
        );
        assert_eq!(
            chunks[1].column("id").unwrap().values(),
            &[Scalar::Int64(3), Scalar::Int64(4)]
        );
        assert_eq!(
            chunks[2].column("name").unwrap().values(),
            &[Scalar::Utf8("e".to_owned())]
        );

        let queries = conn.queries.borrow();
        let expected_params = vec![
            vec![Scalar::Int64(1), Scalar::Int64(0), Scalar::Int64(0)],
            vec![Scalar::Int64(1), Scalar::Int64(2), Scalar::Int64(0)],
            vec![Scalar::Int64(1), Scalar::Int64(2), Scalar::Int64(2)],
            vec![Scalar::Int64(1), Scalar::Int64(2), Scalar::Int64(4)],
        ];
        assert_eq!(
            queries
                .iter()
                .map(|(_, params)| params.clone())
                .collect::<Vec<_>>(),
            expected_params
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_query_chunks_with_options_and_index_col_applies_options_before_indexing() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE query_index_events (ts TEXT, amount TEXT, keep INTEGER);
             INSERT INTO query_index_events (ts, amount, keep) VALUES
                ('2024-01-15', '12.50', 0),
                ('2024-02-01 05:06:07', '$1,234.50', 1),
                ('2024-03-03', '-3.25', 1);",
        )
        .expect("create query_index_events table");

        let chunks = read_sql_query_chunks_with_options_and_index_col(
            &conn,
            "SELECT ts, amount FROM query_index_events WHERE keep = ? ORDER BY ts",
            &SqlReadOptions {
                params: Some(vec![Scalar::Int64(1)]),
                parse_dates: Some(vec!["ts".to_owned()]),
                coerce_float: true,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
            Some("ts"),
            1,
        )
        .expect("indexed query chunk iterator")
        .collect::<Result<Vec<_>, _>>()
        .expect("all chunks");

        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks[0].index().name(), Some("ts"));
        assert_eq!(
            chunks[0].index().labels(),
            &[IndexLabel::Utf8("2024-02-01 05:06:07".to_owned())]
        );
        assert!(chunks[0].column("ts").is_none());
        assert_eq!(
            chunks[0].column("amount").unwrap().values(),
            &[Scalar::Float64(1234.5)]
        );
        assert_eq!(
            chunks[1].index().labels(),
            &[IndexLabel::Utf8("2024-03-03 00:00:00".to_owned())]
        );
        assert_eq!(
            chunks[1].column("amount").unwrap().values(),
            &[Scalar::Float64(-3.25)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_chunks_with_options_and_index_col_none_keeps_options_and_range_index() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE query_options_no_index (id INTEGER, amount TEXT);
             INSERT INTO query_options_no_index (id, amount) VALUES
                (1, '$10.50'),
                (2, '11.25');",
        )
        .expect("create query_options_no_index table");

        let chunks = read_sql_chunks_with_options_and_index_col(
            &conn,
            "SELECT id, amount FROM query_options_no_index ORDER BY id",
            &SqlReadOptions {
                params: None,
                parse_dates: None,
                coerce_float: true,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
            None,
            1,
        )
        .expect("query chunk iterator")
        .collect::<Result<Vec<_>, _>>()
        .expect("all chunks");

        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks[0].index().labels(), &[IndexLabel::Int64(0)]);
        assert_eq!(chunks[1].index().labels(), &[IndexLabel::Int64(0)]);
        assert_eq!(
            chunks[0].column("amount").unwrap().values(),
            &[Scalar::Float64(10.5)]
        );
        assert_eq!(
            chunks[1].column("amount").unwrap().values(),
            &[Scalar::Float64(11.25)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_chunks_with_options_and_index_col_uses_options_index_when_explicit_none() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE query_options_struct_index (id INTEGER, amount TEXT);
             INSERT INTO query_options_struct_index (id, amount) VALUES
                (10, '$10.50'),
                (20, '11.25');",
        )
        .expect("create query_options_struct_index table");

        let chunks = read_sql_chunks_with_options_and_index_col(
            &conn,
            "SELECT id, amount FROM query_options_struct_index ORDER BY id",
            &SqlReadOptions {
                params: None,
                parse_dates: None,
                coerce_float: true,
                dtype: None,
                schema: None,
                columns: None,
                index_col: Some("id".to_owned()),
            },
            None,
            1,
        )
        .expect("query chunk iterator")
        .collect::<Result<Vec<_>, _>>()
        .expect("all chunks");

        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks[0].index().name(), Some("id"));
        assert_eq!(chunks[0].index().labels(), &[IndexLabel::Int64(10)]);
        assert!(chunks[0].column("id").is_none());
        assert_eq!(chunks[1].index().labels(), &[IndexLabel::Int64(20)]);
        assert_eq!(
            chunks[1].column("amount").unwrap().values(),
            &[Scalar::Float64(11.25)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_query_chunks_with_options_and_index_col_missing_column_errors() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE query_options_missing_index (id INTEGER, amount TEXT);
             INSERT INTO query_options_missing_index (id, amount) VALUES (1, '10.5');",
        )
        .expect("create query_options_missing_index table");

        let err = read_sql_query_chunks_with_options_and_index_col(
            &conn,
            "SELECT id, amount FROM query_options_missing_index",
            &SqlReadOptions {
                params: None,
                parse_dates: None,
                coerce_float: true,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
            Some("missing"),
            1,
        )
        .expect_err("missing index_col should error during iterator construction");

        assert!(matches!(err, IoError::Sql(msg) if msg.contains("index_col")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_query_with_options_and_index_col_applies_options_before_indexing() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE query_frame_index_events (ts TEXT, amount TEXT, keep INTEGER);
             INSERT INTO query_frame_index_events (ts, amount, keep) VALUES
                ('2024-01-15', '12.50', 0),
                ('2024-02-01 05:06:07', '$1,234.50', 1),
                ('2024-03-03', '-3.25', 1);",
        )
        .expect("create query_frame_index_events table");

        let frame = read_sql_query_with_options_and_index_col(
            &conn,
            "SELECT ts, amount FROM query_frame_index_events WHERE keep = ? ORDER BY ts",
            &SqlReadOptions {
                params: Some(vec![Scalar::Int64(1)]),
                parse_dates: Some(vec!["ts".to_owned()]),
                coerce_float: true,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
            Some("ts"),
        )
        .expect("read indexed query frame");

        assert_eq!(frame.index().name(), Some("ts"));
        assert_eq!(
            frame.index().labels(),
            &[
                IndexLabel::Utf8("2024-02-01 05:06:07".to_owned()),
                IndexLabel::Utf8("2024-03-03 00:00:00".to_owned())
            ]
        );
        assert!(frame.column("ts").is_none());
        assert_eq!(
            frame.column("amount").unwrap().values(),
            &[Scalar::Float64(1234.5), Scalar::Float64(-3.25)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_query_with_options_and_index_col_explicit_arg_wins() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE query_frame_index_override (a INTEGER, b INTEGER, val TEXT);
             INSERT INTO query_frame_index_override (a, b, val) VALUES
                (1, 100, 'x'),
                (2, 200, 'y');",
        )
        .expect("create query_frame_index_override table");

        let frame = read_sql_query_with_options_and_index_col(
            &conn,
            "SELECT a, b, val FROM query_frame_index_override ORDER BY a",
            &SqlReadOptions {
                index_col: Some("a".to_owned()),
                ..SqlReadOptions::default()
            },
            Some("b"),
        )
        .expect("read indexed query frame with override");

        assert_eq!(frame.column_names(), vec!["a", "val"]);
        assert_eq!(
            frame.index().labels(),
            &[IndexLabel::Int64(100), IndexLabel::Int64(200)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_query_chunks_rejects_zero_chunksize() {
        let conn = make_sql_test_conn();

        let err = read_sql_query_chunks(&conn, "SELECT 1", 0)
            .expect_err("zero query chunksize should be rejected");

        assert!(matches!(err, IoError::Sql(msg) if msg.contains("chunksize")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_query_chunks_with_index_col_promotes_each_chunk_index() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE query_index_chunked (id INTEGER, label TEXT, value INTEGER);
             INSERT INTO query_index_chunked (id, label, value) VALUES
                (1, 'alpha', 10),
                (2, 'beta', 20),
                (3, 'gamma', 30);",
        )
        .expect("create query_index_chunked table");

        let chunks = read_sql_query_chunks_with_index_col(
            &conn,
            "SELECT id, label, value FROM query_index_chunked ORDER BY id",
            Some("label"),
            2,
        )
        .expect("query indexed chunk iterator")
        .collect::<Result<Vec<_>, _>>()
        .expect("all chunks");

        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks[0].index().name(), Some("label"));
        assert_eq!(
            chunks[0].index().labels(),
            &[
                IndexLabel::Utf8("alpha".to_owned()),
                IndexLabel::Utf8("beta".to_owned())
            ]
        );
        assert!(chunks[0].column("label").is_none());
        assert_eq!(
            chunks[1].index().labels(),
            &[IndexLabel::Utf8("gamma".to_owned())]
        );
        assert_eq!(
            chunks[1].column("value").unwrap().values(),
            &[Scalar::Int64(30)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_chunks_with_index_col_none_keeps_fresh_chunk_range_indexes() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE query_no_index_chunked (id INTEGER, label TEXT);
             INSERT INTO query_no_index_chunked (id, label) VALUES
                (1, 'alpha'),
                (2, 'beta');",
        )
        .expect("create query_no_index_chunked table");

        let chunks = read_sql_chunks_with_index_col(
            &conn,
            "SELECT id, label FROM query_no_index_chunked ORDER BY id",
            None,
            1,
        )
        .expect("query chunk iterator")
        .collect::<Result<Vec<_>, _>>()
        .expect("all chunks");

        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks[0].index().labels(), &[IndexLabel::Int64(0)]);
        assert_eq!(chunks[1].index().labels(), &[IndexLabel::Int64(0)]);
        assert_eq!(chunks[1].column_names(), vec!["id", "label"]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_query_chunks_with_index_col_missing_column_errors() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE query_missing_index_chunked (id INTEGER, value INTEGER);
             INSERT INTO query_missing_index_chunked (id, value) VALUES (1, 10);",
        )
        .expect("create query_missing_index_chunked table");

        let err = read_sql_query_chunks_with_index_col(
            &conn,
            "SELECT id, value FROM query_missing_index_chunked",
            Some("missing"),
            1,
        )
        .expect_err("missing index_col should error during iterator construction");

        assert!(matches!(err, IoError::Sql(msg) if msg.contains("index_col")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_chunks_batches_rows() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE table_chunked (id INTEGER, name TEXT);
             INSERT INTO table_chunked (id, name) VALUES
                (1, 'alpha'),
                (2, 'beta'),
                (3, 'gamma'),
                (4, 'delta');",
        )
        .expect("create table_chunked table");

        let chunks = read_sql_table_chunks(&conn, "table_chunked", 3)
            .expect("table chunk iterator")
            .collect::<Result<Vec<_>, _>>()
            .expect("all chunks");

        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks[0].column_names(), vec!["id", "name"]);
        assert_eq!(
            chunks[0].column("id").unwrap().values(),
            &[Scalar::Int64(1), Scalar::Int64(2), Scalar::Int64(3)]
        );
        assert_eq!(
            chunks[1].column("name").unwrap().values(),
            &[Scalar::Utf8("delta".to_owned())]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_chunks_rejects_zero_chunksize() {
        let conn = make_sql_test_conn();
        conn.execute_batch("CREATE TABLE zero_chunked (id INTEGER);")
            .expect("create zero_chunked table");

        let err = read_sql_table_chunks(&conn, "zero_chunked", 0)
            .expect_err("zero table chunksize should be rejected");

        assert!(matches!(err, IoError::Sql(msg) if msg.contains("chunksize")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_chunks_rejects_invalid_table_name() {
        let conn = make_sql_test_conn();

        let err = read_sql_table_chunks(&conn, "bad table", 1)
            .expect_err("invalid table name should be rejected");

        assert!(matches!(err, IoError::Sql(msg) if msg.contains("invalid table name")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_chunks_with_index_col_promotes_each_chunk_index() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE table_index_chunked (id INTEGER, name TEXT, score INTEGER);
             INSERT INTO table_index_chunked (id, name, score) VALUES
                (10, 'alpha', 100),
                (20, 'beta', 200),
                (30, 'gamma', 300);",
        )
        .expect("create table_index_chunked table");

        let chunks =
            read_sql_table_chunks_with_index_col(&conn, "table_index_chunked", Some("id"), 2)
                .expect("table indexed chunk iterator")
                .collect::<Result<Vec<_>, _>>()
                .expect("all chunks");

        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks[0].index().name(), Some("id"));
        assert_eq!(
            chunks[0].index().labels(),
            &[IndexLabel::Int64(10), IndexLabel::Int64(20)]
        );
        assert!(chunks[0].column("id").is_none());
        assert_eq!(
            chunks[1].column("score").unwrap().values(),
            &[Scalar::Int64(300)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_with_options_applies_parse_dates_and_coerce_float() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE table_options (ts TEXT, amount TEXT, label TEXT);
             INSERT INTO table_options (ts, amount, label) VALUES
                ('2024-01-15', '$12.50', 'a'),
                ('2024-02-01 05:06:07', '1,234.50', 'b');",
        )
        .expect("create table_options table");

        let frame = read_sql_table_with_options(
            &conn,
            "table_options",
            &SqlReadOptions {
                params: None,
                parse_dates: Some(vec!["ts".to_owned()]),
                coerce_float: true,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
        )
        .expect("read table with options");

        assert_eq!(
            frame.column("ts").unwrap().values(),
            &[
                Scalar::Utf8("2024-01-15 00:00:00".to_owned()),
                Scalar::Utf8("2024-02-01 05:06:07".to_owned())
            ]
        );
        assert_eq!(
            frame.column("amount").unwrap().values(),
            &[Scalar::Float64(12.5), Scalar::Float64(1234.5)]
        );
        assert_eq!(
            frame.column("label").unwrap().values(),
            &[Scalar::Utf8("a".to_owned()), Scalar::Utf8("b".to_owned())]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_chunks_with_options_applies_options_before_chunking() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE table_options_chunked (ts TEXT, amount TEXT);
             INSERT INTO table_options_chunked (ts, amount) VALUES
                ('2024-03-01', '$10.00'),
                ('2024-03-02', '$20.50'),
                ('2024-03-03', '-3.25');",
        )
        .expect("create table_options_chunked table");

        let chunks = read_sql_table_chunks_with_options(
            &conn,
            "table_options_chunked",
            &SqlReadOptions {
                params: None,
                parse_dates: Some(vec!["ts".to_owned()]),
                coerce_float: true,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
            2,
        )
        .expect("table option chunk iterator")
        .collect::<Result<Vec<_>, _>>()
        .expect("all chunks");

        assert_eq!(chunks.len(), 2);
        assert_eq!(
            chunks[0].column("ts").unwrap().values(),
            &[
                Scalar::Utf8("2024-03-01 00:00:00".to_owned()),
                Scalar::Utf8("2024-03-02 00:00:00".to_owned())
            ]
        );
        assert_eq!(
            chunks[0].column("amount").unwrap().values(),
            &[Scalar::Float64(10.0), Scalar::Float64(20.5)]
        );
        assert_eq!(
            chunks[1].column("amount").unwrap().values(),
            &[Scalar::Float64(-3.25)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_chunks_with_options_validates_chunksize_and_table_name() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE table_options_errors (ts TEXT);
             INSERT INTO table_options_errors (ts) VALUES ('2024-01-01');",
        )
        .expect("create table_options_errors table");

        let zero = read_sql_table_chunks_with_options(
            &conn,
            "table_options_errors",
            &SqlReadOptions::default(),
            0,
        )
        .expect_err("zero chunksize should be rejected");
        assert!(matches!(zero, IoError::Sql(msg) if msg.contains("chunksize")));

        let invalid = read_sql_table_with_options(
            &conn,
            "bad table",
            &SqlReadOptions {
                parse_dates: Some(vec!["ts".to_owned()]),
                ..SqlReadOptions::default()
            },
        )
        .expect_err("invalid table name should be rejected");
        assert!(matches!(invalid, IoError::Sql(msg) if msg.contains("invalid table name")));
    }

    // br-frankenpandas-i8kja: read_sql_table_chunks_with_options previously
    // accepted SqlReadOptions { index_col: Some(...) } and silently dropped
    // the index_col while the full-frame sibling honored it. Surface the
    // mismatch with a typed error so callers route to the
    // `_and_index_col` variant. The plain entrypoint stays
    // `Result<SqlChunkIterator, _>` for backwards compatibility — the
    // indexed surface is what carries promotion logic.
    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_table_chunks_with_options_rejects_options_index_col() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE i8kja_table_chunks_reject (id INTEGER, val TEXT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "INSERT INTO i8kja_table_chunks_reject VALUES (1, 'a'), (2, 'b');",
        )
        .unwrap();

        let err = read_sql_table_chunks_with_options(
            &conn,
            "i8kja_table_chunks_reject",
            &SqlReadOptions {
                index_col: Some("id".to_owned()),
                ..Default::default()
            },
            2,
        )
        .expect_err("options.index_col on non-indexed entrypoint must be rejected");
        assert!(
            matches!(&err, IoError::Sql(msg) if msg.contains("index_col") && msg.contains("read_sql_table_chunks_with_options_and_index_col")),
            "expected typed error pointing to the _and_index_col variant, got: {err:?}"
        );

        // Sanity: same options struct on the indexed sibling honors index_col.
        let chunks: Vec<DataFrame> = read_sql_table_chunks_with_options_and_index_col(
            &conn,
            "i8kja_table_chunks_reject",
            &SqlReadOptions {
                index_col: Some("id".to_owned()),
                ..Default::default()
            },
            None,
            2,
        )
        .expect("indexed sibling honors options.index_col")
        .collect::<Result<Vec<_>, _>>()
        .expect("all chunks");
        assert_eq!(chunks.len(), 1);
        assert!(chunks[0].column("id").is_none());
        assert_eq!(
            chunks[0].index().labels(),
            &[IndexLabel::Int64(1), IndexLabel::Int64(2)]
        );
        assert_eq!(
            chunks[0].column("val").unwrap().values(),
            &[Scalar::Utf8("a".into()), Scalar::Utf8("b".into())]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_chunks_with_options_rejects_options_index_col() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE i8kja_query_chunks_reject (id INTEGER, val TEXT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "INSERT INTO i8kja_query_chunks_reject VALUES (1, 'a');",
        )
        .unwrap();

        let err = read_sql_chunks_with_options(
            &conn,
            "SELECT * FROM i8kja_query_chunks_reject",
            &SqlReadOptions {
                index_col: Some("id".to_owned()),
                ..Default::default()
            },
            2,
        )
        .expect_err("options.index_col on non-indexed entrypoint must be rejected");
        assert!(
            matches!(&err, IoError::Sql(msg) if msg.contains("index_col") && msg.contains("read_sql_chunks_with_options_and_index_col")),
            "expected typed error pointing to the _and_index_col variant, got: {err:?}"
        );

        let err = read_sql_query_chunks_with_options(
            &conn,
            "SELECT * FROM i8kja_query_chunks_reject",
            &SqlReadOptions {
                index_col: Some("id".to_owned()),
                ..Default::default()
            },
            2,
        )
        .expect_err("query delegator should propagate the rejection");
        assert!(
            matches!(&err, IoError::Sql(msg) if msg.contains("index_col") && msg.contains("read_sql_query_chunks_with_options_and_index_col")),
            "expected query-specific _and_index_col suggestion, got: {err:?}"
        );
    }

    // br-frankenpandas-t1777: query readers can't apply options.columns
    // (caller writes the SELECT, projection is fixed). Silently ignoring
    // diverged from the table-reader sibling. All 7 query-reader entry
    // points (3 foundations + 4 delegators) must reject options.columns
    // with a typed error pointing to the appropriate table reader.
    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_with_options_rejects_options_columns_across_query_entrypoints() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE t1777_query_cols_reject (id INTEGER, val TEXT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "INSERT INTO t1777_query_cols_reject VALUES (1, 'a'), (2, 'b');",
        )
        .unwrap();

        fn assert_columns_rejection(err: &IoError, expected_sibling: &str) {
            assert!(
                matches!(err, IoError::Sql(msg)
                    if msg.contains("options.columns") && msg.contains(expected_sibling)),
                "expected options.columns error pointing to `{expected_sibling}`, got: {err:?}"
            );
        }

        let opts_with_cols = || SqlReadOptions {
            columns: Some(vec!["id".to_owned()]),
            ..Default::default()
        };

        // 1. read_sql_with_options (foundation, full-frame)
        let err = read_sql_with_options(
            &conn,
            "SELECT id, val FROM t1777_query_cols_reject",
            &opts_with_cols(),
        )
        .expect_err("read_sql_with_options must reject options.columns");
        assert_columns_rejection(&err, "read_sql_table_with_options");

        // 2. read_sql_chunks_with_options (foundation, chunked)
        let err = read_sql_chunks_with_options(
            &conn,
            "SELECT id, val FROM t1777_query_cols_reject",
            &opts_with_cols(),
            2,
        )
        .expect_err("read_sql_chunks_with_options must reject options.columns");
        assert_columns_rejection(&err, "read_sql_table_chunks_with_options");

        // 3. read_sql_chunks_with_options_and_index_col (foundation, indexed chunked)
        let err = read_sql_chunks_with_options_and_index_col(
            &conn,
            "SELECT id, val FROM t1777_query_cols_reject",
            &opts_with_cols(),
            Some("id"),
            2,
        )
        .expect_err("indexed chunks must reject options.columns");
        assert_columns_rejection(&err, "read_sql_table_chunks_with_options_and_index_col");

        // 4. read_sql_query_with_options (delegator → read_sql_with_options)
        let err = read_sql_query_with_options(
            &conn,
            "SELECT id, val FROM t1777_query_cols_reject",
            &opts_with_cols(),
        )
        .expect_err("read_sql_query_with_options must propagate the rejection");
        assert_columns_rejection(&err, "read_sql_table_with_options");

        // 5. read_sql_query_with_options_and_index_col (delegator)
        let err = read_sql_query_with_options_and_index_col(
            &conn,
            "SELECT id, val FROM t1777_query_cols_reject",
            &opts_with_cols(),
            Some("id"),
        )
        .expect_err("indexed query reader must reject options.columns");
        assert_columns_rejection(&err, "read_sql_table_with_options");

        // 6. read_sql_query_chunks_with_options (delegator → read_sql_chunks_with_options)
        let err = read_sql_query_chunks_with_options(
            &conn,
            "SELECT id, val FROM t1777_query_cols_reject",
            &opts_with_cols(),
            2,
        )
        .expect_err("query chunks delegator must reject options.columns");
        assert_columns_rejection(&err, "read_sql_table_chunks_with_options");

        // 7. read_sql_query_chunks_with_options_and_index_col (delegator)
        let err = read_sql_query_chunks_with_options_and_index_col(
            &conn,
            "SELECT id, val FROM t1777_query_cols_reject",
            &opts_with_cols(),
            Some("id"),
            2,
        )
        .expect_err("indexed query chunks delegator must reject options.columns");
        assert_columns_rejection(&err, "read_sql_table_chunks_with_options_and_index_col");
    }

    // br-frankenpandas-t1777: table readers must continue to honor
    // options.columns (proves the cleared-options pass-through to the
    // query foundation didn't accidentally break the columns projection).
    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_table_with_options_still_honors_options_columns_after_t1777() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE t1777_table_cols_honor (id INTEGER, val TEXT, secret TEXT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "INSERT INTO t1777_table_cols_honor VALUES (1, 'a', 'x'), (2, 'b', 'y');",
        )
        .unwrap();

        // Full-frame table reader with columns should project `id, val`
        // and drop `secret`.
        let frame = read_sql_table_with_options(
            &conn,
            "t1777_table_cols_honor",
            &SqlReadOptions {
                columns: Some(vec!["id".to_owned(), "val".to_owned()]),
                ..Default::default()
            },
        )
        .expect("table reader honors options.columns");
        assert_eq!(frame.column_names(), vec!["id", "val"]);
        assert!(frame.column("secret").is_none());

        // Chunked table reader, same behavior per chunk.
        let chunks: Vec<DataFrame> = read_sql_table_chunks_with_options(
            &conn,
            "t1777_table_cols_honor",
            &SqlReadOptions {
                columns: Some(vec!["id".to_owned(), "val".to_owned()]),
                ..Default::default()
            },
            1,
        )
        .expect("chunked table reader honors options.columns")
        .collect::<Result<Vec<_>, _>>()
        .expect("all chunks");
        assert_eq!(chunks.len(), 2);
        for c in &chunks {
            assert_eq!(c.column_names(), vec!["id", "val"]);
            assert!(c.column("secret").is_none());
        }

        // Indexed full-frame table reader: columns + index_col compose.
        let frame = read_sql_table_with_options_and_index_col(
            &conn,
            "t1777_table_cols_honor",
            &SqlReadOptions {
                columns: Some(vec!["val".to_owned()]),
                ..Default::default()
            },
            Some("id"),
        )
        .expect("indexed table reader honors options.columns");
        assert_eq!(frame.index().name(), Some("id"));
        assert_eq!(frame.column_names(), vec!["val"]);
        assert!(frame.column("id").is_none());
        assert!(frame.column("secret").is_none());

        // Indexed chunked table reader.
        let chunks: Vec<DataFrame> = read_sql_table_chunks_with_options_and_index_col(
            &conn,
            "t1777_table_cols_honor",
            &SqlReadOptions {
                columns: Some(vec!["val".to_owned()]),
                ..Default::default()
            },
            Some("id"),
            1,
        )
        .expect("indexed chunked table reader honors options.columns")
        .collect::<Result<Vec<_>, _>>()
        .expect("all chunks");
        assert_eq!(chunks.len(), 2);
        for c in &chunks {
            assert_eq!(c.column_names(), vec!["val"]);
            assert!(c.column("id").is_none());
            assert!(c.column("secret").is_none());
        }
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_with_options_and_index_col_applies_options_before_indexing() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE table_options_index (ts TEXT, amount TEXT, label TEXT);
             INSERT INTO table_options_index (ts, amount, label) VALUES
                ('2024-04-01', '$10.00', 'a'),
                ('2024-04-02 03:04:05', '20.50', 'b');",
        )
        .expect("create table_options_index table");

        let frame = read_sql_table_with_options_and_index_col(
            &conn,
            "table_options_index",
            &SqlReadOptions {
                params: None,
                parse_dates: Some(vec!["ts".to_owned()]),
                coerce_float: true,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
            Some("ts"),
        )
        .expect("read table with options and index_col");

        assert_eq!(frame.index().name(), Some("ts"));
        assert_eq!(
            frame.index().labels(),
            &[
                IndexLabel::Utf8("2024-04-01 00:00:00".to_owned()),
                IndexLabel::Utf8("2024-04-02 03:04:05".to_owned())
            ]
        );
        assert!(frame.column("ts").is_none());
        assert_eq!(
            frame.column("amount").unwrap().values(),
            &[Scalar::Float64(10.0), Scalar::Float64(20.5)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_with_options_and_index_col_none_keeps_options_and_range_index() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE table_options_no_index (id INTEGER, amount TEXT);
             INSERT INTO table_options_no_index (id, amount) VALUES
                (1, '$1.25'),
                (2, '$2.50');",
        )
        .expect("create table_options_no_index table");

        let frame = read_sql_table_with_options_and_index_col(
            &conn,
            "table_options_no_index",
            &SqlReadOptions {
                params: None,
                parse_dates: None,
                coerce_float: true,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
            None,
        )
        .expect("read table with options and no index_col");

        assert_eq!(
            frame.index().labels(),
            &[IndexLabel::Int64(0), IndexLabel::Int64(1)]
        );
        assert_eq!(frame.column_names(), vec!["id", "amount"]);
        assert_eq!(
            frame.column("amount").unwrap().values(),
            &[Scalar::Float64(1.25), Scalar::Float64(2.5)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_chunks_with_options_and_index_col_promotes_each_chunk_index() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE table_options_index_chunked (ts TEXT, amount TEXT);
             INSERT INTO table_options_index_chunked (ts, amount) VALUES
                ('2024-05-01', '$10.00'),
                ('2024-05-02', '$20.00'),
                ('2024-05-03', '$30.50');",
        )
        .expect("create table_options_index_chunked table");

        let chunks = read_sql_table_chunks_with_options_and_index_col(
            &conn,
            "table_options_index_chunked",
            &SqlReadOptions {
                params: None,
                parse_dates: Some(vec!["ts".to_owned()]),
                coerce_float: true,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
            Some("ts"),
            2,
        )
        .expect("table indexed option chunk iterator")
        .collect::<Result<Vec<_>, _>>()
        .expect("all chunks");

        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks[0].index().name(), Some("ts"));
        assert_eq!(
            chunks[0].index().labels(),
            &[
                IndexLabel::Utf8("2024-05-01 00:00:00".to_owned()),
                IndexLabel::Utf8("2024-05-02 00:00:00".to_owned())
            ]
        );
        assert!(chunks[0].column("ts").is_none());
        assert_eq!(
            chunks[0].column("amount").unwrap().values(),
            &[Scalar::Float64(10.0), Scalar::Float64(20.0)]
        );
        assert_eq!(
            chunks[1].index().labels(),
            &[IndexLabel::Utf8("2024-05-03 00:00:00".to_owned())]
        );
        assert_eq!(
            chunks[1].column("amount").unwrap().values(),
            &[Scalar::Float64(30.5)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_chunks_with_options_and_index_col_uses_options_index_when_explicit_none() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE table_options_struct_index (id INTEGER, amount TEXT);
             INSERT INTO table_options_struct_index (id, amount) VALUES
                (10, '$10.00'),
                (20, '$20.00'),
                (30, '$30.50');",
        )
        .expect("create table_options_struct_index table");

        let chunks = read_sql_table_chunks_with_options_and_index_col(
            &conn,
            "table_options_struct_index",
            &SqlReadOptions {
                params: None,
                parse_dates: None,
                coerce_float: true,
                dtype: None,
                schema: None,
                columns: None,
                index_col: Some("id".to_owned()),
            },
            None,
            2,
        )
        .expect("table indexed option chunk iterator")
        .collect::<Result<Vec<_>, _>>()
        .expect("all chunks");

        assert_eq!(chunks.len(), 2);
        assert_eq!(
            chunks[0].index().labels(),
            &[IndexLabel::Int64(10), IndexLabel::Int64(20)]
        );
        assert!(chunks[0].column("id").is_none());
        assert_eq!(chunks[1].index().labels(), &[IndexLabel::Int64(30)]);
        assert_eq!(
            chunks[1].column("amount").unwrap().values(),
            &[Scalar::Float64(30.5)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_table_chunks_with_options_and_index_col_missing_column_errors() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE table_options_missing_index (id INTEGER, amount TEXT);
             INSERT INTO table_options_missing_index (id, amount) VALUES (1, '$10.00');",
        )
        .expect("create table_options_missing_index table");

        let err = read_sql_table_chunks_with_options_and_index_col(
            &conn,
            "table_options_missing_index",
            &SqlReadOptions {
                params: None,
                parse_dates: None,
                coerce_float: true,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
            Some("missing"),
            1,
        )
        .expect_err("missing index_col should error during iterator construction");

        assert!(matches!(err, IoError::Sql(msg) if msg.contains("index_col")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_with_parse_dates_coerces_named_columns() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE events (ts TEXT, value INTEGER);
             INSERT INTO events (ts, value) VALUES
                ('2024-01-15', 1),
                ('2024-02-01 05:06:07', 2);",
        )
        .expect("create events table");

        let frame = read_sql_with_options(
            &conn,
            "SELECT ts, value FROM events ORDER BY value",
            &SqlReadOptions {
                params: None,
                parse_dates: Some(vec!["ts".to_owned()]),
                coerce_float: false,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
        )
        .expect("read sql with parse_dates");

        assert_eq!(
            frame.column("ts").unwrap().values()[0],
            Scalar::Utf8("2024-01-15 00:00:00".into())
        );
        assert_eq!(
            frame.column("ts").unwrap().values()[1],
            Scalar::Utf8("2024-02-01 05:06:07".into())
        );
        assert_eq!(frame.column("value").unwrap().values()[0], Scalar::Int64(1));
        assert_eq!(frame.column("value").unwrap().values()[1], Scalar::Int64(2));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_with_parse_dates_missing_column_errors() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE metrics (value INTEGER);
             INSERT INTO metrics (value) VALUES (1);",
        )
        .expect("create metrics table");

        let err = read_sql_with_options(
            &conn,
            "SELECT value FROM metrics",
            &SqlReadOptions {
                params: None,
                parse_dates: Some(vec!["ts".to_owned()]),
                coerce_float: false,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
        )
        .expect_err("missing parse_dates column should error");

        assert!(
            matches!(err, IoError::MissingParseDateColumns(missing) if missing == vec!["ts".to_owned()])
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_with_params_binds_positional_placeholders() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "data", SqlIfExists::Fail).unwrap();

        let filtered = read_sql_with_options(
            &conn,
            "SELECT ints, names FROM data WHERE ints > ? AND names != ? ORDER BY ints",
            &SqlReadOptions {
                params: Some(vec![Scalar::Int64(15), Scalar::Utf8("bob".to_owned())]),
                parse_dates: None,
                coerce_float: false,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
        )
        .expect("read sql with params");

        assert_eq!(filtered.index().len(), 1);
        assert_eq!(
            filtered.column("ints").unwrap().values(),
            &[Scalar::Int64(30)]
        );
        assert_eq!(
            filtered.column("names").unwrap().values(),
            &[Scalar::Utf8("carol".into())]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_with_params_wrong_arity_errors() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "data", SqlIfExists::Fail).unwrap();

        let err = read_sql_with_options(
            &conn,
            "SELECT ints FROM data WHERE ints > ? AND names != ?",
            &SqlReadOptions {
                params: Some(vec![Scalar::Int64(15)]),
                parse_dates: None,
                coerce_float: false,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
        )
        .expect_err("wrong arity should error");

        assert!(matches!(err, IoError::Sql(msg) if msg.contains("parameter")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_coerce_float_promotes_decimal_like_text_columns() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE payments (id INTEGER, amount TEXT, fee TEXT);
             INSERT INTO payments (id, amount, fee) VALUES
                (1, '12.50', '$1,234.50'),
                (2, '-3.25', NULL);",
        )
        .expect("create payments table");

        // Per fd90.41: pandas default for coerce_float is True, and our
        // SqlReadOptions::default() now matches. So the bare read_sql
        // path coerces decimal-like text columns to Float64 by default.
        let default_frame =
            read_sql(&conn, "SELECT amount FROM payments ORDER BY id").expect("default read");
        assert_eq!(
            default_frame.column("amount").unwrap().dtype(),
            DType::Float64
        );
        assert_eq!(
            default_frame.column("amount").unwrap().values(),
            &[Scalar::Float64(12.5), Scalar::Float64(-3.25)],
        );

        // Explicitly opting out of coerce_float keeps the raw Utf8.
        let no_coerce = read_sql_with_options(
            &conn,
            "SELECT amount FROM payments ORDER BY id",
            &SqlReadOptions {
                coerce_float: false,
                ..SqlReadOptions::default()
            },
        )
        .expect("read without coerce_float");
        assert_eq!(
            no_coerce.column("amount").unwrap().values(),
            &[
                Scalar::Utf8("12.50".to_owned()),
                Scalar::Utf8("-3.25".to_owned()),
            ],
        );

        let coerced = read_sql_with_options(
            &conn,
            "SELECT amount, fee FROM payments ORDER BY id",
            &SqlReadOptions {
                coerce_float: true,
                ..SqlReadOptions::default()
            },
        )
        .expect("read with coerce_float");

        let amount = coerced.column("amount").expect("amount");
        assert_eq!(amount.dtype(), DType::Float64);
        assert_eq!(
            amount.values(),
            &[Scalar::Float64(12.5), Scalar::Float64(-3.25)],
        );

        let fee = coerced.column("fee").expect("fee");
        assert_eq!(fee.dtype(), DType::Float64);
        assert_eq!(fee.values()[0], Scalar::Float64(1234.5));
        assert!(matches!(fee.values()[1], Scalar::Null(NullKind::NaN)));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_coerce_float_leaves_non_numeric_text_columns_unchanged() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE mixed (id INTEGER, maybe_amount TEXT, label TEXT);
             INSERT INTO mixed (id, maybe_amount, label) VALUES
                (1, '12.50', 'alpha'),
                (2, 'not numeric', '20.0');",
        )
        .expect("create mixed table");

        let frame = read_sql_with_options(
            &conn,
            "SELECT maybe_amount, label FROM mixed ORDER BY id",
            &SqlReadOptions {
                coerce_float: true,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
                ..SqlReadOptions::default()
            },
        )
        .expect("read with coerce_float");

        assert_eq!(
            frame.column("maybe_amount").unwrap().values(),
            &[
                Scalar::Utf8("12.50".to_owned()),
                Scalar::Utf8("not numeric".to_owned()),
            ],
        );
        assert_eq!(
            frame.column("label").unwrap().values(),
            &[
                Scalar::Utf8("alpha".to_owned()),
                Scalar::Utf8("20.0".to_owned()),
            ],
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_chunks_batches_rows_and_resets_index_per_chunk() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE chunked (id INTEGER, name TEXT);
             INSERT INTO chunked (id, name) VALUES
                (1, 'alpha'),
                (2, 'beta'),
                (3, 'gamma'),
                (4, 'delta'),
                (5, 'epsilon');",
        )
        .expect("create chunked table");

        let chunks = read_sql_chunks(&conn, "SELECT id, name FROM chunked ORDER BY id", 2)
            .expect("chunk iterator")
            .collect::<Result<Vec<_>, _>>()
            .expect("all chunks");

        assert_eq!(chunks.len(), 3);
        assert_eq!(
            chunks[0].index().labels(),
            &[IndexLabel::Int64(0), IndexLabel::Int64(1)]
        );
        assert_eq!(
            chunks[1].index().labels(),
            &[IndexLabel::Int64(0), IndexLabel::Int64(1)]
        );
        assert_eq!(chunks[2].index().labels(), &[IndexLabel::Int64(0)]);
        assert_eq!(
            chunks[0].column("id").unwrap().values(),
            &[Scalar::Int64(1), Scalar::Int64(2)]
        );
        assert_eq!(
            chunks[1].column("id").unwrap().values(),
            &[Scalar::Int64(3), Scalar::Int64(4)]
        );
        assert_eq!(
            chunks[2].column("name").unwrap().values(),
            &[Scalar::Utf8("epsilon".to_owned())]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_chunks_sqlite_uses_paged_iterator_state() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE fp_sqlite_paged_chunks (id INTEGER, name TEXT);
             INSERT INTO fp_sqlite_paged_chunks (id, name) VALUES
                (1, 'alpha'),
                (2, 'beta');",
        )
        .expect("create sqlite_paged_chunks table");

        let mut chunks = read_sql_chunks(
            &conn,
            "SELECT id, name FROM fp_sqlite_paged_chunks ORDER BY id",
            1,
        )
        .expect("chunk iterator");

        let initial_debug = format!("{chunks:?}");
        assert!(
            initial_debug.contains("mode: \"paged\""),
            "SQLite chunk reads must use paged mode, got {initial_debug}"
        );
        assert!(initial_debug.contains("next_offset: 0"));

        let first = chunks
            .next()
            .expect("first chunk")
            .expect("first chunk should read");
        assert_eq!(first.column("id").unwrap().values(), &[Scalar::Int64(1)]);

        let after_first_debug = format!("{chunks:?}");
        assert!(after_first_debug.contains("next_offset: 1"));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_chunks_with_options_applies_params_parse_dates_and_coerce_float() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE events (ts TEXT, amount TEXT, keep INTEGER);
             INSERT INTO events (ts, amount, keep) VALUES
                ('2024-01-15', '12.50', 0),
                ('2024-02-01 05:06:07', '$1,234.50', 1),
                ('2024-03-03', '-3.25', 1);",
        )
        .expect("create events table");

        let chunks = read_sql_chunks_with_options(
            &conn,
            "SELECT ts, amount FROM events WHERE keep = ? ORDER BY ts",
            &SqlReadOptions {
                params: Some(vec![Scalar::Int64(1)]),
                parse_dates: Some(vec!["ts".to_owned()]),
                coerce_float: true,
                dtype: None,
                schema: None,
                columns: None,
                index_col: None,
            },
            1,
        )
        .expect("chunk iterator")
        .collect::<Result<Vec<_>, _>>()
        .expect("all chunks");

        assert_eq!(chunks.len(), 2);
        assert_eq!(
            chunks[0].column("ts").unwrap().values(),
            &[Scalar::Utf8("2024-02-01 05:06:07".to_owned())]
        );
        assert_eq!(
            chunks[0].column("amount").unwrap().values(),
            &[Scalar::Float64(1234.5)]
        );
        assert_eq!(
            chunks[1].column("ts").unwrap().values(),
            &[Scalar::Utf8("2024-03-03 00:00:00".to_owned())]
        );
        assert_eq!(
            chunks[1].column("amount").unwrap().values(),
            &[Scalar::Float64(-3.25)]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_read_chunks_rejects_zero_chunksize() {
        let conn = make_sql_test_conn();

        let err =
            read_sql_chunks(&conn, "SELECT 1", 0).expect_err("zero chunksize should be rejected");

        assert!(matches!(err, IoError::Sql(msg) if msg.contains("chunksize")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_duplicate_column_names_error() {
        let conn = make_sql_test_conn();
        let err = read_sql(&conn, "SELECT 1 as dup, 2 as dup");
        assert!(matches!(err, Err(IoError::DuplicateColumnName(name)) if name == "dup"));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_if_exists_fail() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "tbl", SqlIfExists::Fail).unwrap();

        let err = write_sql(&frame, &conn, "tbl", SqlIfExists::Fail);
        assert!(err.is_err());
        assert!(matches!(&err.unwrap_err(), IoError::Sql(msg) if msg.contains("already exists")),);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_if_exists_replace() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "tbl", SqlIfExists::Fail).unwrap();

        // Replace should succeed and overwrite.
        write_sql(&frame, &conn, "tbl", SqlIfExists::Replace).unwrap();
        let frame2 = read_sql_table(&conn, "tbl").unwrap();
        assert_eq!(frame2.index().len(), 3);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_if_exists_append() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "tbl", SqlIfExists::Fail).unwrap();

        // Append should add rows.
        write_sql(&frame, &conn, "tbl", SqlIfExists::Append).unwrap();
        let frame2 = read_sql_table(&conn, "tbl").unwrap();
        assert_eq!(frame2.index().len(), 6); // 3 + 3
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_with_nulls() {
        use fp_types::DType;

        let mut columns = BTreeMap::new();
        columns.insert(
            "vals".to_string(),
            Column::new(
                DType::Float64,
                vec![
                    Scalar::Float64(1.0),
                    Scalar::Null(NullKind::NaN),
                    Scalar::Float64(3.0),
                ],
            )
            .unwrap(),
        );

        let labels = vec![
            IndexLabel::Int64(0),
            IndexLabel::Int64(1),
            IndexLabel::Int64(2),
        ];
        let frame =
            DataFrame::new_with_column_order(Index::new(labels), columns, vec!["vals".to_string()])
                .unwrap();

        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "nulltest", SqlIfExists::Fail).unwrap();
        let frame2 = read_sql_table(&conn, "nulltest").unwrap();

        assert_eq!(
            frame2.column("vals").unwrap().values()[0],
            Scalar::Float64(1.0)
        );
        assert!(frame2.column("vals").unwrap().values()[1].is_missing());
        assert_eq!(
            frame2.column("vals").unwrap().values()[2],
            Scalar::Float64(3.0)
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_bool_roundtrip() {
        use fp_types::DType;

        let mut columns = BTreeMap::new();
        columns.insert(
            "flags".to_string(),
            Column::new(
                DType::Bool,
                vec![Scalar::Bool(true), Scalar::Bool(false), Scalar::Bool(true)],
            )
            .unwrap(),
        );

        let labels = vec![
            IndexLabel::Int64(0),
            IndexLabel::Int64(1),
            IndexLabel::Int64(2),
        ];
        let frame = DataFrame::new_with_column_order(
            Index::new(labels),
            columns,
            vec!["flags".to_string()],
        )
        .unwrap();

        let conn = make_sql_test_conn();
        write_sql(&frame, &conn, "booltest", SqlIfExists::Fail).unwrap();
        let frame2 = read_sql_table(&conn, "booltest").unwrap();

        // Bools stored as INTEGER(0/1), read back as Int64.
        assert_eq!(
            frame2.column("flags").unwrap().values()[0],
            Scalar::Int64(1)
        );
        assert_eq!(
            frame2.column("flags").unwrap().values()[1],
            Scalar::Int64(0)
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_invalid_table_name_rejected() {
        let conn = make_sql_test_conn();
        let err = read_sql_table(&conn, "Robert'; DROP TABLE students; --");
        assert!(err.is_err());
        assert!(
            matches!(&err.unwrap_err(), IoError::Sql(msg) if msg.contains("invalid table name")),
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_empty_table_name_rejected() {
        let conn = make_sql_test_conn();
        let err = read_sql_table(&conn, "");
        assert!(err.is_err());
        assert!(
            matches!(&err.unwrap_err(), IoError::Sql(msg) if msg.contains("invalid table name")),
        );

        let frame = make_test_dataframe();
        let err = write_sql(&frame, &conn, "", SqlIfExists::Fail);
        assert!(err.is_err());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_empty_result() {
        let conn = make_sql_test_conn();
        conn.execute_batch("CREATE TABLE empty (x INTEGER, y TEXT)")
            .unwrap();
        let frame = read_sql_table(&conn, "empty").unwrap();
        assert_eq!(frame.index().len(), 0);
        assert_eq!(frame.column_names().len(), 2);
        assert_eq!(frame.column("x").unwrap().dtype(), DType::Int64);
        assert_eq!(frame.column("y").unwrap().dtype(), DType::Utf8);

        conn.execute_batch(
            "CREATE TABLE typed_nulls (i INTEGER, r REAL, t TEXT);
             INSERT INTO typed_nulls VALUES (NULL, NULL, NULL);",
        )
        .unwrap();
        let null_frame = read_sql_table(&conn, "typed_nulls").unwrap();
        assert_eq!(null_frame.index().len(), 1);
        assert_eq!(null_frame.column("i").unwrap().dtype(), DType::Int64);
        assert_eq!(null_frame.column("r").unwrap().dtype(), DType::Float64);
        assert_eq!(null_frame.column("t").unwrap().dtype(), DType::Utf8);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_empty_filtered_query_preserves_declared_dtypes() {
        let conn = make_sql_test_conn();
        conn.execute_batch(
            "CREATE TABLE filtered_empty (i INTEGER, r REAL, t TEXT);
             INSERT INTO filtered_empty VALUES (1, 1.25, 'kept');",
        )
        .unwrap();

        let frame = read_sql_with_options(
            &conn,
            "SELECT i, r, t FROM filtered_empty WHERE i > ?",
            &SqlReadOptions {
                params: Some(vec![Scalar::Int64(10)]),
                ..SqlReadOptions::default()
            },
        )
        .expect("empty filtered query must preserve cursor dtype hints");

        assert_eq!(frame.index().len(), 0);
        assert_eq!(frame.column_names(), vec!["i", "r", "t"]);
        assert_eq!(frame.column("i").unwrap().dtype(), DType::Int64);
        assert_eq!(frame.column("r").unwrap().dtype(), DType::Float64);
        assert_eq!(frame.column("t").unwrap().dtype(), DType::Utf8);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_extension_trait() {
        let frame = make_test_dataframe();
        let conn = make_sql_test_conn();

        // Use the extension trait method.
        use super::DataFrameIoExt;
        frame.to_sql(&conn, "ext_test", SqlIfExists::Fail).unwrap();
        frame
            .to_sql_with_options(
                &conn,
                "ext_test_options",
                &SqlWriteOptions {
                    if_exists: SqlIfExists::Fail,
                    index: false,
                    index_label: None,
                    schema: None,
                    dtype: None,
                    method: SqlInsertMethod::Single,
                    chunksize: None,
                },
            )
            .unwrap();

        let frame2 = read_sql_table(&conn, "ext_test").unwrap();
        assert_eq!(frame2.index().len(), 3);
        let frame3 = read_sql_table(&conn, "ext_test_options").unwrap();
        assert_eq!(frame3.index().len(), 3);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn series_sql_extension_aliases_roundtrip_to_single_column_table() {
        use super::SeriesIoExt;

        let source = Series::from_values(
            "sales",
            vec!["r1".into(), "r2".into()],
            vec![Scalar::Int64(10), Scalar::Int64(12)],
        )
        .expect("source series");

        let conn = make_sql_test_conn();
        source
            .to_sql(&conn, "series_ext", SqlIfExists::Fail)
            .expect("series to_sql");
        let roundtrip = read_sql_table(&conn, "series_ext").expect("read series table");
        assert_eq!(roundtrip.column_names(), vec!["index", "sales"]);
        assert_eq!(
            roundtrip.column("index").expect("index column").values(),
            &[Scalar::Utf8("r1".into()), Scalar::Utf8("r2".into())]
        );
        assert_eq!(
            roundtrip.column("sales").expect("sales column").values(),
            source.values()
        );

        source
            .to_sql_with_options(
                &conn,
                "series_ext_no_index",
                &SqlWriteOptions {
                    if_exists: SqlIfExists::Fail,
                    index: false,
                    index_label: None,
                    schema: None,
                    dtype: None,
                    method: SqlInsertMethod::Single,
                    chunksize: None,
                },
            )
            .expect("series to_sql index false");
        let no_index =
            read_sql_table(&conn, "series_ext_no_index").expect("read no-index series table");
        assert_eq!(no_index.column_names(), vec!["sales"]);
        assert_eq!(
            no_index.column("sales").expect("sales column").values(),
            source.values()
        );
    }

    // ── Arrow IPC / Feather tests ────────────────────────────────────

    #[test]
    fn feather_bytes_roundtrip() {
        let frame = make_test_dataframe();
        let bytes = super::write_feather_bytes(&frame).expect("write feather");
        assert!(!bytes.is_empty());

        let frame2 = super::read_feather_bytes(&bytes).expect("read feather");
        assert_eq!(frame2.index().len(), 3);

        // Check all column values survive round-trip exactly.
        let ints = frame2.column("ints").unwrap();
        assert_eq!(ints.values()[0], Scalar::Int64(10));
        assert_eq!(ints.values()[1], Scalar::Int64(20));
        assert_eq!(ints.values()[2], Scalar::Int64(30));

        let floats = frame2.column("floats").unwrap();
        assert_eq!(floats.values()[0], Scalar::Float64(1.5));
        assert_eq!(floats.values()[2], Scalar::Float64(3.5));

        let names = frame2.column("names").unwrap();
        assert_eq!(names.values()[0], Scalar::Utf8("alice".into()));
        assert_eq!(names.values()[2], Scalar::Utf8("carol".into()));
    }

    #[test]
    fn feather_row_multiindex_roundtrip_restores_logical_row_axis() {
        let frame = make_row_multiindex_test_dataframe();
        let bytes = super::write_feather_bytes(&frame).expect("write feather");
        let roundtrip = super::read_feather_bytes(&bytes).expect("read feather");

        assert!(roundtrip.equals(&frame));
        assert!(roundtrip.column("__index_level_0__").is_none());
        assert_eq!(
            roundtrip
                .row_multiindex()
                .expect("row multiindex should be restored")
                .get_level_values(1)
                .unwrap()
                .labels(),
            frame
                .row_multiindex()
                .expect("source row multiindex")
                .get_level_values(1)
                .unwrap()
                .labels()
        );
    }

    #[test]
    fn feather_file_roundtrip() {
        let frame = make_test_dataframe();
        let dir = std::env::temp_dir();
        let path = dir.join("fp_io_test_feather_roundtrip.feather");

        super::write_feather(&frame, &path).expect("write feather file");
        let frame2 = super::read_feather(&path).expect("read feather file");
        assert_eq!(frame2.index().len(), 3);
        assert_eq!(
            frame2.column("ints").unwrap().values()[0],
            Scalar::Int64(10)
        );
        std::fs::remove_file(&path).ok();
    }

    #[test]
    fn ipc_stream_bytes_roundtrip() {
        let frame = make_test_dataframe();
        let bytes = super::write_ipc_stream_bytes(&frame).expect("write ipc stream");
        assert!(!bytes.is_empty());

        let frame2 = super::read_ipc_stream_bytes(&bytes).expect("read ipc stream");
        assert_eq!(frame2.index().len(), 3);
        assert_eq!(
            frame2.column("ints").unwrap().values()[1],
            Scalar::Int64(20)
        );
        assert_eq!(
            frame2.column("names").unwrap().values()[1],
            Scalar::Utf8("bob".into())
        );
    }

    #[test]
    fn ipc_stream_row_multiindex_roundtrip_restores_logical_row_axis() {
        let frame = make_row_multiindex_test_dataframe();
        let bytes = super::write_ipc_stream_bytes(&frame).expect("write ipc stream");
        let roundtrip = super::read_ipc_stream_bytes(&bytes).expect("read ipc stream");

        assert!(roundtrip.equals(&frame));
        assert!(roundtrip.row_multiindex().is_some());
    }

    #[test]
    fn feather_with_nulls() {
        use fp_types::DType;

        let mut columns = BTreeMap::new();
        columns.insert(
            "vals".to_string(),
            Column::new(
                DType::Float64,
                vec![
                    Scalar::Float64(1.0),
                    Scalar::Null(NullKind::NaN),
                    Scalar::Float64(3.0),
                ],
            )
            .unwrap(),
        );

        let labels = vec![
            IndexLabel::Int64(0),
            IndexLabel::Int64(1),
            IndexLabel::Int64(2),
        ];
        let frame =
            DataFrame::new_with_column_order(Index::new(labels), columns, vec!["vals".to_string()])
                .unwrap();

        let bytes = super::write_feather_bytes(&frame).expect("write");
        let frame2 = super::read_feather_bytes(&bytes).expect("read");

        assert_eq!(
            frame2.column("vals").unwrap().values()[0],
            Scalar::Float64(1.0)
        );
        assert!(frame2.column("vals").unwrap().values()[1].is_missing());
        assert_eq!(
            frame2.column("vals").unwrap().values()[2],
            Scalar::Float64(3.0)
        );
    }

    #[test]
    fn feather_nullable_int_roundtrip_preserves_int_dtype() {
        use fp_types::DType;

        let mut columns = BTreeMap::new();
        columns.insert(
            "vals".to_string(),
            Column::new(
                DType::Int64,
                vec![
                    Scalar::Int64(10),
                    Scalar::Null(NullKind::Null),
                    Scalar::Int64(30),
                ],
            )
            .unwrap(),
        );

        let labels = vec![
            IndexLabel::Int64(0),
            IndexLabel::Int64(1),
            IndexLabel::Int64(2),
        ];
        let frame =
            DataFrame::new_with_column_order(Index::new(labels), columns, vec!["vals".to_string()])
                .unwrap();

        let bytes = super::write_feather_bytes(&frame).expect("write");
        let frame2 = super::read_feather_bytes(&bytes).expect("read");
        let vals = frame2.column("vals").unwrap();

        assert_eq!(vals.dtype(), DType::Int64);
        assert_eq!(vals.values()[0], Scalar::Int64(10));
        assert_eq!(vals.values()[1], Scalar::Null(NullKind::Null));
        assert_eq!(vals.values()[2], Scalar::Int64(30));
    }

    #[test]
    fn series_arrow_array_nullable_int_roundtrip() {
        let series = Series::from_values(
            "vals",
            vec![
                IndexLabel::Utf8("r0".into()),
                IndexLabel::Utf8("r1".into()),
                IndexLabel::Utf8("r2".into()),
            ],
            vec![
                Scalar::Int64(10),
                Scalar::Null(NullKind::Null),
                Scalar::Int64(30),
            ],
        )
        .unwrap();

        let (dt, arr) = super::series_to_arrow_array(&series).expect("arrow encode");
        assert_eq!(dt, ArrowDataType::Int64);

        let typed = arr
            .as_any()
            .downcast_ref::<Int64Array>()
            .expect("int64 arrow array");
        assert_eq!(typed.value(0), 10);
        assert!(typed.is_null(1));
        assert_eq!(typed.value(2), 30);

        let roundtrip = super::series_from_arrow_array(
            series.name(),
            series.index().labels().to_vec(),
            arr.as_ref(),
            &dt,
        )
        .expect("arrow decode");

        assert_eq!(roundtrip.name(), "vals");
        assert_eq!(roundtrip.index().labels(), series.index().labels());
        assert_eq!(roundtrip.column().dtype(), DType::Int64);
        assert_eq!(roundtrip.values(), series.values());
    }

    #[test]
    fn feather_bool_column() {
        use fp_types::DType;

        let mut columns = BTreeMap::new();
        columns.insert(
            "flags".to_string(),
            Column::new(
                DType::Bool,
                vec![Scalar::Bool(true), Scalar::Bool(false), Scalar::Bool(true)],
            )
            .unwrap(),
        );

        let labels = vec![
            IndexLabel::Int64(0),
            IndexLabel::Int64(1),
            IndexLabel::Int64(2),
        ];
        let frame = DataFrame::new_with_column_order(
            Index::new(labels),
            columns,
            vec!["flags".to_string()],
        )
        .unwrap();

        let bytes = super::write_feather_bytes(&frame).expect("write");
        let frame2 = super::read_feather_bytes(&bytes).expect("read");

        assert_eq!(
            frame2.column("flags").unwrap().values()[0],
            Scalar::Bool(true)
        );
        assert_eq!(
            frame2.column("flags").unwrap().values()[1],
            Scalar::Bool(false)
        );
    }

    #[test]
    fn feather_preserves_column_order() {
        let frame = make_test_dataframe();
        let bytes = super::write_feather_bytes(&frame).expect("write");
        let frame2 = super::read_feather_bytes(&bytes).expect("read");

        assert_eq!(
            frame2
                .column_names()
                .iter()
                .map(|s| s.as_str())
                .collect::<Vec<_>>(),
            frame
                .column_names()
                .iter()
                .map(|s| s.as_str())
                .collect::<Vec<_>>()
        );
    }

    #[test]
    fn feather_extension_trait() {
        use super::DataFrameIoExt;

        let frame = make_test_dataframe();
        let bytes = frame.to_feather_bytes().unwrap();
        let frame2 = super::read_feather_bytes(&bytes).unwrap();
        assert_eq!(frame2.index().len(), 3);
    }

    // ── Adversarial parser tests (frankenpandas-yby) ─────────────────

    // ── CsvReadOptions extended params tests (frankenpandas-qoz) ────

    #[test]
    fn csv_nrows_limits_rows() {
        let input = "x\n1\n2\n3\n4\n5\n";
        let opts = CsvReadOptions {
            nrows: Some(3),
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        assert_eq!(frame.index().len(), 3);
        assert_eq!(frame.column("x").unwrap().values()[2], Scalar::Int64(3));
    }

    #[test]
    fn csv_skiprows_skips_data_rows() {
        let input = "x\n1\n2\n3\n4\n5\n";
        let opts = CsvReadOptions {
            skiprows: 2,
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        assert_eq!(frame.index().len(), 3); // skipped header + first data row
        assert_eq!(frame.column("2").unwrap().values()[0], Scalar::Int64(3));
    }

    #[test]
    fn csv_skiprows_and_nrows_combined() {
        let input = "x\n1\n2\n3\n4\n5\n";
        let opts = CsvReadOptions {
            skiprows: 1,
            nrows: Some(2),
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        assert_eq!(frame.index().len(), 2); // skipped header; read 2 data rows
        assert_eq!(frame.column("1").unwrap().values()[0], Scalar::Int64(2));
        assert_eq!(frame.column("1").unwrap().values()[1], Scalar::Int64(3));
    }

    #[test]
    fn csv_usecols_selects_columns() {
        let input = "a,b,c\n1,2,3\n4,5,6\n";
        let opts = CsvReadOptions {
            usecols: Some(vec!["a".into(), "c".into()]),
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        assert_eq!(frame.column_names().len(), 2);
        assert!(frame.column("a").is_some());
        assert!(frame.column("b").is_none());
        assert!(frame.column("c").is_some());
        assert_eq!(frame.column("a").unwrap().values()[0], Scalar::Int64(1));
        assert_eq!(frame.column("c").unwrap().values()[1], Scalar::Int64(6));
    }

    #[test]
    fn csv_usecols_nonexistent_column_errors() {
        let input = "a,b\n1,2\n";
        let opts = CsvReadOptions {
            usecols: Some(vec!["a".into(), "nonexistent".into()]),
            ..Default::default()
        };
        let err = read_csv_with_options(input, &opts).expect_err("missing usecols should error");
        assert!(matches!(err, IoError::MissingUsecols(_)));
    }

    #[test]
    fn csv_dtype_coercion() {
        let input = "id,score\n1,95\n2,87\n";
        let mut dtype_map = std::collections::HashMap::new();
        dtype_map.insert("score".to_owned(), fp_types::DType::Float64);
        let opts = CsvReadOptions {
            dtype: Some(dtype_map),
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        // score column should be Float64, not Int64
        assert_eq!(
            frame.column("score").unwrap().values()[0],
            Scalar::Float64(95.0)
        );
        assert_eq!(
            frame.column("score").unwrap().values()[1],
            Scalar::Float64(87.0)
        );
        // id column should remain Int64 (not in dtype map)
        assert_eq!(frame.column("id").unwrap().values()[0], Scalar::Int64(1));
    }

    #[test]
    fn csv_dtype_coercion_invalid_value_errors() {
        let input = "id,score\n1,abc\n";
        let mut dtype_map = std::collections::HashMap::new();
        dtype_map.insert("score".to_owned(), fp_types::DType::Int64);
        let opts = CsvReadOptions {
            dtype: Some(dtype_map),
            ..Default::default()
        };
        let err = read_csv_with_options(input, &opts).expect_err("invalid cast must error");
        assert!(matches!(
            err,
            IoError::Column(fp_columnar::ColumnError::Type(
                fp_types::TypeError::InvalidCast { .. }
            ))
        ));
    }

    #[test]
    fn csv_skiprows_beyond_data_errors() {
        let input = "x\n1\n2\n";
        let opts = CsvReadOptions {
            skiprows: 100,
            ..Default::default()
        };
        let err = read_csv_with_options(input, &opts).expect_err("skiprows removes header");
        assert!(matches!(err, IoError::MissingHeaders));
    }

    #[test]
    fn csv_nrows_zero_returns_empty() {
        let input = "x\n1\n2\n3\n";
        let opts = CsvReadOptions {
            nrows: Some(0),
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        assert_eq!(frame.index().len(), 0);
    }

    #[test]
    fn csv_decimal_comma_parses_quoted_float_fields() {
        let input = "price\n\"1,50\"\n\"3,75\"\n";
        let opts = CsvReadOptions {
            decimal: b',',
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        assert_eq!(
            frame.column("price").unwrap().values(),
            &[Scalar::Float64(1.5), Scalar::Float64(3.75)]
        );
    }

    #[test]
    fn csv_default_decimal_keeps_comma_decimal_strings_as_utf8() {
        let input = "price\n\"1,50\"\n";
        let frame = read_csv_with_options(input, &CsvReadOptions::default()).expect("parse");
        assert_eq!(
            frame.column("price").unwrap().values(),
            &[Scalar::Utf8("1,50".to_owned())]
        );
    }

    #[test]
    fn csv_true_false_values_do_not_override_numeric_inference() {
        let input = "flag\n1\n0\n";
        let opts = CsvReadOptions {
            true_values: vec!["1".to_owned()],
            false_values: vec!["0".to_owned()],
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        assert_eq!(
            frame.column("flag").unwrap().values(),
            &[Scalar::Int64(1), Scalar::Int64(0)]
        );
    }

    #[test]
    fn csv_true_false_values_convert_non_numeric_tokens() {
        let input = "flag\nyes\nno\n";
        let opts = CsvReadOptions {
            true_values: vec!["yes".to_owned()],
            false_values: vec!["no".to_owned()],
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        assert_eq!(
            frame.column("flag").unwrap().values(),
            &[Scalar::Bool(true), Scalar::Bool(false)]
        );
    }

    #[test]
    fn csv_default_parsing_keeps_numeric_boolean_tokens_as_ints() {
        let input = "flag\n1\n0\n";
        let frame = read_csv_with_options(input, &CsvReadOptions::default()).expect("parse");
        assert_eq!(
            frame.column("flag").unwrap().values(),
            &[Scalar::Int64(1), Scalar::Int64(0)]
        );
    }

    #[test]
    fn csv_missing_numeric_column_preserves_int() {
        // DISC-011: Nullable extension Int64 dtype parity - Int64 preserved, not promoted to Float64.
        let input = "a,b,c\n,NA,NaN\n1,,x\n";
        let frame = read_csv_with_options(input, &CsvReadOptions::default()).expect("parse");
        assert_eq!(
            frame.column("a").unwrap().values(),
            &[Scalar::Null(NullKind::Null), Scalar::Int64(1)]
        );
        assert!(frame.column("b").unwrap().values()[0].is_missing());
        assert!(frame.column("b").unwrap().values()[1].is_missing());
        assert_eq!(
            frame.column("c").unwrap().values(),
            &[Scalar::Null(NullKind::Null), Scalar::Utf8("x".to_owned())]
        );
    }

    #[test]
    fn csv_parse_dates_mixed_naive_and_aware_strings_normalizes_per_value() {
        // pandas pd.read_csv(parse_dates=["ts"]) normalizes each value
        // independently when the column has mixed naive + aware timestamps:
        // the naive entry stays naive ("YYYY-MM-DD HH:MM:SS"), and the
        // aware entry is rewritten to the offset form ("...+00:00").
        // The previous "preserves object" behavior locked the entire
        // column to the first inferred timezone pattern and silently
        // rejected mismatched values; conformance fixture FP-P2D-429
        // documents the pandas-2.2.3 expectation.
        let input = "ts,value\n2024-01-15 10:30:00,1\n2024-01-15T10:30:00Z,2\n";
        let opts = CsvReadOptions {
            parse_dates: Some(vec!["ts".to_owned()]),
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        assert_eq!(
            frame.column("ts").unwrap().values(),
            &[
                Scalar::Utf8("2024-01-15 10:30:00".to_owned()),
                Scalar::Utf8("2024-01-15 10:30:00+00:00".to_owned()),
            ]
        );
        assert_eq!(
            frame.column("value").unwrap().values(),
            &[Scalar::Int64(1), Scalar::Int64(2)]
        );
    }

    #[test]
    fn csv_parse_dates_combined_columns_replaces_source_columns() {
        let input = "date,time,value\n2024-01-15,10:30:00,1\n2024-01-16,11:45:30,2\n";
        let opts = CsvReadOptions {
            parse_date_combinations: Some(vec![vec!["date".to_owned(), "time".to_owned()]]),
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        assert_eq!(frame.column_names(), vec!["date_time", "value"]);
        assert_eq!(
            frame.column("date_time").unwrap().values(),
            &[
                Scalar::Utf8("2024-01-15 10:30:00".to_owned()),
                Scalar::Utf8("2024-01-16 11:45:30".to_owned()),
            ]
        );
        assert!(frame.column("date").is_none());
        assert!(frame.column("time").is_none());
        assert_eq!(
            frame.column("value").unwrap().values(),
            &[Scalar::Int64(1), Scalar::Int64(2)]
        );
    }

    #[test]
    fn csv_parse_date_combinations_named_uses_caller_supplied_name() {
        let input = "date,time,value\n2024-01-15,10:30:00,1\n2024-01-16,11:45:30,2\n";
        let opts = CsvReadOptions {
            parse_date_combinations_named: Some(vec![(
                "timestamp".to_owned(),
                vec!["date".to_owned(), "time".to_owned()],
            )]),
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        // Dict-style rename: combined column named "timestamp" rather than
        // the default underscore-joined "date_time".
        assert_eq!(frame.column_names(), vec!["timestamp", "value"]);
        assert!(frame.column("date").is_none());
        assert!(frame.column("time").is_none());
        assert_eq!(
            frame.column("timestamp").unwrap().values(),
            &[
                Scalar::Utf8("2024-01-15 10:30:00".to_owned()),
                Scalar::Utf8("2024-01-16 11:45:30".to_owned()),
            ]
        );
    }

    #[test]
    fn csv_parse_date_combinations_named_multiple_groups() {
        let input = "d1,t1,d2,t2,value\n2024-01-01,09:00:00,2024-01-01,17:00:00,10\n2024-02-01,09:00:00,2024-02-01,17:00:00,20\n";
        let opts = CsvReadOptions {
            parse_date_combinations_named: Some(vec![
                ("start".to_owned(), vec!["d1".to_owned(), "t1".to_owned()]),
                ("end".to_owned(), vec!["d2".to_owned(), "t2".to_owned()]),
            ]),
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        let names = frame.column_names();
        assert!(names.iter().any(|n| n.as_str() == "start"));
        assert!(names.iter().any(|n| n.as_str() == "end"));
        assert!(!names.iter().any(|n| n.as_str() == "d1"));
        assert!(!names.iter().any(|n| n.as_str() == "t2"));
        assert_eq!(
            frame.column("value").unwrap().values(),
            &[Scalar::Int64(10), Scalar::Int64(20)]
        );
        assert_eq!(
            frame.column("start").unwrap().values(),
            &[
                Scalar::Utf8("2024-01-01 09:00:00".to_owned()),
                Scalar::Utf8("2024-02-01 09:00:00".to_owned()),
            ]
        );
    }

    #[test]
    fn csv_parse_date_combinations_named_rejects_duplicate_output_names() {
        let input = "a,b,c,d\n2024,01,2024,02\n";
        let opts = CsvReadOptions {
            parse_date_combinations_named: Some(vec![
                ("ts".to_owned(), vec!["a".to_owned(), "b".to_owned()]),
                ("ts".to_owned(), vec!["c".to_owned(), "d".to_owned()]),
            ]),
            ..Default::default()
        };
        let err = read_csv_with_options(input, &opts).unwrap_err();
        assert!(matches!(err, IoError::DuplicateColumnName(name) if name == "ts"));
    }

    #[test]
    fn csv_parse_date_combinations_named_rejects_missing_source_column() {
        let input = "date,time,value\n2024-01-01,09:00:00,1\n";
        let opts = CsvReadOptions {
            parse_date_combinations_named: Some(vec![(
                "ts".to_owned(),
                vec!["date".to_owned(), "missing".to_owned()],
            )]),
            ..Default::default()
        };
        let err = read_csv_with_options(input, &opts).unwrap_err();
        assert!(matches!(err, IoError::MissingParseDateColumns(_)));
    }

    #[test]
    fn csv_parse_date_combinations_named_empty_sources_skipped() {
        let input = "a,b\n1,2\n";
        let opts = CsvReadOptions {
            parse_date_combinations_named: Some(vec![("unused".to_owned(), Vec::new())]),
            ..Default::default()
        };
        let frame = read_csv_with_options(input, &opts).expect("parse");
        // Empty source list is a no-op; original columns remain.
        assert_eq!(frame.column_names(), vec!["a", "b"]);
    }

    // ── JSONL tests (frankenpandas-sue) ──────────────────────────────

    #[test]
    fn jsonl_write_read_roundtrip() {
        let frame = make_test_dataframe();
        let jsonl = super::write_jsonl_string(&frame).expect("JSONL write failed");

        // Each line should be a valid JSON object.
        let line_count = jsonl.lines().count();
        assert_eq!(line_count, 3, "3 rows = 3 lines");

        let back = super::read_jsonl_str(&jsonl).expect("JSONL read failed");
        assert_eq!(back.index().len(), 3);
        assert_eq!(back.column("ints").unwrap().values()[0], Scalar::Int64(10));
        assert_eq!(
            back.column("names").unwrap().values()[2],
            Scalar::Utf8("carol".into())
        );
    }

    #[test]
    fn jsonl_preserves_column_order() {
        let input = r#"
{"b":1,"a":2}
{"c":3}
"#;
        let frame = super::read_jsonl_str(input).expect("JSONL read failed");
        let order: Vec<&str> = frame
            .column_names()
            .iter()
            .map(|name| name.as_str())
            .collect();
        assert_eq!(order, vec!["b", "a", "c"]);
    }

    #[test]
    fn jsonl_each_line_is_valid_json() {
        let frame = make_test_dataframe();
        let jsonl = super::write_jsonl_string(&frame).unwrap();

        for (i, line) in jsonl.lines().enumerate() {
            let parsed: serde_json::Value =
                serde_json::from_str(line).expect("jsonl line must be valid JSON");
            assert!(parsed.is_object(), "line {i} must be a JSON object");
        }
    }

    #[test]
    fn jsonl_with_nulls() {
        use fp_types::DType;

        let mut columns = BTreeMap::new();
        columns.insert(
            "v".to_string(),
            Column::new(
                DType::Float64,
                vec![
                    Scalar::Float64(1.0),
                    Scalar::Null(NullKind::NaN),
                    Scalar::Float64(3.0),
                ],
            )
            .unwrap(),
        );
        let labels = vec![
            IndexLabel::Int64(0),
            IndexLabel::Int64(1),
            IndexLabel::Int64(2),
        ];
        let frame =
            DataFrame::new_with_column_order(Index::new(labels), columns, vec!["v".to_string()])
                .unwrap();

        let jsonl = super::write_jsonl_string(&frame).unwrap();
        let back = super::read_jsonl_str(&jsonl).unwrap();
        assert!(back.column("v").unwrap().values()[1].is_missing());
    }

    #[test]
    fn jsonl_records_write_preserves_nullable_int_column() {
        // DISC-011: Nullable extension Int64 dtype parity - Int64 preserved, not promoted to Float64.
        let frame = DataFrame::from_dict(
            &["a"],
            vec![("a", vec![Scalar::Int64(1), Scalar::Null(NullKind::Null)])],
        )
        .unwrap();

        let jsonl = super::write_jsonl_string(&frame).expect("write jsonl");
        let rows = jsonl
            .lines()
            .map(|line| serde_json::from_str::<serde_json::Value>(line).unwrap())
            .collect::<Vec<_>>();

        assert_eq!(
            rows,
            vec![serde_json::json!({"a": 1}), serde_json::json!({"a": null})]
        );
    }

    #[test]
    fn jsonl_empty_input() {
        let back = super::read_jsonl_str("").expect("empty JSONL must parse");
        assert_eq!(back.index().len(), 0);
    }

    #[test]
    fn jsonl_blank_lines_skipped() {
        let input = "{\"a\":1}\n\n{\"a\":2}\n\n";
        let back = super::read_jsonl_str(input).expect("JSONL with blanks must parse");
        assert_eq!(back.index().len(), 2);
    }

    #[test]
    fn jsonl_non_object_line_errors() {
        let input = "{\"a\":1}\n[1,2,3]\n";
        let err = super::read_jsonl_str(input);
        assert!(err.is_err());
    }

    #[test]
    fn jsonl_different_keys_across_rows() {
        // Rows with different keys should produce union of all columns.
        let input = "{\"a\":1,\"b\":2}\n{\"a\":3,\"c\":4}\n";
        let frame = super::read_jsonl_str(input).expect("JSONL with different keys must parse");
        assert_eq!(frame.index().len(), 2);
        // Should have columns a, b, c (union of all keys).
        assert!(frame.column("a").is_some(), "column a must exist");
        assert!(frame.column("b").is_some(), "column b must exist");
        assert!(frame.column("c").is_some(), "column c must exist");
        // Row 0: a=1, b=2, c=null.
        assert_eq!(frame.column("a").unwrap().values()[0], Scalar::Int64(1));
        assert_eq!(frame.column("b").unwrap().values()[0], Scalar::Float64(2.0));
        assert!(frame.column("c").unwrap().values()[0].is_missing());
        // Row 1: a=3, b=null, c=4.
        assert_eq!(frame.column("a").unwrap().values()[1], Scalar::Int64(3));
        assert!(frame.column("b").unwrap().values()[1].is_missing());
        assert_eq!(frame.column("c").unwrap().values()[1], Scalar::Float64(4.0));
    }

    #[test]
    fn adversarial_csv_very_long_field() {
        // A single field with >100K characters should parse without panic.
        let long_val = "x".repeat(200_000);
        let input = format!("col\n{long_val}\n");
        let frame = read_csv_str(&input).expect("long field must parse");
        assert_eq!(frame.index().len(), 1);
        match &frame.column("col").unwrap().values()[0] {
            Scalar::Utf8(s) => assert_eq!(s.len(), 200_000),
            other => assert!(
                matches!(other, Scalar::Utf8(_)),
                "expected Utf8 for long field"
            ),
        }
    }

    #[test]
    fn adversarial_csv_many_columns() {
        // CSV with 1000 columns should parse correctly.
        let ncols = 1000;
        let headers: Vec<String> = (0..ncols).map(|i| format!("c{i}")).collect();
        let mut csv = headers.join(",");
        csv.push('\n');
        let vals: Vec<String> = (0..ncols).map(|i| i.to_string()).collect();
        csv.push_str(&vals.join(","));
        csv.push('\n');

        let frame = read_csv_str(&csv).expect("1000-column CSV must parse");
        assert_eq!(frame.columns().len(), ncols);
        assert_eq!(frame.index().len(), 1);
    }

    #[test]
    fn adversarial_csv_empty_rows() {
        // CSV with empty rows between data should handle gracefully.
        // The csv crate skips truly empty records, but rows with the right
        // number of empty fields produce null values.
        let input = "a,b\n1,2\n,\n3,4\n";
        let frame = read_csv_str(input).expect("parse");
        assert_eq!(frame.index().len(), 3);
        // Row 1 (index 1) has empty fields → null
        assert!(frame.column("a").unwrap().values()[1].is_missing());
    }

    #[test]
    fn adversarial_csv_field_with_newlines_in_quotes() {
        // Embedded newlines in quoted fields must not break row boundaries.
        let input = "msg\n\"line1\nline2\nline3\"\n\"single\"\n";
        let frame = read_csv_str(input).expect("quoted newlines must parse");
        assert_eq!(frame.index().len(), 2);
    }

    #[test]
    fn adversarial_csv_header_only_no_data() {
        let input = "x,y,z\n";
        let frame = read_csv_str(input).expect("header-only must parse");
        assert_eq!(frame.index().len(), 0);
        assert_eq!(frame.columns().len(), 3);
    }

    #[test]
    fn adversarial_json_deeply_nested_values() {
        // JSON with nested objects as values should store them as strings.
        let input = r#"[{"a":1,"b":{"nested":"value"}}]"#;
        let frame = read_json_str(input, JsonOrient::Records).expect("nested JSON must parse");
        assert_eq!(frame.index().len(), 1);
        // The nested object becomes a Utf8 representation.
        let b_val = &frame.column("b").unwrap().values()[0];
        assert!(matches!(b_val, Scalar::Utf8(_)));
    }

    #[test]
    fn adversarial_json_i64_max_value() {
        // JSON with values at i64 boundary.
        let input = format!(r#"[{{"v":{}}}]"#, i64::MAX);
        let frame = read_json_str(&input, JsonOrient::Records).expect("i64::MAX must parse");
        assert_eq!(
            frame.column("v").unwrap().values()[0],
            Scalar::Int64(i64::MAX)
        );
    }

    #[test]
    fn adversarial_json_i64_min_value() {
        let input = format!(r#"[{{"v":{}}}]"#, i64::MIN);
        let frame = read_json_str(&input, JsonOrient::Records).expect("i64::MIN must parse");
        assert_eq!(
            frame.column("v").unwrap().values()[0],
            Scalar::Int64(i64::MIN)
        );
    }

    #[test]
    fn adversarial_json_float_special_values() {
        // JSON doesn't natively support Infinity/NaN, but we should handle
        // null gracefully.
        let input = r#"[{"v":null},{"v":1.7976931348623157e+308}]"#;
        let frame = read_json_str(input, JsonOrient::Records).expect("special floats must parse");
        assert!(frame.column("v").unwrap().values()[0].is_missing());
        // f64::MAX is approximately 1.7976931348623157e+308
        if let Scalar::Float64(v) = frame.column("v").unwrap().values()[1] {
            assert!(v.is_finite());
        }
    }

    #[test]
    fn adversarial_json_empty_records_array() {
        let input = r#"[]"#;
        let frame = read_json_str(input, JsonOrient::Records).expect("empty array must parse");
        assert_eq!(frame.index().len(), 0);
    }

    #[test]
    fn adversarial_json_empty_columns_object() {
        let input = r#"{}"#;
        let frame = read_json_str(input, JsonOrient::Columns).expect("empty object must parse");
        assert_eq!(frame.index().len(), 0);
        assert_eq!(frame.columns().len(), 0);
    }

    #[test]
    fn adversarial_csv_unicode_values() {
        // CSV with multi-byte UTF-8 characters in values.
        let input = "name,emoji\n日本語,🎉\nрусский,🚀\n";
        let frame = read_csv_str(input).expect("unicode CSV must parse");
        assert_eq!(frame.index().len(), 2);
        assert_eq!(
            frame.column("name").unwrap().values()[0],
            Scalar::Utf8("日本語".into())
        );
        assert_eq!(
            frame.column("emoji").unwrap().values()[1],
            Scalar::Utf8("🚀".into())
        );
    }

    #[test]
    fn adversarial_csv_single_column_no_trailing_newline() {
        let input = "val\n42";
        let frame = read_csv_str(input).expect("no trailing newline must parse");
        assert_eq!(frame.index().len(), 1);
        assert_eq!(frame.column("val").unwrap().values()[0], Scalar::Int64(42));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn adversarial_sql_large_batch_insert() {
        // Insert 10K rows in a single write_sql call.
        let n = 10_000;
        let vals: Vec<Scalar> = (0..n).map(|i| Scalar::Int64(i as i64)).collect();
        let df = fp_frame::DataFrame::from_dict(&["x"], vec![("x", vals)]).unwrap();

        let conn = make_sql_test_conn();
        write_sql(&df, &conn, "big_table", SqlIfExists::Fail).unwrap();
        let back = read_sql_table(&conn, "big_table").unwrap();
        assert_eq!(back.index().len(), n);
        assert_eq!(
            back.column("x").unwrap().values()[n - 1],
            Scalar::Int64((n - 1) as i64)
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn adversarial_sql_column_name_with_spaces_accepted() {
        // Column names with spaces are valid in SQL (quoted identifiers).
        // Table names are restricted, but column names go through quoting.
        let df = fp_frame::DataFrame::from_dict(
            &["has space"],
            vec![("has space", vec![Scalar::Int64(1)])],
        )
        .unwrap();

        let conn = make_sql_test_conn();
        // This should work since column names are quoted.
        let result = write_sql(&df, &conn, "test_spaces", SqlIfExists::Fail);
        assert!(
            result.is_ok(),
            "columns with spaces should work: {:?}",
            result.err()
        );

        let back = read_sql_table(&conn, "test_spaces").unwrap();
        assert!(back.column("has space").is_some());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn adversarial_sql_column_name_with_quotes_accepted() {
        let col_name = "has\"quote";
        let df =
            fp_frame::DataFrame::from_dict(&[col_name], vec![(col_name, vec![Scalar::Int64(7)])])
                .unwrap();

        let conn = make_sql_test_conn();
        let result = write_sql(&df, &conn, "test_quotes", SqlIfExists::Fail);
        assert!(
            result.is_ok(),
            "columns with quotes should work: {:?}",
            result.err()
        );

        let back = read_sql_table(&conn, "test_quotes").unwrap();
        assert_eq!(back.column(col_name).unwrap().values()[0], Scalar::Int64(7));
    }

    // ── SqlConnection capability + dialect probes (br-frankenpandas-6dtf) ────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn rusqlite_dialect_name_is_sqlite() {
        let conn = make_sql_test_conn();
        assert_eq!(super::SqlConnection::dialect_name(&conn), "sqlite");
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn rusqlite_supports_returning_is_true() {
        // Bundled SQLite is 3.35+, so RETURNING is supported.
        let conn = make_sql_test_conn();
        assert!(super::SqlConnection::supports_returning(&conn));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn rusqlite_max_param_count_is_32766() {
        let conn = make_sql_test_conn();
        assert_eq!(super::SqlConnection::max_param_count(&conn), Some(32766));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn rusqlite_with_transaction_commits_on_ok() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE txn_test (x INTEGER)").unwrap();
        let result: Result<i64, IoError> = super::SqlConnection::with_transaction(&conn, |c| {
            super::SqlConnection::execute_batch(c, "INSERT INTO txn_test VALUES (42)")?;
            Ok(42)
        });
        assert_eq!(result.unwrap(), 42);
        // Verify the row committed.
        let row_count =
            super::SqlConnection::query(&conn, "SELECT COUNT(*) FROM txn_test", &[]).unwrap();
        assert_eq!(row_count.rows.len(), 1);
        assert_eq!(row_count.rows[0][0], Scalar::Int64(1));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn rusqlite_with_transaction_rolls_back_on_err() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE txn_rollback (x INTEGER)")
            .unwrap();
        let result: Result<(), IoError> = super::SqlConnection::with_transaction(&conn, |c| {
            super::SqlConnection::execute_batch(c, "INSERT INTO txn_rollback VALUES (99)")?;
            Err(IoError::Sql("simulated failure".to_string()))
        });
        assert!(result.is_err());
        // Row should NOT have committed.
        let row_count =
            super::SqlConnection::query(&conn, "SELECT COUNT(*) FROM txn_rollback", &[]).unwrap();
        assert_eq!(row_count.rows[0][0], Scalar::Int64(0));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn rusqlite_with_transaction_rolls_back_on_panic() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE txn_panic (x INTEGER)").unwrap();

        let panic_result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            let _: Result<(), IoError> = super::SqlConnection::with_transaction(&conn, |c| {
                super::SqlConnection::execute_batch(c, "INSERT INTO txn_panic VALUES (99)")?;
                std::panic::resume_unwind(Box::new("simulated transaction panic"));
            });
        }));
        assert!(panic_result.is_err());

        let row_count =
            super::SqlConnection::query(&conn, "SELECT COUNT(*) FROM txn_panic", &[]).unwrap();
        assert_eq!(row_count.rows[0][0], Scalar::Int64(0));

        let result: Result<(), IoError> = super::SqlConnection::with_transaction(&conn, |c| {
            super::SqlConnection::execute_batch(c, "INSERT INTO txn_panic VALUES (7)")
        });
        assert!(result.is_ok());
        let rows =
            super::SqlConnection::query(&conn, "SELECT x FROM txn_panic ORDER BY x", &[]).unwrap();
        assert_eq!(rows.rows, vec![vec![Scalar::Int64(7)]]);
    }

    #[test]
    fn default_capability_probes_are_conservative() {
        // A test-double SqlConnection that doesn't override defaults
        // should report the conservative-default values from the trait.
        struct StubSql;
        impl super::SqlConnection for StubSql {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }

        let stub = StubSql;
        assert_eq!(super::SqlConnection::dialect_name(&stub), "unknown");
        assert!(!super::SqlConnection::supports_returning(&stub));
        assert_eq!(super::SqlConnection::max_param_count(&stub), None);
        // Default with_transaction passes through (no BEGIN/COMMIT).
        let result: Result<i64, IoError> = super::SqlConnection::with_transaction(&stub, |_| Ok(7));
        assert_eq!(result.unwrap(), 7);
        // Default quote_identifier produces ANSI double-quotes.
        assert_eq!(
            super::SqlConnection::quote_identifier(&stub, "col").unwrap(),
            r#""col""#
        );
    }

    // ── quote_identifier tests (br-frankenpandas-2y7w / fd90.10) ────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn rusqlite_quote_identifier_uses_ansi_double_quotes() {
        let conn = make_sql_test_conn();
        assert_eq!(
            super::SqlConnection::quote_identifier(&conn, "users").unwrap(),
            r#""users""#
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn rusqlite_quote_identifier_doubles_embedded_quotes() {
        let conn = make_sql_test_conn();
        // Identifier containing a `"` must be escaped by doubling the quote.
        assert_eq!(
            super::SqlConnection::quote_identifier(&conn, r#"value"raw"#).unwrap(),
            r#""value""raw""#
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn rusqlite_quote_identifier_rejects_null_bytes() {
        let conn = make_sql_test_conn();
        let err = super::SqlConnection::quote_identifier(&conn, "evil\0name").expect_err("nul");
        assert!(matches!(err, IoError::Sql(_)));
    }

    #[test]
    fn default_quote_identifier_doubles_embedded_quotes() {
        // Verify the default impl on a non-overriding stub matches the
        // SQLite behavior (ANSI is the shared default for SQLite + Postgres).
        struct StubSql;
        impl super::SqlConnection for StubSql {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        let stub = StubSql;
        assert_eq!(
            super::SqlConnection::quote_identifier(&stub, r#"value"raw"#).unwrap(),
            r#""value""raw""#
        );
        assert!(super::SqlConnection::quote_identifier(&stub, "evil\0").is_err());
    }

    // ── SqlReadOptions::dtype tests (br-frankenpandas-l9pt / fd90.11) ───

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_dtype_override_int_to_float() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE amounts (amount INTEGER); INSERT INTO amounts VALUES (1), (2), (3);",
        )
        .unwrap();
        let mut dtype_map = BTreeMap::new();
        dtype_map.insert("amount".to_owned(), DType::Float64);
        let frame = read_sql_with_options(
            &conn,
            "SELECT amount FROM amounts ORDER BY amount",
            &SqlReadOptions {
                params: None,
                parse_dates: None,
                coerce_float: false,
                dtype: Some(dtype_map),
                schema: None,
                columns: None,
                index_col: None,
            },
        )
        .expect("read with dtype");
        let col = frame.column("amount").expect("amount");
        assert_eq!(col.dtype(), DType::Float64);
        assert_eq!(col.values()[0], Scalar::Float64(1.0));
        assert_eq!(col.values()[2], Scalar::Float64(3.0));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_dtype_override_unsupported_cast_returns_typed_error() {
        // This test asserts that when a dtype override cast is unsupported,
        // SQL IO surfaces a typed IoError::Sql with diagnostic context, NOT a
        // panic and not a silent skip.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE labels (id TEXT); INSERT INTO labels VALUES ('yes'), ('no');",
        )
        .unwrap();
        let mut dtype_map = BTreeMap::new();
        dtype_map.insert("id".to_owned(), DType::Bool);
        let err = read_sql_with_options(
            &conn,
            "SELECT id FROM labels ORDER BY id",
            &SqlReadOptions {
                params: None,
                parse_dates: None,
                coerce_float: false,
                dtype: Some(dtype_map),
                schema: None,
                columns: None,
                index_col: None,
            },
        )
        .expect_err("expected dtype override error");
        match err {
            IoError::Sql(message) => {
                assert!(
                    message.contains("dtype override on column 'id'"),
                    "unexpected error message: {message}"
                );
                assert!(
                    message.contains("Bool"),
                    "unexpected error message: {message}"
                );
            }
            other => unreachable!("expected IoError::Sql, got {other:?}"),
        }
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_dtype_override_missing_column_is_ignored() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE t (x INTEGER); INSERT INTO t VALUES (1);",
        )
        .unwrap();
        let mut dtype_map = BTreeMap::new();
        dtype_map.insert("nonexistent".to_owned(), DType::Float64);
        let frame = read_sql_with_options(
            &conn,
            "SELECT x FROM t",
            &SqlReadOptions {
                params: None,
                parse_dates: None,
                coerce_float: false,
                dtype: Some(dtype_map),
                schema: None,
                columns: None,
                index_col: None,
            },
        )
        .expect("read with dtype-on-missing-col");
        let col = frame.column("x").expect("x");
        assert_eq!(col.dtype(), DType::Int64);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_dtype_override_preserves_nulls() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE nulls_tbl (v INTEGER); INSERT INTO nulls_tbl VALUES (1), (NULL), (3);",
        )
        .unwrap();
        let mut dtype_map = BTreeMap::new();
        dtype_map.insert("v".to_owned(), DType::Float64);
        let frame = read_sql_with_options(
            &conn,
            "SELECT v FROM nulls_tbl ORDER BY rowid",
            &SqlReadOptions {
                params: None,
                parse_dates: None,
                coerce_float: false,
                dtype: Some(dtype_map),
                schema: None,
                columns: None,
                index_col: None,
            },
        )
        .expect("read with dtype + nulls");
        let col = frame.column("v").expect("v");
        assert_eq!(col.dtype(), DType::Float64);
        assert!(col.values()[1].is_missing());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_dtype_skipped_when_column_in_parse_dates() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE evt (ts TEXT); INSERT INTO evt VALUES ('2024-01-01 00:00:00');",
        )
        .unwrap();
        let mut dtype_map = BTreeMap::new();
        dtype_map.insert("ts".to_owned(), DType::Float64);
        let frame = read_sql_with_options(
            &conn,
            "SELECT ts FROM evt",
            &SqlReadOptions {
                params: None,
                parse_dates: Some(vec!["ts".to_owned()]),
                coerce_float: false,
                dtype: Some(dtype_map),
                schema: None,
                columns: None,
                index_col: None,
            },
        )
        .expect("read with parse_dates priority");
        let col = frame.column("ts").expect("ts");
        assert_eq!(col.dtype(), DType::Utf8);
    }

    // ── Schema probes (br-frankenpandas-6dk9 / fd90.13) ─────────────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn rusqlite_does_not_support_schemas_by_default() {
        let conn = make_sql_test_conn();
        assert!(!super::SqlConnection::supports_schemas(&conn));
        assert_eq!(super::SqlConnection::default_schema(&conn), None);
    }

    #[test]
    fn default_schema_probes_are_conservative() {
        // A test-double with no schema overrides reports the conservative
        // single-namespace defaults (matches SQLite + most embedded
        // backends). Production multi-schema backends (PG, MySQL) override.
        struct StubSql;
        impl super::SqlConnection for StubSql {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        let stub = StubSql;
        assert!(!super::SqlConnection::supports_schemas(&stub));
        assert_eq!(super::SqlConnection::default_schema(&stub), None);
    }

    #[test]
    fn schema_probe_overrides_take_effect() {
        // A multi-schema-style test backend (e.g. simulating PostgreSQL)
        // overrides supports_schemas + default_schema. The overrides MUST
        // win over the trait defaults.
        struct PgLikeSqlConn;
        impl super::SqlConnection for PgLikeSqlConn {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn default_schema(&self) -> Option<String> {
                Some("public".to_owned())
            }
        }
        let conn = PgLikeSqlConn;
        assert!(super::SqlConnection::supports_schemas(&conn));
        assert_eq!(
            super::SqlConnection::default_schema(&conn).as_deref(),
            Some("public")
        );
    }

    // ── SqlReadOptions::schema tests (br-frankenpandas-u6zn / fd90.14) ──

    #[test]
    fn sql_select_all_query_no_schema_uses_bare_table() {
        struct StubSql;
        impl super::SqlConnection for StubSql {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        let conn = StubSql;
        let q1 = super::sql_select_all_query_in_schema(&conn, "users", None).expect("q1");
        assert_eq!(q1, "SELECT * FROM \"users\"");
    }

    #[test]
    fn sql_select_query_with_schema_rejects_non_schema_backend() {
        struct StubSql;
        impl super::SqlConnection for StubSql {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn dialect_name(&self) -> &'static str {
                "stub"
            }
        }
        let conn = StubSql;
        let err = super::sql_select_all_query_in_schema(&conn, "users", Some("analytics"))
            .expect_err("schema must reject when backend has no schema support");
        assert!(
            matches!(err, IoError::Sql(msg) if msg.contains("schema is not supported by stub backend"))
        );

        let err =
            super::sql_select_columns_query_in_schema(&conn, "users", Some("analytics"), &["id"])
                .expect_err("projected schema select must reject too");
        assert!(
            matches!(err, IoError::Sql(msg) if msg.contains("schema is not supported by stub backend"))
        );
    }

    #[test]
    fn sql_select_all_query_with_schema_qualifies_on_multi_schema_backend() {
        struct PgLikeSchemaSql;
        impl super::SqlConnection for PgLikeSchemaSql {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
        }
        let conn = PgLikeSchemaSql;
        let q =
            super::sql_select_all_query_in_schema(&conn, "users", Some("analytics")).expect("q");
        assert_eq!(q, "SELECT * FROM \"analytics\".\"users\"");
        let bare = super::sql_select_all_query_in_schema(&conn, "users", None).expect("bare");
        assert_eq!(bare, "SELECT * FROM \"users\"");
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_table_with_options_schema_rejected_on_sqlite() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE bare_tbl (x INTEGER); INSERT INTO bare_tbl VALUES (1), (2);",
        )
        .unwrap();
        let err = read_sql_table_with_options(
            &conn,
            "bare_tbl",
            &SqlReadOptions {
                params: None,
                parse_dates: None,
                coerce_float: false,
                dtype: None,
                schema: Some("ignored_on_sqlite".to_owned()),
                columns: None,
                index_col: None,
            },
        )
        .expect_err("read_sql_table schema=Some must reject on SQLite");
        assert!(
            matches!(err, IoError::Sql(msg) if msg.contains("schema is not supported by sqlite backend"))
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_table_chunks_with_options_schema_rejected_on_sqlite() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE chunk_bare_tbl (x INTEGER); INSERT INTO chunk_bare_tbl VALUES (1), (2);",
        )
        .unwrap();
        let err = read_sql_table_chunks_with_options(
            &conn,
            "chunk_bare_tbl",
            &SqlReadOptions {
                schema: Some("ignored_on_sqlite".to_owned()),
                ..Default::default()
            },
            1,
        )
        .expect_err("chunked read_sql_table schema=Some must reject on SQLite");
        assert!(
            matches!(err, IoError::Sql(msg) if msg.contains("schema is not supported by sqlite backend"))
        );
    }

    #[test]
    fn sql_select_all_query_in_schema_validates_schema_name() {
        struct PgLikeValidate;
        impl super::SqlConnection for PgLikeValidate {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
        }
        let conn = PgLikeValidate;
        let err = super::sql_select_all_query_in_schema(&conn, "users", Some("evil; DROP"))
            .expect_err("malformed schema must reject");
        // Per fd90.56: error message now correctly identifies the
        // bad identifier as a schema, not a table.
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("invalid schema name")));
    }

    // ── SqlWriteOptions::schema tests (br-frankenpandas-udn6 / fd90.15) ─

    #[test]
    fn sql_create_table_query_in_schema_qualifies_on_multi_schema_backend() {
        struct PgLikeWrite;
        impl super::SqlConnection for PgLikeWrite {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
        }
        let conn = PgLikeWrite;
        let cols = vec!["id INTEGER".to_owned(), "name TEXT".to_owned()];
        let q = super::sql_create_table_query_in_schema(&conn, "users", Some("analytics"), &cols)
            .expect("create");
        assert_eq!(
            q,
            "CREATE TABLE IF NOT EXISTS \"analytics\".\"users\" (id INTEGER, name TEXT)"
        );
        let bare =
            super::sql_create_table_query_in_schema(&conn, "users", None, &cols).expect("bare");
        assert_eq!(
            bare,
            "CREATE TABLE IF NOT EXISTS \"users\" (id INTEGER, name TEXT)"
        );
    }

    #[test]
    fn sql_insert_rows_query_in_schema_qualifies_on_multi_schema_backend() {
        struct PgLikeInsert;
        impl super::SqlConnection for PgLikeInsert {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
        }
        let conn = PgLikeInsert;
        let cols = vec!["id".to_owned(), "name".to_owned()];
        let q = super::sql_insert_rows_query_in_schema(&conn, "users", Some("analytics"), &cols)
            .expect("insert");
        assert_eq!(
            q,
            "INSERT INTO \"analytics\".\"users\" (\"id\", \"name\") VALUES (?, ?)"
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn write_sql_with_options_schema_silently_ignored_on_sqlite() {
        let conn = make_sql_test_conn();
        let frame = fp_frame::DataFrame::from_dict(
            &["x"],
            vec![("x", vec![Scalar::Int64(1), Scalar::Int64(2)])],
        )
        .unwrap();
        // SQLite reports supports_schemas=false; passing schema=Some(s) must
        // not break the write — the bare table reference is used.
        write_sql_with_options(
            &frame,
            &conn,
            "bare_write_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: Some("ignored_on_sqlite".to_owned()),
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect("write with schema=Some on SQLite");
        let back = read_sql_table(&conn, "bare_write_tbl").expect("read");
        let col = back.column("x").expect("x");
        assert_eq!(col.values()[0], Scalar::Int64(1));
        assert_eq!(col.values()[1], Scalar::Int64(2));
    }

    #[test]
    fn sql_create_table_query_in_schema_validates_schema_name() {
        struct PgLikeValidate;
        impl super::SqlConnection for PgLikeValidate {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
        }
        let conn = PgLikeValidate;
        let cols = vec!["x INTEGER".to_owned()];
        let err =
            super::sql_create_table_query_in_schema(&conn, "users", Some("evil; DROP"), &cols)
                .expect_err("malformed schema must reject");
        // Per fd90.56: schema validation error now says invalid
        // schema name (not invalid table name).
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("invalid schema name")));
    }

    // ── DROP TABLE schema-qualification (br-frankenpandas-hxob / fd90.16) ─

    #[test]
    fn sql_drop_table_query_bare_on_non_multi_schema() {
        struct StubSql;
        impl super::SqlConnection for StubSql {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        let conn = StubSql;
        let q = super::sql_drop_table_query_in_schema(&conn, "users", None).expect("drop none");
        assert_eq!(q, "DROP TABLE IF EXISTS \"users\"");
        // schema=Some on non-multi-schema is silently ignored.
        let q2 =
            super::sql_drop_table_query_in_schema(&conn, "users", Some("ignored")).expect("drop");
        assert_eq!(q2, "DROP TABLE IF EXISTS \"users\"");
    }

    #[test]
    fn sql_drop_table_query_qualifies_on_multi_schema_backend() {
        struct PgLikeDrop;
        impl super::SqlConnection for PgLikeDrop {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
        }
        let conn = PgLikeDrop;
        let q = super::sql_drop_table_query_in_schema(&conn, "users", Some("analytics"))
            .expect("drop qualified");
        assert_eq!(q, "DROP TABLE IF EXISTS \"analytics\".\"users\"");
        let bare = super::sql_drop_table_query_in_schema(&conn, "users", None).expect("drop bare");
        assert_eq!(bare, "DROP TABLE IF EXISTS \"users\"");
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn write_sql_replace_with_schema_silently_ignored_on_sqlite() {
        // Replace path drops + recreates. SQLite reports supports_schemas
        // == false; the schema is silently ignored on the DROP and on the
        // CREATE/INSERT — the round trip lands data in the bare table.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE replace_tbl (x INTEGER); INSERT INTO replace_tbl VALUES (99);",
        )
        .unwrap();
        let frame = fp_frame::DataFrame::from_dict(
            &["x"],
            vec![("x", vec![Scalar::Int64(1), Scalar::Int64(2)])],
        )
        .unwrap();
        write_sql_with_options(
            &frame,
            &conn,
            "replace_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Replace,
                index: false,
                index_label: None,
                schema: Some("ignored_on_sqlite".to_owned()),
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect("replace + schema=Some on SQLite");
        let back = read_sql_table(&conn, "replace_tbl").expect("read");
        let col = back.column("x").expect("x");
        // Pre-existing 99 was dropped; new rows present.
        assert_eq!(col.values().len(), 2);
        assert_eq!(col.values()[0], Scalar::Int64(1));
        assert_eq!(col.values()[1], Scalar::Int64(2));
    }

    // ── table_exists_in_schema (br-frankenpandas-70d1 / fd90.17) ────────

    #[test]
    fn default_table_exists_in_schema_delegates_to_table_exists() {
        // A stub that returns table_exists=true for "users" must report the
        // same value via the schema-aware default impl regardless of schema.
        struct StubExistsTrue;
        impl super::SqlConnection for StubExistsTrue {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, name: &str) -> Result<bool, IoError> {
                Ok(name == "users")
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        let conn = StubExistsTrue;
        // Schema is ignored by the default impl.
        assert!(super::SqlConnection::table_exists_in_schema(&conn, "users", None).unwrap());
        assert!(
            super::SqlConnection::table_exists_in_schema(&conn, "users", Some("ignored")).unwrap()
        );
        assert!(!super::SqlConnection::table_exists_in_schema(&conn, "missing", None).unwrap());
    }

    #[test]
    fn multi_schema_override_scopes_table_exists() {
        // PgLikeSchemaCheck overrides table_exists_in_schema to scope by
        // schema: only ('analytics', 'users') exists.
        struct PgLikeSchemaCheck;
        impl super::SqlConnection for PgLikeSchemaCheck {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                // Bare table_exists isn't queried by the override path.
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn table_exists_in_schema(
                &self,
                table: &str,
                schema: Option<&str>,
            ) -> Result<bool, IoError> {
                Ok(table == "users" && schema == Some("analytics"))
            }
        }
        let conn = PgLikeSchemaCheck;
        assert!(
            super::SqlConnection::table_exists_in_schema(&conn, "users", Some("analytics"))
                .unwrap()
        );
        // Different schema → false.
        assert!(
            !super::SqlConnection::table_exists_in_schema(&conn, "users", Some("audit")).unwrap()
        );
        // No schema → false (override scopes by Some).
        assert!(!super::SqlConnection::table_exists_in_schema(&conn, "users", None).unwrap());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn write_sql_fail_with_schema_some_still_rejects_existing_on_sqlite() {
        // SQLite ignores schema everywhere; the Fail branch still reports
        // 'table already exists' when the bare table is present.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE preexists_tbl (x INTEGER);")
            .unwrap();
        let frame =
            fp_frame::DataFrame::from_dict(&["x"], vec![("x", vec![Scalar::Int64(1)])]).unwrap();
        let err = write_sql_with_options(
            &frame,
            &conn,
            "preexists_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: Some("ignored_on_sqlite".to_owned()),
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect_err("Fail branch must still reject pre-existing");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("already exists")));
    }

    // ── SqlWriteOptions::dtype overrides (br-frankenpandas-ev2s / fd90.18) ─

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn write_sql_dtype_override_emits_custom_sql_type() {
        // SQLite is permissive on declared types — the column-type string
        // ends up in sqlite_master.sql verbatim, which we can grep to verify
        // the override took effect during CREATE TABLE.
        let conn = make_sql_test_conn();
        let frame = fp_frame::DataFrame::from_dict(
            &["amount"],
            vec![("amount", vec![Scalar::Int64(100), Scalar::Int64(250)])],
        )
        .unwrap();
        let mut overrides = BTreeMap::new();
        overrides.insert("amount".to_owned(), "NUMERIC(10,2)".to_owned());
        write_sql_with_options(
            &frame,
            &conn,
            "money_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: Some(overrides),
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect("write with dtype override");
        let sm = super::SqlConnection::query(
            &conn,
            "SELECT sql FROM sqlite_master WHERE name = 'money_tbl'",
            &[],
        )
        .unwrap();
        let create_sql = match &sm.rows[0][0] {
            Scalar::Utf8(s) => s.clone(),
            other => unreachable!("unexpected sqlite_master payload: {other:?}"),
        };
        assert!(
            create_sql.contains("NUMERIC(10,2)"),
            "expected override to land in CREATE TABLE; got: {create_sql}"
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn write_sql_dtype_override_multiple_columns() {
        let conn = make_sql_test_conn();
        let frame = fp_frame::DataFrame::from_dict(
            &["a", "b"],
            vec![
                ("a", vec![Scalar::Int64(1)]),
                ("b", vec![Scalar::Float64(1.5)]),
            ],
        )
        .unwrap();
        let mut overrides = BTreeMap::new();
        overrides.insert("a".to_owned(), "BIGINT".to_owned());
        overrides.insert("b".to_owned(), "DECIMAL(8,4)".to_owned());
        write_sql_with_options(
            &frame,
            &conn,
            "multi_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: Some(overrides),
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect("write with multi-column overrides");
        let sm = super::SqlConnection::query(
            &conn,
            "SELECT sql FROM sqlite_master WHERE name = 'multi_tbl'",
            &[],
        )
        .unwrap();
        let create_sql = match &sm.rows[0][0] {
            Scalar::Utf8(s) => s.clone(),
            other => unreachable!("unexpected sqlite_master payload: {other:?}"),
        };
        assert!(create_sql.contains("BIGINT"));
        assert!(create_sql.contains("DECIMAL(8,4)"));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn write_sql_dtype_override_for_missing_column_silently_ignored() {
        let conn = make_sql_test_conn();
        let frame =
            fp_frame::DataFrame::from_dict(&["x"], vec![("x", vec![Scalar::Int64(1)])]).unwrap();
        let mut overrides = BTreeMap::new();
        overrides.insert("nonexistent".to_owned(), "BIGINT".to_owned());
        // No error — pandas silently ignores dtype entries for columns not in the frame.
        write_sql_with_options(
            &frame,
            &conn,
            "missing_col_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: Some(overrides),
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect("write with override on missing col");
        // The actual 'x' column kept its inferred type.
        let sm = super::SqlConnection::query(
            &conn,
            "SELECT sql FROM sqlite_master WHERE name = 'missing_col_tbl'",
            &[],
        )
        .unwrap();
        let create_sql = match &sm.rows[0][0] {
            Scalar::Utf8(s) => s.clone(),
            other => unreachable!("unexpected sqlite_master payload: {other:?}"),
        };
        assert!(create_sql.contains("INTEGER"));
        assert!(!create_sql.contains("BIGINT"));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn write_sql_dtype_none_falls_back_to_inferred_type() {
        let conn = make_sql_test_conn();
        let frame =
            fp_frame::DataFrame::from_dict(&["x"], vec![("x", vec![Scalar::Int64(1)])]).unwrap();
        write_sql_with_options(
            &frame,
            &conn,
            "no_override_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect("write without override");
        let sm = super::SqlConnection::query(
            &conn,
            "SELECT sql FROM sqlite_master WHERE name = 'no_override_tbl'",
            &[],
        )
        .unwrap();
        let create_sql = match &sm.rows[0][0] {
            Scalar::Utf8(s) => s.clone(),
            other => unreachable!("unexpected sqlite_master payload: {other:?}"),
        };
        // INTEGER is conn.dtype_sql(DType::Int64) for rusqlite.
        assert!(create_sql.contains("INTEGER"));
    }

    // ── SqlInsertMethod::Multi (br-frankenpandas-i0ml / fd90.19) ─────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn write_sql_multi_round_trip_matches_single() {
        // Same frame written via Single vs Multi must produce identical
        // SELECT * results — the only observable difference should be
        // the wire-format efficiency, never the stored values.
        let frame = fp_frame::DataFrame::from_dict(
            &["id", "name", "amount"],
            vec![
                (
                    "id",
                    vec![Scalar::Int64(1), Scalar::Int64(2), Scalar::Int64(3)],
                ),
                (
                    "name",
                    vec![
                        Scalar::Utf8("alice".into()),
                        Scalar::Utf8("bob".into()),
                        Scalar::Utf8("carol".into()),
                    ],
                ),
                (
                    "amount",
                    vec![
                        Scalar::Float64(1.5),
                        Scalar::Float64(2.5),
                        Scalar::Float64(3.5),
                    ],
                ),
            ],
        )
        .unwrap();

        let conn_single = make_sql_test_conn();
        write_sql_with_options(
            &frame,
            &conn_single,
            "single_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .unwrap();
        let single = read_sql(&conn_single, "SELECT * FROM single_tbl ORDER BY id").unwrap();

        let conn_multi = make_sql_test_conn();
        write_sql_with_options(
            &frame,
            &conn_multi,
            "multi_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Multi,
                chunksize: None,
            },
        )
        .unwrap();
        let multi = read_sql(&conn_multi, "SELECT * FROM multi_tbl ORDER BY id").unwrap();

        assert_eq!(single.column_names(), multi.column_names());
        for name in single.column_names() {
            let s = single.column(name).unwrap().values().to_vec();
            let m = multi.column(name).unwrap().values().to_vec();
            assert_eq!(s, m, "column {name} diverged between Single and Multi");
        }
    }

    #[test]
    fn sql_multi_row_insert_query_emits_correct_placeholder_count() {
        // 3 rows × 2 cols = 6 placeholders, ordinals 1..=6.
        struct PgLikeStub;
        impl super::SqlConnection for PgLikeStub {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn parameter_marker(&self, ordinal: usize) -> String {
                format!("${ordinal}")
            }
        }
        let conn = PgLikeStub;
        let cols = vec!["a".to_owned(), "b".to_owned()];
        let sql =
            super::sql_multi_row_insert_query_in_schema(&conn, "tbl", None, &cols, 3).unwrap();
        // Expect: INSERT INTO "tbl" ("a", "b") VALUES ($1, $2), ($3, $4), ($5, $6)
        assert!(
            sql.contains("VALUES ($1, $2), ($3, $4), ($5, $6)"),
            "got: {sql}"
        );
    }

    #[test]
    fn sql_multi_row_insert_query_rejects_zero_rows() {
        struct StubConn;
        impl super::SqlConnection for StubConn {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        let conn = StubConn;
        let cols = vec!["a".to_owned()];
        let err = super::sql_multi_row_insert_query_in_schema(&conn, "tbl", None, &cols, 0)
            .expect_err("zero rows must be rejected");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("at least one row")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn write_sql_multi_chunks_at_max_param_boundary() {
        // Verify the chunking logic dispatches multiple INSERT statements
        // when num_rows * num_cols exceeds max_param_count. We override
        // max_param_count on a recording stub to force a tiny budget.
        use std::cell::RefCell;
        struct ChunkRecorder {
            statements: RefCell<Vec<String>>,
            row_counts: RefCell<Vec<usize>>,
        }
        impl super::SqlConnection for ChunkRecorder {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, sql: &str, rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                self.statements.borrow_mut().push(sql.to_owned());
                self.row_counts
                    .borrow_mut()
                    .push(rows.first().map_or(0, std::vec::Vec::len));
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn max_param_count(&self) -> Option<usize> {
                // 4 params total, ncols=2 → 2 rows per chunk.
                Some(4)
            }
        }
        let conn = ChunkRecorder {
            statements: RefCell::new(vec![]),
            row_counts: RefCell::new(vec![]),
        };
        let frame = fp_frame::DataFrame::from_dict(
            &["a", "b"],
            vec![
                (
                    "a",
                    vec![
                        Scalar::Int64(1),
                        Scalar::Int64(2),
                        Scalar::Int64(3),
                        Scalar::Int64(4),
                        Scalar::Int64(5),
                    ],
                ),
                (
                    "b",
                    vec![
                        Scalar::Int64(10),
                        Scalar::Int64(20),
                        Scalar::Int64(30),
                        Scalar::Int64(40),
                        Scalar::Int64(50),
                    ],
                ),
            ],
        )
        .unwrap();
        write_sql_with_options(
            &frame,
            &conn,
            "chunked",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Multi,
                chunksize: None,
            },
        )
        .unwrap();
        // 5 rows / 2 per chunk = 3 chunks (2, 2, 1).
        let stmts = conn.statements.borrow();
        let counts = conn.row_counts.borrow();
        assert_eq!(stmts.len(), 3, "expected 3 chunked INSERTs");
        // Flat row payloads: 2 rows * 2 cols = 4 scalars, 4, then 1 row * 2 = 2.
        assert_eq!(counts.as_slice(), &[4, 4, 2]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn write_sql_multi_no_max_param_sends_single_statement() {
        // When the backend reports max_param_count() == None, the whole
        // frame should ship in a single multi-row INSERT.
        use std::cell::RefCell;
        struct UnboundedStub {
            statements: RefCell<Vec<String>>,
        }
        impl super::SqlConnection for UnboundedStub {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                self.statements.borrow_mut().push(sql.to_owned());
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn max_param_count(&self) -> Option<usize> {
                None
            }
        }
        let conn = UnboundedStub {
            statements: RefCell::new(vec![]),
        };
        let frame = fp_frame::DataFrame::from_dict(
            &["x"],
            vec![(
                "x",
                vec![Scalar::Int64(1), Scalar::Int64(2), Scalar::Int64(3)],
            )],
        )
        .unwrap();
        write_sql_with_options(
            &frame,
            &conn,
            "uncapped",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Multi,
                chunksize: None,
            },
        )
        .unwrap();
        let stmts = conn.statements.borrow();
        assert_eq!(stmts.len(), 1, "expected exactly one multi-row INSERT");
        // 3 tuples → 2 commas separating tuples in VALUES (...), (...), (...).
        let stmt = &stmts[0];
        assert_eq!(
            stmt.matches("(?)").count(),
            3,
            "expected 3 row tuples in: {stmt}"
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn write_sql_multi_preserves_nulls() {
        // NaT/Null values must round-trip through the multi-row path.
        let frame = fp_frame::DataFrame::from_dict(
            &["a", "b"],
            vec![
                (
                    "a",
                    vec![
                        Scalar::Int64(1),
                        Scalar::Null(NullKind::Null),
                        Scalar::Int64(3),
                    ],
                ),
                (
                    "b",
                    vec![
                        Scalar::Utf8("x".into()),
                        Scalar::Utf8("y".into()),
                        Scalar::Null(NullKind::Null),
                    ],
                ),
            ],
        )
        .unwrap();
        let conn = make_sql_test_conn();
        write_sql_with_options(
            &frame,
            &conn,
            "nulls_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Multi,
                chunksize: None,
            },
        )
        .unwrap();
        let back = read_sql(&conn, "SELECT a, b FROM nulls_tbl ORDER BY rowid").unwrap();
        let a = back.column("a").unwrap().values();
        let b = back.column("b").unwrap().values();
        assert_eq!(a[0], Scalar::Int64(1));
        assert!(matches!(a[1], Scalar::Null(_)));
        assert_eq!(a[2], Scalar::Int64(3));
        assert_eq!(b[0], Scalar::Utf8("x".into()));
        assert_eq!(b[1], Scalar::Utf8("y".into()));
        assert!(matches!(b[2], Scalar::Null(_)));
    }

    #[test]
    fn sql_insert_method_default_is_single() {
        assert_eq!(SqlInsertMethod::default(), SqlInsertMethod::Single);
    }

    // ── list_sql_tables / SqlConnection::list_tables (br-vhq2 / fd90.20) ─

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_tables_empty_db_returns_empty_vec() {
        let conn = make_sql_test_conn();
        let tables = list_sql_tables(&conn, None).unwrap();
        assert!(tables.is_empty(), "expected no tables; got {tables:?}");
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_tables_returns_user_tables_sorted() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE zebra (x INTEGER);").unwrap();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE alpha (y TEXT);").unwrap();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE mango (z REAL);").unwrap();
        let tables = list_sql_tables(&conn, None).unwrap();
        assert_eq!(tables, vec!["alpha", "mango", "zebra"]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_tables_excludes_sqlite_internal_tables() {
        let conn = make_sql_test_conn();
        // Forcing creation of an internal sqlite_sequence table by using
        // AUTOINCREMENT — that table must NOT appear in the result.
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE seq_demo (id INTEGER PRIMARY KEY AUTOINCREMENT, v TEXT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(&conn, "INSERT INTO seq_demo (v) VALUES ('one');")
            .unwrap();
        let tables = list_sql_tables(&conn, None).unwrap();
        assert_eq!(tables, vec!["seq_demo"]);
        assert!(!tables.iter().any(|name| name.starts_with("sqlite_")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_tables_keeps_user_tables_with_sqlite_prefix_no_underscore() {
        // Per fd90.50: a user table named like 'sqliteX' (no underscore
        // between 'sqlite' and the rest) was being incorrectly excluded
        // by the buggy `NOT LIKE 'sqlite_%'` filter (where `_` is a
        // single-char wildcard). After the ESCAPE '\' fix the
        // underscore is treated literally, so only names starting with
        // the literal substring 'sqlite_' are excluded.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE sqliteX (x INTEGER);").unwrap();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE sqliteY (y TEXT);").unwrap();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE sqlite1234 (z REAL);").unwrap();
        let tables = list_sql_tables(&conn, None).unwrap();
        assert_eq!(tables, vec!["sqlite1234", "sqliteX", "sqliteY"]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_views_keeps_user_views_with_sqlite_prefix_no_underscore() {
        // Companion to the list_tables case (fd90.50): same escape fix
        // applies to list_views.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE base (x INTEGER);").unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE VIEW sqliteX_view AS SELECT x FROM base;",
        )
        .unwrap();
        let views = list_sql_views(&conn, None).unwrap();
        // sqliteX_view: 'sqliteX' (no underscore after 'sqlite') so the
        // literal-underscore filter accepts it.
        assert_eq!(views, vec!["sqliteX_view"]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_tables_schema_silently_ignored_on_sqlite() {
        // SQLite reports supports_schemas() == false. Passing a schema
        // arg must NOT error; it is silently dropped and all tables are
        // returned (matches the documented option-struct ignore policy).
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE only_one (x INTEGER);").unwrap();
        let with_schema =
            list_sql_tables(&conn, Some("ignored_on_sqlite")).expect("schema arg must not error");
        let without_schema = list_sql_tables(&conn, None).unwrap();
        assert_eq!(with_schema, without_schema);
    }

    #[test]
    fn list_sql_tables_default_impl_returns_empty() {
        // A backend that doesn't override list_tables falls through to
        // the trait default — returns empty rather than erroring.
        struct NoIntrospection;
        impl super::SqlConnection for NoIntrospection {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        let conn = NoIntrospection;
        let tables = list_sql_tables(&conn, None).unwrap();
        assert!(tables.is_empty());
        let with_schema = list_sql_tables(&conn, Some("any")).unwrap();
        assert!(with_schema.is_empty());
    }

    #[test]
    fn list_sql_tables_routes_schema_to_backend_override() {
        // Multi-schema backend stub: returns different tables per schema.
        struct MultiSchema;
        impl super::SqlConnection for MultiSchema {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn list_tables(&self, schema: Option<&str>) -> Result<Vec<String>, IoError> {
                Ok(match schema {
                    Some("analytics") => {
                        vec!["users".to_owned(), "events".to_owned()]
                    }
                    Some("audit") => vec!["logs".to_owned()],
                    Some(_) => vec![],
                    None => vec!["public_table".to_owned()],
                })
            }
        }
        let conn = MultiSchema;
        assert_eq!(
            list_sql_tables(&conn, Some("analytics")).unwrap(),
            vec!["users", "events"]
        );
        assert_eq!(list_sql_tables(&conn, Some("audit")).unwrap(), vec!["logs"]);
        assert_eq!(
            list_sql_tables(&conn, Some("missing")).unwrap(),
            Vec::<String>::new()
        );
        assert_eq!(list_sql_tables(&conn, None).unwrap(), vec!["public_table"]);
    }

    // ── sql_table_schema / SqlConnection::table_schema (br-w43q / fd90.21) ─

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_table_schema_unknown_table_returns_none() {
        let conn = make_sql_test_conn();
        let result = sql_table_schema(&conn, "no_such_table", None).unwrap();
        assert!(result.is_none());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_table_schema_simple_table() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE simple (id INTEGER, name TEXT);")
            .unwrap();
        let schema = sql_table_schema(&conn, "simple", None).unwrap().unwrap();
        assert_eq!(schema.table_name, "simple");
        assert_eq!(schema.columns.len(), 2);
        assert_eq!(schema.columns[0].name, "id");
        assert_eq!(schema.columns[0].declared_type.as_deref(), Some("INTEGER"));
        assert!(schema.columns[0].nullable);
        assert!(schema.columns[0].primary_key_ordinal.is_none());
        assert_eq!(schema.columns[1].name, "name");
        assert_eq!(schema.columns[1].declared_type.as_deref(), Some("TEXT"));
        assert!(schema.columns[1].nullable);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_table_schema_pk_notnull_default() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE meta ( \
                id INTEGER PRIMARY KEY, \
                name TEXT NOT NULL, \
                status TEXT DEFAULT 'active' \
             );",
        )
        .unwrap();
        let schema = sql_table_schema(&conn, "meta", None).unwrap().unwrap();
        assert_eq!(schema.columns.len(), 3);

        let id = schema.column("id").expect("id col");
        assert_eq!(id.primary_key_ordinal, Some(0));
        // PRIMARY KEY columns in SQLite (without explicit NOT NULL on
        // INTEGER PRIMARY KEY) are reported as nullable=true by
        // table_info — we surface that as-is rather than fabricating.
        // The point is just that primary_key_ordinal is populated.

        let name = schema.column("name").expect("name col");
        assert!(!name.nullable);
        assert!(name.default_value.is_none());
        assert!(name.primary_key_ordinal.is_none());

        let status = schema.column("status").expect("status col");
        assert!(status.nullable);
        assert_eq!(
            status.default_value.as_deref(),
            Some("'active'"),
            "expected SQL literal default text"
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_table_schema_schema_silently_ignored_on_sqlite() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE only_one (x INTEGER);").unwrap();
        let with_schema = sql_table_schema(&conn, "only_one", Some("ignored_on_sqlite"))
            .expect("schema arg must not error")
            .expect("table exists");
        let without_schema = sql_table_schema(&conn, "only_one", None).unwrap().unwrap();
        assert_eq!(with_schema, without_schema);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_table_schema_rejects_invalid_table_name() {
        // The PRAGMA path can't bind parameters, so we validate the
        // identifier first. Reject anything with non-alphanumeric chars.
        let conn = make_sql_test_conn();
        let err = sql_table_schema(&conn, "x; DROP TABLE users", None).expect_err("must reject");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("invalid")));
    }

    #[test]
    fn sql_table_schema_default_impl_returns_none() {
        struct NoIntrospection;
        impl super::SqlConnection for NoIntrospection {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        let conn = NoIntrospection;
        assert!(sql_table_schema(&conn, "anything", None).unwrap().is_none());
    }

    #[test]
    fn sql_table_schema_routes_schema_to_backend_override() {
        struct MultiSchema;
        impl super::SqlConnection for MultiSchema {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn table_schema(
                &self,
                table: &str,
                schema: Option<&str>,
            ) -> Result<Option<SqlTableSchema>, IoError> {
                if table == "users" && schema == Some("analytics") {
                    Ok(Some(SqlTableSchema {
                        table_name: "users".to_owned(),
                        columns: vec![SqlColumnSchema {
                            name: "id".to_owned(),
                            declared_type: Some("BIGINT".to_owned()),
                            nullable: false,
                            default_value: None,
                            primary_key_ordinal: Some(0),
                            comment: None,
                            autoincrement: false,
                        }],
                    }))
                } else {
                    Ok(None)
                }
            }
        }
        let conn = MultiSchema;
        let analytics_users = sql_table_schema(&conn, "users", Some("analytics"))
            .unwrap()
            .expect("found");
        assert_eq!(
            analytics_users.columns[0].declared_type.as_deref(),
            Some("BIGINT")
        );
        assert!(
            sql_table_schema(&conn, "users", Some("audit"))
                .unwrap()
                .is_none()
        );
        assert!(sql_table_schema(&conn, "users", None).unwrap().is_none());
    }

    // ── list_sql_schemas / SqlConnection::list_schemas (br-lxhi / fd90.22) ─

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_schemas_returns_empty_on_sqlite() {
        // SQLite has no meaningful schema concept; the trait default
        // (empty Vec) is the right answer.
        let conn = make_sql_test_conn();
        let schemas = list_sql_schemas(&conn).unwrap();
        assert!(schemas.is_empty(), "expected no schemas; got {schemas:?}");
    }

    #[test]
    fn list_sql_schemas_default_impl_returns_empty() {
        struct NoIntrospection;
        impl super::SqlConnection for NoIntrospection {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        let conn = NoIntrospection;
        assert!(list_sql_schemas(&conn).unwrap().is_empty());
    }

    #[test]
    fn list_sql_schemas_routes_to_backend_override() {
        // Multi-schema backend stub: returns the schemas the connection's
        // role can see, with internal schemas filtered out.
        struct MultiSchemaServer;
        impl super::SqlConnection for MultiSchemaServer {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn list_schemas(&self) -> Result<Vec<String>, IoError> {
                // Filter out information_schema + pg_catalog by default.
                Ok(vec![
                    "public".to_owned(),
                    "analytics".to_owned(),
                    "audit".to_owned(),
                ])
            }
        }
        let conn = MultiSchemaServer;
        let schemas = list_sql_schemas(&conn).unwrap();
        assert_eq!(schemas, vec!["public", "analytics", "audit"]);
        // Verify the override actually filters internal schemas
        // (test contract: stub never returns 'pg_catalog' or
        // 'information_schema').
        assert!(!schemas.iter().any(|s| s.starts_with("pg_")));
        assert!(!schemas.iter().any(|s| s == "information_schema"));
    }

    #[test]
    fn list_sql_schemas_propagates_backend_error() {
        // If the backend errors during introspection, the error should
        // surface through the wrapper unchanged.
        struct BrokenIntrospection;
        impl super::SqlConnection for BrokenIntrospection {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn list_schemas(&self) -> Result<Vec<String>, IoError> {
                Err(IoError::Sql("permission denied for catalog".to_owned()))
            }
        }
        let conn = BrokenIntrospection;
        let err = list_sql_schemas(&conn).expect_err("should surface backend error");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("permission denied")));
    }

    // ── truncate_sql_table / SqlConnection::truncate_table (br-phum / fd90.23) ─

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn truncate_sql_table_clears_rows_but_preserves_schema() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE rolling (id INTEGER, val TEXT);")
            .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "INSERT INTO rolling VALUES (1, 'a'), (2, 'b'), (3, 'c');",
        )
        .unwrap();
        // Sanity: rows present.
        let before =
            super::SqlConnection::query(&conn, "SELECT COUNT(*) FROM rolling", &[]).unwrap();
        assert_eq!(before.rows[0][0], Scalar::Int64(3));

        truncate_sql_table(&conn, "rolling", None).unwrap();

        // Rows gone, table still there.
        let after =
            super::SqlConnection::query(&conn, "SELECT COUNT(*) FROM rolling", &[]).unwrap();
        assert_eq!(after.rows[0][0], Scalar::Int64(0));
        assert!(super::SqlConnection::table_exists(&conn, "rolling").unwrap());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn truncate_sql_table_schema_silently_ignored_on_sqlite() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE t (x INTEGER);").unwrap();
        super::SqlConnection::execute_batch(&conn, "INSERT INTO t VALUES (1);").unwrap();
        truncate_sql_table(&conn, "t", Some("ignored_on_sqlite"))
            .expect("schema arg must not error on SQLite");
        let count = super::SqlConnection::query(&conn, "SELECT COUNT(*) FROM t", &[]).unwrap();
        assert_eq!(count.rows[0][0], Scalar::Int64(0));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn truncate_sql_table_rejects_invalid_table_name() {
        let conn = make_sql_test_conn();
        let err = truncate_sql_table(&conn, "x; DROP TABLE users", None)
            .expect_err("must reject invalid identifier");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("invalid")));
    }

    #[test]
    fn truncate_sql_table_routes_schema_to_quote_identifier() {
        // Multi-schema backend stub records the SQL it receives.
        use std::cell::RefCell;
        struct PgLikeRecorder {
            statements: RefCell<Vec<String>>,
        }
        impl super::SqlConnection for PgLikeRecorder {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, sql: &str) -> Result<(), IoError> {
                self.statements.borrow_mut().push(sql.to_owned());
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
        }
        let conn = PgLikeRecorder {
            statements: RefCell::new(vec![]),
        };
        truncate_sql_table(&conn, "events", Some("analytics")).unwrap();
        let stmts = conn.statements.borrow();
        assert_eq!(stmts.len(), 1);
        // Default impl uses DELETE FROM ... and quote_identifier on
        // both schema + table parts.
        assert!(
            stmts[0].contains("DELETE FROM \"analytics\".\"events\""),
            "expected schema-qualified DELETE; got: {}",
            stmts[0]
        );
    }

    #[test]
    fn truncate_sql_table_backend_override_uses_truncate_keyword() {
        // PG/MySQL impls would override with TRUNCATE TABLE for speed.
        // Verify the trait dispatch picks up the override.
        use std::cell::RefCell;
        struct FastTruncate {
            statements: RefCell<Vec<String>>,
        }
        impl super::SqlConnection for FastTruncate {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, sql: &str) -> Result<(), IoError> {
                self.statements.borrow_mut().push(sql.to_owned());
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn truncate_table(
                &self,
                table_name: &str,
                _schema: Option<&str>,
            ) -> Result<(), IoError> {
                self.execute_batch(&format!("TRUNCATE TABLE \"{table_name}\""))
            }
        }
        let conn = FastTruncate {
            statements: RefCell::new(vec![]),
        };
        truncate_sql_table(&conn, "events", None).unwrap();
        let stmts = conn.statements.borrow();
        assert_eq!(stmts.len(), 1);
        assert!(stmts[0].starts_with("TRUNCATE TABLE"), "got: {}", stmts[0]);
    }

    // ── sql_server_version / SqlConnection::server_version (br-e23k / fd90.24) ─

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_server_version_returns_sqlite_version_string() {
        let conn = make_sql_test_conn();
        let version = sql_server_version(&conn)
            .unwrap()
            .expect("SQLite reports version");
        // Expect dotted-version format like "3.45.1". The parts must be
        // non-empty digits — exact value depends on the bundled SQLite.
        let parts: Vec<&str> = version.split('.').collect();
        assert!(parts.len() >= 2, "expected dotted version; got: {version}");
        for part in &parts {
            assert!(
                !part.is_empty() && part.chars().all(|c| c.is_ascii_digit()),
                "expected numeric version parts; got {version}"
            );
        }
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_server_version_starts_with_three_for_sqlite_3_x() {
        // SQLite has been at major version 3 since 2004; bundled
        // rusqlite is current (3.40+), so the major must be "3".
        let conn = make_sql_test_conn();
        let version = sql_server_version(&conn).unwrap().unwrap();
        assert!(
            version.starts_with("3."),
            "expected SQLite 3.x; got {version}"
        );
    }

    #[test]
    fn sql_server_version_default_impl_returns_none() {
        struct NoIntrospection;
        impl super::SqlConnection for NoIntrospection {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        let conn = NoIntrospection;
        assert!(sql_server_version(&conn).unwrap().is_none());
    }

    #[test]
    fn sql_server_version_routes_to_backend_override() {
        struct PgLikeStub;
        impl super::SqlConnection for PgLikeStub {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn server_version(&self) -> Result<Option<String>, IoError> {
                // Mimic `SHOW server_version` payload.
                Ok(Some("16.2".to_owned()))
            }
        }
        let conn = PgLikeStub;
        assert_eq!(sql_server_version(&conn).unwrap().as_deref(), Some("16.2"));
    }

    #[test]
    fn sql_server_version_propagates_backend_error() {
        struct BrokenIntrospection;
        impl super::SqlConnection for BrokenIntrospection {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn server_version(&self) -> Result<Option<String>, IoError> {
                Err(IoError::Sql("connection lost".to_owned()))
            }
        }
        let conn = BrokenIntrospection;
        let err = sql_server_version(&conn).expect_err("should surface backend error");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("connection lost")));
    }

    // ── sql_primary_key_columns / SqlConnection::primary_key_columns
    //    (br-uw3y / fd90.25) ────────────────────────────────────────────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_primary_key_columns_unknown_table_returns_empty() {
        let conn = make_sql_test_conn();
        let pk = sql_primary_key_columns(&conn, "no_such_table", None).unwrap();
        assert!(pk.is_empty());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_primary_key_columns_table_without_pk_returns_empty() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE no_pk (a INTEGER, b TEXT);")
            .unwrap();
        let pk = sql_primary_key_columns(&conn, "no_pk", None).unwrap();
        assert!(pk.is_empty());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_primary_key_columns_single_pk() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE single_pk (id INTEGER PRIMARY KEY, name TEXT);",
        )
        .unwrap();
        let pk = sql_primary_key_columns(&conn, "single_pk", None).unwrap();
        assert_eq!(pk, vec!["id"]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_primary_key_columns_composite_pk_ordered_by_ordinal() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE composite ( \
                year INTEGER NOT NULL, \
                month INTEGER NOT NULL, \
                code TEXT NOT NULL, \
                value REAL, \
                PRIMARY KEY (year, month, code) \
             );",
        )
        .unwrap();
        let pk = sql_primary_key_columns(&conn, "composite", None).unwrap();
        // PK declaration order: year, month, code.
        assert_eq!(pk, vec!["year", "month", "code"]);
    }

    #[test]
    fn sql_primary_key_columns_default_impl_returns_empty_when_no_introspection() {
        // Backend with no table_schema override returns Ok(None) →
        // primary_key_columns falls through to empty Vec.
        struct NoIntrospection;
        impl super::SqlConnection for NoIntrospection {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        let conn = NoIntrospection;
        assert!(
            sql_primary_key_columns(&conn, "anything", None)
                .unwrap()
                .is_empty()
        );
    }

    #[test]
    fn sql_primary_key_columns_routes_schema_to_table_schema_override() {
        // Backend that returns ordinal-sorted PK columns from a
        // multi-schema introspection.
        struct MultiSchemaPk;
        impl super::SqlConnection for MultiSchemaPk {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn table_schema(
                &self,
                table: &str,
                schema: Option<&str>,
            ) -> Result<Option<SqlTableSchema>, IoError> {
                if table == "events" && schema == Some("analytics") {
                    Ok(Some(SqlTableSchema {
                        table_name: "events".to_owned(),
                        columns: vec![
                            // Intentionally out-of-declaration-order to
                            // verify the helper sorts by ordinal.
                            SqlColumnSchema {
                                name: "code".to_owned(),
                                declared_type: Some("TEXT".to_owned()),
                                nullable: false,
                                default_value: None,
                                primary_key_ordinal: Some(2),
                                comment: None,
                                autoincrement: false,
                            },
                            SqlColumnSchema {
                                name: "year".to_owned(),
                                declared_type: Some("INTEGER".to_owned()),
                                nullable: false,
                                default_value: None,
                                primary_key_ordinal: Some(0),
                                comment: None,
                                autoincrement: false,
                            },
                            SqlColumnSchema {
                                name: "value".to_owned(),
                                declared_type: Some("REAL".to_owned()),
                                nullable: true,
                                default_value: None,
                                primary_key_ordinal: None,
                                comment: None,
                                autoincrement: false,
                            },
                            SqlColumnSchema {
                                name: "month".to_owned(),
                                declared_type: Some("INTEGER".to_owned()),
                                nullable: false,
                                default_value: None,
                                primary_key_ordinal: Some(1),
                                comment: None,
                                autoincrement: false,
                            },
                        ],
                    }))
                } else {
                    Ok(None)
                }
            }
        }
        let conn = MultiSchemaPk;
        let pk = sql_primary_key_columns(&conn, "events", Some("analytics")).unwrap();
        // Sorted by primary_key_ordinal: 0=year, 1=month, 2=code.
        assert_eq!(pk, vec!["year", "month", "code"]);
        // Wrong schema → empty (table_schema returns None).
        assert!(
            sql_primary_key_columns(&conn, "events", Some("audit"))
                .unwrap()
                .is_empty()
        );
    }

    // ── sql_max_identifier_length / SqlConnection::max_identifier_length
    //    (br-cs81 / fd90.26) ────────────────────────────────────────────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_max_identifier_length_returns_none_on_sqlite() {
        // SQLite has no documented identifier-length limit; the trait
        // default (None) is the right answer.
        let conn = make_sql_test_conn();
        assert_eq!(sql_max_identifier_length(&conn), None);
    }

    #[test]
    fn sql_max_identifier_length_default_impl_returns_none() {
        struct Generic;
        impl super::SqlConnection for Generic {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        assert_eq!(sql_max_identifier_length(&Generic), None);
    }

    #[test]
    fn sql_max_identifier_length_pg_override_reports_63() {
        struct PgLikeStub;
        impl super::SqlConnection for PgLikeStub {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn max_identifier_length(&self) -> Option<usize> {
                Some(63)
            }
        }
        assert_eq!(sql_max_identifier_length(&PgLikeStub), Some(63));
    }

    #[test]
    fn sql_max_identifier_length_mysql_override_reports_64() {
        struct MySqlLikeStub;
        impl super::SqlConnection for MySqlLikeStub {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn max_identifier_length(&self) -> Option<usize> {
                Some(64)
            }
        }
        assert_eq!(sql_max_identifier_length(&MySqlLikeStub), Some(64));
    }

    #[test]
    fn sql_max_identifier_length_mssql_override_reports_128() {
        struct MsSqlLikeStub;
        impl super::SqlConnection for MsSqlLikeStub {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn max_identifier_length(&self) -> Option<usize> {
                Some(128)
            }
        }
        assert_eq!(sql_max_identifier_length(&MsSqlLikeStub), Some(128));
    }

    // ── sql backend capability probes / SqlInspector caps
    //    (frankenpandas-fd90.10) ───────────────────────────────────────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_backend_caps_sqlite_reports_param_and_row_caps() {
        let conn = make_sql_test_conn();
        let caps = sql_backend_caps(&conn).unwrap();

        assert_eq!(caps.dialect_name, "sqlite");
        assert!(
            caps.server_version
                .as_deref()
                .is_some_and(|v| v.starts_with("3."))
        );
        assert!(caps.supports_returning);
        assert!(!caps.supports_schemas);
        assert_eq!(caps.max_param_count, Some(32766));
        assert_eq!(caps.max_identifier_length, None);
        assert_eq!(caps.max_insert_rows(3), Some(10922));
        assert_eq!(caps.max_insert_rows(0), None);
        assert_eq!(sql_max_param_count(&conn), Some(32766));
        assert_eq!(sql_max_insert_rows(&conn, 4), Some(8191));
        assert!(sql_supports_returning(&conn));
        assert!(!sql_supports_schemas(&conn));
    }

    #[test]
    fn sql_inspector_backend_caps_pg_like_stub_reports_limits() {
        struct PgLikeCaps;
        impl super::SqlConnection for PgLikeCaps {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn dialect_name(&self) -> &'static str {
                "postgresql"
            }
            fn server_version(&self) -> Result<Option<String>, IoError> {
                Ok(Some("16.3".to_owned()))
            }
            fn supports_returning(&self) -> bool {
                true
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn max_param_count(&self) -> Option<usize> {
                Some(65535)
            }
            fn max_identifier_length(&self) -> Option<usize> {
                Some(63)
            }
        }

        let conn = PgLikeCaps;
        let inspector = SqlInspector::new(&conn);
        let caps = inspector.backend_caps().unwrap();

        assert_eq!(inspector.dialect_name(), "postgresql");
        assert_eq!(inspector.server_version().unwrap().as_deref(), Some("16.3"));
        assert!(inspector.supports_returning());
        assert!(inspector.supports_schemas());
        assert_eq!(inspector.max_param_count(), Some(65535));
        assert_eq!(inspector.max_identifier_length(), Some(63));
        assert_eq!(inspector.max_insert_rows(4), Some(16383));
        assert_eq!(caps.max_insert_rows(4), Some(16383));
        assert_eq!(
            caps,
            SqlBackendCaps {
                dialect_name: "postgresql",
                server_version: Some("16.3".to_owned()),
                supports_returning: true,
                supports_schemas: true,
                max_param_count: Some(65535),
                max_identifier_length: Some(63),
            }
        );
    }

    // ── write_sql identifier-length validation (br-9ynk / fd90.27) ────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn write_sql_long_column_name_succeeds_on_sqlite() {
        // SQLite reports max_identifier_length() == None → no validation.
        let conn = make_sql_test_conn();
        // 80 chars > PG/MySQL caps but fine on SQLite.
        let long_col: String = std::iter::repeat_n('a', 80).collect();
        let frame = fp_frame::DataFrame::from_dict(
            &[long_col.as_str()],
            vec![(long_col.as_str(), vec![Scalar::Int64(1)])],
        )
        .unwrap();
        write_sql_with_options(
            &frame,
            &conn,
            "long_col_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect("SQLite has no identifier limit");
    }

    fn make_pg_like_recorder() -> impl super::SqlConnection + 'static {
        // Stub PG-like backend: enforces 63-char limit, accepts all
        // execute_batch / insert_rows so write_sql can reach the
        // identifier-length check before failing on emit.
        struct PgLikeLimit;
        impl super::SqlConnection for PgLikeLimit {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn max_identifier_length(&self) -> Option<usize> {
                Some(63)
            }
            fn supports_schemas(&self) -> bool {
                true
            }
        }
        PgLikeLimit
    }

    #[test]
    fn write_sql_rejects_long_column_name_on_pg_like_backend() {
        let conn = make_pg_like_recorder();
        let long_col: String = std::iter::repeat_n('c', 64).collect();
        let frame = fp_frame::DataFrame::from_dict(
            &[long_col.as_str()],
            vec![(long_col.as_str(), vec![Scalar::Int64(1)])],
        )
        .unwrap();
        let err = write_sql_with_options(
            &frame,
            &conn,
            "ok_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect_err("64-char column must exceed PG limit");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("column") && msg.contains("63")));
    }

    #[test]
    fn write_sql_rejects_long_table_name_on_pg_like_backend() {
        let conn = make_pg_like_recorder();
        // 64-char identifier (table names also subject to the PG cap).
        // Use only alphanumeric so validate_sql_table_name passes first.
        let long_tbl: String = std::iter::repeat_n('t', 64).collect();
        let frame =
            fp_frame::DataFrame::from_dict(&["x"], vec![("x", vec![Scalar::Int64(1)])]).unwrap();
        let err = write_sql_with_options(
            &frame,
            &conn,
            &long_tbl,
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect_err("64-char table must exceed PG limit");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("table") && msg.contains("63")));
    }

    #[test]
    fn write_sql_rejects_long_index_label_on_pg_like_backend() {
        let conn = make_pg_like_recorder();
        let long_label: String = std::iter::repeat_n('i', 64).collect();
        let frame =
            fp_frame::DataFrame::from_dict(&["x"], vec![("x", vec![Scalar::Int64(1)])]).unwrap();
        let err = write_sql_with_options(
            &frame,
            &conn,
            "ok_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: true,
                index_label: Some(long_label),
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect_err("64-char index label must exceed PG limit");
        assert!(
            matches!(err, IoError::Sql(msg) if msg.contains("index label") && msg.contains("63"))
        );
    }

    #[test]
    fn write_sql_rejects_long_schema_name_on_pg_like_backend() {
        let conn = make_pg_like_recorder();
        let long_schema: String = std::iter::repeat_n('s', 64).collect();
        let frame =
            fp_frame::DataFrame::from_dict(&["x"], vec![("x", vec![Scalar::Int64(1)])]).unwrap();
        let err = write_sql_with_options(
            &frame,
            &conn,
            "ok_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: Some(long_schema),
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect_err("64-char schema must exceed PG limit");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("schema") && msg.contains("63")));
    }

    #[test]
    fn write_sql_just_at_the_boundary_is_accepted() {
        let conn = make_pg_like_recorder();
        // Exactly 63 chars: at the PG limit, must be accepted.
        let just_fits: String = std::iter::repeat_n('a', 63).collect();
        let frame = fp_frame::DataFrame::from_dict(
            &[just_fits.as_str()],
            vec![(just_fits.as_str(), vec![Scalar::Int64(1)])],
        )
        .unwrap();
        write_sql_with_options(
            &frame,
            &conn,
            "ok_tbl",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .expect("63-char column at boundary should be accepted");
    }

    // ── list_sql_indexes / SqlConnection::list_indexes (br-bgv9 / fd90.28) ─

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_indexes_unknown_table_returns_empty() {
        let conn = make_sql_test_conn();
        let indexes = list_sql_indexes(&conn, "no_such_tbl", None).unwrap();
        assert!(indexes.is_empty());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_indexes_table_without_indexes() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE plain (a INTEGER, b TEXT);")
            .unwrap();
        let indexes = list_sql_indexes(&conn, "plain", None).unwrap();
        assert!(indexes.is_empty());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_indexes_single_column() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE events (id INTEGER, ts TEXT);")
            .unwrap();
        super::SqlConnection::execute_batch(&conn, "CREATE INDEX idx_events_ts ON events (ts);")
            .unwrap();
        let indexes = list_sql_indexes(&conn, "events", None).unwrap();
        assert_eq!(indexes.len(), 1);
        assert_eq!(indexes[0].name, "idx_events_ts");
        assert_eq!(indexes[0].columns, vec!["ts"]);
        assert!(!indexes[0].unique);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_indexes_unique_index() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE users (id INTEGER, email TEXT);")
            .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE UNIQUE INDEX idx_users_email ON users (email);",
        )
        .unwrap();
        let indexes = list_sql_indexes(&conn, "users", None).unwrap();
        assert_eq!(indexes.len(), 1);
        assert_eq!(indexes[0].name, "idx_users_email");
        assert_eq!(indexes[0].columns, vec!["email"]);
        assert!(indexes[0].unique);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_indexes_composite_columns_in_definition_order() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE rolling (year INT, month INT, code TEXT, val REAL);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE INDEX idx_rolling_y_m_c ON rolling (year, month, code);",
        )
        .unwrap();
        let indexes = list_sql_indexes(&conn, "rolling", None).unwrap();
        assert_eq!(indexes.len(), 1);
        assert_eq!(indexes[0].columns, vec!["year", "month", "code"]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_indexes_filters_pk_auto_index() {
        // INTEGER PRIMARY KEY in SQLite creates an automatic index that
        // SQLAlchemy.Inspector hides. We must hide it too — only the
        // explicit CREATE INDEX should surface.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE pk_only (id INTEGER PRIMARY KEY, name TEXT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE INDEX idx_pk_only_name ON pk_only (name);",
        )
        .unwrap();
        let indexes = list_sql_indexes(&conn, "pk_only", None).unwrap();
        // Only the explicit user index should appear.
        assert_eq!(indexes.len(), 1);
        assert_eq!(indexes[0].name, "idx_pk_only_name");
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_indexes_rejects_invalid_table_name() {
        let conn = make_sql_test_conn();
        let err = list_sql_indexes(&conn, "x; DROP TABLE users", None)
            .expect_err("must reject invalid identifier");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("invalid")));
    }

    #[test]
    fn list_sql_indexes_default_impl_returns_empty() {
        struct NoIntrospection;
        impl super::SqlConnection for NoIntrospection {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        assert!(
            list_sql_indexes(&NoIntrospection, "anything", None)
                .unwrap()
                .is_empty()
        );
    }

    #[test]
    fn list_sql_indexes_routes_to_backend_override() {
        struct MultiSchemaIdx;
        impl super::SqlConnection for MultiSchemaIdx {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn list_indexes(
                &self,
                table: &str,
                schema: Option<&str>,
            ) -> Result<Vec<SqlIndexSchema>, IoError> {
                if table == "events" && schema == Some("analytics") {
                    Ok(vec![
                        SqlIndexSchema {
                            name: "idx_events_ts".to_owned(),
                            columns: vec!["ts".to_owned()],
                            unique: false,
                        },
                        SqlIndexSchema {
                            name: "uq_events_uid".to_owned(),
                            columns: vec!["user_id".to_owned()],
                            unique: true,
                        },
                    ])
                } else {
                    Ok(vec![])
                }
            }
        }
        let conn = MultiSchemaIdx;
        let indexes = list_sql_indexes(&conn, "events", Some("analytics")).unwrap();
        assert_eq!(indexes.len(), 2);
        assert!(
            indexes
                .iter()
                .any(|i| i.unique && i.name == "uq_events_uid")
        );
        // Wrong schema → empty (override scopes by Some).
        assert!(
            list_sql_indexes(&conn, "events", Some("audit"))
                .unwrap()
                .is_empty()
        );
    }

    // ── list_sql_foreign_keys / SqlConnection::list_foreign_keys
    //    (br-uht8 / fd90.29) ────────────────────────────────────────────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_foreign_keys_unknown_table_returns_empty() {
        let conn = make_sql_test_conn();
        let fks = list_sql_foreign_keys(&conn, "no_such_tbl", None).unwrap();
        assert!(fks.is_empty());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_foreign_keys_table_without_fk() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE plain (a INTEGER, b TEXT);")
            .unwrap();
        let fks = list_sql_foreign_keys(&conn, "plain", None).unwrap();
        assert!(fks.is_empty());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_foreign_keys_single_column_fk() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE parent (id INTEGER PRIMARY KEY, label TEXT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE child (cid INTEGER, parent_id INTEGER, \
             FOREIGN KEY (parent_id) REFERENCES parent(id));",
        )
        .unwrap();
        let fks = list_sql_foreign_keys(&conn, "child", None).unwrap();
        assert_eq!(fks.len(), 1);
        assert_eq!(fks[0].columns, vec!["parent_id"]);
        assert_eq!(fks[0].referenced_table, "parent");
        assert_eq!(fks[0].referenced_columns, vec!["id"]);
        // SQLite PRAGMA does not surface constraint names.
        assert!(fks[0].constraint_name.is_none());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_foreign_keys_composite_fk_ordered_by_seq() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE rolling ( \
                year INTEGER NOT NULL, \
                month INTEGER NOT NULL, \
                code TEXT NOT NULL, \
                PRIMARY KEY (year, month, code) \
             );",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE rolling_fact ( \
                fact_id INTEGER, year INTEGER, month INTEGER, code TEXT, \
                FOREIGN KEY (year, month, code) \
                  REFERENCES rolling(year, month, code) \
             );",
        )
        .unwrap();
        let fks = list_sql_foreign_keys(&conn, "rolling_fact", None).unwrap();
        assert_eq!(fks.len(), 1);
        // Pairs preserved in declaration order (seq=0,1,2).
        assert_eq!(fks[0].columns, vec!["year", "month", "code"]);
        assert_eq!(fks[0].referenced_columns, vec!["year", "month", "code"]);
        assert_eq!(fks[0].referenced_table, "rolling");
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_foreign_keys_multiple_fks_on_one_table() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE users (id INTEGER PRIMARY KEY);")
            .unwrap();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE products (sku TEXT PRIMARY KEY);")
            .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE orders ( \
                oid INTEGER, \
                user_id INTEGER, \
                product_sku TEXT, \
                FOREIGN KEY (user_id) REFERENCES users(id), \
                FOREIGN KEY (product_sku) REFERENCES products(sku) \
             );",
        )
        .unwrap();
        let fks = list_sql_foreign_keys(&conn, "orders", None).unwrap();
        assert_eq!(fks.len(), 2);
        let user_fk = fks.iter().find(|f| f.referenced_table == "users").unwrap();
        assert_eq!(user_fk.columns, vec!["user_id"]);
        assert_eq!(user_fk.referenced_columns, vec!["id"]);
        let prod_fk = fks
            .iter()
            .find(|f| f.referenced_table == "products")
            .unwrap();
        assert_eq!(prod_fk.columns, vec!["product_sku"]);
        assert_eq!(prod_fk.referenced_columns, vec!["sku"]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_foreign_keys_rejects_invalid_table_name() {
        let conn = make_sql_test_conn();
        let err = list_sql_foreign_keys(&conn, "x; DROP TABLE users", None)
            .expect_err("must reject invalid identifier");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("invalid")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_foreign_keys_resolves_implicit_pk_single_column() {
        // Per fd90.44: FOREIGN KEY (parent_id) REFERENCES parent
        // (no column list) is an implicit reference to parent's PK.
        // SQLite returns NULL for the 'to' column; we now resolve via
        // the parent's primary_key_columns.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE imp_parent (pid INTEGER PRIMARY KEY, label TEXT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE imp_child ( \
                cid INTEGER, \
                parent_id INTEGER, \
                FOREIGN KEY (parent_id) REFERENCES imp_parent \
             );",
        )
        .unwrap();
        let fks = list_sql_foreign_keys(&conn, "imp_child", None).unwrap();
        assert_eq!(
            fks.len(),
            1,
            "implicit-PK FK must surface (was being silently dropped)"
        );
        assert_eq!(fks[0].columns, vec!["parent_id"]);
        assert_eq!(fks[0].referenced_table, "imp_parent");
        // resolved from parent's PK.
        assert_eq!(fks[0].referenced_columns, vec!["pid"]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_foreign_keys_resolves_implicit_pk_composite() {
        // Composite FK with implicit reference to composite PK.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE imp_parent_comp ( \
                year INTEGER NOT NULL, \
                month INTEGER NOT NULL, \
                PRIMARY KEY (year, month) \
             );",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE imp_child_comp ( \
                cid INTEGER, \
                fyear INTEGER NOT NULL, \
                fmonth INTEGER NOT NULL, \
                FOREIGN KEY (fyear, fmonth) REFERENCES imp_parent_comp \
             );",
        )
        .unwrap();
        let fks = list_sql_foreign_keys(&conn, "imp_child_comp", None).unwrap();
        assert_eq!(fks.len(), 1);
        assert_eq!(fks[0].columns, vec!["fyear", "fmonth"]);
        assert_eq!(fks[0].referenced_table, "imp_parent_comp");
        // Resolved from composite PK in declaration order.
        assert_eq!(fks[0].referenced_columns, vec!["year", "month"]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_foreign_keys_explicit_columns_unchanged() {
        // Existing behavior preserved: explicit columns still
        // round-trip exactly as before fd90.44.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE exp_parent (pid INTEGER PRIMARY KEY);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE exp_child ( \
                cid INTEGER, \
                parent_id INTEGER, \
                FOREIGN KEY (parent_id) REFERENCES exp_parent(pid) \
             );",
        )
        .unwrap();
        let fks = list_sql_foreign_keys(&conn, "exp_child", None).unwrap();
        assert_eq!(fks.len(), 1);
        assert_eq!(fks[0].columns, vec!["parent_id"]);
        assert_eq!(fks[0].referenced_columns, vec!["pid"]);
    }

    #[test]
    fn list_sql_foreign_keys_default_impl_returns_empty() {
        struct NoIntrospection;
        impl super::SqlConnection for NoIntrospection {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        assert!(
            list_sql_foreign_keys(&NoIntrospection, "anything", None)
                .unwrap()
                .is_empty()
        );
    }

    #[test]
    fn list_sql_foreign_keys_routes_to_backend_override() {
        struct MultiSchemaFk;
        impl super::SqlConnection for MultiSchemaFk {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn list_foreign_keys(
                &self,
                table: &str,
                schema: Option<&str>,
            ) -> Result<Vec<SqlForeignKeySchema>, IoError> {
                if table == "orders" && schema == Some("sales") {
                    Ok(vec![SqlForeignKeySchema {
                        constraint_name: Some("orders_user_fk".to_owned()),
                        columns: vec!["user_id".to_owned()],
                        referenced_table: "users".to_owned(),
                        referenced_columns: vec!["id".to_owned()],
                    }])
                } else {
                    Ok(vec![])
                }
            }
        }
        let conn = MultiSchemaFk;
        let fks = list_sql_foreign_keys(&conn, "orders", Some("sales")).unwrap();
        assert_eq!(fks.len(), 1);
        assert_eq!(fks[0].constraint_name.as_deref(), Some("orders_user_fk"));
        assert_eq!(fks[0].referenced_table, "users");
        // Wrong schema → empty (override scopes by Some).
        assert!(
            list_sql_foreign_keys(&conn, "orders", Some("audit"))
                .unwrap()
                .is_empty()
        );
    }

    // ── list_sql_views / SqlConnection::list_views (br-gm3r / fd90.30) ────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_views_empty_db_returns_empty() {
        let conn = make_sql_test_conn();
        let views = list_sql_views(&conn, None).unwrap();
        assert!(views.is_empty());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_views_returns_user_views_sorted() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE base (id INTEGER, val TEXT);")
            .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE VIEW zebra_view AS SELECT id FROM base;",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE VIEW alpha_view AS SELECT val FROM base;",
        )
        .unwrap();
        let views = list_sql_views(&conn, None).unwrap();
        assert_eq!(views, vec!["alpha_view", "zebra_view"]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_views_separated_from_list_tables() {
        // list_views must NOT surface tables; list_tables must NOT surface
        // views. The two buckets are disjoint per SQLAlchemy.Inspector.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE just_tbl (x INTEGER);").unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE VIEW just_view AS SELECT x FROM just_tbl;",
        )
        .unwrap();

        let tables = list_sql_tables(&conn, None).unwrap();
        let views = list_sql_views(&conn, None).unwrap();
        assert_eq!(tables, vec!["just_tbl"]);
        assert_eq!(views, vec!["just_view"]);
        assert!(!tables.contains(&"just_view".to_owned()));
        assert!(!views.contains(&"just_tbl".to_owned()));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_views_schema_silently_ignored_on_sqlite() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE t (x INTEGER);").unwrap();
        super::SqlConnection::execute_batch(&conn, "CREATE VIEW v AS SELECT x FROM t;").unwrap();
        let with_schema =
            list_sql_views(&conn, Some("ignored_on_sqlite")).expect("schema arg must not error");
        let without_schema = list_sql_views(&conn, None).unwrap();
        assert_eq!(with_schema, without_schema);
    }

    #[test]
    fn list_sql_views_default_impl_returns_empty() {
        struct NoIntrospection;
        impl super::SqlConnection for NoIntrospection {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        let conn = NoIntrospection;
        assert!(list_sql_views(&conn, None).unwrap().is_empty());
        assert!(list_sql_views(&conn, Some("any")).unwrap().is_empty());
    }

    #[test]
    fn list_sql_views_routes_schema_to_backend_override() {
        struct MultiSchemaViews;
        impl super::SqlConnection for MultiSchemaViews {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn list_views(&self, schema: Option<&str>) -> Result<Vec<String>, IoError> {
                Ok(match schema {
                    Some("reporting") => vec!["daily".to_owned(), "weekly".to_owned()],
                    Some("audit") => vec!["log_view".to_owned()],
                    _ => vec![],
                })
            }
        }
        let conn = MultiSchemaViews;
        assert_eq!(
            list_sql_views(&conn, Some("reporting")).unwrap(),
            vec!["daily", "weekly"]
        );
        assert_eq!(
            list_sql_views(&conn, Some("audit")).unwrap(),
            vec!["log_view"]
        );
        assert!(list_sql_views(&conn, None).unwrap().is_empty());
    }

    // ── list_sql_unique_constraints / SqlConnection::list_unique_constraints
    //    (br-sh4v / fd90.31) ────────────────────────────────────────────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_unique_constraints_unknown_table_returns_empty() {
        let conn = make_sql_test_conn();
        let uqs = list_sql_unique_constraints(&conn, "no_such", None).unwrap();
        assert!(uqs.is_empty());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_unique_constraints_table_without_uq() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE plain (a INTEGER, b TEXT);")
            .unwrap();
        let uqs = list_sql_unique_constraints(&conn, "plain", None).unwrap();
        assert!(uqs.is_empty());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_unique_constraints_inline_unique() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT UNIQUE);",
        )
        .unwrap();
        let uqs = list_sql_unique_constraints(&conn, "users", None).unwrap();
        assert_eq!(uqs.len(), 1);
        assert_eq!(uqs[0].columns, vec!["email"]);
        // SQLite gives backend-generated names like sqlite_autoindex_users_1.
        assert!(
            uqs[0].name.starts_with("sqlite_autoindex_users_"),
            "expected sqlite_autoindex_ name; got {}",
            uqs[0].name
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_unique_constraints_composite_table_constraint() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE rolling ( \
                year INTEGER, month INTEGER, code TEXT, val REAL, \
                UNIQUE (year, month, code) \
             );",
        )
        .unwrap();
        let uqs = list_sql_unique_constraints(&conn, "rolling", None).unwrap();
        assert_eq!(uqs.len(), 1);
        assert_eq!(uqs[0].columns, vec!["year", "month", "code"]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_unique_constraints_disjoint_from_create_unique_index() {
        // Per SQLAlchemy: get_unique_constraints surfaces declared UNIQUE
        // constraints (origin='u'); get_indexes surfaces user-created
        // CREATE UNIQUE INDEX (origin='c'). The two must be disjoint.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE mixed ( \
                a INTEGER, \
                b TEXT, \
                c TEXT, \
                UNIQUE (a) \
             );",
        )
        .unwrap();
        super::SqlConnection::execute_batch(&conn, "CREATE UNIQUE INDEX idx_mixed_b ON mixed (b);")
            .unwrap();

        let uqs = list_sql_unique_constraints(&conn, "mixed", None).unwrap();
        let idxs = list_sql_indexes(&conn, "mixed", None).unwrap();

        // The UNIQUE constraint is in uqs only.
        assert_eq!(uqs.len(), 1);
        assert_eq!(uqs[0].columns, vec!["a"]);
        // The CREATE UNIQUE INDEX is in idxs only.
        assert_eq!(idxs.len(), 1);
        assert_eq!(idxs[0].name, "idx_mixed_b");
        assert!(idxs[0].unique);
        assert_eq!(idxs[0].columns, vec!["b"]);

        // No overlap by name (uqs uses sqlite_autoindex_, idxs uses idx_).
        assert!(!uqs.iter().any(|u| u.name == "idx_mixed_b"));
        assert!(!idxs.iter().any(|i| i.name.starts_with("sqlite_autoindex_")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn list_sql_unique_constraints_rejects_invalid_table_name() {
        let conn = make_sql_test_conn();
        let err = list_sql_unique_constraints(&conn, "x; DROP TABLE users", None)
            .expect_err("must reject invalid identifier");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("invalid")));
    }

    #[test]
    fn list_sql_unique_constraints_default_impl_returns_empty() {
        struct NoIntrospection;
        impl super::SqlConnection for NoIntrospection {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        assert!(
            list_sql_unique_constraints(&NoIntrospection, "anything", None)
                .unwrap()
                .is_empty()
        );
    }

    #[test]
    fn list_sql_unique_constraints_routes_to_backend_override() {
        struct MultiSchemaUq;
        impl super::SqlConnection for MultiSchemaUq {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn list_unique_constraints(
                &self,
                table: &str,
                schema: Option<&str>,
            ) -> Result<Vec<SqlUniqueConstraintSchema>, IoError> {
                if table == "users" && schema == Some("public") {
                    Ok(vec![SqlUniqueConstraintSchema {
                        name: "users_email_key".to_owned(),
                        columns: vec!["email".to_owned()],
                    }])
                } else {
                    Ok(vec![])
                }
            }
        }
        let conn = MultiSchemaUq;
        let uqs = list_sql_unique_constraints(&conn, "users", Some("public")).unwrap();
        assert_eq!(uqs.len(), 1);
        assert_eq!(uqs[0].name, "users_email_key");
        assert!(
            list_sql_unique_constraints(&conn, "users", Some("audit"))
                .unwrap()
                .is_empty()
        );
    }

    // ── sql_table_comment / SqlConnection::table_comment (br-yu3w / fd90.32) ─

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_table_comment_returns_none_on_sqlite() {
        // SQLite has no native table-comment storage; the trait default
        // returns None even for a real table.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE t (x INTEGER);").unwrap();
        let comment = sql_table_comment(&conn, "t", None).unwrap();
        assert!(comment.is_none());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_table_comment_returns_none_on_sqlite_for_unknown_table() {
        let conn = make_sql_test_conn();
        let comment = sql_table_comment(&conn, "no_such", None).unwrap();
        assert!(comment.is_none());
    }

    #[test]
    fn sql_table_comment_default_impl_returns_none() {
        struct NoIntrospection;
        impl super::SqlConnection for NoIntrospection {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        let conn = NoIntrospection;
        assert!(
            sql_table_comment(&conn, "anything", None)
                .unwrap()
                .is_none()
        );
    }

    #[test]
    fn sql_table_comment_routes_to_backend_override() {
        struct PgLikeStub;
        impl super::SqlConnection for PgLikeStub {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn table_comment(
                &self,
                table: &str,
                schema: Option<&str>,
            ) -> Result<Option<String>, IoError> {
                if table == "users" && schema == Some("public") {
                    Ok(Some("Customer accounts table".to_owned()))
                } else {
                    Ok(None)
                }
            }
        }
        let conn = PgLikeStub;
        assert_eq!(
            sql_table_comment(&conn, "users", Some("public"))
                .unwrap()
                .as_deref(),
            Some("Customer accounts table")
        );
        assert!(
            sql_table_comment(&conn, "users", Some("audit"))
                .unwrap()
                .is_none()
        );
        assert!(
            sql_table_comment(&conn, "missing", Some("public"))
                .unwrap()
                .is_none()
        );
    }

    #[test]
    fn sql_table_comment_propagates_backend_error() {
        struct BrokenIntrospection;
        impl super::SqlConnection for BrokenIntrospection {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn table_comment(
                &self,
                _table: &str,
                _schema: Option<&str>,
            ) -> Result<Option<String>, IoError> {
                Err(IoError::Sql(
                    "permission denied for pg_description".to_owned(),
                ))
            }
        }
        let conn = BrokenIntrospection;
        let err =
            sql_table_comment(&conn, "anything", None).expect_err("backend error must surface");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("permission denied")));
    }

    // ── SqlWriteOptions::chunksize (br-ls9z / fd90.33) ────────────────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn write_sql_chunksize_zero_rejected() {
        let conn = make_sql_test_conn();
        let frame =
            fp_frame::DataFrame::from_dict(&["x"], vec![("x", vec![Scalar::Int64(1)])]).unwrap();
        let err = write_sql_with_options(
            &frame,
            &conn,
            "t",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: Some(0),
            },
        )
        .expect_err("chunksize=0 must be rejected");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("chunksize")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn write_sql_chunksize_none_preserves_single_transaction_semantics() {
        // 5 rows, chunksize=None — should round-trip cleanly into one
        // transaction (same as before fd90.33 landed).
        let conn = make_sql_test_conn();
        let frame = fp_frame::DataFrame::from_dict(
            &["id"],
            vec![(
                "id",
                vec![
                    Scalar::Int64(1),
                    Scalar::Int64(2),
                    Scalar::Int64(3),
                    Scalar::Int64(4),
                    Scalar::Int64(5),
                ],
            )],
        )
        .unwrap();
        write_sql_with_options(
            &frame,
            &conn,
            "no_chunk",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: None,
            },
        )
        .unwrap();
        let count =
            super::SqlConnection::query(&conn, "SELECT COUNT(*) FROM no_chunk", &[]).unwrap();
        assert_eq!(count.rows[0][0], Scalar::Int64(5));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn write_sql_single_chunksize_round_trips_all_rows() {
        // 5 rows with chunksize=2: chunks of (2, 2, 1). All rows must
        // round-trip and the table must contain every row regardless
        // of how the chunks committed.
        let conn = make_sql_test_conn();
        let frame = fp_frame::DataFrame::from_dict(
            &["id"],
            vec![(
                "id",
                vec![
                    Scalar::Int64(1),
                    Scalar::Int64(2),
                    Scalar::Int64(3),
                    Scalar::Int64(4),
                    Scalar::Int64(5),
                ],
            )],
        )
        .unwrap();
        write_sql_with_options(
            &frame,
            &conn,
            "chunked",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: Some(2),
            },
        )
        .unwrap();
        let result =
            super::SqlConnection::query(&conn, "SELECT id FROM chunked ORDER BY id", &[]).unwrap();
        let ids: Vec<i64> = result
            .rows
            .iter()
            .map(|r| match &r[0] {
                Scalar::Int64(v) => *v,
                other => unreachable!("unexpected scalar: {other:?}"),
            })
            .collect();
        assert_eq!(ids, vec![1, 2, 3, 4, 5]);
    }

    #[test]
    fn write_sql_single_chunksize_dispatches_correct_chunk_counts() {
        // Recording stub verifies the chunk boundaries.
        use std::cell::RefCell;
        struct Recorder {
            row_counts: RefCell<Vec<usize>>,
        }
        impl super::SqlConnection for Recorder {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                self.row_counts.borrow_mut().push(rows.len());
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
        }
        let conn = Recorder {
            row_counts: RefCell::new(vec![]),
        };
        let frame = fp_frame::DataFrame::from_dict(
            &["x"],
            vec![(
                "x",
                vec![
                    Scalar::Int64(1),
                    Scalar::Int64(2),
                    Scalar::Int64(3),
                    Scalar::Int64(4),
                    Scalar::Int64(5),
                ],
            )],
        )
        .unwrap();
        write_sql_with_options(
            &frame,
            &conn,
            "chunked",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Single,
                chunksize: Some(2),
            },
        )
        .unwrap();
        // Single mode: each chunk submits a slice of rows to insert_rows.
        // chunks of size 2, 2, 1 → 3 calls with row counts [2, 2, 1].
        assert_eq!(*conn.row_counts.borrow(), vec![2usize, 2, 1]);
    }

    #[test]
    fn write_sql_multi_chunksize_takes_min_with_param_cap() {
        // Multi mode with max_param_count=10, ncols=2 → param chunk = 5
        // rows. chunksize=3 should win (min(3, 5) = 3).
        // Multi mode flattens each chunk to a single insert_rows call
        // where rows[0].len() = chunk_size * ncols.
        use std::cell::RefCell;
        struct ParamCapRecorder {
            row_counts: RefCell<Vec<usize>>,
        }
        impl super::SqlConnection for ParamCapRecorder {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                // Multi mode passes a single flattened "row" per chunk.
                self.row_counts
                    .borrow_mut()
                    .push(rows.first().map_or(0, std::vec::Vec::len));
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn max_param_count(&self) -> Option<usize> {
                Some(10)
            }
        }
        let conn = ParamCapRecorder {
            row_counts: RefCell::new(vec![]),
        };
        let frame = fp_frame::DataFrame::from_dict(
            &["a", "b"],
            vec![
                (
                    "a",
                    vec![
                        Scalar::Int64(1),
                        Scalar::Int64(2),
                        Scalar::Int64(3),
                        Scalar::Int64(4),
                        Scalar::Int64(5),
                    ],
                ),
                (
                    "b",
                    vec![
                        Scalar::Int64(10),
                        Scalar::Int64(20),
                        Scalar::Int64(30),
                        Scalar::Int64(40),
                        Scalar::Int64(50),
                    ],
                ),
            ],
        )
        .unwrap();
        write_sql_with_options(
            &frame,
            &conn,
            "chunked",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Multi,
                chunksize: Some(3),
            },
        )
        .unwrap();
        // chunksize=3 wins over param cap (5). 5 rows / 3 per chunk = 2
        // chunks (3, 2). Flat scalars per chunk: 3*2=6 then 2*2=4.
        assert_eq!(*conn.row_counts.borrow(), vec![6usize, 4]);
    }

    #[test]
    fn write_sql_multi_chunksize_param_cap_wins_when_smaller() {
        // Param cap = 4 (ncols=2 → 2 rows/chunk). chunksize=10 (loose).
        // Effective chunk = min(10, 2) = 2.
        use std::cell::RefCell;
        struct TightCap {
            row_counts: RefCell<Vec<usize>>,
        }
        impl super::SqlConnection for TightCap {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                self.row_counts
                    .borrow_mut()
                    .push(rows.first().map_or(0, std::vec::Vec::len));
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn max_param_count(&self) -> Option<usize> {
                Some(4)
            }
        }
        let conn = TightCap {
            row_counts: RefCell::new(vec![]),
        };
        let frame = fp_frame::DataFrame::from_dict(
            &["a", "b"],
            vec![
                (
                    "a",
                    vec![
                        Scalar::Int64(1),
                        Scalar::Int64(2),
                        Scalar::Int64(3),
                        Scalar::Int64(4),
                        Scalar::Int64(5),
                    ],
                ),
                (
                    "b",
                    vec![
                        Scalar::Int64(10),
                        Scalar::Int64(20),
                        Scalar::Int64(30),
                        Scalar::Int64(40),
                        Scalar::Int64(50),
                    ],
                ),
            ],
        )
        .unwrap();
        write_sql_with_options(
            &frame,
            &conn,
            "chunked",
            &SqlWriteOptions {
                if_exists: SqlIfExists::Fail,
                index: false,
                index_label: None,
                schema: None,
                dtype: None,
                method: SqlInsertMethod::Multi,
                chunksize: Some(10),
            },
        )
        .unwrap();
        // 5 rows / 2 per chunk = 3 chunks (2, 2, 1). Flat scalars: 4, 4, 2.
        assert_eq!(*conn.row_counts.borrow(), vec![4usize, 4, 2]);
    }

    // ── SqlReadOptions::columns (br-d3e9 / fd90.34) ──────────────────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_table_with_options_columns_none_selects_all() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE projection_default (a INTEGER, b TEXT, c REAL);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "INSERT INTO projection_default VALUES (1, 'x', 1.5);",
        )
        .unwrap();
        let frame = read_sql_table_with_options(
            &conn,
            "projection_default",
            &SqlReadOptions {
                columns: None,
                ..Default::default()
            },
        )
        .unwrap();
        assert_eq!(frame.column_names(), vec!["a", "b", "c"]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_table_with_options_columns_projects_subset() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE projection (id INTEGER, name TEXT, ts TEXT, value REAL);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "INSERT INTO projection VALUES (1, 'a', '2024-01-01', 1.5), \
                                            (2, 'b', '2024-01-02', 2.5);",
        )
        .unwrap();
        let frame = read_sql_table_with_options(
            &conn,
            "projection",
            &SqlReadOptions {
                columns: Some(vec!["id".to_owned(), "name".to_owned()]),
                ..Default::default()
            },
        )
        .unwrap();
        // Only id + name, in that order.
        assert_eq!(frame.column_names(), vec!["id", "name"]);
        assert_eq!(frame.column("id").unwrap().values()[0], Scalar::Int64(1));
        assert_eq!(
            frame.column("name").unwrap().values()[0],
            Scalar::Utf8("a".into())
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_table_with_options_columns_preserves_specified_order() {
        // pandas: pd.read_sql_table(t, con, columns=['c', 'a']) →
        // returns ['c', 'a'] in that exact order, NOT alphabetical.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE ordered_proj (a INT, b INT, c INT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(&conn, "INSERT INTO ordered_proj VALUES (1, 2, 3);")
            .unwrap();
        let frame = read_sql_table_with_options(
            &conn,
            "ordered_proj",
            &SqlReadOptions {
                columns: Some(vec!["c".to_owned(), "a".to_owned()]),
                ..Default::default()
            },
        )
        .unwrap();
        assert_eq!(frame.column_names(), vec!["c", "a"]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_table_with_options_columns_empty_vec_rejected() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE t (x INTEGER);").unwrap();
        let err = read_sql_table_with_options(
            &conn,
            "t",
            &SqlReadOptions {
                columns: Some(vec![]),
                ..Default::default()
            },
        )
        .expect_err("empty columns must be rejected");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("columns must be non-empty")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_table_with_options_columns_invalid_name_rejected() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE t (x INTEGER);").unwrap();
        let err = read_sql_table_with_options(
            &conn,
            "t",
            &SqlReadOptions {
                columns: Some(vec!["x; DROP TABLE t".to_owned()]),
                ..Default::default()
            },
        )
        .expect_err("invalid column name must be rejected");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("invalid")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_table_with_options_columns_combines_with_parse_dates() {
        // columns + parse_dates: project a subset, then date-coerce.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE events (id INT, ts TEXT, note TEXT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "INSERT INTO events VALUES (1, '2024-01-15', 'launched');",
        )
        .unwrap();
        let frame = read_sql_table_with_options(
            &conn,
            "events",
            &SqlReadOptions {
                columns: Some(vec!["id".to_owned(), "ts".to_owned()]),
                index_col: None,
                parse_dates: Some(vec!["ts".to_owned()]),
                ..Default::default()
            },
        )
        .unwrap();
        // Only id + ts surfaced; ts was reformatted by parse_dates
        // (the project-then-coerce path emits the canonical
        // 'YYYY-MM-DD HH:MM:SS' shape via Scalar::Utf8).
        assert_eq!(frame.column_names(), vec!["id", "ts"]);
        assert_eq!(
            frame.column("ts").unwrap().values()[0],
            Scalar::Utf8("2024-01-15 00:00:00".to_owned())
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_table_chunks_with_options_columns_projects_before_chunking() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE chunk_projection (id INTEGER, name TEXT, hidden REAL);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "INSERT INTO chunk_projection VALUES \
                (1, 'a', 10.0), \
                (2, 'b', 20.0), \
                (3, 'c', 30.0);",
        )
        .unwrap();

        let chunks: Vec<DataFrame> = read_sql_table_chunks_with_options(
            &conn,
            "chunk_projection",
            &SqlReadOptions {
                columns: Some(vec!["name".to_owned(), "id".to_owned()]),
                ..Default::default()
            },
            2,
        )
        .unwrap()
        .collect::<Result<Vec<_>, _>>()
        .unwrap();

        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks[0].column_names(), vec!["name", "id"]);
        assert_eq!(chunks[1].column_names(), vec!["name", "id"]);
        assert_eq!(
            chunks[0].column("name").unwrap().values(),
            &[Scalar::Utf8("a".into()), Scalar::Utf8("b".into())]
        );
        assert_eq!(
            chunks[1].column("id").unwrap().values(),
            &[Scalar::Int64(3)]
        );
        assert!(chunks[0].column("hidden").is_none());
    }

    #[test]
    fn read_sql_table_chunks_with_options_schema_projects_before_chunking() {
        use std::cell::RefCell;

        struct MultiSchemaProjectedChunks {
            queries: RefCell<Vec<String>>,
        }

        impl super::SqlConnection for MultiSchemaProjectedChunks {
            fn query(&self, query: &str, _params: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                self.queries.borrow_mut().push(query.to_owned());
                Ok(SqlQueryResult {
                    columns: vec!["name".to_owned(), "id".to_owned()],
                    rows: vec![
                        vec![Scalar::Utf8("a".to_owned()), Scalar::Int64(1)],
                        vec![Scalar::Utf8("b".to_owned()), Scalar::Int64(2)],
                        vec![Scalar::Utf8("c".to_owned()), Scalar::Int64(3)],
                    ],
                })
            }

            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }

            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }

            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }

            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }

            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }

            fn supports_schemas(&self) -> bool {
                true
            }
        }

        let conn = MultiSchemaProjectedChunks {
            queries: RefCell::new(Vec::new()),
        };

        let chunks: Vec<DataFrame> = super::read_sql_table_chunks_with_options(
            &conn,
            "events",
            &SqlReadOptions {
                schema: Some("analytics".to_owned()),
                columns: Some(vec!["name".to_owned(), "id".to_owned()]),
                ..Default::default()
            },
            2,
        )
        .unwrap()
        .collect::<Result<Vec<_>, _>>()
        .unwrap();

        assert_eq!(
            conn.queries.borrow().as_slice(),
            &["SELECT \"name\", \"id\" FROM \"analytics\".\"events\"".to_owned()]
        );
        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks[0].column_names(), vec!["name", "id"]);
        assert_eq!(chunks[1].column_names(), vec!["name", "id"]);
        assert_eq!(
            chunks[0].index().labels(),
            &[IndexLabel::Int64(0), IndexLabel::Int64(1)]
        );
        assert_eq!(chunks[1].index().labels(), &[IndexLabel::Int64(0)]);
        assert_eq!(
            chunks[0].column("name").unwrap().values(),
            &[Scalar::Utf8("a".into()), Scalar::Utf8("b".into())]
        );
        assert_eq!(
            chunks[1].column("id").unwrap().values(),
            &[Scalar::Int64(3)]
        );
    }

    // ── SqlColumnSchema::comment (br-cfld / fd90.35) ─────────────────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_table_schema_comment_is_none_on_sqlite() {
        // SQLite has no column-comment storage; the rusqlite override
        // must always emit comment=None even when the table is real.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE labeled (id INTEGER, name TEXT);")
            .unwrap();
        let schema = sql_table_schema(&conn, "labeled", None).unwrap().unwrap();
        for col in &schema.columns {
            assert!(
                col.comment.is_none(),
                "SQLite should report no column comment; got {:?} on {}",
                col.comment,
                col.name
            );
        }
    }

    #[test]
    fn sql_table_schema_comment_routes_to_backend_override() {
        // PG-like backend stub returns explicit comment text per column.
        struct PgLikeWithComments;
        impl super::SqlConnection for PgLikeWithComments {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn table_schema(
                &self,
                table: &str,
                _schema: Option<&str>,
            ) -> Result<Option<SqlTableSchema>, IoError> {
                if table == "users" {
                    Ok(Some(SqlTableSchema {
                        table_name: "users".to_owned(),
                        columns: vec![
                            SqlColumnSchema {
                                name: "id".to_owned(),
                                declared_type: Some("BIGINT".to_owned()),
                                nullable: false,
                                default_value: None,
                                primary_key_ordinal: Some(0),
                                comment: Some("Surrogate primary key".to_owned()),
                                autoincrement: false,
                            },
                            SqlColumnSchema {
                                name: "email".to_owned(),
                                declared_type: Some("TEXT".to_owned()),
                                nullable: false,
                                default_value: None,
                                primary_key_ordinal: None,
                                comment: Some("Login identifier".to_owned()),
                                autoincrement: false,
                            },
                            SqlColumnSchema {
                                name: "name".to_owned(),
                                declared_type: Some("TEXT".to_owned()),
                                nullable: true,
                                default_value: None,
                                primary_key_ordinal: None,
                                comment: None,
                                autoincrement: false,
                            },
                        ],
                    }))
                } else {
                    Ok(None)
                }
            }
        }
        let conn = PgLikeWithComments;
        let schema = sql_table_schema(&conn, "users", None).unwrap().unwrap();
        let id = schema.column("id").unwrap();
        assert_eq!(id.comment.as_deref(), Some("Surrogate primary key"));
        let email = schema.column("email").unwrap();
        assert_eq!(email.comment.as_deref(), Some("Login identifier"));
        // Mixed: some columns may have no comment even on PG.
        let name = schema.column("name").unwrap();
        assert!(name.comment.is_none());
    }

    // ── SqlReadOptions::index_col (br-c1h9 / fd90.36) ─────────────────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_with_options_index_col_none_keeps_range_index() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE keyed (id INTEGER, val INTEGER);")
            .unwrap();
        super::SqlConnection::execute_batch(&conn, "INSERT INTO keyed VALUES (1, 10), (2, 20);")
            .unwrap();
        let frame = read_sql_with_options(
            &conn,
            "SELECT id, val FROM keyed ORDER BY id",
            &SqlReadOptions {
                index_col: None,
                ..Default::default()
            },
        )
        .unwrap();
        // Default RangeIndex: labels 0, 1.
        assert_eq!(frame.index().len(), 2);
        assert_eq!(frame.column_names(), vec!["id", "val"]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_with_options_index_col_promotes_named_column() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE keyed (id INTEGER, val INTEGER);")
            .unwrap();
        super::SqlConnection::execute_batch(&conn, "INSERT INTO keyed VALUES (10, 1), (20, 2);")
            .unwrap();
        let frame = read_sql_with_options(
            &conn,
            "SELECT id, val FROM keyed ORDER BY id",
            &SqlReadOptions {
                index_col: Some("id".to_owned()),
                ..Default::default()
            },
        )
        .unwrap();
        // 'id' removed from columns, used as index labels.
        assert_eq!(frame.column_names(), vec!["val"]);
        assert_eq!(frame.index().len(), 2);
        // Index labels should be the id values (10, 20).
        let labels: Vec<i64> = frame
            .index()
            .labels()
            .iter()
            .filter_map(|l| match l {
                IndexLabel::Int64(v) => Some(*v),
                _ => None,
            })
            .collect();
        assert_eq!(labels, vec![10, 20]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_with_options_index_col_missing_column_errors() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE t (a INTEGER);").unwrap();
        super::SqlConnection::execute_batch(&conn, "INSERT INTO t VALUES (1);").unwrap();
        let err = read_sql_with_options(
            &conn,
            "SELECT a FROM t",
            &SqlReadOptions {
                index_col: Some("nonexistent".to_owned()),
                ..Default::default()
            },
        )
        .expect_err("missing index_col must error");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("not present")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_with_options_index_col_empty_string_rejected() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE t (a INTEGER);").unwrap();
        let err = read_sql_with_options(
            &conn,
            "SELECT a FROM t",
            &SqlReadOptions {
                index_col: Some(String::new()),
                ..Default::default()
            },
        )
        .expect_err("empty index_col must be rejected");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("empty string")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_explicit_index_col_empty_string_rejected_across_entrypoints() {
        fn assert_empty_index_col(err: IoError) {
            assert!(
                matches!(err, IoError::Sql(ref msg) if msg.contains("empty string")),
                "expected empty index_col error, got {err:?}"
            );
        }

        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE explicit_idx (a INTEGER, b TEXT);
             INSERT INTO explicit_idx VALUES (1, 'x'), (2, 'y');",
        )
        .unwrap();

        assert_empty_index_col(
            read_sql_with_index_col(&conn, "SELECT a, b FROM explicit_idx", Some(""))
                .expect_err("empty explicit read_sql index_col must be rejected"),
        );
        assert_empty_index_col(
            read_sql_query_with_options_and_index_col(
                &conn,
                "SELECT a, b FROM explicit_idx",
                &SqlReadOptions::default(),
                Some(""),
            )
            .expect_err("empty explicit read_sql_query index_col must be rejected"),
        );
        assert_empty_index_col(
            read_sql_query_chunks_with_options_and_index_col(
                &conn,
                "SELECT a, b FROM explicit_idx",
                &SqlReadOptions::default(),
                Some(""),
                1,
            )
            .expect_err("empty explicit query chunk index_col must be rejected"),
        );
        assert_empty_index_col(
            read_sql_table_with_index_col(&conn, "explicit_idx", Some(""))
                .expect_err("empty explicit table index_col must be rejected"),
        );
        assert_empty_index_col(
            read_sql_table_with_options_and_index_col(
                &conn,
                "explicit_idx",
                &SqlReadOptions::default(),
                Some(""),
            )
            .expect_err("empty explicit table options index_col must be rejected"),
        );
        assert_empty_index_col(
            read_sql_table_columns_with_index_col(&conn, "explicit_idx", &["a"], Some(""))
                .expect_err("empty explicit table-columns index_col must be rejected"),
        );
        assert_empty_index_col(
            read_sql_table_columns_chunks_with_index_col(
                &conn,
                "explicit_idx",
                &["a"],
                Some(""),
                1,
            )
            .expect_err("empty explicit table-columns chunk index_col must be rejected"),
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_table_with_options_index_col_combines_with_columns_projection() {
        // columns + index_col: project ['id', 'val'], promote 'id' to
        // index, leaving only 'val' as a data column.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE wide (id INTEGER, val INTEGER, ts TEXT, note TEXT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "INSERT INTO wide VALUES (5, 100, 't1', 'first');",
        )
        .unwrap();
        let frame = read_sql_table_with_options(
            &conn,
            "wide",
            &SqlReadOptions {
                columns: Some(vec!["id".to_owned(), "val".to_owned()]),
                index_col: Some("id".to_owned()),
                ..Default::default()
            },
        )
        .unwrap();
        assert_eq!(frame.column_names(), vec!["val"]);
        let labels: Vec<i64> = frame
            .index()
            .labels()
            .iter()
            .filter_map(|l| match l {
                IndexLabel::Int64(v) => Some(*v),
                _ => None,
            })
            .collect();
        assert_eq!(labels, vec![5]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_table_with_options_columns_auto_project_index_col() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE projected_index (id INTEGER, val TEXT, hidden TEXT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "INSERT INTO projected_index VALUES (10, 'a', 'x'), (20, 'b', 'y');",
        )
        .unwrap();

        let frame = read_sql_table_with_options(
            &conn,
            "projected_index",
            &SqlReadOptions {
                columns: Some(vec!["val".to_owned()]),
                index_col: Some("id".to_owned()),
                ..Default::default()
            },
        )
        .unwrap();

        assert_eq!(frame.column_names(), vec!["val"]);
        assert!(frame.column("id").is_none());
        assert!(frame.column("hidden").is_none());
        assert_eq!(
            frame.index().labels(),
            &[IndexLabel::Int64(10), IndexLabel::Int64(20)]
        );
        assert_eq!(
            frame.column("val").unwrap().values(),
            &[Scalar::Utf8("a".into()), Scalar::Utf8("b".into())]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_table_chunks_with_options_columns_auto_project_index_col() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE projected_index_chunks (id INTEGER, val TEXT, hidden TEXT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "INSERT INTO projected_index_chunks VALUES \
                (10, 'a', 'x'), \
                (20, 'b', 'y'), \
                (30, 'c', 'z');",
        )
        .unwrap();

        let chunks: Vec<DataFrame> = read_sql_table_chunks_with_options_and_index_col(
            &conn,
            "projected_index_chunks",
            &SqlReadOptions {
                columns: Some(vec!["val".to_owned()]),
                ..Default::default()
            },
            Some("id"),
            2,
        )
        .unwrap()
        .collect::<Result<Vec<_>, _>>()
        .unwrap();

        assert_eq!(chunks.len(), 2);
        assert_eq!(chunks[0].column_names(), vec!["val"]);
        assert!(chunks[0].column("id").is_none());
        assert!(chunks[0].column("hidden").is_none());
        assert_eq!(
            chunks[0].index().labels(),
            &[IndexLabel::Int64(10), IndexLabel::Int64(20)]
        );
        assert_eq!(chunks[1].index().labels(), &[IndexLabel::Int64(30)]);
        assert_eq!(
            chunks[1].column("val").unwrap().values(),
            &[Scalar::Utf8("c".into())]
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_table_with_options_and_index_col_explicit_arg_wins_over_options() {
        // Both options.index_col=Some('a') and explicit index_col=Some('b').
        // The explicit arg must win — options.index_col is silently
        // overridden to avoid double-promotion.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE both (a INTEGER, b INTEGER, c TEXT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "INSERT INTO both VALUES (1, 100, 'x'), (2, 200, 'y');",
        )
        .unwrap();
        let frame = read_sql_table_with_options_and_index_col(
            &conn,
            "both",
            &SqlReadOptions {
                index_col: Some("a".to_owned()),
                ..Default::default()
            },
            Some("b"),
        )
        .unwrap();
        // 'b' is promoted to index, 'a' and 'c' remain as columns.
        assert_eq!(frame.column_names(), vec!["a", "c"]);
        let labels: Vec<i64> = frame
            .index()
            .labels()
            .iter()
            .filter_map(|l| match l {
                IndexLabel::Int64(v) => Some(*v),
                _ => None,
            })
            .collect();
        assert_eq!(labels, vec![100, 200]);
    }

    // ── SqlColumnSchema::autoincrement (br-bkl2 / fd90.37) ────────────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_table_schema_autoincrement_detected_on_integer_primary_key() {
        // SQLite rowid-alias rule: INTEGER PRIMARY KEY is an
        // auto-incrementing rowid alias.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE auto_a (id INTEGER PRIMARY KEY, name TEXT);",
        )
        .unwrap();
        let schema = sql_table_schema(&conn, "auto_a", None).unwrap().unwrap();
        let id = schema.column("id").unwrap();
        assert!(
            id.autoincrement,
            "INTEGER PRIMARY KEY must be autoincrement; got {id:?}"
        );
        let name = schema.column("name").unwrap();
        assert!(
            !name.autoincrement,
            "non-PK column must not be autoincrement"
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_table_schema_autoincrement_detected_with_explicit_keyword() {
        // The explicit AUTOINCREMENT keyword affects rowid reuse, not
        // the autoincrement property pandas surfaces.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE auto_b (id INTEGER PRIMARY KEY AUTOINCREMENT, val TEXT);",
        )
        .unwrap();
        let schema = sql_table_schema(&conn, "auto_b", None).unwrap().unwrap();
        let id = schema.column("id").unwrap();
        assert!(id.autoincrement);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_table_schema_autoincrement_not_set_for_text_primary_key() {
        // TEXT PRIMARY KEY is NOT a rowid alias; not auto-incrementing.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE text_pk (code TEXT PRIMARY KEY, name TEXT);",
        )
        .unwrap();
        let schema = sql_table_schema(&conn, "text_pk", None).unwrap().unwrap();
        let code = schema.column("code").unwrap();
        assert!(
            !code.autoincrement,
            "TEXT PRIMARY KEY is not autoincrement; got {code:?}"
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_table_schema_autoincrement_not_set_for_non_pk_integer() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE plain_int (val INTEGER, name TEXT);",
        )
        .unwrap();
        let schema = sql_table_schema(&conn, "plain_int", None).unwrap().unwrap();
        let val = schema.column("val").unwrap();
        assert!(!val.autoincrement, "non-PK INTEGER is not autoincrement");
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_table_schema_autoincrement_not_set_for_composite_pk_integer() {
        // Per fd90.42: SQLite's rowid-alias rule requires the column
        // to be the SOLE primary key. The tightened heuristic counts
        // PK columns first; composite PKs (multiple pk>0 rows) never
        // qualify even when the first column is INTEGER.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE composite_pk ( \
                year INTEGER NOT NULL, \
                month INTEGER NOT NULL, \
                code TEXT NOT NULL, \
                PRIMARY KEY (year, month, code) \
             );",
        )
        .unwrap();
        let schema = sql_table_schema(&conn, "composite_pk", None)
            .unwrap()
            .unwrap();
        let year = schema.column("year").unwrap();
        let month = schema.column("month").unwrap();
        let code = schema.column("code").unwrap();
        // Each part of the composite PK keeps its declaration-order
        // ordinal but NONE of them is autoincrement.
        assert_eq!(year.primary_key_ordinal, Some(0));
        assert_eq!(month.primary_key_ordinal, Some(1));
        assert_eq!(code.primary_key_ordinal, Some(2));
        assert!(
            !year.autoincrement,
            "composite PK first col must not be autoincrement"
        );
        assert!(!month.autoincrement);
        assert!(!code.autoincrement);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_table_schema_autoincrement_two_pass_count_distinguishes_single_vs_composite() {
        // Confirm the fix path: single-column INTEGER PRIMARY KEY -> true,
        // composite INTEGER+INTEGER PRIMARY KEY -> false on both.
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE single_int_pk (id INTEGER PRIMARY KEY, label TEXT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE composite_int_pk ( \
                a INTEGER NOT NULL, \
                b INTEGER NOT NULL, \
                PRIMARY KEY (a, b) \
             );",
        )
        .unwrap();

        let single = sql_table_schema(&conn, "single_int_pk", None)
            .unwrap()
            .unwrap();
        assert!(single.column("id").unwrap().autoincrement);

        let composite = sql_table_schema(&conn, "composite_int_pk", None)
            .unwrap()
            .unwrap();
        // Both columns have INTEGER type and pk>0 but neither qualifies.
        assert!(!composite.column("a").unwrap().autoincrement);
        assert!(!composite.column("b").unwrap().autoincrement);
    }

    #[test]
    fn sql_table_schema_autoincrement_routes_to_backend_override() {
        // PG-like backend stub returns explicit autoincrement true for
        // a SERIAL/IDENTITY column.
        struct PgLikeAutoinc;
        impl super::SqlConnection for PgLikeAutoinc {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn table_schema(
                &self,
                table: &str,
                _schema: Option<&str>,
            ) -> Result<Option<SqlTableSchema>, IoError> {
                if table == "users" {
                    Ok(Some(SqlTableSchema {
                        table_name: "users".to_owned(),
                        columns: vec![
                            SqlColumnSchema {
                                name: "id".to_owned(),
                                declared_type: Some("BIGSERIAL".to_owned()),
                                nullable: false,
                                default_value: None,
                                primary_key_ordinal: Some(0),
                                comment: None,
                                autoincrement: true,
                            },
                            SqlColumnSchema {
                                name: "email".to_owned(),
                                declared_type: Some("TEXT".to_owned()),
                                nullable: false,
                                default_value: None,
                                primary_key_ordinal: None,
                                comment: None,
                                autoincrement: false,
                            },
                        ],
                    }))
                } else {
                    Ok(None)
                }
            }
        }
        let conn = PgLikeAutoinc;
        let schema = sql_table_schema(&conn, "users", None).unwrap().unwrap();
        assert!(schema.column("id").unwrap().autoincrement);
        assert!(!schema.column("email").unwrap().autoincrement);
    }

    // ── SqlInspector facade (br-szs9 / fd90.38) ──────────────────────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_tables_views_schemas() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE t1 (x INTEGER);").unwrap();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE t2 (y TEXT);").unwrap();
        super::SqlConnection::execute_batch(&conn, "CREATE VIEW v1 AS SELECT x FROM t1;").unwrap();

        let inspector = SqlInspector::new(&conn);
        assert_eq!(inspector.tables(None).unwrap(), vec!["t1", "t2"]);
        assert_eq!(inspector.views(None).unwrap(), vec!["v1"]);
        // SQLite has no meaningful schemas → empty vec.
        assert!(inspector.schemas().unwrap().is_empty());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_columns_pk_indexes_fks() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE parent (pid INTEGER PRIMARY KEY);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE child ( \
                cid INTEGER PRIMARY KEY, \
                parent_id INTEGER, \
                tag TEXT, \
                FOREIGN KEY (parent_id) REFERENCES parent(pid) \
             );",
        )
        .unwrap();
        super::SqlConnection::execute_batch(&conn, "CREATE INDEX idx_child_tag ON child(tag);")
            .unwrap();

        let inspector = SqlInspector::new(&conn);

        // columns: 3 columns on 'child', cid + parent_id + tag.
        let schema = inspector.columns("child", None).unwrap().unwrap();
        let names: Vec<&str> = schema.columns.iter().map(|c| c.name.as_str()).collect();
        assert_eq!(names, vec!["cid", "parent_id", "tag"]);

        // primary_key_columns: cid is the sole PK.
        let pk = inspector.primary_key_columns("child", None).unwrap();
        assert_eq!(pk, vec!["cid"]);

        // indexes: only the explicit user index (PK auto-index filtered).
        let indexes = inspector.indexes("child", None).unwrap();
        assert_eq!(indexes.len(), 1);
        assert_eq!(indexes[0].name, "idx_child_tag");

        // foreign_keys: child references parent.
        let fks = inspector.foreign_keys("child", None).unwrap();
        assert_eq!(fks.len(), 1);
        assert_eq!(fks[0].columns, vec!["parent_id"]);
        assert_eq!(fks[0].referenced_table, "parent");
        assert_eq!(fks[0].referenced_columns, vec!["pid"]);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_unique_constraints_and_table_exists() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT UNIQUE);",
        )
        .unwrap();
        let inspector = SqlInspector::new(&conn);
        let uqs = inspector.unique_constraints("users", None).unwrap();
        assert_eq!(uqs.len(), 1);
        assert_eq!(uqs[0].columns, vec!["email"]);
        assert!(inspector.table_exists("users", None).unwrap());
        assert!(!inspector.table_exists("not_there", None).unwrap());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_server_version_and_dialect() {
        let conn = make_sql_test_conn();
        let inspector = SqlInspector::new(&conn);
        let version = inspector.server_version().unwrap().unwrap();
        assert!(version.starts_with("3."));
        assert_eq!(inspector.dialect_name(), "sqlite");
        // SQLite has no documented identifier-length cap.
        assert_eq!(inspector.max_identifier_length(), None);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_table_comment_returns_none_on_sqlite() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE t (x INTEGER);").unwrap();
        let inspector = SqlInspector::new(&conn);
        assert!(inspector.table_comment("t", None).unwrap().is_none());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_via_inspect_helper() {
        // The free-fn `inspect(&conn)` is the one-shot construction helper.
        // Per fd90.46: import lives inside the test so --no-default-features
        // builds don't see it as unused.
        use super::inspect;
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE one (x INTEGER);").unwrap();
        let inspector = inspect(&conn);
        assert_eq!(inspector.tables(None).unwrap(), vec!["one"]);
    }

    #[test]
    fn sql_inspector_routes_schema_arg_to_backend() {
        // Multi-schema backend: verifies SqlInspector forwards the schema
        // arg to every method that accepts one.
        struct PgLikeStub;
        impl super::SqlConnection for PgLikeStub {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn list_tables(&self, schema: Option<&str>) -> Result<Vec<String>, IoError> {
                Ok(match schema {
                    Some("analytics") => vec!["events".to_owned()],
                    _ => vec![],
                })
            }
            fn list_views(&self, schema: Option<&str>) -> Result<Vec<String>, IoError> {
                Ok(match schema {
                    Some("analytics") => vec!["daily".to_owned()],
                    _ => vec![],
                })
            }
            fn list_schemas(&self) -> Result<Vec<String>, IoError> {
                Ok(vec!["public".to_owned(), "analytics".to_owned()])
            }
            fn dialect_name(&self) -> &'static str {
                "postgresql"
            }
            fn max_identifier_length(&self) -> Option<usize> {
                Some(63)
            }
        }
        let conn = PgLikeStub;
        let inspector = SqlInspector::new(&conn);

        assert_eq!(inspector.tables(Some("analytics")).unwrap(), vec!["events"]);
        assert_eq!(inspector.views(Some("analytics")).unwrap(), vec!["daily"]);
        assert!(inspector.tables(Some("audit")).unwrap().is_empty());
        assert_eq!(inspector.schemas().unwrap(), vec!["public", "analytics"]);
        assert_eq!(inspector.dialect_name(), "postgresql");
        assert_eq!(inspector.max_identifier_length(), Some(63));
    }

    // ── SqlInspector::has_column / column (br-ppry / fd90.39) ─────────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_has_column_returns_true_for_present_column() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE has_col_tbl (id INTEGER, name TEXT);",
        )
        .unwrap();
        let inspector = SqlInspector::new(&conn);
        assert!(inspector.has_column("has_col_tbl", "id", None).unwrap());
        assert!(inspector.has_column("has_col_tbl", "name", None).unwrap());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_has_column_returns_false_for_missing_column() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE only_id (id INTEGER);").unwrap();
        let inspector = SqlInspector::new(&conn);
        // Table exists but no such column.
        assert!(!inspector.has_column("only_id", "name", None).unwrap());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_has_column_returns_false_for_missing_table() {
        let conn = make_sql_test_conn();
        let inspector = SqlInspector::new(&conn);
        // Table doesn't exist → has_column propagates Ok(false), not error.
        assert!(
            !inspector
                .has_column("no_such_tbl", "any_col", None)
                .unwrap()
        );
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_column_returns_full_metadata_for_present_column() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE detailed (id INTEGER PRIMARY KEY, status TEXT DEFAULT 'active');",
        )
        .unwrap();
        let inspector = SqlInspector::new(&conn);
        let id = inspector.column("detailed", "id", None).unwrap().unwrap();
        assert_eq!(id.name, "id");
        assert_eq!(id.declared_type.as_deref(), Some("INTEGER"));
        assert_eq!(id.primary_key_ordinal, Some(0));
        // INTEGER PRIMARY KEY → SQLite autoincrement (rowid alias).
        assert!(id.autoincrement);

        let status = inspector
            .column("detailed", "status", None)
            .unwrap()
            .unwrap();
        assert_eq!(status.declared_type.as_deref(), Some("TEXT"));
        assert!(status.nullable);
        assert_eq!(status.default_value.as_deref(), Some("'active'"));
        assert!(!status.autoincrement);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_column_returns_none_for_missing_column_or_table() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE only_x (x INTEGER);").unwrap();
        let inspector = SqlInspector::new(&conn);
        // Existing table, missing column → None.
        assert!(
            inspector
                .column("only_x", "missing", None)
                .unwrap()
                .is_none()
        );
        // Missing table → None.
        assert!(inspector.column("no_such", "any", None).unwrap().is_none());
    }

    #[test]
    fn sql_inspector_has_column_routes_schema_arg_to_backend() {
        struct PgLikeColumns;
        impl super::SqlConnection for PgLikeColumns {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn table_schema(
                &self,
                table: &str,
                schema: Option<&str>,
            ) -> Result<Option<SqlTableSchema>, IoError> {
                if table == "users" && schema == Some("public") {
                    Ok(Some(SqlTableSchema {
                        table_name: "users".to_owned(),
                        columns: vec![SqlColumnSchema {
                            name: "id".to_owned(),
                            declared_type: Some("BIGINT".to_owned()),
                            nullable: false,
                            default_value: None,
                            primary_key_ordinal: Some(0),
                            comment: None,
                            autoincrement: true,
                        }],
                    }))
                } else {
                    Ok(None)
                }
            }
        }
        let conn = PgLikeColumns;
        let inspector = SqlInspector::new(&conn);
        assert!(inspector.has_column("users", "id", Some("public")).unwrap());
        assert!(!inspector.has_column("users", "id", Some("audit")).unwrap());
        assert!(
            !inspector
                .has_column("users", "missing", Some("public"))
                .unwrap()
        );

        let id_col = inspector
            .column("users", "id", Some("public"))
            .unwrap()
            .unwrap();
        assert_eq!(id_col.declared_type.as_deref(), Some("BIGINT"));
        assert!(id_col.autoincrement);
        assert!(
            inspector
                .column("users", "id", Some("audit"))
                .unwrap()
                .is_none()
        );
    }

    // ── SqlInspector::reflect_table (br-76mw / fd90.40) ──────────────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_reflect_table_unknown_returns_none() {
        let conn = make_sql_test_conn();
        let inspector = SqlInspector::new(&conn);
        let result = inspector.reflect_table("no_such", None).unwrap();
        assert!(result.is_none());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_reflect_table_bundles_all_metadata() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE parent (pid INTEGER PRIMARY KEY, code TEXT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE bundled ( \
                id INTEGER PRIMARY KEY, \
                parent_id INTEGER, \
                slug TEXT, \
                email TEXT UNIQUE, \
                FOREIGN KEY (parent_id) REFERENCES parent(pid) \
             );",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE INDEX idx_bundled_slug ON bundled(slug);",
        )
        .unwrap();

        let inspector = SqlInspector::new(&conn);
        let bundle = inspector
            .reflect_table("bundled", None)
            .unwrap()
            .expect("table exists");

        assert_eq!(bundle.table_name, "bundled");

        // Columns: id, parent_id, slug, email.
        let names: Vec<&str> = bundle.columns.iter().map(|c| c.name.as_str()).collect();
        assert_eq!(names, vec!["id", "parent_id", "slug", "email"]);
        // INTEGER PRIMARY KEY id is autoincrement.
        let id_col = bundle
            .columns
            .iter()
            .find(|c| c.name == "id")
            .expect("id col");
        assert!(id_col.autoincrement);

        // Primary key.
        assert_eq!(bundle.primary_key_columns, vec!["id"]);

        // Indexes (only the user CREATE INDEX; the UNIQUE constraint
        // index goes via unique_constraints, the PK auto-index is
        // hidden).
        assert_eq!(bundle.indexes.len(), 1);
        assert_eq!(bundle.indexes[0].name, "idx_bundled_slug");

        // Unique constraints (the inline UNIQUE on email).
        assert_eq!(bundle.unique_constraints.len(), 1);
        assert_eq!(bundle.unique_constraints[0].columns, vec!["email"]);

        // Foreign keys (parent_id -> parent.pid).
        assert_eq!(bundle.foreign_keys.len(), 1);
        assert_eq!(bundle.foreign_keys[0].columns, vec!["parent_id"]);
        assert_eq!(bundle.foreign_keys[0].referenced_table, "parent");

        // SQLite has no native column/table comment; comment is None.
        assert!(bundle.comment.is_none());
    }

    #[test]
    fn sql_inspector_reflect_table_routes_to_backend_override() {
        // Multi-schema PG-like backend that returns explicit comment +
        // populated metadata. Verifies all five sub-calls flow through
        // and end up in the bundled struct.
        struct PgLikeBundle;
        impl super::SqlConnection for PgLikeBundle {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn table_schema(
                &self,
                table: &str,
                schema: Option<&str>,
            ) -> Result<Option<SqlTableSchema>, IoError> {
                if table == "users" && schema == Some("public") {
                    Ok(Some(SqlTableSchema {
                        table_name: "users".to_owned(),
                        columns: vec![SqlColumnSchema {
                            name: "id".to_owned(),
                            declared_type: Some("BIGINT".to_owned()),
                            nullable: false,
                            default_value: None,
                            primary_key_ordinal: Some(0),
                            comment: None,
                            autoincrement: true,
                        }],
                    }))
                } else {
                    Ok(None)
                }
            }
            fn primary_key_columns(
                &self,
                table: &str,
                schema: Option<&str>,
            ) -> Result<Vec<String>, IoError> {
                if table == "users" && schema == Some("public") {
                    Ok(vec!["id".to_owned()])
                } else {
                    Ok(vec![])
                }
            }
            fn list_indexes(
                &self,
                _table: &str,
                _schema: Option<&str>,
            ) -> Result<Vec<SqlIndexSchema>, IoError> {
                Ok(vec![SqlIndexSchema {
                    name: "users_status_idx".to_owned(),
                    columns: vec!["status".to_owned()],
                    unique: false,
                }])
            }
            fn list_foreign_keys(
                &self,
                _table: &str,
                _schema: Option<&str>,
            ) -> Result<Vec<SqlForeignKeySchema>, IoError> {
                Ok(vec![])
            }
            fn list_unique_constraints(
                &self,
                _table: &str,
                _schema: Option<&str>,
            ) -> Result<Vec<SqlUniqueConstraintSchema>, IoError> {
                Ok(vec![SqlUniqueConstraintSchema {
                    name: "users_email_key".to_owned(),
                    columns: vec!["email".to_owned()],
                }])
            }
            fn table_comment(
                &self,
                _table: &str,
                _schema: Option<&str>,
            ) -> Result<Option<String>, IoError> {
                Ok(Some("Customer accounts".to_owned()))
            }
        }
        let conn = PgLikeBundle;
        let inspector = SqlInspector::new(&conn);
        let bundle = inspector
            .reflect_table("users", Some("public"))
            .unwrap()
            .expect("present");
        assert_eq!(bundle.table_name, "users");
        assert_eq!(bundle.columns.len(), 1);
        assert_eq!(bundle.primary_key_columns, vec!["id"]);
        assert_eq!(bundle.indexes.len(), 1);
        assert_eq!(bundle.indexes[0].name, "users_status_idx");
        assert_eq!(bundle.unique_constraints.len(), 1);
        assert_eq!(bundle.foreign_keys.len(), 0);
        assert_eq!(bundle.comment.as_deref(), Some("Customer accounts"));

        // Wrong schema -> None (table_schema returns None).
        assert!(
            inspector
                .reflect_table("users", Some("audit"))
                .unwrap()
                .is_none()
        );
    }

    // Use SqlReflectedTable in a smoke test so the struct's named
    // fields are exercised at the use-site too.
    #[test]
    fn sql_reflected_table_bundle_smoke_test() {
        let bundle = SqlReflectedTable {
            table_name: "t".to_owned(),
            columns: vec![],
            primary_key_columns: vec![],
            indexes: vec![],
            foreign_keys: vec![],
            unique_constraints: vec![],
            comment: None,
        };
        assert_eq!(bundle.table_name, "t");
        assert!(bundle.columns.is_empty());
    }

    // ── SqlReflectedTable accessor methods (br-63ac / fd90.51) ────────────

    #[test]
    fn sql_reflected_table_accessors_find_named_entries() {
        let bundle = SqlReflectedTable {
            table_name: "orders".to_owned(),
            columns: vec![
                SqlColumnSchema {
                    name: "id".to_owned(),
                    declared_type: Some("INTEGER".to_owned()),
                    nullable: false,
                    default_value: None,
                    primary_key_ordinal: Some(0),
                    comment: None,
                    autoincrement: true,
                },
                SqlColumnSchema {
                    name: "user_id".to_owned(),
                    declared_type: Some("INTEGER".to_owned()),
                    nullable: false,
                    default_value: None,
                    primary_key_ordinal: None,
                    comment: None,
                    autoincrement: false,
                },
            ],
            primary_key_columns: vec!["id".to_owned()],
            indexes: vec![SqlIndexSchema {
                name: "idx_orders_user".to_owned(),
                columns: vec!["user_id".to_owned()],
                unique: false,
            }],
            foreign_keys: vec![SqlForeignKeySchema {
                constraint_name: None,
                columns: vec!["user_id".to_owned()],
                referenced_table: "users".to_owned(),
                referenced_columns: vec!["id".to_owned()],
            }],
            unique_constraints: vec![SqlUniqueConstraintSchema {
                name: "uq_orders_id".to_owned(),
                columns: vec!["id".to_owned()],
            }],
            comment: Some("Customer orders".to_owned()),
        };

        // column(name): present + missing.
        let id = bundle.column("id").expect("id column");
        assert_eq!(id.declared_type.as_deref(), Some("INTEGER"));
        assert!(id.autoincrement);
        assert!(bundle.column("missing").is_none());

        // index(name): present + missing.
        let idx = bundle.index("idx_orders_user").expect("idx");
        assert_eq!(idx.columns, vec!["user_id"]);
        assert!(bundle.index("idx_does_not_exist").is_none());

        // unique_constraint(name).
        let uq = bundle.unique_constraint("uq_orders_id").expect("uq");
        assert_eq!(uq.columns, vec!["id"]);
        assert!(bundle.unique_constraint("uq_missing").is_none());

        // foreign_keys_for_column(col): matches the FK touching user_id.
        let fks = bundle.foreign_keys_for_column("user_id");
        assert_eq!(fks.len(), 1);
        assert_eq!(fks[0].referenced_table, "users");
        // Column not part of any FK -> empty.
        assert!(bundle.foreign_keys_for_column("id").is_empty());
        assert!(bundle.foreign_keys_for_column("nonexistent").is_empty());
    }

    #[test]
    fn sql_reflected_table_foreign_keys_for_column_handles_composite_fks() {
        let bundle = SqlReflectedTable {
            table_name: "rolling_fact".to_owned(),
            columns: vec![],
            primary_key_columns: vec![],
            indexes: vec![],
            foreign_keys: vec![SqlForeignKeySchema {
                constraint_name: None,
                columns: vec!["fyear".to_owned(), "fmonth".to_owned()],
                referenced_table: "rolling".to_owned(),
                referenced_columns: vec!["year".to_owned(), "month".to_owned()],
            }],
            unique_constraints: vec![],
            comment: None,
        };
        // Composite FK touches both fyear and fmonth — both should
        // surface the same FK.
        assert_eq!(bundle.foreign_keys_for_column("fyear").len(), 1);
        assert_eq!(bundle.foreign_keys_for_column("fmonth").len(), 1);
        assert!(bundle.foreign_keys_for_column("year").is_empty()); // referenced col, not from col
    }

    #[test]
    fn sql_reflected_table_foreign_keys_for_column_returns_multiple_when_relevant() {
        // Rare but valid: one column participates in two FKs (e.g.
        // same column referenced by separate FKs to two parents).
        let bundle = SqlReflectedTable {
            table_name: "audit".to_owned(),
            columns: vec![],
            primary_key_columns: vec![],
            indexes: vec![],
            foreign_keys: vec![
                SqlForeignKeySchema {
                    constraint_name: Some("fk_audit_a".to_owned()),
                    columns: vec!["entity_id".to_owned()],
                    referenced_table: "users".to_owned(),
                    referenced_columns: vec!["id".to_owned()],
                },
                SqlForeignKeySchema {
                    constraint_name: Some("fk_audit_b".to_owned()),
                    columns: vec!["entity_id".to_owned()],
                    referenced_table: "products".to_owned(),
                    referenced_columns: vec!["id".to_owned()],
                },
            ],
            unique_constraints: vec![],
            comment: None,
        };
        let fks = bundle.foreign_keys_for_column("entity_id");
        assert_eq!(fks.len(), 2);
        // Order preserved.
        assert_eq!(fks[0].constraint_name.as_deref(), Some("fk_audit_a"));
        assert_eq!(fks[1].constraint_name.as_deref(), Some("fk_audit_b"));
    }

    // ── indexes_for_column / unique_constraints_for_column (br-37uy / fd90.52) ─

    #[test]
    fn sql_reflected_table_indexes_for_column_matches_any_position() {
        let bundle = SqlReflectedTable {
            table_name: "rolling".to_owned(),
            columns: vec![],
            primary_key_columns: vec![],
            indexes: vec![
                SqlIndexSchema {
                    name: "idx_rolling_year".to_owned(),
                    columns: vec!["year".to_owned()],
                    unique: false,
                },
                SqlIndexSchema {
                    name: "idx_rolling_y_m_c".to_owned(),
                    columns: vec!["year".to_owned(), "month".to_owned(), "code".to_owned()],
                    unique: false,
                },
            ],
            foreign_keys: vec![],
            unique_constraints: vec![],
            comment: None,
        };

        // 'year' appears in both indexes (first in idx_year, first in
        // composite). Returns both.
        let year_idxs = bundle.indexes_for_column("year");
        assert_eq!(year_idxs.len(), 2);

        // 'month' only appears in the composite index, in middle position.
        let month_idxs = bundle.indexes_for_column("month");
        assert_eq!(month_idxs.len(), 1);
        assert_eq!(month_idxs[0].name, "idx_rolling_y_m_c");

        // 'code' appears only in the composite, last position.
        let code_idxs = bundle.indexes_for_column("code");
        assert_eq!(code_idxs.len(), 1);

        // Column not in any index.
        assert!(bundle.indexes_for_column("nonexistent").is_empty());
    }

    #[test]
    fn sql_reflected_table_unique_constraints_for_column_matches_any_position() {
        let bundle = SqlReflectedTable {
            table_name: "events".to_owned(),
            columns: vec![],
            primary_key_columns: vec![],
            indexes: vec![],
            foreign_keys: vec![],
            unique_constraints: vec![
                SqlUniqueConstraintSchema {
                    name: "uq_events_email".to_owned(),
                    columns: vec!["email".to_owned()],
                },
                SqlUniqueConstraintSchema {
                    name: "uq_events_user_event_ts".to_owned(),
                    columns: vec!["user_id".to_owned(), "event_id".to_owned(), "ts".to_owned()],
                },
            ],
            comment: None,
        };

        let email_uqs = bundle.unique_constraints_for_column("email");
        assert_eq!(email_uqs.len(), 1);
        assert_eq!(email_uqs[0].name, "uq_events_email");

        // 'event_id' middle position in composite.
        let event_uqs = bundle.unique_constraints_for_column("event_id");
        assert_eq!(event_uqs.len(), 1);
        assert_eq!(event_uqs[0].columns, vec!["user_id", "event_id", "ts"]);

        // 'ts' last position in composite.
        let ts_uqs = bundle.unique_constraints_for_column("ts");
        assert_eq!(ts_uqs.len(), 1);

        assert!(
            bundle
                .unique_constraints_for_column("nonexistent")
                .is_empty()
        );
    }

    #[test]
    fn sql_reflected_table_for_column_accessors_return_multiple() {
        // A column can appear in multiple indexes / unique constraints.
        let bundle = SqlReflectedTable {
            table_name: "wide".to_owned(),
            columns: vec![],
            primary_key_columns: vec![],
            indexes: vec![
                SqlIndexSchema {
                    name: "idx_a".to_owned(),
                    columns: vec!["x".to_owned()],
                    unique: false,
                },
                SqlIndexSchema {
                    name: "idx_b".to_owned(),
                    columns: vec!["x".to_owned(), "y".to_owned()],
                    unique: true,
                },
            ],
            foreign_keys: vec![],
            unique_constraints: vec![
                SqlUniqueConstraintSchema {
                    name: "uq_a".to_owned(),
                    columns: vec!["x".to_owned()],
                },
                SqlUniqueConstraintSchema {
                    name: "uq_b".to_owned(),
                    columns: vec!["x".to_owned(), "z".to_owned()],
                },
            ],
            comment: None,
        };

        let idx_for_x = bundle.indexes_for_column("x");
        assert_eq!(idx_for_x.len(), 2);
        assert_eq!(idx_for_x[0].name, "idx_a");
        assert_eq!(idx_for_x[1].name, "idx_b");

        let uq_for_x = bundle.unique_constraints_for_column("x");
        assert_eq!(uq_for_x.len(), 2);
        assert_eq!(uq_for_x[0].name, "uq_a");
        assert_eq!(uq_for_x[1].name, "uq_b");
    }

    // ── SqlInspector::reflect_all_tables (br-jmmo / fd90.53) ─────────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_reflect_all_tables_empty_db() {
        let conn = make_sql_test_conn();
        let inspector = SqlInspector::new(&conn);
        let bundles = inspector.reflect_all_tables(None).unwrap();
        assert!(bundles.is_empty());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_reflect_all_tables_returns_one_bundle_per_table() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE alpha (id INTEGER PRIMARY KEY, name TEXT);",
        )
        .unwrap();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE beta (uid INTEGER, label TEXT);")
            .unwrap();
        let inspector = SqlInspector::new(&conn);
        let bundles = inspector.reflect_all_tables(None).unwrap();
        assert_eq!(bundles.len(), 2);
        // Ordered alphabetically by list_tables.
        assert_eq!(bundles[0].table_name, "alpha");
        assert_eq!(bundles[1].table_name, "beta");
        // Each bundle has full metadata.
        assert_eq!(
            bundles[0]
                .columns
                .iter()
                .map(|c| c.name.as_str())
                .collect::<Vec<_>>(),
            vec!["id", "name"]
        );
        assert_eq!(bundles[0].primary_key_columns, vec!["id"]);
        assert_eq!(bundles[1].columns.len(), 2);
        assert!(bundles[1].primary_key_columns.is_empty());
    }

    #[test]
    fn sql_inspector_reflect_all_tables_skips_disappearing_tables() {
        // Race-condition stub: list_tables returns ["a", "b"] but
        // table_schema returns None for "b" (simulating a concurrent
        // DROP between list and reflect). reflect_all_tables must
        // skip "b" without erroring.
        struct DisappearingTable;
        impl super::SqlConnection for DisappearingTable {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn list_tables(&self, _schema: Option<&str>) -> Result<Vec<String>, IoError> {
                Ok(vec!["a".to_owned(), "b".to_owned()])
            }
            fn table_schema(
                &self,
                table: &str,
                _schema: Option<&str>,
            ) -> Result<Option<SqlTableSchema>, IoError> {
                if table == "a" {
                    Ok(Some(SqlTableSchema {
                        table_name: "a".to_owned(),
                        columns: vec![SqlColumnSchema {
                            name: "x".to_owned(),
                            declared_type: Some("INTEGER".to_owned()),
                            nullable: true,
                            default_value: None,
                            primary_key_ordinal: None,
                            comment: None,
                            autoincrement: false,
                        }],
                    }))
                } else {
                    // b "disappeared" between list and reflect.
                    Ok(None)
                }
            }
        }
        let conn = DisappearingTable;
        let inspector = SqlInspector::new(&conn);
        let bundles = inspector.reflect_all_tables(None).unwrap();
        assert_eq!(bundles.len(), 1);
        assert_eq!(bundles[0].table_name, "a");
    }

    #[test]
    fn sql_inspector_reflect_all_tables_routes_schema_arg() {
        // Multi-schema stub: list_tables returns different sets per
        // schema; reflect_all_tables must propagate the schema arg.
        struct MultiSchemaReflect;
        impl super::SqlConnection for MultiSchemaReflect {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn list_tables(&self, schema: Option<&str>) -> Result<Vec<String>, IoError> {
                Ok(match schema {
                    Some("analytics") => vec!["events".to_owned()],
                    _ => vec![],
                })
            }
            fn table_schema(
                &self,
                table: &str,
                schema: Option<&str>,
            ) -> Result<Option<SqlTableSchema>, IoError> {
                if table == "events" && schema == Some("analytics") {
                    Ok(Some(SqlTableSchema {
                        table_name: "events".to_owned(),
                        columns: vec![SqlColumnSchema {
                            name: "ts".to_owned(),
                            declared_type: Some("TIMESTAMPTZ".to_owned()),
                            nullable: false,
                            default_value: None,
                            primary_key_ordinal: None,
                            comment: None,
                            autoincrement: false,
                        }],
                    }))
                } else {
                    Ok(None)
                }
            }
        }
        let conn = MultiSchemaReflect;
        let inspector = SqlInspector::new(&conn);
        let bundles = inspector.reflect_all_tables(Some("analytics")).unwrap();
        assert_eq!(bundles.len(), 1);
        assert_eq!(bundles[0].table_name, "events");
        assert_eq!(
            bundles[0].columns[0].declared_type.as_deref(),
            Some("TIMESTAMPTZ")
        );
        // Wrong schema -> empty.
        assert!(
            inspector
                .reflect_all_tables(Some("audit"))
                .unwrap()
                .is_empty()
        );
    }

    // ── SqlInspector::reflect_all_views (br-zuqt / fd90.54) ──────────────

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_reflect_all_views_empty_db() {
        let conn = make_sql_test_conn();
        let inspector = SqlInspector::new(&conn);
        let bundles = inspector.reflect_all_views(None).unwrap();
        assert!(bundles.is_empty());
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn sql_inspector_reflect_all_views_returns_one_bundle_per_view() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(&conn, "CREATE TABLE base (id INTEGER, label TEXT);")
            .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE VIEW alpha_view AS SELECT id FROM base;",
        )
        .unwrap();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE VIEW zebra_view AS SELECT label FROM base;",
        )
        .unwrap();
        let inspector = SqlInspector::new(&conn);
        let bundles = inspector.reflect_all_views(None).unwrap();
        // Tables ARE NOT included — only views.
        assert_eq!(bundles.len(), 2);
        assert_eq!(bundles[0].table_name, "alpha_view");
        assert_eq!(bundles[1].table_name, "zebra_view");
        // Each view's columns are surfaced via PRAGMA table_info.
        assert_eq!(
            bundles[0]
                .columns
                .iter()
                .map(|c| c.name.as_str())
                .collect::<Vec<_>>(),
            vec!["id"]
        );
        assert_eq!(
            bundles[1]
                .columns
                .iter()
                .map(|c| c.name.as_str())
                .collect::<Vec<_>>(),
            vec!["label"]
        );
        // Views don't carry constraints — PK/FK/UC/index lists are empty.
        for bundle in &bundles {
            assert!(bundle.primary_key_columns.is_empty());
            assert!(bundle.indexes.is_empty());
            assert!(bundle.foreign_keys.is_empty());
            assert!(bundle.unique_constraints.is_empty());
        }
    }

    #[test]
    fn sql_inspector_reflect_all_views_routes_schema_arg() {
        // Multi-schema stub: list_views returns different sets per schema.
        struct MultiSchemaViewReflect;
        impl super::SqlConnection for MultiSchemaViewReflect {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn list_views(&self, schema: Option<&str>) -> Result<Vec<String>, IoError> {
                Ok(match schema {
                    Some("reporting") => vec!["weekly_summary".to_owned()],
                    _ => vec![],
                })
            }
            fn table_schema(
                &self,
                table: &str,
                schema: Option<&str>,
            ) -> Result<Option<SqlTableSchema>, IoError> {
                if table == "weekly_summary" && schema == Some("reporting") {
                    Ok(Some(SqlTableSchema {
                        table_name: "weekly_summary".to_owned(),
                        columns: vec![SqlColumnSchema {
                            name: "week".to_owned(),
                            declared_type: Some("DATE".to_owned()),
                            nullable: true,
                            default_value: None,
                            primary_key_ordinal: None,
                            comment: None,
                            autoincrement: false,
                        }],
                    }))
                } else {
                    Ok(None)
                }
            }
        }
        let conn = MultiSchemaViewReflect;
        let inspector = SqlInspector::new(&conn);
        let bundles = inspector.reflect_all_views(Some("reporting")).unwrap();
        assert_eq!(bundles.len(), 1);
        assert_eq!(bundles[0].table_name, "weekly_summary");
        assert_eq!(bundles[0].columns[0].declared_type.as_deref(), Some("DATE"));
        // Wrong schema -> empty.
        assert!(
            inspector
                .reflect_all_views(Some("audit"))
                .unwrap()
                .is_empty()
        );
    }

    #[test]
    fn sql_inspector_reflect_table_calls_table_schema_only_once() {
        // Per fd90.43: reflect_table must derive primary_key_columns
        // from the fetched SqlTableSchema rather than dispatching
        // primary_key_columns() (which itself calls table_schema). A
        // recording stub counts table_schema invocations and asserts
        // exactly one round-trip.
        use std::cell::Cell;
        struct CountingTableSchema {
            table_schema_calls: Cell<usize>,
        }
        impl super::SqlConnection for CountingTableSchema {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<SqlQueryResult, IoError> {
                Ok(SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
                Ok(())
            }
            fn table_exists(&self, _name: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _sql: &str, _rows: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _dtype: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _index: &Index) -> &'static str {
                "TEXT"
            }
            fn table_schema(
                &self,
                _table: &str,
                _schema: Option<&str>,
            ) -> Result<Option<SqlTableSchema>, IoError> {
                self.table_schema_calls
                    .set(self.table_schema_calls.get() + 1);
                Ok(Some(SqlTableSchema {
                    table_name: "x".to_owned(),
                    columns: vec![SqlColumnSchema {
                        name: "id".to_owned(),
                        declared_type: Some("BIGINT".to_owned()),
                        nullable: false,
                        default_value: None,
                        primary_key_ordinal: Some(0),
                        comment: None,
                        autoincrement: true,
                    }],
                }))
            }
        }
        let conn = CountingTableSchema {
            table_schema_calls: Cell::new(0),
        };
        let inspector = SqlInspector::new(&conn);
        let bundle = inspector.reflect_table("x", None).unwrap().unwrap();
        // Exactly one table_schema fetch — primary_key_columns derived
        // from the fetched meta, NOT a second round-trip.
        assert_eq!(conn.table_schema_calls.get(), 1);
        assert_eq!(bundle.primary_key_columns, vec!["id"]);
    }

    // ── SqlReadOptions default coerce_float (br-o0x6 / fd90.41) ──────────

    #[test]
    fn sql_read_options_default_coerce_float_matches_pandas() {
        // Pandas defaults coerce_float=True for read_sql / read_sql_query
        // / read_sql_table. We must match — any bare ::default() call
        // should opt INTO coerce_float, not opt out.
        let opts = SqlReadOptions::default();
        assert!(
            opts.coerce_float,
            "default coerce_float must be true (pandas parity)"
        );
        // Sanity: other defaults are the natural empty / None values.
        assert!(opts.params.is_none());
        assert!(opts.parse_dates.is_none());
        assert!(opts.dtype.is_none());
        assert!(opts.schema.is_none());
        assert!(opts.columns.is_none());
        assert!(opts.index_col.is_none());
    }

    // ── SQL identifier quoting regression matrix (br-frankenpandas-fd90.12) ─
    //
    // Cross-product of (ANSI / MySQL backtick / MSSQL bracket) quoting
    // backends × (SELECT * / SELECT cols / CREATE TABLE / INSERT /
    // multi-row INSERT / DROP / TRUNCATE) × identifier shapes that the
    // shared validator currently allows: reserved-word names, mixed case,
    // leading digits, embedded quote chars (where the backend defines an
    // escape rule). All tests are pure query-builder assertions — no live
    // backend touched.

    #[derive(Default)]
    struct AnsiSchemaConn;
    impl super::SqlConnection for AnsiSchemaConn {
        fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
            Ok(super::SqlQueryResult {
                columns: vec![],
                rows: vec![],
            })
        }
        fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
            Ok(())
        }
        fn table_exists(&self, _n: &str) -> Result<bool, IoError> {
            Ok(false)
        }
        fn insert_rows(&self, _s: &str, _r: &[Vec<Scalar>]) -> Result<(), IoError> {
            Ok(())
        }
        fn dtype_sql(&self, _d: DType) -> &'static str {
            "TEXT"
        }
        fn index_dtype_sql(&self, _i: &Index) -> &'static str {
            "TEXT"
        }
        fn supports_schemas(&self) -> bool {
            true
        }
        fn parameter_marker(&self, ordinal: usize) -> String {
            format!("${ordinal}")
        }
        fn max_identifier_length(&self) -> Option<usize> {
            Some(63)
        }
    }

    #[derive(Default)]
    struct MysqlBacktickConn;
    impl super::SqlConnection for MysqlBacktickConn {
        fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
            Ok(super::SqlQueryResult {
                columns: vec![],
                rows: vec![],
            })
        }
        fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
            Ok(())
        }
        fn table_exists(&self, _n: &str) -> Result<bool, IoError> {
            Ok(false)
        }
        fn insert_rows(&self, _s: &str, _r: &[Vec<Scalar>]) -> Result<(), IoError> {
            Ok(())
        }
        fn dtype_sql(&self, _d: DType) -> &'static str {
            "TEXT"
        }
        fn index_dtype_sql(&self, _i: &Index) -> &'static str {
            "TEXT"
        }
        fn supports_schemas(&self) -> bool {
            true
        }
        fn parameter_marker(&self, _ordinal: usize) -> String {
            "?".to_owned()
        }
        fn max_identifier_length(&self) -> Option<usize> {
            Some(64)
        }
        fn quote_identifier(&self, ident: &str) -> Result<String, IoError> {
            if ident.contains('\0') {
                return Err(IoError::Sql("invalid SQL identifier: NUL byte".to_owned()));
            }
            Ok(format!("`{}`", ident.replace('`', "``")))
        }
    }

    #[derive(Default)]
    struct MssqlBracketConn;
    impl super::SqlConnection for MssqlBracketConn {
        fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
            Ok(super::SqlQueryResult {
                columns: vec![],
                rows: vec![],
            })
        }
        fn execute_batch(&self, _sql: &str) -> Result<(), IoError> {
            Ok(())
        }
        fn table_exists(&self, _n: &str) -> Result<bool, IoError> {
            Ok(false)
        }
        fn insert_rows(&self, _s: &str, _r: &[Vec<Scalar>]) -> Result<(), IoError> {
            Ok(())
        }
        fn dtype_sql(&self, _d: DType) -> &'static str {
            "NVARCHAR(MAX)"
        }
        fn index_dtype_sql(&self, _i: &Index) -> &'static str {
            "NVARCHAR(MAX)"
        }
        fn supports_schemas(&self) -> bool {
            true
        }
        fn parameter_marker(&self, ordinal: usize) -> String {
            format!("@p{ordinal}")
        }
        fn max_identifier_length(&self) -> Option<usize> {
            Some(128)
        }
        fn quote_identifier(&self, ident: &str) -> Result<String, IoError> {
            if ident.contains('\0') {
                return Err(IoError::Sql("invalid SQL identifier: NUL byte".to_owned()));
            }
            // T-SQL bracket quoting: doubled `]` escapes a literal `]`.
            Ok(format!("[{}]", ident.replace(']', "]]")))
        }
    }

    /// Reserved SQL keywords that the shape validator allows as
    /// alphanumeric identifiers — they must round-trip through every
    /// query builder safely (i.e. quoted, never bare).
    const FD90_12_RESERVED_WORDS: &[&str] = &[
        "select", "from", "where", "order", "group", "table", "index", "join",
    ];

    #[test]
    fn fd90_12_quoting_matrix_select_all_reserved_words_quoted_per_dialect() {
        let ansi = AnsiSchemaConn;
        let mysql = MysqlBacktickConn;
        let mssql = MssqlBracketConn;
        for word in FD90_12_RESERVED_WORDS {
            assert_eq!(
                super::sql_select_all_query(&ansi, word).expect("ansi select"),
                format!("SELECT * FROM \"{word}\""),
                "ansi reserved word `{word}`"
            );
            assert_eq!(
                super::sql_select_all_query(&mysql, word).expect("mysql select"),
                format!("SELECT * FROM `{word}`"),
                "mysql reserved word `{word}`"
            );
            assert_eq!(
                super::sql_select_all_query(&mssql, word).expect("mssql select"),
                format!("SELECT * FROM [{word}]"),
                "mssql reserved word `{word}`"
            );
        }
    }

    #[test]
    fn fd90_12_quoting_matrix_select_columns_mixed_case_preserved_per_dialect() {
        let ansi = AnsiSchemaConn;
        let mysql = MysqlBacktickConn;
        let mssql = MssqlBracketConn;
        let cases: &[&str] = &["MyCol", "MIXEDcase", "camelCase", "SCREAMING_SNAKE"];
        for col in cases {
            assert_eq!(
                super::sql_select_columns_query(&ansi, "users", &[col]).expect("ansi cols"),
                format!("SELECT \"{col}\" FROM \"users\""),
                "ansi mixed-case col `{col}`"
            );
            assert_eq!(
                super::sql_select_columns_query(&mysql, "users", &[col]).expect("mysql cols"),
                format!("SELECT `{col}` FROM `users`"),
                "mysql mixed-case col `{col}`"
            );
            assert_eq!(
                super::sql_select_columns_query(&mssql, "users", &[col]).expect("mssql cols"),
                format!("SELECT [{col}] FROM [users]"),
                "mssql mixed-case col `{col}`"
            );
        }
    }

    #[test]
    fn fd90_12_quoting_matrix_leading_digit_identifiers_quoted_per_dialect() {
        let ansi = AnsiSchemaConn;
        let mysql = MysqlBacktickConn;
        let mssql = MssqlBracketConn;
        let cases: &[&str] = &["1col", "2nd_place", "9lives", "123"];
        for col in cases {
            assert_eq!(
                super::sql_select_columns_query(&ansi, "tbl", &[col]).expect("ansi"),
                format!("SELECT \"{col}\" FROM \"tbl\"")
            );
            assert_eq!(
                super::sql_select_columns_query(&mysql, "tbl", &[col]).expect("mysql"),
                format!("SELECT `{col}` FROM `tbl`")
            );
            assert_eq!(
                super::sql_select_columns_query(&mssql, "tbl", &[col]).expect("mssql"),
                format!("SELECT [{col}] FROM [tbl]")
            );
        }
    }

    #[test]
    fn fd90_12_quoting_matrix_schema_qualified_select_per_dialect() {
        let ansi = AnsiSchemaConn;
        let mysql = MysqlBacktickConn;
        let mssql = MssqlBracketConn;
        assert_eq!(
            super::sql_select_all_query_in_schema(&ansi, "users", Some("analytics")).expect("ansi"),
            "SELECT * FROM \"analytics\".\"users\""
        );
        assert_eq!(
            super::sql_select_all_query_in_schema(&mysql, "users", Some("analytics"))
                .expect("mysql"),
            "SELECT * FROM `analytics`.`users`"
        );
        assert_eq!(
            super::sql_select_all_query_in_schema(&mssql, "users", Some("dbo")).expect("mssql"),
            "SELECT * FROM [dbo].[users]"
        );
    }

    #[test]
    fn fd90_12_quoting_matrix_create_table_per_dialect() {
        let ansi = AnsiSchemaConn;
        let mysql = MysqlBacktickConn;
        let mssql = MssqlBracketConn;
        let cols = vec![
            super::sql_column_definition(&ansi, "id", "BIGINT").expect("ansi col"),
            super::sql_column_definition(&ansi, "select", "TEXT").expect("ansi reserved col"),
        ];
        assert_eq!(
            super::sql_create_table_query_in_schema(&ansi, "events", Some("public"), &cols)
                .expect("ansi create"),
            "CREATE TABLE IF NOT EXISTS \"public\".\"events\" (\"id\" BIGINT, \"select\" TEXT)"
        );
        let mysql_cols = vec![
            super::sql_column_definition(&mysql, "id", "BIGINT").expect("mysql col"),
            super::sql_column_definition(&mysql, "select", "TEXT").expect("mysql reserved col"),
        ];
        assert_eq!(
            super::sql_create_table_query_in_schema(
                &mysql,
                "events",
                Some("analytics"),
                &mysql_cols
            )
            .expect("mysql create"),
            "CREATE TABLE IF NOT EXISTS `analytics`.`events` (`id` BIGINT, `select` TEXT)"
        );
        let mssql_cols = vec![
            super::sql_column_definition(&mssql, "id", "BIGINT").expect("mssql col"),
            super::sql_column_definition(&mssql, "select", "NVARCHAR(MAX)")
                .expect("mssql reserved col"),
        ];
        assert_eq!(
            super::sql_create_table_query_in_schema(&mssql, "events", Some("dbo"), &mssql_cols)
                .expect("mssql create"),
            "CREATE TABLE IF NOT EXISTS [dbo].[events] ([id] BIGINT, [select] NVARCHAR(MAX))"
        );
    }

    #[test]
    fn fd90_12_quoting_matrix_insert_per_dialect_with_param_markers() {
        let ansi = AnsiSchemaConn;
        let mysql = MysqlBacktickConn;
        let mssql = MssqlBracketConn;
        let cols = vec!["id".to_owned(), "MixedCase".to_owned(), "select".to_owned()];
        assert_eq!(
            super::sql_insert_rows_query_in_schema(&ansi, "events", Some("public"), &cols)
                .expect("ansi insert"),
            "INSERT INTO \"public\".\"events\" (\"id\", \"MixedCase\", \"select\") VALUES ($1, $2, $3)"
        );
        assert_eq!(
            super::sql_insert_rows_query_in_schema(&mysql, "events", Some("analytics"), &cols)
                .expect("mysql insert"),
            "INSERT INTO `analytics`.`events` (`id`, `MixedCase`, `select`) VALUES (?, ?, ?)"
        );
        assert_eq!(
            super::sql_insert_rows_query_in_schema(&mssql, "events", Some("dbo"), &cols)
                .expect("mssql insert"),
            "INSERT INTO [dbo].[events] ([id], [MixedCase], [select]) VALUES (@p1, @p2, @p3)"
        );
    }

    #[test]
    fn fd90_12_quoting_matrix_multi_row_insert_param_ordinals_span_rows() {
        let ansi = AnsiSchemaConn;
        let mysql = MysqlBacktickConn;
        let cols = vec!["a".to_owned(), "b".to_owned()];
        assert_eq!(
            super::sql_multi_row_insert_query_in_schema(&ansi, "tbl", None, &cols, 2)
                .expect("ansi multi"),
            "INSERT INTO \"tbl\" (\"a\", \"b\") VALUES ($1, $2), ($3, $4)"
        );
        assert_eq!(
            super::sql_multi_row_insert_query_in_schema(&mysql, "tbl", None, &cols, 2)
                .expect("mysql multi"),
            "INSERT INTO `tbl` (`a`, `b`) VALUES (?, ?), (?, ?)"
        );
    }

    #[test]
    fn fd90_12_quoting_matrix_drop_table_per_dialect() {
        let ansi = AnsiSchemaConn;
        let mysql = MysqlBacktickConn;
        let mssql = MssqlBracketConn;
        assert_eq!(
            super::sql_drop_table_query_in_schema(&ansi, "events", Some("public"))
                .expect("ansi drop"),
            "DROP TABLE IF EXISTS \"public\".\"events\""
        );
        assert_eq!(
            super::sql_drop_table_query_in_schema(&mysql, "events", Some("analytics"))
                .expect("mysql drop"),
            "DROP TABLE IF EXISTS `analytics`.`events`"
        );
        assert_eq!(
            super::sql_drop_table_query_in_schema(&mssql, "events", Some("dbo"))
                .expect("mssql drop"),
            "DROP TABLE IF EXISTS [dbo].[events]"
        );
    }

    #[test]
    fn fd90_12_quoting_matrix_truncate_uses_default_delete_with_per_dialect_quoting() {
        // Default truncate_table impl emits `DELETE FROM <quoted>` and
        // routes through the backend's quote_identifier.
        #[derive(Default)]
        struct CapturingAnsi {
            captured: std::cell::RefCell<Vec<String>>,
        }
        impl super::SqlConnection for CapturingAnsi {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, sql: &str) -> Result<(), IoError> {
                self.captured.borrow_mut().push(sql.to_owned());
                Ok(())
            }
            fn table_exists(&self, _n: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _s: &str, _r: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _d: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _i: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
        }
        let ansi = CapturingAnsi::default();
        super::SqlConnection::truncate_table(&ansi, "events", Some("public"))
            .expect("ansi truncate");
        assert_eq!(
            ansi.captured.borrow().as_slice(),
            &["DELETE FROM \"public\".\"events\"".to_owned()]
        );

        #[derive(Default)]
        struct CapturingMysql {
            captured: std::cell::RefCell<Vec<String>>,
        }
        impl super::SqlConnection for CapturingMysql {
            fn query(&self, _q: &str, _p: &[Scalar]) -> Result<super::SqlQueryResult, IoError> {
                Ok(super::SqlQueryResult {
                    columns: vec![],
                    rows: vec![],
                })
            }
            fn execute_batch(&self, sql: &str) -> Result<(), IoError> {
                self.captured.borrow_mut().push(sql.to_owned());
                Ok(())
            }
            fn table_exists(&self, _n: &str) -> Result<bool, IoError> {
                Ok(false)
            }
            fn insert_rows(&self, _s: &str, _r: &[Vec<Scalar>]) -> Result<(), IoError> {
                Ok(())
            }
            fn dtype_sql(&self, _d: DType) -> &'static str {
                "TEXT"
            }
            fn index_dtype_sql(&self, _i: &Index) -> &'static str {
                "TEXT"
            }
            fn supports_schemas(&self) -> bool {
                true
            }
            fn quote_identifier(&self, ident: &str) -> Result<String, IoError> {
                if ident.contains('\0') {
                    return Err(IoError::Sql("invalid SQL identifier: NUL byte".to_owned()));
                }
                Ok(format!("`{}`", ident.replace('`', "``")))
            }
        }
        let mysql = CapturingMysql::default();
        super::SqlConnection::truncate_table(&mysql, "events", Some("analytics"))
            .expect("mysql truncate");
        assert_eq!(
            mysql.captured.borrow().as_slice(),
            &["DELETE FROM `analytics`.`events`".to_owned()]
        );
    }

    #[test]
    fn fd90_12_quoting_matrix_embedded_quote_chars_doubled_per_dialect() {
        // Embedded quote chars must be doubled per the dialect's escape
        // rule. quote_identifier is exposed for column names which may
        // legitimately contain embedded quotes (sql_column_definition
        // takes any string).
        let ansi = AnsiSchemaConn;
        let mysql = MysqlBacktickConn;
        let mssql = MssqlBracketConn;
        use super::SqlConnection as _;
        assert_eq!(ansi.quote_identifier("a\"b").expect("ansi"), "\"a\"\"b\"");
        assert_eq!(mysql.quote_identifier("a`b").expect("mysql"), "`a``b`");
        assert_eq!(mssql.quote_identifier("a]b").expect("mssql"), "[a]]b]");
        // Cross-dialect non-escape: ANSI doesn't escape backticks, etc.
        assert_eq!(
            ansi.quote_identifier("a`b")
                .expect("ansi backtick passthrough"),
            "\"a`b\""
        );
        assert_eq!(
            mysql
                .quote_identifier("a\"b")
                .expect("mysql quote passthrough"),
            "`a\"b`"
        );
        assert_eq!(
            mssql
                .quote_identifier("a\"b")
                .expect("mssql quote passthrough"),
            "[a\"b]"
        );
    }

    #[test]
    fn fd90_12_quoting_matrix_long_identifier_within_cap_succeeds_over_cap_rejected() {
        // PG cap = 63, MySQL cap = 64, MSSQL cap = 128.
        use super::SqlConnection as _;
        let ansi = AnsiSchemaConn;
        let mysql = MysqlBacktickConn;
        let mssql = MssqlBracketConn;
        let pg63 = "a".repeat(63);
        let pg64 = "a".repeat(64);
        let mysql64 = "b".repeat(64);
        let mysql65 = "b".repeat(65);
        let mssql128 = "c".repeat(128);
        let mssql129 = "c".repeat(129);

        super::validate_sql_identifier_length(&pg63, ansi.max_identifier_length(), "table")
            .expect("pg 63 ok");
        super::validate_sql_identifier_length(&mysql64, mysql.max_identifier_length(), "table")
            .expect("mysql 64 ok");
        super::validate_sql_identifier_length(&mssql128, mssql.max_identifier_length(), "table")
            .expect("mssql 128 ok");

        let err =
            super::validate_sql_identifier_length(&pg64, ansi.max_identifier_length(), "table")
                .expect_err("pg 64 over cap");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("63") && msg.contains("table")));
        let err =
            super::validate_sql_identifier_length(&mysql65, mysql.max_identifier_length(), "table")
                .expect_err("mysql 65 over cap");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("64")));
        let err = super::validate_sql_identifier_length(
            &mssql129,
            mssql.max_identifier_length(),
            "table",
        )
        .expect_err("mssql 129 over cap");
        assert!(matches!(err, IoError::Sql(msg) if msg.contains("128")));
    }

    #[test]
    fn fd90_12_query_builders_enforce_identifier_length_caps() {
        fn assert_length_error(err: IoError, kind: &str) {
            assert!(
                matches!(&err, IoError::Sql(msg)
                    if msg.contains(kind)
                        && msg.contains("63")
                        && msg.contains("backend identifier limit")),
                "expected SQL identifier-length error for {kind}, got {err:?}"
            );
        }

        let conn = AnsiSchemaConn;
        let over_cap = "a".repeat(64);
        let cols = vec![over_cap.clone()];
        let defs = vec!["id BIGINT".to_owned()];

        assert_length_error(
            super::sql_select_all_query_in_schema(&conn, &over_cap, None)
                .expect_err("SELECT * table over cap"),
            "table",
        );
        assert_length_error(
            super::sql_select_all_query_in_schema(&conn, "events", Some(&over_cap))
                .expect_err("SELECT * schema over cap"),
            "schema",
        );
        assert_length_error(
            super::sql_select_columns_query_in_schema(&conn, "events", None, &[over_cap.as_str()])
                .expect_err("SELECT column over cap"),
            "column",
        );
        assert_length_error(
            super::sql_create_table_query_in_schema(&conn, &over_cap, None, &defs)
                .expect_err("CREATE table over cap"),
            "table",
        );
        assert_length_error(
            super::sql_insert_rows_query_in_schema(&conn, "events", None, &cols)
                .expect_err("INSERT column over cap"),
            "column",
        );
        assert_length_error(
            super::sql_multi_row_insert_query_in_schema(&conn, "events", None, &cols, 1)
                .expect_err("multi-row INSERT column over cap"),
            "column",
        );
        assert_length_error(
            super::sql_drop_table_query_in_schema(&conn, &over_cap, None)
                .expect_err("DROP table over cap"),
            "table",
        );
        assert_length_error(
            super::SqlConnection::truncate_table(&conn, &over_cap, None)
                .expect_err("TRUNCATE fallback table over cap"),
            "table",
        );
    }

    #[test]
    fn fd90_12_quoting_matrix_special_characters_rejected_by_validator() {
        // Per validate_sql_ident: only alphanumeric + underscore allowed.
        // Special chars (`-`, `.`, ` `, `:`, `'`, `"`, `;`) and dotted
        // names must be rejected before they ever reach quote_identifier.
        let bad: &[&str] = &[
            "my-col",
            "my.col",
            "my col",
            "my:col",
            "my'col",
            "my\"col",
            "my;col",
            "schema.table",
            "DROP--",
            "",
        ];
        for name in bad {
            let err =
                super::validate_sql_table_name(name).expect_err(&format!("must reject `{name}`"));
            assert!(matches!(err, IoError::Sql(msg) if msg.contains("invalid table name")));
            let err = super::validate_sql_column_name(name)
                .expect_err(&format!("must reject col `{name}`"));
            assert!(matches!(err, IoError::Sql(msg) if msg.contains("invalid column name")));
        }
    }

    #[test]
    fn fd90_12_quoting_matrix_nul_byte_rejected_at_quote_identifier_layer() {
        // Defense in depth: even if a backend's quote_identifier is
        // called with a NUL-containing string (bypassing
        // validate_sql_ident), every dialect must reject — guards
        // against C-string driver-layer statement injection via
        // embedded null terminators.
        use super::SqlConnection as _;
        let ansi = AnsiSchemaConn;
        let mysql = MysqlBacktickConn;
        let mssql = MssqlBracketConn;
        let err_ansi = ansi
            .quote_identifier("ab\0cd")
            .expect_err("ansi must reject NUL");
        assert!(matches!(err_ansi, IoError::Sql(msg) if msg.contains("NUL")));
        let err_mysql = mysql
            .quote_identifier("ab\0cd")
            .expect_err("mysql must reject NUL");
        assert!(matches!(err_mysql, IoError::Sql(msg) if msg.contains("NUL")));
        let err_mssql = mssql
            .quote_identifier("ab\0cd")
            .expect_err("mssql must reject NUL");
        assert!(matches!(err_mssql, IoError::Sql(msg) if msg.contains("NUL")));
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_empty_typed_table_preserves_column_dtypes_ex8ec() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE empty_typed_ex8ec (i INTEGER, t TEXT, r REAL);",
        )
        .expect("create");
        // No INSERTs — empty result set.

        let frame = read_sql(&conn, "SELECT * FROM empty_typed_ex8ec").expect("read empty");
        assert_eq!(frame.index().len(), 0, "empty table should yield zero rows");

        let i_col = frame.column("i").expect("column i must exist");
        assert_eq!(i_col.dtype(), crate::DType::Int64);
        let t_col = frame.column("t").expect("column t must exist");
        assert_eq!(t_col.dtype(), crate::DType::Utf8);
        let r_col = frame.column("r").expect("column r must exist");
        assert_eq!(r_col.dtype(), crate::DType::Float64);
    }

    #[cfg(feature = "sql-sqlite")]
    #[test]
    fn read_sql_all_null_typed_table_preserves_column_dtypes_0qo9c() {
        let conn = make_sql_test_conn();
        super::SqlConnection::execute_batch(
            &conn,
            "CREATE TABLE all_null_typed_0qo9c (i INTEGER, t TEXT, r REAL);
             INSERT INTO all_null_typed_0qo9c (i, t, r) VALUES (NULL, NULL, NULL);",
        )
        .expect("create and insert");

        let frame = read_sql(&conn, "SELECT * FROM all_null_typed_0qo9c")
            .expect("read all-null typed table");
        assert_eq!(frame.index().len(), 1);

        let i_col = frame.column("i").expect("column i must exist");
        assert_eq!(i_col.dtype(), crate::DType::Int64);
        assert!(i_col.values()[0].is_missing());
        let t_col = frame.column("t").expect("column t must exist");
        assert_eq!(t_col.dtype(), crate::DType::Utf8);
        assert!(t_col.values()[0].is_missing());
        let r_col = frame.column("r").expect("column r must exist");
        assert_eq!(r_col.dtype(), crate::DType::Float64);
        assert!(r_col.values()[0].is_missing());
    }
}

#[cfg(test)]
mod fused_numeric_csv_field_tests {
    use super::{
        CsvTypedColumnValues, fuse_scan_numeric_csv_field, push_csv_default_numeric_field,
        push_fused_numeric_csv_field,
    };

    fn assert_same_columns(base: &CsvTypedColumnValues, fused: &CsvTypedColumnValues, token: &str) {
        match (base, fused) {
            (CsvTypedColumnValues::Int64(lhs), CsvTypedColumnValues::Int64(rhs)) => {
                assert_eq!(lhs, rhs, "Int64 mismatch for token {token:?}");
            }
            (CsvTypedColumnValues::Float64(lhs), CsvTypedColumnValues::Float64(rhs)) => {
                let lhs_bits: Vec<u64> = lhs.iter().map(|value| value.to_bits()).collect();
                let rhs_bits: Vec<u64> = rhs.iter().map(|value| value.to_bits()).collect();
                assert_eq!(
                    lhs_bits, rhs_bits,
                    "Float64 bit mismatch for token {token:?}"
                );
            }
            _ => panic!("column dtype diverged for token {token:?}"),
        }
    }

    /// Every token the fused scanner admits must produce bit-identical column
    /// state to the `push_csv_default_numeric_field` fallback, for both a
    /// fresh Int64 column and a Float64 column, under every terminator.
    #[test]
    fn fused_field_matches_fallback_parser() {
        let tokens = [
            "0",
            "-0",
            "+7",
            "007",
            "5",
            "-5",
            "123456789",
            "999999999999999999",
            "-999999999999999999",
            "9007199254740993",
            "1234567890123456789",
            "0.1",
            "-0.1",
            "+0.5",
            ".5",
            "-.5",
            "00.5",
            "5.",
            "12.34",
            "123456.7",
            "0.30000000000000004",
            "9007199254740993.0",
            "1e5",
            "1E5",
            "1.5e-3",
            "inf",
            "-inf",
            "nan",
            "NaN",
            "",
            " 5",
            "5 ",
            "true",
            "false",
            "TRUE",
            "1.2.3",
            "--5",
            "+-5",
            "1-2",
            "#N/A",
            "NULL",
            "abc",
        ];

        for token in tokens {
            for suffix in ["", ",", "\n", ",9\n"] {
                let data = format!("{token}{suffix}");
                let Some(field) = fuse_scan_numeric_csv_field(data.as_bytes(), 0) else {
                    // Rejected tokens take the unchanged fallback route;
                    // nothing further to prove.
                    continue;
                };
                assert_eq!(
                    field.end,
                    token.len(),
                    "fused scanner must stop at the delimiter for token {token:?}"
                );

                // The fallback must accept every token the fused scanner
                // admits (the fused grammar is a strict subset).
                let mut base_int = CsvTypedColumnValues::Int64(Vec::new());
                assert!(
                    push_csv_default_numeric_field(&mut base_int, token.as_bytes()),
                    "fallback rejected fused-admitted token {token:?}"
                );
                let mut fused_int = CsvTypedColumnValues::Int64(Vec::new());
                push_fused_numeric_csv_field(&mut fused_int, &field);
                assert_same_columns(&base_int, &fused_int, token);

                let mut base_float = CsvTypedColumnValues::Float64(Vec::new());
                assert!(
                    push_csv_default_numeric_field(&mut base_float, token.as_bytes()),
                    "fallback Float64 rejected fused-admitted token {token:?}"
                );
                let mut fused_float = CsvTypedColumnValues::Float64(Vec::new());
                push_fused_numeric_csv_field(&mut fused_float, &field);
                assert_same_columns(&base_float, &fused_float, token);
            }
        }
    }

    /// The sign of zero must survive the fused route on Float64 columns:
    /// `-0` parses to -0.0 via `parse_f64_csv_number`, and the fused field
    /// must carry the same bits.
    #[test]
    fn fused_field_preserves_negative_zero_bits() {
        let field = fuse_scan_numeric_csv_field(b"-0,", 0).expect("fused scanner must admit -0");
        assert_eq!(field.int_value, Some(0));
        assert_eq!(field.float_value.to_bits(), (-0.0f64).to_bits());

        let mut float_column = CsvTypedColumnValues::Float64(Vec::new());
        push_fused_numeric_csv_field(&mut float_column, &field);
        match float_column {
            CsvTypedColumnValues::Float64(values) => {
                assert_eq!(values.len(), 1);
                assert_eq!(values[0].to_bits(), (-0.0f64).to_bits());
            }
            CsvTypedColumnValues::Int64(_) => panic!("expected Float64 column"),
        }
    }
}

#[cfg(test)]
mod merge_simple_numeric_csv_chunks_tests {
    use super::{CsvTypedColumnValues, merge_simple_numeric_csv_chunks};

    /// Verbatim copy of the pre-parallel chunk-major merge, kept as the
    /// reference implementation for the differential test below.
    fn reference_merge(
        parsed_chunks: Vec<(Vec<CsvTypedColumnValues>, i64)>,
        header_count: usize,
    ) -> Option<(Vec<CsvTypedColumnValues>, i64)> {
        let mut final_is_float = vec![false; header_count];
        let mut row_count = 0i64;
        for (columns, rows) in &parsed_chunks {
            if columns.len() != header_count {
                return None;
            }
            row_count = row_count.checked_add(*rows)?;
            for (idx, column) in columns.iter().enumerate() {
                final_is_float[idx] |= matches!(column, CsvTypedColumnValues::Float64(_));
            }
        }

        let capacity = usize::try_from(row_count).ok()?;
        let mut merged: Vec<CsvTypedColumnValues> = final_is_float
            .into_iter()
            .map(|is_float| {
                if is_float {
                    CsvTypedColumnValues::Float64(Vec::with_capacity(capacity))
                } else {
                    CsvTypedColumnValues::Int64(Vec::with_capacity(capacity))
                }
            })
            .collect();

        for (columns, _) in parsed_chunks {
            for (dst, src) in merged.iter_mut().zip(columns) {
                match (dst, src) {
                    (CsvTypedColumnValues::Int64(dst), CsvTypedColumnValues::Int64(src)) => {
                        dst.extend(src);
                    }
                    (CsvTypedColumnValues::Float64(dst), CsvTypedColumnValues::Int64(src)) => {
                        dst.extend(src.into_iter().map(|value| value as f64));
                    }
                    (CsvTypedColumnValues::Float64(dst), CsvTypedColumnValues::Float64(src)) => {
                        dst.extend(src);
                    }
                    (CsvTypedColumnValues::Int64(_), CsvTypedColumnValues::Float64(_)) => {
                        return None;
                    }
                }
            }
        }

        Some((merged, row_count))
    }

    fn build_chunks(
        chunk_count: usize,
        rows_per_chunk: usize,
        header_count: usize,
        float_from_chunk_for_col: impl Fn(usize) -> usize,
    ) -> Vec<(Vec<CsvTypedColumnValues>, i64)> {
        (0..chunk_count)
            .map(|chunk| {
                let columns = (0..header_count)
                    .map(|col| {
                        if chunk >= float_from_chunk_for_col(col) {
                            CsvTypedColumnValues::Float64(
                                (0..rows_per_chunk)
                                    .map(|row| {
                                        (chunk * rows_per_chunk + row) as f64 * 0.5
                                            + col as f64 * 1000.0
                                    })
                                    .collect(),
                            )
                        } else {
                            CsvTypedColumnValues::Int64(
                                (0..rows_per_chunk)
                                    .map(|row| {
                                        (chunk * rows_per_chunk + row) as i64 + col as i64 * 1000
                                    })
                                    .collect(),
                            )
                        }
                    })
                    .collect();
                (columns, rows_per_chunk as i64)
            })
            .collect()
    }

    fn assert_merge_matches_reference(
        chunks: Vec<(Vec<CsvTypedColumnValues>, i64)>,
        header_count: usize,
    ) {
        let reference_chunks: Vec<(Vec<CsvTypedColumnValues>, i64)> = chunks
            .iter()
            .map(|(columns, rows)| {
                let cloned = columns
                    .iter()
                    .map(|column| match column {
                        CsvTypedColumnValues::Int64(values) => {
                            CsvTypedColumnValues::Int64(values.clone())
                        }
                        CsvTypedColumnValues::Float64(values) => {
                            CsvTypedColumnValues::Float64(values.clone())
                        }
                    })
                    .collect();
                (cloned, *rows)
            })
            .collect();

        let expected = reference_merge(reference_chunks, header_count);
        let actual = merge_simple_numeric_csv_chunks(chunks, header_count);

        match (expected, actual) {
            (None, None) => {}
            (Some((expected_columns, expected_rows)), Some((actual_columns, actual_rows))) => {
                assert_eq!(expected_rows, actual_rows);
                assert_eq!(expected_columns.len(), actual_columns.len());
                for (idx, (lhs, rhs)) in expected_columns
                    .iter()
                    .zip(actual_columns.iter())
                    .enumerate()
                {
                    match (lhs, rhs) {
                        (CsvTypedColumnValues::Int64(lhs), CsvTypedColumnValues::Int64(rhs)) => {
                            assert_eq!(lhs, rhs, "Int64 column {idx} diverged");
                        }
                        (
                            CsvTypedColumnValues::Float64(lhs),
                            CsvTypedColumnValues::Float64(rhs),
                        ) => {
                            let lhs_bits: Vec<u64> =
                                lhs.iter().map(|value| value.to_bits()).collect();
                            let rhs_bits: Vec<u64> =
                                rhs.iter().map(|value| value.to_bits()).collect();
                            assert_eq!(lhs_bits, rhs_bits, "Float64 column {idx} bits diverged");
                        }
                        _ => panic!("column {idx} dtype diverged"),
                    }
                }
            }
            (expected, actual) => panic!(
                "merge outcome diverged: reference some={} actual some={}",
                expected.is_some(),
                actual.is_some()
            ),
        }
    }

    /// Big merge (crosses the parallel threshold): mixed promotion patterns —
    /// some columns all-Int64, some all-Float64, some promoting mid-stream —
    /// must match the chunk-major reference bit-for-bit, in column order.
    #[test]
    fn parallel_merge_matches_reference_with_mixed_promotion() {
        // 8 chunks x 1000 rows x 12 columns = 96000 values > 65536 threshold.
        let chunks = build_chunks(8, 1000, 12, |col| match col % 4 {
            0 => usize::MAX, // never float: stays Int64
            1 => 0,          // float from the first chunk
            2 => 3,          // promotes mid-stream
            _ => 7,          // promotes at the last chunk
        });
        assert_merge_matches_reference(chunks, 12);
    }

    /// Small merge (below the parallel threshold) takes the sequential path
    /// and must also match.
    #[test]
    fn sequential_merge_matches_reference() {
        let chunks = build_chunks(3, 4, 5, |col| if col % 2 == 0 { usize::MAX } else { 1 });
        assert_merge_matches_reference(chunks, 5);
    }

    /// More worker groups than columns (header_count < MAX_WORKERS) and
    /// header_count not divisible by the group size must keep column order.
    #[test]
    fn parallel_merge_handles_narrow_and_ragged_widths() {
        for header_count in [2, 3, 7, 9, 17] {
            let chunks = build_chunks(5, 2000, header_count, |col| col % 6);
            assert_merge_matches_reference(chunks, header_count);
        }
    }

    /// A chunk whose column count disagrees with the header must reject, as
    /// before.
    #[test]
    fn merge_rejects_mismatched_chunk_width() {
        let mut chunks = build_chunks(2, 10, 4, |_| usize::MAX);
        chunks[1].0.pop();
        assert!(merge_simple_numeric_csv_chunks(chunks, 4).is_none());
    }
}