#!/usr/bin/env python3
"""One launcher entry point: preflight, development freeze, retrospective, full report."""
from __future__ import annotations
from s34_runtime import configure_cuda_workspace

configure_cuda_workspace()

import argparse
import csv
from datetime import datetime, timezone
import importlib.metadata
import json
import os
from pathlib import Path
import platform
import shutil
import sys
import tempfile
import time
import traceback

PACKAGE = Path(__file__).resolve().parent
VERSION = "1.0.1"


def arguments():
    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.ArgumentDefaultsHelpFormatter)
    p.add_argument("--config", default=str(PACKAGE/"config/default.json"))
    p.add_argument("--root")
    for name in ("cache-dir", "structured-dir", "output-dir", "log-file", "feature-view-manifest"):
        p.add_argument("--"+name)
    for name in ("faculties", "folds", "seeds", "arms"):
        p.add_argument("--"+name, nargs="+")
    for name in ("epochs", "min-epochs", "patience", "batch-size", "validation-blocks",
                 "backbone-width", "residual-blocks", "view-dim", "interaction-rank",
                 "threads", "gradient-accumulation", "bootstrap", "bootstrap-seed",
                 "expected-faculties", "hgb-iterations"):
        p.add_argument("--"+name, type=int)
    for name in ("learning-rate", "weight-decay", "dropout", "gradient-clip", "aux-weight"):
        p.add_argument("--"+name, type=float)
    p.add_argument("--device", choices=["auto", "cpu", "cuda"])
    p.add_argument("--diagnostics", choices=["full", "none"])
    p.add_argument("--amp", action="store_true", default=None)
    p.add_argument("--save-checkpoints", action=argparse.BooleanOptionalAction, default=None)
    for name in ("resume", "smoke-test", "synthetic", "preflight-only", "report-only",
                 "skip-tests", "skip-hgb", "include-a3", "print-feature-manifest",
                 "strict-data-gate", "print-log-path"):
        p.add_argument("--"+name, action="store_true", default=None)
    return p.parse_args()


def _list(value, numeric=False):
    if isinstance(value, str):
        value = [value]
    items = [x for part in value for x in str(part).split(",") if x]
    result = [int(x) for x in items] if numeric else items
    if len(set(result)) != len(result):
        raise ValueError("Duplicate faculty/fold/seed/arm selection")
    return result


def configuration(args):
    cfg = json.loads(Path(args.config).read_text())
    for k, v in vars(args).items():
        if k not in ("config",) and v is not None:
            # Boolean parser flags not in defaults are operational switches.
            cfg[k] = v
    cfg["root"] = str(Path(args.root or os.environ.get("AQ_ROOT") or cfg.get("root") or
        ("./synthetic_workspace" if cfg["synthetic"] else "/root/disk_3tb/earlywarning/30072026")).resolve())
    root = Path(cfg["root"])
    if cfg["synthetic"] or cfg["smoke_test"]:
        if args.epochs is None:
            cfg["epochs"] = 2
        if args.min_epochs is None:
            cfg["min_epochs"] = 1
        if args.patience is None:
            cfg["patience"] = 1
        if args.seeds is None:
            cfg["seeds"] = [29]
        if cfg["smoke_test"] and args.folds is None:
            cfg["folds"] = [1]
    if cfg["synthetic"] and args.expected_faculties is None:
        cfg["expected_faculties"] = 2
    suffix = "_synthetic" if cfg["synthetic"] else "_smoke" if cfg["smoke_test"] else ""
    cfg["cache_dir"] = str(Path(args.cache_dir or cfg.get("cache_dir") or root/"results/cross_faculty_residual_moe/cache").resolve())
    cfg["structured_dir"] = str(Path(args.structured_dir or cfg.get("structured_dir") or root/"results/suite12_structured_cache").resolve())
    cfg["output_dir"] = str(Path(args.output_dir or cfg.get("output_dir") or root/f"results/suite34_ipmvcl{suffix}").resolve())
    cfg["log_file"] = str(Path(args.log_file or cfg.get("log_file") or root/f"log/suite34_ipmvcl{suffix}.log").resolve())
    cfg["feature_view_manifest"] = str(Path(args.feature_view_manifest or cfg.get("feature_view_manifest") or PACKAGE/"config/feature_views.json").resolve())
    cfg["faculties"] = _list(cfg["faculties"])
    for k in ("folds", "seeds"):
        cfg[k] = _list(cfg[k], True)
    cfg["folds"] = sorted(cfg["folds"])
    cfg["arms"] = _list(cfg["arms"])
    if cfg["include_a3"] and "A3" not in cfg["arms"]:
        cfg["arms"].append("A3")
    if not set(cfg["folds"]).issubset(range(1, 8)) or not cfg["folds"] or not cfg["seeds"]:
        raise ValueError("Require nonempty folds in 1..7 and nonempty seeds")
    if not cfg["arms"] or not set(cfg["arms"]).issubset({"A0", "A0M", "A1", "A2", "P1", "A3"}):
        raise ValueError("Unknown/empty experimental arm")
    if not 1 <= cfg["min_epochs"] <= cfg["epochs"]:
        raise ValueError("Require 1 <= min_epochs <= epochs")
    for k in ("batch_size", "patience", "threads", "gradient_accumulation", "validation_blocks",
              "backbone_width", "view_dim", "interaction_rank", "expected_faculties", "hgb_iterations"):
        if cfg[k] < 1:
            raise ValueError(f"{k} must be positive")
    if cfg["bootstrap"] < 0 or cfg["residual_blocks"] < 0:
        raise ValueError("Negative bootstrap/residual block count")
    if not 0 <= cfg["dropout"] < 1 or cfg["learning_rate"] <= 0 or cfg["weight_decay"] < 0:
        raise ValueError("Invalid optimizer/dropout setting")
    if cfg["gradient_clip"] <= 0 or cfg["aux_weight"] < 0 or min(cfg["seeds"]) < 0:
        raise ValueError("Gradient clip must be positive; auxiliary weight and seeds nonnegative")
    logfile = Path(cfg["log_file"])
    if logfile.suffix != ".log" or any(
            Path(s) == logfile or Path(s) in logfile.parents
            for s in (cfg["cache_dir"], cfg["structured_dir"])):
        raise ValueError("Log must be a .log file outside the source cache directories")
    return cfg


