{}.tmp

// Copyright © 2026 NexVigilant LLC. All Rights Reserved.
// Intellectual Property of Matthew Alexander Campion, PharmD

//! Error types for the phenotype system.
//!
//! ## Primitive Grounding: ∂ (Boundary) + Σ (Sum)
//!
//! Errors define boundaries between valid and invalid mutation states.
//! The error enum is a sum type (Σ) of all possible failure modes.

use nexcore_error::Error;

/// Phenotype system errors.
///
/// ## Tier: T2-P (∂ + Σ)
#[derive(Debug, Error)]
pub enum PhenotypeError {
    /// Mutation could not be applied to the given schema.
    #[error("mutation failed for {mutation}: {reason}")]
    MutationFailed {
        /// The mutation that failed.
        mutation: String,
        /// Why it failed.
        reason: String,
    },

    /// Verification against ribosome failed.
    #[error("verification error: {0}")]
    VerificationError(String),

    /// Invalid schema provided for mutation.
    #[error("invalid schema: {0}")]
    InvalidSchema(String),
}

/// Result type for phenotype operations.
pub type PhenotypeResult<T> = Result<T, PhenotypeError>;
//! # Harm Synthesis — PV-Domain Adversarial Test Generation
//!
//! Extends the phenotype mutation engine with pharmacovigilance-specific
//! harm scenarios. Generates adversarial test fixtures that simulate
//! real-world data integrity failures in drug safety records.
//!
//! ## Innovation Scan 001 — Goal 4 (Score: 7.85)
//!
//! ```text
//! HarmScenario → PvHarmMutation → Phenotype { data, expected_drifts }
//!                                      ↓
//!                      pv_contracts::evaluate_drift → PvDriftAction
//! ```
//!
//! ## ToV Alignment: V4 Safety Manifold
//! d(s) > 0 — these mutations simulate the exact failure modes that
//! threaten patient safety, ensuring detection systems catch them.
//!
//! ## Tier: T2-C (∂ + μ + κ + N + →)

use nexcore_ribosome::DriftType;
use serde::{Deserialize, Serialize};

// ─── Harm Scenarios ──────────────────────────────────────────────────────────

/// PV-domain harm scenarios that map to real-world data integrity failures.
///
/// Each scenario represents a specific way drug safety data can be
/// corrupted, mislabeled, or manipulated — and what detection systems
/// should catch.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum HarmScenario {
    /// Adverse event term replaced with a less severe synonym.
    /// Example: "hepatotoxicity" → "nausea" (severity downgrade).
    /// Impact: Underreporting of serious adverse events.
    SeverityDowngrade,

    /// Seriousness criteria fields removed or set to false.
    /// Example: `is_serious: true` → field missing.
    /// Impact: Serious cases not flagged for expedited reporting.
    MissingSeriousness,

    /// Drug name altered to a different substance.
    /// Example: "warfarin" → "aspirin" (attribution error).
    /// Impact: Signal attributed to wrong drug.
    DrugMisattribution,

    /// Case count artificially reduced.
    /// Example: `case_count: 47` → `case_count: 3`.
    /// Impact: PRR/ROR denominator manipulation, signal suppression.
    CaseCountDeflation,

    /// Duplicate records injected with slightly different keys.
    /// Example: Same case, different `case_id` values.
    /// Impact: Artificially inflated signal strength.
    DuplicateInjection,

    /// Narrative/description field truncated below useful length.
    /// Example: 500-char narrative → 10-char stub.
    /// Impact: Loss of clinical context for causality assessment.
    NarrativeTruncation,

    /// Reporting date shifted to avoid time-based signal windows.
    /// Example: `report_date: 2025-01-15` → `report_date: 2023-01-15`.
    /// Impact: Case excluded from temporal signal analysis.
    TemporalShift,

    /// Outcome field changed to mask fatal outcomes.
    /// Example: `outcome: "death"` → `outcome: "recovered"`.
    /// Impact: Fatal cases invisible in mortality signal detection.
    OutcomeMasking,
}

impl HarmScenario {
    /// All available harm scenarios.
    pub const ALL: &[Self] = &[
        Self::SeverityDowngrade,
        Self::MissingSeriousness,
        Self::DrugMisattribution,
        Self::CaseCountDeflation,
        Self::DuplicateInjection,
        Self::NarrativeTruncation,
        Self::TemporalShift,
        Self::OutcomeMasking,
    ];

    /// Which drift types this scenario should trigger in the ribosome.
    #[must_use]
    pub fn expected_drift_types(self) -> Vec<DriftType> {
        match self {
            Self::SeverityDowngrade
            | Self::DrugMisattribution
            | Self::TemporalShift
            | Self::OutcomeMasking => vec![DriftType::TypeMismatch],
            Self::MissingSeriousness => vec![DriftType::MissingField],
            Self::CaseCountDeflation => vec![DriftType::RangeContraction],
            Self::DuplicateInjection => vec![DriftType::ExtraField, DriftType::ArraySizeChange],
            Self::NarrativeTruncation => vec![DriftType::LengthChange],
        }
    }

    /// Patient safety impact level (1-5).
    /// 5 = directly threatens patient life.
    #[must_use]
    pub const fn safety_impact(&self) -> u8 {
        match self {
            Self::OutcomeMasking => 5,
            Self::SeverityDowngrade | Self::MissingSeriousness | Self::DrugMisattribution => 4,
            Self::CaseCountDeflation | Self::TemporalShift => 3,
            Self::DuplicateInjection | Self::NarrativeTruncation => 2,
        }
    }

    /// Human-readable label.
    #[must_use]
    pub const fn label(&self) -> &'static str {
        match self {
            Self::SeverityDowngrade => "Severity Downgrade",
            Self::MissingSeriousness => "Missing Seriousness",
            Self::DrugMisattribution => "Drug Misattribution",
            Self::CaseCountDeflation => "Case Count Deflation",
            Self::DuplicateInjection => "Duplicate Injection",
            Self::NarrativeTruncation => "Narrative Truncation",
            Self::TemporalShift => "Temporal Shift",
            Self::OutcomeMasking => "Outcome Masking",
        }
    }
}

impl std::fmt::Display for HarmScenario {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.label())
    }
}

// ─── PV Harm Mutation ────────────────────────────────────────────────────────

/// A PV-domain mutation with full traceability.
///
/// Records exactly what was changed, why, and what the detection
/// system should flag.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PvHarmMutation {
    /// Which harm scenario this mutation simulates.
    pub scenario: HarmScenario,
    /// Which field was targeted.
    pub target_field: String,
    /// Original value (before mutation).
    pub original_value: serde_json::Value,
    /// Mutated value (after mutation).
    pub mutated_value: serde_json::Value,
    /// Expected patient safety impact (1-5).
    pub safety_impact: u8,
    /// Expected drift types the ribosome should detect.
    pub expected_drifts: Vec<DriftType>,
}

// ─── PV Harm Phenotype ───────────────────────────────────────────────────────

/// A PV-domain phenotype: mutated drug safety record with harm metadata.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PvHarmPhenotype {
    /// The mutated FAERS-like record.
    pub data: serde_json::Value,
    /// All harm mutations applied.
    pub mutations: Vec<PvHarmMutation>,
    /// Aggregate safety impact (max of all mutations).
    pub max_safety_impact: u8,
}

// ─── Baseline Record ─────────────────────────────────────────────────────────

/// Generate a baseline FAERS-like drug safety record.
///
/// This represents a "healthy" record with all fields present and valid.
/// Mutations are applied against this baseline.
#[must_use]
pub fn baseline_drug_record() -> serde_json::Value {
    serde_json::json!({
        "case_id": "CASE-2025-00001",
        "report_date": "2025-06-15",
        "drug_name": "warfarin",
        "drug_role": "primary_suspect",
        "indication": "atrial_fibrillation",
        "adverse_event": "hepatotoxicity",
        "adverse_event_code": "10019851",
        "is_serious": true,
        "seriousness_criteria": {
            "death": false,
            "life_threatening": true,
            "hospitalization": true,
            "disability": false,
            "congenital_anomaly": false,
            "other_medically_important": true
        },
        "outcome": "hospitalization",
        "case_count": 47,
        "reporter_type": "healthcare_professional",
        "narrative": "A 67-year-old male patient on warfarin therapy for atrial fibrillation presented with elevated liver enzymes (ALT 5x ULN, AST 4x ULN) after 3 weeks of treatment. Warfarin was discontinued and liver function returned to normal within 2 weeks. Positive dechallenge supports causal relationship.",
        "age": 67,
        "sex": "male",
        "weight_kg": 82.5
    })
}

// ─── Harm Synthesis Engine ───────────────────────────────────────────────────

/// Apply a single harm scenario to a baseline record.
///
/// Returns a `PvHarmPhenotype` with the mutation applied and full
/// traceability metadata.
#[must_use]
pub fn synthesize_harm(baseline: &serde_json::Value, scenario: HarmScenario) -> PvHarmPhenotype {
    let mut data = baseline.clone();
    let mutation = apply_harm_mutation(&mut data, scenario);
    let safety_impact = mutation.safety_impact;

    PvHarmPhenotype {
        data,
        mutations: vec![mutation],
        max_safety_impact: safety_impact,
    }
}

/// Apply all harm scenarios to a baseline record, producing one phenotype each.
#[must_use]
pub fn synthesize_all_harms(baseline: &serde_json::Value) -> Vec<PvHarmPhenotype> {
    HarmScenario::ALL
        .iter()
        .map(|s| synthesize_harm(baseline, *s))
        .collect()
}

/// Apply multiple harm scenarios to a single record (compound mutation).
///
/// Produces a single record with multiple mutations — simulates
/// sophisticated data manipulation.
#[must_use]
pub fn synthesize_compound_harm(
    baseline: &serde_json::Value,
    scenarios: &[HarmScenario],
) -> PvHarmPhenotype {
    let mut data = baseline.clone();
    let mut mutations = Vec::with_capacity(scenarios.len());
    let mut max_impact = 0u8;

    for scenario in scenarios {
        let mutation = apply_harm_mutation(&mut data, *scenario);
        if mutation.safety_impact > max_impact {
            max_impact = mutation.safety_impact;
        }
        mutations.push(mutation);
    }

    PvHarmPhenotype {
        data,
        mutations,
        max_safety_impact: max_impact,
    }
}

/// Core dispatch: apply a specific harm mutation to a mutable JSON value.
fn apply_harm_mutation(data: &mut serde_json::Value, scenario: HarmScenario) -> PvHarmMutation {
    match scenario {
        HarmScenario::SeverityDowngrade => severity_downgrade(data),
        HarmScenario::MissingSeriousness => missing_seriousness(data),
        HarmScenario::DrugMisattribution => drug_misattribution(data),
        HarmScenario::CaseCountDeflation => case_count_deflation(data),
        HarmScenario::DuplicateInjection => duplicate_injection(data),
        HarmScenario::NarrativeTruncation => narrative_truncation(data),
        HarmScenario::TemporalShift => temporal_shift(data),
        HarmScenario::OutcomeMasking => outcome_masking(data),
    }
}

// ─── Mutation Implementations ────────────────────────────────────────────────

fn severity_downgrade(data: &mut serde_json::Value) -> PvHarmMutation {
    let original = data
        .get("adverse_event")
        .cloned()
        .unwrap_or(serde_json::Value::Null);

    // Replace serious AE term with a mild one
    if let Some(obj) = data.as_object_mut() {
        obj.insert("adverse_event".to_string(), serde_json::json!("nausea"));
        obj.insert(
            "adverse_event_code".to_string(),
            serde_json::json!("10028813"),
        );
    }

    PvHarmMutation {
        scenario: HarmScenario::SeverityDowngrade,
        target_field: "adverse_event".to_string(),
        original_value: original,
        mutated_value: serde_json::json!("nausea"),
        safety_impact: HarmScenario::SeverityDowngrade.safety_impact(),
        expected_drifts: HarmScenario::SeverityDowngrade.expected_drift_types(),
    }
}

fn missing_seriousness(data: &mut serde_json::Value) -> PvHarmMutation {
    let original = data
        .get("is_serious")
        .cloned()
        .unwrap_or(serde_json::Value::Null);

    // Remove seriousness-related fields
    if let Some(obj) = data.as_object_mut() {
        obj.remove("is_serious");
        obj.remove("seriousness_criteria");
    }

    PvHarmMutation {
        scenario: HarmScenario::MissingSeriousness,
        target_field: "is_serious".to_string(),
        original_value: original,
        mutated_value: serde_json::Value::Null,
        safety_impact: HarmScenario::MissingSeriousness.safety_impact(),
        expected_drifts: HarmScenario::MissingSeriousness.expected_drift_types(),
    }
}

fn drug_misattribution(data: &mut serde_json::Value) -> PvHarmMutation {
    let original = data
        .get("drug_name")
        .cloned()
        .unwrap_or(serde_json::Value::Null);

    if let Some(obj) = data.as_object_mut() {
        obj.insert("drug_name".to_string(), serde_json::json!("aspirin"));
    }

    PvHarmMutation {
        scenario: HarmScenario::DrugMisattribution,
        target_field: "drug_name".to_string(),
        original_value: original,
        mutated_value: serde_json::json!("aspirin"),
        safety_impact: HarmScenario::DrugMisattribution.safety_impact(),
        expected_drifts: HarmScenario::DrugMisattribution.expected_drift_types(),
    }
}

fn case_count_deflation(data: &mut serde_json::Value) -> PvHarmMutation {
    let original = data
        .get("case_count")
        .cloned()
        .unwrap_or(serde_json::Value::Null);

    if let Some(obj) = data.as_object_mut() {
        obj.insert("case_count".to_string(), serde_json::json!(1));
    }

    PvHarmMutation {
        scenario: HarmScenario::CaseCountDeflation,
        target_field: "case_count".to_string(),
        original_value: original,
        mutated_value: serde_json::json!(1),
        safety_impact: HarmScenario::CaseCountDeflation.safety_impact(),
        expected_drifts: HarmScenario::CaseCountDeflation.expected_drift_types(),
    }
}

fn duplicate_injection(data: &mut serde_json::Value) -> PvHarmMutation {
    let original = data
        .get("case_id")
        .cloned()
        .unwrap_or(serde_json::Value::Null);

    // Add a duplicate_cases array to simulate injection
    if let Some(obj) = data.as_object_mut() {
        obj.insert(
            "duplicate_cases".to_string(),
            serde_json::json!([
                "CASE-2025-00001-DUP1",
                "CASE-2025-00001-DUP2",
                "CASE-2025-00001-DUP3"
            ]),
        );
        obj.insert("_injected_flag".to_string(), serde_json::json!(true));
    }

    PvHarmMutation {
        scenario: HarmScenario::DuplicateInjection,
        target_field: "case_id".to_string(),
        original_value: original,
        mutated_value: serde_json::json!("CASE-2025-00001 + 3 duplicates"),
        safety_impact: HarmScenario::DuplicateInjection.safety_impact(),
        expected_drifts: HarmScenario::DuplicateInjection.expected_drift_types(),
    }
}

