# -*- coding: utf-8 -*-
"""
Suite19 FINAL corrective runner.

This deliberately reuses the already-tested Suite19 core implementation while
hard-overriding the pieces whose scientific contract changed:

1. common-coordinate OOF embeddings;
2. symmetric historical conditional-path selection;
3. strict aligned reference discovery;
4. finite-only paired metrics;
5. symmetric representation verdict;
6. all-prior / best-prior project-SOTA reports;
7. additional trajectory logging.

Run this file, NOT the legacy trainer directly.
"""
from __future__ import annotations

import json
import time
import traceback
from pathlib import Path

import numpy as np
import pandas as pd

import train_suite19_representation_audit as core
import suite19_final_reporting as final_reporting

from suite19_coordinates import (
    COORDINATE_SYSTEM,
)
from suite19_temporal import repair_target_blocks

FINAL_PACKAGE_VERSION = "2026.09.05-final"


# ---------------------------------------------------------------------
# Harden reference + metric functions used inside core.run_fold/postprocess
# ---------------------------------------------------------------------
core.reference_scores_for_faculty = (
    final_reporting.reference_scores_for_faculty
)
core.faculty_fold_rows = (
    final_reporting.faculty_fold_rows
)
core.paired_summary = (
    final_reporting.paired_summary
)
core.paired_table = (
    final_reporting.paired_table
)
core.operational_metrics = (
    final_reporting.operational_metrics
)
core.summarize_encoder_verdict = (
    final_reporting.summarize_encoder_verdict
)


# ---------------------------------------------------------------------
# Historical representation selection:
# evaluate BOTH predeclared conditional-information paths symmetrically.
# ---------------------------------------------------------------------
core._selection_stats = (
    final_reporting.selection_stats
)


# ---------------------------------------------------------------------
# Global latent probes are forbidden on an unaligned OOF ledger.
# ---------------------------------------------------------------------
_ORIGINAL_RUN_PROBES = core._run_probes
# ---------------------------------------------------------------------
# Global latent probes are forbidden on an unaligned OOF ledger.
#
# Runtime-optimized Suite19 additionally supports
# historical=False for production seeds whose historical probe scoring
# is redundant. Preserve that argument through this scientific guard.
# ---------------------------------------------------------------------


def _run_probes_hardened(
    name,
    cfg,
    seed,
    hist,
    target,
    ledger,
    args,
    folder,
    with_target,
    historical=True,
):
    system = getattr(
        ledger,
        "coordinate_system",
        None,
    )

    if system != COORDINATE_SYSTEM:
        raise RuntimeError(
            "Suite19 refuses global latent probes on an "
            f"unaligned OOF ledger. Got coordinate_system={system!r}; "
            f"expected {COORDINATE_SYSTEM!r}."
        )

    return _ORIGINAL_RUN_PROBES(
        name,
        cfg,
        seed,
        hist,
        target,
        ledger,
        args,
        folder,
        with_target,
        historical=historical,
    )


core._run_probes = _run_probes_hardened


# ---------------------------------------------------------------------
# Candidate guard: common-coordinate construction is now a hard invariant.
# ---------------------------------------------------------------------
_ORIGINAL_CANDIDATE_GUARD = (
    core._candidate_guard
)


def _candidate_guard_hardened(
    ledger,
    diag,
    args,
    runtime,
):
    reasons = list(
        _ORIGINAL_CANDIDATE_GUARD(
            ledger,
            diag,
            args,
            runtime,
        )
    )

    if (
        getattr(
            ledger,
            "coordinate_system",
            None,
        )
        != COORDINATE_SYSTEM
    ):
        reasons.append(
            "common_coordinate_system_missing"
        )

    ca = getattr(
        ledger,
        "coordinate_audit",
        None,
    )

    if not ca:
        reasons.append(
            "coordinate_audit_missing"
        )
    else:
        hist = [
            r
            for r in ca
            if r.get("scope") == "hist"
        ]

        if hist:
            ranks = np.asarray(
                [
                    r.get(
                        "whiten_rank",
                        np.nan,
                    )
                    for r in hist
                ],
                float,
            )

            if (
                np.isfinite(ranks).any()
                and np.nanmin(ranks) < 2
            ):
                reasons.append(
                    "coordinate_whiten_rank_collapse"
                )

    return reasons


