"""Train Suite26 MINT with chronological selection, full-history refit and audits."""
from __future__ import annotations

import argparse
from collections import Counter
import json
import os
from pathlib import Path
import platform
import resource
import shutil
import time

import numpy as np
import pandas as pd
import sklearn
import torch
from torch.nn import functional as F
from torch.utils.data import DataLoader, WeightedRandomSampler

from mint_data import (Preprocessor, MemoryDataset, build_history, shuffle_history,
                       load_fold, discover_faculties, common_feature_names, chronological_split)
from mint_seed import fit_seed_forest, seed_predict
from mint_model import MemoryIntegratedForest
from mint_metrics import metrics, macro_ap, add_references, write_report
from mint_runtime import (seed_all, atomic_json, atomic_checkpoint, sha256,
                          to_device, infer, score_frame)

VARIANTS = ['tree_only', 'memory', 'mint']
REFERENCE_DIRECTORIES = {
    'suite14': 'suite14_authority_safe_collaborative_moe',
    'suite16': 'suite16_conditional_tree_boosting',
    'suite17': 'suite17_robust_forward_specialist_boosting',
    'suite18': 'suite18_fmm_forward_specialist_boosting',
    'suite20': 'suite20_semester_target_transformer',
    'suite21': 'suite21_guarded_temporal_residual',
    'suite22': 'suite22_sftr_tabm', 'suite22_primary': 'suite22_sftr_tabm',
    'suite22_relational': 'suite22_sftr_tabm',
    'suite23': 'suite23_cs_hagt', 'suite23_graph': 'suite23_cs_hagt',
    'suite24': 'suite24_target_conditioned_structural_residual',
    'suite24_posthoc': 'suite24_target_conditioned_structural_residual',
    'suite25': 'suite25_structure_aware_chronological_retrieval',
    'suite25_blend': 'suite25_structure_aware_chronological_retrieval',
    'suite26_original': 'suite26_tree_native_student_memory',
    'suite26_original_memory': 'suite26_tree_native_student_memory',
    'suite26_original_tree': 'suite26_tree_native_student_memory',
    'suite26_original_joint_head': 'suite26_tree_native_student_memory',
    'council': 'suite4/2_competence_council', 'v2': 'final_train_v2',
}


def _list(values, cast=str):
    return [cast(item.strip()) for value in values for item in str(value).split(',') if item.strip()]


def parser():
    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.ArgumentDefaultsHelpFormatter)
    p.add_argument('--root', default='/root/disk_3tb/earlywarning/30072026')
    p.add_argument('--cache-dir', '--cache_dir')
    p.add_argument('--structured-dir', '--structured_cache_dir')
    p.add_argument('--out-dir', '--out_dir')
    p.add_argument('--faculties', nargs='+', default=['all'])
    p.add_argument('--folds', nargs='+', default=['1', '2', '3', '4', '5', '6', '7'])
    p.add_argument('--dev-folds', nargs='+', default=['1', '2', '3', '4', '5'])
    p.add_argument('--holdout-folds', nargs='+', default=['6', '7'])
    p.add_argument('--variants', nargs='+', choices=VARIANTS, default=VARIANTS)
    p.add_argument('--reference-dirs', nargs='*', default=None, help='name=directory or known suite directories. Default: existing prior results under root/results.')
    p.add_argument('--device', default='auto', help='auto, cpu, cuda, or cuda:0')
    p.add_argument('--seed', type=int, default=20260930)
    p.add_argument('--trees', type=int, default=64)
    p.add_argument('--depth', type=int, default=6)
    p.add_argument('--min-leaf', type=int, default=8)
    p.add_argument('--tree-jobs', type=int, default=-1)
    p.add_argument('--hidden', type=int, default=32)
    p.add_argument('--ability-dim', type=int, default=16)
    p.add_argument('--dropout', type=float, default=.1)
    p.add_argument('--max-history', type=int, default=32)
    p.add_argument('--history-k', nargs='+', type=int, default=[4, 8, 16, 32])
    p.add_argument('--val-semesters', type=int, default=1, help='One semester avoids earlier-validation labels in row-time features. Larger windows have fixed memory but row-time feature provenance.')
    p.add_argument('--epochs', type=int, default=15)
    p.add_argument('--min-epochs', type=int, default=3)
    p.add_argument('--patience', type=int, default=4)
    p.add_argument('--batch-size', type=int, default=128)
    p.add_argument('--eval-batch-size', type=int, default=128)
    p.add_argument('--max-samples', type=int, default=180000)
    p.add_argument('--lr', type=float, default=.001)
    p.add_argument('--weight-decay', type=float, default=.0001)
    p.add_argument('--rank-weight', type=float, default=.05)
    p.add_argument('--shift-reg', type=float, default=.0001)
    p.add_argument('--grad-clip', type=float, default=5.)
    p.add_argument('--threads', type=int, default=min(os.cpu_count() or 1, 8))
    p.add_argument('--bootstrap', type=int, default=200)
    p.add_argument('--skip-diagnostics', action='store_true', help='Skip intervention and history-k inference; keep main metrics and gradient logs.')
    p.add_argument('--preflight-only', action='store_true', help='Validate every requested cache/split without creating result files.')
    p.add_argument('--resume', action='store_true', help='Reuse only complete folds with matching code/configuration/input fingerprints.')
    return p


