# -*- coding: utf-8 -*-
"""Suite19 — Learned Representation Audit.

Scientific question
-------------------
Does a modern learned representation of the existing chronology-safe academic
feature space simplify prediction and, more importantly, add stable conditional
information beyond raw X and the immutable Suite17 Committee?

This is intentionally an AUDIT.  It does not deploy Suite17's R/M/L specialist
cascade and never tunes representations/probes on target-fold labels.
"""
from __future__ import annotations

import argparse
from dataclasses import dataclass
from pathlib import Path
import hashlib
import json
import os
import sys
import time
import traceback
from types import SimpleNamespace
from typing import Any

import joblib
import numpy as np
import pandas as pd
from sklearn.neighbors import NearestNeighbors

from suite19_common import (
    atomic_json_dump, import_suite17, metric_dict, package_versions,
    parse_csv_floats, parse_csv_ints, parse_csv_strings, print_table,
    runtime_snapshot, safe_ap, safe_auc, seed_everything,
)
from suite19_encoders import (
    TabMRepresentationEncoder, ModernNCAEncoder, RFMAGOPEncoder,
    PCARepresentationEncoder, RandomProjectionRepresentationEncoder,
)
from suite19_prequential import build_prequential_ledger
from suite19_probes import run_probe_matrix
from suite19_diagnostics import (
    representation_diagnostics, temporal_drift_rows, mechanism_probe_rows,
    residual_sign_probe, redundancy_audit_rows, hard_case_audit_rows,
    rfm_eigenvector_loadings, nca_difficulty_rows, direction_stability_rows,
)
from suite19_reporting import (
    faculty_fold_rows, paired_summary, paired_table, bootstrap_ci,
    reference_scores_for_faculty, summarize_encoder_verdict,
    next_architecture_decision, operational_metrics, print_verdict_table,
)

from suite19_incremental import (
    build_incremental_context,
    identity_context,
)

DISPLAY={
    'tabm':'TabM',
    'modern_nca':'ModernNCA',
    'modern_nca_hard':'ModernNCA + Committee-hard sampling',
    'modern_nca_mechanism':'Mechanism-aware ModernNCA',
    'rfm':'RFM / AGOP',
}
PRIMARY_ENCODERS=tuple(DISPLAY)
CONTROL_ENCODERS=('pca','random_projection')


def _jsonable(x):
    if isinstance(x,np.ndarray):return x.tolist()
    if isinstance(x,(np.integer,np.floating)):return x.item()
    return str(x)


def _save_json(obj,path):
    p=Path(path);p.parent.mkdir(parents=True,exist_ok=True);p.write_text(json.dumps(obj,indent=2,default=_jsonable))


def _committee_meta(teacher):
    p=np.clip(np.asarray(teacher,float),1e-6,1-1e-6);mean=p.mean(1);mn=p.min(1);mx=p.max(1);std=p.std(1);spread=mx-mn;vote=(p>=.5).mean(1);ent=-(mean*np.log(mean)+(1-mean)*np.log(1-mean))
    # Keep the individual base probabilities and statistics. Committee mean is
    # supplied separately by the residual probe, exactly as the Suite19 spec asks.
    return np.column_stack([p,mn,mx,std,spread,vote,ent]).astype(np.float32)


def _safe_mechanism(bundle):
    m=np.asarray(bundle.mechanism_targets,np.float32)
    # Suite17's column 2 is literally y. It is excluded from mechanism-aware
    # representation supervision to avoid disguising outcome supervision as a
    # mechanism label. Student/course/mastery summaries remain.
    if m.ndim==2 and m.shape[1]>=4:return m[:,[0,1,3]]
    return m


def _encoder_configs(name,args,base_nca_config=None):
    dims=args.latent_dims;out=[]
    if name=='tabm':
        for d in dims:
            for depth in args.tabm_depths:out.append({'latent_dim':d,'depth':depth})
    elif name=='modern_nca':
        for d in dims:
            for t in args.nca_temperatures:
                for aux in args.nca_aux_bce_grid:out.append({'latent_dim':d,'temperature':t,'aux_bce':aux})
    elif name in {'modern_nca_hard','modern_nca_mechanism'}:
        # Controlled ablation: when base NCA was selected in this fold, change
        # only the requested mechanism/sampling principle. This avoids turning
        # an ablation into a separate broad hyperparameter search.
        if base_nca_config is not None:return [dict(base_nca_config)]
        for d in dims:
            for t in args.nca_temperatures:
                for aux in args.nca_aux_bce_grid:out.append({'latent_dim':d,'temperature':t,'aux_bce':aux})
    elif name=='rfm':
        for d in dims:
            for r in args.rfm_recursions:
                for bw in args.rfm_bandwidths:out.append({'latent_dim':d,'recursions':r,'bandwidth':bw})
    elif name in CONTROL_ENCODERS:
        out=[{'latent_dim':d} for d in dims]
    else:raise KeyError(name)
    return out


def _make_factory(name,cfg,args):
    def factory(seed):
        if name=='tabm':
            return TabMRepresentationEncoder(
                latent_dim=cfg['latent_dim'],depth=cfg['depth'],ensemble_size=args.tabm_ensemble_size,
                dropout=args.tabm_dropout,epochs=args.tabm_epochs,batch_size=args.tabm_batch_size,
                lr=args.tabm_lr,weight_decay=args.neural_weight_decay,class_beta=args.class_beta,
                seed=seed,device=args.device,max_train_rows=args.max_encoder_train_rows,
                backend=('internal' if args.synthetic_smoke else args.tabm_backend),arch_type=args.tabm_arch_type,
            )
        if name in {'modern_nca','modern_nca_hard','modern_nca_mechanism'}:
            return ModernNCAEncoder(
                latent_dim=cfg['latent_dim'],hidden_dim=args.nca_hidden_dim,epochs=args.nca_epochs,
                batch_size=args.nca_batch_size,temperature=cfg['temperature'],lr=args.nca_lr,
                weight_decay=args.neural_weight_decay,aux_bce=cfg['aux_bce'],
                hard_sampling=(name=='modern_nca_hard'),hard_strength=args.nca_hard_strength,
                mechanism_aware=(name=='modern_nca_mechanism'),mechanism_tau=args.nca_mechanism_tau,
                class_beta=args.class_beta,seed=seed,device=args.device,max_train_rows=args.max_encoder_train_rows,
                retrieval_k=args.nca_retrieval_k,backend=args.nca_backend,
                retrieval_query_chunk=args.nca_retrieval_query_chunk,
                retrieval_memory_chunk=args.nca_retrieval_memory_chunk,
            )
        if name=='rfm':
            return RFMAGOPEncoder(
                latent_dim=cfg['latent_dim'],recursions=cfg['recursions'],centers=args.rfm_centers,
                agop_rows=args.rfm_agop_rows,ridge=args.rfm_ridge,bandwidth=cfg['bandwidth'],
                metric_floor=args.rfm_metric_floor,seed=seed,
                backend=('internal' if args.synthetic_smoke else args.rfm_backend),device=args.device,
                max_train_rows=args.rfm_max_train_rows,mem_gb=args.rfm_mem_gb,
            )
        if name=='pca':return PCARepresentationEncoder(latent_dim=cfg['latent_dim'],seed=seed)
        if name=='random_projection':return RandomProjectionRepresentationEncoder(latent_dim=cfg['latent_dim'],seed=seed)
        raise KeyError(name)
    factory.__name__=f'{name}_factory'
    return factory


def _cache_key(name,config,seed,phase):
    blob=json.dumps({'name':name,'config':config,'seed':int(seed),'phase':phase},sort_keys=True).encode();return hashlib.sha1(blob).hexdigest()[:14]


def _ledger_cache_path(
    folder,
    name,
    cfg,
    seed,
    phase,
):
    return (
        Path(folder)
        / "cache"
        / (
            f"{name}_{phase}_"
            f"{_cache_key(name,cfg,seed,phase)}"
            ".joblib"
        )
    )


def _safe_load_joblib(path):
    path = Path(path)

    if not path.exists():
        return None

    try:
        return joblib.load(path)
    except Exception:
        return None


def _probe_cache_path(
    folder,
    name,
    cfg,
    ledger,
    seed,
    phase,
    args,
    *,
    target_only=False,
):
    identity = {
        **cfg,
        "ledger": ledger.signature,
        "hgb": args.probe_hgb_iter,
    }

    if target_only:
        identity[
            "probe_mode"
        ] = "target_only_v1"

    key = _cache_key(
        name,
        identity,
        seed,
        phase,
    )

    return (
        Path(folder)
        / "probe_cache"
        / f"{name}_{key}.joblib"
    )