core._candidate_guard = (
    _candidate_guard_hardened
)


# ---------------------------------------------------------------------
# Save and print the coordinate trajectory for every production seed.
# ---------------------------------------------------------------------
_ORIGINAL_ENCODER_TARGET_RUN = (
    core._encoder_target_run
)


def _encoder_target_run_hardened(
    name,
    cfg,
    hist,
    target,
    names,
    args,
    folder,
):
    result = _ORIGINAL_ENCODER_TARGET_RUN(
        name,
        cfg,
        hist,
        target,
        names,
        args,
        folder,
    )

    # Original Suite19 contract:
    # (avg_scores, std_scores, primary_seed_pair, total_runtime, metadata)
    avg, std, primary, total_time, metadata = result

    if primary is not None:
        ledger, _probe = primary

        ca = pd.DataFrame(
            getattr(
                ledger,
                "coordinate_audit",
                [],
            )
        )

        out = (
            Path(folder)
            / name
            / "latent_coordinate_alignment.csv"
        )

        ca.to_csv(
            out,
            index=False,
        )

        final_reporting.print_table(
            f"{core.DISPLAY.get(name, name)} "
            "— COMMON LATENT COORDINATE AUDIT",
            ca,
            max_rows=100,
        )

        if len(ca):
            histca = ca[
                ca.scope == "hist"
            ]

            if len(histca):
                print(
                    f"[COORDINATE TRAJECTORY {name}] "
                    f"system={COORDINATE_SYSTEM} "
                    f"windows={len(histca)} "
                    f"mean_rank="
                    f"{histca.whiten_rank.mean():.2f} "
                    f"worst_rank="
                    f"{histca.whiten_rank.min():.0f} "
                    f"median_condition="
                    f"{histca.covariance_condition.median():.3g} "
                    f"mean_raw_ProcrustesR2="
                    f"{histca.raw_procrustes_r2.mean():+.4f}"
                )

    return result


core._encoder_target_run = (
    _encoder_target_run_hardened
)


# ---------------------------------------------------------------------
# More informative historical selector printing.
# ---------------------------------------------------------------------
_ORIGINAL_SELECT_CONFIG = (
    core._select_config
)


