convert_genome 0.3.2

use crate::cli::Sex;
use crate::reference::ParBoundaries;
use std::{
    fs,
    io::{self},
    path::PathBuf,
};

use anyhow::{Context, Result, anyhow, bail};
use clap::ValueEnum;
use noodles::bcf;
use noodles::vcf::{
    self,
    header::{
        FileFormat,
        record::{
            key,
            value::{
                Collection, Map,
                map::{
                    AlternativeAllele, Contig, Format, Info as InfoMap,
                    info::{Number, Type},
                },
            },
        },
    },
    variant::{
        io::Write as VariantRecordWrite,
        record::samples::keys::key as format_key,
        record::samples::series::value::genotype::Phasing,
        record_buf::{RecordBuf, Samples, samples::sample::Value},
    },
};
use rayon::prelude::*;

use thiserror::Error;
use time::{OffsetDateTime, macros::format_description};

use crate::{
    ConversionSummary,
    dtc::{self, Allele as DtcAllele, parse_genotype},
    external_sort::{RecordExternalSorter, RecordOrder, SortFormat},
    liftover::{ChainRegistry, LiftoverAdapter},
    plink::PlinkWriter,
    reference::{ReferenceError, ReferenceGenome},
    vcf_utils::remap_sample_genotypes,
};
use std::sync::Arc;

/// Supported output formats for the converter.
#[derive(Debug, Clone, Copy, Eq, PartialEq, ValueEnum)]
pub enum OutputFormat {
    /// Variant Call Format text output.
    Vcf,
    /// Binary Call Format output.
    Bcf,
    /// PLINK 1.9 binary output (.bed, .bim, .fam).
    Plink,
}

/// Default minimum number of emitted variant records below which a conversion
/// is treated as a failure rather than a silent near-empty result. A genuine
/// genotyping array or genome yields tens of thousands to millions of variant
/// sites; a handful (or zero) almost always means the input was empty, the
/// wrong file, or unparseable. Overridable via `--min-emitted-variants`.
pub const DEFAULT_MIN_EMITTED_VARIANTS: usize = 1000;

/// Default minimum build-detection confidence (0..=1, winning match rate over
/// the sum of both builds) required to trust an auto-detected genome build.
/// Below this the coordinates match neither build decisively and silently
/// assuming GRCh38 would risk scoring a genome against the wrong coordinates.
/// Overridable via `--min-build-confidence`; bypass detection entirely with
/// `--input-build`.
pub const DEFAULT_MIN_BUILD_CONFIDENCE: f64 = 0.55;

/// Default maximum fraction of input lines that may fail to parse before the
/// conversion is treated as a failure. Above this the input is almost
/// certainly the wrong format (e.g. binary data or a non-genome CSV read as
/// DTC). Overridable via `--max-parse-error-ratio`.
pub const DEFAULT_MAX_PARSE_ERROR_RATIO: f64 = 0.5;

/// Configuration required to drive a conversion.
#[derive(Debug, Clone)]
pub struct ConversionConfig {
    pub input: PathBuf,
    pub input_format: crate::input::InputFormat,
    pub input_origin: String,
    pub reference_fasta: Option<PathBuf>,
    pub reference_origin: Option<String>,
    pub reference_fai: Option<PathBuf>,
    pub reference_fai_origin: Option<String>,
    pub output: PathBuf,
    pub output_dir: Option<PathBuf>,
    pub output_format: OutputFormat,
    pub sample_id: String,
    pub assembly: String,
    pub include_reference_sites: bool,
    pub sex: Option<Sex>,
    pub par_boundaries: Option<ParBoundaries>,
    pub standardize: bool,
    pub panel: Option<PathBuf>,
    /// Caller-asserted source build (e.g. "GRCh37", "GRCh38"). When `Some`,
    /// position-based build detection (`check_build`) is skipped entirely
    /// and the asserted value is treated as the detected build. When
    /// `None` (default), behavior is unchanged from prior releases.
    pub input_build: Option<String>,
    /// Clinical-safety floor: if the conversion emits fewer than this many
    /// variant records, [`convert_dtc_file`] returns an `Err` instead of a
    /// silent near-empty result. See the `DEFAULT_MIN_EMITTED_VARIANTS` const.
    pub min_emitted_variants: usize,
    /// Clinical-safety floor: minimum auto-detected build confidence (0..=1)
    /// required to proceed without an explicit `--input-build`. See the
    /// default const of the same name for the rationale.
    pub min_build_confidence: f64,
    /// Clinical-safety ceiling: maximum fraction of input lines that may fail
    /// to parse before the conversion is rejected. See the default const of
    /// the same name for the rationale.
    pub max_parse_error_ratio: f64,
}

// ConversionSummary moved to crate root

// DtcAllele moved to dtc.rs