def clean_json(value):
    import numpy as np
    if isinstance(value, dict):
        return {str(k): clean_json(v) for k, v in value.items()}
    if isinstance(value, (list, tuple)):
        return [clean_json(v) for v in value]
    if isinstance(value, np.ndarray):
        return clean_json(value.tolist())
    if isinstance(value, np.generic):
        return clean_json(value.item())
    if isinstance(value, float) and not np.isfinite(value):
        return None
    if isinstance(value, Path):
        return str(value)
    return value


def write_json(path, value):
    path = Path(path)
    path.parent.mkdir(parents=True, exist_ok=True)
    temporary = path.with_name(path.name+".tmp")
    temporary.write_text(json.dumps(clean_json(value), indent=2, ensure_ascii=False, sort_keys=True))
    temporary.replace(path)


def environment():
    import torch
    packages = {}
    for name in ("numpy", "pandas", "scipy", "scikit-learn", "joblib", "torch", "threadpoolctl"):
        packages[name] = importlib.metadata.version(name)
    return dict(package_version=VERSION, python=sys.version, platform=platform.platform(),
                dependencies=packages, cuda_available=torch.cuda.is_available(),
                torch_cuda_version=torch.version.cuda,
                device_name=torch.cuda.get_device_name(0) if torch.cuda.is_available() else "CPU",
                deterministic_algorithms="enabled_warn_only", tf32=False,
                cublas_workspace_config=configure_cuda_workspace())


def cell_key(faculty, fold, seed, arm):
    return f"{faculty}__f{fold}__{arm}__s{seed}"


def verify_completed(path, signature, freeze_hash=None):
    from s34_data import sha256_file
    status = json.loads((path/"complete.json").read_text())
    if status["run_signature"] != signature:
        raise ValueError("Completed cell signature mismatch")
    required = {"predictions.csv", "curves.csv", "metadata.json", "diagnostics.json", "events.json"}
    if not isinstance(status.get("artifacts"), dict) or not required.issubset(status["artifacts"]):
        raise ValueError("Incomplete completed-cell artifact manifest")
    if not isinstance(status.get("checkpoint_required"), bool):
        raise ValueError("Incomplete checkpoint requirement in completion manifest")
    if status["checkpoint_required"] and "checkpoint.pt" not in status["artifacts"]:
        raise ValueError("Missing required checkpoint artifact")
    if freeze_hash is not None and status.get("development_freeze_sha256") != freeze_hash:
        raise ValueError("Retrospective cell development-freeze hash mismatch")
    for name, digest in status["artifacts"].items():
        if Path(name).name != name:
            raise ValueError("Invalid artifact path in completion manifest")
        if not (path/name).is_file() or sha256_file(path/name) != digest:
            raise ValueError(f"Completed artifact integrity failed: {path/name}")
    metadata = json.loads((path/"metadata.json").read_text())
    key = metadata["key"]
    if status["key"] != key or path.name != cell_key(key["faculty"], key["fold"], key["seed"], key["arm"]):
        raise ValueError("Completed-cell key/directory identity mismatch")
    return status


