# -*- coding: utf-8 -*-
"""
Final Suite19 reporting hardening.

This module layers on top of suite19_reporting.py without changing the
underlying metric definitions used by the project.
"""
from __future__ import annotations

from functools import lru_cache
from pathlib import Path

import numpy as np
import pandas as pd

import suite19_reporting as legacy
from suite19_common import metric_dict, print_table


REFERENCE_ALIASES = {
    "suite17_final": [
        "suite17_hgb_final",
        "suite17_final",
    ],
    "suite17_raw": [
        "suite17_hgb_raw",
        "suite17_raw",
    ],
    "suite18_final": [
        "suite18_hgb_final",
        "suite18_final",
    ],
    "suite18_raw": [
        "suite18_hgb_raw",
        "suite18_raw",
    ],
    "suite16": [
        "suite16_hgb_final",
        "suite16_conditional_tree_boosting",
        "suite16",
    ],
    "suite14": [
        "suite14_authority_safe_final",
        "suite14",
    ],
    "v2": [
        "failure_probability_lt5",
        "failure_probability",
        "stacked_probability",
        "stacked_prob",
        "v2",
    ],
    "council": [
        "suite4_competence_council",
        "competence_council",
        "council",
        "final",
        "council_probability",
    ],
}

ACTUAL_ALIASES = (
    "actual",
    "actual_failure_lt5",
    "y",
    "label",
    "target",
)

DEPLOYABLE_PRIORS = (
    "suite14",
    "suite16",
    "suite17_final",
    "suite18_final",
    "council",
    "v2",
)


def _finite_score(s):
    s = np.asarray(s, float).reshape(-1)
    return bool(len(s) and np.isfinite(s).all())


def faculty_fold_rows(
    fold,
    faculty_names,
    faculty_idx,
    y,
    scores,
    beta=2.0,
):
    y = np.asarray(y, int)
    fi = np.asarray(faculty_idx, int)
    rows = []

    for i, faculty in enumerate(faculty_names):
        m = fi == i

        if not m.any():
            continue

        for model, score in scores.items():
            s = np.asarray(score, float)

            if (
                len(s) != len(y)
                or not np.isfinite(s[m]).all()
            ):
                md = {
                    "ap": np.nan,
                    "auc": np.nan,
                }

                for rate in (10, 15, 20, 25, 30):
                    for key in (
                        "precision",
                        "recall",
                        "f1",
                        "fbeta",
                        "flag_rate",
                    ):
                        md[f"{key}_at_{rate}"] = np.nan

                availability = 0.0
                status = "UNAVAILABLE"
            else:
                md = metric_dict(
                    y[m],
                    s[m],
                    beta,
                )
                availability = 1.0
                status = "OK"

            rows.append(
                {
                    "fold": int(fold),
                    "faculty": faculty,
                    "model": model,
                    "rows": int(m.sum()),
                    "failures": int(y[m].sum()),
                    "prevalence": float(
                        y[m].mean()
                    ),
                    "score_available_rate": availability,
                    "status": status,
                    **md,
                }
            )

    return rows


def paired_table(metrics, candidate, base):
    d = (
        metrics.copy()
        if isinstance(metrics, pd.DataFrame)
        else pd.DataFrame(metrics)
    )

    required = {
        "fold",
        "faculty",
        "model",
        "rows",
        "failures",
        "ap",
        "auc",
        "fbeta_at_20",
    }

    if d.empty or not required.issubset(d.columns):
        return pd.DataFrame(
            columns=[
                "fold",
                "faculty",
                "candidate_rows",
                "candidate_failures",
                "candidate_ap",
                "candidate_auc",
                "candidate_f2_at20",
                "base_rows",
                "base_failures",
                "base_ap",
                "base_auc",
                "base_f2_at20",
                "delta_ap",
                "delta_auc",
                "delta_f2_at20",
                "win",
            ]
        )


    df = (
        metrics.copy()
        if isinstance(metrics, pd.DataFrame)
        else pd.DataFrame(metrics)
    )

    needed = [
        "fold",
        "faculty",
        "rows",
        "failures",
        "model",
        "ap",
        "auc",
        "fbeta_at_20",
    ]

    d = df[
        [c for c in needed if c in df.columns]
    ].copy()

    a = d[d.model == candidate].rename(
        columns={
            "rows": "candidate_rows",
            "failures": "candidate_failures",
            "ap": "candidate_ap",
            "auc": "candidate_auc",
            "fbeta_at_20": "candidate_f2_at20",
        }
    )

    b = d[d.model == base].rename(
        columns={
            "rows": "base_rows",
            "failures": "base_failures",
            "ap": "base_ap",
            "auc": "base_auc",
            "fbeta_at_20": "base_f2_at20",
        }
    )

    a = a.drop(columns=["model"])
    b = b.drop(columns=["model"])

    z = a.merge(
        b,
        on=["fold", "faculty"],
        how="inner",
    )

    if not len(z):
        return z

    finite = (
        np.isfinite(z.candidate_ap)
        & np.isfinite(z.base_ap)
    )

    z = z.loc[finite].copy()

    if not len(z):
        return z

    z["delta_ap"] = (
        z.candidate_ap - z.base_ap
    )
    z["delta_auc"] = (
        z.candidate_auc - z.base_auc
    )
    z["delta_f2_at20"] = (
        z.candidate_f2_at20
        - z.base_f2_at20
    )

    z["win"] = np.where(
        z.delta_ap > 0,
        "WIN",
        np.where(
            z.delta_ap < 0,
            "LOSS",
            "TIE",
        ),
    )

    return z