/// Errors raised while converting an individual record.
#[derive(Debug, Error)]
pub enum RecordConversionError {
    #[error("unknown contig {chromosome}")]
    UnknownContig { chromosome: String },
    #[error("missing genotype call at {chromosome}:{position}")]
    MissingGenotype { chromosome: String, position: u64 },
    #[error("invalid genotype '{genotype}' at {chromosome}:{position}")]
    InvalidGenotype {
        chromosome: String,
        position: u64,
        genotype: String,
    },
    #[error("reference lookup failed for {chromosome}:{position}: {source}")]
    Reference {
        chromosome: String,
        position: u64,
        #[source]
        source: ReferenceError,
    },
    #[error("failed to set genomic position: {0}")]
    Position(#[from] noodles::core::position::TryFromIntError),
}

trait VariantWriter {
    fn write_variant(&mut self, header: &vcf::Header, record: &RecordBuf) -> io::Result<()>;
}

impl<W> VariantWriter for vcf::io::Writer<W>
where
    W: io::Write,
{
    fn write_variant(&mut self, header: &vcf::Header, record: &RecordBuf) -> io::Result<()> {
        VariantRecordWrite::write_variant_record(self, header, record)
    }
}

impl<W> VariantWriter for bcf::io::Writer<W>
where
    W: io::Write,
{
    fn write_variant(&mut self, header: &vcf::Header, record: &RecordBuf) -> io::Result<()> {
        VariantRecordWrite::write_variant_record(self, header, record)
    }
}

impl VariantWriter for PlinkWriter {
    fn write_variant(&mut self, _: &vcf::Header, record: &RecordBuf) -> io::Result<()> {
        // Header not used for PLINK format but required by trait
        self.write_variant(record)
    }
}

/// Pre-scan a DTC-like file to collect records for inference.
/// This reads the file once and returns records for both build and sex inference.
///
/// `format` selects the line parser: GenomeStudio Final Reports use the
/// [`crate::genomestudio`] reader; everything else uses the plain DTC reader.
pub fn prescan_dtc_records(
    input: &std::path::Path,
    format: crate::input::InputFormat,
) -> Result<Vec<dtc::Record>> {
    let reader = crate::smart_reader::open_input(input)
        .with_context(|| format!("failed to open input for inference: {}", input.display()))?;

    // Collect records (using same max_records limit for safety)
    let max_records = crate::input::get_max_records_limit();
    let mut records = Vec::new();
    let mut records_read = 0;

    let mut collect = |res: Option<dtc::Record>| -> bool {
        if let Some(limit) = max_records
            && records_read >= limit
        {
            return false;
        }
        if let Some(rec) = res {
            records.push(rec);
            records_read += 1;
        }
        true
    };

    if matches!(format, crate::input::InputFormat::GenomeStudio) {
        let gs_reader = crate::genomestudio::Reader::new(reader)
            .map_err(|e| anyhow!("failed to read GenomeStudio Final Report: {e}"))?;
        // convert_genome emits a single sample. A Final Report covering several
        // samples is converted for its FIRST Sample ID only; warn loudly so the
        // caller isn't surprised by missing samples.
        if let Some(n) = gs_reader.metadata().num_samples
            && n > 1
        {
            tracing::warn!(
                num_samples = n,
                "GenomeStudio report contains {n} samples; converting only the first. \
                 Split the report per-sample to convert the others.",
            );
        }
        for res in gs_reader {
            if !collect(res.ok()) {
                break;
            }
        }
    } else {
        let dtc_reader = dtc::Reader::new(reader);
        for res in dtc_reader {
            if !collect(res.ok()) {
                break;
            }
        }
    }

    Ok(records)
}

/// Build a [`DtcSource`] for a DTC-like input (plain DTC text or a GenomeStudio
/// Final Report), applying the liftover-aware reference/PAR handling shared by
/// both. Selects the GenomeStudio line parser when `format` is
/// [`crate::input::InputFormat::GenomeStudio`], otherwise the plain DTC parser.
fn build_dtc_like_source(
    format: crate::input::InputFormat,
    config: &ConversionConfig,
    reference: &Option<ReferenceGenome>,
    liftover_active: bool,
    inferred_strand: Option<crate::source_ref::InferredStrand>,
) -> Result<Box<dyn crate::input::VariantSource>> {
    let reader = crate::smart_reader::open_input(&config.input)
        .with_context(|| format!("failed to open input {}", config.input.display()))?;

    // If liftover is active, we do NOT provide the reference to DtcSource
    // (this prevents validation against the wrong genome; records emit an 'N'
    // ref), and we skip PAR-boundary ploidy checks because config.par_boundaries
    // are in target coordinates while the source operates in source coordinates.
    let dtc_reference = if liftover_active {
        None
    } else {
        reference.clone()
    };
    let mut source_config = config.clone();
    if liftover_active {
        source_config.par_boundaries = None;
    }

    let source = if matches!(format, crate::input::InputFormat::GenomeStudio) {
        let gs_reader = crate::genomestudio::Reader::new(reader)
            .map_err(|e| anyhow!("failed to read GenomeStudio Final Report: {e}"))?;
        crate::input::DtcSource::new(gs_reader, dtc_reference, source_config, inferred_strand)
            .with_context(|| "failed to initialize GenomeStudio source")?
    } else {
        let dtc_reader = dtc::Reader::new(reader);
        crate::input::DtcSource::new(dtc_reader, dtc_reference, source_config, inferred_strand)
            .with_context(|| "failed to initialize DTC source")?
    };
    Ok(Box::new(source))
}

fn builds_match(detected_build: &str, target_build: &str) -> bool {
    let detected_normalized = detected_build.to_lowercase();
    let target_normalized = target_build.to_lowercase();

    (detected_normalized.contains("37") || detected_normalized.contains("hg19"))
        && (target_normalized.contains("37") || target_normalized.contains("hg19"))
        || (detected_normalized.contains("38") || detected_normalized.contains("hg38"))
            && (target_normalized.contains("38") || target_normalized.contains("hg38"))
}

/// Convert the provided direct-to-consumer genotype file into VCF or BCF.
/// Convert the provided input file into VCF, BCF, or PLINK.
pub fn convert_dtc_file(config: ConversionConfig) -> Result<ConversionSummary> {
    tracing::info!(
        input_format = ?config.input_format,
        output_format = ?config.output_format,
        reference = ?config.reference_fasta,
        input = %config.input.display(),
        output = %config.output.display(),
        sample_id = %config.sample_id,
        panel = ?config.panel,
        standardize = config.standardize,
        "starting conversion",
    );

    // Resolve `Auto` to a concrete format up front. The CLI already does this
    // before calling us, but library callers may pass `Auto`; resolving it once
    // here means every downstream decision — reference requirement, build/sex/
    // strand inference, FORMAT-field declaration (header) and emission
    // (DtcSource) — sees the real format and stays consistent.
    let mut config = config;
    if matches!(config.input_format, crate::input::InputFormat::Auto) {
        config.input_format = crate::input::InputFormat::detect(&config.input);
        tracing::info!(detected = ?config.input_format, "resolved Auto input format");
    }

    // Determine if reference is required based on input format and options
    let mut requires_reference =
        config.input_format.is_dtc_like() || config.standardize || config.panel.is_some();

    // Track inference results for the report
    let mut sex_inferred = false;
    let mut sex_confidence: Option<f64> = None;
    let mut sex_y_genome_density: Option<f64> = None;
    let mut sex_x_autosome_het_ratio: Option<f64> = None;

    // Auto-detect build and sex if not provided (DTC format only)
    let mut liftover_chain: Option<Arc<crate::liftover::ChainMap>> = None;
    #[allow(unused_assignments)]
    let mut inferred_build_opt: Option<String> = None;
    let mut inferred_strand: Option<crate::source_ref::InferredStrand> = None;

    let source_reference_for_liftover: Option<ReferenceGenome> = None;
    // We will initialize 'reference' strictly as the TARGET reference after build detection.
    let mut reference: Option<ReferenceGenome> = None;

    // build_detection variable is used in report_builder
    let mut build_detection: Option<crate::report::BuildDetection> = None;

    fn set_auto_reference_metadata(config: &mut ConversionConfig, reference: &ReferenceGenome) {
        config.reference_fasta = Some(reference.path().to_path_buf());
        config.reference_origin = Some(format!("auto({})", config.assembly));
    }

    if config.input_format.is_dtc_like() {
        // Pre-scan the genotype file for inference (done once, used for both)
        let prescan_records = prescan_dtc_records(&config.input, config.input_format)?;

        if prescan_records.is_empty() {
            tracing::warn!("No records available for build detection; skipping build inference");
        } else if let Some(declared) = config.input_build.clone() {
            // Caller asserted the source build; skip position-based detection.
            tracing::info!(
                "Build declared by caller: {}; skipping detection.",
                declared
            );
            inferred_build_opt = Some(declared.clone());
            build_detection = Some(crate::report::BuildDetection {
                detected_build: declared.clone(),
                hg19_match_rate: f64::NAN,
                hg38_match_rate: f64::NAN,
                // Caller-declared build: no detection was run, so no confidence.
                build_confidence: None,
            });

            if !builds_match(&declared, &config.assembly) {
                tracing::info!(
                    "Declared build {} differs from target {}. Initiating liftover.",
                    declared,
                    config.assembly
                );
                match ChainRegistry::new() {
                    Ok(registry) => match registry.get_chain(&declared, &config.assembly) {
                        Ok(chain) => {
                            liftover_chain = Some(Arc::new(chain));
                            config.standardize = true;
                        }
                        Err(e) => {
                            tracing::error!("Failed to load chain file: {}", e);
                        }
                    },
                    Err(e) => {
                        tracing::error!("Failed to initialize ChainRegistry: {}", e);
                    }
                }
            } else {
                tracing::info!("Declared build matches target assembly. No liftover needed.");
            }
        } else {
            // Build Detection using check_build library (position-only, not allele-based)
            // This avoids false liftover triggers on homozygous-alt sites
            tracing::info!("Detecting genome build using check_build (position-only)...");

            // This uses check_build's internal caching and does NOT require us to provide a reference
            match crate::inference::detect_build_from_dtc(&prescan_records) {
                Ok(detection) => {
                    tracing::info!("Detected input build: {}", detection.detected_build);
                    inferred_build_opt = Some(detection.detected_build.clone());
                    build_detection = Some(crate::report::BuildDetection {
                        detected_build: detection.detected_build.clone(),
                        hg19_match_rate: detection.hg19_match_rate,
                        hg38_match_rate: detection.hg38_match_rate,
                        build_confidence: detection.build_confidence(),
                    });

                    if !builds_match(&detection.detected_build, &config.assembly) {
                        println!(
                            "DEBUG: Detected build {} != target {}. Initiating liftover...",
                            detection.detected_build, config.assembly
                        );
                        tracing::info!(
                            "Detected build {} differs from target {}. Initiating liftover.",
                            detection.detected_build,
                            config.assembly
                        );

                        // Setup Liftover
                        match ChainRegistry::new() {
                            Ok(registry) => {
                                match registry
                                    .get_chain(&detection.detected_build, &config.assembly)
                                {
                                    Ok(chain) => {
                                        println!("DEBUG: Chain loaded successfully.");
                                        let liftover_chain_local = Some(Arc::new(chain));
                                        liftover_chain = liftover_chain_local;
                                        // Force standardization for liftover workflow
                                        config.standardize = true;
                                    }
                                    Err(e) => {
                                        println!("DEBUG: Failed to load chain: {}", e);
                                        tracing::error!("Failed to load chain file: {}", e);
                                    }
                                }
                            }
                            Err(e) => {
                                println!("DEBUG: ChainRegistry init failed: {}", e);
                                tracing::error!("Failed to initialize ChainRegistry: {}", e);
                            }
                        }
                    } else {
                        tracing::info!("Build matches target assembly. No liftover needed.");
                    }
                }
                Err(e) => {
                    return Err(anyhow!(
                        "Build detection failed: {}. Refusing to assume input matches target ({})",
                        e,
                        config.assembly
                    ));
                }
            }
        }

        // Strand handling.
        //
        // Illumina GenomeStudio Final Reports give us the genotype on the
        // genome's `+` strand directly (the `Allele1/2 - Plus` columns the
        // reader requires). That is authoritative and per-marker correct, so we
        // skip the file-wide strand heuristic entirely — it would be both
        // redundant (an extra reference download + scan) and *less* accurate
        // than the source-of-truth the array vendor already provides.
        if matches!(config.input_format, crate::input::InputFormat::GenomeStudio) {
            tracing::info!(
                "GenomeStudio report: using authoritative Plus-strand alleles; skipping strand inference"
            );
            inferred_strand = Some(crate::source_ref::InferredStrand::Forward);
        } else if let Some(ref detected_build) = inferred_build_opt {
            // Strand Inference (fail-closed)
            // Use the detected source build and source reference to infer file-wide orientation.
            tracing::info!(build = %detected_build, "Inferring strand orientation for DTC input");
            let source_ref = crate::source_ref::load_source_reference(detected_build)
                .with_context(|| "failed to load source reference for strand inference")?;

            match crate::source_ref::infer_strand_lock(&prescan_records, &source_ref) {
                Ok(strand) => {
                    inferred_strand = Some(strand);
                    // Do NOT populate source_reference_for_liftover.
                    // Doing so causes LiftoverAdapter to pre-fill REF with the source base.
                    // This switches LiftoverAdapter from "Permissive N-ref" mode to "Strict" mode.
                    // Strict mode rejects records where the source ref doesn't match the target ref
                    // (which happens frequently e.g. hg19 A -> hg38 G).
                    // We want permissive lifting for DTC files.
                    // source_reference_for_liftover = Some(source_ref);
                }
                Err(e) => {
                    // If liftover is required, strand uncertainty is a hard error.
                    // If liftover is not required, allow conversion to proceed (it may emit
                    // fewer or less-harmonized variants) but do not block empty/sparse inputs.
                    if liftover_chain.is_some() {
                        return Err(e).with_context(|| "strand inference failed");
                    }
                    tracing::warn!(error = %e, "strand inference failed; defaulting to Forward");
                    inferred_strand = Some(crate::source_ref::InferredStrand::Forward);
                }
            }
        }

        // Initialize 'reference' for input validation/standardization
        // Initialize 'reference' (Target Reference) for output/validation/standardization
        if reference.is_none() {
            // 1. Try user-provided FASTA
            if let Some(ref fasta_path) = config.reference_fasta {
                reference = Some(
                    ReferenceGenome::open(fasta_path, config.reference_fai.clone())
                        .with_context(|| "failed to open reference genome")?,
                );
            } else {
                // 2. If no user FASTA, but we need one (e.g. for liftover target validation),
                // try to load standard reference for the TARGET assembly.
                // This mirrors how we load source reference, but for the target.
                match crate::source_ref::load_source_reference(&config.assembly) {
                    Ok(r) => {
                        set_auto_reference_metadata(&mut config, &r);
                        reference = Some(r);
                    }
                    Err(e) => {
                        // Only soft-fail here; hard failure happens below if it was strictly required.
                        tracing::debug!(
                            "Could not auto-load target reference for {}: {}",
                            config.assembly,
                            e
                        );
                    }
                }
            }
        }

        // Validate we have a reference if required (and not doing liftover, where we just loaded it)
        if reference.is_none() && requires_reference && liftover_chain.is_none() {
            return Err(anyhow!(
                "Reference FASTA (Target) is required for {} input or when using --standardize/--panel.
                Could not load standard reference for target assembly '{}'. Please provide --reference.",
                match config.input_format {
                    crate::input::InputFormat::Dtc => "DTC",
                    crate::input::InputFormat::GenomeStudio => "GenomeStudio",
                    _ => "this",
                },
                config.assembly
            ));
        }

        // Infer sex if not provided
        if config.sex.is_none() {
            let build_for_sex = inferred_build_opt.as_ref().unwrap_or(&config.assembly);
            tracing::info!(
                "Sex not specified, inferring from input data (assuming {})...",
                build_for_sex
            );
            match crate::inference::infer_sex_detail_from_records(&prescan_records, build_for_sex) {
                Ok(detail) => {
                    tracing::info!("Inferred sex: {:?}", detail.sex);
                    config.sex = Some(detail.sex);
                    sex_inferred = true;
                    sex_confidence = detail.composite_sex_index;
                    sex_y_genome_density = detail.y_genome_density;
                    sex_x_autosome_het_ratio = detail.x_autosome_het_ratio;
                }
                Err(e) => {
                    tracing::warn!("Sex inference failed: {}. Defaulting to Unknown.", e);
                    config.sex = Some(Sex::Unknown);
                    sex_inferred = true;
                }
            }
        }
    }

    if matches!(
        config.input_format,
        crate::input::InputFormat::Vcf | crate::input::InputFormat::Bcf
    ) {
        if let Some(declared) = config.input_build.clone() {
            // Caller asserted the source build; skip position-based detection.
            tracing::info!(
                "Build declared by caller: {}; skipping detection.",
                declared
            );
            build_detection = Some(crate::report::BuildDetection {
                detected_build: declared.clone(),
                hg19_match_rate: f64::NAN,
                hg38_match_rate: f64::NAN,
                // Caller-declared build: no detection was run, so no confidence.
                build_confidence: None,
            });

            if !builds_match(&declared, &config.assembly) {
                tracing::info!(
                    "Declared build {} differs from target {}. Initiating liftover.",
                    declared,
                    config.assembly
                );
                match ChainRegistry::new() {
                    Ok(registry) => match registry.get_chain(&declared, &config.assembly) {
                        Ok(chain) => {
                            liftover_chain = Some(Arc::new(chain));
                            config.standardize = true;
                        }
                        Err(e) => {
                            tracing::error!("Failed to load chain file: {}", e);
                        }
                    },
                    Err(e) => {
                        tracing::error!("Failed to initialize ChainRegistry: {}", e);
                    }
                }
            } else {
                tracing::info!("Declared build matches target assembly. No liftover needed.");
            }
        } else {
            tracing::info!("Detecting genome build using check_build (position-only)...");
            match crate::inference::detect_build_from_variant_file(
                &config.input,
                config.input_format,
            ) {
                Ok(Some(detection)) => {
                    tracing::info!("Detected input build: {}", detection.detected_build);
                    build_detection = Some(crate::report::BuildDetection {
                        detected_build: detection.detected_build.clone(),
                        hg19_match_rate: detection.hg19_match_rate,
                        hg38_match_rate: detection.hg38_match_rate,
                        build_confidence: detection.build_confidence(),
                    });

                    if !builds_match(&detection.detected_build, &config.assembly) {
                        tracing::info!(
                            "Detected build {} differs from target {}. Initiating liftover.",
                            detection.detected_build,
                            config.assembly
                        );

                        match ChainRegistry::new() {
                            Ok(registry) => {
                                match registry
                                    .get_chain(&detection.detected_build, &config.assembly)
                                {
                                    Ok(chain) => {
                                        let liftover_chain_local = Some(Arc::new(chain));
                                        liftover_chain = liftover_chain_local;
                                        // Force standardization for liftover workflow
                                        config.standardize = true;
                                    }
                                    Err(e) => {
                                        tracing::error!("Failed to load chain file: {}", e);
                                    }
                                }
                            }
                            Err(e) => {
                                tracing::error!("Failed to initialize ChainRegistry: {}", e);
                            }
                        }
                    } else {
                        tracing::info!("Build matches target assembly. No liftover needed.");
                    }
                }
                Ok(None) => {
                    tracing::warn!(
                        "No records available for build detection; skipping build inference"
                    );
                }
                Err(e) => {
                    return Err(anyhow!(
                        "Build detection failed: {}. Refusing to assume input matches target ({})",
                        e,
                        config.assembly
                    ));
                }
            }
        }

        if config.sex.is_none() {
            let build_for_sex = build_detection
                .as_ref()
                .map(|d| d.detected_build.as_str())
                .unwrap_or(&config.assembly);
            tracing::info!(
                "Sex not specified, inferring from variant input (assuming {})...",
                build_for_sex
            );
            match crate::inference::infer_sex_detail_from_variant_file(
                &config.input,
                config.input_format,
                build_for_sex,
            ) {
                Ok(detail) => {
                    tracing::info!("Inferred sex: {:?}", detail.sex);
                    config.sex = Some(detail.sex);
                    sex_inferred = true;
                    sex_confidence = detail.composite_sex_index;
                    sex_y_genome_density = detail.y_genome_density;
                    sex_x_autosome_het_ratio = detail.x_autosome_het_ratio;
                }
                Err(e) => {
                    tracing::warn!("Sex inference failed: {}. Defaulting to Unknown.", e);
                    config.sex = Some(Sex::Unknown);
                    sex_inferred = true;
                }
            }
        }
    }

    if liftover_chain.is_some() {
        requires_reference = true;
    }

    if !config.input_format.is_dtc_like() {
        if reference.is_none() && (config.reference_fasta.is_some() || requires_reference) {
            if let Some(ref fasta_path) = config.reference_fasta {
                reference = Some(
                    ReferenceGenome::open(fasta_path, config.reference_fai.clone())
                        .with_context(|| "failed to open reference genome")?,
                );
            } else if requires_reference {
                match crate::source_ref::load_source_reference(&config.assembly) {
                    Ok(r) => {
                        set_auto_reference_metadata(&mut config, &r);
                        reference = Some(r);
                    }
                    Err(e) => {
                        tracing::debug!(
                            "Could not auto-load target reference for {}: {}",
                            config.assembly,
                            e
                        );
                    }
                }
            }
        }

        if reference.is_none() && requires_reference {
            return Err(anyhow!(
                "Reference FASTA (Target) is required for this input or when using --standardize/--panel.
                Could not load standard reference for target assembly '{}'. Please provide --reference.",
                config.assembly
            ));
        }
    }

    // Load panel if provided
    let padded_panel: Option<parking_lot::Mutex<crate::panel::PaddedPanel>> =
        if let Some(panel_path) = &config.panel {
            tracing::info!(panel = %panel_path.display(), "loading reference panel");
            let panel_index = crate::panel::PanelIndex::load(panel_path)
                .with_context(|| format!("failed to load panel {}", panel_path.display()))?;
            if panel_index.is_empty() {
                return Err(anyhow!(
                    "Panel provided but no sites were loaded from {}",
                    panel_path.display()
                ));
            }
            tracing::info!(sites = panel_index.len(), "panel loaded");
            Some(parking_lot::Mutex::new(crate::panel::PaddedPanel::new(
                panel_index,
            )))
        } else {
            None
        };

    let input_header = match config.input_format {
        crate::input::InputFormat::Vcf => {
            let reader = crate::smart_reader::open_input(&config.input)
                .with_context(|| format!("failed to open input {}", config.input.display()))?;
            let mut vcf_reader = vcf::io::Reader::new(reader);
            Some(
                vcf_reader
                    .read_header()
                    .with_context(|| "failed to read VCF header")?,
            )
        }
        crate::input::InputFormat::Bcf => {
            let reader = crate::smart_reader::open_input(&config.input)
                .with_context(|| format!("failed to open input {}", config.input.display()))?;
            let mut bcf_reader = bcf::io::Reader::new(reader);
            Some(
                bcf_reader
                    .read_header()
                    .with_context(|| "failed to read BCF header")?,
            )
        }
        _ => None,
    };

    let header = build_header(&config, reference.as_ref(), input_header.as_ref())?;

    // Instantiate Source Iterator
    let mut source: Box<dyn crate::input::VariantSource> = match config.input_format {
        crate::input::InputFormat::Dtc | crate::input::InputFormat::GenomeStudio => {
            build_dtc_like_source(
                config.input_format,
                &config,
                &reference,
                liftover_chain.is_some(),
                inferred_strand,
            )?
        }
        crate::input::InputFormat::Vcf => {
            let reader = crate::smart_reader::open_input(&config.input)
                .with_context(|| format!("failed to open input {}", config.input.display()))?;
            let vcf_reader = vcf::io::Reader::new(reader);
            let source = if let Some(ref ref_genome) = reference {
                crate::input::VcfSource::new(vcf_reader, ref_genome)
                    .with_context(|| "failed to initialize VCF source")?
            } else {
                crate::input::VcfSource::new_without_reference(vcf_reader)
                    .with_context(|| "failed to initialize VCF source")?
            };
            Box::new(source)
        }
        crate::input::InputFormat::Bcf => {
            let reader = crate::smart_reader::open_input(&config.input)
                .with_context(|| format!("failed to open input {}", config.input.display()))?;
            let bcf_reader = bcf::io::Reader::new(reader);
            let source = if let Some(ref ref_genome) = reference {
                crate::input::BcfSource::new(bcf_reader, ref_genome)
                    .with_context(|| "failed to initialize BCF source")?
            } else {
                crate::input::BcfSource::new_without_reference(bcf_reader)
                    .with_context(|| "failed to initialize BCF source")?
            };
            Box::new(source)
        }
        crate::input::InputFormat::Auto => {
            // This should have been resolved by CLI, but if used as library, we might need to resolve it.
            let format = crate::input::InputFormat::detect(&config.input);
            match format {
                crate::input::InputFormat::Dtc | crate::input::InputFormat::GenomeStudio => {
                    build_dtc_like_source(
                        format,
                        &config,
                        &reference,
                        liftover_chain.is_some(),
                        inferred_strand,
                    )?
                }
                crate::input::InputFormat::Vcf => {
                    let reader =
                        crate::smart_reader::open_input(&config.input).with_context(|| {
                            format!("failed to open input {}", config.input.display())
                        })?;
                    let vcf_reader = vcf::io::Reader::new(reader);
                    let source = if let Some(ref ref_genome) = reference {
                        crate::input::VcfSource::new(vcf_reader, ref_genome)
                            .with_context(|| "failed to initialize VCF source")?
                    } else {
                        crate::input::VcfSource::new_without_reference(vcf_reader)
                            .with_context(|| "failed to initialize VCF source")?
                    };
                    Box::new(source)
                }
                crate::input::InputFormat::Bcf => {
                    let reader =
                        crate::smart_reader::open_input(&config.input).with_context(|| {
                            format!("failed to open input {}", config.input.display())
                        })?;
                    let bcf_reader = bcf::io::Reader::new(reader);
                    let source = if let Some(ref ref_genome) = reference {
                        crate::input::BcfSource::new(bcf_reader, ref_genome)
                            .with_context(|| "failed to initialize BCF source")?
                    } else {
                        crate::input::BcfSource::new_without_reference(bcf_reader)
                            .with_context(|| "failed to initialize BCF source")?
                    };
                    Box::new(source)
                }
                crate::input::InputFormat::Auto => {
                    return Err(anyhow!("Auto format detection failed recursively"));
                }
            }
        }
    };

    let needs_sort = liftover_chain.is_some() || config.standardize || config.panel.is_some();

    // Apply Liftover Adapter if active
    if let Some(chain) = liftover_chain {
        tracing::info!("Applying liftover adapter...");
        source = Box::new(LiftoverAdapter::new(
            source,
            chain,
            reference.clone().unwrap(),
            source_reference_for_liftover.clone(),
        ));
    }

    let mut summary = crate::ConversionSummary::default();

    match config.output_format {
        OutputFormat::Vcf => {
            let output = fs::File::create(&config.output)
                .with_context(|| format!("failed to create output {}", config.output.display()))?;
            let mut writer = vcf::io::Writer::new(io::BufWriter::new(output));
            writer
                .write_header(&header)
                .with_context(|| "failed to write VCF header")?;
            let ctx = ProcessingContext {
                reference: reference.as_ref(),
                header: &header,
                config: &config,
                panel: padded_panel.as_ref(),
                needs_sort,
            };
            process_records(source, &mut writer, &mut summary, ctx)?;
        }
        OutputFormat::Bcf => {
            let mut writer = bcf::io::writer::Builder::default()
                .build_from_path(&config.output)
                .with_context(|| format!("failed to create output {}", config.output.display()))?;
            writer
                .write_header(&header)
                .with_context(|| "failed to write BCF header")?;
            let ctx = ProcessingContext {
                reference: reference.as_ref(),
                header: &header,
                config: &config,
                panel: padded_panel.as_ref(),
                needs_sort,
            };
            process_records(source, &mut writer, &mut summary, ctx)?;
        }
        OutputFormat::Plink => {
            let mut writer =
                PlinkWriter::new(&config.output).context("failed to create PLINK writer")?;

            // Sex is normally filled by inference (which itself defaults to
            // Unknown on failure); default here too rather than panicking, so a
            // caller path that skipped inference still produces a valid FAM.
            writer
                .write_fam(&config.sample_id, config.sex.unwrap_or(Sex::Unknown))
                .context("failed to write FAM file")?;

            let ctx = ProcessingContext {
                reference: reference.as_ref(),
                header: &header,
                config: &config,
                panel: padded_panel.as_ref(),
                needs_sort,
            };
            process_records(source, &mut writer, &mut summary, ctx)?;
        }
    }

    // Write padded panel if we have one and output_dir is set
    if let (Some(panel), Some(output_dir)) = (&padded_panel, &config.output_dir) {
        let panel = panel.lock();
        if panel.modified_site_count() > 0 || panel.novel_site_count() > 0 {
            let panel_output = output_dir.join("panel.vcf");
            tracing::info!(
                path = %panel_output.display(),
                modified = panel.modified_site_count(),
                novel = panel.novel_site_count(),
                "writing padded panel"
            );

            if let Some(original_panel_path) = &config.panel {
                crate::panel_writer::write_padded_panel(original_panel_path, &panel, &panel_output)
                    .with_context(|| "failed to write padded panel")?;
            }
        } else {
            tracing::info!("no panel modifications needed, skipping padded panel output");
        }
    }

    // Build and write the run report
    let panel_info = padded_panel.as_ref().map(|p| {
        let panel = p.lock();
        crate::report::PanelInfo {
            path: config
                .panel
                .as_ref()
                .map(|p| p.display().to_string())
                .unwrap_or_default(),
            total_sites: panel.total_site_count(),
            modified_sites: panel.modified_site_count(),
            novel_sites: panel.novel_site_count(),
        }
    });

    // Use build_detection if available from previous steps
    // (Wait, I removed the usage locally in the previous `replace` attempt which was a mistake,
    //  but wait, `build_detection` is passed to `RunReportBuilder` below. Why did it warn?)

    // Ah, `let mut build_detection` was declared but not mutated in some paths?
    // Or maybe I just need to remove `mut`.

    // Capture the build-detection confidence before `build_detection` is moved
    // into the report builder, so the clinical-safety gate below can inspect it.
    // `None` means either no detection ran (caller asserted `--input-build`) or
    // there was no informative signal to compute a confidence from.
    let detected_confidence = build_detection
        .as_ref()
        .and_then(|d| d.build_confidence);

    let report_builder = crate::report::RunReportBuilder {
        input_path: config.input.display().to_string(),
        input_format: Some(config.input_format),
        input_origin: config.input_origin.clone(),
        output_path: config.output.display().to_string(),
        output_format: Some(config.output_format),
        reference_path: config
            .reference_fasta
            .as_ref()
            .map(|p| p.display().to_string())
            .unwrap_or_default(),
        reference_origin: config.reference_origin.clone().unwrap_or_default(),
        assembly: config.assembly.clone(),
        standardize: config.standardize,
        panel: panel_info,
        sample_id: config.sample_id.clone(),
        sex: config.sex,
        sex_inferred,
        sex_confidence,
        sex_y_genome_density,
        sex_x_autosome_het_ratio,
        build_detection,
    };
    let report = report_builder.build(&summary);
    if let Err(e) = report.write(&config.output) {
        tracing::warn!("Failed to write run report: {}", e);
    }

    enforce_clinical_safety_gates(&config, &summary, detected_confidence)?;

    Ok(summary)
}

/// Fail loud (return `Err`, i.e. nonzero exit) when a conversion produced output
/// that should not be trusted by a downstream clinical scorer.
///
/// Without these gates a malformed, empty, or wrong-build input exits `0` with
/// an empty / sparse / mis-parsed result, so garbage can silently flow into
/// clinical scoring with no error signal. Each gate is tunable via a CLI flag
/// (never an env var, per repo convention) and has a defensible default.
///
/// The gates fire in order of how diagnostic they are:
/// 1. **Parse-error ratio** — most of the input could not be parsed, so the
///    file is almost certainly the wrong format (binary data, a non-genome CSV
///    read as DTC, etc.).
/// 2. **Build confidence** — the coordinates match neither reference build
///    decisively, so silently assuming GRCh38 could score against the wrong
///    coordinates. Skipped when the caller asserted `--input-build`.
/// 3. **Minimum emitted variants** — a real genome/array yields tens of
///    thousands of variant sites; a handful (or zero) means empty/malformed
///    input or a mis-detected format.
fn enforce_clinical_safety_gates(
    config: &ConversionConfig,
    summary: &ConversionSummary,
    detected_confidence: Option<f64>,
) -> Result<()> {
    // Gate 1: parse-error ratio.
    let considered = summary.total_records + summary.parse_errors;
    if considered > 0 {
        let parse_error_ratio = summary.parse_errors as f64 / considered as f64;
        if parse_error_ratio > config.max_parse_error_ratio {
            return Err(anyhow!(
                "{:.1}% of input lines failed to parse ({} of {} considered), above the maximum \
                 of {:.1}% — input appears to be the wrong format (e.g. binary data or a \
                 non-genome CSV) and the output cannot be trusted. Pass --max-parse-error-ratio \
                 to override, or correct the input.",
                parse_error_ratio * 100.0,
                summary.parse_errors,
                considered,
                config.max_parse_error_ratio * 100.0,
            ));
        }
    }

    // Gate 2: build confidence. Only meaningful when position-based detection
    // actually ran; a caller-asserted `--input-build` yields `None` here and
    // deliberately bypasses this gate (the caller took responsibility).
    if config.input_build.is_none()
        && let Some(confidence) = detected_confidence
        && confidence < config.min_build_confidence
    {
        return Err(anyhow!(
            "could not confidently determine genome build (confidence {:.2} < {:.2}); the \
             coordinates match neither GRCh37 nor GRCh38 decisively. Refusing to silently \
             assume a build for clinical scoring. Re-run with an explicit --input-build, or \
             lower --min-build-confidence if you accept the risk.",
            confidence,
            config.min_build_confidence,
        ));
    }

    // Gate 3: minimum emitted variant records.
    if summary.variant_records < config.min_emitted_variants {
        return Err(anyhow!(
            "emitted {} variant records, below the minimum of {} — input appears \
             empty/malformed/unparseable and the output is not safe for clinical scoring. \
             Pass --min-emitted-variants to override if a small panel is expected.",
            summary.variant_records,
            config.min_emitted_variants,
        ));
    }

    Ok(())
}

struct ProcessingContext<'a> {
    reference: Option<&'a ReferenceGenome>,
    header: &'a vcf::Header,
    config: &'a ConversionConfig,
    panel: Option<&'a parking_lot::Mutex<crate::panel::PaddedPanel>>,
    needs_sort: bool,
}