def collect(output, signature, max_fold=None):
    import pandas as pd
    metrics, index, curves, interactions, views, history, budgets, runtimes, events = [], [], [], [], [], [], [], [], []
    for path in sorted((output/"cells").glob("*")):
        if path.name.startswith("incomplete_"):
            continue  # Uncommitted temporary directory, including a crash just before rename.
        if not path.is_dir() or not (path/"complete.json").exists():
            continue
        verify_completed(path, signature)
        meta = json.loads((path/"metadata.json").read_text())
        base = meta["key"]
        if max_fold is not None and int(base["fold"]) > max_fold:
            continue
        events.extend(json.loads((path/"events.json").read_text()))
        metrics.append(dict(**base, **meta["metrics"]))
        index.append(dict(**base, path=str(path/"predictions.csv")))
        c = pd.read_csv(path/"curves.csv")
        if not c.empty:
            curves.append(c.assign(**base, selected_epoch=meta["selection"]["selected_epoch"]))
        diag = json.loads((path/"diagnostics.json").read_text())
        for target, name in ((interactions, "interactions"), (views, "views"), (history, "history")):
            target.extend(dict(**base, **r) for r in diag[name])
        budgets.extend(dict(**base, **r) for r in meta["budgets"])
        runtimes.append(dict(**base, **meta["runtimes"]))
    return dict(metrics=pd.DataFrame(metrics), index=pd.DataFrame(index),
                curves=pd.concat(curves, ignore_index=True) if curves else pd.DataFrame(),
                interactions=pd.DataFrame(interactions), views=pd.DataFrame(views),
                history=pd.DataFrame(history), budgets=pd.DataFrame(budgets),
                runtimes=pd.DataFrame(runtimes), events=events)


def run_cell(cell, faculty, fold, seed, arm, cfg, manifest, calendar, signature,
             output, sources, freeze_hash=None):
    import numpy as np
    import pandas as pd
    from s34_checkpoint import save_checkpoint, replay_checkpoint
    from s34_data import json_hash, sha256_file
    from s34_diagnostics import diagnose, history_strata
    from s34_metrics import cell_metrics, budget_metrics
    from s34_reporting import note
    from s34_training import fit_predict, fit_hgb
    key = dict(faculty=faculty, fold=fold, seed=seed, arm=arm,
               stage="development" if fold <= 5 else "retrospective")
    destination = output/"cells"/cell_key(faculty, fold, seed, arm)
    if arm == "CacheReference" and not np.isfinite(cell.target.reference).all():
        note("REFERENCE_UNAVAILABLE", dict(**key, reason="Partial reference coverage; full target control not emitted"))
        return
    if (destination/"complete.json").exists():
        if not cfg["resume"]:
            raise ValueError("Existing completed cells require --resume")
        verify_completed(destination, signature, freeze_hash)
        note("RESUME_CELL", key)
        return
    if cfg["report_only"]:
        raise ValueError("Report-only run has incomplete requested cells")
    begin = time.monotonic()
    events = []
    def emit(tag, row):
        values = {**key, **row}
        events.append(dict(tag=tag, values=values))
        note(tag, values)
    if arm == "CacheReference":
        result = dict(probabilities=cell.target.reference, model=None, preprocessor=None,
                      selection=dict(selected_epoch=0), training_curves=[], final_train_ap=np.nan,
                      parameter_count=0, runtimes=dict(inference_seconds=0.))
    elif arm == "HGB":
        emit("HGB_CONFIGURATION", dict(learning_rate=.06, max_iter=cfg["hgb_iterations"],
             max_leaf_nodes=15, min_samples_leaf=20, l2_regularization=1.,
             early_stopping=False, preprocessing="NATIVE_NAN_ORIGINAL_RAW_CHANNELS"))
        result = fit_hgb(cell.history, cell.target, cfg, seed)
    else:
        result = fit_predict(cell.history, cell.target, manifest, cfg, seed, arm, emit, calendar)
    p = result["probabilities"]
    metric = cell_metrics(cell.target.y, p)
    support_hash = json_hash(dict(row_index=cell.target.row_index,
        student=cell.target.frame.IDSV.astype(str).tolist(),
        course=cell.target.frame.IDMH.astype(str).tolist(),
        semester=cell.target.frame.target_NHHK.astype(str).tolist(), y=cell.target.y))
    metric.update(parameter_count=result["parameter_count"], support_hash=support_hash,
                  final_train_ap=result["final_train_ap"],
                  validation_ap=result["selection"].get("validation_ap", np.nan),
                  selected_epoch=result["selection"]["selected_epoch"],
                  input_dimension=(result["preprocessor"].dimension if result["preprocessor"] else cell.target.X.shape[1]))
    diag_start = time.monotonic()
    if cfg["diagnostics"] == "full" and arm != "CacheReference":
        diag = diagnose(result, cell.target)
    else:
        diag = dict(interactions=[], views=[], history=history_strata(cell.target, p))
    diagnostic_seconds = time.monotonic()-diag_start
    output.joinpath("cells").mkdir(parents=True, exist_ok=True)
    with tempfile.TemporaryDirectory(prefix="incomplete_", dir=output/"cells") as td:
        staging = Path(td)
        prediction = pd.DataFrame(dict(**{k: [v]*len(p) for k, v in key.items()},
            row_index=cell.target.row_index, student_id=cell.target.frame.IDSV.astype(str),
            course_id=cell.target.frame.IDMH.astype(str),
            target_semester=cell.target.frame.target_NHHK.astype(str), y=cell.target.y, p=p,
            reference_prediction=cell.target.reference))
        prediction.to_csv(staging/"predictions.csv", index=False)
        curves = pd.DataFrame(result["training_curves"])
        if curves.empty:
            curves = pd.DataFrame(columns=["phase", "epoch", "train_loss", "train_ap", "validation_ap"])
        curves.to_csv(staging/"curves.csv", index=False)
        write_json(staging/"diagnostics.json", diag)
        write_json(staging/"events.json", events)
        checkpoint_max_error = None
        if cfg["save_checkpoints"] and result["model"] is not None:
            save_checkpoint(staging/"checkpoint.pt", result, dict(**key, feature_names=cell.target.names,
                run_signature=signature, source_sha256=sources, software=cfg["software"],
                feature_manifest_hash=manifest["schema_hash"], selected_epoch=result["selection"]["selected_epoch"]))
            replay = replay_checkpoint(staging/"checkpoint.pt", cell.target.X, cell.target.names)
            checkpoint_max_error = float(np.max(np.abs(replay-p)))
            if not np.allclose(replay, p, atol=2e-5, rtol=2e-5):
                raise ValueError(f"CPU-portable checkpoint replay mismatch: {checkpoint_max_error}")
        runtimes = dict(**result["runtimes"], diagnostics_seconds=diagnostic_seconds,
                        total_seconds=time.monotonic()-begin)
        metric["checkpoint_replay_max_abs_error"] = checkpoint_max_error
        metadata = dict(key=key, metrics=metric, selection=result["selection"],
                        budgets=[budget_metrics(cell.target.y, p, cell.target.row_index, f)
                                 for f in (.10, .15, .20, .25)], runtimes=runtimes,
                        feature_names=cell.target.names, source_sha256=sources,
                        diagnostic_status="COMPLETE" if cfg["diagnostics"] == "full" else "NOT_REQUESTED")
        write_json(staging/"metadata.json", metadata)
        artifacts = {f.name: sha256_file(f) for f in staging.iterdir() if f.is_file()}
        write_json(staging/"complete.json", dict(run_signature=signature, key=key,
            development_freeze_sha256=freeze_hash, artifacts=artifacts,
            checkpoint_required=bool(cfg["save_checkpoints"] and result["model"] is not None)))
        if destination.exists():
            raise ValueError(f"Incomplete destination exists; inspect before retry: {destination}")
        staging.rename(destination)
    if (destination/"checkpoint.pt").exists():
        checkpoint_path = output/"checkpoints"/(destination.name+".pt")
        checkpoint_path.parent.mkdir(exist_ok=True)
        if not checkpoint_path.exists():
            os.link(destination/"checkpoint.pt", checkpoint_path)
    note("FACULTY_FOLD_RESULT", dict(**key, **metric, **runtimes))