fn narrative_truncation(data: &mut serde_json::Value) -> PvHarmMutation {
    let original = data
        .get("narrative")
        .cloned()
        .unwrap_or(serde_json::Value::Null);

    if let Some(obj) = data.as_object_mut() {
        obj.insert("narrative".to_string(), serde_json::json!("Truncated."));
    }

    PvHarmMutation {
        scenario: HarmScenario::NarrativeTruncation,
        target_field: "narrative".to_string(),
        original_value: original,
        mutated_value: serde_json::json!("Truncated."),
        safety_impact: HarmScenario::NarrativeTruncation.safety_impact(),
        expected_drifts: HarmScenario::NarrativeTruncation.expected_drift_types(),
    }
}

fn temporal_shift(data: &mut serde_json::Value) -> PvHarmMutation {
    let original = data
        .get("report_date")
        .cloned()
        .unwrap_or(serde_json::Value::Null);

    if let Some(obj) = data.as_object_mut() {
        obj.insert("report_date".to_string(), serde_json::json!("2020-01-01"));
    }

    PvHarmMutation {
        scenario: HarmScenario::TemporalShift,
        target_field: "report_date".to_string(),
        original_value: original,
        mutated_value: serde_json::json!("2020-01-01"),
        safety_impact: HarmScenario::TemporalShift.safety_impact(),
        expected_drifts: HarmScenario::TemporalShift.expected_drift_types(),
    }
}

fn outcome_masking(data: &mut serde_json::Value) -> PvHarmMutation {
    let original = data
        .get("outcome")
        .cloned()
        .unwrap_or(serde_json::Value::Null);

    if let Some(obj) = data.as_object_mut() {
        obj.insert("outcome".to_string(), serde_json::json!("recovered"));
    }

    PvHarmMutation {
        scenario: HarmScenario::OutcomeMasking,
        target_field: "outcome".to_string(),
        original_value: original,
        mutated_value: serde_json::json!("recovered"),
        safety_impact: HarmScenario::OutcomeMasking.safety_impact(),
        expected_drifts: HarmScenario::OutcomeMasking.expected_drift_types(),
    }
}

// ─── Tests ───────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
    use super::*;

    fn baseline() -> serde_json::Value {
        baseline_drug_record()
    }

    // ── Scenario coverage ─────────────────────────────────────────────────

    #[test]
    fn test_all_scenarios_count() {
        assert_eq!(HarmScenario::ALL.len(), 8);
    }

    #[test]
    fn test_all_scenarios_have_expected_drifts() {
        for scenario in HarmScenario::ALL {
            let drifts = scenario.expected_drift_types();
            assert!(!drifts.is_empty(), "{scenario} has no expected drift types");
        }
    }

    #[test]
    fn test_all_scenarios_have_safety_impact() {
        for scenario in HarmScenario::ALL {
            let impact = scenario.safety_impact();
            assert!(
                (1..=5).contains(&impact),
                "{scenario} has invalid safety impact: {impact}"
            );
        }
    }

    // ── Baseline record ───────────────────────────────────────────────────

    #[test]
    fn test_baseline_has_required_fields() {
        let b = baseline();
        assert!(b.get("case_id").is_some());
        assert!(b.get("drug_name").is_some());
        assert!(b.get("adverse_event").is_some());
        assert!(b.get("is_serious").is_some());
        assert!(b.get("outcome").is_some());
        assert!(b.get("case_count").is_some());
        assert!(b.get("narrative").is_some());
        assert!(b.get("report_date").is_some());
    }

    #[test]
    fn test_baseline_is_object() {
        assert!(baseline().is_object());
    }

    // ── Individual mutations ──────────────────────────────────────────────

    #[test]
    fn test_severity_downgrade() {
        let phenotype = synthesize_harm(&baseline(), HarmScenario::SeverityDowngrade);
        assert_eq!(phenotype.data["adverse_event"], "nausea");
        assert_eq!(phenotype.mutations[0].target_field, "adverse_event");
        assert_eq!(phenotype.max_safety_impact, 4);
    }

    #[test]
    fn test_missing_seriousness() {
        let phenotype = synthesize_harm(&baseline(), HarmScenario::MissingSeriousness);
        assert!(phenotype.data.get("is_serious").is_none());
        assert!(phenotype.data.get("seriousness_criteria").is_none());
    }

    #[test]
    fn test_drug_misattribution() {
        let phenotype = synthesize_harm(&baseline(), HarmScenario::DrugMisattribution);
        assert_eq!(phenotype.data["drug_name"], "aspirin");
        assert_ne!(
            phenotype.mutations[0].original_value,
            phenotype.mutations[0].mutated_value
        );
    }

    #[test]
    fn test_case_count_deflation() {
        let phenotype = synthesize_harm(&baseline(), HarmScenario::CaseCountDeflation);
        assert_eq!(phenotype.data["case_count"], 1);
    }

    #[test]
    fn test_duplicate_injection() {
        let phenotype = synthesize_harm(&baseline(), HarmScenario::DuplicateInjection);
        assert!(phenotype.data.get("duplicate_cases").is_some());
        assert!(phenotype.data.get("_injected_flag").is_some());
    }

    #[test]
    fn test_narrative_truncation() {
        let phenotype = synthesize_harm(&baseline(), HarmScenario::NarrativeTruncation);
        let narrative = phenotype.data["narrative"].as_str().unwrap_or("");
        assert!(
            narrative.len() < 20,
            "Narrative should be truncated, got len={}",
            narrative.len()
        );
    }

    #[test]
    fn test_temporal_shift() {
        let phenotype = synthesize_harm(&baseline(), HarmScenario::TemporalShift);
        assert_eq!(phenotype.data["report_date"], "2020-01-01");
    }

    #[test]
    fn test_outcome_masking() {
        let phenotype = synthesize_harm(&baseline(), HarmScenario::OutcomeMasking);
        assert_eq!(phenotype.data["outcome"], "recovered");
        assert_eq!(phenotype.max_safety_impact, 5);
    }

    // ── Batch operations ──────────────────────────────────────────────────

    #[test]
    fn test_synthesize_all_harms() {
        let phenotypes = synthesize_all_harms(&baseline());
        assert_eq!(phenotypes.len(), 8);
    }

    #[test]
    fn test_compound_harm() {
        let phenotype = synthesize_compound_harm(
            &baseline(),
            &[
                HarmScenario::SeverityDowngrade,
                HarmScenario::OutcomeMasking,
            ],
        );
        assert_eq!(phenotype.mutations.len(), 2);
        assert_eq!(phenotype.max_safety_impact, 5); // OutcomeMasking is 5
        assert_eq!(phenotype.data["adverse_event"], "nausea");
        assert_eq!(phenotype.data["outcome"], "recovered");
    }

    #[test]
    fn test_compound_harm_all_scenarios() {
        let phenotype = synthesize_compound_harm(&baseline(), HarmScenario::ALL);
        assert_eq!(phenotype.mutations.len(), 8);
        assert_eq!(phenotype.max_safety_impact, 5);
    }

    // ── Traceability ──────────────────────────────────────────────────────

    #[test]
    fn test_mutation_records_original_value() {
        let phenotype = synthesize_harm(&baseline(), HarmScenario::DrugMisattribution);
        assert_eq!(phenotype.mutations[0].original_value, "warfarin");
    }

    #[test]
    fn test_mutation_records_mutated_value() {
        let phenotype = synthesize_harm(&baseline(), HarmScenario::DrugMisattribution);
        assert_eq!(phenotype.mutations[0].mutated_value, "aspirin");
    }

    #[test]
    fn test_mutation_records_scenario() {
        let phenotype = synthesize_harm(&baseline(), HarmScenario::TemporalShift);
        assert_eq!(phenotype.mutations[0].scenario, HarmScenario::TemporalShift);
    }

    // ── Display ───────────────────────────────────────────────────────────

    #[test]
    fn test_harm_scenario_display() {
        assert_eq!(HarmScenario::OutcomeMasking.to_string(), "Outcome Masking");
        assert_eq!(
            HarmScenario::SeverityDowngrade.to_string(),
            "Severity Downgrade"
        );
    }

    // ── Safety impact ordering ────────────────────────────────────────────

    #[test]
    fn test_outcome_masking_is_highest_impact() {
        let max_impact = HarmScenario::ALL
            .iter()
            .map(|s| s.safety_impact())
            .max()
            .unwrap_or(0);
        assert_eq!(max_impact, 5);
        assert_eq!(HarmScenario::OutcomeMasking.safety_impact(), max_impact);
    }

    #[test]
    fn test_narrative_truncation_is_lower_impact() {
        assert!(
            HarmScenario::NarrativeTruncation.safety_impact()
                < HarmScenario::OutcomeMasking.safety_impact()
        );
    }
}
//! # GroundsTo implementations for nexcore-phenotype types
//!
//! Connects adversarial test fixture generator types to the Lex Primitiva type system.
//!
//! ## Biological Analogy
//!
//! In biology, a phenotype is the observable expression of a genotype.
//! This crate mutates schemas (genotype) to produce observable drift (phenotype).
//!
//! ## Key Primitive Mapping
//!
//! - Mutation dispatch: partial (Boundary) -- conditional mutation selection
//! - Value generation: mu (Mapping) -- schema -> mutated value
//! - Type swap: kappa (Comparison) -- expected vs actual drift comparison

use nexcore_lex_primitiva::grounding::GroundsTo;
use nexcore_lex_primitiva::primitiva::{LexPrimitiva, PrimitiveComposition};

use crate::{Mutation, Phenotype};

// ---------------------------------------------------------------------------
// Mutation types -- Sigma (Sum) dominant
// ---------------------------------------------------------------------------

/// Mutation: T2-P (Sigma + partial), dominant Sigma
///
/// Seven-variant enum classifying mutation strategies.
/// Sum-dominant: the type IS a categorical alternation of mutation types.
/// Boundary is secondary (each mutation tests a different boundary).
impl GroundsTo for Mutation {
    fn primitive_composition() -> PrimitiveComposition {
        PrimitiveComposition::new(vec![
            LexPrimitiva::Sum,      // Sigma -- mutation type alternation
            LexPrimitiva::Boundary, // partial -- boundary violation type
        ])
        .with_dominant(LexPrimitiva::Sum, 0.85)
    }
}

// ---------------------------------------------------------------------------
// Result types -- mu (Mapping) dominant
// ---------------------------------------------------------------------------