def resolve_args(argv=None):
    p = parser()
    args = p.parse_args(argv)
    args.root = str(Path(args.root).expanduser().resolve())
    args.cache_dir = str(Path(args.cache_dir or Path(args.root) / 'results/cross_faculty_residual_moe/cache').expanduser().resolve())
    args.structured_dir = str(Path(args.structured_dir or Path(args.root) / 'results/suite12_structured_cache').expanduser().resolve())
    args.out_dir = str(Path(args.out_dir or Path(args.root) / 'results/suite26_joint_tree_memory').expanduser().resolve())
    args.folds, args.dev_folds, args.holdout_folds = (_list(getattr(args, key), int) for key in ['folds', 'dev_folds', 'holdout_folds'])
    if any(f < 1 for f in args.folds) or len(set(args.folds)) != len(args.folds):
        p.error('folds must be unique positive integers')
    if set(args.dev_folds) & set(args.holdout_folds):
        p.error('Development and holdout folds must be disjoint.')
    args.faculties = _list(args.faculties)
    if args.faculties == ['all']:
        args.faculties = discover_faculties(args.cache_dir, args.folds[0])
    if not args.faculties or len(set(args.faculties)) != len(args.faculties):
        p.error('Faculty names must be nonempty and unique.')
    if not 1 <= args.depth <= 10 or not 0 <= args.dropout < 1:
        p.error('Require depth in 1..10 and dropout in [0,1).')
    for name in ['trees', 'min_leaf', 'hidden', 'ability_dim', 'max_history', 'val_semesters', 'epochs',
                 'min_epochs', 'patience', 'batch_size', 'eval_batch_size', 'max_samples', 'threads']:
        if getattr(args, name) < 1:
            p.error(f'{name} must be positive')
    if args.min_epochs > args.epochs:
        p.error('min-epochs cannot exceed epochs')
    if args.lr <= 0 or args.grad_clip <= 0 or min(args.rank_weight, args.shift_reg, args.weight_decay, args.bootstrap) < 0:
        p.error('Invalid optimization/bootstrap settings.')
    if args.device == 'auto':
        args.device = 'cuda' if torch.cuda.is_available() else 'cpu'
    if args.device.startswith('cuda') and not torch.cuda.is_available():
        p.error('CUDA requested but unavailable in this Python environment; check PyTorch or use --device cpu.')
    if args.reference_dirs is None:
        args.reference_dirs = {name: str(Path(args.root) / 'results' / directory)
                               for name, directory in REFERENCE_DIRECTORIES.items()
                               if (Path(args.root) / 'results' / directory).is_dir()}
    else:
        provided = {}
        for item in args.reference_dirs:
            if '=' in item:
                name, directory = item.split('=', 1)
                provided[name] = str(Path(directory).expanduser().resolve())
            else:
                directory = Path(item).expanduser().resolve()
                names = [name for name, known in REFERENCE_DIRECTORIES.items() if Path(known).name == directory.name]
                for name in names or [directory.name]:
                    provided[name] = str(directory)
        args.reference_dirs = provided
    args.variants = list(dict.fromkeys(args.variants))
    args.history_k = sorted(set(k for k in args.history_k if 0 < k <= args.max_history))
    return args