def test_paired_table_empty_input_is_safe():
    z = paired_table(
        pd.DataFrame(),
        "committee_residual",
        "committee",
    )

    assert z.empty
    assert "delta_ap" in z.columns


def paired_summary(metrics, candidate, base):
    z = paired_table(
        metrics,
        candidate,
        base,
    )

    if not len(z):
        return {
            "candidate": candidate,
            "base": base,
            "cells": 0,
            "wins": 0,
            "losses": 0,
            "ties": 0,
            "win_rate": np.nan,
            "mean_delta_ap": np.nan,
            "median_delta_ap": np.nan,
            "q25_delta_ap": np.nan,
            "worst_delta_ap": np.nan,
            "mean_delta_auc": np.nan,
            "mean_delta_f2_at20": np.nan,
        }

    return {
        "candidate": candidate,
        "base": base,
        "cells": int(len(z)),
        "wins": int((z.delta_ap > 0).sum()),
        "losses": int((z.delta_ap < 0).sum()),
        "ties": int((z.delta_ap == 0).sum()),
        "win_rate": float(
            (z.delta_ap > 0).mean()
        ),
        "mean_delta_ap": float(
            z.delta_ap.mean()
        ),
        "median_delta_ap": float(
            z.delta_ap.median()
        ),
        "q25_delta_ap": float(
            z.delta_ap.quantile(0.25)
        ),
        "worst_delta_ap": float(
            z.delta_ap.min()
        ),
        "mean_delta_auc": float(
            z.delta_auc.mean()
        ),
        "mean_delta_f2_at20": float(
            z.delta_f2_at20.mean()
        ),
    }


def _direct_candidates(root, fold, faculty):
    r = Path(root)

    return [
        r / f"fold_{fold}" / f"{faculty}_scores.csv",
        r / f"{faculty}_fold_{fold}_scores.csv",
        r / f"fold_{fold}" / f"{faculty}_target_scores.csv",
        r / f"{faculty}_fold_{fold}_target_scores.csv",
        r / f"{faculty}_fold_{fold}_test_results.csv",
    ]


@lru_cache(maxsize=4096)
def _discover_candidates(root, fold, faculty):
    root = str(root)
    r = Path(root)

    if not r.exists():
        return []

    found = []

    for p in _direct_candidates(
        r,
        fold,
        faculty,
    ):
        if p.exists():
            found.append(p)

    # Recursive fallback is important for copied/extracted historical results.
    patterns = (
        f"**/fold_{fold}/{faculty}_scores.csv",
        f"**/{faculty}_fold_{fold}_scores.csv",
        f"**/fold_{fold}/{faculty}_target_scores.csv",
        f"**/{faculty}_fold_{fold}_target_scores.csv",
        f"**/{faculty}_fold_{fold}_test_results.csv",
    )

    for pattern in patterns:
        for p in r.glob(pattern):
            if p not in found:
                found.append(p)

    return [
        str(p)
        for p in sorted(
            found,
            key=lambda x: (
                len(x.parts),
                str(x),
            ),
        )
    ]


def _try_reference_file(
    path,
    y,
    aliases,
):
    p = Path(path)
    df = pd.read_csv(
        p,
        low_memory=False,
    )

    actual = next(
        (
            c
            for c in ACTUAL_ALIASES
            if c in df.columns
        ),
        None,
    )

    if actual is None:
        return None, {
            "status": "actual_column_missing",
            "path": str(p),
        }

    av = pd.to_numeric(
        df[actual],
        errors="coerce",
    ).to_numpy()

    if (
        len(df) != len(y)
        or not np.isfinite(av).all()
        or not np.array_equal(
            av.astype(int),
            np.asarray(y, int),
        )
    ):
        return None, {
            "status": "alignment_mismatch",
            "path": str(p),
            "actual_column": actual,
        }

    column = next(
        (
            c
            for c in aliases
            if c in df.columns
        ),
        None,
    )

    if column is None:
        return None, {
            "status": "score_column_missing",
            "path": str(p),
            "actual_column": actual,
            "columns": "|".join(
                map(str, df.columns)
            ),
        }

    s = pd.to_numeric(
        df[column],
        errors="coerce",
    ).to_numpy(float)

    if (
        len(s) != len(y)
        or not np.isfinite(s).all()
    ):
        return None, {
            "status": "score_nonfinite_or_length_mismatch",
            "path": str(p),
            "actual_column": actual,
            "column": column,
        }

    return s, {
        "status": "loaded",
        "path": str(p),
        "actual_column": actual,
        "column": column,
    }