def _matrix(metrics, index):
    return metrics.pivot_table(index=index, columns="arm", values="ap", aggfunc="mean").reset_index() if not metrics.empty else metrics


def report(output, collected, cfg, decision, audits, signature):
    import numpy as np
    import pandas as pd
    from s34_comparisons import (summarize_metrics, paired_contrasts, operational_tables,
                                archived_comparisons)
    from s34_data import sha256_file
    from s34_diagnostics import rescue_harm
    from s34_reporting import note, print_table, conclusions
    metrics, index = collected["metrics"], collected["index"]
    note("RESTORED_TRAINING_AUDITS", completed_cells=len(metrics),
         event_count=len(collected["events"]), source="HASHED_COMPLETED_CELL_EVENTS")
    for event in collected["events"]:
        if event["tag"] != "EPOCH_METRICS":
            note(event["tag"], event["values"])
    thresholds, operations = operational_tables(index)
    contrasts, deltas, uncertainty = paired_contrasts(metrics, cfg["bootstrap"], cfg["bootstrap_seed"])
    summary = summarize_metrics(metrics)
    dev, late = metrics[metrics.fold <= 5], metrics[metrics.fold >= 6]
    faculty_summary = metrics.groupby(["stage", "faculty", "arm"], as_index=False).ap.mean()
    fold_summary = metrics.groupby(["fold", "arm"], as_index=False).ap.mean()
    seed_summary = metrics.groupby(["stage", "seed", "arm"], as_index=False).ap.mean()
    # Variability across complete per-seed macro scores; never seed ensembles.
    seed_variability = seed_summary.groupby(["stage", "arm"]).ap.agg(["mean", "std", "count"]).reset_index()
    tables = {
        "FACULTY_FOLD_RESULTS": metrics,
        "DEVELOPMENT_MACRO_RESULTS": summary[summary.stage == "development"],
        "DEVELOPMENT_FOLD_MATRIX": _matrix(dev, "fold"),
        "DEVELOPMENT_FACULTY_MATRIX": _matrix(dev, "faculty"),
        "DEVELOPMENT_PAIRED_CONTRASTS": contrasts[contrasts.stage == "development"] if not contrasts.empty else contrasts,
        "RETROSPECTIVE_RESULTS": summary[summary.stage == "retrospective"],
        "RETROSPECTIVE_FOLD_MATRIX": _matrix(late, "fold"),
        "RETROSPECTIVE_FACULTY_MATRIX": _matrix(late, "faculty"),
        "ALL_FOLD_MATRIX": _matrix(metrics, "fold"),
        "CALIBRATION_RESULTS": summary,
        "HISTORICAL_COMPARISONS": archived_comparisons(cfg["primary_population"]),
        "MATCHED_WITHIN_RUN_COMPARISONS": contrasts,
        "PAIRED_CELL_DIFFERENCES": deltas,
        "OPERATIONAL_THRESHOLDS": thresholds,
        "OPERATIONAL_METRICS": operations,
        "ALERT_BUDGET_RESULTS": collected["budgets"],
        "INTERACTION_ABLATIONS": collected["interactions"],
        "VIEW_DIAGNOSTICS": collected["views"],
        "HISTORY_AVAILABILITY": collected["history"],
        "SEED_RESULTS": seed_summary,
        "SEED_VARIABILITY": seed_variability,
        "UNCERTAINTY": uncertainty,
        "RUNTIMES": collected["runtimes"],
        "DATA_COVERAGE": pd.DataFrame(audits),
    }
    if not operations.empty:
        op_columns = ["f1", "f2", "precision", "recall", "alert_fraction"]
        tables["OPERATIONAL_MACRO_RESULTS"] = operations.groupby(
            ["stage", "arm", "beta"], as_index=False)[op_columns].mean()
        tables["OPERATIONAL_POLICY_SUPPORT"] = operations.groupby(
            ["stage", "arm", "beta"]).f1.agg(["size", "count"]).reset_index().rename(
                columns={"size": "total_seed_cells", "count": "available_seed_cells"})
    if not collected["budgets"].empty:
        tables["ALERT_BUDGET_MACRO_RESULTS"] = collected["budgets"].groupby(
            ["stage", "arm", "budget"], as_index=False)[
                ["f1", "f2", "precision", "recall", "alert_fraction"]].mean()
    if not collected["history"].empty:
        strata = collected["history"]
        if "ap" in strata:
            tables["HISTORY_STRATUM_MACRO_RESULTS"] = strata.groupby(
                ["stage", "arm", "stratum"], as_index=False)[["ap", "auc", "rows", "failures"]].mean()
    if not collected["curves"].empty:
        curves = collected["curves"].copy()
        curves["train_validation_gap"] = curves.train_ap-curves.validation_ap
        tables["EPOCH_METRICS"] = curves
        tables["TRAINING_GENERALIZATION_GAPS"] = curves[
            (curves.phase == "selection") & (curves.epoch == curves.selected_epoch)]
    else:
        tables["EPOCH_METRICS"] = pd.DataFrame()
    effects = deltas.groupby(["contrast", "faculty", "fold"], as_index=False).delta_ap.mean() if not deltas.empty else deltas
    if not effects.empty:
        effects["stage"] = np.where(effects.fold <= 5, "development", "retrospective")
        stable = effects.groupby(["contrast", "faculty", "stage"]).delta_ap.mean().unstack("stage")
        if "development" in stable and "retrospective" in stable:
            stable["sign_reversal"] = stable.development*stable.retrospective < 0
        tables["TEMPORAL_STABILITY"] = stable.reset_index()
        tables["FACULTY_PAIRED_EFFECTS"] = deltas.groupby(["stage", "contrast", "faculty"], as_index=False).delta_ap.mean()
        tables["FOLD_PAIRED_EFFECTS"] = deltas.groupby(["stage", "contrast", "fold"], as_index=False).delta_ap.mean()
        tables["SEED_PAIRED_EFFECTS"] = deltas.groupby(["stage", "contrast", "seed"], as_index=False).delta_ap.mean()
    else:
        tables["TEMPORAL_STABILITY"] = pd.DataFrame()
    threshold_map = {(r.faculty, int(r.fold), int(r.seed), r.arm, int(r.beta)): r.threshold
                     for r in thresholds.itertuples()}
    rescues = []
    for (faculty, fold, seed), records in index.groupby(["faculty", "fold", "seed"]):
        paths = {r.arm: r.path for r in records.itertuples()}
        if "A2" not in paths:
            continue
        new = pd.read_csv(paths["A2"], dtype={"student_id": str, "course_id": str, "target_semester": str})
        for base in ("A0", "A1"):
            if base not in paths:
                continue
            original = pd.read_csv(paths[base], dtype={"student_id": str, "course_id": str, "target_semester": str})
            a = {b: threshold_map.get((faculty, fold, seed, "A2", b)) for b in (1, 2)}
            b = {v: threshold_map.get((faculty, fold, seed, base, v)) for v in (1, 2)}
            rescues.extend(dict(faculty=faculty, fold=int(fold), seed=int(seed), contrast="A2-"+base, **r)
                           for r in rescue_harm(new, original, a, b))
    tables["ERROR_RESCUES_AND_HARMS"] = pd.DataFrame(rescues)
    tables["MODEL_PARAMETER_COUNTS"] = metrics[["faculty", "fold", "seed", "arm", "parameter_count", "input_dimension"]]
    # Write all machine-readable aggregate artifacts and print exactly those tables.
    names = dict(FACULTY_FOLD_RESULTS="all_metrics", OPERATIONAL_THRESHOLDS="threshold_policies",
                 OPERATIONAL_METRICS="operational_metrics", INTERACTION_ABLATIONS="interaction_ablations",
                 VIEW_DIAGNOSTICS="view_diagnostics", HISTORY_AVAILABILITY="history_strata",
                 UNCERTAINTY="uncertainty", RUNTIMES="runtimes", EPOCH_METRICS="training_curves",
                 ERROR_RESCUES_AND_HARMS="rescues_and_harms", HISTORICAL_COMPARISONS="historical_comparisons",
                 PAIRED_CELL_DIFFERENCES="paired_contrasts")
    for name, frame in tables.items():
        frame.to_csv(output/(names.get(name, name.lower())+".csv"), index=False)
        print_table(name, frame)
    faculty_summary.to_csv(output/"faculty_summary.csv", index=False)
    fold_summary.to_csv(output/"fold_summary.csv", index=False)
    # Stream prediction shards; never construct the full multi-arm table in RAM.
    temporary = output/"all_predictions.csv.tmp"
    with temporary.open("w") as dest:
        first = True
        for r in index.sort_values(["faculty", "fold", "seed", "arm"]).itertuples():
            with open(r.path) as source:
                header = source.readline()
                if first:
                    dest.write(header)
                    first = False
                shutil.copyfileobj(source, dest)
    temporary.replace(output/"all_predictions.csv")
    write_json(output/"report_manifest.json", dict(run_signature=signature,
        completed_cells=len(metrics), primary_population=cfg["primary_population"],
        diagnostic_status=cfg["diagnostics"], development_freeze_sha256=sha256_file(output/"development_selection.json"),
        tables={name: dict(rows=len(frame), columns=list(frame.columns)) for name, frame in tables.items()}))
    note("DEVELOPMENT_DECISION", decision)
    for message in conclusions(contrasts, decision, metrics):
        print("[RESEARCH_CONCLUSIONS] "+message, flush=True)
    questions = [
        ("Q1 semantic view separation", "A1-A0 / A1-A0M"),
        ("Q2 explicit interactions", "A2-A1"),
        ("Q3 capacity control", "A2-A0M"),
        ("Q4 semantic assignment", "A2-P1; three partitions have limited placebo coverage"),
        ("Q5 interaction types", "zero_SC / zero_HC sensitivity, not necessity or causal attribution"),
        ("Q6 chronological generalization", "development / F6 / F7 / validation gaps"),
        ("Q7 faculty heterogeneity", "complete faculty effects and worst losses"),
        ("Q8 limited history", "observed-cache flags and supported strata; unknown remains unknown"),
        ("Q9 warning decisions", "frozen beta1/beta2 policies plus 10/15/20/25% budgets"),
        ("Q10 strong predictors", "same-run HGB, CacheReference, archived support-qualified metrics"),
        ("Q11 hypothesis", decision["hypothesis"]),
        ("Q12 continuation", "See descriptive RESEARCH_CONCLUSIONS; no deployment certification")]
    print_table("RESEARCH_QUESTIONS", pd.DataFrame(questions, columns=["question", "evidence"]))