def _run_ledger(
    name,
    cfg,
    seed,
    hist,
    target,
    names,
    args,
    folder,
    with_target,
):
    phase = (
        "production"
        if with_target
        else "selection"
    )

    factory = _make_factory(
        name,
        cfg,
        args,
    )

    mech = _safe_mechanism(hist)

    tmech = (
        _safe_mechanism(target)
        if with_target
        else None
    )

    cp = _ledger_cache_path(
        folder,
        name,
        cfg,
        seed,
        phase,
    )

    cache_cfg = {
        "suite19_version": 1,
        "encoder": name,
        "config": cfg,
        "phase": phase,
        "fold": int(
            args._current_fold
        ),
        "tabm_backend":
            args.tabm_backend,
        "rfm_backend":
            args.rfm_backend,
        "nca_backend":
            args.nca_backend,
    }

    if name in {
        "modern_nca",
        "modern_nca_hard",
        "modern_nca_mechanism",
    }:
        cache_cfg.update(
            {
                "nca_retrieval_implementation":
                    "exact_streaming_topk_v1",
                "nca_retrieval_k":
                    int(
                        args.nca_retrieval_k
                    ),
                "nca_retrieval_query_chunk":
                    int(
                        args
                        .nca_retrieval_query_chunk
                    ),
                "nca_retrieval_memory_chunk":
                    int(
                        args
                        .nca_retrieval_memory_chunk
                    ),
            }
        )

    reuse_context = None

    incremental = bool(
        getattr(
            args,
            "incremental_runtime",
            False,
        )
    )

    # --------------------------------------------------------------
    # Production seed 42 can reuse this SAME FOLD's selection
    # historical representation.
    # --------------------------------------------------------------
    if (
        incremental
        and with_target
        and int(seed)
            == int(args.seeds[0])
    ):
        selection_path = (
            _ledger_cache_path(
                folder,
                name,
                cfg,
                seed,
                "selection",
            )
        )

        selection_ledger = (
            _safe_load_joblib(
                selection_path
            )
        )

        if selection_ledger is not None:
            reuse_context = {
                "ledger":
                    selection_ledger,
                "fold_context":
                    identity_context(
                        hist,
                        args._current_fold,
                    ),
                "source":
                    str(selection_path),
            }

            print(
                "[RUNTIME OPT] "
                f"{name} production "
                f"seed={seed}: "
                "reusing SAME-FOLD "
                "selection history."
            )



    # Selection does not use native/direct historical predictions.
    compute_historical_scores = (
        with_target
        or not incremental
    )

    return build_prequential_ledger(
        hist.flat,
        hist.y,
        hist.blocks,
        hist.faculty_idx,
        hist.teacher.mean(1),
        mech,
        factory,

        latent_dim=
            cfg["latent_dim"],

        target_X=(
            target.flat
            if with_target
            else None
        ),

        target_committee=(
            target.teacher.mean(1)
            if with_target
            else None
        ),

        target_mechanism=
            tmech,

        target_blocks=(
            target.blocks
            if with_target
            else None
        ),

        min_prior_blocks=
            args
            .representation_min_prior_blocks,

        min_train_rows=
            args
            .representation_min_train_rows,

        min_failures=
            args
            .representation_min_failures,

        seed=seed,

        feature_names=
            names,

        cache_path=
            cp,

        cache_config=
            cache_cfg,

        force=
            args.force_encoder,

        clip_z=
            args.clip_z,

        min_coverage_guard=
            args
            .min_oof_representation_coverage,

        max_runtime_seconds=
            args.max_encoder_seconds,

        reuse_context=
            reuse_context,

        compute_historical_scores=
            compute_historical_scores,
    )


def _run_probes(
    name,
    cfg,
    seed,
    hist,
    target,
    led,
    args,
    folder,
    with_target,
    historical=True,
):
    phase = (
        "production"
        if with_target
        else "selection"
    )

    incremental = bool(
        getattr(
            args,
            "incremental_runtime",
            False,
        )
    )

    legacy_path = (
        _probe_cache_path(
            folder,
            name,
            cfg,
            led,
            seed,
            phase,
            args,
            target_only=False,
        )
    )

    # Existing caches — including verified Fold 1 caches —
    # must always take priority.
    if (
        legacy_path.exists()
        and not args.force_probe
    ):
        try:
            return joblib.load(
                legacy_path
            )
        except Exception:
            pass

    target_only = bool(
        with_target
        and not historical
    )

    p = (
        _probe_cache_path(
            folder,
            name,
            cfg,
            led,
            seed,
            phase,
            args,
            target_only=
                target_only,
        )
        if target_only
        else legacy_path
    )

    if (
        p.exists()
        and not args.force_probe
    ):
        try:
            return joblib.load(p)
        except Exception:
            pass

    reuse_result = None
    reuse_ctx = None

    # --------------------------------------------------------------
    # Production seed 42:
    # reuse same-fold selection historical probes.
    # --------------------------------------------------------------
    if (
        incremental
        and with_target
        and historical
        and int(seed)
            == int(args.seeds[0])
    ):
        selection_ledger_path = (
            _ledger_cache_path(
                folder,
                name,
                cfg,
                seed,
                "selection",
            )
        )

        selection_ledger = (
            _safe_load_joblib(
                selection_ledger_path
            )
        )

        if selection_ledger is not None:
            selection_probe_path = (
                _probe_cache_path(
                    folder,
                    name,
                    cfg,
                    selection_ledger,
                    seed,
                    "selection",
                    args,
                    target_only=False,
                )
            )

            selection_probe = (
                _safe_load_joblib(
                    selection_probe_path
                )
            )

            if selection_probe is not None:
                reuse_result = (
                    selection_probe
                )

                reuse_ctx = (
                    identity_context(
                        hist,
                        args._current_fold,
                    )
                )

                print(
                    "[RUNTIME OPT] "
                    f"{name} production "
                    f"seed={seed}: "
                    "reusing SAME-FOLD "
                    "selection probe history."
                )


    r = run_probe_matrix(
        hist.flat,
        hist.y,
        hist.blocks,
        hist.faculty_idx,
        hist.teacher.mean(1),
        led.hist_z,
        led.hist_available,

        target_X=(
            target.flat
            if with_target
            else None
        ),

        target_z=(
            led.target_z
            if with_target
            else None
        ),

        target_committee=(
            target.teacher.mean(1)
            if with_target
            else None
        ),

        target_z_available=(
            led.target_available
            if with_target
            else None
        ),

        committee_meta=
            _committee_meta(
                hist.teacher
            ),

        target_committee_meta=(
            _committee_meta(
                target.teacher
            )
            if with_target
            else None
        ),

        faculty_names=
            hist.faculty_names,

        min_prior_blocks=
            args.probe_min_prior_blocks,

        min_train_rows=
            args.probe_min_train_rows,

        min_failures=
            args.probe_min_failures,

        hgb_iter=
            args.probe_hgb_iter,

        class_beta=
            args.class_beta,

        seed=seed,

        clip_z=
            args.clip_z,

        max_train_rows=
            args.probe_max_train_rows,

        use_suite17_residual=
            not args.synthetic_smoke,

        require_suite17_residual=
            not args.synthetic_smoke,

        residual_eta_grid=
            args.residual_eta_grid,

        residual_iter_candidates=
            args
            .residual_iter_candidates,

        residual_max_rows=
            args.probe_max_train_rows,

        residual_min_prior_blocks=
            args
            .residual_min_prior_blocks,

        residual_min_faculties=
            args
            .residual_min_faculties,

        residual_min_failures=
            args
            .residual_min_failures,

        residual_min_rows=
            args.residual_min_rows,

        compute_historical=
            historical,

        reuse_result=
            reuse_result,

        reuse_previous_blocks=(
            None
            if reuse_ctx is None
            else
            reuse_ctx
            .previous_hist.blocks
        ),

        reuse_previous_to_current=(
            None
            if reuse_ctx is None
            else
            reuse_ctx
            .previous_to_current
        ),

        reuse_blocks=(
            None
            if reuse_ctx is None
            else
            reuse_ctx.shared_blocks
        ),
    )

    p.parent.mkdir(
        parents=True,
        exist_ok=True,
    )

    joblib.dump(
        r,
        p,
        compress=3,
    )

    return r


def _selection_cells(hist,led,probe):
    q=hist.teacher.mean(1);rows=[];valid=np.asarray(led.hist_available,bool)
    for block in sorted(v for v in np.unique(hist.blocks[valid]) if np.isfinite(v)):
        for fi,fac in enumerate(hist.faculty_names):
            m=valid&(hist.blocks==block)&(hist.faculty_idx==fi)&np.isfinite(probe.hist_scores['committee_residual'])&np.isfinite(probe.hist_scores['hgb_xz'])&np.isfinite(probe.hist_scores['raw_hgb'])
            if m.sum()<10 or np.unique(hist.y[m]).size<2:continue
            rows.append({'block':float(block),'faculty':fac,'rows':int(m.sum()),'failures':int(hist.y[m].sum()),'conditional_delta_ap':safe_ap(hist.y[m],probe.hist_scores['committee_residual'][m])-safe_ap(hist.y[m],q[m]),'xz_delta_ap':safe_ap(hist.y[m],probe.hist_scores['hgb_xz'][m])-safe_ap(hist.y[m],probe.hist_scores['raw_hgb'][m])})
    return rows


def _selection_stats(hist,led,probe):
    cells=_selection_cells(hist,led,probe)
    if not cells:return {'score':-np.inf,'mean_conditional_delta_ap':np.nan,'median_conditional_delta_ap':np.nan,'q25_conditional_delta_ap':np.nan,'recent_mean_conditional_delta_ap':np.nan,'mean_xz_delta_ap':np.nan,'win_rate':0.,'cells':0}
    df=pd.DataFrame(cells);c=df.conditional_delta_ap.to_numpy(float);x=df.xz_delta_ap.to_numpy(float);last=df.block.max();recent=df[df.block==last].conditional_delta_ap.to_numpy(float);score=.35*np.mean(c)+.30*np.median(c)+.15*np.quantile(c,.25)+.10*np.mean(recent)+.10*np.mean(x)-.5*max(0.,-np.quantile(c,.25))
    return {'score':float(score),'mean_conditional_delta_ap':float(np.mean(c)),'median_conditional_delta_ap':float(np.median(c)),'q25_conditional_delta_ap':float(np.quantile(c,.25)),'recent_mean_conditional_delta_ap':float(np.mean(recent)),'mean_xz_delta_ap':float(np.mean(x)),'win_rate':float(np.mean(c>0)),'cells':len(c)}