def _manifest(args):
    config = {k: v for k, v in vars(args).items() if k not in {'resume', 'preflight_only', 'out_dir'}}
    fingerprints = {}
    for fold in args.folds:
        for faculty in args.faculties:
            for parent in [args.cache_dir, args.structured_dir]:
                path = Path(parent) / f'{faculty}_fold_{fold}.joblib'
                if not path.is_file():
                    raise FileNotFoundError(f'Missing required cache: {path}')
                fingerprints[str(path)] = dict(bytes=path.stat().st_size, sha256=sha256(path))
    here = Path(__file__).resolve().parent
    code = {path.name: sha256(path) for path in sorted(here.glob('*.py'))}
    versions = dict(python=platform.python_version(), torch=torch.__version__, numpy=np.__version__,
                    pandas=pd.__version__, sklearn=sklearn.__version__)
    return dict(format_version=1, configuration=config, inputs=fingerprints, code=code, versions=versions)


def common_features_for_run(args):
    """Keep one numeric schema across every requested faculty and fold."""
    ordered = common_feature_names(args.cache_dir, args.faculties, args.folds[0])
    shared = set(ordered)
    for fold in args.folds[1:]:
        shared.intersection_update(common_feature_names(args.cache_dir, args.faculties, fold))
    names = [name for name in ordered if name in shared]
    if not names:
        raise ValueError('No common numeric features across the requested faculties and folds.')
    return names


def _rank_loss(prob, y, faculty):
    pairs, losses = 0, []
    logit = torch.logit(prob.clamp(1e-6, 1 - 1e-6))
    for f in faculty.unique():
        positives = torch.where((faculty == f) & (y == 1))[0]
        negatives = torch.where((faculty == f) & (y == 0))[0]
        if len(positives) and len(negatives):
            count = min(256, max(len(positives), len(negatives)))
            pi = positives[torch.randint(len(positives), (count,), device=prob.device)]
            ni = negatives[torch.randint(len(negatives), (count,), device=prob.device)]
            losses.append(F.softplus(-(logit[pi] - logit[ni])).mean())
            pairs += count
    return torch.stack(losses).mean() if losses else prob.sum() * 0, pairs