def _select_config_final(
    name,
    hist,
    target,
    names,
    args,
    folder,
    base_nca_config=None,
):
    configs = core._encoder_configs(
        name,
        args,
        base_nca_config,
    )

    rows = []
    best = None

    print(
        f"\n[ENCODER SELECTION] "
        f"{core.DISPLAY.get(name, name)} "
        "— historical OOF only"
    )

    print(
        "[SELECTION RULE] Both predeclared paths are scored: "
        "CommitteeResidual(z)-Committee AND "
        "HGB([X,z])-HGB(X). "
        "The stronger robust HISTORICAL path defines selection_basis."
    )

    for ci, cfg in enumerate(
        configs,
        1,
    ):
        started = time.perf_counter()
        status = "ok"
        reason = ""

        led = probe = None
        diag = {}
        stats = {
            "score": -np.inf,
        }

        try:
            led = core._run_ledger(
                name,
                cfg,
                args.seeds[0],
                hist,
                target,
                names,
                args,
                folder,
                False,
            )

            probe = core._run_probes(
                name,
                cfg,
                args.seeds[0],
                hist,
                target,
                led,
                args,
                folder,
                False,
            )

            diag = core.representation_diagnostics(
                led.hist_z,
                hist.y,
                hist.faculty_idx,
                hist.teacher.mean(1),
                led.hist_available,
                max_pairs=args.diagnostic_max_pairs,
                seed=args.seeds[0],
            )

            stats = final_reporting.selection_stats(
                hist,
                led,
                probe,
            )

            guard = core._candidate_guard(
                led,
                diag,
                args,
                time.perf_counter()
                - started,
            )

            if guard:
                status = "reject"
                reason = ";".join(guard)

        except Exception as exc:
            status = "error"
            reason = (
                f"{type(exc).__name__}: "
                f"{exc}"
            )

            if args.verbose_errors:
                traceback.print_exc()

        runtime = (
            time.perf_counter()
            - started
        )

        row = {
            "candidate": ci,
            "encoder": name,
            "config": json.dumps(
                cfg,
                sort_keys=True,
            ),
            "status": status,
            "reason": reason,
            "runtime_seconds": runtime,
            "effective_rank":
                diag.get(
                    "effective_rank",
                    np.nan,
                ),
            "dead_dimension_fraction":
                diag.get(
                    "dead_dimension_fraction",
                    np.nan,
                ),
            "coverage":
                diag.get(
                    "availability_rate",
                    np.nan,
                ),
            **stats,
        }

        rows.append(row)

        print(
            f"  cand={ci:02d} "
            f"cfg={cfg} "
            f"status={status:6s} "
            f"basis={row.get('selection_basis', '?'):35s} "
            f"primaryScore={row.get('score', np.nan):+.5f}"
        )

        print(
            "      RESIDUAL "
            f"score={row.get('residual_score', np.nan):+.5f} "
            f"mean/med/q25/recent/worst="
            f"{row.get('residual_mean_delta_ap', np.nan):+.4f}/"
            f"{row.get('residual_median_delta_ap', np.nan):+.4f}/"
            f"{row.get('residual_q25_delta_ap', np.nan):+.4f}/"
            f"{row.get('residual_recent_mean_delta_ap', np.nan):+.4f}/"
            f"{row.get('residual_worst_block_mean_delta_ap', np.nan):+.4f} "
            f"wins={row.get('residual_win_rate', np.nan):.1%}"
        )

        print(
            "      X+Z      "
            f"score={row.get('xz_score', np.nan):+.5f} "
            f"mean/med/q25/recent/worst="
            f"{row.get('xz_mean_delta_ap', np.nan):+.4f}/"
            f"{row.get('xz_median_delta_ap', np.nan):+.4f}/"
            f"{row.get('xz_q25_delta_ap', np.nan):+.4f}/"
            f"{row.get('xz_recent_mean_delta_ap', np.nan):+.4f}/"
            f"{row.get('xz_worst_block_mean_delta_ap', np.nan):+.4f} "
            f"wins={row.get('xz_win_rate', np.nan):.1%}"
        )

        print(
            f"      coverage={row.get('coverage', np.nan):.1%} "
            f"rank={row.get('effective_rank', np.nan):.2f} "
            f"dead={row.get('dead_dimension_fraction', np.nan):.1%} "
            f"time={runtime:.1f}s"
        )

        if reason:
            print(
                f"      REJECT/ERROR: {reason}"
            )

        if status == "ok":
            key = (
                row["score"],
                max(
                    row.get(
                        "residual_mean_delta_ap",
                        -np.inf,
                    ),
                    row.get(
                        "xz_mean_delta_ap",
                        -np.inf,
                    ),
                ),
                row.get(
                    "xz_win_rate",
                    0.0,
                ),
                row.get(
                    "residual_win_rate",
                    0.0,
                ),
                -cfg.get(
                    "latent_dim",
                    999,
                ),
                -ci,
            )

            if (
                best is None
                or key > best[0]
            ):
                best = (
                    key,
                    cfg,
                    row,
                )

    df = pd.DataFrame(rows)

    df.to_csv(
        Path(folder)
        / f"{name}_selection_candidates.csv",
        index=False,
    )

    if best is None:
        raise RuntimeError(
            f"All {name} candidates "
            "failed/rejected."
        )

    cfg = best[1]
    selected_row = best[2]

    Path(folder).mkdir(
        parents=True,
        exist_ok=True,
    )

    (
        Path(folder)
        / f"{name}_selected_config.json"
    ).write_text(
        json.dumps(
            {
                "config": cfg,
                "selection": selected_row,
                "selection_contract":
                    "stronger of two "
                    "predeclared historical "
                    "conditional-information paths",
            },
            indent=2,
            default=str,
        )
    )

    print(
        f"[ENCODER SELECTED] "
        f"{core.DISPLAY.get(name, name)} "
        f"config={cfg} "
        f"basis={selected_row.get('selection_basis')} "
        f"historicalScore={selected_row.get('score', np.nan):+.5f}"
    )

    return cfg, selected_row


core._select_config = (
    _select_config_final
)


# ---------------------------------------------------------------------
# Add reference-root diagnostics before each real fold.
# ---------------------------------------------------------------------
_ORIGINAL_RUN_FOLD = core.run_fold