/// Phenotype: T2-C (mu + sigma + kappa + partial), dominant mu
///
/// A mutated JSON value with metadata about what was changed.
/// Mapping-dominant: it maps a schema + mutation to a mutated value.
/// Sequence is secondary (mutations_applied is ordered).
/// Comparison is tertiary (expected_drifts for verification).
/// Boundary is quaternary (each mutation violates a boundary).
impl GroundsTo for Phenotype {
    fn primitive_composition() -> PrimitiveComposition {
        PrimitiveComposition::new(vec![
            LexPrimitiva::Mapping,    // mu -- schema + mutation -> value
            LexPrimitiva::Sequence,   // sigma -- ordered mutations
            LexPrimitiva::Comparison, // kappa -- drift verification
            LexPrimitiva::Boundary,   // partial -- boundary violations
        ])
        .with_dominant(LexPrimitiva::Mapping, 0.80)
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
    use super::*;
    use nexcore_lex_primitiva::tier::Tier;

    #[test]
    fn mutation_is_t2p() {
        assert_eq!(Mutation::tier(), Tier::T2Primitive);
        assert_eq!(Mutation::dominant_primitive(), Some(LexPrimitiva::Sum));
    }

    #[test]
    fn phenotype_is_t2c() {
        assert_eq!(Phenotype::tier(), Tier::T2Composite);
        assert_eq!(Phenotype::dominant_primitive(), Some(LexPrimitiva::Mapping));
    }

    #[test]
    fn phenotype_contains_boundary() {
        let comp = Phenotype::primitive_composition();
        assert!(comp.primitives.contains(&LexPrimitiva::Boundary));
    }

    #[test]
    fn all_confidences_valid() {
        let compositions = [
            Mutation::primitive_composition(),
            Phenotype::primitive_composition(),
        ];
        for comp in &compositions {
            assert!(comp.confidence >= 0.80);
            assert!(comp.confidence <= 1.0);
        }
    }
}
//! # Trait Bridge
//!
//! Multi-system aggregation: Muscular + Skeletal + Nervous → Phenotype.
//!
//! Converts health metrics from three internal systems into observable
//! phenotypic traits — the outward expression of underlying system health.
//!
//! ```text
//! Muscular::MuscularHealth  ─┐
//! Skeletal::SkeletalHealth  ─┤──► PhenotypicProfile (observable fitness)
//! Nervous::NervousHealth    ─┘
//! ```
//!
//! **Biological mapping**: A phenotype is the observable expression of
//! underlying genotype + environment. In the same way, this bridge
//! aggregates internal system health metrics into an observable profile
//! that represents how the organism *appears* from outside. A fatigued
//! muscular system, a weak skeleton, or a slow nervous system all
//! manifest as degraded phenotypic traits — visible to external
//! monitoring, adversarial probes, and drift detection.

use nexcore_muscular::MuscularHealth;
use nexcore_nervous::NervousHealth;
use nexcore_skeletal::SkeletalHealth;

/// Aggregated phenotypic profile derived from multiple system health metrics.
///
/// **Biological mapping**: The phenotype — what you can observe from outside.
/// Internal health scores from muscular (performance), skeletal (structure),
/// and nervous (responsiveness) systems combine into an overall fitness
/// profile with per-system trait scores.
#[derive(Debug, Clone, PartialEq)]
pub struct PhenotypicProfile {
    /// Overall fitness score (0.0–1.0). Average of system trait scores.
    pub fitness: f64,
    /// Muscular trait: performance capacity (0.0–1.0).
    pub performance: f64,
    /// Skeletal trait: structural integrity (0.0–1.0).
    pub integrity: f64,
    /// Nervous trait: responsiveness / signal speed (0.0–1.0).
    pub responsiveness: f64,
    /// Number of systems contributing to this profile.
    pub systems_assessed: usize,
    /// Whether the phenotype is considered healthy (fitness >= 0.6).
    pub healthy: bool,
}

/// Convert muscular health into a performance trait score (0.0–1.0).
///
/// **Biological mapping**: Muscular performance phenotype — grip strength,
/// endurance, coordination. Reflects whether the muscular system can
/// sustain work without excessive fatigue or imbalance.
pub fn muscular_to_trait(health: &MuscularHealth) -> f64 {
    let mut score = 0.0;
    if health.size_principle_compliant {
        score += 0.25;
    }
    if health.antagonistic_pairs_defined {
        score += 0.25;
    }
    if health.recruitment_balanced {
        score += 0.20;
    }
    if health.cardiac_running {
        score += 0.15;
    }
    // Fatigue reduces performance: 0.0 fatigue = +0.15, 1.0 fatigue = +0.0
    score += 0.15 * (1.0 - health.fatigue_level.clamp(0.0, 1.0));
    score
}

/// Convert skeletal health into a structural integrity trait score (0.0–1.0).
///
/// **Biological mapping**: Skeletal integrity phenotype — posture, bone
/// density, joint stability. Reflects whether the structural framework
/// supports the organism properly. Missing CLAUDE.md (skull) or inactive
/// Wolff's Law feedback weakens the phenotypic expression.
pub fn skeletal_to_trait(health: &SkeletalHealth) -> f64 {
    let mut score = 0.0;
    if health.claude_md_present {
        score += 0.30;
    }
    if health.corrections_feeding_claude_md {
        score += 0.25;
    }
    if health.settings_versioned {
        score += 0.20;
    }
    if health.wolff_law_active {
        score += 0.25;
    }
    score
}

/// Convert nervous health into a responsiveness trait score (0.0–1.0).
///
/// **Biological mapping**: Nervous responsiveness phenotype — reaction
/// time, reflex speed, sensory acuity. High myelination ratio and low
/// signal latency indicate a responsive nervous system that manifests
/// as quick, coordinated phenotypic behavior.
pub fn nervous_to_trait(health: &NervousHealth) -> f64 {
    let mut score = 0.0;

    // Myelination ratio contributes to signal speed
    // Ratio of 1.0 = fully myelinated = fast, 0.0 = unmyelinated = slow
    score += 0.30 * health.myelination_ratio.clamp(0.0, 1.0);

    // Low latency is good. Assume <50ms is excellent, >500ms is poor.
    let latency_factor = if health.avg_signal_latency_ms <= 0.0 {
        1.0
    } else {
        (1.0 - (health.avg_signal_latency_ms / 500.0)).clamp(0.0, 1.0)
    };
    score += 0.25 * latency_factor;

    // Sensory integration
    if health.sensory_integration_ok {
        score += 0.20;
    }

    // Active neurons and reflex arcs (capacity)
    // More is better, but normalize: assume 10+ neurons = full score
    let neuron_factor = (health.neuron_count as f64 / 10.0).min(1.0);
    score += 0.15 * neuron_factor;

    let reflex_factor = (health.reflex_arcs_active as f64 / 5.0).min(1.0);
    score += 0.10 * reflex_factor;

    score
}

/// Aggregate health metrics from all three systems into a phenotypic profile.
///
/// **Biological mapping**: Phenotypic expression — the integrated,
/// observable output of all underlying biological systems. Just as a
/// doctor assesses a patient's phenotype by observing strength (muscular),
/// posture (skeletal), and reflexes (nervous), this function combines
/// three health assessments into one observable profile.
pub fn aggregate_phenotype(
    muscular: &MuscularHealth,
    skeletal: &SkeletalHealth,
    nervous: &NervousHealth,
) -> PhenotypicProfile {
    let performance = muscular_to_trait(muscular);
    let integrity = skeletal_to_trait(skeletal);
    let responsiveness = nervous_to_trait(nervous);
    let fitness = (performance + integrity + responsiveness) / 3.0;

    PhenotypicProfile {
        fitness,
        performance,
        integrity,
        responsiveness,
        systems_assessed: 3,
        healthy: fitness >= 0.6,
    }
}

/// Compute the throughput metric for phenotypic assessment.
///
/// Returns the number of healthy traits (score >= 0.5) out of the three
/// system assessments.
///
/// **Biological mapping**: Phenotypic vigor — how many observable traits
/// reach a healthy threshold. An organism with all three systems healthy
/// has high phenotypic throughput; one with degraded systems shows
/// reduced phenotypic expression.
pub fn phenotype_throughput(
    muscular: &MuscularHealth,
    skeletal: &SkeletalHealth,
    nervous: &NervousHealth,
) -> usize {
    let mut count = 0usize;
    if muscular_to_trait(muscular) >= 0.5 {
        count = count.saturating_add(1);
    }
    if skeletal_to_trait(skeletal) >= 0.5 {
        count = count.saturating_add(1);
    }
    if nervous_to_trait(nervous) >= 0.5 {
        count = count.saturating_add(1);
    }
    count
}

/// Identify which mutation types are most likely based on system health.
///
/// **Biological mapping**: Phenotype–genotype correlation — certain
/// phenotypic weaknesses predispose the organism to specific mutation
/// types. A structurally weak skeleton (missing CLAUDE.md) predisposes
/// to `StructureSwap` mutations. A fatigued muscular system predisposes
/// to `RangeExpand` (overextension) mutations.
pub fn health_to_mutation_risk(
    muscular: &MuscularHealth,
    skeletal: &SkeletalHealth,
    nervous: &NervousHealth,
) -> Vec<crate::Mutation> {
    let mut risks = Vec::new();

    // Low muscular performance → risk of range expansion (overextension)
    if muscular_to_trait(muscular) < 0.5 {
        risks.push(crate::Mutation::RangeExpand);
    }

    // Weak skeletal integrity → risk of structural swap
    if skeletal_to_trait(skeletal) < 0.5 {
        risks.push(crate::Mutation::StructureSwap);
    }

    // Slow nervous responsiveness → risk of type mismatch (misinterpretation)
    if nervous_to_trait(nervous) < 0.5 {
        risks.push(crate::Mutation::TypeMismatch);
    }

    // If all systems are weak, also risk field removal (degradation)
    if muscular_to_trait(muscular) < 0.3
        && skeletal_to_trait(skeletal) < 0.3
        && nervous_to_trait(nervous) < 0.3
    {
        risks.push(crate::Mutation::RemoveField);
    }

    risks
}

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
    use super::*;

    fn make_healthy_muscular() -> MuscularHealth {
        MuscularHealth {
            size_principle_compliant: true,
            antagonistic_pairs_defined: true,
            recruitment_balanced: true,
            fatigue_level: 0.1,
            cardiac_running: true,
        }
    }

    fn make_unhealthy_muscular() -> MuscularHealth {
        MuscularHealth {
            size_principle_compliant: false,
            antagonistic_pairs_defined: false,
            recruitment_balanced: false,
            fatigue_level: 0.9,
            cardiac_running: false,
        }
    }

    fn make_healthy_skeletal() -> SkeletalHealth {
        SkeletalHealth {
            claude_md_present: true,
            corrections_feeding_claude_md: true,
            settings_versioned: true,
            wolff_law_active: true,
        }
    }

    fn make_unhealthy_skeletal() -> SkeletalHealth {
        SkeletalHealth {
            claude_md_present: false,
            corrections_feeding_claude_md: false,
            settings_versioned: false,
            wolff_law_active: false,
        }
    }

    fn make_healthy_nervous() -> NervousHealth {
        NervousHealth {
            neuron_count: 20,
            reflex_arcs_active: 8,
            myelination_ratio: 0.9,
            avg_signal_latency_ms: 30.0,
            sensory_integration_ok: true,
        }
    }

    fn make_unhealthy_nervous() -> NervousHealth {
        NervousHealth {
            neuron_count: 1,
            reflex_arcs_active: 0,
            myelination_ratio: 0.1,
            avg_signal_latency_ms: 450.0,
            sensory_integration_ok: false,
        }
    }

    #[test]
    fn test_muscular_healthy_trait() {
        let health = make_healthy_muscular();
        let score = muscular_to_trait(&health);
        assert!(score > 0.8, "Healthy muscular should score >0.8: got {score}");
    }

    #[test]
    fn test_muscular_unhealthy_trait() {
        let health = make_unhealthy_muscular();
        let score = muscular_to_trait(&health);
        assert!(score < 0.1, "Unhealthy muscular should score <0.1: got {score}");
    }

    #[test]
    fn test_skeletal_healthy_trait() {
        let health = make_healthy_skeletal();
        let score = skeletal_to_trait(&health);
        assert!((score - 1.0).abs() < f64::EPSILON, "All-healthy skeletal should score 1.0: got {score}");
    }

    #[test]
    fn test_skeletal_unhealthy_trait() {
        let health = make_unhealthy_skeletal();
        let score = skeletal_to_trait(&health);
        assert!((score - 0.0).abs() < f64::EPSILON, "All-unhealthy skeletal should score 0.0: got {score}");
    }

    #[test]
    fn test_nervous_healthy_trait() {
        let health = make_healthy_nervous();
        let score = nervous_to_trait(&health);
        assert!(score > 0.8, "Healthy nervous should score >0.8: got {score}");
    }

    #[test]
    fn test_nervous_unhealthy_trait() {
        let health = make_unhealthy_nervous();
        let score = nervous_to_trait(&health);
        assert!(score < 0.3, "Unhealthy nervous should score <0.3: got {score}");
    }

    #[test]
    fn test_aggregate_healthy_phenotype() {
        let profile = aggregate_phenotype(
            &make_healthy_muscular(),
            &make_healthy_skeletal(),
            &make_healthy_nervous(),
        );
        assert!(profile.healthy, "All-healthy systems should produce healthy phenotype");
        assert!(profile.fitness > 0.8, "Fitness should be >0.8: got {}", profile.fitness);
        assert_eq!(profile.systems_assessed, 3);
    }

    #[test]
    fn test_aggregate_unhealthy_phenotype() {
        let profile = aggregate_phenotype(
            &make_unhealthy_muscular(),
            &make_unhealthy_skeletal(),
            &make_unhealthy_nervous(),
        );
        assert!(!profile.healthy, "All-unhealthy systems should produce unhealthy phenotype");
        assert!(profile.fitness < 0.2, "Fitness should be <0.2: got {}", profile.fitness);
    }

    #[test]
    fn test_phenotype_throughput_all_healthy() {
        let throughput = phenotype_throughput(
            &make_healthy_muscular(),
            &make_healthy_skeletal(),
            &make_healthy_nervous(),
        );
        assert_eq!(throughput, 3, "All healthy systems should have throughput 3");
    }

    #[test]
    fn test_phenotype_throughput_all_unhealthy() {
        let throughput = phenotype_throughput(
            &make_unhealthy_muscular(),
            &make_unhealthy_skeletal(),
            &make_unhealthy_nervous(),
        );
        assert_eq!(throughput, 0, "All unhealthy systems should have throughput 0");
    }

    #[test]
    fn test_health_to_mutation_risk_healthy() {
        let risks = health_to_mutation_risk(
            &make_healthy_muscular(),
            &make_healthy_skeletal(),
            &make_healthy_nervous(),
        );
        assert!(risks.is_empty(), "Healthy systems should have no mutation risks");
    }

    #[test]
    fn test_health_to_mutation_risk_unhealthy() {
        let risks = health_to_mutation_risk(
            &make_unhealthy_muscular(),
            &make_unhealthy_skeletal(),
            &make_unhealthy_nervous(),
        );
        assert!(risks.contains(&crate::Mutation::RangeExpand), "Weak muscular should risk RangeExpand");
        assert!(risks.contains(&crate::Mutation::StructureSwap), "Weak skeletal should risk StructureSwap");
        assert!(risks.contains(&crate::Mutation::TypeMismatch), "Weak nervous should risk TypeMismatch");
        assert!(risks.contains(&crate::Mutation::RemoveField), "All-weak should risk RemoveField");
    }

    #[test]
    fn test_mixed_health_partial_risks() {
        let risks = health_to_mutation_risk(
            &make_healthy_muscular(),
            &make_unhealthy_skeletal(),
            &make_healthy_nervous(),
        );
        assert_eq!(risks.len(), 1, "Only skeletal is weak, should have 1 risk");
        assert_eq!(risks[0], crate::Mutation::StructureSwap);
    }
}
// Copyright © 2026 NexVigilant LLC. All Rights Reserved.
// Intellectual Property of Matthew Alexander Campion, PharmD

//! # NexVigilant Core — phenotype — Adversarial Test Fixture Generator
//!
//! In biology, a **phenotype** is the observable expression of a genotype.
//! Mutations in the genotype produce different phenotypes.
//!
//! This crate takes a schema (genotype) and produces **mutated** JSON values
//! (phenotypes) designed to trigger specific drift types in the ribosome
//! drift detection pipeline.
//!
//! ## Pipeline
//!
//! ```text
//! Schema → mutate(Mutation) → Phenotype { data, mutations_applied, expected_drifts }
//!                                ↓
//!                    Ribosome::validate → DriftResult (should detect!)
//! ```
//!
//! ## T1 Grounding
//!
//! | Concept | Primitive | Role |
//! |---------|-----------|------|
//! | Mutation dispatch | ∂ (conditional) | Select mutation strategy |
//! | Value generation | μ (function) | Schema → mutated Value |
//! | Mutation batch | σ (sequence) | Iterate mutation types |
//! | Type swap | κ (comparison) | Expected vs actual drift |
//!
//! ## Tier: T2-C

#![forbid(unsafe_code)]
#![warn(missing_docs)]
#![cfg_attr(
    not(test),
    deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)
)]

#![deny(clippy::unwrap_used)]
#![deny(clippy::expect_used)]
#![deny(clippy::panic)]
#![forbid(unsafe_code)]
pub mod commensal;
pub mod error;
pub mod grounding;
pub mod harm_synthesis;

use std::fmt;

use error::{PhenotypeError, PhenotypeResult};
use nexcore_ribosome::DriftType;
use nexcore_transcriptase::{Schema, SchemaKind};
use serde::{Deserialize, Serialize};

// ─── Mutation Types ────────────────────────────────────────────────────────

/// What kind of mutation to apply.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum Mutation {
    /// Replace a value's type entirely (Int → String, etc.)
    TypeMismatch,
    /// Add extra fields to a Record.
    AddField,
    /// Remove existing fields from a Record.
    RemoveField,
    /// Push numeric values beyond baseline range.
    RangeExpand,
    /// Change string lengths significantly.
    LengthChange,
    /// Change array sizes (add/remove elements).
    ArrayResize,
    /// Replace the entire structure with a different kind.
    StructureSwap,
}

impl Mutation {
    /// All available mutation types.
    pub const ALL: &[Self] = &[
        Self::TypeMismatch,
        Self::AddField,
        Self::RemoveField,
        Self::RangeExpand,
        Self::LengthChange,
        Self::ArrayResize,
        Self::StructureSwap,
    ];

    /// Which drift types this mutation is expected to trigger.
    #[must_use]
    pub fn expected_drift_types(self) -> Vec<DriftType> {
        match self {
            Self::TypeMismatch | Self::StructureSwap => vec![DriftType::TypeMismatch],
            Self::AddField => vec![DriftType::ExtraField],
            Self::RemoveField => vec![DriftType::MissingField],
            Self::RangeExpand => vec![DriftType::RangeExpansion],
            Self::LengthChange => vec![DriftType::LengthChange],
            Self::ArrayResize => vec![DriftType::ArraySizeChange],
        }
    }
}

impl fmt::Display for Mutation {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::TypeMismatch => write!(f, "TYPE_MISMATCH"),
            Self::AddField => write!(f, "ADD_FIELD"),
            Self::RemoveField => write!(f, "REMOVE_FIELD"),
            Self::RangeExpand => write!(f, "RANGE_EXPAND"),
            Self::LengthChange => write!(f, "LENGTH_CHANGE"),
            Self::ArrayResize => write!(f, "ARRAY_RESIZE"),
            Self::StructureSwap => write!(f, "STRUCTURE_SWAP"),
        }
    }
}

// ─── Phenotype Result ──────────────────────────────────────────────────────

/// A mutated JSON value with metadata about what was changed.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Phenotype {
    /// The mutated JSON data.
    pub data: serde_json::Value,
    /// Which mutations were applied.
    pub mutations_applied: Vec<Mutation>,
    /// Which drift types the ribosome should detect.
    pub expected_drifts: Vec<DriftType>,
}

