perf-sentinel-core 0.8.13

//! Per-region accumulation, folding, model-tag selection, and final
//! [`CarbonReport`] assembly. Consumed by [`super::carbon_compute`].

use std::cmp::Ordering;
use std::collections::BTreeMap;

use super::carbon::{
    self, CO2_MODEL, CO2_MODEL_CLOUD_SPECPOWER, CO2_MODEL_EMAPS, CO2_MODEL_KEPLER,
    CO2_MODEL_REDFISH, CO2_MODEL_SCAPHANDRE, CO2_MODEL_V2, CO2_MODEL_V3, CarbonEstimate,
    CarbonReport, GENERIC_PUE, IntensitySource, REGION_STATUS_KNOWN, REGION_STATUS_OUT_OF_TABLE,
    REGION_STATUS_UNRESOLVED, RegionBreakdown, UNKNOWN_REGION, lookup_region_lower,
};

/// Per-region CO₂ accumulator. `intensity_sum_per_op / total_ops`
/// gives the ops-weighted mean intensity for the breakdown row.
///
/// The four measured-source bools plus the calibration flag are
/// independent observations (a single region can mix every source), so a
/// state machine or enum would not model the domain faithfully. Kept as
/// a flat flag bag with a targeted `struct_excessive_bools` allow.
#[derive(Default)]
#[allow(clippy::struct_excessive_bools)]
pub(super) struct RegionAccumulator {
    pub(super) co2_gco2: f64,
    pub(super) total_ops: usize,
    /// Sum of per-op intensities (NOT `ops * intensity`). Mean = sum / `total_ops`.
    pub(super) intensity_sum_per_op: f64,
    /// Highest-fidelity intensity source seen for this region.
    pub(super) max_intensity_source: IntensitySource,
    pub(super) any_scaphandre: bool,
    pub(super) any_kepler_ebpf: bool,
    pub(super) any_redfish_bmc: bool,
    pub(super) any_cloud_specpower: bool,
    /// Whether any span in this region used a calibrated proxy energy.
    pub(super) any_calibrated: bool,
    /// Latest `Electricity Maps` `isEstimated` flag observed for this
    /// region, captured when the source flips to `RealTime`. All spans
    /// in a single batch resolve against the same per-region snapshot,
    /// so this is constant across spans in practice.
    pub(super) realtime_estimated: Option<bool>,
    /// Latest `Electricity Maps` `estimationMethod` tag observed.
    pub(super) realtime_estimation_method: Option<String>,
}

/// Aggregated "which intensity sources / measured-energy backends did
/// the report see?" flags, collected in [`build_region_breakdowns`]
/// and consumed by [`select_co2_model_tag`].
///
/// The eight booleans are independent observations that can freely
/// combine (e.g. a single run can see both hourly and cloud `SPECpower`
/// at the same time), so a state machine or enum would not model the
/// domain faithfully. Kept as a flat flag bag with a targeted
/// `struct_excessive_bools` allow.
#[derive(Default, Clone, Copy)]
#[allow(clippy::struct_excessive_bools)]
pub(super) struct ReportFlags {
    any_hourly: bool,
    any_monthly_hourly: bool,
    any_scaphandre: bool,
    any_kepler_ebpf: bool,
    any_redfish_bmc: bool,
    any_cloud_specpower: bool,
    any_calibrated: bool,
    any_realtime: bool,
}

/// Fold the per-region accumulators into a breakdown vector, collect
/// the cross-region flags needed for model-tag selection, and compute
/// the total operational CO₂. Regions whose name is not in the
/// embedded carbon table get a dedicated out-of-table row with the
/// generic PUE fallback; the synthetic "unknown" bucket is appended
/// if there are any unresolvable ops.
pub(super) fn build_region_breakdowns(
    per_region: BTreeMap<String, RegionAccumulator>,
    unknown_ops: usize,
) -> (Vec<RegionBreakdown>, ReportFlags, f64) {
    let mut regions: Vec<RegionBreakdown> = Vec::with_capacity(per_region.len() + 1);
    let mut flags = ReportFlags::default();
    let mut operational_gco2: f64 = 0.0;
    for (region, acc) in per_region {
        operational_gco2 += acc.co2_gco2;
        update_flags_from_accumulator(&mut flags, &acc);
        regions.push(build_single_region_row(region, acc));
    }
    if unknown_ops > 0 {
        tracing::debug!(
            "{unknown_ops} I/O ops had no resolvable region and were excluded \
             from operational CO₂ estimates. Set [green] default_region or \
             [green.service_regions] to attribute them."
        );
        regions.push(RegionBreakdown {
            status: REGION_STATUS_UNRESOLVED.to_string(),
            region: UNKNOWN_REGION.to_string(),
            grid_intensity_gco2_kwh: 0.0,
            pue: 0.0,
            io_ops: unknown_ops,
            co2_gco2: 0.0,
            intensity_source: IntensitySource::Annual,
            intensity_estimated: None,
            intensity_estimation_method: None,
        });
    }
    (regions, flags, operational_gco2)
}