def reference_scores_for_faculty(
    reference_dirs,
    fold,
    faculty,
    y,
):
    out = {}
    metadata = []

    for name, root in (
        reference_dirs or {}
    ).items():
        if not root:
            metadata.append(
                {
                    "reference": name,
                    "faculty": faculty,
                    "fold": int(fold),
                    "status": "disabled",
                    "root": "",
                }
            )
            continue

        r = Path(root)

        if not r.exists():
            metadata.append(
                {
                    "reference": name,
                    "faculty": faculty,
                    "fold": int(fold),
                    "status": "root_missing",
                    "root": str(r),
                }
            )
            continue

        aliases = REFERENCE_ALIASES.get(
            name,
            [name, "final"],
        )

        candidates = _discover_candidates(
            str(r),
            int(fold),
            str(faculty),
        )

        loaded = None
        attempts = []

        for candidate in candidates:
            score, info = _try_reference_file(
                candidate,
                y,
                aliases,
            )

            attempts.append(info)

            if score is not None:
                loaded = (
                    score,
                    info,
                )
                break

        if loaded is not None:
            score, info = loaded
            out[name] = score

            metadata.append(
                {
                    "reference": name,
                    "faculty": faculty,
                    "fold": int(fold),
                    "status": "loaded",
                    "root": str(r),
                    "path": info["path"],
                    "column": info["column"],
                    "actual_column": info[
                        "actual_column"
                    ],
                    "discovery": (
                        "direct"
                        if Path(info["path"])
                        in _direct_candidates(
                            r,
                            fold,
                            faculty,
                        )
                        else "recursive"
                    ),
                    "candidate_files": len(
                        candidates
                    ),
                }
            )
        else:
            metadata.append(
                {
                    "reference": name,
                    "faculty": faculty,
                    "fold": int(fold),
                    "status": "missing_or_unaligned",
                    "root": str(r),
                    "candidate_files": len(
                        candidates
                    ),
                    "attempts": str(
                        attempts[:4]
                    ),
                }
            )

    return out, metadata


def print_reference_root_audit(
    reference_dirs,
    fold,
):
    rows = []

    for name, root in (
        reference_dirs or {}
    ).items():
        p = Path(root) if root else None

        rows.append(
            {
                "reference": name,
                "root": str(root or ""),
                "root_exists": bool(
                    p is not None and p.exists()
                ),
                "fold": int(fold),
                "fold_dir_exists": bool(
                    p is not None
                    and (
                        p / f"fold_{fold}"
                    ).exists()
                ),
            }
        )

    print_table(
        "[REFERENCE ROOT AUDIT]",
        pd.DataFrame(rows),
        max_rows=100,
    )


def _path_stats(cells, column):
    if not cells:
        return {
            "score": -np.inf,
            "mean": np.nan,
            "median": np.nan,
            "q25": np.nan,
            "recent_mean": np.nan,
            "worst_block_mean": np.nan,
            "win_rate": 0.0,
            "cells": 0,
        }

    df = pd.DataFrame(cells)

    z = pd.to_numeric(
        df[column],
        errors="coerce",
    )

    keep = np.isfinite(z)
    df = df.loc[keep].copy()

    if not len(df):
        return {
            "score": -np.inf,
            "mean": np.nan,
            "median": np.nan,
            "q25": np.nan,
            "recent_mean": np.nan,
            "worst_block_mean": np.nan,
            "win_rate": 0.0,
            "cells": 0,
        }

    v = df[column].to_numpy(float)

    block_mean = (
        df.groupby("block")[column]
        .mean()
        .sort_index()
    )

    recent_mean = float(
        block_mean.iloc[-1]
    )
    worst_block = float(
        block_mean.min()
    )

    mean = float(np.mean(v))
    median = float(np.median(v))
    q25 = float(
        np.quantile(v, 0.25)
    )
    win_rate = float(
        np.mean(v > 0)
    )

    score = (
        0.35 * mean
        + 0.30 * median
        + 0.20 * q25
        + 0.15 * recent_mean
        - 0.50 * max(
            0.0,
            -worst_block,
        )
    )

    return {
        "score": float(score),
        "mean": mean,
        "median": median,
        "q25": q25,
        "recent_mean": recent_mean,
        "worst_block_mean": worst_block,
        "win_rate": win_rate,
        "cells": int(len(v)),
    }


def selection_stats(hist, ledger, probe):
    q = np.asarray(
        hist.teacher.mean(1),
        float,
    )

    valid = np.asarray(
        ledger.hist_available,
        bool,
    )

    cells = []

    for block in sorted(
        x
        for x in np.unique(
            hist.blocks[valid]
        )
        if np.isfinite(x)
    ):
        for fi, faculty in enumerate(
            hist.faculty_names
        ):
            m = (
                valid
                & (hist.blocks == block)
                & (
                    hist.faculty_idx
                    == fi
                )
            )

            # Every conditional score used here must be genuinely available.
            score_names = (
                "committee_residual",
                "hgb_xz",
                "raw_hgb",
            )

            for name in score_names:
                m &= np.isfinite(
                    probe.hist_scores[name]
                )

            if (
                m.sum() < 10
                or np.unique(
                    hist.y[m]
                ).size < 2
            ):
                continue

            residual_delta = (
                legacy.safe_ap(
                    hist.y[m],
                    probe.hist_scores[
                        "committee_residual"
                    ][m],
                )
                - legacy.safe_ap(
                    hist.y[m],
                    q[m],
                )
            )

            xz_delta = (
                legacy.safe_ap(
                    hist.y[m],
                    probe.hist_scores[
                        "hgb_xz"
                    ][m],
                )
                - legacy.safe_ap(
                    hist.y[m],
                    probe.hist_scores[
                        "raw_hgb"
                    ][m],
                )
            )

            cells.append(
                {
                    "block": float(block),
                    "faculty": faculty,
                    "rows": int(m.sum()),
                    "failures": int(
                        hist.y[m].sum()
                    ),
                    "conditional_delta_ap": float(
                        residual_delta
                    ),
                    "xz_delta_ap": float(
                        xz_delta
                    ),
                }
            )

    residual = _path_stats(
        cells,
        "conditional_delta_ap",
    )
    xz = _path_stats(
        cells,
        "xz_delta_ap",
    )

    if xz["score"] > residual["score"]:
        basis = "hgb_xz_vs_raw_hgb"
        primary = xz
    else:
        basis = (
            "committee_residual_vs_committee"
        )
        primary = residual

    return {
        # Used by existing selector.
        "score": primary["score"],
        "selection_basis": basis,

        # Existing compatibility fields.
        "mean_conditional_delta_ap":
            residual["mean"],
        "median_conditional_delta_ap":
            residual["median"],
        "q25_conditional_delta_ap":
            residual["q25"],
        "recent_mean_conditional_delta_ap":
            residual["recent_mean"],
        "mean_xz_delta_ap": xz["mean"],
        "win_rate": primary["win_rate"],
        "cells": primary["cells"],

        # Explicit residual path.
        "residual_score": residual["score"],
        "residual_mean_delta_ap":
            residual["mean"],
        "residual_median_delta_ap":
            residual["median"],
        "residual_q25_delta_ap":
            residual["q25"],
        "residual_recent_mean_delta_ap":
            residual["recent_mean"],
        "residual_worst_block_mean_delta_ap":
            residual[
                "worst_block_mean"
            ],
        "residual_win_rate":
            residual["win_rate"],

        # Explicit raw-X complementarity path.
        "xz_score": xz["score"],
        "xz_mean_delta_ap": xz["mean"],
        "xz_median_delta_ap":
            xz["median"],
        "xz_q25_delta_ap": xz["q25"],
        "xz_recent_mean_delta_ap":
            xz["recent_mean"],
        "xz_worst_block_mean_delta_ap":
            xz["worst_block_mean"],
        "xz_win_rate": xz["win_rate"],
    }


