# THE ADAPTER FILE (ADR-0067 D6): what a Track B trainer hands to the scorer, and what the customer downloads.
# ONE safetensors file, because a pipeline stage passes exactly one artifact to the next (/in/upN):
#   tensors       PEFT's own names and shapes for LoRA on the seven projections of every layer, F32 or BF16;
#   __metadata__  {"format": "pt", "nexido": <JSON text>}, the JSON holding:
#     kind           "nexido-lora-v1"
#     base_model     {"repo": ..., "revision": ...}, the model the image holds
#     lora           {"r", "lora_alpha", "target_modules"}, the whole adapter configuration: nothing else is read
#     plan_version   the Track B plan version it was trained under
#     split          the server's split declaration it trained on, and trained_on: "train"
#     input          {"file_sha256", "row_tokens_sha256"}: the counted file it trained on
# The scorer refuses anything else, and refuses an adapter trained on another split or another file.
import hashlib, io, json, os, re, struct
KIND = "nexido-lora-v1"
REPO, REV = "Qwen/Qwen3-4B-Instruct-2507", "cdbee75f17c01a7cc42f958dc650907174af0554"
T = ("q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj")
KEY = re.compile(r"^base_model\.model\.(model\.layers\.(\d+)\.(?:self_attn|mlp)\.(%s))\.lora_([AB])\.weight$"
                 % "|".join(T))
DTYPES = {"F32": 4, "BF16": 2}
MAX_FILE = 512 << 20
MAX_HEADER = 4 << 20
SPLIT_KEYS = ("rule_version", "seed", "test_bps", "val_bps", "n_train", "n_val", "n_test",
              "digest_train", "digest_val", "digest_test")
class AdapterRefusal(Exception):
    def __init__(self, reason, detail):
        Exception.__init__(self, "%s: %s" % (reason, detail))
        self.reason, self.detail = reason, detail
def _no_constant(c):
    raise ValueError("%s is not JSON" % c)
def _int(v):
    return type(v) is int
def read(path):
    """The file's header, its metadata and its size, every byte accounted for; or AdapterRefusal."""
    with io.open(path, "rb") as f:
        f.seek(0, 2)
        size = f.tell()
        f.seek(0)
        if size < 8 or size > MAX_FILE:
            raise AdapterRefusal("adapter_size", "%d bytes" % size)
        n = struct.unpack("<Q", f.read(8))[0]
        if n < 2 or n > MAX_HEADER or 8 + n > size:
            raise AdapterRefusal("adapter_header", "a header of %d bytes" % n)
        raw = f.read(n)
    try:
        hdr = json.loads(raw.decode("utf-8"), parse_constant=_no_constant)
    except (UnicodeDecodeError, ValueError, RecursionError):
        raise AdapterRefusal("adapter_header", "the header is not JSON")
    if not isinstance(hdr, dict):
        raise AdapterRefusal("adapter_header", "the header is not an object")
    meta = hdr.pop("__metadata__", None)
    if not isinstance(meta, dict) or set(meta) != {"format", "nexido"} or meta["format"] != "pt" or not isinstance(
            meta["nexido"], str):
        raise AdapterRefusal("adapter_metadata", "the metadata must be exactly format pt and nexido")
    spans = []
    for k, v in hdr.items():
        if not isinstance(v, dict) or set(v) != {"dtype", "shape", "data_offsets"} or v["dtype"] not in DTYPES:
            raise AdapterRefusal("adapter_tensor", "tensor %s" % k[:80])
        sh, off = v["shape"], v["data_offsets"]
        if not (isinstance(sh, list) and len(sh) == 2 and all(_int(x) and x > 0 for x in sh) and isinstance(
                off, list) and len(off) == 2 and all(_int(x) and x >= 0 for x in off)):
            raise AdapterRefusal("adapter_tensor", "tensor %s" % k[:80])
        if (off[1] - off[0]) != sh[0] * sh[1] * DTYPES[v["dtype"]]:
            raise AdapterRefusal("adapter_tensor", "tensor %s: its bytes do not match its shape" % k[:80])
        spans.append(tuple(off))
    spans.sort()
    if not spans or spans[0][0] != 0 or spans[-1][1] != size - 8 - n or any(a[1] != b[0] for a, b in zip(
            spans, spans[1:])):
        raise AdapterRefusal("adapter_layout", "the tensors do not exactly fill the file")
    return hdr, meta, size