def _candidate_guard(led,diag,args,elapsed):
    reasons=[]
    if led.chronology_violations:reasons.append(f'chronology_violations={led.chronology_violations}')
    if diag.get('availability_rate',0)<args.min_oof_representation_coverage:reasons.append(f'coverage={diag.get("availability_rate",0):.3f}')
    if diag.get('dead_dimension_fraction',0)>.90:reasons.append(f'dead_dimensions={diag.get("dead_dimension_fraction"):.3f}')
    if diag.get('latent_dim',1)>1 and 0<diag.get('effective_rank',0)<1.05:reasons.append(f'effective_rank={diag.get("effective_rank"):.3f}')
    if args.max_encoder_seconds>0 and elapsed>args.max_encoder_seconds:reasons.append(f'runtime={elapsed:.1f}>{args.max_encoder_seconds}')
    return reasons


def _select_config(name,hist,target,names,args,folder,base_nca_config=None):
    rows=[];best=None;seed=args.seeds[0];configs=_encoder_configs(name,args,base_nca_config)
    print('\n'+'='*160);print(f'ENCODER HISTORICAL SELECTION — {DISPLAY.get(name,name)}');print('Target-fold labels are not consulted. Every representation/probe row below is prequential.');print('='*160)
    if name in {'modern_nca_hard','modern_nca_mechanism'} and base_nca_config is not None:print(f'[CONTROLLED ABLATION] Reusing base ModernNCA-selected architecture/hyperparameters: {base_nca_config}')
    for ci,cfg in enumerate(configs,1):
        t0=time.perf_counter();snap0=runtime_snapshot();status='ok';reason='';st={};diag={};led=None;probe=None
        try:
            led=_run_ledger(name,cfg,seed,hist,target,names,args,folder,False);probe=_run_probes(name,cfg,seed,hist,target,led,args,folder,False);diag=representation_diagnostics(led.hist_z,hist.y,hist.faculty_idx,hist.teacher.mean(1),led.hist_available,max_pairs=args.diagnostic_max_pairs,seed=seed);st=_selection_stats(hist,led,probe);guard=_candidate_guard(led,diag,args,time.perf_counter()-t0)
            if guard:status='reject';reason=';'.join(guard)
        except Exception as e:
            status='error';reason=f'{type(e).__name__}: {e}';st={'score':-np.inf}
            if args.verbose_errors:traceback.print_exc()
        snap1=runtime_snapshot();row={'candidate':ci,'encoder':name,'config':json.dumps(cfg,sort_keys=True),'status':status,'reason':reason,'runtime_seconds':time.perf_counter()-t0,'rss_delta_mb':snap1.get('rss_mb',np.nan)-snap0.get('rss_mb',np.nan),'gpu_peak_mb':snap1.get('gpu_peak_mb',np.nan),'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),**st};rows.append(row)
        print(f"  cand={ci:02d} cfg={cfg} status={status:6s} | score={row.get('score',np.nan):+.5f} cond(mean/med/q25/recent)={row.get('mean_conditional_delta_ap',np.nan):+.4f}/{row.get('median_conditional_delta_ap',np.nan):+.4f}/{row.get('q25_conditional_delta_ap',np.nan):+.4f}/{row.get('recent_mean_conditional_delta_ap',np.nan):+.4f} XZ={row.get('mean_xz_delta_ap',np.nan):+.4f} wins={row.get('win_rate',np.nan):.1%} coverage={row.get('coverage',np.nan):.1%} rank={row.get('effective_rank',np.nan):.2f} time={row['runtime_seconds']:.1f}s"+(f' | REJECT/ERROR: {reason}' if reason else ''))
        if led is not None:
            print(f"      chronology={led.chronology_violations} violations | train/query windows={len([r for r in led.chronology_audit if r['scope']=='hist'])} | dead={diag.get('dead_dimension_fraction',np.nan):.1%} | neighborhood purity={diag.get('neighborhood_label_purity',np.nan):.3f}")
        if status=='ok':
            key=(row['score'],row.get('mean_conditional_delta_ap',-np.inf),row.get('mean_xz_delta_ap',-np.inf),-cfg.get('latent_dim',999),-ci)
            if best is None or key>best[0]:best=(key,cfg,row)
    pd.DataFrame(rows).to_csv(folder/f'{name}_selection_candidates.csv',index=False)
    if best is None:raise RuntimeError(f'All {name} candidates failed/rejected. See {folder/name}_selection_candidates.csv')
    print(f'[ENCODER SELECTED] {DISPLAY.get(name,name)} | config={best[1]} | historical selection score={best[2]["score"]:+.5f}')
    _save_json({'encoder':name,'selected_config':best[1],'selection_row':best[2]},folder/f'{name}_selected_config.json')
    return best[1],rows


def _aggregate_scores(score_dicts):
    keys=sorted(set().union(*[set(x) for x in score_dicts]));mean={};std={}
    for k in keys:
        vals=[x[k] for x in score_dicts if k in x];a=np.stack(vals,0).astype(float);mean[k]=np.nanmean(a,axis=0).astype(np.float32);std[k]=np.nanstd(a,axis=0).astype(np.float32)
    return mean,std


def _print_chronology(name,seed,led,probe):
    print(f'\n[CHRONOLOGY AUDIT] {DISPLAY.get(name,name)} seed={seed}')
    cols=['scope','window','query_blocks','query_min_block','query_rows','train_rows','train_failures','train_max_block','available','strict_train_before_query','encoder_fit_seconds']
    print_table('  Representation chronology',pd.DataFrame(led.chronology_audit),cols=cols,max_rows=100)
    print_table('  Probe chronology',pd.DataFrame(probe.chronology_audit),max_rows=100)
    total=led.chronology_violations+probe.chronology_violations;print(f'  >>> ZERO-VIOLATION ASSERTION: representation={led.chronology_violations}, probe={probe.chronology_violations}, TOTAL={total}')
    if total:raise RuntimeError(f'Chronology violation detected for {name}')


def _encoder_target_run(name,cfg,hist,target,names,args,folder):
    score_seeds=[];seed_metric_rows=[];primary=None;total_time=0.;metas=[]
    print('\n'+'#'*160);print(f'PRODUCTION REPRESENTATION AUDIT — {DISPLAY.get(name,name)} — TARGET FOLD {args._current_fold}');print('#'*160)
    for si,seed in enumerate(args.seeds):
        print(f'\n[SEED {seed}] begin | backend TabM={"internal" if args.synthetic_smoke else args.tabm_backend} NCA={args.nca_backend} RFM={"internal" if args.synthetic_smoke else args.rfm_backend}')
        t0 = time.perf_counter()
        snap0 = runtime_snapshot()

        led = _run_ledger(
            name,
            cfg,
            seed,
            hist,
            target,
            names,
            args,
            folder,
            True,
        )

        compute_historical_probe = (
            not getattr(
                args,
                "incremental_runtime",
                False,
            )
            or si == 0
        )

        if not compute_historical_probe:
            print(
                f"[RUNTIME OPT] seed={seed}: "
                "skipping redundant historical "
                "probe scoring; target probe "
                "still trains from this seed's "
                "complete historical representation."
            )

        probe = _run_probes(
            name,
            cfg,
            seed,
            hist,
            target,
            led,
            args,
            folder,
            True,
            historical=
                compute_historical_probe,
        )

        elapsed = (
            time.perf_counter()
            - t0
        )

        total_time += elapsed
        scores={'committee':target.teacher.mean(1).astype(np.float32),**probe.target_scores}
        if led.target_native is not None and np.isfinite(led.target_native).any():scores['native_metric']=np.asarray(led.target_native,np.float32)
        if led.target_direct is not None and np.isfinite(led.target_direct).any():scores['direct_native']=np.asarray(led.target_direct,np.float32)
        score_seeds.append(scores);sr=faculty_fold_rows(args._current_fold,target.faculty_names,target.faculty_idx,target.y,scores,args.threshold_beta)
        for r in sr:r['seed']=seed;r['encoder']=name
        seed_metric_rows+=sr
        fd=folder/name/f'seed_{seed}';fd.mkdir(parents=True,exist_ok=True);pd.DataFrame(led.chronology_audit).to_csv(fd/'chronology_audit.csv',index=False);pd.DataFrame(probe.chronology_audit).to_csv(fd/'probe_chronology_audit.csv',index=False);pd.DataFrame(probe.selection_rows).to_csv(fd/'residual_selection.csv',index=False);_save_json({'historical_models':led.model_metadata,'production':led.production_metadata,'probe_backend':probe.backend,'runtime':{'seconds':elapsed,'before':snap0,'after':runtime_snapshot()}},fd/'model_metadata.json')
        if args.save_embeddings:np.savez_compressed(fd/'embeddings.npz',hist_z=led.hist_z,hist_available=led.hist_available,target_z=led.target_z,target_available=led.target_available)
        if si==0:primary=(led,probe)
        metas.append({'seed':seed,'chronology_violations':led.chronology_violations+probe.chronology_violations,'coverage':float(led.hist_available.mean()),'runtime_seconds':elapsed,'production_metadata':led.production_metadata})
        _print_chronology(name,seed,led,probe)
        print(f'[RESOURCE] seed={seed} runtime={elapsed:.1f}s | OOF coverage={led.hist_available.mean():.1%} | RSS={runtime_snapshot().get("rss_mb",np.nan):.1f} MB | GPU peak={runtime_snapshot().get("gpu_peak_mb",np.nan):.1f} MB')
        # Console result block per seed.
        md=pd.DataFrame(sr);macro=md.groupby('model')[['ap','auc','fbeta_at_20']].mean().reset_index().sort_values('ap',ascending=False);print_table(f'{DISPLAY.get(name,name)} SEED {seed} — TARGET MACRO FACULTY RESULTS',macro,max_rows=20)
    pd.DataFrame(seed_metric_rows).to_csv(folder/name/'seed_target_metrics.csv',index=False);avg,std=_aggregate_scores(score_seeds);return avg,std,primary,total_time,metas


def _top_by_faculty(score,faculty_idx,rate=.20,known=None):
    s=np.asarray(score,float);f=np.asarray(faculty_idx,int);out=np.zeros(len(s),bool);known=np.isfinite(s) if known is None else np.asarray(known,bool)
    for fi in np.unique(f):
        idx=np.where((f==fi)&known)[0]
        if not len(idx):continue
        k=max(1,int(round(len(idx)*rate)));out[idx[np.argsort(-s[idx],kind='mergesort')[:k]]]=True
    return out


def _council_rescue_masks(target,reference_full):
    if 'council' not in reference_full:return {}
    y=np.asarray(target.y,int);q=target.teacher.mean(1);known=np.isfinite(reference_full['council']);ctop=_top_by_faculty(reference_full['council'],target.faculty_idx,.20,known);qtop=_top_by_faculty(q,target.faculty_idx,.20)
    mask=(y==1)&known&ctop&(~qtop)
    if 'suite17_final' in reference_full:
        k=np.isfinite(reference_full['suite17_final']);s17top=_top_by_faculty(reference_full['suite17_final'],target.faculty_idx,.20,k);mask &= (~k)|(~s17top)
    return {'council_rescued_failure':mask}


def _neighbor_rows_for_mask(led,target,hist,mask,k=5,max_queries=30):
    m=np.asarray(mask,bool)&np.asarray(led.target_available,bool);qi=np.where(m)[0][:int(max_queries)];hm=np.asarray(led.hist_available,bool);hi=np.where(hm)[0]
    if not len(qi) or not len(hi):return []
    Z=np.asarray(led.hist_z,float)[hi];Q=np.asarray(led.target_z,float)[qi];nn=NearestNeighbors(n_neighbors=min(int(k),len(Z)),metric='euclidean').fit(Z);dist,ind=nn.kneighbors(Q);rows=[]
    for a,qidx in enumerate(qi):
        for rank,(d,j) in enumerate(zip(dist[a],ind[a]),1):
            hidx=hi[int(j)];rows.append({'query_index':int(qidx),'query_student_id':str(target.student_id[qidx]),'query_course_id':str(target.course_id[qidx]),'query_actual':int(target.y[qidx]),'neighbor_rank':rank,'neighbor_index':int(hidx),'neighbor_student_id':str(hist.student_id[hidx]),'neighbor_course_id':str(hist.course_id[hidx]),'neighbor_label':int(hist.y[hidx]),'distance':float(d),'same_course':bool(str(target.course_id[qidx])==str(hist.course_id[hidx])),'same_student':bool(str(target.student_id[qidx])==str(hist.student_id[hidx]))})
    return rows


def _save_encoder_diagnostics(name,hist,target,avg,primary,names,args,folder,reference_full):
    led,probe=primary;ed=folder/name;ed.mkdir(parents=True,exist_ok=True);hd=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]);td=representation_diagnostics(led.target_z,target.y,target.faculty_idx,target.teacher.mean(1),led.target_available,max_pairs=args.diagnostic_max_pairs,seed=args.seeds[0]+1);diagdf=pd.DataFrame([{'scope':'historical',**hd},{'scope':'target_DIAGNOSTIC_ONLY',**td}]);diagdf.to_csv(ed/'representation_diagnostics.csv',index=False);print_table(f'{DISPLAY.get(name,name)} — REPRESENTATION GEOMETRY',diagdf,max_rows=4)
    drift=pd.DataFrame(temporal_drift_rows(led.hist_z,hist.blocks,led.hist_available,hist.faculty_idx));drift.to_csv(ed/'temporal_representation_drift.csv',index=False);print_table(f'{DISPLAY.get(name,name)} — TEMPORAL REPRESENTATION DRIFT',drift,max_rows=40)
    mech=_safe_mechanism(hist);mnames=['student_history_risk','course_history_risk','mastery_deficiency'][:mech.shape[1]];mr=mechanism_probe_rows(led.hist_z,mech,mnames,led.hist_available,seed=args.seeds[0])+residual_sign_probe(led.hist_z,hist.y,hist.teacher.mean(1),led.hist_available,seed=args.seeds[0]);pd.DataFrame(mr).to_csv(ed/'mechanism_probes.csv',index=False);print_table(f'{DISPLAY.get(name,name)} — MECHANISM / RESIDUAL-SIGN PROBES',pd.DataFrame(mr),max_rows=30)
    rr=redundancy_audit_rows(led.hist_z,hist.flat,names,led.hist_available,seed=args.seeds[0]);pd.DataFrame(rr).to_csv(ed/'redundancy_audit.csv',index=False);print_table(f'{DISPLAY.get(name,name)} — REPRESENTATION REDUNDANCY AUDIT',pd.DataFrame(rr),max_rows=30)
    extra=_council_rescue_masks(target,reference_full);hard=hard_case_audit_rows(target.y,target.teacher.mean(1),{k:v for k,v in avg.items() if k!='committee'},warning_rate=.20,extra_masks=extra);pd.DataFrame(hard).to_csv(ed/'hard_case_audit.csv',index=False);print_table(f'{DISPLAY.get(name,name)} — HARD-CASE AUDIT',pd.DataFrame(hard),max_rows=80)
    if extra.get('council_rescued_failure',np.zeros(0,bool)).any():
        nr=_neighbor_rows_for_mask(led,target,hist,extra['council_rescued_failure'],5,30);pd.DataFrame(nr).to_csv(ed/'council_rescued_failure_neighbors.csv',index=False);print(f'[COUNCIL RESCUE] {name}: rescued-failure rows={int(extra["council_rescued_failure"].sum())}; saved nearest-neighbor inspection rows={len(nr)}')
    prod=led.production_metadata or {}
    if name=='rfm' and prod.get('metric_eigenvalues') is not None and prod.get('metric_eigenvectors_top') is not None:
        ev=np.asarray(prod['metric_eigenvalues'],float);vec=np.asarray(prod['metric_eigenvectors_top'],float);load=pd.DataFrame(rfm_eigenvector_loadings(ev,vec,names,top_k=12));load.to_csv(ed/'rfm_metric_loadings.csv',index=False);pd.DataFrame(prod.get('recursion_history',[])).to_csv(ed/'rfm_recursion_history.csv',index=False);print_table('RFM/AGOP — LEADING SUPERVISED DIRECTIONS',load,max_rows=80);print_table('RFM/AGOP — RECURSION HISTORY',pd.DataFrame(prod.get('recursion_history',[])),max_rows=20)
    if name.startswith('modern_nca') and 'native_metric' in avg:
        diff=pd.DataFrame(nca_difficulty_rows(target.y,target.teacher.mean(1),avg['native_metric'],target.faculty_idx));diff.to_csv(ed/'modern_nca_committee_difficulty.csv',index=False);print_table(f'{DISPLAY.get(name,name)} — PERFORMANCE BY COMMITTEE DIFFICULTY',diff,max_rows=20)
        ex=pd.DataFrame(prod.get('neighbor_examples',[]));
        if len(ex):
            ex['neighbor_student_id']=ex.neighbor_index.map(lambda i:str(hist.student_id[int(i)]) if int(i)<len(hist.student_id) else '');ex['neighbor_course_id']=ex.neighbor_index.map(lambda i:str(hist.course_id[int(i)]) if int(i)<len(hist.course_id) else '');ex['query_student_id']=ex.query_index.map(lambda i:str(target.student_id[int(i)]) if int(i)<len(target.student_id) else '');ex['query_course_id']=ex.query_index.map(lambda i:str(target.course_id[int(i)]) if int(i)<len(target.course_id) else '');ex.to_csv(ed/'modern_nca_neighbor_examples.csv',index=False);print_table(f'{DISPLAY.get(name,name)} — NEAREST-NEIGHBOR EXAMPLES',ex,max_rows=50)
    if name=='tabm':
        curves=[]
        for md in led.model_metadata:
            for r in md.get('training_curve',[]):curves.append({'scope':'hist','window':md.get('window'),**r})
        for r in prod.get('training_curve',[]):curves.append({'scope':'production','window':'target',**r})
        pd.DataFrame(curves).to_csv(ed/'tabm_training_curves.csv',index=False);print_table('TabM — TRAINING CURVE EXCERPT',pd.DataFrame(curves),max_rows=30)
    return hd,td