def _run_fold_final(
    args,
    faculties,
    fold,
    out,
):
    if not args.synthetic_smoke:
        reference_dirs = {
            "suite17_final":
                args.suite17_results_dir,
            "suite17_raw":
                args.suite17_results_dir,
            "suite18_final":
                args.suite18_results_dir,
            "suite18_raw":
                args.suite18_results_dir,
            "suite16":
                args.suite16_results_dir,
            "suite14":
                args.suite14_results_dir,
            "v2":
                args.v2_results_dir,
            "council":
                args.council_results_dir,
        }

        final_reporting.print_reference_root_audit(
            reference_dirs,
            fold,
        )

    return _ORIGINAL_RUN_FOLD(
        args,
        faculties,
        fold,
        out,
    )


core.run_fold = _run_fold_final


# ---------------------------------------------------------------------
# Preserve the core postprocessing and then add the final authoritative
# reference envelope + project-SOTA report.
# ---------------------------------------------------------------------
_ORIGINAL_POSTPROCESS = (
    core.postprocess
)


def _postprocess_final(
    args,
    out,
    fold_results,
):
    verdict = _ORIGINAL_POSTPROCESS(
        args,
        out,
        fold_results,
    )

    final_reporting.write_final_reports(
        args,
        out,
        fold_results,
    )

    return verdict


core.postprocess = _postprocess_final

# ---------------------------------------------------------------------
# Repair Suite17 target-block metadata.
#
# Suite17's extract_temporal_groups() requires >=2 distinct temporal
# values, which is appropriate for cross-fitting but not for a target
# fold containing one future semester.
#
# We preserve the strict fail-closed production chronology check and
# reconstruct audit-only target block IDs from target_semester.
# ---------------------------------------------------------------------
_ORIGINAL_LOAD_FOLD = core._load_fold


def _load_fold_final(args, faculties, fold):
    hist, target, names = _ORIGINAL_LOAD_FOLD(
        args,
        faculties,
        fold,
    )

    target, temporal_audit = repair_target_blocks(
        hist,
        target,
    )

    print("\n[TARGET TEMPORAL METADATA REPAIR / ASSERTION]")
    print("-" * 120)

    print(
        "  original Suite17 target.blocks may be unavailable "
        "because the target frame contains a single temporal group."
    )

    for row in temporal_audit:
        if row["scope"] == "global":
            print(
                f"  source={row['source']} | "
                f"hist_block_max={row['historical_block_max']:g} | "
                f"target_block_min/max="
                f"{row['target_block_min']:g}/"
                f"{row['target_block_max']:g} | "
                f"raw_hist_semester_max="
                f"{row.get('raw_hist_semester_max', float('nan')):g} | "
                f"raw_target_semester_min="
                f"{row.get('raw_target_semester_min', float('nan')):g} | "
                f"strict={row['strict_after_history']}"
            )

    pd.DataFrame(temporal_audit).to_csv(
        Path(args.out_dir)
        / f"fold_{fold}"
        / "target_temporal_metadata_audit.csv",
        index=False,
    )

    return hist, target, names


core._load_fold = _load_fold_final

def main(argv=None):
    print(
        f"[SUITE19 FINAL PACKAGE] "
        f"version={FINAL_PACKAGE_VERSION}"
    )

    print(
        "[FINAL SCIENTIFIC CONTRACT] "
        f"OOF coordinate system="
        f"{COORDINATE_SYSTEM}"
    )

    print(
        "[FINAL SCIENTIFIC CONTRACT] "
        "Target chronology fails closed; "
        "global probes cannot consume native "
        "unaligned temporal embeddings."
    )

    print(
        "[FINAL SCIENTIFIC CONTRACT] "
        "Representation success may come from "
        "either predeclared conditional pathway: "
        "X+z vs X OR residual(z) vs Committee."
    )

    print(
        "[FINAL SCIENTIFIC CONTRACT] "
        "Project-SOTA is evaluated separately "
        "against the best aligned prior system "
        "for every faculty×holdout-fold cell."
    )

    core.main(argv)

    # Never pass a pandas DataFrame or partial result object
    # to SystemExit.
    return 0


if __name__ == "__main__":
    raise SystemExit(main())