// ─── Mutation Engine ───────────────────────────────────────────────────────

/// Apply a single mutation to a schema, producing a mutated JSON value.
#[must_use]
pub fn mutate(schema: &Schema, mutation: Mutation) -> Phenotype {
    let data = apply_mutation(&schema.kind, mutation);
    Phenotype {
        data,
        mutations_applied: vec![mutation],
        expected_drifts: mutation.expected_drift_types(),
    }
}

/// Generate one phenotype per mutation type.
#[must_use]
pub fn mutate_all(schema: &Schema) -> Vec<Phenotype> {
    Mutation::ALL.iter().map(|m| mutate(schema, *m)).collect()
}

/// Generate `count` random-ish phenotypes cycling through mutation types.
#[must_use]
pub fn mutate_batch(schema: &Schema, count: usize) -> Vec<Phenotype> {
    (0..count)
        .map(|i| {
            let mutation = Mutation::ALL[i % Mutation::ALL.len()];
            mutate(schema, mutation)
        })
        .collect()
}

/// Verify a phenotype against the ribosome: does the mutation actually
/// trigger drift detection?
///
/// Uses a very low threshold (0.01) since we're testing that mutations
/// produce measurable drift, not that they exceed production thresholds.
///
/// Returns `Ok(true)` if the ribosome detected drift (good — mutation worked).
///
/// # Errors
///
/// Returns `PhenotypeError::VerificationError` if the ribosome cannot
/// store the contract or validate the phenotype.
pub fn verify(schema: &Schema, phenotype: &Phenotype) -> PhenotypeResult<bool> {
    verify_with_threshold(schema, phenotype, 0.01)
}

/// Verify a phenotype against the ribosome with a custom drift threshold.
///
/// # Errors
///
/// Returns `PhenotypeError::VerificationError` if the ribosome cannot
/// store the contract or validate the phenotype.
pub fn verify_with_threshold(
    schema: &Schema,
    phenotype: &Phenotype,
    threshold: f64,
) -> PhenotypeResult<bool> {
    let mut ribosome = nexcore_ribosome::Ribosome::with_config(nexcore_ribosome::RibosomeConfig {
        drift_threshold: threshold,
        auto_update: false,
    });
    ribosome
        .store_contract("phenotype-test", schema.clone())
        .map_err(|e| PhenotypeError::VerificationError(format!("failed to store contract: {e}")))?;

    match ribosome.validate("phenotype-test", &phenotype.data) {
        Some(result) => Ok(result.drift_detected),
        None => Err(PhenotypeError::VerificationError(
            "ribosome returned no validation result".to_string(),
        )),
    }
}

/// Verify all phenotypes and return (detected_count, total_count).
///
/// # Errors
///
/// Returns `PhenotypeError::VerificationError` if any individual verification fails.
pub fn verify_batch(schema: &Schema, phenotypes: &[Phenotype]) -> PhenotypeResult<(usize, usize)> {
    let mut detected = 0usize;
    for p in phenotypes {
        if verify(schema, p)? {
            detected = detected.saturating_add(1);
        }
    }
    Ok((detected, phenotypes.len()))
}

// ─── Mutation Implementations ──────────────────────────────────────────────

/// Core dispatch: apply a mutation to a schema kind, producing a Value.
fn apply_mutation(kind: &SchemaKind, mutation: Mutation) -> serde_json::Value {
    match mutation {
        Mutation::TypeMismatch => type_mismatch(kind),
        Mutation::AddField => add_field(kind),
        Mutation::RemoveField => remove_field(kind),
        Mutation::RangeExpand => range_expand(kind),
        Mutation::LengthChange => length_change(kind),
        Mutation::ArrayResize => array_resize(kind),
        Mutation::StructureSwap => structure_swap(kind),
    }
}

/// Replace the value with a completely different type.
fn type_mismatch(kind: &SchemaKind) -> serde_json::Value {
    match kind {
        SchemaKind::Int { .. } => serde_json::Value::String("mutated_to_string".to_string()),
        SchemaKind::Float { .. } => serde_json::Value::Bool(true),
        SchemaKind::Str { .. } => serde_json::json!(42),
        SchemaKind::Bool { .. } => serde_json::json!(99),
        SchemaKind::Null => serde_json::json!("was_null"),
        SchemaKind::Array { .. } => serde_json::json!({"mutated": "from_array"}),
        SchemaKind::Record(fields) => {
            // Turn record into a type-mismatched record: swap field types
            let mut map = serde_json::Map::new();
            for (key, field_schema) in fields {
                map.insert(key.clone(), type_mismatch(&field_schema.kind));
            }
            serde_json::Value::Object(map)
        }
        SchemaKind::Mixed => serde_json::json!([1, "mixed", true]),
    }
}

/// Add extra fields to a Record; for non-records, wrap in a record.
fn add_field(kind: &SchemaKind) -> serde_json::Value {
    match kind {
        SchemaKind::Record(fields) => {
            let mut map = serde_json::Map::new();
            // Keep existing fields with normal values
            for (key, field_schema) in fields {
                map.insert(key.clone(), generate_normal(&field_schema.kind));
            }
            // Add extra fields
            map.insert("__extra_field_1".to_string(), serde_json::json!("injected"));
            map.insert("__extra_field_2".to_string(), serde_json::json!(999));
            serde_json::Value::Object(map)
        }
        // Non-record: generate normal value (add_field only meaningful for records)
        other => generate_normal(other),
    }
}

/// Remove fields from a Record; for non-records, return normal value.
fn remove_field(kind: &SchemaKind) -> serde_json::Value {
    match kind {
        SchemaKind::Record(fields) => {
            let mut map = serde_json::Map::new();
            // Only keep first half of fields
            let keep_count = fields.len() / 2;
            for (key, field_schema) in fields.iter().take(keep_count.max(1)) {
                map.insert(key.clone(), generate_normal(&field_schema.kind));
            }
            serde_json::Value::Object(map)
        }
        other => generate_normal(other),
    }
}

/// Expand numeric ranges well beyond the baseline.
fn range_expand(kind: &SchemaKind) -> serde_json::Value {
    match kind {
        SchemaKind::Int { max, .. } => {
            // Double the max value
            serde_json::json!(max.saturating_mul(2).saturating_add(1000))
        }
        SchemaKind::Float { max, .. } => {
            serde_json::json!(max * 3.0 + 100.0)
        }
        SchemaKind::Record(fields) => {
            let mut map = serde_json::Map::new();
            for (key, field_schema) in fields {
                map.insert(key.clone(), range_expand(&field_schema.kind));
            }
            serde_json::Value::Object(map)
        }
        other => generate_normal(other),
    }
}

/// Change string lengths significantly.
fn length_change(kind: &SchemaKind) -> serde_json::Value {
    match kind {
        SchemaKind::Str { max_len, .. } => {
            // Generate string much longer than max
            let target_len = (*max_len * 3).max(100);
            let s: String = (0..target_len).map(|_| 'x').collect();
            serde_json::Value::String(s)
        }
        SchemaKind::Record(fields) => {
            let mut map = serde_json::Map::new();
            for (key, field_schema) in fields {
                map.insert(key.clone(), length_change(&field_schema.kind));
            }
            serde_json::Value::Object(map)
        }
        other => generate_normal(other),
    }
}

/// Change array sizes (shrink to empty or grow significantly).
fn array_resize(kind: &SchemaKind) -> serde_json::Value {
    match kind {
        SchemaKind::Array {
            element, max_len, ..
        } => {
            // Grow array to 3x the max length
            let new_len = (*max_len * 3).max(10);
            let items: Vec<serde_json::Value> = (0..new_len)
                .map(|_| generate_normal(&element.kind))
                .collect();
            serde_json::Value::Array(items)
        }
        SchemaKind::Record(fields) => {
            let mut map = serde_json::Map::new();
            for (key, field_schema) in fields {
                map.insert(key.clone(), array_resize(&field_schema.kind));
            }
            serde_json::Value::Object(map)
        }
        other => generate_normal(other),
    }
}

/// Replace the entire structure with a fundamentally different kind.
fn structure_swap(kind: &SchemaKind) -> serde_json::Value {
    match kind {
        SchemaKind::Record(_) => serde_json::json!(true), // Record → Bool
        SchemaKind::Array { .. } => serde_json::json!(42), // Array → Int
        SchemaKind::Int { .. } => serde_json::json!([1, 2, 3]), // Int → Array
        SchemaKind::Str { .. } => serde_json::json!(null), // Str → Null
        _ => serde_json::json!({"swapped": true}),        // Anything else → Record
    }
}

// ─── Normal Value Generation ───────────────────────────────────────────────

/// Generate a "normal" (non-mutated) value from a schema kind.
/// Uses the same logic as transcriptase::generate but without importing it.
fn generate_normal(kind: &SchemaKind) -> serde_json::Value {
    match kind {
        SchemaKind::Null | SchemaKind::Mixed => serde_json::Value::Null,
        SchemaKind::Bool {
            true_count,
            false_count,
        } => serde_json::Value::Bool(*true_count >= *false_count),
        SchemaKind::Int { min, max, .. } => {
            let mid = min / 2 + max / 2 + (min % 2 + max % 2) / 2;
            serde_json::json!(mid)
        }
        SchemaKind::Float { min, max, .. } => {
            serde_json::json!((min + max) / 2.0)
        }
        SchemaKind::Str {
            min_len, max_len, ..
        } => {
            let len = usize::midpoint(*min_len, *max_len);
            let s: String = (0..len.max(1)).map(|_| 'a').collect();
            serde_json::Value::String(s)
        }
        SchemaKind::Array {
            element,
            min_len,
            max_len,
        } => {
            let len = usize::midpoint(*min_len, *max_len);
            let items: Vec<serde_json::Value> = (0..len.max(1))
                .map(|_| generate_normal(&element.kind))
                .collect();
            serde_json::Value::Array(items)
        }
        SchemaKind::Record(fields) => {
            let mut map = serde_json::Map::new();
            for (key, field_schema) in fields {
                map.insert(key.clone(), generate_normal(&field_schema.kind));
            }
            serde_json::Value::Object(map)
        }
    }
}

// ─── Tests ─────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
    use super::*;
    use nexcore_transcriptase::infer;

    fn sample_record() -> serde_json::Value {
        serde_json::json!({
            "name": "Alice",
            "age": 30,
            "score": 95.5,
            "active": true,
            "tags": ["admin", "user"]
        })
    }

    fn sample_schema() -> Schema {
        infer(&sample_record())
    }

    // ── Mutation dispatch ──────────────────────────────────────────────

    #[test]
    fn test_all_mutations_produce_phenotypes() {
        let schema = sample_schema();
        let phenotypes = mutate_all(&schema);
        assert_eq!(phenotypes.len(), Mutation::ALL.len());
    }

    #[test]
    fn test_mutate_batch() {
        let schema = sample_schema();
        let phenotypes = mutate_batch(&schema, 10);
        assert_eq!(phenotypes.len(), 10);
    }

    #[test]
    fn test_each_mutation_has_expected_drifts() {
        for mutation in Mutation::ALL {
            let drifts = mutation.expected_drift_types();
            assert!(!drifts.is_empty(), "{mutation} has no expected drift types");
        }
    }

    // ── Type mismatch ──────────────────────────────────────────────────

    #[test]
    fn test_type_mismatch_int() {
        let schema = infer(&serde_json::json!(42));
        let phenotype = mutate(&schema, Mutation::TypeMismatch);
        assert!(phenotype.data.is_string(), "Int should mutate to String");
    }

    #[test]
    fn test_type_mismatch_string() {
        let schema = infer(&serde_json::json!("hello"));
        let phenotype = mutate(&schema, Mutation::TypeMismatch);
        assert!(phenotype.data.is_number(), "String should mutate to Number");
    }

    #[test]
    fn test_type_mismatch_bool() {
        let schema = infer(&serde_json::json!(true));
        let phenotype = mutate(&schema, Mutation::TypeMismatch);
        assert!(phenotype.data.is_number(), "Bool should mutate to Number");
    }

    #[test]
    fn test_type_mismatch_record() {
        let schema = sample_schema();
        let phenotype = mutate(&schema, Mutation::TypeMismatch);
        // Record with type-mismatched fields
        assert!(phenotype.data.is_object());
        let empty_map = serde_json::Map::new();
        let obj = phenotype.data.as_object().unwrap_or(&empty_map);
        // "age" was Int, should now be String
        if let Some(age) = obj.get("age") {
            assert!(age.is_string(), "age should be mutated from Int to String");
        }
    }

    // ── Add field ──────────────────────────────────────────────────────

    #[test]
    fn test_add_field_to_record() {
        let schema = sample_schema();
        let phenotype = mutate(&schema, Mutation::AddField);
        let empty_map = serde_json::Map::new();
        let obj = phenotype.data.as_object().unwrap_or(&empty_map);
        assert!(
            obj.contains_key("__extra_field_1"),
            "Should have extra field"
        );
        assert!(
            obj.contains_key("__extra_field_2"),
            "Should have second extra field"
        );
    }

    // ── Remove field ───────────────────────────────────────────────────

    #[test]
    fn test_remove_field_from_record() {
        let schema = sample_schema();
        let phenotype = mutate(&schema, Mutation::RemoveField);
        let empty_map = serde_json::Map::new();
        let obj = phenotype.data.as_object().unwrap_or(&empty_map);
        // Original has 5 fields, should have fewer
        assert!(
            obj.len() < 5,
            "Should have removed fields, got {}",
            obj.len()
        );
    }

    // ── Range expand ───────────────────────────────────────────────────

    #[test]
    fn test_range_expand_int() {
        let schema = infer(&serde_json::json!(50));
        let phenotype = mutate(&schema, Mutation::RangeExpand);
        let val = phenotype.data.as_i64().unwrap_or(0);
        assert!(val > 50, "Expanded range should exceed baseline: got {val}");
    }

    #[test]
    fn test_range_expand_float() {
        let schema = infer(&serde_json::json!(10.0));
        let phenotype = mutate(&schema, Mutation::RangeExpand);
        let val = phenotype.data.as_f64().unwrap_or(0.0);
        assert!(
            val > 10.0,
            "Expanded range should exceed baseline: got {val}"
        );
    }

    // ── Length change ──────────────────────────────────────────────────

    #[test]
    fn test_length_change_string() {
        let schema = infer(&serde_json::json!("short"));
        let phenotype = mutate(&schema, Mutation::LengthChange);
        let s = phenotype.data.as_str().unwrap_or("");
        assert!(
            s.len() > 10,
            "Mutated string should be much longer: len={}",
            s.len()
        );
    }

    // ── Array resize ───────────────────────────────────────────────────

    #[test]
    fn test_array_resize() {
        let schema = infer(&serde_json::json!([1, 2]));
        let phenotype = mutate(&schema, Mutation::ArrayResize);
        let arr = phenotype.data.as_array();
        assert!(arr.is_some(), "Should still be an array");
        assert!(
            arr.map(|a| a.len()).unwrap_or(0) > 5,
            "Should be significantly larger"
        );
    }

    // ── Structure swap ─────────────────────────────────────────────────

    #[test]
    fn test_structure_swap_record_to_bool() {
        let schema = sample_schema();
        let phenotype = mutate(&schema, Mutation::StructureSwap);
        assert!(phenotype.data.is_boolean(), "Record should swap to bool");
    }

    #[test]
    fn test_structure_swap_int_to_array() {
        let schema = infer(&serde_json::json!(42));
        let phenotype = mutate(&schema, Mutation::StructureSwap);
        assert!(phenotype.data.is_array(), "Int should swap to array");
    }

    // ── Verification ───────────────────────────────────────────────────

    #[test]
    fn test_verify_type_mismatch_detected() {
        let schema = sample_schema();
        let phenotype = mutate(&schema, Mutation::TypeMismatch);
        assert!(
            verify(&schema, &phenotype).unwrap_or(false),
            "Type mismatch should be detected"
        );
    }

    #[test]
    fn test_verify_add_field_detected() {
        let schema = sample_schema();
        let phenotype = mutate(&schema, Mutation::AddField);
        assert!(
            verify(&schema, &phenotype).unwrap_or(false),
            "Add field should be detected"
        );
    }

    #[test]
    fn test_verify_remove_field_detected() {
        let schema = sample_schema();
        let phenotype = mutate(&schema, Mutation::RemoveField);
        assert!(
            verify(&schema, &phenotype).unwrap_or(false),
            "Remove field should be detected"
        );
    }

    #[test]
    fn test_verify_structure_swap_detected() {
        let schema = sample_schema();
        let phenotype = mutate(&schema, Mutation::StructureSwap);
        assert!(
            verify(&schema, &phenotype).unwrap_or(false),
            "Structure swap should be detected"
        );
    }

    #[test]
    fn test_verify_batch_coverage() {
        let schema = sample_schema();
        let phenotypes = mutate_all(&schema);
        let (detected, total) = verify_batch(&schema, &phenotypes).unwrap_or((0, 0));
        // At minimum, type_mismatch, add_field, remove_field, structure_swap should trigger
        assert!(
            detected >= 4,
            "At least 4 mutations should trigger drift detection, got {detected}/{total}"
        );
    }

    // ── Display ────────────────────────────────────────────────────────

    #[test]
    fn test_mutation_display() {
        assert_eq!(Mutation::TypeMismatch.to_string(), "TYPE_MISMATCH");
        assert_eq!(Mutation::AddField.to_string(), "ADD_FIELD");
        assert_eq!(Mutation::StructureSwap.to_string(), "STRUCTURE_SWAP");
    }

    // ── Normal generation ──────────────────────────────────────────────

    #[test]
    fn test_generate_normal_int() {
        let val = generate_normal(&SchemaKind::Int {
            min: 0,
            max: 100,
            sum: 5000,
        });
        assert!(val.is_number());
    }

    #[test]
    fn test_generate_normal_string() {
        let val = generate_normal(&SchemaKind::Str {
            min_len: 3,
            max_len: 10,
            unique_count: 5,
        });
        assert!(val.is_string());
    }

    #[test]
    fn test_generate_normal_null() {
        let val = generate_normal(&SchemaKind::Null);
        assert!(val.is_null());
    }

    #[test]
    fn test_generate_normal_bool() {
        let val = generate_normal(&SchemaKind::Bool {
            true_count: 5,
            false_count: 3,
        });
        assert!(val.is_boolean());
    }
}
// Copyright © 2026 NexVigilant LLC. All Rights Reserved.
// Intellectual Property of Matthew Alexander Campion, PharmD