def _macro_target_table(metrics,encoder):
    d=metrics[metrics.encoder==encoder] if 'encoder' in metrics.columns else metrics
    return d.groupby('model').agg(faculties=('faculty','nunique'),rows=('rows','sum'),ap=('ap','mean'),auc=('auc','mean'),f2_at20=('fbeta_at_20','mean')).reset_index().sort_values('ap',ascending=False)


def _reference_full_arrays(target,reference_by_faculty):
    keys=sorted(set().union(*[set(v) for v in reference_by_faculty.values()])) if reference_by_faculty else [];
    out={k:np.full(len(target.y),np.nan,float) for k in keys}
    for fi,fac in enumerate(target.faculty_names):
        m=target.faculty_idx==fi
        for k,s in reference_by_faculty.get(fac,{}).items():out[k][m]=s
    return out


def _synthetic_bundle(fold,args):
    rng=np.random.default_rng(1300+fold);facnames=['khoa_cong_nghe_thong_tin','khoa_quan_tri_kinh_doanh','khoa_du_lich'];d=10;blocks=np.repeat(np.arange(1,8),args.synthetic_rows_per_block);n=len(blocks);X=rng.normal(size=(n,d)).astype(np.float32);fi=np.arange(n)%len(facnames);latent=X[:,0]*X[:,1]+.55*X[:,2]**2-.3*X[:,3]+.15*(fi==0);pr=1/(1+np.exp(-latent));y=(rng.random(n)<(.08+.38*pr)).astype(np.int8);q=np.clip(.08+.55*y+.12*rng.normal(size=n),.01,.99);teacher=np.column_stack([np.clip(q+rng.normal(0,.04,n),.01,.99) for _ in range(3)]).astype(np.float32);mech=np.column_stack([np.clip(.5-.2*X[:,0],0,1),np.clip(.4+.2*X[:,2],0,1),y,np.clip(.5-.2*X[:,1],0,1)]).astype(np.float32)
    nt=args.synthetic_target_rows;Xt=rng.normal(size=(nt,d)).astype(np.float32);fit=np.arange(nt)%len(facnames);lt=Xt[:,0]*Xt[:,1]+.55*Xt[:,2]**2-.3*Xt[:,3]+.15*(fit==0);pt=1/(1+np.exp(-lt));yt=(rng.random(nt)<(.08+.38*pt)).astype(np.int8);qt=np.clip(.08+.55*yt+.12*rng.normal(size=nt),.01,.99);tt=np.column_stack([np.clip(qt+rng.normal(0,.04,nt),.01,.99) for _ in range(3)]).astype(np.float32);mt=np.column_stack([np.clip(.5-.2*Xt[:,0],0,1),np.clip(.4+.2*Xt[:,2],0,1),yt,np.clip(.5-.2*Xt[:,1],0,1)]).astype(np.float32)
    def B(flat,y,teach,mech,faculty,blocks,offset=0):
        nn=len(y);return SimpleNamespace(flat=flat,y=y,teacher=teach,mechanism_targets=mech,faculty_idx=faculty,blocks=np.asarray(blocks,float),row_index=np.arange(nn),faculty_names=facnames,student_id=np.asarray([f'S{offset+i//4}' for i in range(nn)],object),course_id=np.asarray([f'C{i%17}' for i in range(nn)],object),target_semester=np.asarray(blocks,float))
    return B(X,y,teacher,mech,fi,blocks),B(Xt,yt,tt,mt,fit,np.full(nt,8),100000),[f'x{i}' for i in range(d)]