def optimize(model, dataset, args, epochs, seed, phase, variant, fold, validation=None, examples_per_epoch=None):
    device = torch.device(args.device)
    model.to(device)
    optimizer = torch.optim.AdamW(model.parameters(), lr=args.lr, weight_decay=args.weight_decay)
    faculty = dataset.query.table.faculty[dataset.indices]
    counts = Counter(faculty.tolist())
    weights = torch.tensor([1 / counts[int(f)] for f in faculty], dtype=torch.double)
    n_samples = min(len(dataset), args.max_samples) if examples_per_epoch is None else int(examples_per_epoch)
    records, best_epoch, best_ap, stale = [], 1, -np.inf, 0
    for epoch in range(1, epochs + 1):
        started = time.perf_counter()
        generator = torch.Generator().manual_seed(seed + epoch)
        sampler = WeightedRandomSampler(weights, n_samples, replacement=True, generator=generator)
        loader = DataLoader(dataset, batch_size=args.batch_size, sampler=sampler, num_workers=0,
                            pin_memory=args.device.startswith('cuda'))
        model.train()
        sums, seen, pair_count, grad_norms, sampled = np.zeros(3), 0, 0, {}, Counter()
        if args.device.startswith('cuda'):
            torch.cuda.reset_peak_memory_stats(device)
        for batch_number, host in enumerate(loader):
            sampled.update(host['faculty'].tolist())
            batch = to_device(host, device)
            optimizer.zero_grad(set_to_none=True)
            output = model(batch)
            bce = F.binary_cross_entropy(output['prob'], batch['y'])
            rank, pairs = _rank_loss(output['prob'], batch['y'], batch['faculty']) if args.rank_weight else (bce * 0, 0)
            loss = bce + args.rank_weight * rank + args.shift_reg * output['threshold_penalty'].mean()
            if not torch.isfinite(loss):
                raise FloatingPointError(f'Non-finite loss at fold {fold} {phase}/{variant} epoch {epoch}.')
            if batch_number == 0:
                tracked = ['selector_logits', 'thresholds', 'temperature_unconstrained', 'leaf_logits',
                           'memory_key.weight', 'memory_value.weight', 'node_memory_weight', 'node_gap_weight']
                parameters = dict(model.named_parameters())
                # Diagnostics come from the main BCE alone, before regularizers.
                gradients = torch.autograd.grad(bce, [parameters[k] for k in tracked], retain_graph=True, allow_unused=True)
                grad_norms = {f'gradient_{k}': float(g.detach().norm()) if g is not None else 0.
                              for k, g in zip(tracked, gradients)}
            loss.backward()
            torch.nn.utils.clip_grad_norm_(model.parameters(), args.grad_clip, error_if_nonfinite=True)
            optimizer.step()
            size = len(batch['y'])
            sums += np.asarray([float(loss.detach()), float(bce.detach()), float(rank.detach())]) * size
            seen += size
            pair_count += pairs
        row = dict(fold=fold, phase=phase, variant=variant, epoch=epoch, examples=seen,
                   loss=sums[0] / seen, bce=sums[1] / seen, ranking_loss=sums[2] / seen,
                   ranking_pairs=pair_count, sampled_by_faculty=json.dumps(dict(sampled), sort_keys=True),
                   seconds=time.perf_counter() - started,
                   peak_host_rss_mb=resource.getrusage(resource.RUSAGE_SELF).ru_maxrss / 1024,
                   peak_cuda_mb=torch.cuda.max_memory_allocated(device) / 2 ** 20 if args.device.startswith('cuda') else 0.,
                   **grad_norms)
        if validation is not None:
            score, _ = infer(model, validation, device, args.eval_batch_size)
            val_table = validation.query.table.subset(validation.indices)
            frame = pd.DataFrame(dict(actual=val_table.y, faculty=val_table.faculty, score=score))
            row['validation_macro_ap'] = macro_ap(frame, 'score')
            row['validation_f2_budget20'] = float(np.nanmean([metrics(g.actual, g.score)['f2_at_20'] for _, g in frame.groupby('faculty')]))
            if not np.isfinite(row['validation_macro_ap']):
                raise ValueError('No validation faculty has both classes. Increase validation history or inspect labels.')
            if row['validation_macro_ap'] > best_ap + 1e-8:
                best_ap, best_epoch, stale = row['validation_macro_ap'], epoch, 0
            else:
                stale += 1
            suffix = f" val_macro_AP={row['validation_macro_ap']:.5f} F2@20={row['validation_f2_budget20']:.5f} best_epoch={best_epoch}"
        else:
            suffix = ''
        records.append(row)
        print(f"[F{fold} {phase} {variant} {epoch}/{epochs}] BCE={row['bce']:.5f} examples={seen} "
              f"split_grad={row['gradient_thresholds']:.3g} memory_grad={row['gradient_memory_value.weight']:.3g}"
              f"{suffix} time={row['seconds']:.1f}s", flush=True)
        if validation is not None and epoch >= args.min_epochs and stale >= args.patience:
            break
    return best_epoch if validation is not None else epochs, records


def _model(blueprint, prepared, preprocessor, variant, args, seed):
    seed_all(seed)
    return MemoryIntegratedForest(blueprint, prepared.course_meta.shape[1], preprocessor.n_courses,
                                  variant=variant, hidden=args.hidden, ability_dim=args.ability_dim, dropout=args.dropout)