def check(path, plan_version, split, receipt, lin, layers):
    """Everything the scorer needs to trust about an adapter before attaching it. lin: the base model's Linear
    modules by name (model.layers.N.mlp.down_proj ...); layers: how many. Returns (sha256, lora, info)."""
    hdr, meta, size = read(path)
    try:
        nx = json.loads(meta["nexido"], parse_constant=_no_constant)
    except (ValueError, RecursionError):
        raise AdapterRefusal("adapter_metadata", "nexido is not JSON")
    want = {"kind", "base_model", "lora", "plan_version", "split", "trained_on", "input"}
    if not isinstance(nx, dict) or set(nx) != want:
        raise AdapterRefusal("adapter_metadata", "nexido must hold exactly %s" % ", ".join(sorted(want)))
    if nx["kind"] != KIND:
        raise AdapterRefusal("adapter_kind", repr(nx["kind"])[:60])
    if nx["base_model"] != {"repo": REPO, "revision": REV}:
        raise AdapterRefusal("adapter_base_model", "trained on another model")
    if not _int(nx["plan_version"]) or nx["plan_version"] != plan_version:
        raise AdapterRefusal("adapter_plan_version", repr(nx["plan_version"])[:30])
    if nx["trained_on"] != "train":
        raise AdapterRefusal("adapter_not_trained_on_train", repr(nx["trained_on"])[:30])
    if not isinstance(nx["split"], dict) or set(nx["split"]) != set(SPLIT_KEYS) or any(
            nx["split"][k] != split.get(k) or type(nx["split"][k]) is not type(split.get(k)) for k in SPLIT_KEYS):
        raise AdapterRefusal("adapter_split_mismatch", "the adapter was trained on another split")
    if nx["input"] != {"file_sha256": receipt["file_sha256"], "row_tokens_sha256": receipt["row_tokens_sha256"]}:
        raise AdapterRefusal("adapter_input_mismatch", "the adapter was trained on another file")
    lo = nx["lora"]
    if not isinstance(lo, dict) or set(lo) != {"r", "lora_alpha", "target_modules"}:
        raise AdapterRefusal("adapter_lora", "lora must hold exactly r, lora_alpha, target_modules")
    r, alpha, tm = lo["r"], lo["lora_alpha"], lo["target_modules"]
    if not (_int(r) and 1 <= r <= 256):
        raise AdapterRefusal("adapter_lora", "r %r" % (r,))
    if not ((_int(alpha) or type(alpha) is float) and 0 < alpha <= 4096 and alpha == alpha):
        raise AdapterRefusal("adapter_lora", "lora_alpha %r" % (alpha,))
    if not (isinstance(tm, list) and tm and all(isinstance(x, str) and x in T for x in tm) and len(set(tm)) == len(
            tm) and tm == sorted(tm)):
        raise AdapterRefusal("adapter_lora", "target_modules must be a sorted list of distinct projections")
    want_keys = set()
    for i in range(layers):
        for t in tm:
            for ab in "AB":
                part = "self_attn" if t in T[:4] else "mlp"
                want_keys.add("base_model.model.model.layers.%d.%s.%s.lora_%s.weight" % (i, part, t, ab))
    if set(hdr) != want_keys:
        raise AdapterRefusal("adapter_tensors", "%d tensors, not the %d of r=%d on %s in %d layers" % (
            len(hdr), len(want_keys), r, ",".join(tm), layers))
    params, dts = 0, {}
    for k, v in hdr.items():
        m = KEY.match(k)
        mod = lin.get(m.group(1))
        if mod is None:
            raise AdapterRefusal("adapter_tensor", "no such projection: %s" % k[:80])
        want = [r, mod.in_features] if m.group(4) == "A" else [mod.out_features, r]
        if v["shape"] != want:
            raise AdapterRefusal("adapter_shape", "%s is %r, not %r" % (k[:80], v["shape"], want))
        params += v["shape"][0] * v["shape"][1]
        dts[v["dtype"]] = dts.get(v["dtype"], 0) + 1
    h = hashlib.sha256()
    with io.open(path, "rb") as f:
        for b in iter(lambda: f.read(8 << 20), b""):
            h.update(b)
    return h.hexdigest(), {"r": r, "lora_alpha": alpha, "target_modules": tm}, {
        "tensors": len(hdr), "parameters": params, "dtypes": dts, "bytes": size}
def write(path, tensors, r, lora_alpha, target_modules, plan_version, split, receipt):
    """For the trainer and the tests: an adapter file in exactly the form check() accepts, and the same bytes for
    the same tensors. Written here, not by safetensors' own writer: that one orders the metadata's two keys at
    random, so the same adapter could have two SHA-256s, and its SHA-256 is its pin (measured, block 123). Written
    under a temporary name, synced, read back by read(), and only then renamed."""
    import torch
    nx = {"kind": KIND, "base_model": {"repo": REPO, "revision": REV},
          "lora": {"r": r, "lora_alpha": lora_alpha, "target_modules": sorted(target_modules)},
          "plan_version": plan_version, "split": dict((k, split[k]) for k in SPLIT_KEYS), "trained_on": "train",
          "input": {"file_sha256": receipt["file_sha256"], "row_tokens_sha256": receipt["row_tokens_sha256"]}}
    hdr, off, data = {"__metadata__": {"format": "pt", "nexido": json.dumps(nx, sort_keys=True, separators=(
        ",", ":"))}}, 0, []
    for k in sorted(tensors):
        v = tensors[k].detach().cpu().resolve_conj().resolve_neg().contiguous()
        if k == "__metadata__" or v.dtype not in (torch.float32, torch.bfloat16):
            raise ValueError("%s: an adapter holds F32 or BF16 tensors only, none named __metadata__" % k[:80])
        dt = "F32" if v.dtype == torch.float32 else "BF16"
        b = (v.view(torch.int16).numpy().astype("<i2") if dt == "BF16" else v.numpy().astype("<f4")).tobytes()
        hdr[k] = {"dtype": dt, "shape": list(v.shape), "data_offsets": [off, off + len(b)]}
        off += len(b)
        data.append(b)
    h = json.dumps(hdr, sort_keys=True, separators=(",", ":")).encode("utf-8")
    h += b" " * (-len(h) % 8)
    with io.open(path + ".part", "wb") as f:
        f.write(struct.pack("<Q", len(h)) + h)
        for b in data:
            f.write(b)
        f.flush()
        os.fsync(f.fileno())
    try:
        read(path + ".part")
    except AdapterRefusal:
        os.remove(path + ".part")
        raise
    os.replace(path + ".part", path)