def _load_fold(args,faculties,fold):
    if args.synthetic_smoke:return _synthetic_bundle(fold,args)
    mods=import_suite17();return mods['suite17_pipeline'].load_fold_bundle(args.cache_dir,args.structured_cache_dir,faculties,fold)


def _discover_faculties(args):
    if args.synthetic_smoke:return ['khoa_cong_nghe_thong_tin','khoa_quan_tri_kinh_doanh','khoa_du_lich']
    mods=import_suite17();pipe=mods['suite17_pipeline'];avail=pipe.discover_faculties(args.cache_dir,args.folds[0]);return pipe.parse_faculties(args.faculties,avail)


def _print_fold_data(hist,target,names,fold):
    print('\n'+'='*180);print(f'SUITE19 — TARGET FOLD {fold} — LEARNED REPRESENTATION AUDIT');print('='*180);print(f'[DATA] faculties={len(hist.faculty_names)} common_raw_dim={len(names)} | historical OOF rows={len(hist.y):,} failures={int(hist.y.sum()):,} prevalence={hist.y.mean():.2%} | target rows={len(target.y):,} failures={int(target.y.sum()):,} prevalence={target.y.mean():.2%}');print(f'[COMMITTEE] target macro faculty AP={np.nanmean([safe_ap(target.y[target.faculty_idx==fi],target.teacher.mean(1)[target.faculty_idx==fi]) for fi in range(len(target.faculty_names))]):.4f} | pooled AP={safe_ap(target.y,target.teacher.mean(1)):.4f} AUC={safe_auc(target.y,target.teacher.mean(1)):.4f}');print('[SCIENTIFIC BOUNDARY] Representation audit only. No Suite17 R/M/L cascade. No target labels used for encoder/probe selection.')