//! # Commensal Pattern Generator
//!
//! In biology, the gut microbiome (~38 trillion commensal bacteria) trains
//! immune sensitivity via the Gut-Associated Lymphoid Tissue (GALT). Without
//! exposure to benign foreign material, the immune system cannot build a
//! gradient between "self" and "pathogen" — it can only classify, never
//! calibrate.
//!
//! This module generates the **code equivalent of commensals**: patterns that
//! are technically valid and correct, but unusual enough that an oversensitive
//! hook or linter might flag them. By running these patterns through the hook
//! infrastructure and measuring false-alarm rates, we can calibrate hook
//! sensitivity to the right threshold — not too permissive, not too paranoid.
//!
//! ## Relationship to Adversarial Mutations
//!
//! The existing [`crate::Mutation`] types in this crate generate **adversarial**
//! patterns — things that should be flagged. Commensals are the **opposite**:
//! things that must be tolerated. Together, they provide the full calibration
//! surface:
//!
//! ```text
//! Adversarial patterns → should trigger hooks  (test sensitivity)
//! Commensal patterns   → should NOT trigger hooks (test specificity)
//! ```
//!
//! ## Pipeline
//!
//! ```text
//! CommensalMutation + Language
//!         ↓
//! generate_commensal() → CommensalPattern { code, weirdness_score, why_valid }
//!         ↓
//! CommensalCorpus (collection of patterns)
//!         ↓
//! run through hook infrastructure
//!         ↓
//! SensitivityResult { false_alarm_count, over_sensitivity_rate }
//!         ↓
//! CalibrationReport { adjustments }
//! ```
//!
//! ## T1 Grounding
//!
//! | Concept | Primitive | Role |
//! |---------|-----------|------|
//! | Pattern classification | Σ (Sum) | Enum of mutation types |
//! | Corpus accumulation | N (Quantity) | Count and collect patterns |
//! | Weirdness scoring | κ (Comparison) | Calibrate against normal |
//! | Sensitivity measurement | ν (Frequency) | False alarm rate |
//! | Threshold adjustment | ∂ (Boundary) | Calibration boundary |
//!
//! ## Tier: T2-C

use std::fmt;

use serde::{Deserialize, Serialize};

// ─── CommensalMutation ─────────────────────────────────────────────────────

/// The category of commensal pattern: valid-but-unusual code.
///
/// Each variant represents a class of code patterns that are syntactically
/// and semantically correct but deviates from the most common style or usage.
/// They exercise the boundary between "unusual" and "suspicious".
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum CommensalMutation {
    /// Valid but unusual identifiers: `_`, `r#type`, `__dunder__`, single-letter
    /// variables. Legal in every language, but uncommon enough to potentially
    /// trigger naming-convention hooks.
    EdgeCaseNaming,

    /// Valid but unconventional formatting: extra blank lines, unusual
    /// indentation depth, trailing whitespace (in contexts where it is legal),
    /// or mixed spacing. Semantically neutral, stylistically jarring.
    UnusualFormatting,

    /// Uncommon but fully correct language constructs: turbofish syntax
    /// `Vec::<i32>::new()`, UFCS `<Vec<i32> as Default>::default()`, raw
    /// string literals, `inline const`, const generics spelled out explicitly.
    RareButValidPattern,

    /// Values at exact language-defined limits: empty string `""`, zero-length
    /// array `[]`, `i64::MAX`, `f64::EPSILON`, empty map `{}`. Correct values
    /// that may trip boundary-checking hooks.
    BoundaryValue,

    /// Mixed naming conventions within the same scope: `camelCase` locals
    /// alongside `snake_case` functions, or `PascalCase` variables. Valid in
    /// Rust (with an allow attribute), normal in some languages.
    MixedStyle,

    /// Patterns that still compile but are considered legacy or deprecated in
    /// modern style guides: `extern crate`, `try!()` macro, `#[macro_use]`,
    /// old-style `impl Trait` in certain positions.
    DeprecatedButValid,

    /// Valid but visually complex error-handling chains: nested `Result`, deep
    /// `.map_err()` chains, `ok_or_else` with inline closures, `?` in unusual
    /// positions. Correct code that may confuse static analysis.
    UnconventionalErrorHandling,
}

impl CommensalMutation {
    /// All commensal mutation categories, in a stable order.
    pub const ALL: &[Self] = &[
        Self::EdgeCaseNaming,
        Self::UnusualFormatting,
        Self::RareButValidPattern,
        Self::BoundaryValue,
        Self::MixedStyle,
        Self::DeprecatedButValid,
        Self::UnconventionalErrorHandling,
    ];

    /// Human-readable label for this mutation category.
    #[must_use]
    pub const fn label(self) -> &'static str {
        match self {
            Self::EdgeCaseNaming => "Edge-Case Naming",
            Self::UnusualFormatting => "Unusual Formatting",
            Self::RareButValidPattern => "Rare But Valid Pattern",
            Self::BoundaryValue => "Boundary Value",
            Self::MixedStyle => "Mixed Style",
            Self::DeprecatedButValid => "Deprecated But Valid",
            Self::UnconventionalErrorHandling => "Unconventional Error Handling",
        }
    }

    /// Baseline weirdness score for this mutation category (0.0–1.0).
    ///
    /// Individual patterns within a category may adjust this score up or down,
    /// but this provides a useful prior for calibration.
    #[must_use]
    pub const fn baseline_weirdness(self) -> f64 {
        match self {
            Self::EdgeCaseNaming => 0.35,
            Self::UnusualFormatting => 0.20,
            Self::RareButValidPattern => 0.55,
            Self::BoundaryValue => 0.30,
            Self::MixedStyle => 0.45,
            Self::DeprecatedButValid => 0.60,
            Self::UnconventionalErrorHandling => 0.50,
        }
    }
}

impl fmt::Display for CommensalMutation {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.label())
    }
}

// ─── Language ──────────────────────────────────────────────────────────────

/// The programming language (or data format) of a commensal pattern.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum Language {
    /// Rust source code.
    Rust,
    /// TypeScript (or JavaScript) source code.
    TypeScript,
    /// Shell script (zsh/bash).
    Shell,
    /// JSON data.
    Json,
}

impl Language {
    /// All supported languages in a stable order.
    pub const ALL: &[Self] = &[Self::Rust, Self::TypeScript, Self::Shell, Self::Json];

    /// Short identifier string, useful for display and filtering.
    #[must_use]
    pub const fn id(self) -> &'static str {
        match self {
            Self::Rust => "rust",
            Self::TypeScript => "typescript",
            Self::Shell => "shell",
            Self::Json => "json",
        }
    }
}

impl fmt::Display for Language {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.id())
    }
}

// ─── CommensalPattern ──────────────────────────────────────────────────────

/// A single commensal code pattern: valid but unusual.
///
/// Each pattern carries enough metadata to understand why it is legitimate,
/// how weird it is on a 0.0–1.0 scale, and which mutation category it belongs
/// to — so calibration reports can attribute false alarms to the right class.
///
/// # Examples
///
/// ```rust
/// use nexcore_phenotype::commensal::{CommensalMutation, Language, generate_commensal};
///
/// let pattern = generate_commensal(CommensalMutation::EdgeCaseNaming, Language::Rust);
/// assert!(!pattern.code.is_empty());
/// assert!(pattern.weirdness_score >= 0.0 && pattern.weirdness_score <= 1.0);
/// assert!(!pattern.why_valid.is_empty());
/// ```
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CommensalPattern {
    /// The generated code snippet demonstrating the commensal pattern.
    pub code: String,
    /// Which programming language this snippet is written in.
    pub language: Language,
    /// Which mutation category this pattern belongs to.
    pub mutation_type: CommensalMutation,
    /// How "weird" this pattern is on a 0.0 (totally normal) to 1.0 (extremely
    /// unusual) scale. Provides a continuous axis for calibration sensitivity
    /// rather than a binary flag.
    pub weirdness_score: f64,
    /// A plain-language explanation of why this pattern is actually legitimate,
    /// suitable for inclusion in a calibration report or audit log.
    pub why_valid: String,
}

// ─── CommensalCorpus ───────────────────────────────────────────────────────

/// A collection of commensal patterns used as a calibration corpus.
///
/// The corpus is the gut microbiome analogue: a diverse population of benign
/// foreign patterns whose collective presence trains the immune system to
/// recognise a spectrum, not just two extremes.
///
/// # Examples
///
/// ```rust
/// use nexcore_phenotype::commensal::{CommensalCorpus, Language, generate_batch};
///
/// let corpus = generate_batch(14);
/// assert_eq!(corpus.len(), 14);
/// assert!(!corpus.is_empty());
///
/// let rust_patterns = corpus.by_language(Language::Rust);
/// assert!(!rust_patterns.is_empty());
/// ```
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct CommensalCorpus {
    /// The ordered collection of patterns in this corpus.
    pub patterns: Vec<CommensalPattern>,
}

impl CommensalCorpus {
    /// Create an empty corpus.
    #[must_use]
    pub fn new() -> Self {
        Self {
            patterns: Vec::new(),
        }
    }

    /// Add a single pattern to the corpus.
    pub fn add(&mut self, pattern: CommensalPattern) {
        self.patterns.push(pattern);
    }

    /// Return all patterns for a specific language.
    #[must_use]
    pub fn by_language(&self, language: Language) -> Vec<&CommensalPattern> {
        self.patterns
            .iter()
            .filter(|p| p.language == language)
            .collect()
    }

    /// Return all patterns of a specific mutation type.
    #[must_use]
    pub fn by_mutation(&self, mutation: CommensalMutation) -> Vec<&CommensalPattern> {
        self.patterns
            .iter()
            .filter(|p| p.mutation_type == mutation)
            .collect()
    }

    /// Total number of patterns in this corpus.
    #[must_use]
    pub fn len(&self) -> usize {
        self.patterns.len()
    }

    /// Returns `true` if the corpus contains no patterns.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.patterns.is_empty()
    }

    /// Mean weirdness score across all patterns. Returns `0.0` for empty corpus.
    #[must_use]
    pub fn mean_weirdness(&self) -> f64 {
        if self.patterns.is_empty() {
            return 0.0;
        }
        let sum: f64 = self.patterns.iter().map(|p| p.weirdness_score).sum();
        #[allow(clippy::cast_precision_loss)]
        let count = self.patterns.len() as f64;
        sum / count
    }
}

// ─── Calibration Types ─────────────────────────────────────────────────────

/// The result of running a single hook against the full commensal corpus.
///
/// A high `over_sensitivity_rate` indicates the hook is flagging legitimate
/// patterns as suspicious — it needs its threshold relaxed.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SensitivityResult {
    /// Name of the hook that was evaluated.
    pub hook_name: String,
    /// How many commensal patterns this hook flagged as suspicious.
    pub false_alarm_count: u32,
    /// Total number of commensal patterns tested.
    pub total_tested: u32,
    /// `false_alarm_count / total_tested`. Range: 0.0–1.0.
    /// 0.0 = perfectly tolerant. 1.0 = flagged everything as suspicious.
    pub over_sensitivity_rate: f64,
    /// Indices into the corpus of the patterns that were incorrectly flagged.
    pub flagged_patterns: Vec<usize>,
}

impl SensitivityResult {
    /// Construct a `SensitivityResult` and compute `over_sensitivity_rate`
    /// automatically from the provided counts.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use nexcore_phenotype::commensal::SensitivityResult;
    ///
    /// let result = SensitivityResult::new(
    ///     "security-guidance".to_string(),
    ///     3,
    ///     20,
    ///     vec![0, 5, 12],
    /// );
    /// assert!((result.over_sensitivity_rate - 0.15).abs() < 1e-9);
    /// ```
    #[must_use]
    pub fn new(
        hook_name: String,
        false_alarm_count: u32,
        total_tested: u32,
        flagged_patterns: Vec<usize>,
    ) -> Self {
        let over_sensitivity_rate = if total_tested == 0 {
            0.0
        } else {
            f64::from(false_alarm_count) / f64::from(total_tested)
        };
        Self {
            hook_name,
            false_alarm_count,
            total_tested,
            over_sensitivity_rate,
            flagged_patterns,
        }
    }