def execute(cfg):
    import numpy as np
    import pandas as pd
    import torch
    from s34_comparisons import operational_tables, promotion_decision
    from s34_data import (discover_population, inspect_population, load_cell,
                          json_hash, sha256_file)
    from s34_model import IPMVCL, matched_width, parameter_count
    from s34_preprocessing import Preprocessor
    from s34_reporting import note, print_table
    from s34_synthetic import make_synthetic
    from s34_views import bind_manifest, randomize_manifest, view_indices, VIEWS
    root, output = Path(cfg["root"]), Path(cfg["output_dir"])
    if cfg["synthetic"]:
        canonical_destination = (root/"results/cross_faculty_residual_moe/cache").resolve()
        structured_destination = (root/"results/suite12_structured_cache").resolve()
        if (Path(cfg["cache_dir"]) != canonical_destination or
                Path(cfg["structured_dir"]) != structured_destination):
            raise ValueError("Synthetic cache path overrides are not allowed; use a separate --root")
        make_synthetic(root)
    cfg["synthetic_data"] = (root/"SYNTHETIC_DATA.json").exists()
    for source in (Path(cfg["cache_dir"]), Path(cfg["structured_dir"])):
        if output == source or output in source.parents or source in output.parents:
            raise ValueError("Output directory must be separate from source cache trees")
    cfg["software"] = environment()
    note("RUN_CONFIGURATION", cfg)
    note("ENVIRONMENT", cfg["software"])
    note("DEPENDENCIES", cfg["software"]["dependencies"])
    note("DATA_DISCOVERY", cache_dir=cfg["cache_dir"], structured_dir=cfg["structured_dir"],
         newer_experiment_caches_required=False)
    population = discover_population(cfg["cache_dir"], cfg["structured_dir"], cfg["expected_faculties"])
    common, audits, calendar, sources = inspect_population(
        population, cfg["strict_data_gate"], lambda row: note("PREFLIGHT_SCAN", row))
    faculties = sorted(population) if cfg["faculties"] == ["all"] else cfg["faculties"]
    if not set(faculties).issubset(population):
        raise ValueError("Requested faculty missing from canonical population")
    cfg["resolved_faculties"] = faculties
    first = faculties[0]
    first_cell = load_cell(*population[first][1], first, 1, common, cfg["strict_data_gate"])
    names = first_cell.history.names
    catalog = json.loads(Path(cfg["feature_view_manifest"]).read_text())
    pp = Preprocessor(names, catalog.get("categorical", []), cfg["categorical_slots"], cfg["clip"])
    manifest = bind_manifest(names, catalog, pp.bundles)
    cfg["matched_width"] = matched_width(pp.dimension, view_indices(manifest, pp.bundles), cfg)
    cfg["primary_population"] = (len(population) == 14 and len(faculties) == 14 and
        cfg["folds"] == list(range(1, 8)) and set(cfg["seeds"]) == {29, 129, 229} and
        {"A0", "A0M", "A1", "A2", "P1"}.issubset(cfg["arms"]) and
        not cfg["smoke_test"] and not cfg["synthetic_data"])
    placebo = {seed: randomize_manifest(manifest, pp.bundles, cfg["partition_seed"]+seed)
               for seed in cfg["seeds"]}
    feature_rows = []
    for name in names:
        owner = next((v for v in VIEWS if name in manifest[v]), "full_path_only")
        feature_rows.append(dict(feature=name, view=owner, channels=len(pp.bundles[name]),
                                 reviewed=name not in manifest["unreviewed_live_features"]))
    print_table("FEATURE_SCHEMA", pd.DataFrame(feature_rows))
    note("FEATURE_VIEW_MANIFEST", manifest)
    for seed, part in placebo.items():
        note("PLACEBO_VIEW_MANIFEST", dict(model_seed=seed, **part))
    for audit in audits:
        safe = dict(audit)
        if audit["fold"] >= 6:
            for key in ("target_failures", "target_prevalence", "history_failures", "excluded_failures"):
                safe[key] = "QUARANTINED_UNTIL_DEVELOPMENT_FREEZE"
        note("CACHE_ALIGNMENT", safe)
    note("CHRONOLOGY_AUDIT", global_historical_calendars=calendar, source_release_times="UNVERIFIED_SEMESTER_PROXY",
         target_labels_used_for_fitting=False, retrospective_label_summaries_quarantined=True)
    parameter_rows = []
    for arm in cfg["arms"]:
        model = IPMVCL(pp.dimension, view_indices(manifest, pp.bundles), arm, cfg)
        parameter_rows.append(dict(arm=arm, input_dimension=pp.dimension, full_input_dimension=pp.dimension,
                                   trainable_parameters=parameter_count(model),
                                   optimizer_parameters=parameter_count(model)))
    counts = {r["arm"]: r["trainable_parameters"] for r in parameter_rows}
    if "A1" in counts and "A2" in counts and counts["A1"] != counts["A2"]:
        raise ValueError("A1/A2 parameter matching failed")
    if "A0M" in counts and "A2" in counts and abs(counts["A0M"]/counts["A2"]-1) > .05:
        raise ValueError("A0M matching failed")
    if "P1" in counts and "A2" in counts and counts["P1"] != counts["A2"]:
        raise ValueError("P1 parameter matching failed")
    print_table("MODEL_PARAMETER_COUNTS", pd.DataFrame(parameter_rows))
    output.mkdir(parents=True, exist_ok=True)
    if cfg["preflight_only"]:
        write_json(output/"preflight_feature_manifest.json", manifest)
        note("RUN_STATUS", status="PREFLIGHT_COMPLETE", real_cache_fitting=False,
             origin_availability_certified=False, primary_research_result=False)
        return
    package_sources = {p.relative_to(PACKAGE).as_posix(): sha256_file(p)
                       for pattern in ("*.py", "*.sh", "config/*.json", "PROTOCOL.md")
                       for p in PACKAGE.glob(pattern)}
    excluded = {"resume", "report_only", "preflight_only", "print_log_path", "print_feature_manifest",
                "skip_tests", "log_file"}
    material = {k: v for k, v in cfg.items() if k not in excluded}
    signature = json_hash(dict(configuration=material, manifest=manifest, placebo=placebo,
                               source_sha256=sources, package_sources=package_sources))
    prior_path = output/"config.json"
    if prior_path.exists():
        prior = json.loads(prior_path.read_text())
        if not cfg["resume"] or prior["run_signature"] != signature:
            raise ValueError("Existing run signature differs or --resume missing; use a new output directory")
    else:
        write_json(prior_path, dict(run_signature=signature, configuration=cfg))
    write_json(output/"environment.json", cfg["software"])
    write_json(output/"source_manifest.json", dict(source_sha256=sources, package_sources=package_sources))
    write_json(output/"feature_manifest.json", dict(semantic=manifest, placebo=placebo,
                                                    transformed_feature_names=pp.transformed_names,
                                                    feature_bundles=pp.bundles))
    note("RUN_SIZE", neural_cells=len(faculties)*len(cfg["folds"])*len(cfg["seeds"])*len(cfg["arms"]),
         training_phases_per_neural_cell=2, primary_population=cfg["primary_population"],
         device=cfg["device"], runtime_estimate="MEASURE_REAL_CACHE_SMOKE; NOT_SYNTHETIC")
    del first_cell
    freeze = output/"development_selection.json"
    freeze_hash = None
    for stage, folds in (("development", [f for f in cfg["folds"] if f <= 5]),
                         ("retrospective", [f for f in cfg["folds"] if f >= 6])):
        if stage == "retrospective":
            dev = collect(output, signature, max_fold=5)
            metrics = dev["metrics"]
            if metrics.empty:
                metrics = pd.DataFrame(columns=["faculty", "fold", "seed", "arm", "stage", "ap"])
            dev_index = dev["index"]
            _, dev_operations = operational_tables(dev_index)
            decision = promotion_decision(metrics, dev_operations, cfg["primary_population"])
            decision.update(run_signature=signature, protocol_version=VERSION,
                development_predictions_digest=json_hash(
                    sorted(sha256_file(r.path) for r in dev_index.itertuples()
                           if int(r.fold) <= 5)) if not dev_index.empty else json_hash([]))
            if freeze.exists():
                if json.loads(freeze.read_text()) != clean_json(decision):
                    raise ValueError("Immutable development freeze changed; refusing retrospective continuation")
            else:
                write_json(freeze, decision)
            freeze_hash = sha256_file(freeze)
            note("DEVELOPMENT_DECISION", decision)
            if not dev["metrics"].empty:
                from s34_comparisons import summarize_metrics
                print_table("DEVELOPMENT_MACRO_RESULTS", summarize_metrics(dev["metrics"][dev["metrics"].fold <= 5]))
        for fold in folds:
            for faculty in faculties:
                cp, sp = population[faculty][fold]
                start = time.monotonic()
                cell = load_cell(cp, sp, faculty, fold, common, cfg["strict_data_gate"])
                note("CELL_DATA_READY", faculty=faculty, fold=fold,
                     loading_seconds=time.monotonic()-start, history_rows=len(cell.history),
                     target_rows=len(cell.target))
                for seed in cfg["seeds"]:
                    arms = cfg["arms"] + ([] if cfg["skip_hgb"] else ["HGB"]) + ["CacheReference"]
                    for arm in arms:
                        chosen = placebo[seed] if arm == "P1" else manifest
                        run_cell(cell, faculty, fold, seed, arm, cfg, chosen, calendar[fold],
                                 signature, output, dict(canonical=sources[str(cp.resolve())],
                                 structured=sources[str(sp.resolve())]), freeze_hash)
                del cell
                if torch.cuda.is_available():
                    torch.cuda.empty_cache()
    collected = collect(output, signature)
    if collected["metrics"].empty:
        raise ValueError("No completed evaluation cells")
    decision = json.loads(freeze.read_text())
    report(output, collected, cfg, decision, audits, signature)
    note("RUN_STATUS", status="COMPLETE", completed_cells=len(collected["metrics"]),
         synthetic=cfg["synthetic_data"], smoke=cfg["smoke_test"],
         primary_research_run=cfg["primary_population"], real_data_performance_claimed=False,
         source_cache_modified=False, results=str(output), expected_log=cfg["log_file"])


def main():
    args = arguments()
    cfg = configuration(args)
    if args.print_log_path:
        print(cfg["log_file"])
        return
    execute(cfg)


if __name__ == "__main__":
    try:
        main()
    except Exception as error:
        print("[RUN_STATUS] "+json.dumps(dict(status="FAILED", error=str(error))), flush=True)
        traceback.print_exc()
        sys.exit(1)