/// Apply standardize + panel harmonization + normalize to a single record.
/// Returns Some(RecordBuf) if the record should be emitted, or None if filtered.
/// Updates `summary` counters for skips and standardization failures.
fn transform_record(
    record: RecordBuf,
    ctx: &ProcessingContext,
    summary: &mut crate::ConversionSummary,
    warned_unknown_chroms: &mut std::collections::HashSet<String>,
) -> Option<RecordBuf> {
    let mut final_record = if ctx.config.standardize {
        match standardize_record(
            &record,
            // Guaranteed Some: process_records bails up front when
            // standardize is set without a reference.
            ctx.reference
                .expect("reference presence is enforced up front in process_records"),
            ctx.config,
            summary,
            warned_unknown_chroms,
        ) {
            Ok(Some(standardized)) => standardized,
            Ok(None) => return None,
            Err(e) => {
                tracing::warn!(error = %e, "failed to standardize record, skipping");
                summary.reference_failures += 1;
                return None;
            }
        }
    } else {
        record
    };

    if let Some(panel_cell) = ctx.panel {
        let chrom = final_record.reference_sequence_name().to_string();
        let pos = final_record.variant_start().map(usize::from).unwrap_or(0) as u64;
        let ref_base = final_record.reference_bases().to_string();

        let record_alts: Vec<String> = final_record
            .alternate_bases()
            .as_ref()
            .iter()
            .map(|s| s.to_string())
            .collect();

        let mut all_input_alleles = vec![ref_base.clone()];
        all_input_alleles.extend(record_alts.iter().cloned());

        let mut panel_borrow = panel_cell.lock();
        let harmonized_indices = match crate::harmonize::harmonize_alleles(
            &all_input_alleles,
            &ref_base,
            &chrom,
            pos,
            &mut panel_borrow,
        ) {
            Ok(indices) => Some(indices),
            Err(e) => {
                tracing::debug!(
                    chrom = %chrom,
                    pos = pos,
                    error = %e,
                    "allele harmonization failed"
                );
                None
            }
        };

        if let Some(indices) = harmonized_indices {
            if let Some(site) = panel_borrow.get_original(&chrom, pos) {
                let record_ref_len = final_record.reference_bases().len();
                let panel_ref_len = site.ref_allele.len();
                let panel_alts_same_len = site
                    .alt_alleles
                    .iter()
                    .all(|alt| alt.len() == panel_ref_len);
                let record_alts_same_len = final_record
                    .alternate_bases()
                    .as_ref()
                    .iter()
                    .all(|alt| alt.len() == record_ref_len);

                let should_inject_panel_alts =
                    panel_ref_len == record_ref_len && panel_alts_same_len && record_alts_same_len;

                if should_inject_panel_alts {
                    let merged_alts = crate::harmonize::get_merged_alts(
                        site,
                        panel_borrow.added_alts(&site.chrom, pos),
                    );

                    let mut mapping = std::collections::HashMap::new();
                    for (old_idx, new_idx) in indices.iter().enumerate() {
                        mapping.insert(old_idx, *new_idx);
                    }

                    let samples = if mapping.iter().any(|(old, new)| old != new) {
                        remap_sample_genotypes(final_record.samples(), &mapping)
                    } else {
                        final_record.samples().clone()
                    };

                    let pos_val = match final_record.variant_start() {
                        Some(p) => p,
                        None => {
                            summary.reference_failures += 1;
                            return None;
                        }
                    };

                    let mut info = final_record.info().clone();
                    if merged_alts != record_alts {
                        let infos = ctx.header.infos();
                        info.as_mut().retain(|key, _| match infos.get(key) {
                            Some(definition) => !matches!(
                                definition.number(),
                                Number::AlternateBases | Number::ReferenceAlternateBases
                            ),
                            None => true,
                        });
                    }

                    let mut builder = RecordBuf::builder()
                        .set_reference_sequence_name(final_record.reference_sequence_name())
                        .set_variant_start(pos_val)
                        .set_ids(final_record.ids().clone())
                        .set_filters(final_record.filters().clone())
                        .set_reference_bases(final_record.reference_bases().to_string())
                        .set_info(info)
                        .set_alternate_bases(
                            noodles::vcf::variant::record_buf::AlternateBases::from(merged_alts),
                        )
                        .set_samples(samples);

                    if let Some(qual) = final_record.quality_score() {
                        builder = builder.set_quality_score(qual);
                    }

                    final_record = builder.build();
                }
            }
        }
    }

    normalize_record(&mut final_record);
    summary.record_emission(!final_record.alternate_bases().as_ref().is_empty());
    Some(final_record)
}