def _seed(prepared, indices, args, seed):
    return fit_seed_forest(prepared.x[indices], prepared.table.y[indices], args.trees, args.depth,
                           args.min_leaf, seed, args.tree_jobs)


def _metric_rows(frame, score_cols, group_name='faculty'):
    records = []
    for group, part in frame.groupby(group_name, dropna=False):
        for column in score_cols:
            records.append({group_name: group, 'model': column, **metrics(part.actual, part[column])})
    return records


def diagnose(model, prepared_target, prepared_bank, history, dataset, frame, args, fold_dir, fold_seed):
    columns = []
    ablation = frame[['fold', 'faculty', 'sample_id', 'student_id', 'course_id', 'semester', 'actual']].copy()
    ablation['primary'] = frame['suite26_mint']
    columns.append('primary')
    for intervention in ['no_memory', 'no_outcomes', 'no_ability', 'uniform_attention', 'hard_routing', 'no_context']:
        score, _ = infer(model, dataset, args.device, args.eval_batch_size, intervention=intervention)
        ablation[intervention] = score
        columns.append(intervention)
    shuffled, audit = shuffle_history(prepared_bank.table, prepared_target.table, history, fold_seed + 200)
    shuffled_set = MemoryDataset(prepared_target, prepared_bank, shuffled)
    ablation['shuffled_students'], _ = infer(model, shuffled_set, args.device, args.eval_batch_size)
    columns.append('shuffled_students')
    atomic_json(audit, fold_dir / 'history_shuffle_audit.json')
    for k in args.history_k:
        if k == args.max_history:
            ablation[f'history_k_{k}'] = ablation.primary
        else:
            short = build_history(prepared_bank.table, prepared_target.table, max_history=k)
            short_set = MemoryDataset(prepared_target, prepared_bank, short)
            ablation[f'history_k_{k}'], _ = infer(model, short_set, args.device, args.eval_batch_size)
        columns.append(f'history_k_{k}')
    ablation.to_csv(fold_dir / 'intervention_predictions.csv', index=False)
    pd.DataFrame(_metric_rows(ablation, columns)).to_csv(fold_dir / 'intervention_metrics.csv', index=False)
    atomic_json({c: macro_ap(ablation, c) for c in columns}, fold_dir / 'intervention_macro_ap.json')