/// Merge a single accumulator's intensity source and measured-energy
/// flags into the aggregate [`ReportFlags`].
fn update_flags_from_accumulator(flags: &mut ReportFlags, acc: &RegionAccumulator) {
    match acc.max_intensity_source {
        IntensitySource::RealTime => {
            flags.any_realtime = true;
        }
        IntensitySource::MonthlyHourly => {
            flags.any_monthly_hourly = true;
            flags.any_hourly = true;
        }
        IntensitySource::Hourly => {
            flags.any_hourly = true;
        }
        IntensitySource::Annual => {}
    }
    flags.any_scaphandre |= acc.any_scaphandre;
    flags.any_kepler_ebpf |= acc.any_kepler_ebpf;
    flags.any_redfish_bmc |= acc.any_redfish_bmc;
    flags.any_cloud_specpower |= acc.any_cloud_specpower;
    flags.any_calibrated |= acc.any_calibrated;
}

/// Build a single `RegionBreakdown` row from a finished accumulator.
/// Known regions (present in the embedded carbon table) use the
/// canonical PUE; out-of-table regions use the generic PUE when a
/// custom profile produced non-zero CO₂, and a zeroed row otherwise.
///
/// Takes `acc` by value so the optional `realtime_estimation_method`
/// `String` can move directly into the row instead of being cloned.
fn build_single_region_row(region: String, acc: RegionAccumulator) -> RegionBreakdown {
    if let Some((_, pue)) = lookup_region_lower(&region) {
        // Time-weighted mean intensity for display. Guaranteed non-zero
        // ops because the accumulator was only inserted after
        // incrementing total_ops.
        let mean_intensity = acc.intensity_sum_per_op / acc.total_ops as f64;
        let intensity_source = acc.max_intensity_source;
        let total_ops = acc.total_ops;
        let co2_gco2 = acc.co2_gco2;
        let (intensity_estimated, intensity_estimation_method) =
            realtime_metadata_for_row(intensity_source, acc);
        return RegionBreakdown {
            status: REGION_STATUS_KNOWN.to_string(),
            region,
            grid_intensity_gco2_kwh: mean_intensity,
            pue,
            io_ops: total_ops,
            co2_gco2,
            intensity_source,
            intensity_estimated,
            intensity_estimation_method,
        };
    }
    // Out-of-table region: name resolved but not in our table. When a
    // custom hourly profile produced non-zero CO₂ (via the generic PUE
    // fallback), report the actual accumulated values so
    // sum(regions[].co2_gco2) == operational_gco2.
    let has_co2 = acc.co2_gco2 > 0.0;
    if !has_co2 {
        tracing::debug!(
            "Region '{region}' is not in the embedded carbon table; \
             {ops} I/O ops contribute 0 to operational CO₂. \
             See docs/CONFIGURATION.md for the list of supported regions.",
            ops = acc.total_ops
        );
    }
    let mean_intensity = if acc.total_ops > 0 && has_co2 {
        acc.intensity_sum_per_op / acc.total_ops as f64
    } else {
        0.0
    };
    let pue_display = if has_co2 { GENERIC_PUE } else { 0.0 };
    let intensity_source = if has_co2 {
        acc.max_intensity_source
    } else {
        IntensitySource::Annual
    };
    let total_ops = acc.total_ops;
    let co2_gco2 = acc.co2_gco2;
    let (intensity_estimated, intensity_estimation_method) =
        realtime_metadata_for_row(intensity_source, acc);
    RegionBreakdown {
        status: REGION_STATUS_OUT_OF_TABLE.to_string(),
        region,
        grid_intensity_gco2_kwh: mean_intensity,
        pue: pue_display,
        io_ops: total_ops,
        co2_gco2,
        intensity_source,
        intensity_estimated,
        intensity_estimation_method,
    }
}

/// Surface the Electricity Maps estimation flags only when the
/// row's effective `intensity_source` is `RealTime`. Other sources
/// (annual, hourly, monthly hourly) carry no estimation metadata
/// and must serialize without the optional fields.
///
/// Consumes the accumulator so the optional `String` moves out
/// without an extra allocation.
fn realtime_metadata_for_row(
    source: IntensitySource,
    acc: RegionAccumulator,
) -> (Option<bool>, Option<String>) {
    if source == IntensitySource::RealTime {
        (acc.realtime_estimated, acc.realtime_estimation_method)
    } else {
        (None, None)
    }
}

/// Pick the top-level `co2.model` tag given the aggregate flags.
///
/// Precedence (most to least precise): real-time, Scaphandre, Kepler,
/// Redfish, cloud `SPECpower`, monthly/hourly proxy, annual proxy. The
/// `+cal` suffix only applies to the proxy branches, the measured
/// branches all short-circuit earlier so the calibration flag is
/// implicitly suppressed when any measured source is active.
pub(super) fn select_co2_model_tag(flags: ReportFlags) -> &'static str {
    if flags.any_realtime {
        CO2_MODEL_EMAPS
    } else if flags.any_scaphandre {
        CO2_MODEL_SCAPHANDRE
    } else if flags.any_kepler_ebpf {
        CO2_MODEL_KEPLER
    } else if flags.any_redfish_bmc {
        CO2_MODEL_REDFISH
    } else if flags.any_cloud_specpower {
        CO2_MODEL_CLOUD_SPECPOWER
    } else {
        select_proxy_co2_model_tag(
            flags.any_monthly_hourly,
            flags.any_hourly,
            flags.any_calibrated,
        )
    }
}