/// Upper bound on the number of raw input records pulled into RAM at once for
/// a parallel transform batch. This — together with the external sorter's
/// `RECORDBUF_CHUNK_SIZE` spill threshold — caps live `RecordBuf` residency to
/// a constant independent of genome size, so a dense WGS genome (~4M variants)
/// no longer materializes wholesale in RAM. Tuned so each rayon worker still
/// gets a meaty slice while keeping peak memory modest.
const TRANSFORM_BATCH_SIZE: usize = 16_384;

fn process_records<S, W>(
    mut source: S,
    writer: &mut W,
    summary: &mut crate::ConversionSummary,
    ctx: ProcessingContext,
) -> Result<()>
where
    S: crate::input::VariantSource,
    W: VariantWriter,
{
    let mut warned_unknown_chroms = std::collections::HashSet::new();

    // Standardization polarizes alleles against the reference, so it cannot run
    // without one. This is a configuration invariant (liftover, for instance,
    // forces standardize=true and is expected to have loaded a target
    // reference). Fail fast with an actionable message here rather than letting
    // `transform_record` panic once per record deep inside the hot loop.
    if ctx.config.standardize && ctx.reference.is_none() {
        bail!(
            "standardization is enabled but no reference genome is loaded; cannot \
             polarize alleles. If liftover was requested, the target-build reference \
             failed to load — supply it explicitly with --reference."
        );
    }

    let mut sorter = if ctx.needs_sort {
        let order = if let Some(reference) = ctx.reference {
            RecordOrder::from_reference(reference)
        } else {
            RecordOrder::Natural
        };
        let format = match ctx.config.output_format {
            OutputFormat::Bcf => SortFormat::Bcf,
            OutputFormat::Vcf | OutputFormat::Plink => SortFormat::Vcf,
        };
        Some(RecordExternalSorter::new(ctx.header.clone(), format, order))
    } else {
        None
    };

    // Transform records in parallel batches only when it is provably
    // order-independent: no panel (the panel path mutates shared state whose
    // mutation order is load-bearing) and a sorter is active (so the external
    // sort re-establishes emitted order regardless of transform order).
    // Otherwise transform serially in stream order. Either way memory stays
    // bounded — the sorter spills to disk every RECORDBUF_CHUNK_SIZE records,
    // and at most TRANSFORM_BATCH_SIZE raw records are held in RAM at a time.
    let parallel_transform =
        should_parallelize(ctx.config) && ctx.panel.is_none() && sorter.is_some();

    if parallel_transform {
        let mut batch: Vec<RecordBuf> = Vec::with_capacity(TRANSFORM_BATCH_SIZE);
        loop {
            batch.clear();
            let mut exhausted = false;
            while batch.len() < TRANSFORM_BATCH_SIZE {
                match source.next_variant(summary) {
                    Some(Ok(record)) => batch.push(record),
                    Some(Err(e)) => {
                        summary.parse_errors += 1;
                        tracing::warn!(error = %e, "failed to parse/convert input record");
                    }
                    None => {
                        exhausted = true;
                        break;
                    }
                }
            }

            if !batch.is_empty() {
                // Transform the batch in parallel; each record carries its own
                // summary delta and warned-chrom set so the merge below is
                // deterministic in input order (byte-identical to serial).
                let transformed: Vec<(
                    Option<RecordBuf>,
                    crate::ConversionSummary,
                    std::collections::HashSet<String>,
                )> = batch
                    .par_drain(..)
                    .map(|record| {
                        let mut local_summary = crate::ConversionSummary::default();
                        let mut local_warned = std::collections::HashSet::new();
                        let out =
                            transform_record(record, &ctx, &mut local_summary, &mut local_warned);
                        (out, local_summary, local_warned)
                    })
                    .collect();

                let sorter = sorter.as_mut().expect("sorter present for parallel path");
                for (final_record, delta, warned) in transformed {
                    merge_summary(summary, &delta);
                    warned_unknown_chroms.extend(warned);
                    if let Some(final_record) = final_record {
                        sorter
                            .push(final_record)
                            .context("failed to spill sorted records")?;
                    }
                }
            }

            if exhausted {
                break;
            }
        }
    } else {
        while let Some(result) = source.next_variant(summary) {
            match result {
                Ok(record) => {
                    let Some(final_record) =
                        transform_record(record, &ctx, summary, &mut warned_unknown_chroms)
                    else {
                        continue;
                    };

                    if let Some(sorter) = sorter.as_mut() {
                        sorter
                            .push(final_record)
                            .context("failed to spill sorted records")?;
                    } else {
                        writer
                            .write_variant(ctx.header, &final_record)
                            .context("failed to write variant record")?;
                    }
                }
                Err(e) => {
                    summary.parse_errors += 1;
                    tracing::warn!(error = %e, "failed to parse/convert input record");
                }
            }
        }
    }

    if let Some(sorter) = sorter {
        let mut sorted_records = sorter
            .finish()
            .context("failed to finalize external sorter")?;
        while let Some(record) = sorted_records.next() {
            let mut record = record.context("failed to read sorted spill record")?;
            normalize_record(&mut record);
            writer
                .write_variant(ctx.header, &record)
                .context("failed to write variant record")?;
        }
    }

    Ok(())
}