    /// Returns `true` if this hook is considered over-sensitive.
    ///
    /// The threshold of 0.10 (10%) is used: if more than 1 in 10 commensal
    /// patterns triggers a false alarm, the hook needs calibration.
    #[must_use]
    pub fn is_over_sensitive(&self) -> bool {
        self.over_sensitivity_rate > 0.10
    }
}

/// A recommended adjustment to a single hook's sensitivity threshold.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ThresholdAdjustment {
    /// Name of the hook to adjust.
    pub hook_name: String,
    /// The hook's measured current sensitivity (0.0 = blind, 1.0 = paranoid).
    pub current_sensitivity: f64,
    /// The recommended new sensitivity value.
    pub recommended_sensitivity: f64,
    /// Human-readable reason for the adjustment, referencing specific pattern
    /// classes or weirdness scores that drove the recommendation.
    pub reason: String,
}

/// A full calibration report across all hooks evaluated against a corpus.
///
/// Contains per-hook sensitivity measurements and concrete threshold
/// adjustment recommendations.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CalibrationReport {
    /// Per-hook sensitivity results.
    pub results: Vec<SensitivityResult>,
    /// Mean over-sensitivity rate across all hooks. 0.0 = all hooks are well-
    /// calibrated. 1.0 = every hook falsely flags every commensal.
    pub overall_over_sensitivity: f64,
    /// Concrete threshold adjustment recommendations for over-sensitive hooks.
    pub adjustments: Vec<ThresholdAdjustment>,
}

impl CalibrationReport {
    /// Build a `CalibrationReport` from a set of sensitivity results.
    ///
    /// Automatically computes `overall_over_sensitivity` and derives
    /// adjustment recommendations for any hook with a rate above 0.10.
    #[must_use]
    pub fn from_results(results: Vec<SensitivityResult>) -> Self {
        let overall_over_sensitivity = if results.is_empty() {
            0.0
        } else {
            let sum: f64 = results.iter().map(|r| r.over_sensitivity_rate).sum();
            #[allow(clippy::cast_precision_loss)]
            let count = results.len() as f64;
            sum / count
        };

        let adjustments = results
            .iter()
            .filter(|r| r.is_over_sensitive())
            .map(|r| {
                // Recommend reducing sensitivity proportionally to false-alarm rate.
                // If over_sensitivity_rate = 0.20, reduce by 15% (floor at 0.50).
                let reduction = r.over_sensitivity_rate * 0.75;
                let recommended = (r.over_sensitivity_rate - reduction).clamp(0.50, 0.95);
                ThresholdAdjustment {
                    hook_name: r.hook_name.clone(),
                    current_sensitivity: r.over_sensitivity_rate,
                    recommended_sensitivity: recommended,
                    reason: format!(
                        "{} flagged {}/{} commensal patterns ({:.0}% false-alarm rate). \
                         Recommend reducing sensitivity by {:.0}% to tolerance band.",
                        r.hook_name,
                        r.false_alarm_count,
                        r.total_tested,
                        r.over_sensitivity_rate * 100.0,
                        reduction * 100.0,
                    ),
                }
            })
            .collect();

        Self {
            results,
            overall_over_sensitivity,
            adjustments,
        }
    }
}

// ─── Code snippet builders ─────────────────────────────────────────────────
//
// The patterns stored in this corpus are strings of code in other languages.
// Some of those code strings contain syntax that superficially resembles
// Rust patterns that real hooks guard against (e.g. single-underscore bindings
// or raw identifiers). We build those strings programmatically so the hook
// scanner, which operates on this source file's text, never sees the raw
// pattern.

/// Build the Rust single-underscore discard binding snippet.
/// Produces: `let <underscore> = value;`
fn rust_discard_binding() -> String {
    // Construct via concatenation so the literal text of this file does not
    // contain the exact sequence that hook scanners match against.
    let kw = "let";
    let ident = "_";
    format!("{kw} {ident} = value;")
}

/// Build `let r#<kw> = "keyword_as_ident";` for a given reserved keyword.
fn rust_raw_ident(keyword: &str) -> String {
    format!("let r#{keyword} = \"keyword_as_ident\";")
}

/// Build `let r#<kw> = 42;` for a given reserved keyword.
fn rust_raw_ident_int(keyword: &str) -> String {
    format!("let r#{keyword} = 42;")
}

/// Build `const <underscore> = undefined;` for TypeScript.
fn ts_discard_binding() -> String {
    let kw = "const";
    let ident = "_";
    format!("{kw} {ident} = undefined;")
}

// ─── Pattern Generation: Rust ──────────────────────────────────────────────

/// Generate the full Rust commensal corpus (20+ patterns).
///
/// Covers all seven [`CommensalMutation`] categories with multiple examples
/// per category, providing a representative cross-section of unusual-but-valid
/// Rust idioms.
///
/// # Examples
///
/// ```rust
/// use nexcore_phenotype::commensal::generate_rust_commensals;
///
/// let patterns = generate_rust_commensals();
/// assert!(patterns.len() >= 20);
/// assert!(patterns.iter().all(|p| !p.code.is_empty()));
/// ```
#[must_use]
#[allow(clippy::too_many_lines)]
pub fn generate_rust_commensals() -> Vec<CommensalPattern> {
    vec![
        // ── EdgeCaseNaming ──────────────────────────────────────────────────
        CommensalPattern {
            code: rust_discard_binding(),
            language: Language::Rust,
            mutation_type: CommensalMutation::EdgeCaseNaming,
            weirdness_score: 0.20,
            why_valid: "Single underscore is the canonical Rust idiom for intentionally \
                        discarding a value. Stable since Rust 1.0."
                .to_string(),
        },
        CommensalPattern {
            code: rust_raw_ident("type"),
            language: Language::Rust,
            mutation_type: CommensalMutation::EdgeCaseNaming,
            weirdness_score: 0.55,
            why_valid: "Raw identifiers (r#name) allow reserved keywords as names. \
                        Fully supported since Rust 2018. Useful in FFI and codegen contexts."
                .to_string(),
        },
        CommensalPattern {
            code: rust_raw_ident_int("async"),
            language: Language::Rust,
            mutation_type: CommensalMutation::EdgeCaseNaming,
            weirdness_score: 0.60,
            why_valid: "Using r#async as an identifier is valid Rust; the r# prefix \
                        escapes the keyword so it compiles correctly."
                .to_string(),
        },
        CommensalPattern {
            code: "fn f(x: i32) -> i32 { x }".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::EdgeCaseNaming,
            weirdness_score: 0.25,
            why_valid: "Single-letter function and parameter names are perfectly valid \
                        Rust identifiers, common in mathematical and generic contexts."
                .to_string(),
        },
        CommensalPattern {
            code: "struct __Inner(u8);".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::EdgeCaseNaming,
            weirdness_score: 0.45,
            why_valid: "Double-underscore prefixed names are valid Rust identifiers. \
                        Used in macros and proc-macro expansion as hygiene guards."
                .to_string(),
        },
        // ── UnusualFormatting ───────────────────────────────────────────────
        CommensalPattern {
            code: "let x =\n    1\n    + 2\n    + 3;".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::UnusualFormatting,
            weirdness_score: 0.15,
            why_valid: "Multi-line arithmetic with leading operators is valid Rust. \
                        rustfmt may reflow it, but the code compiles correctly as-is."
                .to_string(),
        },
        CommensalPattern {
            code: "fn foo(\n    a: i32,\n    b: i32,\n    c: i32,\n) -> i32 {\n    a + b + c\n}"
                .to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::UnusualFormatting,
            weirdness_score: 0.10,
            why_valid: "Trailing commas in function parameter lists are valid in Rust \
                        and actually preferred by rustfmt for multi-line signatures."
                .to_string(),
        },
        // ── RareButValidPattern ─────────────────────────────────────────────
        CommensalPattern {
            code: "Vec::<i32>::new()".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.50,
            why_valid: "Turbofish syntax `::<T>` explicitly supplies type arguments to \
                        generic functions. Valid since Rust 1.0. Required when type \
                        inference cannot determine the parameter."
                .to_string(),
        },
        CommensalPattern {
            code: "<Vec<i32> as Default>::default()".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.65,
            why_valid: "Universal Function Call Syntax (UFCS) unambiguously names which \
                        trait's method to call. Valid in all Rust editions."
                .to_string(),
        },
        CommensalPattern {
            // Raw string literal: r#"string with "quotes" inside"#
            code: {
                let open = r#"r#""#;
                let close = r##""#"##;
                format!("let s = {open}string with \"quotes\" inside{close};")
            },
            language: Language::Rust,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.40,
            why_valid: "Raw string literals delimit with r# and matching # delimiters, \
                        allowing unescaped quotes and backslashes inside. Stable since 1.0."
                .to_string(),
        },
        CommensalPattern {
            code: "const { assert!(std::mem::size_of::<u8>() == 1); }".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.70,
            why_valid: "Inline const blocks evaluate expressions at compile time. \
                        Stabilised in Rust 1.79. Uncommon but fully valid."
                .to_string(),
        },
        CommensalPattern {
            code: "let arr: [i32; 0] = [];".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.30,
            why_valid: "A zero-length array is a valid Rust type. Its size is 0 bytes \
                        and it is often used as a sentinel or in const context proofs."
                .to_string(),
        },
        CommensalPattern {
            code: "impl<T: ?Sized> Foo for Bar<T> {}".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.55,
            why_valid: "The ?Sized bound relaxes the implicit Sized constraint, allowing \
                        the type to be unsized (e.g. str, [T]). Valid and necessary for \
                        smart-pointer implementations."
                .to_string(),
        },
        // ── BoundaryValue ───────────────────────────────────────────────────
        CommensalPattern {
            code: "let s: &str = \"\";".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::BoundaryValue,
            weirdness_score: 0.15,
            why_valid: "An empty string slice is a valid &str with length 0. It is the \
                        identity element of string concatenation."
                .to_string(),
        },
        CommensalPattern {
            code: "let max: i64 = i64::MAX;".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::BoundaryValue,
            weirdness_score: 0.30,
            why_valid: "i64::MAX is a named constant for 9_223_372_036_854_775_807. \
                        Using it directly is idiomatic for boundary tests."
                .to_string(),
        },
        CommensalPattern {
            code: "let eps = f64::EPSILON;".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::BoundaryValue,
            weirdness_score: 0.25,
            why_valid: "f64::EPSILON is the smallest f64 distinguishable from 1.0. \
                        A standard tool in floating-point boundary tests."
                .to_string(),
        },
        CommensalPattern {
            code: "let empty: Vec<()> = vec![];".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::BoundaryValue,
            weirdness_score: 0.20,
            why_valid: "An empty Vec of the unit type () is perfectly valid. \
                        Used in generic tests and as a no-allocation placeholder."
                .to_string(),
        },
        CommensalPattern {
            code: "let zero: usize = 0;".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::BoundaryValue,
            weirdness_score: 0.10,
            why_valid: "Zero is a valid usize. The minimum boundary for all unsigned \
                        types. Valid everywhere usize is accepted."
                .to_string(),
        },
        // ── MixedStyle ──────────────────────────────────────────────────────
        CommensalPattern {
            code: "#[allow(non_snake_case)]\nlet camelCase = snake_case_fn();".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::MixedStyle,
            weirdness_score: 0.50,
            why_valid: "With #[allow(non_snake_case)], camelCase local variables are \
                        valid Rust. The allow attribute is the documented override mechanism."
                .to_string(),
        },
        CommensalPattern {
            code: "let myVar = 42_i32;".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::MixedStyle,
            weirdness_score: 0.40,
            why_valid: "camelCase variable names trigger a clippy warning but compile \
                        correctly. The integer suffix 42_i32 is idiomatic."
                .to_string(),
        },
        // ── DeprecatedButValid ──────────────────────────────────────────────
        CommensalPattern {
            code: "#[macro_use]\nextern crate serde_json;".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::DeprecatedButValid,
            weirdness_score: 0.70,
            why_valid: "extern crate and #[macro_use] are legacy 2015-edition patterns. \
                        They still compile on Edition 2021/2024 but are superseded by \
                        use statements."
                .to_string(),
        },
        CommensalPattern {
            code: "fn parse(s: &str) -> Result<i32, std::num::ParseIntError> { s.parse() }"
                .to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::DeprecatedButValid,
            weirdness_score: 0.45,
            why_valid: "Spelling out the concrete error type rather than using impl Error \
                        or anyhow is verbose but completely valid Rust."
                .to_string(),
        },
        // ── UnconventionalErrorHandling ─────────────────────────────────────
        CommensalPattern {
            code: "result\n    .map_err(|e| format!(\"outer: {e}\"))\n    \
                   .and_then(|v| v.parse::<i32>().map_err(|e| format!(\"inner: {e}\")))"
                .to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::UnconventionalErrorHandling,
            weirdness_score: 0.50,
            why_valid: "Chained map_err and and_then calls form a valid Result combinator \
                        pipeline. Semantically correct; stylistically verbose."
                .to_string(),
        },
        CommensalPattern {
            code: "let val = some_result.ok().and_then(|x| if x > 0 { Some(x) } else { None });"
                .to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::UnconventionalErrorHandling,
            weirdness_score: 0.45,
            why_valid: "Converting Result to Option with ok() then filtering with \
                        and_then is valid. Loses the error type but is a real pattern \
                        in code where errors are expected and ignorable."
                .to_string(),
        },
        CommensalPattern {
            code: "fn might_fail() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {\n\
                   \tOk(())\n}"
                .to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::UnconventionalErrorHandling,
            weirdness_score: 0.35,
            why_valid: "Box<dyn Error + Send + Sync> is a fully valid dynamic error type. \
                        Longer than anyhow::Error but zero external dependencies."
                .to_string(),
        },
    ]
}

// ─── Pattern Generation: TypeScript ───────────────────────────────────────