def run_fold(args, fold, common, manifest):
    started = time.perf_counter()
    folder = Path(args.out_dir) / f'fold_{fold}'
    if folder.exists():
        # This is our incomplete fold only. Completed folds are validated above.
        shutil.rmtree(folder)
    folder.mkdir(parents=True)
    history, target, data_audit = load_fold(args.cache_dir, args.structured_dir, args.faculties, fold, common)
    train_idx, val_idx, split_audit = chronological_split(history, args.val_semesters)
    split_audit['feature_origin_policy'] = 'Canonical row-time features retained; reconstructed course features use strictly earlier semesters.'
    split_audit['single_validation_semester'] = len(np.unique(history.semester[val_idx])) == 1
    if not split_audit['single_validation_semester']:
        print('[PROTOCOL] Multi-semester validation: memory is fixed at the training origin; '
              'row-time features may contain outcomes of earlier validation semesters. '
              'Use --val-semesters 1 for the default single-semester selection protocol.', flush=True)
    atomic_json({'data': data_audit, 'selection': split_audit}, folder / 'data_audit.json')
    seed = args.seed + fold * 1009
    selected_pre = Preprocessor.fit(history, train_idx)
    selected = selected_pre.transform(history)
    allowed = np.zeros(len(history), bool)
    allowed[train_idx] = True
    selected_history = build_history(history, history, max_history=args.max_history, allowed=allowed)
    train_set = MemoryDataset(selected, selected, selected_history, indices=train_idx)
    val_set = MemoryDataset(selected, selected, selected_history, indices=val_idx)
    blueprint = _seed(selected, train_idx, args, seed)
    logs, selected_epochs = [], {}
    selected_examples = min(len(train_set), args.max_samples)
    print(f'[F{fold}] selection train={len(train_idx):,}, validation={len(val_idx):,}, target={len(target):,}', flush=True)
    for variant in args.variants:
        model = _model(blueprint, selected, selected_pre, variant, args, seed)
        best_epoch, rows = optimize(model, train_set, args, args.epochs, seed, 'selection', variant, fold, val_set)
        selected_epochs[variant] = best_epoch
        logs.extend(rows)
        pd.DataFrame(logs).to_csv(folder / 'training_log.csv', index=False)
        del model
    del train_set, val_set, selected, selected_history, selected_pre, blueprint
    if args.device.startswith('cuda'):
        torch.cuda.empty_cache()
    all_idx = np.arange(len(history))
    preprocessor = Preprocessor.fit(history, all_idx)
    prepared_bank, prepared_target = preprocessor.transform(history), preprocessor.transform(target)
    fit_history = build_history(history, history, max_history=args.max_history)
    target_history = build_history(history, target, max_history=args.max_history)
    fit_set = MemoryDataset(prepared_bank, prepared_bank, fit_history)
    target_set = MemoryDataset(prepared_target, prepared_bank, target_history)
    blueprint = _seed(prepared_bank, all_idx, args, seed)
    frame = score_frame(target, fold)
    frame['suite26_seed_forest'] = seed_predict(blueprint, prepared_target.x)
    structures = []
    for variant in args.variants:
        model = _model(blueprint, prepared_bank, preprocessor, variant, args, seed)
        _, rows = optimize(model, fit_set, args, selected_epochs[variant], seed, 'refit', variant, fold,
                           examples_per_epoch=selected_examples)
        logs.extend(rows)
        pd.DataFrame(logs).to_csv(folder / 'training_log.csv', index=False)
        score, diagnostics = infer(model, target_set, args.device, args.eval_batch_size, diagnostics=variant == 'mint')
        frame[f'suite26_{variant}'] = score
        state = {key: value.detach().cpu() for key, value in model.state_dict().items()}
        bundle = dict(format_version=1, blueprint=blueprint, preprocessor=preprocessor.to_dict(),
                      model_config=model.config(), model_state=state, fold=fold,
                      faculties=args.faculties, common_features=common, max_history=args.max_history,
                      selected_epochs=selected_epochs[variant], optimizer_examples_per_epoch=selected_examples,
                      seed=seed, configuration=manifest['configuration'],
                      input_fingerprints=manifest['inputs'], code=manifest['code'], versions=manifest['versions'])
        atomic_checkpoint(bundle, folder / f'{variant}.pt')
        structure = dict(variant=variant, **model.structural_diagnostics(), checkpoint_bytes=(folder / f'{variant}.pt').stat().st_size)
        structures.append(structure)
        if variant == 'mint':
            diagnostics.insert(0, 'sample_id', frame.sample_id)
            diagnostics['faculty'] = frame.faculty
            diagnostics['actual'] = frame.actual
            diagnostics['history_full_count'] = target_history.full_count
            diagnostics['history_retained_count'] = target_history.retained_count
            diagnostics['unknown_course'] = prepared_target.course_id == 0
            diagnostics.to_csv(folder / 'memory_diagnostics.csv', index=False)
            if not args.skip_diagnostics:
                diagnose(model, prepared_target, prepared_bank, target_history, target_set, frame, args, folder, seed)
            stratified = frame.copy()
            stratified['history_stratum'] = pd.cut(target_history.full_count, bins=[-1, 0, 4, 16, np.inf], labels=['0', '1-4', '5-16', '17+']).astype(str)
            stratified['course_regime'] = np.where(prepared_target.course_id == 0, 'unknown', 'known')
            score_cols = [c for c in frame if c.startswith('suite26_')] + ['committee']
            records = []
            for grouping in ['history_stratum', 'course_regime']:
                for faculty, part in stratified.groupby('faculty'):
                    for row in _metric_rows(part, score_cols, grouping):
                        records.append({'faculty': faculty, 'stratum_type': grouping, 'stratum': row.pop(grouping), **row})
            pd.DataFrame(records).to_csv(folder / 'regime_metrics.csv', index=False)
        del model
    atomic_json(structures, folder / 'tree_diagnostics.json')
    atomic_json(dict(selected_epochs=selected_epochs, seconds=time.perf_counter() - started,
                     optimizer_examples_per_epoch=selected_examples,
                     training_rows=len(history), target_rows=len(target)), folder / 'fold_summary.json')
    frame.to_csv(folder / 'predictions.csv', index=False)
    # Compatibility outputs retain identifying keys, so future suites can join safely.
    for faculty, part in frame.groupby('faculty'):
        part.to_csv(folder / f'{faculty}_fold_{fold}_predictions.csv', index=False)
    files = {p.name: sha256(p) for p in sorted(folder.iterdir()) if p.is_file()}
    atomic_json(dict(status='complete', files=files), folder / 'complete.json')
    return frame