fn merge_summary(into: &mut crate::ConversionSummary, delta: &crate::ConversionSummary) {
    into.total_records += delta.total_records;
    into.emitted_records += delta.emitted_records;
    into.variant_records += delta.variant_records;
    into.reference_records += delta.reference_records;
    into.missing_genotype_records += delta.missing_genotype_records;
    into.skipped_reference_sites += delta.skipped_reference_sites;
    into.unknown_chromosomes += delta.unknown_chromosomes;
    into.reference_failures += delta.reference_failures;
    into.invalid_genotypes += delta.invalid_genotypes;
    into.symbolic_allele_records += delta.symbolic_allele_records;
    into.parse_errors += delta.parse_errors;
    into.liftover_unmapped += delta.liftover_unmapped;
    into.liftover_ambiguous += delta.liftover_ambiguous;
    into.liftover_incompatible += delta.liftover_incompatible;
    into.liftover_straddled += delta.liftover_straddled;
    into.liftover_contig_missing += delta.liftover_contig_missing;
}

/// Returns true if the parallel code path should be used.
fn should_parallelize(config: &ConversionConfig) -> bool {
    if rayon::current_num_threads() <= 1 {
        return false;
    }
    if std::env::var("CONVERT_GENOME_FORCE_SERIAL").ok().as_deref() == Some("1") {
        return false;
    }
    matches!(
        config.output_format,
        OutputFormat::Plink | OutputFormat::Vcf
    )
}