def _fold_delta(
    metrics,
    fold,
    candidate,
    base,
):
    return paired_summary(
        metrics[
            metrics.fold
            == int(fold)
        ],
        candidate,
        base,
    ).get(
        "mean_delta_ap",
        np.nan,
    )


def _faculty_delta(
    metrics,
    faculty_mask,
    candidate,
    base,
):
    return paired_summary(
        metrics[faculty_mask],
        candidate,
        base,
    ).get(
        "mean_delta_ap",
        np.nan,
    )


def classify_verdict(
    conditional_delta_ap,
    f6_delta_ap,
    f7_delta_ap,
    win_rate,
    it_delta_ap,
    dominated_by_control,
):
    d = (
        float(conditional_delta_ap)
        if np.isfinite(
            conditional_delta_ap
        )
        else -np.inf
    )

    f6 = (
        float(f6_delta_ap)
        if np.isfinite(f6_delta_ap)
        else -np.inf
    )

    f7 = (
        float(f7_delta_ap)
        if np.isfinite(f7_delta_ap)
        else -np.inf
    )

    wr = (
        float(win_rate)
        if np.isfinite(win_rate)
        else 0.0
    )

    it = (
        float(it_delta_ap)
        if np.isfinite(it_delta_ap)
        else -np.inf
    )

    if dominated_by_control or d <= 0:
        return "REJECT"

    if (
        d >= 0.010
        and f6 > 0
        and f7 > 0
        and wr >= 0.60
        and it >= -0.005
    ):
        return "BREAKTHROUGH"

    if (
        d >= 0.005
        and f6 > 0
        and f7 > 0
        and wr >= 0.55
        and it >= -0.005
    ):
        return "PROMISING"

    return "WEAK"


def summarize_encoder_verdict(
    encoder_name,
    metrics_df,
    holdout_folds=(6, 7),
    raw_model="raw_hgb",
    candidate_model="committee_residual",
    pca_summary=None,
    random_summary=None,
    primary_faculty="khoa_cong_nghe_thong_tin",
    business_faculty_keywords=(
        "kinh_doanh",
        "du_lich",
        "business",
        "tourism",
    ),
    native_ap=np.nan,
    linear_ap=np.nan,
    hgb_z_ap=np.nan,
    hgb_xz_ap=np.nan,
    raw_hgb_ap=np.nan,
    runtime=np.nan,
    latent_dim=np.nan,
    effective_rank_value=np.nan,
    native_metric_ap=np.nan,
):
    d = metrics_df.copy()

    hold = d[
        d.fold.isin(
            list(holdout_folds)
        )
    ]

    residual = paired_summary(
        hold,
        "committee_residual",
        "committee",
    )

    xz = paired_summary(
        hold,
        "hgb_xz",
        raw_model,
    )

    rv = residual.get(
        "mean_delta_ap",
        np.nan,
    )
    xv = xz.get(
        "mean_delta_ap",
        np.nan,
    )

    # Both paths were prespecified by the frozen design.
    if (
        np.isfinite(xv)
        and (
            not np.isfinite(rv)
            or xv > rv
        )
    ):
        basis = "hgb_xz_vs_raw_hgb"
        candidate = "hgb_xz"
        base = raw_model
        primary = xz
    else:
        basis = (
            "committee_residual_vs_committee"
        )
        candidate = "committee_residual"
        base = "committee"
        primary = residual

    f6 = (
        _fold_delta(
            hold,
            holdout_folds[0],
            candidate,
            base,
        )
        if len(holdout_folds) > 0
        else np.nan
    )

    f7 = (
        _fold_delta(
            hold,
            holdout_folds[1],
            candidate,
            base,
        )
        if len(holdout_folds) > 1
        else np.nan
    )

    itmask = (
        hold.faculty
        == primary_faculty
    )

    it_delta = _faculty_delta(
        hold,
        itmask,
        candidate,
        base,
    )

    bmask = (
        hold.faculty
        .astype(str)
        .str.lower()
        .apply(
            lambda s: any(
                k in s
                for k in business_faculty_keywords
            )
        )
    )

    business_delta = _faculty_delta(
        hold,
        bmask,
        candidate,
        base,
    )

    # Existing caller only passes XZ matched-control deltas.
    # The authoritative final report below recomputes controls for BOTH paths.
    controls = [
        x
        for x in (
            pca_summary,
            random_summary,
        )
        if x is not None
        and np.isfinite(x)
    ]

    dominated = bool(
        basis == "hgb_xz_vs_raw_hgb"
        and controls
        and np.isfinite(xv)
        and xv
        <= max(controls) + 1e-4
    )

    verdict = classify_verdict(
        primary.get(
            "mean_delta_ap",
            np.nan,
        ),
        f6,
        f7,
        primary.get(
            "win_rate",
            np.nan,
        ),
        it_delta,
        dominated,
    )

    return {
        "encoder": encoder_name,
        "verdict_basis": basis,
        "primary_conditional_delta_ap":
            primary.get(
                "mean_delta_ap",
                np.nan,
            ),

        "direct_native_ap": native_ap,
        "native_metric_ap":
            native_metric_ap,
        "linear_z_ap": linear_ap,
        "hgb_z_ap": hgb_z_ap,
        "hgb_xz_ap": hgb_xz_ap,
        "raw_hgb_x_ap": raw_hgb_ap,

        "delta_ap_from_xz": xv,
        "committee_residual_delta_ap":
            rv,

        "holdout_f6_delta_ap": f6,
        "holdout_f7_delta_ap": f7,

        "faculty_ap_wins":
            primary.get("wins", 0),
        "faculty_cells":
            primary.get("cells", 0),
        "faculty_win_rate":
            primary.get(
                "win_rate",
                np.nan,
            ),

        "f2_at20_delta":
            primary.get(
                "mean_delta_f2_at20",
                np.nan,
            ),

        "it_delta_ap": it_delta,
        "business_delta_ap":
            business_delta,

        "runtime_seconds": runtime,
        "latent_dim": latent_dim,
        "effective_rank":
            effective_rank_value,

        "dominated_by_control":
            dominated,
        "verdict": verdict,
    }