def run_fold(
    args,
    faculties,
    fold,
    out,
):
    args._current_fold = fold

    folder = (
        out / f"fold_{fold}"
    )

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

    hist, target, names = (
        _load_fold(
            args,
            faculties,
            fold,
        )
    )

    # --------------------------------------------------------------
    # Prove exact expanding-fold identity before allowing reuse.
    # --------------------------------------------------------------
    args._incremental_context = None

    if getattr(
        args,
        "incremental_runtime",
        False,
    ):
        print(
            "\n[RUNTIME OPT CONTRACT] "
            "cross-fold representation/probe reuse=DISABLED | "
            "reason=fold-specific X and Committee differ materially | "
            "same-fold selection->production reuse=ENABLED | "
            "seed43/44 redundant historical probe scoring=DISABLED"
        )

    _print_fold_data(
        hist,
        target,
        names,
        fold,
    )
    # References are loaded before diagnostics only so target-only hard-case
    # analyses can use them. They never enter representation/probe fitting.
    ref_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};ref_by_fac={};ref_meta=[]
    for fi,fac in enumerate(target.faculty_names):
        m=target.faculty_idx==fi;s,meta=reference_scores_for_faculty(ref_dirs,fold,fac,target.y[m]);ref_by_fac[fac]=s;ref_meta+=meta
    pd.DataFrame(ref_meta).to_csv(folder/'reference_loading_audit.csv',index=False);print_table('[REFERENCE SCORE LOADING AUDIT]',pd.DataFrame(ref_meta),max_rows=100);ref_full=_reference_full_arrays(target,ref_by_fac)

    fold_metric_rows=[];score_columns={'committee':target.teacher.mean(1).astype(np.float32)};score_std_columns={};selected={};enc_summaries={};control_delta={};control_metrics=[];base_nca=None
    requested=list(args.encoders)
    for name in requested:
        try:
            cfg,_=_select_config(name,hist,target,names,args,folder,base_nca if name in {'modern_nca_hard','modern_nca_mechanism'} else None);selected[name]=cfg
            if name=='modern_nca':base_nca=cfg
            avg,std,primary,total_time,meta=_encoder_target_run(name,cfg,hist,target,names,args,folder);hd,td=_save_encoder_diagnostics(name,hist,target,avg,primary,names,args,folder,ref_full)
            scores={'committee':avg['committee'],**{k:v for k,v in avg.items() if k!='committee'}};rows=faculty_fold_rows(fold,target.faculty_names,target.faculty_idx,target.y,scores,args.threshold_beta)
            for r in rows:r['encoder']=name;r['selected_config']=json.dumps(cfg,sort_keys=True)
            fold_metric_rows+=rows;mdf=pd.DataFrame(rows);enc_summaries[name]={'metrics':mdf,'runtime':total_time,'hist_diag':hd,'target_diag':td,'metadata':meta}
            for k,v in avg.items():score_columns[f'{name}__{k}']=v
            for k,v in std.items():score_std_columns[f'{name}__{k}__seed_std']=v
            print_table(f'{DISPLAY.get(name,name)} — TARGET MACRO FACULTY PROBE MATRIX',_macro_target_table(mdf,name),max_rows=30)
            for cand,base in [('linear_z','committee'),('hgb_z','committee'),('hgb_xz','raw_hgb'),('committee_residual','committee'),('native_metric','committee'),('direct_native','committee')]:
                if cand in set(mdf.model) and base in set(mdf.model):
                    pt=paired_table(mdf,cand,base);pt.to_csv(folder/name/f'paired_{cand}_vs_{base}.csv',index=False);print_table(f'{DISPLAY.get(name,name)} — PAIRED FACULTY {cand} vs {base}',pt,max_rows=100)
        except Exception as e:
            print(f'[ENCODER FAILURE] {name}: {type(e).__name__}: {e}');(folder/f'{name}_FAILED.txt').write_text(traceback.format_exc())
            if args.fail_fast:raise

    # Matched PCA and random projection controls at every requested latent dim.
    print('\n'+'='*160);print('MATCHED DIMENSIONAL-COMPRESSION CONTROLS — PCA + RANDOM PROJECTION');print('='*160)
    for cname in CONTROL_ENCODERS:
        for cfg in _encoder_configs(cname,args):
            tag=f'{cname}_d{cfg["latent_dim"]}'
            try:
                # Controls are deterministic; one seed is enough.
                seed=args.seeds[0];led=_run_ledger(cname,cfg,seed,hist,target,names,args,folder,True);probe=_run_probes(cname,cfg,seed,hist,target,led,args,folder,True);scores={'committee':target.teacher.mean(1),**probe.target_scores};rows=faculty_fold_rows(fold,target.faculty_names,target.faculty_idx,target.y,scores,args.threshold_beta)
                for r in rows:r['encoder']=tag;r['selected_config']=json.dumps(cfg)
                fold_metric_rows+=rows;control_metrics+=rows;delta=paired_summary(pd.DataFrame(rows),'hgb_xz','raw_hgb').get('mean_delta_ap',np.nan);control_delta[(cname,cfg['latent_dim'])]=delta;print(f'  {tag:26s} HGB([X,z])-HGB(X) macro ΔAP={delta:+.4f} coverage={led.hist_available.mean():.1%} rank={representation_diagnostics(led.hist_z,hist.y,hist.faculty_idx,hist.teacher.mean(1),led.hist_available).get("effective_rank",np.nan):.2f}')
                for k,v in probe.target_scores.items():score_columns[f'{tag}__{k}']=v
            except Exception as e:
                print(f'  [CONTROL FAILURE] {tag}: {e}')
    metrics_df=pd.DataFrame(fold_metric_rows);metrics_df.to_csv(folder/'fold_metrics.csv',index=False)

    # Add external reference metrics, still aligned faculty-by-faculty.
    reference_metric_rows=[]
    for fi,fac in enumerate(target.faculty_names):
        m=target.faculty_idx==fi
        for key,s in ref_by_fac.get(fac,{}).items():reference_metric_rows.append({'fold':fold,'faculty':fac,'encoder':'reference','model':key,'rows':int(m.sum()),'failures':int(target.y[m].sum()),'prevalence':float(target.y[m].mean()),**metric_dict(target.y[m],s,args.threshold_beta)})
    pd.DataFrame(reference_metric_rows).to_csv(folder/'reference_metrics.csv',index=False)

    # Save one aligned target score table per faculty with all representations,
    # controls and available earlier-version references.
    for fi,fac in enumerate(target.faculty_names):
        m=target.faculty_idx==fi;df=pd.DataFrame({'actual':target.y[m],'student_id':target.student_id[m],'course_id':target.course_id[m],'target_semester':target.target_semester[m],'faculty':fac,'fold':fold})
        for k,v in score_columns.items():df[k]=np.asarray(v)[m]
        for k,v in score_std_columns.items():df[k]=np.asarray(v)[m]
        for k,v in ref_by_fac.get(fac,{}).items():df[f'reference__{k}']=v
        df.to_csv(folder/f'{fac}_scores.csv',index=False)

    # Per-fold result snapshot and concise target comparison.
    print_table('[TARGET FOLD METRICS — ALL PRIMARY ENCODERS]',metrics_df[metrics_df.encoder.isin(requested)].groupby(['encoder','model']).agg(ap=('ap','mean'),auc=('auc','mean'),f2_at20=('fbeta_at_20','mean'),faculties=('faculty','nunique')).reset_index().sort_values(['encoder','ap'],ascending=[True,False]),max_rows=100)
    if len(reference_metric_rows):print_table('[EARLIER VERSION REFERENCES — TARGET FOLD]',pd.DataFrame(reference_metric_rows).groupby('model').agg(ap=('ap','mean'),auc=('auc','mean'),f2_at20=('fbeta_at_20','mean'),faculties=('faculty','nunique')).reset_index().sort_values('ap',ascending=False),max_rows=50)
    _save_json({'fold':fold,'selected_configs':selected,'package_versions':package_versions(),'runtime':runtime_snapshot()},folder/'fold_manifest.json')
    return {'fold':fold,'hist':hist,'target':target,'names':names,'metrics':metrics_df,'reference_metrics':pd.DataFrame(reference_metric_rows),'score_columns':score_columns,'references':ref_by_fac,'reference_full':ref_full,'selected':selected,'enc_summaries':enc_summaries,'control_delta':control_delta}


def _pooled_model_rows(fold_results,models):
    rows=[];faculties=sorted(set(sum([list(r['target'].faculty_names) for r in fold_results],[])))
    for fac in faculties:
        for model in models:
            ys=[];ss=[]
            for r in fold_results:
                t=r['target'];
                if fac not in t.faculty_names:continue
                fi=t.faculty_names.index(fac);m=t.faculty_idx==fi
                if model=='committee':s=t.teacher.mean(1)[m]
                elif model in r['score_columns']:s=r['score_columns'][model][m]
                else:continue
                ys.append(t.y[m]);ss.append(s)
            if ys:
                y=np.concatenate(ys);s=np.concatenate(ss);rows.append({'faculty':fac,'model':model,'rows':len(y),'failures':int(y.sum()),**metric_dict(y,s)})
    return pd.DataFrame(rows)


def _records_for_operational(fold_results,holdout_only=False):
    records=[]
    for r in fold_results:
        t=r['target']
        for fi,fac in enumerate(t.faculty_names):
            m=t.faculty_idx==fi;scores={'committee':t.teacher.mean(1)[m]}
            for name in r['selected']:
                for local in ('committee_residual','hgb_xz','raw_hgb'):
                    key=f'{name}__{local}'
                    if key in r['score_columns']:scores[key]=r['score_columns'][key][m]
            for ref,s in r['references'].get(fac,{}).items():scores[f'reference__{ref}']=s
            records.append({'faculty':fac,'fold':r['fold'],'y':t.y[m],'scores':scores})
    return records


def _dedicated_faculty_reports(all_metrics,op,faculty,reference_metrics,out):
    if faculty not in set(all_metrics.faculty):return
    d=all_metrics[all_metrics.faculty==faculty].copy();key=d[d.fold.isin([6,7])];summary=key.groupby(['encoder','model']).agg(mean_fold_ap=('ap','mean'),mean_fold_auc=('auc','mean'),mean_fold_f2_at20=('fbeta_at_20','mean'),folds=('fold','nunique')).reset_index().sort_values('mean_fold_ap',ascending=False);summary.to_csv(out/f'dedicated_{faculty}_holdout.csv',index=False);print_table(f'DEDICATED FACULTY AUDIT — {faculty} — F6/F7 + MEAN-FOLD',summary,max_rows=100)
    print_table(f'DEDICATED FACULTY AUDIT — {faculty} — INDIVIDUAL F6/F7',key[['fold','encoder','model','rows','failures','ap','auc','fbeta_at_20']].sort_values(['fold','ap'],ascending=[True,False]),max_rows=150)
    if len(reference_metrics):
        rr=reference_metrics[(reference_metrics.faculty==faculty)&reference_metrics.fold.isin([6,7])];print_table(f'DEDICATED FACULTY REFERENCES — {faculty}',rr[['fold','model','rows','failures','ap','auc','fbeta_at_20']].sort_values(['fold','ap'],ascending=[True,False]),max_rows=100)
    if len(op):print_table(f'DEDICATED FACULTY OPERATIONAL METRICS — {faculty}',op[(op.faculty==faculty)&(op.fold.astype(str).isin(['6','7','POOLED']))],max_rows=150)