/// Resolve the proxy-tier `co2.model` tag once every measured branch
/// has been ruled out by the caller.
fn select_proxy_co2_model_tag(
    monthly_hourly: bool,
    hourly: bool,
    calibrated: bool,
) -> &'static str {
    if monthly_hourly {
        if calibrated {
            carbon::CO2_MODEL_V3_CAL
        } else {
            CO2_MODEL_V3
        }
    } else if hourly {
        if calibrated {
            carbon::CO2_MODEL_V2_CAL
        } else {
            CO2_MODEL_V2
        }
    } else if calibrated {
        carbon::CO2_MODEL_V1_CAL
    } else {
        CO2_MODEL
    }
}

/// Region-blind avoidable share: `window_total` (operational CO₂ or energy)
/// scaled by the fraction of accounted I/O ops that are avoidable, clamped
/// to 1.0.
///
/// Units-neutral and shared by [`finalize_carbon_report`] and the
/// canonical-disclosure rescale (`score::canonical`) so the operational and
/// canonical avoidable figures cannot drift on the formula. The clamp guards
/// the pathological case where avoidable ops from unknown-region spans exceed
/// the accounted denominator.
#[must_use]
pub(super) fn avoidable_share(
    window_total: f64,
    avoidable_io_ops: usize,
    accounted_io_ops: usize,
) -> f64 {
    if accounted_io_ops > 0 {
        let ratio = (avoidable_io_ops as f64 / accounted_io_ops as f64).min(1.0);
        window_total * ratio
    } else {
        0.0
    }
}

/// Final assembly of the [`CarbonReport`] struct: SCI v1.0 numerator
/// (E × I + M + T), avoidable CO₂ via region-blind ratio, and the
/// methodology tag that shifts when network transport is included.
#[allow(clippy::too_many_arguments)]
pub(super) fn finalize_carbon_report(
    traces_len: usize,
    operational_gco2: f64,
    total_transport_gco2: f64,
    total_io_ops: usize,
    avoidable_io_ops: usize,
    unknown_ops: usize,
    embodied_per_request_gco2: f64,
    model: &'static str,
) -> CarbonReport {
    // SCI v1.0 embodied carbon term M = traces × per-trace constant.
    // Region-independent, emitted unconditionally when we have at least
    // one trace (empty case is early-returned in the caller).
    let embodied_gco2 = traces_len as f64 * embodied_per_request_gco2;

    // Total = SCI v1.0 numerator (E × I) + M, summed over all analyzed
    // traces. NOT the SCI per-R intensity: consumers compute that
    // themselves as total_mid / traces.len() if needed.
    let total_mid = operational_gco2 + embodied_gco2 + total_transport_gco2;

    // Avoidable CO₂ via region-blind ratio. Denominator excludes the
    // unknown bucket (operational_gco2 already excludes it, so we match).
    // Embodied is NOT included in avoidable: hardware emissions are fixed
    // regardless of whether the application does N+1 queries.
    let accounted_io_ops = total_io_ops.saturating_sub(unknown_ops);
    let avoidable_mid = avoidable_share(operational_gco2, avoidable_io_ops, accounted_io_ops);

    let transport_gco2 = if total_transport_gco2 > 0.0 {
        Some(total_transport_gco2)
    } else {
        None
    };
    let total_methodology = if transport_gco2.is_some() {
        carbon::METHODOLOGY_SCI_NUMERATOR_TRANSPORT
    } else {
        carbon::METHODOLOGY_SCI_NUMERATOR
    };

    // SCI per-R intensity: the numerator divided by the functional unit
    // R = 1 trace. This is the SCI score proper. traces_len >= 1 here (the
    // empty case is early-returned in the caller), but guard defensively.
    let sci_per_trace = (traces_len > 0).then(|| {
        CarbonEstimate::new_with_model(
            total_mid / traces_len as f64,
            model,
            carbon::METHODOLOGY_SCI_INTENSITY,
        )
    });

    CarbonReport {
        total: CarbonEstimate::new_with_model(total_mid, model, total_methodology),
        avoidable: CarbonEstimate::operational_ratio_with_model(avoidable_mid, model),
        operational_gco2,
        embodied_gco2,
        transport_gco2,
        sci_per_trace,
        functional_unit: "trace".to_string(),
    }
}

/// Sort the per-region breakdown by `co2_gco2` descending with an
/// alphabetical tiebreak. BTreeMap-based accumulation gives stable
/// f64 sums upstream; this final sort is purely cosmetic and the
/// result stays deterministic.
pub(super) fn sort_regions_by_co2_desc(regions: &mut [RegionBreakdown]) {
    regions.sort_by(|a, b| {
        b.co2_gco2
            .partial_cmp(&a.co2_gco2)
            .unwrap_or(Ordering::Equal)
            .then_with(|| a.region.cmp(&b.region))
    });
}