#!/usr/bin/env bash
# kld-gate-qwen38.sh — RUNS ON DANKSERVER (or anywhere the reports are). The campaign's
# acceptance gate: three KLD reports against ONE reference recording, one verdict.
#
# The reference is the BF16 container built from the vendor checkpoint (run-qwen38-bf16.sh
# kldref, in the same drained window that records the calibration grams). Every scored
# container is measured against that one recording, so the KL scale runs from 0 = the
# checkpoint itself downward in faithfulness. Three containers ride it:
#
#   fp8.json    the published FP8-native release   — the achievable end of the interval
#   iq4r.json   the payload frank-archon serves    — the bar to beat
#   cand.json   the arm under test                 — the subject
#
# The FP8 number is what makes the interval absolute instead of relative: "half the gap"
# is half of the distance between the 4-bit payload and the near-lossless release, not half
# of an invented distance to the checkpoint. That is also why the FP8 payload is FETCHED and
# scored, never converted: it is a second opinion about what this checkpoint tolerates, not a
# step of the campaign. It lands LAST (disk sequencing) — by then the 335 GiB bf16 container
# is gone, so its 172.8 GiB fits.
#
# The law, in order of severity, on the mean KL of one slice (--slice all | a corpus source):
#   1. KL(fp8) < KL(iq4r)                 the anchors are ordered. If the near-lossless
#                                         release does NOT sit closer to the checkpoint than
#                                         the 4-bit payload, the corpus, the tokenizer or the
#                                         boot shape is wrong and no arm number means anything.
#   2. KL(fp8) < KL(cand) < KL(iq4r)      the candidate lies strictly inside the interval —
#                                         outside it, something is mis-measured, not better
#   3. KL(cand) <= KL(iq4r) - R x gap     it closes at least R (--recover, default 0.5) of the
#                                         gap = KL(iq4r) - KL(fp8): at least half the way from
#                                         what is served toward the release (agreed 2026-10-27)
#   4. top-1(cand) >= top-1(iq4r)         the agreement the harness keys on does not fall
#
# Booting the containers is NOT this script's job: `run-qwen38-bf16.sh score RAD OUT.json`
# writes the reports and owns the single engine argv (same pin, --tp 2, --kv-cache-dtype fp8,
# same step size, --deterministic, no speculation) that makes the three numbers comparable.
# This script is arithmetic, so it re-runs against old reports and is testable without a GPU.
#
# Usage: kld-gate-qwen38.sh FP8.json IQ4R.json CAND.json [--slice NAME] [--recover F]
set -uo pipefail

[ "$#" -ge 3 ] || { echo "usage: kld-gate-qwen38.sh FP8.json IQ4R.json CAND.json [--slice NAME] [--recover F]" >&2; exit 2; }
python3 - "$@" <<'PY'
import json, sys

a = sys.argv[1:]
opts, files = [], []
i = 0
while i < len(a):
    if a[i].startswith("--"):
        opts += [a[i], a[i + 1]]
        i += 2
    else:
        files.append(a[i])
        i += 1
if len(files) != 3:
    sys.exit("usage: kld-gate-qwen38.sh FP8.json IQ4R.json CAND.json [--slice NAME] [--recover F]")
o = dict(zip(opts[0::2], opts[1::2]))
slice_ = o.get("--slice", "all")
recover = float(o.get("--recover", 0.5))
if not 0.0 < recover <= 1.0:
    sys.exit(f"--recover must be in (0,1], got {recover}")


def die(msg):
    print(msg, file=sys.stderr)
    raise SystemExit(2)


def read(path):
    try:
        d = json.load(open(path))
    except Exception as e:
        die(f"cannot read the KLD report {path}: {e}")
    if slice_ == "all":
        g = d.get("all")
    else:
        g = (d.get("by_source") or {}).get(slice_)
        if g is None:
            die(f"{path} has no slice {slice_!r}; it has: "
                f"{', '.join(sorted(d.get('by_source') or {})) or '(none)'}")
    if g is None or "kld" not in g or "top1_agreement" not in g:
        die(f"{path} has no {slice_!r} summary — wrong report version?")
    return d, g


rows = []
for label, path in zip(("fp8", "iq4r", "cand"), files):
    d, g = read(path)
    rows.append((label, path, d.get("model", "?"), g["kld"]["mean"], g["kld"]["p99_9"],
                 g["top1_agreement"], g["positions"]))

print(f"reference: BF16 container; slice: {slice_}")
print(f"{'':6} {'model':38} {'KL mean':>10} {'KL p99.9':>10} {'top-1':>8}  positions")
for label, path, model, kl, p999, top1, n in rows:
    print(f"{label:6} {str(model)[:38]:38} {kl:10.6f} {p999:10.4f} {100*top1:7.2f}%  {n}")
r = {label: (kl, top1) for label, _p, _m, kl, _q, top1, _n in rows}
kl_fp8, kl_iq4r, kl_cand = r["fp8"][0], r["iq4r"][0], r["cand"][0]
t_iq4r, t_cand = r["iq4r"][1], r["cand"][1]
gap = kl_iq4r - kl_fp8
ok = True


def law(n, text, passed):
    global ok
    ok = ok and passed
    print(f"  [{'PASS' if passed else 'FAIL'}] {n}. {text}")


law(1, f"anchors ordered: fp8 {kl_fp8:.6f} < iq4r {kl_iq4r:.6f} (gap {gap:.6f})",
    gap > 0)
law(2, f"candidate inside the interval: {kl_fp8:.6f} < {kl_cand:.6f} < {kl_iq4r:.6f}",
    kl_fp8 < kl_cand < kl_iq4r)
need = kl_iq4r - recover * gap
law(3, f"candidate closes {100*max((kl_iq4r - kl_cand)/gap, 0):.1f}% of the "
       f"{gap:.6f} gap (needs {100*recover:.0f}%, i.e. KL <= {need:.6f})"
       if gap > 0 else "gap is not positive; cannot score recovery",
    gap > 0 and kl_cand <= need)
law(4, f"candidate top-1 {100*t_cand:.2f}% >= served iq4r top-1 {100*t_iq4r:.2f}%",
    t_cand >= t_iq4r)
print("KLD GATE " + ("PASS" if ok else "FAIL"))
sys.exit(0 if ok else 1)
PY