def postprocess(args,out,fold_results):
    all_metrics=pd.concat([r['metrics'] for r in fold_results],ignore_index=True) if fold_results else pd.DataFrame();all_refs=pd.concat([r['reference_metrics'] for r in fold_results],ignore_index=True) if fold_results and any(len(r['reference_metrics']) for r in fold_results) else pd.DataFrame();all_metrics.to_csv(out/'all_fold_metrics.csv',index=False);all_refs.to_csv(out/'all_reference_metrics.csv',index=False)
    records=_records_for_operational(fold_results);op=operational_metrics(records,args.dev_folds,args.holdout_folds,args.threshold_beta);op.to_csv(out/'operational_metrics.csv',index=False)
    verdict_rows=[];paired_all=[];control_summary=[]
    # Controls pooled across holdout faculty x fold cells.
    for c in CONTROL_ENCODERS:
        for d in args.latent_dims:
            tag=f'{c}_d{d}';z=all_metrics[(all_metrics.encoder==tag)&all_metrics.fold.isin(args.holdout_folds)];v=paired_summary(z,'hgb_xz','raw_hgb').get('mean_delta_ap',np.nan);control_summary.append({'control':c,'latent_dim':d,'hgb_xz_delta_ap':v})
    pd.DataFrame(control_summary).to_csv(out/'compression_control_summary.csv',index=False);print_table('PCA / RANDOM-PROJECTION MATCHED CONTROL SUMMARY',pd.DataFrame(control_summary),max_rows=50)
    for name in args.encoders:
        d=all_metrics[all_metrics.encoder==name].copy()
        if not len(d):continue
        hold=d[d.fold.isin(args.holdout_folds)];dim_values=[];runtime=0.;rank=[]
        for r in fold_results:
            if name in r['selected']:dim_values.append(r['selected'][name].get('latent_dim',np.nan))
            if name in r['enc_summaries']:runtime+=r['enc_summaries'][name]['runtime'];rank.append(r['enc_summaries'][name]['target_diag'].get('effective_rank',np.nan))
        dim=int(np.nanmedian(dim_values)) if dim_values else np.nan;pca=next((x['hgb_xz_delta_ap'] for x in control_summary if x['control']=='pca' and x['latent_dim']==dim),np.nan);rp=next((x['hgb_xz_delta_ap'] for x in control_summary if x['control']=='random_projection' and x['latent_dim']==dim),np.nan)
        def macro_model(m):
            z=hold[hold.model==m];return float(z.ap.mean()) if len(z) else np.nan
        vr=summarize_encoder_verdict(name,d,args.holdout_folds,'raw_hgb','committee_residual',pca,rp,args.primary_faculty,tuple(args.business_faculty_keywords),native_ap=macro_model('direct_native'),native_metric_ap=macro_model('native_metric'),linear_ap=macro_model('linear_z'),hgb_z_ap=macro_model('hgb_z'),hgb_xz_ap=macro_model('hgb_xz'),raw_hgb_ap=macro_model('raw_hgb'),runtime=runtime,latent_dim=dim,effective_rank_value=float(np.nanmean(rank)) if rank else np.nan);verdict_rows.append(vr)
        for cand,base in [('linear_z','raw_hgb'),('hgb_z','raw_hgb'),('hgb_xz','raw_hgb'),('committee_residual','committee'),('native_metric','committee'),('direct_native','committee')]:
            if cand in set(d.model) and base in set(d.model):
                pt=paired_table(d,cand,base);pt['encoder']=name;pt['candidate']=cand;pt['base']=base;paired_all.append(pt);pt.to_csv(out/f'paired_{name}_{cand}_vs_{base}.csv',index=False)
                hs=pt[pt.fold.isin(args.holdout_folds)];mean,lo,hi=bootstrap_ci(hs.delta_ap,args.bootstrap_seed,args.bootstrap_samples) if len(hs) else (np.nan,np.nan,np.nan);print(f'[BOOTSTRAP] {name:22s} {cand:20s} vs {base:12s} holdout faculty×fold ΔAP mean={mean:+.4f} 95%CI=[{lo:+.4f},{hi:+.4f}] n={len(hs)}')
    verdict=pd.DataFrame(verdict_rows);verdict.to_csv(out/'suite19_representation_verdict.csv',index=False);print_verdict_table(verdict)
    if paired_all:pd.concat(paired_all,ignore_index=True).to_csv(out/'all_paired_faculty_fold_deltas.csv',index=False)
    # Seed variability across stochastic encoders.
    seed_files=[]
    for f in args.folds:
        for name in args.encoders:
            p=out/f'fold_{f}'/name/'seed_target_metrics.csv'
            if p.exists():z=pd.read_csv(p);z['fold_source']=f;seed_files.append(z)
    if seed_files:
        sd=pd.concat(seed_files,ignore_index=True);g=sd[sd.fold.isin(args.holdout_folds)].groupby(['encoder','model','faculty']).ap.agg(['mean','std','count']).reset_index();g.to_csv(out/'holdout_seed_variability.csv',index=False);print_table('STOCHASTIC SEED VARIABILITY — HOLDOUT AP',g,max_rows=100)
    # Operational comparisons.
    print_table('SUITE19 OPERATIONAL HOLDOUT SUMMARY — POOLED FIXED/DRIFT',op[op.fold.astype(str)=='POOLED'].sort_values(['faculty','policy','model']),max_rows=250)
    # Reference overlap and win-rate audit.
    if len(all_refs):
        print_table('EARLIER VERSION REFERENCE SUMMARY — HOLDOUT',all_refs[all_refs.fold.isin(args.holdout_folds)].groupby('model').agg(faculties=('faculty','nunique'),cells=('faculty','size'),mean_fold_ap=('ap','mean'),mean_fold_auc=('auc','mean'),mean_fold_f2_at20=('fbeta_at_20','mean')).reset_index().sort_values('mean_fold_ap',ascending=False),max_rows=50)
        # Explicitly disclose Council overlap.
        c=all_refs[(all_refs.model=='council')&all_refs.fold.isin(args.holdout_folds)];print(f'[COUNCIL OVERLAP] faculties={c.faculty.nunique()} names={sorted(c.faculty.unique().tolist()) if len(c) else []}')
    # Dedicated unresolved faculties.
    _dedicated_faculty_reports(all_metrics,op,args.primary_faculty,all_refs,out)
    for fac in sorted(set(all_metrics.faculty)):
        low=fac.lower()
        if fac!=args.primary_faculty and any(k in low for k in args.business_faculty_keywords):_dedicated_faculty_reports(all_metrics,op,fac,all_refs,out)
    # Across-fold representation stability summary.
    stab=[];rfm_dirs={}
    for r in fold_results:
        for name,s in r['enc_summaries'].items():
            d=s['target_diag'];stab.append({'fold':r['fold'],'encoder':name,**{k:d.get(k,np.nan) for k in ['latent_dim','effective_rank','dead_dimension_fraction','class_centroid_distance','between_over_within','neighborhood_label_purity','faculty_centroid_separability_accuracy']}})
            if name=='rfm':
                p=out/f'fold_{r["fold"]}'/'rfm'/f'seed_{args.seeds[0]}'/'model_metadata.json'
                if p.exists():
                    obj=json.loads(p.read_text());vec=(obj.get('production') or {}).get('metric_eigenvectors_top');
                    if vec is not None:rfm_dirs[f'F{r["fold"]}']=np.asarray(vec,float)
    sdf=pd.DataFrame(stab);sdf.to_csv(out/'representation_stability_by_fold.csv',index=False)
    if len(sdf):print_table('REPRESENTATION STABILITY ACROSS FOLDS',sdf.groupby('encoder').agg(['mean','std']).reset_index(),max_rows=30)
    if len(rfm_dirs)>1:
        dr=pd.DataFrame(direction_stability_rows(rfm_dirs));dr.to_csv(out/'rfm_direction_stability.csv',index=False);print_table('RFM/AGOP LEARNED-DIRECTION STABILITY ACROSS FOLDS',dr,max_rows=50)
    decision=next_architecture_decision(verdict);(out/'NEXT_ARCHITECTURE_DECISION.txt').write_text(decision+'\n');print('\n'+'='*160);print('NEXT ARCHITECTURE DECISION');print('='*160);print(decision)
    _save_json({'package_versions':package_versions(),'args':vars(args),'runtime':runtime_snapshot()},out/'suite19_run_manifest.json')
    return verdict