def _binary_metrics(
    y,
    s,
    threshold,
    beta=2.0,
):
    y = np.asarray(y, int)
    s = np.asarray(s, float)

    pred = s >= float(threshold)

    tp = int(
        np.sum(pred & (y == 1))
    )
    fp = int(
        np.sum(pred & (y == 0))
    )
    fn = int(
        np.sum((~pred) & (y == 1))
    )
    tn = int(
        np.sum((~pred) & (y == 0))
    )

    p = tp / max(tp + fp, 1)
    r = tp / max(tp + fn, 1)

    f1 = (
        2 * p * r
        / max(p + r, 1e-12)
    )

    b2 = float(beta) ** 2

    fb = (
        (1 + b2) * p * r
        / max(b2 * p + r, 1e-12)
    )

    return {
        "threshold": float(threshold),
        "precision": float(p),
        "recall": float(r),
        "f1": float(f1),
        "fbeta": float(fb),
        "flag_rate": float(
            pred.mean()
        ),
        "tp": tp,
        "fp": fp,
        "fn": fn,
        "tn": tn,
    }


def _select_threshold(y, s, beta):
    y = np.asarray(y, int)
    s = np.asarray(s, float)

    if (
        len(y) == 0
        or not np.isfinite(s).all()
    ):
        return None, None

    qs = np.unique(
        np.quantile(
            s,
            np.linspace(
                0.01,
                0.99,
                min(
                    199,
                    max(20, len(s)),
                ),
            ),
        )
    )

    best = None

    for t in qs:
        m = _binary_metrics(
            y,
            s,
            t,
            beta,
        )

        key = (
            m["fbeta"],
            m["recall"],
            m["precision"],
            -m["flag_rate"],
        )

        if (
            best is None
            or key > best[0]
        ):
            best = (
                key,
                float(t),
                m,
            )

    return (
        best[1],
        best[2]["flag_rate"],
    )