/// Normalizes and standardizes RecordBuf fields for VCF/BCF compatibility.
/// Handles empty string normalization, genotype string conversion, and enforces
/// correct data types for reserved keys like MQ (RMS mapping quality).
fn normalize_record(record: &mut RecordBuf) {
    // 1. Standardize INFO fields.
    // Site-level MQ must be a Float in VCF 4.3+. If input data provides it as
    // an Integer, we cast it to prevent writer definition mismatches.
    use noodles::vcf::variant::record_buf::info::field::Value as InfoValue;
    if let Some(value_opt) = record.info_mut().get_mut("MQ") {
        if let Some(InfoValue::Integer(n)) = value_opt {
            *value_opt = Some(InfoValue::Float(*n as f32));
        }
    }

    // 2. Standardize Sample (FORMAT) values.
    let keys = record.samples().keys().clone();
    let keys_len = keys.as_ref().len();
    if keys_len == 0 {
        return;
    }

    let mut needs_fix = false;
    let mut new_values = Vec::new();

    for sample in record.samples().values() {
        let values = sample.values();
        if values.len() != keys_len {
            needs_fix = true;
        }

        let mut filled = Vec::with_capacity(keys_len);
        for idx in 0..keys_len {
            let value = values.get(idx).cloned().unwrap_or(None);
            let key_name = keys
                .as_ref()
                .get_index(idx)
                .map(|s| s.as_str())
                .unwrap_or("");

            let cleaned = match value {
                Some(Value::String(ref s)) if s.is_empty() => {
                    needs_fix = true;
                    None
                }
                Some(Value::Genotype(ref gt)) => {
                    needs_fix = true;
                    Some(Value::String(genotype_to_string(gt)))
                }
                // Ensure sample-level MQ is an Integer as per VCF 4.5 specifications.
                Some(Value::Float(f)) if key_name == "MQ" => {
                    needs_fix = true;
                    Some(Value::Integer(f as i32))
                }
                other => other,
            };
            filled.push(cleaned);
        }
        new_values.push(filled);
    }

    if new_values.is_empty() {
        needs_fix = true;
        new_values.push(vec![None; keys_len]);
    }

    if needs_fix {
        *record.samples_mut() = Samples::new(keys, new_values);
    }
}

fn genotype_to_string(
    genotype: &noodles::vcf::variant::record_buf::samples::sample::value::Genotype,
) -> String {
    let alleles = genotype.as_ref();
    if alleles.is_empty() {
        return String::from(".");
    }

    let mut out = String::new();
    for (idx, allele) in alleles.iter().enumerate() {
        if idx > 0 {
            let sep = match allele.phasing() {
                Phasing::Phased => '|',
                Phasing::Unphased => '/',
            };
            out.push(sep);
        }
        match allele.position() {
            Some(pos) => out.push_str(&pos.to_string()),
            None => out.push('.'),
        }
    }
    out
}

// parse_genotype moved to dtc.rs

pub fn format_genotype(
    alleles: &[DtcAllele],
    reference_base: char,
    alt_bases: &[String],
) -> Result<String, String> {
    if alleles.is_empty() {
        return Err(String::from(""));
    }

    let codes: Vec<String> = alleles
        .iter()
        .map(|allele| match allele {
            DtcAllele::Missing => Ok(String::from(".")),
            DtcAllele::Base(base) => {
                if base == &reference_base.to_string() {
                    Ok(String::from("0"))
                } else if let Some((index, _)) =
                    alt_bases.iter().enumerate().find(|(_, alt)| *alt == base)
                {
                    Ok((index + 1).to_string())
                } else {
                    Err(base.clone())
                }
            }
            DtcAllele::Deletion => {
                if let Some((index, _)) =
                    alt_bases.iter().enumerate().find(|(_, alt)| *alt == "DEL")
                {
                    Ok((index + 1).to_string())
                } else {
                    Err(String::from("DEL"))
                }
            }
            DtcAllele::Insertion => {
                if let Some((index, _)) =
                    alt_bases.iter().enumerate().find(|(_, alt)| *alt == "INS")
                {
                    Ok((index + 1).to_string())
                } else {
                    Err(String::from("INS"))
                }
            }
        })
        .collect::<Result<_, _>>()?;

    if codes.len() == 1 {
        Ok(codes[0].clone())
    } else {
        Ok(codes.join("/"))
    }
}

#[derive(Debug, PartialEq, Eq)]
pub enum Ploidy {
    Haploid,
    Diploid,
    Zero,
}

pub fn determine_ploidy(
    chrom: &str,
    pos: u64,
    sex: Sex,
    boundaries: Option<&ParBoundaries>,
) -> Ploidy {
    let chrom_upper = chrom.to_ascii_uppercase();
    let short_chrom = chrom_upper.strip_prefix("CHR").unwrap_or(&chrom_upper);

    if short_chrom == "MT" || short_chrom == "M" {
        return Ploidy::Haploid;
    }

    match (short_chrom, sex) {
        (c, _) if c != "X" && c != "Y" => Ploidy::Diploid,
        ("X", Sex::Female) => Ploidy::Diploid,
        ("Y", Sex::Female) => Ploidy::Zero,
        ("X", Sex::Unknown) => Ploidy::Diploid,
        ("Y", Sex::Unknown) => Ploidy::Haploid,
        ("Y", Sex::Male) => {
            if let Some(b) = boundaries {
                if b.is_par(short_chrom, pos) {
                    Ploidy::Diploid
                } else {
                    Ploidy::Haploid
                }
            } else {
                Ploidy::Haploid
            }
        }
        ("X", Sex::Male) => {
            if let Some(b) = boundaries {
                if b.is_par(short_chrom, pos) {
                    Ploidy::Diploid
                } else {
                    Ploidy::Haploid
                }
            } else {
                Ploidy::Haploid
            }
        }
        _ => Ploidy::Diploid,
    }
}