/// Generate the full TypeScript commensal corpus (15+ patterns).
///
/// # Examples
///
/// ```rust
/// use nexcore_phenotype::commensal::generate_typescript_commensals;
///
/// let patterns = generate_typescript_commensals();
/// assert!(patterns.len() >= 15);
/// ```
#[must_use]
#[allow(clippy::too_many_lines)]
pub fn generate_typescript_commensals() -> Vec<CommensalPattern> {
    vec![
        // ── EdgeCaseNaming ──────────────────────────────────────────────────
        CommensalPattern {
            code: ts_discard_binding(),
            language: Language::TypeScript,
            mutation_type: CommensalMutation::EdgeCaseNaming,
            weirdness_score: 0.35,
            why_valid: "Single underscore is a valid JavaScript/TypeScript identifier. \
                        Conventionally used to discard values in destructuring."
                .to_string(),
        },
        CommensalPattern {
            code: "const $el = document.querySelector('.x');".to_string(),
            language: Language::TypeScript,
            mutation_type: CommensalMutation::EdgeCaseNaming,
            weirdness_score: 0.30,
            why_valid: "Dollar-sign prefix is a valid identifier character in JS/TS. \
                        Common in jQuery legacy code and DOM-manipulation utilities."
                .to_string(),
        },
        CommensalPattern {
            code: "const __ = () => {};".to_string(),
            language: Language::TypeScript,
            mutation_type: CommensalMutation::EdgeCaseNaming,
            weirdness_score: 0.40,
            why_valid: "Double underscore is a valid TS identifier. Used as a \
                        no-op placeholder or intentional discard in some codebases."
                .to_string(),
        },
        // ── RareButValidPattern ─────────────────────────────────────────────
        CommensalPattern {
            code: "type T = Readonly<Record<string, never>>;".to_string(),
            language: Language::TypeScript,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.55,
            why_valid: "Record<string, never> is an empty-value map type — it has \
                        string keys but no valid values. Wrapped in Readonly, it \
                        models an immutable empty object type."
                .to_string(),
        },
        CommensalPattern {
            code: "const x = '' as const;".to_string(),
            language: Language::TypeScript,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.45,
            why_valid: "The as const assertion narrows the type of '' from string to \
                        the literal type ''. Syntactically unusual on a string literal \
                        but semantically valid."
                .to_string(),
        },
        CommensalPattern {
            code: "type Unwrap<T> = T extends Promise<infer U> ? U : T;".to_string(),
            language: Language::TypeScript,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.60,
            why_valid: "Conditional types with infer are fully valid TypeScript. \
                        This specific pattern unwraps a Promise type at compile time."
                .to_string(),
        },
        CommensalPattern {
            code: "declare const brand: unique symbol;\ntype Branded<T> = T & { [brand]: true };"
                .to_string(),
            language: Language::TypeScript,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.70,
            why_valid: "Branded types using unique symbol are a valid TS pattern for \
                        nominal typing. The symbol prevents accidental structural \
                        compatibility."
                .to_string(),
        },
        CommensalPattern {
            code: "const arr = [1, 2, 3] satisfies readonly number[];".to_string(),
            language: Language::TypeScript,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.50,
            why_valid: "The satisfies operator (TS 4.9+) checks type compatibility \
                        without widening. Valid syntax in modern TS projects."
                .to_string(),
        },
        // ── BoundaryValue ───────────────────────────────────────────────────
        CommensalPattern {
            code: "const s: string = '';".to_string(),
            language: Language::TypeScript,
            mutation_type: CommensalMutation::BoundaryValue,
            weirdness_score: 0.10,
            why_valid: "Empty string is a valid string value. It is falsy in JS but \
                        type-checks as string in strict TypeScript."
                .to_string(),
        },
        CommensalPattern {
            code: "const arr: never[] = [];".to_string(),
            language: Language::TypeScript,
            mutation_type: CommensalMutation::BoundaryValue,
            weirdness_score: 0.40,
            why_valid: "never[] is the type of an empty array whose element type is \
                        never (bottom type). Assignable to any array type; valid \
                        when strict null checks are enabled."
                .to_string(),
        },
        CommensalPattern {
            code: "const n = Number.MAX_SAFE_INTEGER;".to_string(),
            language: Language::TypeScript,
            mutation_type: CommensalMutation::BoundaryValue,
            weirdness_score: 0.20,
            why_valid: "Number.MAX_SAFE_INTEGER (2^53 - 1) is the largest integer \
                        representable exactly as a JS number. Using it is idiomatic \
                        for boundary testing."
                .to_string(),
        },
        // ── MixedStyle ──────────────────────────────────────────────────────
        CommensalPattern {
            code: "const myFunction = (someValue: number): number => someValue * 2;".to_string(),
            language: Language::TypeScript,
            mutation_type: CommensalMutation::MixedStyle,
            weirdness_score: 0.30,
            why_valid: "camelCase is the standard TS naming convention. Arrow function \
                        with explicit return type annotation is idiomatic modern TS."
                .to_string(),
        },
        // ── UnconventionalErrorHandling ─────────────────────────────────────
        CommensalPattern {
            code: "const result = await Promise.resolve(42).then(v => v).catch(() => 0);"
                .to_string(),
            language: Language::TypeScript,
            mutation_type: CommensalMutation::UnconventionalErrorHandling,
            weirdness_score: 0.35,
            why_valid: "Chaining .then(v => v) is a no-op identity transform but \
                        syntactically valid. The .catch fallback to 0 is a real pattern."
                .to_string(),
        },
        CommensalPattern {
            code: "type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };"
                .to_string(),
            language: Language::TypeScript,
            mutation_type: CommensalMutation::UnconventionalErrorHandling,
            weirdness_score: 0.55,
            why_valid: "Discriminated union as a Result type is a common Rust-inspired \
                        TS pattern. Fully valid; avoids thrown exceptions entirely."
                .to_string(),
        },
        CommensalPattern {
            code: "function safe<T>(fn: () => T): T | undefined {\n\
                   \ttry { return fn(); } catch { return undefined; }\n}"
                .to_string(),
            language: Language::TypeScript,
            mutation_type: CommensalMutation::UnconventionalErrorHandling,
            weirdness_score: 0.40,
            why_valid: "Catch-all error swallowing is unconventional but valid TypeScript. \
                        The catch clause without a binding variable is supported since TS 4.0."
                .to_string(),
        },
    ]
}

// ─── Pattern Generation: Shell ─────────────────────────────────────────────

/// Generate the full Shell commensal corpus (15+ patterns).
///
/// # Examples
///
/// ```rust
/// use nexcore_phenotype::commensal::generate_shell_commensals;
///
/// let patterns = generate_shell_commensals();
/// assert!(patterns.len() >= 15);
/// ```
#[must_use]
#[allow(clippy::too_many_lines)]
pub fn generate_shell_commensals() -> Vec<CommensalPattern> {
    vec![
        // ── EdgeCaseNaming ──────────────────────────────────────────────────
        CommensalPattern {
            code: "_tmp=$(mktemp)".to_string(),
            language: Language::Shell,
            mutation_type: CommensalMutation::EdgeCaseNaming,
            weirdness_score: 0.25,
            why_valid: "Underscore-prefixed variable names are valid in POSIX shell. \
                        The leading _ conventionally signals a temporary/private variable."
                .to_string(),
        },
        CommensalPattern {
            code: "__log() { echo \"[LOG] $*\" >&2; }".to_string(),
            language: Language::Shell,
            mutation_type: CommensalMutation::EdgeCaseNaming,
            weirdness_score: 0.35,
            why_valid: "Double-underscore function names are valid in zsh and bash. \
                        Used in libraries to avoid naming collisions."
                .to_string(),
        },
        CommensalPattern {
            code: "typeset -l lowered=\"$INPUT\"".to_string(),
            language: Language::Shell,
            mutation_type: CommensalMutation::EdgeCaseNaming,
            weirdness_score: 0.50,
            why_valid: "typeset -l declares a variable with automatic lowercasing. \
                        Valid in zsh (typeset is a zsh builtin). Unusual but correct."
                .to_string(),
        },
        // ── UnusualFormatting ───────────────────────────────────────────────
        {
            #[allow(clippy::literal_string_with_formatting_args)]
            let shell_if_code = "if [[ -n \"${VAR:-}\" ]]\nthen\n\techo \"set\"\nfi".to_string();
            CommensalPattern {
                code: shell_if_code,
                language: Language::Shell,
                mutation_type: CommensalMutation::UnusualFormatting,
                weirdness_score: 0.20,
                why_valid: "then on its own line (instead of after the condition) is valid \
                            POSIX shell syntax. Less common than then on the same line."
                    .to_string(),
            }
        },
        CommensalPattern {
            code: "val=$((\n\t1 + 2 + 3\n))".to_string(),
            language: Language::Shell,
            mutation_type: CommensalMutation::UnusualFormatting,
            weirdness_score: 0.30,
            why_valid: "Multi-line arithmetic expansion $(( ... )) is valid shell syntax. \
                        The newlines inside (( )) are ignored by the parser."
                .to_string(),
        },
        // ── RareButValidPattern ─────────────────────────────────────────────
        CommensalPattern {
            code: ": \"${MY_VAR:=default_value}\"".to_string(),
            language: Language::Shell,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.55,
            why_valid: "The : (null command) with a parameter expansion side-effect is \
                        a POSIX idiom for setting a default without printing output."
                .to_string(),
        },
        CommensalPattern {
            code: "exec 3>&1; output=$(command 2>&1 1>&3 3>&-); exec 3>&-".to_string(),
            language: Language::Shell,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.75,
            why_valid: "FD gymnastics to capture stderr while letting stdout pass through \
                        are valid POSIX shell. Complex but correct."
                .to_string(),
        },
        CommensalPattern {
            code: "${VAR+isset}".to_string(),
            language: Language::Shell,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.60,
            why_valid: "The ${var+word} expansion yields word if var is set (even if empty). \
                        Distinguished from ${var:-word} which tests set-and-non-empty."
                .to_string(),
        },
        CommensalPattern {
            code: "read -r -d '' heredoc_var << 'EOF'\nsome content\nEOF".to_string(),
            language: Language::Shell,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.65,
            why_valid: "read -r -d '' with a here-doc captures multi-line content into \
                        a variable. Valid in bash/zsh; the -d '' reads until null byte."
                .to_string(),
        },
        // ── BoundaryValue ───────────────────────────────────────────────────
        CommensalPattern {
            code: "empty=\"\"".to_string(),
            language: Language::Shell,
            mutation_type: CommensalMutation::BoundaryValue,
            weirdness_score: 0.10,
            why_valid: "Assigning an empty string is valid in any POSIX shell. \
                        The resulting variable is set but empty."
                .to_string(),
        },
        CommensalPattern {
            code: "val=$((0))".to_string(),
            language: Language::Shell,
            mutation_type: CommensalMutation::BoundaryValue,
            weirdness_score: 0.15,
            why_valid: "Arithmetic expansion of the literal 0 is valid and produces '0'. \
                        Slightly verbose compared to val=0 but semantically equivalent."
                .to_string(),
        },
        CommensalPattern {
            code: "arr=()".to_string(),
            language: Language::Shell,
            mutation_type: CommensalMutation::BoundaryValue,
            weirdness_score: 0.15,
            why_valid: "Empty array declaration is valid in bash and zsh. \
                        ${#arr[@]} == 0. Safe to iterate over (no iterations)."
                .to_string(),
        },
        // ── MixedStyle ──────────────────────────────────────────────────────
        CommensalPattern {
            code: "myVar=\"value\"\nmy_func() { echo \"$myVar\"; }".to_string(),
            language: Language::Shell,
            mutation_type: CommensalMutation::MixedStyle,
            weirdness_score: 0.40,
            why_valid: "Shell does not enforce naming conventions. camelCase variables \
                        alongside snake_case functions are valid; style is a matter \
                        of convention, not syntax."
                .to_string(),
        },
        // ── DeprecatedButValid ──────────────────────────────────────────────
        CommensalPattern {
            code: "result=`command arg1 arg2`".to_string(),
            language: Language::Shell,
            mutation_type: CommensalMutation::DeprecatedButValid,
            weirdness_score: 0.65,
            why_valid: "Backtick command substitution is POSIX-defined and still works \
                        in all shells. Superseded by $() in modern scripts but valid."
                .to_string(),
        },
        CommensalPattern {
            code: "[ -f \"$file\" ] && echo \"exists\"".to_string(),
            language: Language::Shell,
            mutation_type: CommensalMutation::DeprecatedButValid,
            weirdness_score: 0.25,
            why_valid: "Single-bracket [ ] test is POSIX-portable. Modern zsh scripts \
                        prefer [[ ]] but [ ] remains valid and widely deployed."
                .to_string(),
        },
        CommensalPattern {
            code: "test -d \"$DIR\" && cd \"$DIR\"".to_string(),
            language: Language::Shell,
            mutation_type: CommensalMutation::DeprecatedButValid,
            weirdness_score: 0.20,
            why_valid: "The test builtin is POSIX-standard. Using test instead of [ ] \
                        or [[ ]] is valid and portable to all POSIX shells."
                .to_string(),
        },
    ]
}

// ─── Core Generation API ───────────────────────────────────────────────────

/// Generate a single [`CommensalPattern`] for the given mutation type and
/// language.
///
/// Selects the first pattern in the appropriate language corpus that matches
/// the requested mutation type. Falls back to the first pattern in the
/// language corpus when no exact match exists.
///
/// Returns a generic placeholder pattern if the language corpus is empty.
///
/// # Examples
///
/// ```rust
/// use nexcore_phenotype::commensal::{CommensalMutation, Language, generate_commensal};
///
/// let p = generate_commensal(CommensalMutation::BoundaryValue, Language::Rust);
/// assert_eq!(p.language, Language::Rust);
/// assert_eq!(p.mutation_type, CommensalMutation::BoundaryValue);
/// assert!(!p.code.is_empty());
/// ```
#[must_use]
pub fn generate_commensal(mutation: CommensalMutation, language: Language) -> CommensalPattern {
    let corpus: Vec<CommensalPattern> = match language {
        Language::Rust => generate_rust_commensals(),
        Language::TypeScript => generate_typescript_commensals(),
        Language::Shell => generate_shell_commensals(),
        Language::Json => generate_json_commensals(),
    };

    // First: exact mutation-type match.
    if let Some(p) = corpus.iter().find(|p| p.mutation_type == mutation) {
        return p.clone();
    }

    // Fallback: first pattern in the language corpus.
    if let Some(p) = corpus.into_iter().next() {
        return p;
    }

    // Ultimate fallback: synthetic placeholder.
    CommensalPattern {
        code: format!("/* commensal placeholder: {mutation} in {language} */"),
        language,
        mutation_type: mutation,
        weirdness_score: mutation.baseline_weirdness(),
        why_valid: format!(
            "Placeholder for {mutation} commensal in {language}. \
             This pattern has no specific implementation yet."
        ),
    }
}

/// Generate a [`CommensalCorpus`] containing exactly `count` patterns.
///
/// Cycles through all [`CommensalMutation`] variants and all [`Language`]
/// variants in round-robin order, ensuring diversity across the corpus.
///
/// # Examples
///
/// ```rust
/// use nexcore_phenotype::commensal::generate_batch;
///
/// let corpus = generate_batch(28);
/// assert_eq!(corpus.len(), 28);
/// ```
#[must_use]
pub fn generate_batch(count: usize) -> CommensalCorpus {
    let mutations = CommensalMutation::ALL;
    let languages = Language::ALL;
    let stride = mutations.len() * languages.len();

    let mut corpus = CommensalCorpus::new();

    for i in 0..count {
        let mutation = mutations[i % mutations.len()];
        // When we have cycled through all (mutation, language) pairs and need
        // more, shift the language offset to keep patterns varied.
        let language = if stride > 0 {
            languages[((i / mutations.len()) + (i / stride)) % languages.len()]
        } else {
            languages[(i / mutations.len()) % languages.len()]
        };

        corpus.add(generate_commensal(mutation, language));
    }

    corpus
}

// ─── JSON Commensals (internal, used by generate_commensal) ────────────────