def operational_metrics(
    records,
    dev_folds,
    holdout_folds,
    beta=2.0,
):
    rows = []

    faculties = sorted(
        {
            r["faculty"]
            for r in records
        }
    )

    models = sorted(
        set().union(
            *[
                set(r["scores"])
                for r in records
            ]
        )
    )

    for faculty in faculties:
        rr = [
            r
            for r in records
            if r["faculty"] == faculty
        ]

        for model in models:
            dev = [
                r
                for r in rr
                if r["fold"] in dev_folds
                and model in r["scores"]
            ]

            hold = [
                r
                for r in rr
                if r["fold"]
                in holdout_folds
                and model in r["scores"]
            ]

            if not dev or not hold:
                continue

            yd = np.concatenate(
                [
                    np.asarray(
                        r["y"],
                        int,
                    )
                    for r in dev
                ]
            )

            sd = np.concatenate(
                [
                    np.asarray(
                        r["scores"][model],
                        float,
                    )
                    for r in dev
                ]
            )

            if not np.isfinite(sd).all():
                rows.append(
                    {
                        "faculty": faculty,
                        "model": model,
                        "fold": "POOLED",
                        "policy": "UNAVAILABLE",
                        "status": "UNAVAILABLE_DEV_SCORE",
                    }
                )
                continue

            threshold, warning_rate = (
                _select_threshold(
                    yd,
                    sd,
                    beta,
                )
            )

            if threshold is None:
                rows.append(
                    {
                        "faculty": faculty,
                        "model": model,
                        "fold": "POOLED",
                        "policy": "UNAVAILABLE",
                        "status": "UNAVAILABLE_THRESHOLD",
                    }
                )
                continue

            pooled = {
                "fixed": [[], []],
                "drift": [[], []],
            }

            unavailable = False

            for r in hold:
                y = np.asarray(
                    r["y"],
                    int,
                )

                s = np.asarray(
                    r["scores"][model],
                    float,
                )

                if not np.isfinite(s).all():
                    unavailable = True
                    rows.append(
                        {
                            "faculty": faculty,
                            "model": model,
                            "fold": r["fold"],
                            "policy": "UNAVAILABLE",
                            "status": "NONFINITE_HOLDOUT_SCORE",
                        }
                    )
                    continue

                drift_threshold = float(
                    np.quantile(
                        s,
                        max(
                            0.0,
                            min(
                                1.0,
                                1.0
                                - warning_rate,
                            ),
                        ),
                    )
                )

                for policy, t in (
                    (
                        "fixed",
                        threshold,
                    ),
                    (
                        "drift",
                        drift_threshold,
                    ),
                ):
                    m = _binary_metrics(
                        y,
                        s,
                        t,
                        beta,
                    )

                    rows.append(
                        {
                            "faculty":
                                faculty,
                            "model": model,
                            "fold":
                                int(r["fold"]),
                            "policy":
                                policy,
                            "status": "OK",
                            **m,
                        }
                    )

                    pooled[policy][0].append(
                        y
                    )
                    pooled[policy][1].append(
                        s
                    )

            if unavailable:
                continue

            for policy in (
                "fixed",
                "drift",
            ):
                if not pooled[policy][0]:
                    continue

                y = np.concatenate(
                    pooled[policy][0]
                )
                s = np.concatenate(
                    pooled[policy][1]
                )

                if policy == "fixed":
                    t = threshold
                else:
                    t = float(
                        np.quantile(
                            s,
                            max(
                                0.0,
                                min(
                                    1.0,
                                    1.0
                                    - warning_rate,
                                ),
                            ),
                        )
                    )

                rows.append(
                    {
                        "faculty": faculty,
                        "model": model,
                        "fold": "POOLED",
                        "policy": policy,
                        "status": "OK",
                        **_binary_metrics(
                            y,
                            s,
                            t,
                            beta,
                        ),
                    }
                )

    return pd.DataFrame(rows)


def _best_prior_envelope(
    reference_metrics,
    holdout_folds,
):
    refs = reference_metrics[
        reference_metrics.fold.isin(
            list(holdout_folds)
        )
        & reference_metrics.model.isin(
            DEPLOYABLE_PRIORS
        )
        & np.isfinite(
            reference_metrics.ap
        )
    ].copy()

    rows = []

    for (
        fold,
        faculty,
    ), g in refs.groupby(
        ["fold", "faculty"]
    ):
        best = g.sort_values(
            "ap",
            ascending=False,
        ).iloc[0]

        rows.append(
            {
                "fold": int(fold),
                "faculty": faculty,
                "best_prior_model":
                    best.model,
                "best_prior_ap":
                    float(best.ap),
                "best_prior_auc":
                    float(best.auc),
                "best_prior_f2_at20":
                    float(
                        best.fbeta_at_20
                    ),
                "available_prior_models":
                    "|".join(
                        sorted(
                            g.model.astype(
                                str
                            ).unique()
                        )
                    ),
                "prior_models_available":
                    int(
                        g.model.nunique()
                    ),
            }
        )

    return pd.DataFrame(rows)