/// Standardize a VCF record by:
/// 1. Normalizing chromosome name to canonical form
/// 2. Polarizing alleles against reference genome (swap REF/ALT if needed)
/// 3. Generating synthetic ID if missing
///
/// Returns the standardized record, or None if the record should be skipped.
pub fn standardize_record(
    record: &RecordBuf,
    reference: &ReferenceGenome,
    config: &ConversionConfig,
    summary: &mut crate::ConversionSummary,
    warned_unknown_chroms: &mut std::collections::HashSet<String>,
) -> Result<Option<RecordBuf>, RecordConversionError> {
    use noodles::vcf::variant::record_buf::{AlternateBases, Ids};

    let chrom = record.reference_sequence_name();
    let pos = record
        .variant_start()
        .map(|p| usize::from(p) as u64)
        .unwrap_or(0);

    // 1. Normalize chromosome name
    let canonical_name = match reference.resolve_contig_name(chrom) {
        Some(name) => name.to_string(),
        None => {
            summary.unknown_chromosomes += 1;
            if warned_unknown_chroms.insert(chrom.to_string()) {
                const WARN_LIMIT: usize = 5;
                let unique = warned_unknown_chroms.len();
                if unique <= WARN_LIMIT {
                    tracing::warn!("chromosome not in reference: {}", chrom);
                    if unique == WARN_LIMIT {
                        tracing::warn!("additional unknown chromosomes will be suppressed");
                    }
                }
            }
            return Ok(None);
        }
    };

    // 2. Get reference base at this position
    let ref_base = match reference.base(&canonical_name, pos) {
        Ok(base) => base.to_ascii_uppercase(),
        Err(e) => {
            tracing::warn!(
                "reference lookup failed at {}:{}: {}",
                canonical_name,
                pos,
                e
            );
            return Err(RecordConversionError::Reference {
                chromosome: canonical_name,
                position: pos,
                source: e,
            });
        }
    };

    let input_ref = record.reference_bases().to_uppercase();
    let ref_base_str = ref_base.to_string();

    // 3. Check if allele polarization is needed
    let (final_ref, final_alts, needs_remap) = if input_ref.len() == 1 && input_ref != ref_base_str
    {
        // Single-base REF doesn't match reference - need to polarize
        let alt_bases: Vec<String> = record
            .alternate_bases()
            .as_ref()
            .iter()
            .map(|s| s.to_string())
            .collect();

        // Check if reference base is in ALTs
        if let Some(flip_idx) = alt_bases.iter().position(|a| a == &ref_base_str) {
            // Swap: new REF = ref_base, new ALTs = [old_ref] + (old_alts - ref_base)
            let mut new_alts = vec![input_ref.clone()];
            let mut mapping = std::collections::HashMap::new();

            // Mapping Logic:
            // Old REF (Index 0) -> New Index 1 (it becomes the first ALT)
            mapping.insert(0, 1);

            // Old ALT that matches Reference (Index flip_idx + 1) -> New Index 0 (REF)
            mapping.insert(flip_idx + 1, 0);

            let mut next_new_idx = 2;
            for (i, alt) in alt_bases.iter().enumerate() {
                if i != flip_idx {
                    new_alts.push(alt.clone());
                    // Old ALT index was i + 1. New index is next_new_idx.
                    mapping.insert(i + 1, next_new_idx);
                    next_new_idx += 1;
                }
            }

            (ref_base_str.clone(), new_alts, Some(mapping))
        } else {
            // Cannot polarize - REF/ALT don't contain reference base
            tracing::warn!(
                "cannot polarize alleles at {}:{}: REF={} but reference={}, ALTs={:?}",
                canonical_name,
                pos,
                input_ref,
                ref_base_str,
                alt_bases
            );
            (input_ref.clone(), alt_bases, None)
        }
    } else {
        // REF matches or is multi-base (indel)
        // Validation: For Indels, check at least the first base matches reference
        // (VCF spec requires POS to be the position of the first base of REF)
        if input_ref.len() > 1 {
            let first_char = input_ref.chars().next().unwrap();
            let ref_first_char = ref_base_str.chars().next().unwrap(); // ref_base is usually single char from .base() call

            // Wait, reference.base() returns a single char at `pos`.
            // If input_ref="TGT", first base 'T' must match ref_base 'T'.
            if first_char != ref_first_char {
                tracing::warn!(
                    "Indel REF mismatch at {}:{}: user REF={} but reference base={}. Skipping.",
                    canonical_name,
                    pos,
                    input_ref,
                    ref_first_char
                );
                return Ok(None);
            }
        }

        let alt_bases: Vec<String> = record
            .alternate_bases()
            .as_ref()
            .iter()
            .map(|s| s.to_string())
            .collect();
        (input_ref.clone(), alt_bases, None)
    };

    // 4. Generate synthetic ID if missing
    let ids = if record.ids().as_ref().is_empty() {
        let alt_str = if final_alts.is_empty() {
            ".".to_string()
        } else {
            final_alts.join(",")
        };
        let synthetic_id = format!("{}:{}:{}:{}", canonical_name, pos, final_ref, alt_str);
        Ids::from_iter(vec![synthetic_id])
    } else {
        record.ids().clone()
    };

    // 5. Apply GT remapping if allele polarization occurred
    let samples = if let Some(mapping) = needs_remap {
        tracing::debug!(
            chrom = %canonical_name, pos = pos,
            "Allele polarization applied, remapping GT indices: {:?}", mapping
        );
        remap_sample_genotypes(record.samples(), &mapping)
    } else {
        record.samples().clone()
    };

    // 6. Check ploidy and enforce if needed
    let ploidy = determine_ploidy(
        &canonical_name,
        pos,
        config.sex.unwrap_or(Sex::Unknown),
        config.par_boundaries.as_ref(),
    );
    if ploidy == Ploidy::Zero {
        // Skip this record for this sex
        return Ok(None);
    }
    // Note: Haploid enforcement is already handled by the source for DTC files.
    // For VCF/BCF standardization, we preserve the original ploidy.

    // Build standardized record
    let pos_val = noodles::core::Position::new(pos as usize);
    let pos_val = match pos_val {
        Some(p) => p,
        None => return Ok(None), // Invalid position
    };

    let mut builder = RecordBuf::builder()
        .set_reference_sequence_name(canonical_name)
        .set_variant_start(pos_val)
        .set_ids(ids)
        .set_reference_bases(final_ref)
        .set_alternate_bases(AlternateBases::from(final_alts))
        .set_samples(samples);

    // Preserve quality and filters if present
    if let Some(qual) = record.quality_score() {
        builder = builder.set_quality_score(qual);
    }

    Ok(Some(builder.build()))
}

#[doc(hidden)]
pub fn format_genotype_for_tests(
    alleles: &[DtcAllele],
    reference_base: char,
    alt_bases: &[String],
) -> Result<String, String> {
    format_genotype(alleles, reference_base, alt_bases)
}

#[doc(hidden)]
pub fn parse_genotype_for_tests(raw: &str) -> Vec<DtcAllele> {
    parse_genotype(raw)
}

fn build_header(
    config: &ConversionConfig,
    reference: Option<&ReferenceGenome>,
    input_header: Option<&vcf::Header>,
) -> Result<vcf::Header> {
    let mut builder = vcf::Header::builder().set_file_format(FileFormat::new(4, 5));

    let genotype_format = Map::<Format>::from(format_key::GENOTYPE);
    builder = builder.add_format(format_key::GENOTYPE, genotype_format);

    // Add FORMAT fields that may be preserved during standardization
    use noodles::vcf::header::record::value::map::format::{Number as FmtNumber, Type as FmtType};
    builder = builder
        .add_format(
            "GQ",
            Map::<Format>::new(FmtNumber::Count(1), FmtType::Integer, "Genotype Quality"),
        )
        .add_format(
            "DP",
            Map::<Format>::new(FmtNumber::Count(1), FmtType::Integer, "Read Depth"),
        )
        .add_format(
            "MIN_DP",
            Map::<Format>::new(
                FmtNumber::Count(1),
                FmtType::Integer,
                "Minimum DP observed within the GVCF block",
            ),
        );

    // GenomeStudio Final Reports carry per-sample array metrics; declare the
    // FORMAT fields the DtcSource emits (see input::ARRAY_METRIC_KEYS) so the
    // values it writes are valid. Descriptions follow Illumina's terminology.
    if matches!(config.input_format, crate::input::InputFormat::GenomeStudio) {
        builder = builder
            .add_format(
                "BAF",
                Map::<Format>::new(
                    FmtNumber::Count(1),
                    FmtType::Float,
                    "B Allele Frequency (Illumina GenomeStudio)",
                ),
            )
            .add_format(
                "LRR",
                Map::<Format>::new(
                    FmtNumber::Count(1),
                    FmtType::Float,
                    "Log R Ratio (Illumina GenomeStudio)",
                ),
            )
            .add_format(
                "IGC",
                Map::<Format>::new(
                    FmtNumber::Count(1),
                    FmtType::Float,
                    "Illumina GenCall confidence score",
                ),
            )
            .add_format(
                "GTS",
                Map::<Format>::new(
                    FmtNumber::Count(1),
                    FmtType::Float,
                    "Illumina GenTrain cluster-quality score",
                ),
            );
    }

    // Add symbolic alleles for Indels as per VCF spec
    builder = builder
        .add_alternative_allele("DEL", Map::<AlternativeAllele>::new("Deletion"))
        .add_alternative_allele("INS", Map::<AlternativeAllele>::new("Insertion"))
        .add_info(
            "IMPRECISE",
            Map::<InfoMap>::new(
                Number::Count(0),
                Type::Flag,
                "Imprecise structural variation",
            ),
        )
        .add_info(
            "SVTYPE",
            Map::<InfoMap>::new(
                Number::Count(1),
                Type::String,
                "Type of structural variation",
            ),
        )
        // Explicitly define MQ fields to ensure consistency with strict VCF/BCF writers.
        // As of VCF 4.3, site-level INFO MQ is defined as Float.
        .add_info(
            "MQ",
            Map::<InfoMap>::new(Number::Count(1), Type::Float, "RMS mapping quality"),
        )
        // Sample-level FORMAT MQ is defined as Integer in VCF 4.5.
        .add_format(
            "MQ",
            Map::<Format>::new(FmtNumber::Count(1), FmtType::Integer, "RMS mapping quality"),
        );

    // Add contigs from reference if available
    if let Some(ref_genome) = reference {
        for contig in ref_genome.contigs() {
            let mut contig_map = Map::<Contig>::new();
            if let Ok(length) = usize::try_from(contig.length) {
                *contig_map.length_mut() = Some(length);
            }
            builder = builder.add_contig(contig.name.clone(), contig_map);
        }
    }

    builder = builder.add_sample_name(config.sample_id.clone());

    let mut header = builder.build();

    if let Some(input_header) = input_header {
        for (id, format) in input_header.formats() {
            if !header.formats().contains_key(id) {
                header.formats_mut().insert(id.clone(), format.clone());
            }
        }

        for (id, info) in input_header.infos() {
            if !header.infos().contains_key(id) {
                header.infos_mut().insert(id.clone(), info.clone());
            }
        }

        for (id, filter) in input_header.filters() {
            if !header.filters().contains_key(id) {
                header.filters_mut().insert(id.clone(), filter.clone());
            }
        }
    }

    insert_other_record(
        &mut header,
        "source",
        format!("convert_genome {}", env!("CARGO_PKG_VERSION")),
    )?;

    if !config.assembly.is_empty() {
        insert_other_record(&mut header, "assembly", config.assembly.clone())?;
    }

    let reference_uri = if config
        .reference_origin
        .as_ref()
        .map(|s| is_remote_source(s))
        .unwrap_or(false)
    {
        config.reference_origin.clone().unwrap_or_default()
    } else {
        config
            .reference_fasta
            .as_ref()
            .map(|p| format!("file://{}", p.display()))
            .unwrap_or_else(|| "none".to_string())
    };
    insert_other_record(&mut header, "reference", reference_uri)?;

    let date_format = format_description!("%Y%m%d");
    let today = OffsetDateTime::now_utc()
        .format(&date_format)
        .unwrap_or_else(|_| String::from("19700101"));
    insert_other_record(&mut header, "fileDate", today)?;

    Ok(header)
}

fn insert_other_record(header: &mut vcf::Header, key: &str, value: String) -> Result<()> {
    let key: key::Other = key
        .parse()
        .map_err(|e| anyhow!("invalid header key {key}: {e}"))?;
    header
        .other_records_mut()
        .insert(key, Collection::Unstructured(vec![value]));
    Ok(())
}

fn is_remote_source(raw: &str) -> bool {
    raw.contains("://")
}

#[cfg(test)]
mod tests {
    use super::*;
    use assert_fs::prelude::*;