def build_parser():
    root='/root/disk_3tb/earlywarning/30072026';p=argparse.ArgumentParser(description='Suite19 chronology-safe learned representation audit')
    p.add_argument('--cache_dir',default=f'{root}/results/cross_faculty_residual_moe/cache');p.add_argument('--structured_cache_dir',default=f'{root}/results/suite12_structured_cache');p.add_argument('--out_dir',default=f'{root}/results/suite19_representation_audit');p.add_argument('--faculties',default='all');p.add_argument('--folds',default='1,2,3,4,5,6,7');p.add_argument('--dev_folds',default='1,2,3,4,5');p.add_argument('--holdout_folds',default='6,7');p.add_argument('--encoders',default='tabm,modern_nca,modern_nca_hard,modern_nca_mechanism,rfm');p.add_argument('--latent_dims',default='32,64');p.add_argument('--seeds',default='42,43,44');p.add_argument('--device',default='auto')
    p.add_argument('--tabm_backend',choices=['official','internal'],default='official');p.add_argument('--tabm_arch_type',default='tabm');p.add_argument('--tabm_depths',default='2,3');p.add_argument('--tabm_ensemble_size',type=int,default=32);p.add_argument('--tabm_dropout',type=float,default=0.0);p.add_argument('--tabm_epochs',type=int,default=40);p.add_argument('--tabm_batch_size',type=int,default=512);p.add_argument('--tabm_lr',type=float,default=2e-3)
    p.add_argument('--nca_backend',choices=['internal'],default='internal');p.add_argument('--nca_hidden_dim',type=int,default=128);p.add_argument('--nca_epochs',type=int,default=40);p.add_argument('--nca_batch_size',type=int,default=512);p.add_argument('--nca_lr',type=float,default=2e-3);p.add_argument('--nca_temperatures',default='.05,.10,.20');p.add_argument('--nca_aux_bce_grid',default='0,.25');p.add_argument('--nca_hard_strength',type=float,default=2.0);p.add_argument('--nca_mechanism_tau',type=float,default=1.0);p.add_argument('--nca_retrieval_k',type=int,default=32)
    p.add_argument(
        "--nca_retrieval_query_chunk",
        type=int,
        default=256,
    )

    p.add_argument(
        "--nca_retrieval_memory_chunk",
        type=int,
        default=8192,
    )
    p.add_argument('--rfm_backend',choices=['official','internal'],default='official');p.add_argument('--rfm_recursions',default='1,2,3');p.add_argument('--rfm_bandwidths',default='1.0');p.add_argument('--rfm_centers',type=int,default=512);p.add_argument('--rfm_agop_rows',type=int,default=2048);p.add_argument('--rfm_ridge',type=float,default=1e-3);p.add_argument('--rfm_metric_floor',type=float,default=1e-6);p.add_argument('--rfm_max_train_rows',type=int,default=20000);p.add_argument('--rfm_mem_gb',type=float,default=8.)
    p.add_argument('--neural_weight_decay',type=float,default=3e-4);p.add_argument('--class_beta',type=float,default=.9999);p.add_argument('--max_encoder_train_rows',type=int,default=180000);p.add_argument('--clip_z',type=float,default=12.0)
    p.add_argument('--representation_min_prior_blocks',type=int,default=4);p.add_argument('--representation_min_train_rows',type=int,default=5000);p.add_argument('--representation_min_failures',type=int,default=50);p.add_argument('--min_oof_representation_coverage',type=float,default=.35);p.add_argument('--max_encoder_seconds',type=float,default=0.)
    p.add_argument('--probe_min_prior_blocks',type=int,default=4);p.add_argument('--probe_min_train_rows',type=int,default=5000);p.add_argument('--probe_min_failures',type=int,default=50);p.add_argument('--probe_hgb_iter',type=int,default=250);p.add_argument('--probe_max_train_rows',type=int,default=180000)
    p.add_argument('--residual_eta_grid',default='0,.05,.10,.20,.30');p.add_argument('--residual_iter_candidates',default='20,40,60,80');p.add_argument('--residual_min_prior_blocks',type=int,default=4);p.add_argument('--residual_min_faculties',type=int,default=8);p.add_argument('--residual_min_failures',type=int,default=120);p.add_argument('--residual_min_rows',type=int,default=5000)
    p.add_argument('--threshold_beta',type=float,default=2.0);p.add_argument('--diagnostic_max_pairs',type=int,default=20000);p.add_argument('--bootstrap_samples',type=int,default=4000);p.add_argument('--bootstrap_seed',type=int,default=20260904);p.add_argument('--primary_faculty',default='khoa_cong_nghe_thong_tin');p.add_argument('--business_faculty_keywords',default='kinh_doanh,du_lich,business,tourism')
    p.add_argument('--suite17_results_dir',default=f'{root}/results/suite17_robust_forward_specialist_boosting');p.add_argument('--suite18_results_dir',default=f'{root}/results/suite18_hgb');p.add_argument('--suite16_results_dir',default=f'{root}/results/suite16_conditional_tree_boosting');p.add_argument('--suite14_results_dir',default=f'{root}/results/suite14_authority_safe');p.add_argument('--v2_results_dir',default=f'{root}/results/final_train_v2_f2');p.add_argument('--council_results_dir',default=f'{root}/results/suite4')
    p.add_argument(
        "--incremental_runtime",
        action="store_true",
        help=(
            "Enable scientifically exact Suite19 runtime optimizations: "
            "same-fold selection-to-production representation/probe reuse, "
            "selection-phase native-score skipping, and redundant historical "
            "probe elimination for production seeds 43/44. "
            "Cross-fold representation/probe reuse is intentionally disabled."
        ),
    )

    p.add_argument(
        "--defer_postprocess",
        action="store_true",
        help=(
            "Persist requested fold results "
            "without issuing the global "
            "F6/F7 verdict yet."
        ),
    )
    p.add_argument('--force_encoder',action='store_true');p.add_argument('--force_probe',action='store_true');p.add_argument('--save_embeddings',action='store_true');p.add_argument('--fail_fast',action='store_true');p.add_argument('--verbose_errors',action='store_true')
    p.add_argument('--synthetic_smoke',action='store_true',help='Run a tiny chronology-safe synthetic end-to-end audit; forces diagnostic internal TabM/RFM backends.');p.add_argument('--synthetic_rows_per_block',type=int,default=35);p.add_argument('--synthetic_target_rows',type=int,default=120)
    return p


def _normalize_args(a):
    a.folds=parse_csv_ints(a.folds);a.dev_folds=parse_csv_ints(a.dev_folds);a.holdout_folds=parse_csv_ints(a.holdout_folds);a.encoders=parse_csv_strings(a.encoders);a.latent_dims=parse_csv_ints(a.latent_dims);a.seeds=parse_csv_ints(a.seeds);a.tabm_depths=parse_csv_ints(a.tabm_depths);a.nca_temperatures=parse_csv_floats(a.nca_temperatures);a.nca_aux_bce_grid=parse_csv_floats(a.nca_aux_bce_grid);a.rfm_recursions=parse_csv_ints(a.rfm_recursions);a.rfm_bandwidths=parse_csv_floats(a.rfm_bandwidths);a.residual_eta_grid=parse_csv_floats(a.residual_eta_grid);a.residual_iter_candidates=parse_csv_ints(a.residual_iter_candidates);a.business_faculty_keywords=parse_csv_strings(a.business_faculty_keywords)
    unknown=[x for x in a.encoders if x not in PRIMARY_ENCODERS]
    if unknown:raise ValueError(f'unknown primary encoders: {unknown}')
    if a.synthetic_smoke:
        # Small but complete smoke: no external references, low chronology gates.
        a.latent_dims=[min(a.latent_dims[0],8)];a.seeds=[a.seeds[0]];a.tabm_depths=[1];a.tabm_epochs=min(a.tabm_epochs,2);a.tabm_batch_size=min(a.tabm_batch_size,64);a.nca_epochs=min(a.nca_epochs,2);a.nca_batch_size=min(a.nca_batch_size,64);a.nca_temperatures=[a.nca_temperatures[0]];a.nca_aux_bce_grid=[0.0];a.rfm_recursions=[1];a.rfm_bandwidths=[1.0];a.rfm_centers=min(a.rfm_centers,48);a.rfm_agop_rows=min(a.rfm_agop_rows,80);a.rfm_max_train_rows=1000;a.representation_min_prior_blocks=2;a.representation_min_train_rows=45;a.representation_min_failures=3;a.probe_min_prior_blocks=2;a.probe_min_train_rows=45;a.probe_min_failures=3;a.residual_min_prior_blocks=2;a.residual_min_faculties=1;a.residual_min_failures=3;a.residual_min_rows=45;a.probe_hgb_iter=min(a.probe_hgb_iter,25);a.probe_max_train_rows=2000;a.min_oof_representation_coverage=.20;a.bootstrap_samples=min(a.bootstrap_samples,200)
        for k in ['suite17_results_dir','suite18_results_dir','suite16_results_dir','suite14_results_dir','v2_results_dir','council_results_dir']:setattr(a,k,'')
    return a


def main(argv=None):
    args=_normalize_args(build_parser().parse_args(argv));seed_everything(args.seeds[0]);out=Path(args.out_dir);out.mkdir(parents=True,exist_ok=True);print('='*180);print('SUITE19 — LEARNED REPRESENTATION AUDIT');print('Representation quality != native predictor quality != raw-X complementarity != Committee complementarity');print('='*180);print(f'Folds={args.folds} | dev={args.dev_folds} | holdout={args.holdout_folds} | encoders={args.encoders} | latent_dims={args.latent_dims} | seeds={args.seeds}');print(f'Backends: TabM={"internal DIAGNOSTIC" if args.synthetic_smoke else args.tabm_backend} | ModernNCA={args.nca_backend} | RFM={"internal DIAGNOSTIC" if args.synthetic_smoke else args.rfm_backend}');print('[VERSIONS]',package_versions());print('[NON-NEGOTIABLE] no target-fold tuning; no same-row supervised embedding; no future retrieval; official-backend failures are never silently substituted.')
    faculties=_discover_faculties(args);print(f'[FACULTIES] {len(faculties)}: {faculties}');results=[]
    for fold in args.folds:
        try:results.append(run_fold(args,faculties,fold,out))
        except Exception as e:
            print(f'\n[FOLD FAILURE] F{fold}: {type(e).__name__}: {e}');(out/f'fold_{fold}_FAILED.txt').write_text(traceback.format_exc())
            if args.fail_fast:raise
            
    if not results:
        raise RuntimeError(
            "No Suite19 folds "
            "completed successfully"
        )

    if getattr(
        args,
        "defer_postprocess",
        False,
    ):
        completed = [
            int(r["fold"])
            for r in results
        ]

        partial = {
            "completed_folds":
                completed,

            "configured_dev_folds":
                list(args.dev_folds),

            "configured_holdout_folds":
                list(args.holdout_folds),

            "global_postprocess":
                "DEFERRED",

            "representation_verdict":
                "PENDING_HOLDOUT",

            "project_sota_verdict":
                "PENDING_HOLDOUT",

            "scientific_note": (
                "Requested fold outputs "
                "are complete. Final Suite19 "
                "verdict is deferred until "
                "the configured holdout folds "
                "are available."
            ),
        }

        _save_json(
            partial,
            out
            / (
                "partial_run_"
                + "_".join(
                    f"F{x}"
                    for x
                    in completed
                )
                + ".json"
            ),
        )

        print(
            "\n[PARTIAL RUN COMPLETE] "
            f"folds={completed} | "
            "global verdict deferred."
        )

        return pd.DataFrame()

    verdict = postprocess(
        args,
        out,
        results,
    )

    print(
        f"\nSuite19 complete. "
        f"Results: {out}"
    )

    return verdict


if __name__=='__main__':main()