def main(argv=None):
    args = resolve_args(argv)
    torch.set_num_threads(args.threads)
    seed_all(args.seed)
    common = common_features_for_run(args)
    print('Suite26 MINT: memory conditions internal forest routing; final scores come only from leaves.', flush=True)
    print(f'Device={args.device}; faculties={args.faculties}; folds={args.folds}; variants={args.variants}', flush=True)
    if args.preflight_only:
        for fold in args.folds:
            history, target, audit = load_fold(args.cache_dir, args.structured_dir, args.faculties, fold, common)
            train_idx, val_idx, split = chronological_split(history, args.val_semesters)
            pre = Preprocessor.fit(history, train_idx)
            pre.transform(history)
            pre.transform(target)
            print(f'[PREFLIGHT F{fold}] OK: {len(history):,} history, {len(target):,} target, '
                  f'{len(train_idx):,}/{len(val_idx):,} selection rows, {pre.n_courses} course codes.', flush=True)
        print('Preflight complete; no training or result files created.', flush=True)
        return
    output = Path(args.out_dir)
    if output.exists() and any(output.iterdir()) and not args.resume:
        raise FileExistsError(f'Result directory is nonempty: {output}. Choose a new --out-dir or use --resume.')
    print('Computing cache and code fingerprints for safe resume.', flush=True)
    manifest = _manifest(args)
    existing = output / 'run_manifest.json'
    if args.resume and output.exists() and any(output.iterdir()):
        if not existing.exists() or json.loads(existing.read_text()) != manifest:
            raise ValueError('Resume configuration, code, versions or input fingerprints do not match. Use a new output directory.')
    output.mkdir(parents=True, exist_ok=True)
    atomic_json(manifest, existing)
    frames = []
    for fold in args.folds:
        folder = output / f'fold_{fold}'
        marker = folder / 'complete.json'
        if args.resume and marker.exists():
            completed = json.loads(marker.read_text())
            if completed.get('status') != 'complete' or not completed.get('files'):
                raise ValueError(f'Invalid completion manifest for fold {fold}.')
            for name, expected in completed['files'].items():
                if not (folder / name).is_file() or sha256(folder / name) != expected:
                    raise ValueError(f'Completed fold {fold} is missing or has modified file {name}. Use a new output directory.')
            print(f'[RESUME F{fold}] matching completed fold; reusing predictions.', flush=True)
            frames.append(pd.read_csv(folder / 'predictions.csv', dtype={'sample_id': str, 'student_id': str, 'course_id': str, 'faculty': str}))
        else:
            frames.append(run_fold(args, fold, common, manifest))
    frame = pd.concat(frames, ignore_index=True)
    frame, reference_audit = add_references(frame, args.reference_dirs)
    reference_audit.to_csv(output / 'reference_alignment.csv', index=False)
    report = write_report(frame, output, dev_folds=tuple(args.dev_folds), holdout_folds=tuple(args.holdout_folds),
                          bootstrap=args.bootstrap, seed=args.seed)
    print(f'Complete. Reports and reloadable model bundles: {output}', flush=True)
    print('Interpret component comparisons and interventions alongside uncertainty; improvement is not guaranteed.', flush=True)
    return report


if __name__ == '__main__':
    main()