    #[test]
    fn genotype_parsing() {
        assert_eq!(
            parse_genotype("AA"),
            vec![
                DtcAllele::Base("A".to_string()),
                DtcAllele::Base("A".to_string())
            ]
        );
        assert_eq!(
            parse_genotype("A-"),
            vec![DtcAllele::Base("A".to_string()), DtcAllele::Missing]
        );
        assert_eq!(
            parse_genotype("A/AG"),
            vec![
                DtcAllele::Base("A".to_string()),
                DtcAllele::Base("AG".to_string())
            ]
        );
        assert_eq!(
            parse_genotype("--"),
            vec![DtcAllele::Missing, DtcAllele::Missing]
        );
        assert_eq!(
            parse_genotype("DI"),
            vec![DtcAllele::Deletion, DtcAllele::Insertion]
        );
        assert_eq!(
            parse_genotype("00"),
            vec![DtcAllele::Missing, DtcAllele::Missing]
        );
        assert_eq!(
            parse_genotype("??"),
            vec![DtcAllele::Missing, DtcAllele::Missing]
        );
    }

    #[test]
    fn format_genotype_strings() {
        assert_eq!(
            format_genotype(
                &[
                    DtcAllele::Base("A".to_string()),
                    DtcAllele::Base("C".to_string())
                ],
                'A',
                &[String::from("C")]
            )
            .unwrap(),
            "0/1"
        );
        assert_eq!(
            format_genotype(
                &[
                    DtcAllele::Base("T".to_string()),
                    DtcAllele::Base("T".to_string())
                ],
                'A',
                &[String::from("T")]
            )
            .unwrap(),
            "1/1"
        );

        assert_eq!(
            format_genotype(&[DtcAllele::Missing, DtcAllele::Missing], 'A', &[]).unwrap(),
            "./."
        );
        assert_eq!(
            format_genotype(
                &[DtcAllele::Base("G".to_string()), DtcAllele::Deletion],
                'G',
                &[String::from("DEL")]
            )
            .unwrap(),
            "0/1"
        );
    }

    #[test]
    fn test_vcf_header_symbolic_alleles() {
        use std::io::Write;

        // Setup temp reference
        let dir = tempfile::tempdir().unwrap();
        let ref_path = dir.path().join("ref.fa");
        {
            let mut file = std::fs::File::create(&ref_path).unwrap();
            writeln!(file, ">1\nACGT").unwrap();
        }

        let reference = crate::reference::ReferenceGenome::open(&ref_path, None).unwrap();
        let config = ConversionConfig {
            input: std::path::PathBuf::from("dummy.txt"),
            input_format: crate::input::InputFormat::Dtc,
            input_origin: "test_input.txt".into(),
            reference_fasta: Some(ref_path.clone()),
            reference_origin: Some("dummy_ref".to_string()),
            reference_fai: None,
            reference_fai_origin: None,
            output: dir.path().join("out.vcf"),
            output_dir: None,
            output_format: OutputFormat::Vcf,
            sample_id: "SAMPLE".to_string(),
            assembly: "GRCh38".to_string(),
            include_reference_sites: true,
            sex: Some(Sex::Female),
            par_boundaries: None,
            standardize: false,
            panel: None,
            input_build: None,
            min_emitted_variants: 0,
            min_build_confidence: 0.0,
            max_parse_error_ratio: 1.0,
        };

        let header = build_header(&config, Some(&reference), None).unwrap();

        // Write header to string
        let mut buf = Vec::new();
        let mut writer = noodles::vcf::io::Writer::new(&mut buf);
        writer.write_header(&header).unwrap();
        let output = String::from_utf8(buf).unwrap();

        assert!(output.contains("##ALT=<ID=DEL,Description=\"Deletion\">"));
        assert!(output.contains("##ALT=<ID=INS,Description=\"Insertion\">"));
    }

    #[test]
    fn build_header_sets_contigs_and_metadata() {
        let temp = assert_fs::TempDir::new().unwrap();
        let fasta_path = temp.child("ref.fa");
        fasta_path.write_str(">1\nACGT\n").unwrap();

        let reference = ReferenceGenome::open(fasta_path.path(), None).unwrap();
        let config = ConversionConfig {
            input: PathBuf::from("input.txt"),
            input_format: crate::input::InputFormat::Dtc,
            input_origin: String::from("input.txt"),
            reference_fasta: Some(fasta_path.path().to_path_buf()),
            reference_origin: Some(fasta_path.path().to_string_lossy().to_string()),
            reference_fai: None,
            reference_fai_origin: None,
            output: PathBuf::from("out.vcf"),
            output_dir: None,
            output_format: OutputFormat::Vcf,
            sample_id: String::from("sample"),
            assembly: String::from("GRCh38"),
            include_reference_sites: true,
            sex: Some(Sex::Female),
            par_boundaries: None,
            standardize: false,
            panel: None,
            input_build: None,
            min_emitted_variants: 0,
            min_build_confidence: 0.0,
            max_parse_error_ratio: 1.0,
        };

        let header = build_header(&config, Some(&reference), None).unwrap();
        assert!(!header.contigs().is_empty());
        assert!(header.other_records().contains_key("source"));
        assert!(header.other_records().contains_key("reference"));
    }

    #[test]
    fn determine_ploidy_handles_unknown_sex() {
        assert_eq!(
            determine_ploidy("1", 100, Sex::Unknown, None),
            Ploidy::Diploid
        );
        assert_eq!(
            determine_ploidy("X", 100, Sex::Unknown, None),
            Ploidy::Diploid
        );
        assert_eq!(
            determine_ploidy("Y", 100, Sex::Unknown, None),
            Ploidy::Haploid
        );
    }

    /// A config whose safety gates are all set to the production defaults, so
    /// the gate unit tests exercise the real thresholds rather than placeholder
    /// values. Paths are dummies; `enforce_clinical_safety_gates` does no I/O.
    fn config_with_default_gates() -> ConversionConfig {
        ConversionConfig {
            input: PathBuf::from("dummy.txt"),
            input_format: crate::input::InputFormat::Dtc,
            input_origin: "dummy".into(),
            reference_fasta: None,
            reference_origin: None,
            reference_fai: None,
            reference_fai_origin: None,
            output: PathBuf::from("out.vcf"),
            output_dir: None,
            output_format: OutputFormat::Vcf,
            sample_id: "SAMPLE".into(),
            assembly: "GRCh38".into(),
            include_reference_sites: true,
            sex: Some(Sex::Female),
            par_boundaries: None,
            standardize: false,
            panel: None,
            input_build: None,
            min_emitted_variants: DEFAULT_MIN_EMITTED_VARIANTS,
            min_build_confidence: DEFAULT_MIN_BUILD_CONFIDENCE,
            max_parse_error_ratio: DEFAULT_MAX_PARSE_ERROR_RATIO,
        }
    }

    fn summary_with(variant_records: usize, total: usize, parse_errors: usize) -> ConversionSummary {
        let mut s = ConversionSummary::default();
        s.variant_records = variant_records;
        s.total_records = total;
        s.parse_errors = parse_errors;
        s
    }

    #[test]
    fn gate_passes_for_a_healthy_conversion() {
        let config = config_with_default_gates();
        // Plenty of variants, no parse errors, confident build.
        let summary = summary_with(600_000, 600_000, 0);
        assert!(enforce_clinical_safety_gates(&config, &summary, Some(0.98)).is_ok());
    }

    #[test]
    fn gate_rejects_empty_output() {
        let config = config_with_default_gates();
        // Zero emitted variants (empty / header-only input).
        let summary = summary_with(0, 0, 0);
        let err = enforce_clinical_safety_gates(&config, &summary, Some(0.98)).unwrap_err();
        assert!(
            err.to_string().contains("below the minimum"),
            "unexpected: {err}"
        );
    }

    #[test]
    fn gate_rejects_sparse_output() {
        let config = config_with_default_gates();
        // A handful of variants, well under the floor.
        let summary = summary_with(12, 12, 0);
        let err = enforce_clinical_safety_gates(&config, &summary, Some(0.98)).unwrap_err();
        assert!(err.to_string().contains("emitted 12 variant records"));
    }

    #[test]
    fn gate_rejects_high_parse_error_ratio() {
        let config = config_with_default_gates();
        // 900 of 1000 lines unparseable (binary garbage / wrong-format CSV).
        // Even with enough variants, the parse-error gate must fire first.
        let summary = summary_with(2_000, 100, 900);
        let err = enforce_clinical_safety_gates(&config, &summary, Some(0.98)).unwrap_err();
        assert!(err.to_string().contains("failed to parse"), "unexpected: {err}");
    }

    #[test]
    fn gate_rejects_low_build_confidence() {
        let config = config_with_default_gates();
        let summary = summary_with(600_000, 600_000, 0);
        // Coordinates match neither build decisively (≈ tie).
        let err = enforce_clinical_safety_gates(&config, &summary, Some(0.50)).unwrap_err();
        assert!(
            err.to_string().contains("could not confidently determine genome build"),
            "unexpected: {err}"
        );
    }

    #[test]
    fn build_confidence_gate_is_bypassed_by_explicit_input_build() {
        let mut config = config_with_default_gates();
        config.input_build = Some("GRCh37".into());
        let summary = summary_with(600_000, 600_000, 0);
        // Low confidence is ignored because the caller asserted the build.
        assert!(enforce_clinical_safety_gates(&config, &summary, Some(0.10)).is_ok());
        // And None confidence (no detection ran) is also fine.
        assert!(enforce_clinical_safety_gates(&config, &summary, None).is_ok());
    }

    #[test]
    fn parse_error_gate_allows_a_few_bad_lines() {
        let config = config_with_default_gates();
        // 5 bad lines out of ~600k is well under the 50% ceiling.
        let summary = summary_with(600_000, 600_000, 5);
        assert!(enforce_clinical_safety_gates(&config, &summary, Some(0.98)).is_ok());
    }

    #[test]
    fn gates_are_tunable_to_accept_a_small_panel() {
        let mut config = config_with_default_gates();
        config.min_emitted_variants = 10;
        config.min_build_confidence = 0.0;
        let summary = summary_with(50, 50, 0);
        assert!(enforce_clinical_safety_gates(&config, &summary, Some(0.51)).is_ok());
    }
}