def write_final_reports(
    args,
    out,
    fold_results,
):
    out = Path(out)

    metrics_path = (
        out / "all_fold_metrics.csv"
    )
    refs_path = (
        out / "all_reference_metrics.csv"
    )

    if not metrics_path.exists():
        print(
            "[FINAL REPORT WARN] "
            "all_fold_metrics.csv missing"
        )
        return

    metrics = pd.read_csv(
        metrics_path
    )

    refs = (
        pd.read_csv(refs_path)
        if refs_path.exists()
        else pd.DataFrame()
    )

    print(
        "\n"
        + "=" * 180
    )
    print(
        "SUITE19 FINAL CORRECTED "
        "REPRESENTATION / PRIOR-SOTA AUDIT"
    )
    print(
        "=" * 180
    )

    # --------------------------------------------------------------
    # Reference availability
    # --------------------------------------------------------------
    if len(refs):
        availability = (
            refs[
                refs.fold.isin(
                    args.holdout_folds
                )
            ]
            .groupby("model")
            .agg(
                cells=("faculty", "size"),
                faculties=(
                    "faculty",
                    "nunique",
                ),
                folds=("fold", "nunique"),
            )
            .reset_index()
        )

        availability.to_csv(
            out
            / "reference_availability_holdout.csv",
            index=False,
        )

        print_table(
            "REFERENCE AVAILABILITY — HOLDOUT",
            availability,
            max_rows=100,
        )

    # --------------------------------------------------------------
    # Direct prior head-to-head
    # --------------------------------------------------------------
    prior_cells = []

    if len(refs):
        for encoder in sorted(
            metrics.encoder.dropna().unique()
        ):
            em = metrics[
                metrics.encoder == encoder
            ]

            for candidate in (
                "committee_residual",
                "hgb_xz",
                "hgb_z",
                "linear_z",
                "direct_native",
                "native_metric",
            ):
                a = em[
                    em.model == candidate
                ][
                    [
                        "fold",
                        "faculty",
                        "ap",
                        "auc",
                        "fbeta_at_20",
                    ]
                ].rename(
                    columns={
                        "ap":
                            "suite19_ap",
                        "auc":
                            "suite19_auc",
                        "fbeta_at_20":
                            "suite19_f2_at20",
                    }
                )

                if not len(a):
                    continue

                for prior in DEPLOYABLE_PRIORS:
                    b = refs[
                        refs.model == prior
                    ][
                        [
                            "fold",
                            "faculty",
                            "ap",
                            "auc",
                            "fbeta_at_20",
                        ]
                    ].rename(
                        columns={
                            "ap":
                                "prior_ap",
                            "auc":
                                "prior_auc",
                            "fbeta_at_20":
                                "prior_f2_at20",
                        }
                    )

                    z = a.merge(
                        b,
                        on=[
                            "fold",
                            "faculty",
                        ],
                        how="inner",
                    )

                    finite = (
                        np.isfinite(
                            z.suite19_ap
                        )
                        & np.isfinite(
                            z.prior_ap
                        )
                    )

                    z = z.loc[
                        finite
                    ].copy()

                    if not len(z):
                        continue

                    z["encoder"] = encoder
                    z["candidate"] = candidate
                    z["prior_model"] = prior

                    z["delta_ap"] = (
                        z.suite19_ap
                        - z.prior_ap
                    )
                    z["delta_auc"] = (
                        z.suite19_auc
                        - z.prior_auc
                    )
                    z["delta_f2_at20"] = (
                        z.suite19_f2_at20
                        - z.prior_f2_at20
                    )
                    z["win"] = (
                        z.delta_ap > 0
                    )

                    prior_cells.append(z)

    prior_cells_df = (
        pd.concat(
            prior_cells,
            ignore_index=True,
        )
        if prior_cells
        else pd.DataFrame()
    )

    prior_cells_df.to_csv(
        out
        / "prior_head_to_head_cells.csv",
        index=False,
    )

    if len(prior_cells_df):
        prior_summary = (
            prior_cells_df[
                prior_cells_df.fold.isin(
                    args.holdout_folds
                )
            ]
            .groupby(
                [
                    "encoder",
                    "candidate",
                    "prior_model",
                ]
            )
            .agg(
                cells=("delta_ap", "size"),
                faculties=(
                    "faculty",
                    "nunique",
                ),
                mean_delta_ap=(
                    "delta_ap",
                    "mean",
                ),
                median_delta_ap=(
                    "delta_ap",
                    "median",
                ),
                q25_delta_ap=(
                    "delta_ap",
                    lambda x:
                        x.quantile(0.25),
                ),
                worst_delta_ap=(
                    "delta_ap",
                    "min",
                ),
                win_rate=(
                    "win",
                    "mean",
                ),
                mean_delta_f2_at20=(
                    "delta_f2_at20",
                    "mean",
                ),
            )
            .reset_index()
        )

        prior_summary.to_csv(
            out
            / "prior_head_to_head_summary.csv",
            index=False,
        )

        print_table(
            "SUITE19 DIRECT HEAD-TO-HEAD "
            "VS HISTORICAL SYSTEMS",
            prior_summary.sort_values(
                [
                    "candidate",
                    "mean_delta_ap",
                ],
                ascending=[
                    True,
                    False,
                ],
            ),
            max_rows=300,
        )

    # --------------------------------------------------------------
    # Best-prior envelope
    # --------------------------------------------------------------
    envelope = (
        _best_prior_envelope(
            refs,
            args.holdout_folds,
        )
        if len(refs)
        else pd.DataFrame()
    )

    envelope.to_csv(
        out
        / "best_prior_envelope.csv",
        index=False,
    )

    envelope_cells = []

    if len(envelope):
        for encoder in sorted(
            metrics.encoder.dropna().unique()
        ):
            for candidate in (
                "committee_residual",
                "hgb_xz",
                "hgb_z",
                "linear_z",
                "direct_native",
                "native_metric",
            ):
                a = metrics[
                    (metrics.encoder == encoder)
                    & (
                        metrics.model
                        == candidate
                    )
                    & metrics.fold.isin(
                        args.holdout_folds
                    )
                ][
                    [
                        "fold",
                        "faculty",
                        "ap",
                        "auc",
                        "fbeta_at_20",
                    ]
                ].rename(
                    columns={
                        "ap":
                            "suite19_ap",
                        "auc":
                            "suite19_auc",
                        "fbeta_at_20":
                            "suite19_f2_at20",
                    }
                )

                if not len(a):
                    continue

                z = a.merge(
                    envelope,
                    on=[
                        "fold",
                        "faculty",
                    ],
                    how="inner",
                )

                z = z[
                    np.isfinite(
                        z.suite19_ap
                    )
                    & np.isfinite(
                        z.best_prior_ap
                    )
                ].copy()

                if not len(z):
                    continue

                z["encoder"] = encoder
                z["candidate"] = candidate
                z["delta_ap_vs_best_prior"] = (
                    z.suite19_ap
                    - z.best_prior_ap
                )
                z[
                    "delta_auc_vs_best_prior"
                ] = (
                    z.suite19_auc
                    - z.best_prior_auc
                )
                z[
                    "delta_f2_vs_best_prior"
                ] = (
                    z.suite19_f2_at20
                    - z.best_prior_f2_at20
                )
                z["win"] = (
                    z.delta_ap_vs_best_prior
                    > 0
                )

                envelope_cells.append(z)

    envelope_cells = (
        pd.concat(
            envelope_cells,
            ignore_index=True,
        )
        if envelope_cells
        else pd.DataFrame()
    )

    envelope_cells.to_csv(
        out
        / "suite19_vs_best_prior_cells.csv",
        index=False,
    )

    project_summary = []

    if len(envelope_cells):
        for (
            encoder,
            candidate,
        ), g in envelope_cells.groupby(
            ["encoder", "candidate"]
        ):
            f6 = g[
                g.fold
                == args.holdout_folds[0]
            ].delta_ap_vs_best_prior.mean()

            f7 = (
                g[
                    g.fold
                    == args.holdout_folds[1]
                ].delta_ap_vs_best_prior.mean()
                if len(
                    args.holdout_folds
                ) > 1
                else np.nan
            )

            it = g[
                g.faculty
                == args.primary_faculty
            ].delta_ap_vs_best_prior.mean()

            bizmask = (
                g.faculty
                .astype(str)
                .str.lower()
                .apply(
                    lambda s: any(
                        k in s
                        for k in
                        args.business_faculty_keywords
                    )
                )
            )

            business = g.loc[
                bizmask,
                "delta_ap_vs_best_prior",
            ].mean()

            mean = float(
                g.delta_ap_vs_best_prior.mean()
            )
            median = float(
                g.delta_ap_vs_best_prior.median()
            )
            q25 = float(
                g.delta_ap_vs_best_prior.quantile(
                    0.25
                )
            )
            win_rate = float(
                g.win.mean()
            )

            if (
                mean > 0
                and f6 > 0
                and f7 > 0
                and win_rate >= 0.60
                and (
                    not np.isfinite(it)
                    or it >= -0.005
                )
                and (
                    not np.isfinite(business)
                    or business >= -0.005
                )
            ):
                verdict = (
                    "NEW_PROJECT_SOTA_CANDIDATE"
                )
            elif (
                mean > 0
                and win_rate >= 0.50
            ):
                verdict = (
                    "COMPETITIVE_WITH_PRIOR_SOTA"
                )
            else:
                verdict = (
                    "BELOW_BEST_PRIOR_ENVELOPE"
                )

            project_summary.append(
                {
                    "encoder": encoder,
                    "candidate": candidate,
                    "cells": int(len(g)),
                    "faculties":
                        int(
                            g.faculty.nunique()
                        ),
                    "mean_delta_ap_vs_best_prior":
                        mean,
                    "median_delta_ap_vs_best_prior":
                        median,
                    "q25_delta_ap_vs_best_prior":
                        q25,
                    "worst_delta_ap_vs_best_prior":
                        float(
                            g.delta_ap_vs_best_prior.min()
                        ),
                    "win_rate_vs_best_prior":
                        win_rate,
                    "f6_delta_ap_vs_best_prior":
                        float(f6),
                    "f7_delta_ap_vs_best_prior":
                        float(f7),
                    "it_delta_ap_vs_best_prior":
                        float(it),
                    "business_delta_ap_vs_best_prior":
                        float(business),
                    "mean_delta_f2_vs_best_prior":
                        float(
                            g.delta_f2_vs_best_prior.mean()
                        ),
                    "project_sota_verdict":
                        verdict,
                }
            )

    project_summary = pd.DataFrame(
        project_summary
    )

    project_summary.to_csv(
        out
        / "suite19_project_sota_verdict.csv",
        index=False,
    )

    if len(project_summary):
        print_table(
            "SUITE19 PROJECT-SOTA VERDICT "
            "— VS BEST PRIOR PER FACULTY×FOLD",
            project_summary.sort_values(
                "mean_delta_ap_vs_best_prior",
                ascending=False,
            ),
            max_rows=200,
        )

    # --------------------------------------------------------------
    # Suite15 information-audit reference
    # --------------------------------------------------------------
    suite15_reference = pd.DataFrame(
        [
            {
                "reference":
                    "Suite15 V1+V4",
                "type":
                    "aggregate_information_audit_only",
                "holdout_cells": 28,
                "mean_delta_ap_vs_control":
                    0.0051,
                "wins_vs_control": 17,
                "interpretation":
                    "Do not include in deployable best-prior envelope.",
            }
        ]
    )

    suite15_reference.to_csv(
        out
        / "suite15_information_reference.csv",
        index=False,
    )

    print_table(
        "SUITE15 INFORMATION-AUDIT REFERENCE",
        suite15_reference,
    )

    # --------------------------------------------------------------
    # Dedicated unresolved faculties
    # --------------------------------------------------------------
    if len(envelope_cells):
        dedicated = envelope_cells[
            (
                envelope_cells.faculty
                == args.primary_faculty
            )
            |
            (
                envelope_cells.faculty
                .astype(str)
                .str.lower()
                .apply(
                    lambda s: any(
                        k in s
                        for k in
                        args.business_faculty_keywords
                    )
                )
            )
        ].copy()

        dedicated.to_csv(
            out
            / "dedicated_it_business_vs_best_prior.csv",
            index=False,
        )

        print_table(
            "IT + BUSINESS/TOURISM "
            "VS BEST PRIOR ENVELOPE",
            dedicated.sort_values(
                [
                    "faculty",
                    "fold",
                    "delta_ap_vs_best_prior",
                ],
                ascending=[
                    True,
                    True,
                    False,
                ],
            ),
            max_rows=300,
        )

    print(
        "\n[FINAL INTERPRETATION RULE]"
    )
    print(
        "Representation verdict answers: "
        "does z add conditional information?"
    )
    print(
        "Project-SOTA verdict answers: "
        "does any predeclared Suite19 consumer "
        "actually beat the strongest prior "
        "deployable system faculty-by-faculty?"
    )