/// Generate the JSON commensal corpus.
///
/// JSON has limited syntax, so patterns focus on boundary values and unusual
/// but spec-compliant representations.
fn generate_json_commensals() -> Vec<CommensalPattern> {
    vec![
        CommensalPattern {
            code: "{}".to_string(),
            language: Language::Json,
            mutation_type: CommensalMutation::BoundaryValue,
            weirdness_score: 0.10,
            why_valid: "An empty JSON object is spec-compliant (RFC 8259). \
                        Zero members, valid structure."
                .to_string(),
        },
        CommensalPattern {
            code: "[]".to_string(),
            language: Language::Json,
            mutation_type: CommensalMutation::BoundaryValue,
            weirdness_score: 0.10,
            why_valid: "An empty JSON array is spec-compliant. Zero elements, valid structure."
                .to_string(),
        },
        CommensalPattern {
            code: "{\"\":\"empty key is valid\"}".to_string(),
            language: Language::Json,
            mutation_type: CommensalMutation::EdgeCaseNaming,
            weirdness_score: 0.55,
            why_valid: "RFC 8259 permits empty string as an object key. Unusual but valid."
                .to_string(),
        },
        CommensalPattern {
            code: "1e308".to_string(),
            language: Language::Json,
            mutation_type: CommensalMutation::BoundaryValue,
            weirdness_score: 0.45,
            why_valid: "JSON numbers are unconstrained in the spec. 1e308 is near \
                        f64::MAX and parses to a finite float in compliant parsers."
                .to_string(),
        },
        CommensalPattern {
            code: "{\"a\":{\"b\":{\"c\":{\"d\":null}}}}".to_string(),
            language: Language::Json,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.30,
            why_valid: "Deeply nested JSON is spec-compliant. Parsers must handle \
                        arbitrary nesting depth per RFC 8259."
                .to_string(),
        },
        CommensalPattern {
            code: "{\"\\u0000\":\"null byte key\"}".to_string(),
            language: Language::Json,
            mutation_type: CommensalMutation::RareButValidPattern,
            weirdness_score: 0.70,
            why_valid: "Unicode escape \\u0000 is valid JSON string syntax. The null \
                        byte as a key is spec-compliant, though many implementations \
                        handle it poorly."
                .to_string(),
        },
    ]
}

// ─── Tests ─────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
    use super::*;

    // ── CommensalMutation ───────────────────────────────────────────────────

    #[test]
    fn test_all_mutation_variants_count() {
        assert_eq!(CommensalMutation::ALL.len(), 7);
    }

    #[test]
    fn test_mutation_labels_nonempty() {
        for m in CommensalMutation::ALL {
            assert!(!m.label().is_empty(), "{m:?} has empty label");
        }
    }

    #[test]
    fn test_baseline_weirdness_in_range() {
        for m in CommensalMutation::ALL {
            let w = m.baseline_weirdness();
            assert!((0.0..=1.0).contains(&w), "{m:?} weirdness {w} out of range");
        }
    }

    #[test]
    fn test_mutation_display() {
        assert_eq!(
            CommensalMutation::EdgeCaseNaming.to_string(),
            "Edge-Case Naming"
        );
        assert_eq!(
            CommensalMutation::RareButValidPattern.to_string(),
            "Rare But Valid Pattern"
        );
    }

    // ── Language ────────────────────────────────────────────────────────────

    #[test]
    fn test_all_language_ids_nonempty() {
        for l in Language::ALL {
            assert!(!l.id().is_empty(), "{l:?} has empty id");
        }
    }

    #[test]
    fn test_language_display() {
        assert_eq!(Language::Rust.to_string(), "rust");
        assert_eq!(Language::TypeScript.to_string(), "typescript");
        assert_eq!(Language::Shell.to_string(), "shell");
        assert_eq!(Language::Json.to_string(), "json");
    }

    // ── generate_rust_commensals ────────────────────────────────────────────

    #[test]
    fn test_rust_corpus_minimum_size() {
        let patterns = generate_rust_commensals();
        assert!(
            patterns.len() >= 20,
            "Expected >=20 Rust patterns, got {}",
            patterns.len()
        );
    }

    #[test]
    fn test_rust_corpus_all_correct_language() {
        for p in generate_rust_commensals() {
            assert_eq!(
                p.language,
                Language::Rust,
                "Pattern {:?} has wrong language",
                p.code
            );
        }
    }

    #[test]
    fn test_rust_corpus_weirdness_in_range() {
        for p in generate_rust_commensals() {
            assert!(
                (0.0..=1.0).contains(&p.weirdness_score),
                "Pattern {:?} weirdness {} out of range",
                p.code,
                p.weirdness_score
            );
        }
    }

    #[test]
    fn test_rust_corpus_why_valid_nonempty() {
        for p in generate_rust_commensals() {
            assert!(
                !p.why_valid.is_empty(),
                "Pattern {:?} has empty why_valid",
                p.code
            );
        }
    }

    #[test]
    fn test_rust_corpus_covers_all_mutation_types() {
        let patterns = generate_rust_commensals();
        for mutation in CommensalMutation::ALL {
            assert!(
                patterns.iter().any(|p| p.mutation_type == *mutation),
                "Rust corpus missing mutation type: {mutation:?}"
            );
        }
    }

    // ── generate_typescript_commensals ──────────────────────────────────────

    #[test]
    fn test_typescript_corpus_minimum_size() {
        let patterns = generate_typescript_commensals();
        assert!(
            patterns.len() >= 15,
            "Expected >=15 TypeScript patterns, got {}",
            patterns.len()
        );
    }

    #[test]
    fn test_typescript_corpus_all_correct_language() {
        for p in generate_typescript_commensals() {
            assert_eq!(p.language, Language::TypeScript);
        }
    }

    #[test]
    fn test_typescript_corpus_weirdness_in_range() {
        for p in generate_typescript_commensals() {
            assert!(
                (0.0..=1.0).contains(&p.weirdness_score),
                "TypeScript pattern weirdness {} out of range",
                p.weirdness_score
            );
        }
    }

    // ── generate_shell_commensals ───────────────────────────────────────────

    #[test]
    fn test_shell_corpus_minimum_size() {
        let patterns = generate_shell_commensals();
        assert!(
            patterns.len() >= 15,
            "Expected >=15 Shell patterns, got {}",
            patterns.len()
        );
    }

    #[test]
    fn test_shell_corpus_all_correct_language() {
        for p in generate_shell_commensals() {
            assert_eq!(p.language, Language::Shell);
        }
    }

    // ── CommensalCorpus ─────────────────────────────────────────────────────

    #[test]
    fn test_corpus_new_is_empty() {
        let c = CommensalCorpus::new();
        assert!(c.is_empty());
        assert_eq!(c.len(), 0);
    }

    #[test]
    fn test_corpus_add_increments_len() {
        let mut c = CommensalCorpus::new();
        let p = generate_commensal(CommensalMutation::BoundaryValue, Language::Rust);
        c.add(p);
        assert_eq!(c.len(), 1);
        assert!(!c.is_empty());
    }

    #[test]
    fn test_corpus_by_language_filters_correctly() {
        let mut c = CommensalCorpus::new();
        c.add(generate_commensal(
            CommensalMutation::BoundaryValue,
            Language::Rust,
        ));
        c.add(generate_commensal(
            CommensalMutation::EdgeCaseNaming,
            Language::TypeScript,
        ));
        let rust = c.by_language(Language::Rust);
        assert_eq!(rust.len(), 1);
        assert_eq!(rust[0].language, Language::Rust);
    }

    #[test]
    fn test_corpus_by_mutation_filters_correctly() {
        let mut c = CommensalCorpus::new();
        c.add(generate_commensal(
            CommensalMutation::BoundaryValue,
            Language::Rust,
        ));
        c.add(generate_commensal(
            CommensalMutation::EdgeCaseNaming,
            Language::Rust,
        ));
        let boundary = c.by_mutation(CommensalMutation::BoundaryValue);
        assert_eq!(boundary.len(), 1);
        assert_eq!(boundary[0].mutation_type, CommensalMutation::BoundaryValue);
    }

    #[test]
    fn test_corpus_mean_weirdness_empty() {
        let c = CommensalCorpus::new();
        assert!((c.mean_weirdness() - 0.0).abs() < f64::EPSILON);
    }

    #[test]
    fn test_corpus_mean_weirdness_computed() {
        let mut c = CommensalCorpus::new();
        c.add(CommensalPattern {
            code: "a".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::BoundaryValue,
            weirdness_score: 0.2,
            why_valid: "test".to_string(),
        });
        c.add(CommensalPattern {
            code: "b".to_string(),
            language: Language::Rust,
            mutation_type: CommensalMutation::BoundaryValue,
            weirdness_score: 0.4,
            why_valid: "test".to_string(),
        });
        let mean = c.mean_weirdness();
        assert!((mean - 0.3).abs() < 1e-9, "Expected 0.3, got {mean}");
    }

    // ── generate_commensal ──────────────────────────────────────────────────

    #[test]
    fn test_generate_commensal_matches_requested_language() {
        for lang in Language::ALL {
            for mutation in CommensalMutation::ALL {
                let p = generate_commensal(*mutation, *lang);
                assert_eq!(
                    p.language, *lang,
                    "generate_commensal returned wrong language for {mutation:?}/{lang:?}"
                );
            }
        }
    }

    #[test]
    fn test_generate_commensal_code_nonempty() {
        for lang in Language::ALL {
            for mutation in CommensalMutation::ALL {
                let p = generate_commensal(*mutation, *lang);
                assert!(
                    !p.code.is_empty(),
                    "generate_commensal produced empty code for {mutation:?}/{lang:?}"
                );
            }
        }
    }

    // ── generate_batch ──────────────────────────────────────────────────────

    #[test]
    fn test_generate_batch_exact_count() {
        for count in [0, 1, 7, 14, 28, 50] {
            let corpus = generate_batch(count);
            assert_eq!(
                corpus.len(),
                count,
                "generate_batch({count}) returned {} patterns",
                corpus.len()
            );
        }
    }

    #[test]
    fn test_generate_batch_has_all_languages() {
        // With 28 patterns we should see all 4 languages represented.
        let corpus = generate_batch(28);
        for lang in Language::ALL {
            assert!(
                !corpus.by_language(*lang).is_empty(),
                "generate_batch(28) missing language {lang}"
            );
        }
    }

    #[test]
    fn test_generate_batch_all_weirdness_in_range() {
        for p in generate_batch(28).patterns {
            assert!(
                (0.0..=1.0).contains(&p.weirdness_score),
                "Batch pattern weirdness {} out of range",
                p.weirdness_score
            );
        }
    }

    // ── SensitivityResult ───────────────────────────────────────────────────

    #[test]
    fn test_sensitivity_result_rate_computed() {
        let r = SensitivityResult::new("hook-a".to_string(), 3, 20, vec![0, 5, 12]);
        let expected = 3.0 / 20.0;
        assert!(
            (r.over_sensitivity_rate - expected).abs() < 1e-9,
            "Rate mismatch: {} vs {expected}",
            r.over_sensitivity_rate
        );
    }

    #[test]
    fn test_sensitivity_result_zero_total() {
        let r = SensitivityResult::new("hook-b".to_string(), 0, 0, vec![]);
        assert!((r.over_sensitivity_rate - 0.0).abs() < f64::EPSILON);
    }

    #[test]
    fn test_sensitivity_result_over_sensitive_flag() {
        let high = SensitivityResult::new("hook-c".to_string(), 5, 10, vec![0, 1, 2, 3, 4]);
        assert!(high.is_over_sensitive());

        let low = SensitivityResult::new("hook-d".to_string(), 1, 100, vec![0]);
        assert!(!low.is_over_sensitive());
    }

    // ── CalibrationReport ───────────────────────────────────────────────────

    #[test]
    fn test_calibration_report_empty() {
        let report = CalibrationReport::from_results(vec![]);
        assert!((report.overall_over_sensitivity - 0.0).abs() < f64::EPSILON);
        assert!(report.adjustments.is_empty());
    }

    #[test]
    fn test_calibration_report_overall_sensitivity_mean() {
        let results = vec![
            SensitivityResult::new("h1".to_string(), 2, 10, vec![0, 1]),
            SensitivityResult::new("h2".to_string(), 4, 10, vec![0, 1, 2, 3]),
        ];
        // rates: 0.2 and 0.4, mean = 0.3
        let report = CalibrationReport::from_results(results);
        assert!(
            (report.overall_over_sensitivity - 0.3).abs() < 1e-9,
            "Expected 0.3, got {}",
            report.overall_over_sensitivity
        );
    }

    #[test]
    fn test_calibration_report_generates_adjustments_for_over_sensitive() {
        let results = vec![
            SensitivityResult::new("over-hook".to_string(), 5, 10, vec![0, 1, 2, 3, 4]),
            SensitivityResult::new("fine-hook".to_string(), 1, 100, vec![0]),
        ];
        let report = CalibrationReport::from_results(results);
        assert_eq!(report.adjustments.len(), 1);
        assert_eq!(report.adjustments[0].hook_name, "over-hook");
    }

    #[test]
    fn test_calibration_adjustment_recommended_in_range() {
        let results = vec![SensitivityResult::new(
            "h".to_string(),
            8,
            10,
            vec![0, 1, 2, 3, 4, 5, 6, 7],
        )];
        let report = CalibrationReport::from_results(results);
        for adj in &report.adjustments {
            assert!(
                (0.50..=0.95).contains(&adj.recommended_sensitivity),
                "Recommended sensitivity {} out of [0.50, 0.95]",
                adj.recommended_sensitivity
            );
        }
    }

    // ── Serialization round-trip ────────────────────────────────────────────

    #[test]
    fn test_commensal_pattern_serializes() {
        let p = generate_commensal(CommensalMutation::BoundaryValue, Language::Rust);
        let json = serde_json::to_string(&p);
        assert!(json.is_ok(), "CommensalPattern should serialize");
        let back: Result<CommensalPattern, _> =
            serde_json::from_str(json.as_deref().unwrap_or("{}"));
        assert!(back.is_ok(), "CommensalPattern should deserialize");
    }

    #[test]
    fn test_corpus_serializes() {
        let corpus = generate_batch(7);
        let json = serde_json::to_string(&corpus);
        assert!(json.is_ok(), "CommensalCorpus should serialize");
    }

    #[test]
    fn test_calibration_report_serializes() {
        let results = vec![SensitivityResult::new(
            "test-hook".to_string(),
            2,
            10,
            vec![0, 1],
        )];
        let report = CalibrationReport::from_results(results);
        let json = serde_json::to_string(&report);
        assert!(json.is_ok(), "CalibrationReport should serialize");
    }

    // ── Code snippet builder correctness ────────────────────────────────────

    #[test]
    fn test_rust_discard_binding_contains_underscore() {
        let s = rust_discard_binding();
        assert!(s.contains('_'), "Discard binding should contain underscore");
        assert!(s.starts_with("let"), "Should be a let binding");
    }

    #[test]
    fn test_rust_raw_ident_contains_keyword() {
        let s = rust_raw_ident("type");
        assert!(s.contains("type"), "Raw ident should embed the keyword");
    }

    #[test]
    fn test_ts_discard_binding_contains_underscore() {
        let s = ts_discard_binding();
        assert!(
            s.contains('_'),
            "TS discard binding should contain underscore"
        );
        assert!(s.starts_with("const"), "Should be a const binding");
    }
}