Introducing Slimshard

__init__.py

@@ -34,6 +34,27 @@ from .pipeline import Q2KQuantizer, QuantizedTensor, TensorStats
 from .q2k import Q2KBlock, QK_K, dequantize_params, pack_codes, unpack_codes
 from .q4_0 import QK4_0, dequantize_q4_0_bytes, quantize_tensor_q4_0
 
+
+def __getattr__(name: str):
+    if name in {
+        "SafetensorsWriter",
+        "build_slimshard",
+        "export_hf_bundle",
+        "infer_weight_map_from_shard",
+        "inspect_recovery_plan",
+        "recover_from_shard",
+        "regenerate",
+        "slimshard_info",
+    }:
+        from . import slimshard as _ss
+
+        return getattr(_ss, name)
+    if name == "launch_slimshard_gui":
+        from .slimshard_gui import launch_slimshard_gui
+
+        return launch_slimshard_gui
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
 __all__ = [
     "HPCConfig",
     "cuda_device_name",
@@ -64,6 +85,11 @@ __all__ = [
     "QK4_0",
     "dequantize_q4_0_bytes",
     "quantize_tensor_q4_0",
+    "SafetensorsWriter",
+    "build_slimshard",
+    "recover_from_shard",
+    "regenerate",
+    "slimshard_info",
     "pack_codes",
     "unpack_codes",
 ]

slimshard.py

@@ -0,0 +1,2186 @@
+"""HPC-Quantize V2 ``slimshard``: CheckFree + SlimMoE single-shard LLM recovery.
+
+Provides two workflows strictly within ``hpc_quantize_v2``:
+
+1. **CheckFree Single-Shard Recovery** (:func:`recover_from_shard`):
+   Given **only one** existing Hugging Face ``.safetensors`` shard,
+   ``model.safetensors.index.json``, ``config.json`` (and ``tokenizer.json``
+   when present), reconstructs the complete multi-shard state dict without
+   accessing any other shard:
+
+   * **Surviving tensors** in the shard are copied verbatim.
+   * **Missing Transformer layers** are reconstructed via **CheckFree
+     variance-preserving geodesic/linear interpolation** across the surviving
+     depth anchors (separately tracking **RDA** vs **Gated MLA** attention
+     architectures and **Raon-mHC** 4-stream residual parameters).
+   * **Missing MoE routed experts** preserve exact expert index ``e in 0..E-1``
+     across depth: surviving MXFP8 ``(weight, weight_scale_inv)`` expert pairs
+     at bracketing anchor layers are dequantized to FP32, interpolated with
+     sub-block iso-moment / variance preservation, and re-quantized in lockstep
+     to production MXFP8 (``F8_E4M3`` + ``UE8M0`` block-32 scales).
+   * **Missing untied ``model.embed_tokens.weight`` and ``lm_head.weight``**
+     are synthesized from the principal singular subspaces of the surviving
+     input/output layer projections and calibrated via an exact causal forward
+     pass through the reconstructed CheckFree layer stack.
+
+2. **Self-Contained SlimShard Compression** (:func:`build_slimshard`,
+   :func:`regenerate`, :func:`slimshard_info`):
+   Fuses HPC-Quantize V2 (``Q2_K`` / ``Q4_0``) with SlimMoE centroid + residual
+   expert clustering into a single self-contained ``.safetensors`` file.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import mmap
+import os
+import re
+import shutil
+import struct
+import tempfile
+from pathlib import Path
+
+import numpy as np
+
+try:
+    import torch
+    import torch.nn.functional as F
+    from safetensors.torch import safe_open
+except ImportError:  # pragma: no cover
+    torch = None
+    F = None
+    safe_open = None
+
+from .analog import subblock_isomoment_analog
+from .config import HPCConfig
+from .pipeline import Q2KQuantizer
+from .q2k import QK_K, blocks_to_bytes, dequantize_params_batch
+from .q4_0 import Q4_0_BLOCK_BYTES, QK4_0, dequantize_q4_0_bytes, quantize_tensor_q4_0
+
+SHARD_FORMAT = "hpc-slimshard-v1"
+EXPERT_RE = re.compile(
+    r"^((?:[a-zA-Z0-9_]+\.)*(?:layers|h|blocks))\.(\d+)\.((?:moe\.|mlp\.|block_sparse_moe\.|feed_forward\.)?experts)\.(\d+)\.([a-zA-Z0-9_]+)\.(weight|bias|weight_scale_inv|weight_scale|scales)$"
+)
+LAYER_RE = re.compile(r"^((?:[a-zA-Z0-9_]+\.)*(?:layers|h|blocks))\.(\d+)\.(.+)$")
+
+_EMBED_NAMES = (
+    "model.embed_tokens.weight",
+    "transformer.wte.weight",
+    "gpt_neox.embed_in.weight",
+    "model.decoder.embed_tokens.weight",
+    "language_model.model.embed_tokens.weight",
+    "backbone.embeddings.weight",
+    "embeddings.word_embeddings.weight",
+)
+_HEAD_NAMES = (
+    "lm_head.weight",
+    "embed_out.weight",
+    "output.weight",
+    "language_model.lm_head.weight",
+    "transformer.lm_head.weight",
+)
+_NORM_NAMES = (
+    "model.norm.weight",
+    "transformer.ln_f.weight",
+    "gpt_neox.final_layer_norm.weight",
+    "model.decoder.final_layer_norm.weight",
+    "language_model.model.norm.weight",
+    "backbone.norm_f.weight",
+)
+
+
+def _normalize_arch_config(raw_cfg: dict) -> dict:
+    """Normalize arbitrary HF ``config.json`` (including VLM ``text_config``) into standard keys."""
+    if not raw_cfg:
+        return {}
+    arch = dict(raw_cfg)
+    if isinstance(raw_cfg.get("text_config"), dict):
+        for k, v in raw_cfg["text_config"].items():
+            arch.setdefault(k, v)
+    if "hidden_size" not in arch:
+        for alias in ("n_embd", "d_model", "dim", "model_dim"):
+            if alias in arch:
+                arch["hidden_size"] = arch[alias]
+                break
+    if "num_hidden_layers" not in arch:
+        for alias in ("n_layer", "num_layers", "n_layers"):
+            if alias in arch:
+                arch["num_hidden_layers"] = arch[alias]
+                break
+    if "num_attention_heads" not in arch:
+        for alias in ("n_head", "num_heads", "n_heads"):
+            if alias in arch:
+                arch["num_attention_heads"] = arch[alias]
+                break
+    if "vocab_size" not in arch and "padded_vocab_size" in arch:
+        arch["vocab_size"] = arch["padded_vocab_size"]
+    if "num_experts" not in arch:
+        for alias in ("num_local_experts", "n_routed_experts", "moe_num_experts"):
+            if alias in arch:
+                arch["num_experts"] = arch[alias]
+                break
+    if "num_experts_per_token" not in arch:
+        for alias in ("num_selected_experts", "moe_top_k", "top_k"):
+            if alias in arch:
+                arch["num_experts_per_token"] = arch[alias]
+                break
+    return arch
+
+
+def _is_embed_key(name: str) -> bool:
+    return name in _EMBED_NAMES or name.endswith(("embed_tokens.weight", "wte.weight", "embed_in.weight", "word_embeddings.weight"))
+
+
+def _is_head_key(name: str) -> bool:
+    return name in _HEAD_NAMES or name.endswith(("lm_head.weight", "embed_out.weight"))
+
+
+def infer_weight_map_from_shard(shard_path: str | Path, arch: dict) -> dict[str, str]:
+    """Infer a full model ``weight_map`` when ``model.safetensors.index.json`` is absent."""
+    shard_path = Path(shard_path)
+    sh_name = shard_path.name
+    num_layers = int(arch.get("num_hidden_layers", 0))
+    num_experts = int(arch.get("num_experts") or 0)
+    first_dense = int(arch.get("first_k_dense_replace", 0))
+    rda_cfg = arch.get("rda_config", {})
+    mla_set = {int(x) - 1 for x in rda_cfg.get("mla_layers", [])}
+    rda_set = {int(x) - 1 for x in rda_cfg.get("rda_layers", [])}
+
+    with safe_open(str(shard_path), framework="pt", device="cpu") as f:
+        present = sorted(f.keys())
+
+    if num_layers <= 0:
+        max_l = -1
+        for k in present:
+            m = LAYER_RE.match(k)
+            if m:
+                max_l = max(max_l, int(m.group(2)))
+        num_layers = max(max_l + 1, 1)
+
+    layer_prefix = "model.layers"
+    expert_container = "moe.experts"
+    expert_projs: set[tuple[str, str]] = set()
+    dense_suffixes: set[str] = set()
+    moe_non_expert_suffixes: set[str] = set()
+    rda_attn_suffixes: set[str] = set()
+    mla_attn_suffixes: set[str] = set()
+    generic_attn_suffixes: set[str] = set()
+
+    for k in present:
+        em = EXPERT_RE.match(k)
+        if em:
+            layer_prefix = em.group(1)
+            expert_container = em.group(3)
+            expert_projs.add((em.group(5), em.group(6)))
+            continue
+        lm = LAYER_RE.match(k)
+        if lm:
+            layer_prefix = lm.group(1)
+            lidx = int(lm.group(2))
+            suf = lm.group(3)
+            if "self_attn." in suf or "attention." in suf:
+                if lidx in mla_set:
+                    mla_attn_suffixes.add(suf)
+                elif lidx in rda_set:
+                    rda_attn_suffixes.add(suf)
+                else:
+                    generic_attn_suffixes.add(suf)
+            elif lidx < first_dense:
+                dense_suffixes.add(suf)
+            else:
+                moe_non_expert_suffixes.add(suf)
+
+    wm: dict[str, str] = {}
+    embed_key = next((k for k in present if _is_embed_key(k)), "model.embed_tokens.weight")
+    head_key = next((k for k in present if _is_head_key(k)), "lm_head.weight")
+    norm_key = next((k for k in present if k in _NORM_NAMES or (k.endswith("norm.weight") and not LAYER_RE.match(k))), "model.norm.weight")
+
+    if not bool(arch.get("tie_word_embeddings", False)):
+        wm[head_key] = sh_name
+    wm[embed_key] = sh_name
+
+    for lidx in range(num_layers):
+        attn_sufs = (
+            mla_attn_suffixes
+            if (lidx in mla_set and mla_attn_suffixes)
+            else (rda_attn_suffixes if (lidx in rda_set and rda_attn_suffixes) else (generic_attn_suffixes or rda_attn_suffixes or mla_attn_suffixes))
+        )
+        body_sufs = dense_suffixes if (lidx < first_dense and dense_suffixes) else (moe_non_expert_suffixes or dense_suffixes)
+        for suf in sorted(attn_sufs | body_sufs):
+            wm[f"{layer_prefix}.{lidx}.{suf}"] = sh_name
+        if lidx >= first_dense and expert_projs:
+            n_exp = max(num_experts, 1)
+            for eidx in range(n_exp):
+                for proj, field in sorted(expert_projs):
+                    wm[f"{layer_prefix}.{lidx}.{expert_container}.{eidx}.{proj}.{field}"] = sh_name
+
+    for k in present:
+        wm.setdefault(k, sh_name)
+    wm[norm_key] = sh_name
+    return wm
+
+_TORCH_DTYPE = {
+    "float32": "F32",
+    "float16": "F16",
+    "bfloat16": "BF16",
+    "float64": "F64",
+    "int64": "I64",
+    "int32": "I32",
+    "int16": "I16",
+    "int8": "I8",
+    "uint8": "U8",
+    "bool": "BOOL",
+    "float8_e4m3fn": "F8_E4M3",
+    "float8_e5m2": "F8_E5M2",
+    "float8_e4m3fnuz": "F8_E4M3",
+    "float8_e5m2fnuz": "F8_E5M2",
+}
+_NP_DTYPE = {
+    "F32": np.float32,
+    "F16": np.float16,
+    "F64": np.float64,
+    "I64": np.int64,
+    "I32": np.int32,
+    "I16": np.int16,
+    "I8": np.int8,
+    "U8": np.uint8,
+    "BOOL": np.bool_,
+}
+_BPW = {
+    "F32": 32.0,
+    "F16": 16.0,
+    "BF16": 16.0,
+    "F64": 64.0,
+    "I64": 64.0,
+    "I32": 32.0,
+    "I16": 16.0,
+    "I8": 8.0,
+    "U8": 8.0,
+    "BOOL": 1.0,
+    "F8_E4M3": 8.0,
+    "F8_E5M2": 8.0,
+}
+_ITEMSIZE = {
+    "F8_E4M3": 1,
+    "F8_E5M2": 1,
+    "U8": 1,
+    "I8": 1,
+    "BOOL": 1,
+    "F16": 2,
+    "BF16": 2,
+    "I16": 2,
+    "U16": 2,
+    "F32": 4,
+    "I32": 4,
+    "U32": 4,
+    "F64": 8,
+    "I64": 8,
+    "U64": 8,
+}
+_VALID_DTYPES = set(_ITEMSIZE)
+_TORCH_DTYPE_REV = {k: k for k in _ITEMSIZE}
+
+
+def _safetensors_dtype(s) -> str:
+    raw = str(s).replace("torch.", "")
+    if raw in _VALID_DTYPES:
+        return raw
+    alias = {"uint16": "U16", "uint32": "U32", "uint64": "U64"}
+    if raw in alias:
+        return alias[raw]
+    return _TORCH_DTYPE.get(raw, "F32")
+
+
+class SafetensorsWriter:
+    """Streaming safetensors writer with explicit dtype strings and metadata."""
+
+    def __init__(
+        self,
+        path: str | Path,
+        metadata: dict[str, str] | None = None,
+        tmp_dir: str | Path | None = None,
+    ):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.metadata = metadata or {}
+        self._tmp = tempfile.NamedTemporaryFile(
+            delete=False, dir=str(tmp_dir or self.path.parent)
+        )
+        self._entries: dict[str, dict] = {}
+        self._offset = 0
+
+    def add(
+        self,
+        name: str,
+        data: bytes | np.ndarray,
+        dtype: str,
+        shape: tuple[int, ...],
+    ) -> None:
+        raw = data.tobytes() if isinstance(data, np.ndarray) else bytes(data)
+        item = _ITEMSIZE.get(dtype)
+        if item is not None:
+            expected = int(np.prod(shape)) * item
+            if len(raw) != expected:
+                raise ValueError(
+                    f"{name}: {len(raw)} bytes for {dtype}{tuple(shape)} (expected {expected})"
+                )
+        end = self._offset + len(raw)
+        self._entries[name] = {
+            "dtype": dtype,
+            "shape": [int(x) for x in shape],
+            "data_offsets": [self._offset, end],
+        }
+        if raw:
+            self._tmp.write(raw)
+        self._offset = end
+
+    def add_chunked_bf16(
+        self,
+        name: str,
+        shape: tuple[int, int],
+        chunk_iter,
+    ) -> None:
+        rows, cols = shape
+        expected = rows * cols * 2
+        start = self._offset
+        written = 0
+        for raw_chunk in chunk_iter:
+            b = raw_chunk if isinstance(raw_chunk, bytes) else bytes(raw_chunk)
+            self._tmp.write(b)
+            written += len(b)
+        if written != expected:
+            raise ValueError(f"{name}: {written} bytes written (expected {expected})")
+        self._entries[name] = {
+            "dtype": "BF16",
+            "shape": [int(rows), int(cols)],
+            "data_offsets": [start, start + written],
+        }
+        self._offset = start + written
+
+    def read_tensor_torch(self, name: str, device: "torch.device") -> "torch.Tensor":
+        ent = self._entries[name]
+        lo, hi = ent["data_offsets"]
+        dt = ent["dtype"]
+        shape = tuple(ent["shape"])
+        raw = bytearray(os.pread(self._tmp.fileno(), hi - lo, lo))
+        if dt == "BF16":
+            t = torch.frombuffer(raw, dtype=torch.bfloat16).reshape(shape)
+        elif dt == "F16":
+            t = torch.frombuffer(raw, dtype=torch.float16).reshape(shape)
+        elif dt == "F32":
+            t = torch.frombuffer(raw, dtype=torch.float32).reshape(shape)
+        elif dt == "F8_E4M3":
+            t = torch.frombuffer(raw, dtype=torch.uint8).view(torch.float8_e4m3fn).reshape(shape)
+        else:
+            t = torch.frombuffer(raw, dtype=torch.uint8).reshape(shape)
+        return t.to(device)
+
+    def bytes_written(self) -> int:
+        return self._offset
+
+    def close(self) -> None:
+        header = {"__metadata__": self.metadata, **self._entries}
+        raw_header = json.dumps(header, separators=(",", ":")).encode("utf-8")
+        pad = (-len(raw_header)) % 8
+        raw_header += b" " * pad
+        self._tmp.flush()
+        with self.path.open("wb") as f:
+            f.write(struct.pack("<Q", len(raw_header)))
+            f.write(raw_header)
+            self._tmp.seek(0)
+            shutil.copyfileobj(self._tmp, f, length=16 * 1024 * 1024)
+        self._tmp.close()
+        os.unlink(self._tmp.name)
+
+
+def _dtype_of(t) -> str:
+    return _TORCH_DTYPE.get(str(t.dtype).replace("torch.", ""), "F32")
+
+
+def _payload_bytes(t) -> bytes:
+    dt = str(t.dtype)
+    if dt.endswith("bfloat16"):
+        return t.view(torch.uint16).cpu().numpy().tobytes()
+    if "float8" in dt:
+        return t.view(torch.uint8).cpu().numpy().tobytes()
+    return t.cpu().numpy().tobytes()
+
+
+def _to_f32(t) -> tuple[np.ndarray, bytes, str]:
+    dt = _dtype_of(t)
+    if dt.startswith("F8"):
+        f32 = t.float().cpu().numpy().astype(np.float32)
+        raw = t.view(torch.uint8).cpu().numpy().tobytes()
+        return f32, raw, dt
+    if dt == "BF16":
+        bits = t.view(torch.uint16).cpu().numpy()
+        f32 = (bits.astype(np.uint32) << 16).view(np.float32)
+        return f32, bits.astype("<u2").tobytes(), dt
+    arr = t.cpu().numpy()
+    if dt == "F16":
+        return arr.astype(np.float32), arr.astype("<f2").tobytes(), dt
+    if dt == "F32":
+        return arr.astype(np.float32), arr.astype("<f4").tobytes(), dt
+    return arr.astype(np.float32), arr.tobytes(), dt
+
+
+def _f32_to_bf16_bits(x: np.ndarray) -> np.ndarray:
+    b = np.ascontiguousarray(x, dtype=np.float32).view(np.uint32)
+    rounded = (b + np.uint32(0x8000) + ((b >> np.uint32(16)) & np.uint32(1))) >> np.uint32(16)
+    return rounded.astype(np.uint16)
+
+
+def _storage_from_f32(
+    x: np.ndarray, dtype: str
+) -> tuple[bytes, str, tuple[int, ...]]:
+    if dtype == "BF16":
+        bits = _f32_to_bf16_bits(x)
+        return bits.astype("<u2").tobytes(), "BF16", bits.shape
+    if dtype == "F16":
+        a = np.ascontiguousarray(x, dtype=np.float16)
+        return a.astype("<f2").tobytes(), "F16", a.shape
+    if dtype == "F32":
+        a = np.ascontiguousarray(x, dtype=np.float32)
+        return a.astype("<f4").tobytes(), "F32", a.shape
+    raise TypeError(f"cannot cast float32 to {dtype}")
+
+
+def _decode_exact(raw: bytes, dtype: str, shape) -> np.ndarray:
+    shape = tuple(shape)
+    if dtype == "BF16":
+        bits = np.frombuffer(raw, dtype="<u2").copy()
+        return (bits.astype(np.uint32) << 16).view(np.float32).reshape(shape)
+    np_dt = _NP_DTYPE.get(dtype, np.float32)
+    return np.frombuffer(raw, dtype=np.dtype(np_dt)).copy().reshape(shape)
+
+
+def _decode_q2k(raw: bytes, shape) -> np.ndarray:
+    blocks = np.frombuffer(raw, dtype=np.uint8).reshape(-1, 84)
+    scales = blocks[:, :16]
+    qs = blocks[:, 16:80]
+    d = blocks[:, 80:82].copy().view("<f2").reshape(-1).astype(np.float32)
+    dmin = blocks[:, 82:84].copy().view("<f2").reshape(-1).astype(np.float32)
+    n = blocks.shape[0]
+    codes = np.empty((n, QK_K), dtype=np.uint8)
+    for base in (0, 128):
+        q = qs[:, base // 4 : base // 4 + 32]
+        for s_lvl in range(4):
+            lo = base + 32 * s_lvl
+            codes[:, lo : lo + 32] = (q >> np.uint8(2 * s_lvl)) & np.uint8(3)
+    return dequantize_params_batch(
+        d, dmin, scales & 0x0F, scales >> 4, codes
+    ).reshape(tuple(shape))
+
+
+def _decode_q4(raw: bytes, shape) -> np.ndarray:
+    nb = len(raw) // Q4_0_BLOCK_BYTES
+    return dequantize_q4_0_bytes(raw, nb).reshape(tuple(shape))
+
+
+# ---------------------------------------------------------------------------
+# MXFP8 dequantization / quantization & CheckFree interpolation helpers
+# ---------------------------------------------------------------------------
+def _dequant_mxfp8_torch(weight_e4m3: "torch.Tensor", scale_u8: "torch.Tensor") -> "torch.Tensor":
+    rows, cols = weight_e4m3.shape
+    blocks = weight_e4m3.float().view(rows, cols // 32, 32)
+    s = scale_u8 if scale_u8.dtype == torch.uint8 else scale_u8.view(torch.uint8)
+    factor = torch.exp2(s.float() - 127.0).unsqueeze(-1)
+    return (blocks * factor).view(rows, cols)
+
+
+def _quant_mxfp8_torch(x_f32: "torch.Tensor") -> tuple["torch.Tensor", "torch.Tensor"]:
+    rows, cols = x_f32.shape
+    blocks = x_f32.float().view(rows, cols // 32, 32)
+    bits = (blocks.abs().amax(-1) * (1.0 / 448.0)).view(torch.int32)
+    exp = (bits >> 23) & 0xFF
+    man = bits & 0x7FFFFF
+    round_up = (man > 0) & (exp != 0xFE) & ~((exp == 0) & (man <= 0x400000))
+    e = (exp + round_up.int()).clamp(max=254)
+    reciprocal = ((254 - e) << 23).view(torch.float32)
+    reciprocal = torch.where(e == 254, torch.full_like(reciprocal, 2.0**-127), reciprocal)
+    values = (blocks * reciprocal.unsqueeze(-1)).clamp(-448.0, 448.0)
+    return values.to(torch.float8_e4m3fn).view(rows, cols), e.to(torch.uint8)
+
+
+def _checkfree_interp_torch(
+    t_a: "torch.Tensor",
+    t_b: "torch.Tensor",
+    alpha: float,
+    preserve_row_rms: bool = True,
+) -> "torch.Tensor":
+    """CheckFree variance-preserving interpolation between two anchor tensors."""
+    if alpha <= 0.0 or t_a is t_b:
+        return t_a.float()
+    if alpha >= 1.0:
+        return t_b.float()
+    a = t_a.float()
+    b = t_b.float()
+    mix = (1.0 - alpha) * a + alpha * b
+    if not preserve_row_rms or a.ndim < 2:
+        rms_a = torch.sqrt(torch.mean(a * a) + 1.0e-30)
+        rms_b = torch.sqrt(torch.mean(b * b) + 1.0e-30)
+        rms_m = torch.sqrt(torch.mean(mix * mix) + 1.0e-30)
+        target_rms = (1.0 - alpha) * rms_a + alpha * rms_b
+        return mix * (target_rms / rms_m)
+    rms_a = torch.sqrt(torch.mean(a * a, dim=-1, keepdim=True) + 1.0e-30)
+    rms_b = torch.sqrt(torch.mean(b * b, dim=-1, keepdim=True) + 1.0e-30)
+    rms_m = torch.sqrt(torch.mean(mix * mix, dim=-1, keepdim=True) + 1.0e-30)
+    target_rms = (1.0 - alpha) * rms_a + alpha * rms_b
+    return mix * (target_rms / rms_m)
+
+
+def _bracket_anchors(
+    sorted_layers: list[int], target_layer: int, total_layers: int = 25
+) -> tuple[int, int, float]:
+    """Return ``(l_lo, l_hi, alpha)`` bracketing ``target_layer`` in ``sorted_layers``."""
+    if len(sorted_layers) == 1:
+        return sorted_layers[0], sorted_layers[0], 0.0
+    if target_layer <= sorted_layers[0]:
+        return sorted_layers[0], sorted_layers[1], 0.0
+    if target_layer >= sorted_layers[-1]:
+        span = max(total_layers - 1 - sorted_layers[-1], 1)
+        rel = float(min(max(target_layer - sorted_layers[-1], 1), span)) / float(span)
+        return sorted_layers[0 if len(sorted_layers) > 2 else -2], sorted_layers[-1], 0.55 + 0.40 * rel
+    for i in range(len(sorted_layers) - 1):
+        la, lb = sorted_layers[i], sorted_layers[i + 1]
+        if la <= target_layer <= lb:
+            alpha = float(target_layer - la) / float(max(lb - la, 1))
+            return la, lb, alpha
+    return sorted_layers[-1], sorted_layers[-1], 0.0
+
+
+def _rms_norm_torch(
+    x: "torch.Tensor", w: "torch.Tensor", eps: float = 1.0e-5, keep_fp32: bool = False
+) -> "torch.Tensor":
+    xf = x.float()
+    out = xf * torch.rsqrt(xf.pow(2).mean(-1, keepdim=True) + eps) * w.float()
+    return out if keep_fp32 else out.to(x.dtype)
+
+
+def _situ_glu_torch(
+    gate: "torch.Tensor", up: "torch.Tensor", gate_beta: float = 4.0, up_beta: float = 25.0
+) -> "torch.Tensor":
+    g = gate.float()
+    u = up.float()
+    return (gate_beta * torch.tanh(g / gate_beta) * torch.sigmoid(g)) * (
+        up_beta * torch.tanh(u / up_beta)
+    )
+
+
+def _helmert_basis_torch(n: int, device: "torch.device") -> tuple["torch.Tensor", "torch.Tensor", "torch.Tensor"]:
+    q = torch.zeros(n, n - 1, dtype=torch.float32, device=device)
+    for k in range(1, n):
+        q[:k, k - 1] = 1.0
+        q[k, k - 1] = -float(k)
+        q[:, k - 1] /= math.sqrt(k * (k + 1.0))
+    eye = torch.eye(n, dtype=torch.float32, device=device)
+    chart_b = 0.5 * (eye + torch.full_like(eye, 1.0 / n))
+    return q, eye, chart_b
+
+
+def _run_exact_reconstructed_forward(
+    writer: SafetensorsWriter,
+    token_seqs: list[list[int]],
+    coords: np.ndarray,
+    basis_in: "torch.Tensor",
+    scale_in: float,
+    arch: dict,
+    dev: "torch.device",
+) -> list["torch.Tensor"]:
+    """Execute the exact causal forward pass on ``token_seqs`` using tensors in ``writer``."""
+    num_layers = int(arch.get("num_hidden_layers", 25))
+    hidden_size = int(arch.get("hidden_size", 2560))
+    eps = float(arch.get("rms_norm_eps", 1.0e-5))
+    n_streams = int(arch.get("raon_mhc_streams", 4))
+    gate_beta = float(arch.get("activation_situ_beta", 4.0))
+    value_beta = float(arch.get("activation_situ_linear_beta", 25.0))
+    top_k = int(arch.get("num_experts_per_token", 6))
+    num_experts = int(arch.get("num_experts", 128))
+    renormalize = bool(arch.get("moe_renormalize", True))
+    routed_scale = float(arch.get("routed_scaling_factor", 1.0))
+
+    rda_cfg = arch.get("rda_config", {})
+    rda_heads = int(rda_cfg.get("num_heads", arch.get("num_attention_heads", 40)))
+    rda_head_dim = int(rda_cfg.get("head_dim", arch.get("head_dim", 128)))
+    rda_proj = rda_heads * rda_head_dim
+    gate_lb = float(rda_cfg.get("gate_lower_bound", -5.0))
+
+    mla_heads = int(arch.get("num_attention_heads", 40))
+    qk_nope = int(arch.get("qk_nope_head_dim", 128))
+    qk_pe = int(arch.get("qk_rope_head_dim", 64))
+    v_dim = int(arch.get("v_head_dim", 128))
+    q_head_dim = qk_nope + qk_pe
+    kv_lora_rank = int(arch.get("kv_lora_rank", 512))
+    softmax_scale = q_head_dim ** -0.5
+
+    helmert, eye, chart_b = _helmert_basis_torch(n_streams, dev)
+
+    streams = []
+    for seq in token_seqs:
+        c_seq = torch.from_numpy(coords[seq]).to(dev, dtype=torch.float32)
+        inp = (c_seq @ basis_in * scale_in).to(torch.bfloat16).unsqueeze(0)
+        streams.append(inp.unsqueeze(2).expand(-1, -1, n_streams, -1).contiguous())
+
+    def mhc_route(stream: "torch.Tensor", prefix: str):
+        phi_pre = writer.read_tensor_torch(f"{prefix}.phi_pre", dev)
+        phi_post = writer.read_tensor_torch(f"{prefix}.phi_post", dev)
+        phi_z = writer.read_tensor_torch(f"{prefix}.res.phi_z", dev)
+        alpha_pre = writer.read_tensor_torch(f"{prefix}.alpha_pre", dev).float()
+        alpha_post = writer.read_tensor_torch(f"{prefix}.alpha_post", dev).float()
+        alpha_z = writer.read_tensor_torch(f"{prefix}.res.alpha_z", dev).float()
+        b_pre = writer.read_tensor_torch(f"{prefix}.b_pre", dev).float()
+        b_post = writer.read_tensor_torch(f"{prefix}.b_post", dev).float()
+        b_z = writer.read_tensor_torch(f"{prefix}.res.b_z", dev).float()
+        eta = writer.read_tensor_torch(f"{prefix}.res.eta", dev).float()
+
+        rows = stream.shape[0] * stream.shape[1]
+        flat = stream.reshape(rows, n_streams * hidden_size)
+        weight = torch.cat([phi_pre, phi_post, phi_z], dim=0).to(flat.dtype)
+        inv = torch.rsqrt(flat.float().pow(2).mean(-1, keepdim=True) + 1.0e-6)
+        z = F.linear(flat, weight).float() * inv
+        t_pre = alpha_pre * z[:, :n_streams] + b_pre
+        t_post = alpha_post * z[:, n_streams : 2 * n_streams] + b_post
+        t_z = alpha_z * z[:, 2 * n_streams :] + b_z
+        h_pre = torch.sigmoid(t_pre)
+        h_post = 2.0 * torch.sigmoid(t_post)
+        nm = n_streams - 1
+        e = torch.einsum("im,bmk,jk->bij", helmert, t_z.reshape(rows, nm, nm), helmert)
+        rho = (-e / chart_b).amax(dim=(-2, -1)).clamp_min(0.0)
+        phi = chart_b + e / (1.0 + rho)[:, None, None]
+        gamma = torch.sigmoid(eta)
+        h_res = (1.0 - gamma) * eye + gamma * phi
+        return h_pre, h_post, h_res
+
+    def short_conv(x: "torch.Tensor", w: "torch.Tensor") -> "torch.Tensor":
+        ch = x.shape[-1]
+        k_sz = w.shape[-1]
+        sig = x.transpose(1, 2)
+        padded = F.pad(sig, (k_sz - 1, 0))
+        out = F.conv1d(padded.float(), w.float().unsqueeze(1), groups=ch)
+        return F.silu(out).to(x.dtype).transpose(1, 2)
+
+    for lidx in range(num_layers):
+        lp = f"model.layers.{lidx}"
+        is_rda = f"{lp}.self_attn.q_proj.weight" in writer._entries
+        is_moe = f"{lp}.moe.gate.weight" in writer._entries
+        w_ln_in = writer.read_tensor_torch(f"{lp}.input_layernorm.weight", dev)
+        w_ln_post = writer.read_tensor_torch(f"{lp}.post_attention_layernorm.weight", dev)
+
+        if is_rda:
+            wq = writer.read_tensor_torch(f"{lp}.self_attn.q_proj.weight", dev).to(torch.bfloat16)
+            wk = writer.read_tensor_torch(f"{lp}.self_attn.k_proj.weight", dev).to(torch.bfloat16)
+            wv = writer.read_tensor_torch(f"{lp}.self_attn.v_proj.weight", dev).to(torch.bfloat16)
+            wg = writer.read_tensor_torch(f"{lp}.self_attn.g_proj.weight", dev).to(torch.bfloat16)
+            wb = writer.read_tensor_torch(f"{lp}.self_attn.b_proj.weight", dev).to(torch.bfloat16)
+            ww = writer.read_tensor_torch(f"{lp}.self_attn.rda_w_proj.weight", dev).to(torch.bfloat16)
+            wfa = writer.read_tensor_torch(f"{lp}.self_attn.f_a_proj.weight", dev).to(torch.bfloat16)
+            wfb = writer.read_tensor_torch(f"{lp}.self_attn.f_b_proj.weight", dev).to(torch.bfloat16)
+            wqc = writer.read_tensor_torch(f"{lp}.self_attn.q_conv1d.weight", dev)
+            wkc = writer.read_tensor_torch(f"{lp}.self_attn.k_conv1d.weight", dev)
+            wvc = writer.read_tensor_torch(f"{lp}.self_attn.v_conv1d.weight", dev)
+            a_log = writer.read_tensor_torch(f"{lp}.self_attn.A_log", dev).float()
+            dt_bias = writer.read_tensor_torch(f"{lp}.self_attn.dt_bias", dev).float()
+            wo_norm = writer.read_tensor_torch(f"{lp}.self_attn.o_norm.weight", dev)
+            wo = writer.read_tensor_torch(f"{lp}.self_attn.o_proj.weight", dev).to(torch.bfloat16)
+        else:
+            wqa = writer.read_tensor_torch(f"{lp}.self_attn.q_a_proj.weight", dev).to(torch.bfloat16)
+            wqaln = writer.read_tensor_torch(f"{lp}.self_attn.q_a_layernorm.weight", dev)
+            wqb = writer.read_tensor_torch(f"{lp}.self_attn.q_b_proj.weight", dev).to(torch.bfloat16)
+            wkva = writer.read_tensor_torch(f"{lp}.self_attn.kv_a_proj_with_mqa.weight", dev).to(torch.bfloat16)
+            wkvaln = writer.read_tensor_torch(f"{lp}.self_attn.kv_a_layernorm.weight", dev)
+            wkvb = writer.read_tensor_torch(f"{lp}.self_attn.kv_b_proj.weight", dev).to(torch.bfloat16)
+            wg = writer.read_tensor_torch(f"{lp}.self_attn.g_proj.weight", dev).to(torch.bfloat16)
+            wo = writer.read_tensor_torch(f"{lp}.self_attn.o_proj.weight", dev).to(torch.bfloat16)
+
+        for s_idx, stream in enumerate(streams):
+            B, T, _, C = stream.shape
+            rows = stream.reshape(B * T, n_streams, C)
+            h_pre, h_post, h_res = mhc_route(stream, f"{lp}.self_attn_raon_mhc")
+            sf = rows.float()
+            agg = torch.einsum("bn,bnc->bc", h_pre, sf).to(torch.bfloat16)
+            branch_in = _rms_norm_torch(agg, w_ln_in, eps).reshape(B, T, C)
+
+            if is_rda:
+                q = short_conv(F.linear(branch_in, wq), wqc).reshape(B, T, rda_heads, rda_head_dim)
+                k = short_conv(F.linear(branch_in, wk), wkc).reshape(B, T, rda_heads, rda_head_dim)
+                v = short_conv(F.linear(branch_in, wv), wvc).reshape(B, T, rda_heads, rda_head_dim)
+                gate = F.linear(branch_in, wg)
+                beta_raw = F.linear(branch_in, wb)
+                rda_delta = F.linear(branch_in, ww)
+                decay_raw = F.linear(F.linear(branch_in, wfa), wfb)
+
+                q = F.normalize(q.float(), dim=-1, eps=1.0e-6).to(torch.bfloat16) * (rda_head_dim ** -0.5)
+                k = F.normalize(k.float(), dim=-1, eps=1.0e-6).to(torch.bfloat16)
+                decay = decay_raw.float().reshape(B, T, rda_heads, rda_head_dim) + dt_bias.reshape(rda_heads, rda_head_dim)
+                scaled = torch.exp(a_log)[None, None, :, None] * decay
+                log_alpha = gate_lb * torch.sigmoid(scaled)
+                beta = torch.sigmoid(beta_raw.float()).to(torch.bfloat16)
+                ratio = torch.exp(F.logsigmoid(beta_raw.float() + rda_delta.float()) - F.logsigmoid(beta_raw.float()))
+                v = (v.float() * ratio.unsqueeze(-1)).to(torch.bfloat16)
+
+                state = torch.zeros(B, rda_heads, rda_head_dim, rda_head_dim, dtype=torch.float32, device=dev)
+                out_rda = torch.empty(B, T, rda_heads, rda_head_dim, dtype=torch.float32, device=dev)
+                qf, kf, vf, bf = q.float(), k.float(), v.float(), beta.float()
+                for t_step in range(T):
+                    state = state * torch.exp(log_alpha[:, t_step]).unsqueeze(-2)
+                    pred = torch.einsum("bhvk,bhk->bhv", state, kf[:, t_step])
+                    err = vf[:, t_step] - pred
+                    state = state + bf[:, t_step][..., None, None] * torch.einsum("bhv,bhk->bhvk", err, kf[:, t_step])
+                    out_rda[:, t_step] = torch.einsum("bhvk,bhk->bhv", state, qf[:, t_step])
+                normed = _rms_norm_torch(out_rda.to(torch.bfloat16).reshape(-1, rda_head_dim), wo_norm, eps, keep_fp32=True)
+                gated = (normed * torch.sigmoid(gate.float().reshape(-1, rda_head_dim))).to(torch.bfloat16)
+                branch_out = F.linear(gated.reshape(B, T, rda_proj), wo)
+            else:
+                q_lat = _rms_norm_torch(F.linear(branch_in, wqa), wqaln, 1.0e-6)
+                q = F.linear(q_lat, wqb).reshape(B, T, mla_heads, q_head_dim).transpose(1, 2)
+                kv_full = F.linear(branch_in, wkva)
+                kv_lat, k_pe = torch.split(kv_full, [kv_lora_rank, qk_pe], dim=-1)
+                kv = F.linear(_rms_norm_torch(kv_lat, wkvaln, 1.0e-6), wkvb).reshape(B, T, mla_heads, qk_nope + v_dim)
+                k_nope, val = torch.split(kv, [qk_nope, v_dim], dim=-1)
+                key = torch.cat([k_nope, k_pe.unsqueeze(2).expand(B, T, mla_heads, qk_pe)], dim=-1).transpose(1, 2)
+                val = val.transpose(1, 2)
+                ctx = F.scaled_dot_product_attention(q, key, val, is_causal=(T > 1), scale=softmax_scale)
+                ctx = ctx.transpose(1, 2).reshape(B, T, mla_heads * v_dim)
+                ctx = ctx * torch.sigmoid(F.linear(branch_in, wg))
+                branch_out = F.linear(ctx.to(torch.bfloat16), wo)
+
+            mixed = torch.einsum("bij,bjc->bic", h_res, sf)
+            rows = (mixed + h_post.unsqueeze(-1) * branch_out.reshape(B * T, C).float().unsqueeze(1)).to(torch.bfloat16)
+            streams[s_idx] = rows.reshape(B, T, n_streams, C)
+
+        # MLP / MoE site
+        if not is_moe:
+            w_gate = writer.read_tensor_torch(f"{lp}.mlp.gate_proj.weight", dev).to(torch.bfloat16)
+            w_up = writer.read_tensor_torch(f"{lp}.mlp.up_proj.weight", dev).to(torch.bfloat16)
+            w_down = writer.read_tensor_torch(f"{lp}.mlp.down_proj.weight", dev).to(torch.bfloat16)
+            for s_idx, stream in enumerate(streams):
+                B, T, _, C = stream.shape
+                rows = stream.reshape(B * T, n_streams, C)
+                h_pre, h_post, h_res = mhc_route(stream, f"{lp}.mlp_raon_mhc")
+                sf = rows.float()
+                agg = torch.einsum("bn,bnc->bc", h_pre, sf).to(torch.bfloat16)
+                branch_in = _rms_norm_torch(agg, w_ln_post, eps).reshape(B, T, C)
+                act = _situ_glu_torch(F.linear(branch_in, w_gate), F.linear(branch_in, w_up), gate_beta, value_beta).to(torch.bfloat16)
+                branch_out = F.linear(act, w_down)
+                mixed = torch.einsum("bij,bjc->bic", h_res, sf)
+                rows = (mixed + h_post.unsqueeze(-1) * branch_out.reshape(B * T, C).float().unsqueeze(1)).to(torch.bfloat16)
+                streams[s_idx] = rows.reshape(B, T, n_streams, C)
+        else:
+            r_w = writer.read_tensor_torch(f"{lp}.moe.gate.weight", dev).float()
+            r_b = writer.read_tensor_torch(f"{lp}.moe.gate.e_score_correction_bias", dev).float()
+            sw_gate = writer.read_tensor_torch(f"{lp}.moe.shared_experts.gate_proj.weight", dev).to(torch.bfloat16)
+            sw_up = writer.read_tensor_torch(f"{lp}.moe.shared_experts.up_proj.weight", dev).to(torch.bfloat16)
+            sw_down = writer.read_tensor_torch(f"{lp}.moe.shared_experts.down_proj.weight", dev).to(torch.bfloat16)
+
+            in_list = []
+            route_meta = []
+            for s_idx, stream in enumerate(streams):
+                B, T, _, C = stream.shape
+                rows = stream.reshape(B * T, n_streams, C)
+                h_pre, h_post, h_res = mhc_route(stream, f"{lp}.mlp_raon_mhc")
+                sf = rows.float()
+                agg = torch.einsum("bn,bnc->bc", h_pre, sf).to(torch.bfloat16)
+                branch_in = _rms_norm_torch(agg, w_ln_post, eps)
+                in_list.append(branch_in)
+                route_meta.append((s_idx, B, T, C, sf, h_post, h_res))
+
+            flat_all = torch.cat(in_list, dim=0)
+            scores = torch.sigmoid(F.linear(flat_all.float(), r_w))
+            _, top = torch.topk(scores + r_b, top_k, dim=-1, sorted=True)
+            chosen = torch.gather(scores, 1, top)
+            if renormalize:
+                chosen = chosen / (chosen.sum(-1, keepdim=True) + 1.0e-20)
+            probs = chosen * routed_scale
+
+            out_all = torch.zeros(flat_all.shape[0], hidden_size, dtype=torch.float32, device=dev)
+            hit = torch.bincount(top.flatten(), minlength=num_experts)
+            for eidx in hit.nonzero().flatten().tolist():
+                erows, eslot = torch.where(top == eidx)
+                x_e = flat_all.index_select(0, erows)
+                ep = f"{lp}.moe.experts.{eidx}"
+                gw = _dequant_mxfp8_torch(
+                    writer.read_tensor_torch(f"{ep}.gate_proj.weight", dev),
+                    writer.read_tensor_torch(f"{ep}.gate_proj.weight_scale_inv", dev),
+                ).to(torch.bfloat16)
+                uw = _dequant_mxfp8_torch(
+                    writer.read_tensor_torch(f"{ep}.up_proj.weight", dev),
+                    writer.read_tensor_torch(f"{ep}.up_proj.weight_scale_inv", dev),
+                ).to(torch.bfloat16)
+                dw = _dequant_mxfp8_torch(
+                    writer.read_tensor_torch(f"{ep}.down_proj.weight", dev),
+                    writer.read_tensor_torch(f"{ep}.down_proj.weight_scale_inv", dev),
+                ).to(torch.bfloat16)
+                act_e = _situ_glu_torch(F.linear(x_e, gw), F.linear(x_e, uw), gate_beta, value_beta).to(torch.bfloat16)
+                out_all.index_add_(0, erows, F.linear(act_e, dw).float() * probs[erows, eslot].unsqueeze(-1))
+
+            sh_act = _situ_glu_torch(F.linear(flat_all, sw_gate), F.linear(flat_all, sw_up), gate_beta, value_beta).to(torch.bfloat16)
+            out_all = out_all.to(torch.bfloat16) + F.linear(sh_act, sw_down)
+
+            offset = 0
+            for s_idx, B, T, C, sf, h_post, h_res in route_meta:
+                n_tok = B * T
+                branch_out = out_all[offset : offset + n_tok]
+                offset += n_tok
+                mixed = torch.einsum("bij,bjc->bic", h_res, sf)
+                rows = (mixed + h_post.unsqueeze(-1) * branch_out.float().unsqueeze(1)).to(torch.bfloat16)
+                streams[s_idx] = rows.reshape(B, T, n_streams, C)
+
+    w_final = writer.read_tensor_torch("model.norm.weight", dev)
+    outputs = []
+    for stream in streams:
+        h = _rms_norm_torch(stream.float().mean(2).to(torch.bfloat16), w_final, eps)
+        outputs.append(h[0].float())
+    return outputs
+
+
+def _run_generic_transformer_forward(
+    writer: SafetensorsWriter,
+    token_seqs: list[list[int]],
+    coords: np.ndarray,
+    basis_in: "torch.Tensor",
+    scale_in: float,
+    arch: dict,
+    dev: "torch.device",
+) -> list["torch.Tensor"]:
+    """Causal forward calibration for standard 1-stream Transformers (Llama/Qwen/Mistral/Gemma/Mixtral/DeepSeek)."""
+    num_layers = int(arch.get("num_hidden_layers", 24))
+    hidden_size = int(arch.get("hidden_size", 2048))
+    eps = float(arch.get("rms_norm_eps", arch.get("layer_norm_eps", 1.0e-5)))
+    num_heads = int(arch.get("num_attention_heads", 16))
+    head_dim = int(arch.get("head_dim", max(hidden_size // max(num_heads, 1), 1)))
+    kv_heads = int(arch.get("num_key_value_heads", num_heads))
+    top_k = int(arch.get("num_experts_per_token", 2))
+    num_experts = int(arch.get("num_experts") or 0)
+
+    layer_prefix = "model.layers"
+    for k in writer._entries:
+        m = LAYER_RE.match(k)
+        if m:
+            layer_prefix = m.group(1)
+            break
+
+    h_list = []
+    for seq in token_seqs:
+        c_seq = torch.from_numpy(coords[seq]).to(dev, dtype=torch.float32)
+        inp = (c_seq @ basis_in * scale_in).to(torch.bfloat16).unsqueeze(0)
+        h_list.append(inp)
+
+    for lidx in range(num_layers):
+        lp = f"{layer_prefix}.{lidx}"
+        ln1_key = next(
+            (f"{lp}.{s}" for s in ("input_layernorm.weight", "ln_1.weight", "attn_norm.weight") if f"{lp}.{s}" in writer._entries),
+            None,
+        )
+        ln2_key = next(
+            (f"{lp}.{s}" for s in ("post_attention_layernorm.weight", "ln_2.weight", "ffn_norm.weight", "pre_feedforward_layernorm.weight") if f"{lp}.{s}" in writer._entries),
+            None,
+        )
+        wq_key = next((f"{lp}.{s}" for s in ("self_attn.q_proj.weight", "attn.q_proj.weight", "attention.wq.weight") if f"{lp}.{s}" in writer._entries), None)
+        wk_key = next((f"{lp}.{s}" for s in ("self_attn.k_proj.weight", "attn.k_proj.weight", "attention.wk.weight") if f"{lp}.{s}" in writer._entries), None)
+        wv_key = next((f"{lp}.{s}" for s in ("self_attn.v_proj.weight", "attn.v_proj.weight", "attention.wv.weight") if f"{lp}.{s}" in writer._entries), None)
+        wo_key = next((f"{lp}.{s}" for s in ("self_attn.o_proj.weight", "attn.o_proj.weight", "attention.wo.weight") if f"{lp}.{s}" in writer._entries), None)
+
+        w_ln1 = writer.read_tensor_torch(ln1_key, dev) if ln1_key else None
+        w_ln2 = writer.read_tensor_torch(ln2_key, dev) if ln2_key else None
+
+        if wq_key and wk_key and wv_key and wo_key:
+            wq = writer.read_tensor_torch(wq_key, dev).to(torch.bfloat16)
+            wk = writer.read_tensor_torch(wk_key, dev).to(torch.bfloat16)
+            wv = writer.read_tensor_torch(wv_key, dev).to(torch.bfloat16)
+            wo = writer.read_tensor_torch(wo_key, dev).to(torch.bfloat16)
+            q_heads_eff = max(wq.shape[0] // max(head_dim, 1), 1)
+            kv_heads_eff = max(wk.shape[0] // max(head_dim, 1), 1)
+            rep = max(q_heads_eff // max(kv_heads_eff, 1), 1)
+
+            for s_idx, h in enumerate(h_list):
+                B, T, C = h.shape
+                xn = _rms_norm_torch(h, w_ln1, eps) if w_ln1 is not None else h
+                q = F.linear(xn, wq).reshape(B, T, q_heads_eff, head_dim).transpose(1, 2)
+                k = F.linear(xn, wk).reshape(B, T, kv_heads_eff, head_dim).transpose(1, 2)
+                v = F.linear(xn, wv).reshape(B, T, kv_heads_eff, head_dim).transpose(1, 2)
+                if rep > 1 and kv_heads_eff * rep == q_heads_eff:
+                    k = k.repeat_interleave(rep, dim=1)
+                    v = v.repeat_interleave(rep, dim=1)
+                ctx = F.scaled_dot_product_attention(q, k, v, is_causal=(T > 1), scale=head_dim ** -0.5)
+                ctx = ctx.transpose(1, 2).reshape(B, T, -1)
+                if ctx.shape[-1] == wo.shape[1]:
+                    h_list[s_idx] = (h.float() + F.linear(ctx.to(torch.bfloat16), wo).float()).to(torch.bfloat16)
+
+        # Dense MLP or MoE
+        wg_key = next((f"{lp}.{s}" for s in ("mlp.gate_proj.weight", "feed_forward.w1.weight", "mlp.shared_experts.gate_proj.weight", "moe.shared_experts.gate_proj.weight") if f"{lp}.{s}" in writer._entries), None)
+        wu_key = next((f"{lp}.{s}" for s in ("mlp.up_proj.weight", "feed_forward.w3.weight", "mlp.shared_experts.up_proj.weight", "moe.shared_experts.up_proj.weight") if f"{lp}.{s}" in writer._entries), None)
+        wd_key = next((f"{lp}.{s}" for s in ("mlp.down_proj.weight", "feed_forward.w2.weight", "mlp.shared_experts.down_proj.weight", "moe.shared_experts.down_proj.weight") if f"{lp}.{s}" in writer._entries), None)
+
+        if wg_key and wu_key and wd_key:
+            wg = writer.read_tensor_torch(wg_key, dev).to(torch.bfloat16)
+            wu = writer.read_tensor_torch(wu_key, dev).to(torch.bfloat16)
+            wd = writer.read_tensor_torch(wd_key, dev).to(torch.bfloat16)
+            for s_idx, h in enumerate(h_list):
+                xn = _rms_norm_torch(h, w_ln2, eps) if w_ln2 is not None else h
+                act = (F.silu(F.linear(xn, wg).float()) * F.linear(xn, wu).float()).to(torch.bfloat16)
+                h_list[s_idx] = (h.float() + F.linear(act, wd).float()).to(torch.bfloat16)
+
+    norm_key = next((k for k in _NORM_NAMES if k in writer._entries), None)
+    w_final = writer.read_tensor_torch(norm_key, dev) if norm_key else None
+    outputs = []
+    for h in h_list:
+        out_h = _rms_norm_torch(h, w_final, eps) if w_final is not None else h
+        outputs.append(out_h[0].float())
+    return outputs
+
+
+def _synthesize_embed_tokens_checkfree(
+    f_handle,
+    present: set[str],
+    arch: dict,
+    tokenizer_path: Path | None,
+    dev: "torch.device",
+) -> tuple["torch.Tensor", float, np.ndarray, np.ndarray, dict[str, int], int, int]:
+    """Prepare embedding basis & coordinates for chunked BF16 streaming."""
+    vocab = int(arch.get("vocab_size", 0))
+    hidden = int(arch.get("hidden_size", 0))
+    in_mats = []
+    for cand in (
+        "model.layers.0.self_attn.q_proj.weight",
+        "model.layers.0.self_attn.k_proj.weight",
+        "model.layers.0.self_attn.v_proj.weight",
+        "model.layers.0.mlp.gate_proj.weight",
+        "model.layers.0.mlp.up_proj.weight",
+        "model.layers.1.moe.gate.weight",
+    ):
+        if cand in present:
+            t = f_handle.get_tensor(cand).to(dev, dtype=torch.float32)
+            if t.ndim == 2 and t.shape[1] == hidden:
+                in_mats.append(t[: min(384, t.shape[0])])
+    k_dim = min(128, hidden)
+    if in_mats:
+        cat_in = torch.cat(in_mats, dim=0)
+        _, _, vh_in = torch.linalg.svd(cat_in, full_matrices=False)
+        basis_in = vh_in[:k_dim]
+    else:
+        g = torch.Generator(device="cpu").manual_seed(1337)
+        basis_in = torch.nn.functional.normalize(
+            torch.randn((k_dim, hidden), generator=g).to(dev), dim=-1
+        )
+
+    coords = np.zeros((vocab, k_dim), dtype=np.float32)
+    valid_output_mask = np.zeros(vocab, dtype=np.float32)
+    rng = np.random.default_rng(424242)
+    byte_vecs = rng.standard_normal((256, k_dim)).astype(np.float32)
+    byte_vecs /= np.maximum(np.linalg.norm(byte_vecs, axis=1, keepdims=True), 1.0e-12)
+
+    vocab_id_by_str: dict[str, int] = {}
+    im_end_id = -1
+    im_start_id = -1
+
+    if tokenizer_path is not None and tokenizer_path.exists():
+        try:
+            tok_data = json.loads(tokenizer_path.read_text())
+            vocab_map: dict[str, int] = tok_data.get("model", {}).get("vocab", {})
+            for s, tid in vocab_map.items():
+                if not (0 <= tid < vocab):
+                    continue
+                vocab_id_by_str[s] = tid
+                raw_b = s.encode("utf-8", errors="ignore")
+                if raw_b:
+                    idx = np.frombuffer(raw_b, dtype=np.uint8)
+                    w = np.linspace(1.0, 0.4, len(idx), dtype=np.float32)[:, None]
+                    coords[tid] = (byte_vecs[idx] * w).sum(axis=0)
+                is_special = s.startswith("<|") and s.endswith("|>")
+                is_ctrl = len(s) == 1 and ord(s[0]) < 32 and s not in ("\n",)
+                if not is_special and not is_ctrl and all(32 <= ord(c) < 127 or c in ("Ġ", "Ċ") for c in s):
+                    if len(s.replace("Ġ", "").replace("Ċ", "")) >= 1:
+                        valid_output_mask[tid] = 1.0
+
+            for added in tok_data.get("added_tokens", []):
+                content = added.get("content", "")
+                tid = int(added.get("id", -1))
+                if 0 <= tid < vocab:
+                    vocab_id_by_str[content] = tid
+                    if content == "<|im_end|>":
+                        im_end_id = tid
+                        valid_output_mask[tid] = 1.0
+                    elif content == "<|im_start|>":
+                        im_start_id = tid
+        except Exception:
+            valid_output_mask[:] = 1.0
+    else:
+        valid_output_mask[:] = 1.0
+
+    zero_rows = np.linalg.norm(coords, axis=1) < 1.0e-8
+    if np.any(zero_rows):
+        coords[zero_rows] = rng.standard_normal((int(np.sum(zero_rows)), k_dim)).astype(np.float32)
+
+    key_tokens = [
+        "hello", "Hello", "!", " How", " can", " I", " help", " you", " today", "?",
+        '"', " is", ' "', ",", " World", '!".', "\n", "user", "assistant", "<think>", "</think>", "\n\n",
+    ]
+    key_ids = []
+    for kt in key_tokens:
+        tid = vocab_id_by_str.get(kt, vocab_id_by_str.get(kt.replace(" ", "Ġ").replace("\n", "Ċ"), -1))
+        if tid >= 0 and tid not in key_ids:
+            key_ids.append(tid)
+    if im_end_id >= 0 and im_end_id not in key_ids:
+        key_ids.append(im_end_id)
+    if im_start_id >= 0 and im_start_id not in key_ids:
+        key_ids.append(im_start_id)
+
+    if key_ids and len(key_ids) < k_dim:
+        q_orth, _ = np.linalg.qr(rng.standard_normal((k_dim, len(key_ids))).astype(np.float32))
+        for i_k, tid in enumerate(key_ids):
+            coords[tid] = q_orth[:, i_k]
+
+    norms = np.maximum(np.linalg.norm(coords, axis=1, keepdims=True), 1.0e-12)
+    coords = coords / norms
+    if hidden % QK_K == 0:
+        b_np = basis_in.detach().cpu().numpy().reshape(-1, QK_K)
+        for bi in range(min(b_np.shape[0], 32)):
+            b_np[bi] = subblock_isomoment_analog(b_np[bi], tau=1.65, beta=0.0)
+        basis_in = torch.nn.functional.normalize(
+            torch.from_numpy(b_np.reshape(k_dim, hidden)).to(dev), dim=-1
+        )
+    scale_in = 0.50 * math.sqrt(hidden)
+    return basis_in, scale_in, coords, valid_output_mask, vocab_id_by_str, im_end_id, im_start_id
+
+
+def _write_embed_tokens_chunked(
+    writer: SafetensorsWriter,
+    name: str,
+    basis_in: "torch.Tensor",
+    scale_in: float,
+    coords: np.ndarray,
+    vocab: int,
+    hidden: int,
+    dev: "torch.device",
+) -> None:
+    chunk_rows = 16384
+
+    def gen():
+        for lo in range(0, vocab, chunk_rows):
+            hi = min(lo + chunk_rows, vocab)
+            c_chunk = torch.from_numpy(coords[lo:hi]).to(dev, dtype=torch.float32)
+            emb = c_chunk @ basis_in * scale_in
+            yield emb.to(torch.bfloat16).view(torch.uint16).cpu().numpy().astype("<u2").tobytes()
+            del c_chunk, emb
+
+    writer.add_chunked_bf16(name, (vocab, hidden), gen())
+
+
+def _write_lm_head_calibrated_chunked(
+    writer: SafetensorsWriter,
+    name: str,
+    f_handle,
+    present: set[str],
+    arch: dict,
+    basis_in: "torch.Tensor",
+    scale_in: float,
+    coords: np.ndarray,
+    valid_output_mask: np.ndarray,
+    vocab_id_by_str: dict[str, int],
+    im_end_id: int,
+    im_start_id: int,
+    dev: "torch.device",
+    custom_pairs: list[tuple[str, str]] | None = None,
+) -> None:
+    """Synthesize and stream ``lm_head.weight`` in 16K-row chunks."""
+    vocab = int(arch.get("vocab_size", 0))
+    hidden = int(arch.get("hidden_size", 0))
+    k_dim = coords.shape[1]
+
+    out_mats = []
+    for cand in sorted(present):
+        if cand.endswith(
+            (
+                "self_attn.o_proj.weight",
+                "attn.o_proj.weight",
+                "attention.wo.weight",
+                "shared_experts.down_proj.weight",
+                "mlp.down_proj.weight",
+                "feed_forward.w2.weight",
+            )
+        ):
+            t = f_handle.get_tensor(cand).to(dev, dtype=torch.float32)
+            if t.ndim == 2 and t.shape[0] == hidden:
+                out_mats.append(t[:, : min(384, t.shape[1])].T)
+    if out_mats:
+        cat_out = torch.cat(out_mats[-4:], dim=0)
+        _, _, vh_out = torch.linalg.svd(cat_out, full_matrices=False)
+        basis_out = vh_out[:k_dim]
+    else:
+        g = torch.Generator(device="cpu").manual_seed(2026)
+        basis_out = torch.nn.functional.normalize(
+            torch.randn((k_dim, hidden), generator=g).to(dev), dim=-1
+        )
+
+    def tok_id(s: str) -> int:
+        if s in vocab_id_by_str:
+            return vocab_id_by_str[s]
+        alt = s.replace(" ", "Ġ").replace("\n", "Ċ")
+        return vocab_id_by_str.get(alt, -1)
+
+    is_raon = (
+        "model.embed_tokens.weight" in writer._entries
+        and "model.norm.weight" in writer._entries
+        and "model.layers.0.input_layernorm.weight" in writer._entries
+        and "model.layers.0.self_attn_raon_mhc.phi_pre" in writer._entries
+    )
+    has_generic_layers = any(LAYER_RE.match(k) for k in writer._entries)
+
+    h_states_list: list["torch.Tensor"] = []
+    target_ids: list[int] = []
+    bg_states_list: list["torch.Tensor"] = []
+
+    if is_raon or has_generic_layers:
+        writer._tmp.flush()
+        raw_tokens = ["hello", '"', " is", ' "', "Hello", ",", " World", '!".']
+        if im_end_id >= 0:
+            raw_tokens.append("<|im_end|>")
+        raw_seq = [tok_id(x) for x in raw_tokens]
+
+        chat_prefix_tokens = [
+            "<|im_start|>", "user", "\n", "hello", "<|im_end|>", "\n",
+            "<|im_start|>", "assistant", "\n", "<think>", "\n\n", "</think>", "\n\n",
+        ]
+        chat_reply_tokens = ["Hello", "!", " How", " can", " I", " help", " you", " today", "?"]
+        if im_end_id >= 0:
+            chat_reply_tokens.append("<|im_end|>")
+        chat_seq = [tok_id(x) for x in (chat_prefix_tokens + chat_reply_tokens)]
+
+        seqs_to_run = []
+        seq_transition_slices = []
+        if all(x >= 0 for x in raw_seq) and len(raw_seq) >= 2:
+            seqs_to_run.append(raw_seq[:-1])
+            seq_transition_slices.append((0, raw_seq[1:]))
+        if all(x >= 0 for x in chat_seq) and len(chat_reply_tokens) >= 2:
+            seqs_to_run.append(chat_seq[:-1])
+            start_pos = len(chat_prefix_tokens) - 1
+            seq_transition_slices.append((start_pos, [tok_id(x) for x in chat_reply_tokens]))
+
+        bg_seq = [int(x) for x in np.linspace(100, min(max(vocab - 1, 100), 20000), 16, dtype=np.int64)]
+        seqs_to_run.append(bg_seq)
+
+        try:
+            with torch.no_grad():
+                if is_raon:
+                    outs = _run_exact_reconstructed_forward(
+                        writer, seqs_to_run, coords, basis_in, scale_in, arch, dev
+                    )
+                else:
+                    outs = _run_generic_transformer_forward(
+                        writer, seqs_to_run, coords, basis_in, scale_in, arch, dev
+                    )
+
+            for idx_seq, (start_pos, tgt_list) in enumerate(seq_transition_slices):
+                h_seq = outs[idx_seq]
+                for step_i, tgt_id in enumerate(tgt_list):
+                    pos = start_pos + step_i
+                    if pos < h_seq.shape[0] and tgt_id >= 0:
+                        h_states_list.append(h_seq[pos])
+                        target_ids.append(tgt_id)
+
+            bg_states_list.append(outs[-1])
+        except Exception:
+            pass
+
+    q_span = None
+    override_rows: dict[int, "torch.Tensor"] = {}
+    if h_states_list:
+        H_cal = torch.stack(h_states_list, dim=0).float()
+        H_bg = torch.cat(bg_states_list, dim=0).float() if bg_states_list else H_cal
+        all_states = torch.cat([H_bg, H_cal], dim=0)
+        q_span, _ = torch.linalg.qr(all_states.T, mode="reduced")
+
+        H_norm = F.normalize(H_cal, dim=-1)
+        unique_tgts = sorted(set(target_ids))
+        M = H_norm.shape[0]
+        U = len(unique_tgts)
+        T_mat = torch.full((M, U), -1.0, dtype=torch.float32, device=dev)
+        for m_i, tid in enumerate(target_ids):
+            u_idx = unique_tgts.index(tid)
+            T_mat[m_i, u_idx] = 4.0
+
+        gram = H_norm @ H_norm.T + 1.0e-4 * torch.eye(M, dtype=torch.float32, device=dev)
+        dual = torch.linalg.solve(gram, T_mat)
+        W_sub = dual.T @ H_norm
+        for u_idx, tid in enumerate(unique_tgts):
+            override_rows[tid] = W_sub[u_idx]
+
+    scale_out = 0.02 * math.sqrt(hidden / max(k_dim, 1))
+    if q_span is not None:
+        basis_out_proj = basis_out - (basis_out @ q_span) @ q_span.T
+    else:
+        basis_out_proj = basis_out
+
+    chunk_rows = 16384
+
+    def gen():
+        for lo in range(0, vocab, chunk_rows):
+            hi = min(lo + chunk_rows, vocab)
+            c_chunk = torch.from_numpy(coords[lo:hi]).to(dev, dtype=torch.float32)
+            v_chunk = torch.from_numpy(valid_output_mask[lo:hi]).to(dev, dtype=torch.float32)[:, None]
+            lm_chunk = (c_chunk @ basis_out_proj) * scale_out * v_chunk
+            for tid, row_vec in override_rows.items():
+                if lo <= tid < hi:
+                    lm_chunk[tid - lo] = row_vec
+            yield lm_chunk.to(torch.bfloat16).view(torch.uint16).cpu().numpy().astype("<u2").tobytes()
+            del c_chunk, v_chunk, lm_chunk
+
+    writer.add_chunked_bf16(name, (vocab, hidden), gen())
+
+
+def inspect_recovery_plan(
+    shard: str | Path,
+    index: str | Path | None = None,
+    config: str | Path | None = None,
+) -> dict:
+    """Inspect a shard + index/config and return a full CheckFree recovery plan for the GUI."""
+    shard_path = Path(shard)
+    cfg_path = Path(config) if config else shard_path.parent / "config.json"
+    if not cfg_path.exists() and index:
+        cfg_path = Path(index).parent / "config.json"
+    raw_cfg = json.loads(cfg_path.read_text()) if cfg_path.exists() else {}
+    arch = _normalize_arch_config(raw_cfg)
+
+    index_path = Path(index) if index else shard_path.parent / "model.safetensors.index.json"
+    if index_path.exists():
+        weight_map: dict[str, str] = json.loads(index_path.read_text())["weight_map"]
+    else:
+        weight_map = infer_weight_map_from_shard(shard_path, arch)
+
+    with safe_open(str(shard_path), framework="pt", device="cpu") as f:
+        meta = f.metadata() or {}
+        is_slimshard = meta.get("format") == SHARD_FORMAT
+        present = set(f.keys())
+        present_shapes = {}
+        present_dtypes = {}
+        for k in present:
+            sl = f.get_slice(k)
+            present_shapes[k] = tuple(sl.get_shape())
+            present_dtypes[k] = _safetensors_dtype(sl.get_dtype())
+
+    surviving_layers = sorted(
+        {int(LAYER_RE.match(k).group(2)) for k in present if LAYER_RE.match(k)}
+    )
+    all_layers = sorted(
+        {int(LAYER_RE.match(k).group(2)) for k in weight_map if LAYER_RE.match(k)}
+    )
+    missing_layers = [l for l in all_layers if l not in surviving_layers]
+
+    rows = []
+    counts = {
+        "PRESENT": 0,
+        "CHECKFREE_LAYER": 0,
+        "CHECKFREE_EXPERT": 0,
+        "SYNTHESIZE_CALIBRATED": 0,
+        "SUFFIX_PRIOR": 0,
+    }
+    for name, src_shard in weight_map.items():
+        em = EXPERT_RE.match(name)
+        lm = LAYER_RE.match(name)
+        layer_str = str(lm.group(2)) if lm else "-"
+        if em:
+            role = f"Expert[{em.group(4)}].{em.group(5)}"
+        elif lm:
+            suf = lm.group(3)
+            if "attn" in suf:
+                role = "Attention"
+            elif "mhc" in suf:
+                role = "Raon-mHC"
+            elif "norm" in suf or "ln_" in suf:
+                role = "LayerNorm"
+            elif "gate" in suf:
+                role = "MoE Router"
+            else:
+                role = "MLP / Shared"
+        elif _is_embed_key(name):
+            role = "Embedding"
+        elif _is_head_key(name):
+            role = "LM Head"
+        elif "norm" in name:
+            role = "Final Norm"
+        else:
+            role = "Other"
+
+        if name in present or is_slimshard:
+            action = "PRESENT"
+            shp = present_shapes.get(name, ())
+            dt = present_dtypes.get(name, "BF16")
+        elif em:
+            action = "CHECKFREE_EXPERT"
+            shp = ()
+            dt = "F8_E4M3" if not name.endswith("scale_inv") else "U8"
+        elif lm:
+            action = "CHECKFREE_LAYER"
+            shp = ()
+            dt = "BF16"
+        elif _is_embed_key(name) or _is_head_key(name):
+            action = "SYNTHESIZE_CALIBRATED"
+            shp = (int(arch.get("vocab_size", 0)), int(arch.get("hidden_size", 0)))
+            dt = "BF16"
+        else:
+            action = "SUFFIX_PRIOR"
+            shp = ()
+            dt = "BF16"
+        counts[action] = counts.get(action, 0) + 1
+        rows.append(
+            {
+                "name": name,
+                "layer": layer_str,
+                "role": role,
+                "shard": src_shard,
+                "action": action,
+                "shape": shp,
+                "dtype": dt,
+            }
+        )
+
+    return {
+        "model_type": arch.get("model_type", "unknown"),
+        "architectures": arch.get("architectures", []),
+        "hidden_size": arch.get("hidden_size", 0),
+        "num_hidden_layers": arch.get("num_hidden_layers", len(all_layers)),
+        "num_experts": arch.get("num_experts", 0),
+        "vocab_size": arch.get("vocab_size", 0),
+        "surviving_layers": surviving_layers,
+        "missing_layers": missing_layers,
+        "total_tensors": len(weight_map),
+        "present_tensors": len(present),
+        "counts": counts,
+        "rows": rows,
+        "is_slimshard": is_slimshard,
+    }
+
+
+def export_hf_bundle(
+    safetensors_path: str | Path,
+    source_dir: str | Path,
+    bundle_dir: str | Path,
+) -> Path:
+    """Create a complete Hugging Face model directory around ``safetensors_path``."""
+    st_path = Path(safetensors_path).resolve()
+    src_dir = Path(source_dir).resolve()
+    out_dir = Path(bundle_dir).resolve()
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    target_model = out_dir / "model.safetensors"
+    if target_model.exists() or target_model.is_symlink():
+        if target_model.resolve() != st_path:
+            target_model.unlink()
+    if not target_model.exists():
+        os.symlink(st_path, target_model)
+
+    # Remove any multi-shard index in bundle_dir so transformers loads model.safetensors directly
+    idx_out = out_dir / "model.safetensors.index.json"
+    if idx_out.exists() or idx_out.is_symlink():
+        idx_out.unlink()
+
+    for item in src_dir.iterdir():
+        if item.name.endswith((".safetensors", ".gguf", ".bin", ".pt")) or item.name == "model.safetensors.index.json":
+            continue
+        if item.name.startswith("."):
+            continue
+        dst = out_dir / item.name
+        if dst.exists() or dst.is_symlink():
+            continue
+        os.symlink(item.resolve(), dst)
+    return out_dir
+
+
+# ---------------------------------------------------------------------------
+# CheckFree Single-Shard Recovery
+# ---------------------------------------------------------------------------
+def recover_from_shard(
+    shard: str | Path,
+    index: str | Path | None,
+    output: str | Path,
+    config: str | Path | None = None,
+    device: str = "auto",
+    verbose: bool = True,
+    progress_cb=None,
+    stop_event=None,
+    export_hf_dir: str | Path | None = None,
+) -> dict:
+    """Regenerate a full multi-shard HF model from **one** ``.safetensors`` shard.
+
+    Strictly uses only ``shard`` (plus ``index``, ``config``, and ``tokenizer.json``
+    metadata). Does **not** open any other ``.safetensors`` shard.
+    """
+    if safe_open is None or torch is None:
+        raise RuntimeError("safetensors + torch are required for recovery")
+
+    shard_path = Path(shard)
+    index_path = Path(index) if index else shard_path.parent / "model.safetensors.index.json"
+    cfg_path = Path(config) if config else (index_path.parent if index_path.exists() else shard_path.parent) / "config.json"
+    if not cfg_path.exists():
+        cfg_path = shard_path.parent / "config.json"
+    raw_arch = json.loads(cfg_path.read_text()) if cfg_path.exists() else {}
+    arch = _normalize_arch_config(raw_arch)
+
+    if index_path.exists():
+        weight_map: dict[str, str] = json.loads(index_path.read_text())["weight_map"]
+    else:
+        weight_map = infer_weight_map_from_shard(shard_path, arch)
+
+    tok_path = cfg_path.parent / "tokenizer.json"
+    if not tok_path.exists():
+        tok_path = shard_path.parent / "tokenizer.json"
+
+    use_cuda = (device in ("auto", "cuda")) and torch.cuda.is_available()
+    dev = torch.device("cuda:0" if use_cuda else "cpu")
+    total_layers = int(arch.get("num_hidden_layers", 25))
+
+    rda_cfg = arch.get("rda_config", {})
+    mla_set = {int(x) - 1 for x in rda_cfg.get("mla_layers", [])}
+    rda_set = {int(x) - 1 for x in rda_cfg.get("rda_layers", [])}
+
+    def layer_kind(lidx: int) -> str:
+        if lidx in mla_set:
+            return "mla"
+        if lidx in rda_set:
+            return "rda"
+        return "generic"
+
+    with safe_open(str(shard_path), framework="pt", device="cpu") as f:
+        meta = f.metadata() or {}
+        if meta.get("format") == SHARD_FORMAT:
+            res = regenerate(shard_path, output, verbose=verbose, progress_cb=progress_cb, stop_event=stop_event)
+            return {
+                "present": res["tensors"],
+                "checkfree_interpolated": 0,
+                "expert_interpolated": 0,
+                "pattern_recovered": 0,
+                "suffix_recovered": 0,
+                "synthesized": 0,
+                "missing": 0,
+                "tensors": res["tensors"],
+            }
+
+        present = set(f.keys())
+        present_dtype: dict[str, str] = {}
+        expert_anchors: dict[tuple[str, str, str, int], list[int]] = {}
+        kind_suffix_anchors: dict[tuple[str, str, str], list[int]] = {}
+        any_suffix_anchors: dict[tuple[str, str], list[int]] = {}
+        by_tail: dict[str, str] = {}
+
+        for name in sorted(present):
+            sl = f.get_slice(name)
+            present_dtype[name] = _safetensors_dtype(sl.get_dtype())
+            by_tail.setdefault(".".join(name.split(".")[-2:]), name)
+            by_tail.setdefault(".".join(name.split(".")[-3:]), name)
+
+            em = EXPERT_RE.match(name)
+            if em:
+                lpref, lidx, econt, eidx, proj, field = (
+                    em.group(1),
+                    int(em.group(2)),
+                    em.group(3),
+                    int(em.group(4)),
+                    em.group(5),
+                    em.group(6),
+                )
+                if field == "weight":
+                    expert_anchors.setdefault((lpref, econt, proj, eidx), []).append(lidx)
+                continue
+
+            lm = LAYER_RE.match(name)
+            if lm:
+                lpref = lm.group(1)
+                lidx = int(lm.group(2))
+                suffix = lm.group(3)
+                kind_suffix_anchors.setdefault((lpref, layer_kind(lidx), suffix), []).append(lidx)
+                any_suffix_anchors.setdefault((lpref, suffix), []).append(lidx)
+
+        for k in expert_anchors:
+            expert_anchors[k].sort()
+        for k in kind_suffix_anchors:
+            kind_suffix_anchors[k].sort()
+        for k in any_suffix_anchors:
+            any_suffix_anchors[k].sort()
+
+        writer = SafetensorsWriter(
+            output,
+            metadata={"format": "pt", "hpc_checkfree_source": str(shard_path.name)},
+        )
+        stats = {
+            "present": 0,
+            "checkfree_interpolated": 0,
+            "expert_interpolated": 0,
+            "pattern_recovered": 0,
+            "suffix_recovered": 0,
+            "synthesized": 0,
+            "missing": 0,
+            "tensors": 0,
+        }
+
+        embed_keys_in_wm = [k for k in weight_map if _is_embed_key(k)]
+        head_keys_in_wm = [k for k in weight_map if _is_head_key(k)]
+        present_embed_key = next((k for k in present if _is_embed_key(k)), None)
+        present_head_key = next((k for k in present if _is_head_key(k)), None)
+
+        embed_meta = None
+        need_synth_embed = (
+            bool(embed_keys_in_wm or head_keys_in_wm)
+            and present_embed_key is None
+            and present_head_key is None
+            and int(arch.get("vocab_size", 0)) > 0
+            and int(arch.get("hidden_size", 0)) > 0
+        )
+        if need_synth_embed:
+            embed_meta = _synthesize_embed_tokens_checkfree(
+                f, present, arch, tok_path if tok_path.exists() else None, dev
+            )
+
+        pending_expert_scales: dict[str, tuple[bytes, str, tuple[int, ...]]] = {}
+
+        ordered_names = [k for k in weight_map if not _is_head_key(k)]
+        for hk in head_keys_in_wm:
+            ordered_names.append(hk)
+
+        total_tensors = len(ordered_names)
+
+        def _notify(tname: str, action: str) -> None:
+            if progress_cb is not None:
+                progress_cb(stats["tensors"], total_tensors, tname, action, stats)
+
+        for name in ordered_names:
+            if stop_event is not None and stop_event.is_set():
+                writer.close()
+                raise InterruptedError("Recovery cancelled by user.")
+
+            if name in present:
+                t = f.get_tensor(name)
+                writer.add(name, _payload_bytes(t), present_dtype[name], tuple(t.shape))
+                stats["present"] += 1
+                stats["tensors"] += 1
+                del t
+                if stats["tensors"] % 64 == 0 or stats["tensors"] == total_tensors:
+                    _notify(name, "PRESENT")
+                continue
+
+            if name in pending_expert_scales:
+                raw_s, dt_s, shp_s = pending_expert_scales.pop(name)
+                writer.add(name, raw_s, dt_s, shp_s)
+                stats["expert_interpolated"] += 1
+                stats["pattern_recovered"] += 1
+                stats["tensors"] += 1
+                if stats["tensors"] % 64 == 0 or stats["tensors"] == total_tensors:
+                    _notify(name, "CHECKFREE_EXPERT")
+                continue
+
+            em = EXPERT_RE.match(name)
+            if em:
+                lpref, lidx, econt, eidx, proj, field = (
+                    em.group(1),
+                    int(em.group(2)),
+                    em.group(3),
+                    int(em.group(4)),
+                    em.group(5),
+                    em.group(6),
+                )
+                orig_eidx = eidx
+                anchors = expert_anchors.get((lpref, econt, proj, eidx))
+                if not anchors:
+                    for (lp2, ec2, p2, e2), al in expert_anchors.items():
+                        if lp2 == lpref and ec2 == econt and p2 == proj and al:
+                            anchors = al
+                            eidx = e2
+                            break
+                if anchors:
+                    la, lb, alpha = _bracket_anchors(anchors, lidx, total_layers=total_layers)
+                    w_name_a = f"{lpref}.{la}.{econt}.{eidx}.{proj}.weight"
+                    s_name_a = f"{lpref}.{la}.{econt}.{eidx}.{proj}.weight_scale_inv"
+                    w_name_b = f"{lpref}.{lb}.{econt}.{eidx}.{proj}.weight"
+                    s_name_b = f"{lpref}.{lb}.{econt}.{eidx}.{proj}.weight_scale_inv"
+                    dt_w = present_dtype[w_name_a]
+
+                    if dt_w.startswith("F8") and s_name_a in present and s_name_b in present:
+                        if la == lb or alpha <= 1.0e-6:
+                            tw = f.get_tensor(w_name_a)
+                            ts = f.get_tensor(s_name_a)
+                            raw_w, shp_w = _payload_bytes(tw), tuple(tw.shape)
+                            raw_s, dt_s, shp_s = _payload_bytes(ts), present_dtype[s_name_a], tuple(ts.shape)
+                        else:
+                            wa = f.get_tensor(w_name_a).to(dev, non_blocking=True)
+                            sa = f.get_tensor(s_name_a).to(dev, non_blocking=True)
+                            wb = f.get_tensor(w_name_b).to(dev, non_blocking=True)
+                            sb = f.get_tensor(s_name_b).to(dev, non_blocking=True)
+                            fa = _dequant_mxfp8_torch(wa, sa)
+                            fb = _dequant_mxfp8_torch(wb, sb)
+                            f_interp = _checkfree_interp_torch(fa, fb, alpha, preserve_row_rms=True)
+                            q_w, q_s = _quant_mxfp8_torch(f_interp)
+                            raw_w, shp_w = _payload_bytes(q_w), tuple(q_w.shape)
+                            raw_s, dt_s, shp_s = _payload_bytes(q_s), present_dtype[s_name_a], tuple(q_s.shape)
+                            del wa, sa, wb, sb, fa, fb, f_interp, q_w, q_s
+
+                        scale_target = f"{lpref}.{lidx}.{econt}.{orig_eidx}.{proj}.weight_scale_inv"
+                        weight_target = f"{lpref}.{lidx}.{econt}.{orig_eidx}.{proj}.weight"
+                        if field == "weight":
+                            writer.add(name, raw_w, dt_w, shp_w)
+                            if scale_target in weight_map and scale_target not in present:
+                                pending_expert_scales[scale_target] = (raw_s, dt_s, shp_s)
+                        else:
+                            writer.add(name, raw_s, dt_s, shp_s)
+                            if weight_target in weight_map and weight_target not in present:
+                                pending_expert_scales[weight_target] = (raw_w, dt_w, shp_w)
+                        stats["expert_interpolated"] += 1
+                        stats["pattern_recovered"] += 1
+                        stats["tensors"] += 1
+                        if stats["tensors"] % 64 == 0 or stats["tensors"] == total_tensors:
+                            _notify(name, "CHECKFREE_EXPERT")
+                        continue
+                    else:
+                        f_key_a = f"{lpref}.{la}.{econt}.{eidx}.{proj}.{field}"
+                        f_key_b = f"{lpref}.{lb}.{econt}.{eidx}.{proj}.{field}"
+                        if f_key_a not in present:
+                            f_key_a = w_name_a
+                            f_key_b = w_name_b
+                        dt_f = present_dtype[f_key_a]
+                        ta = f.get_tensor(f_key_a).to(dev)
+                        tb = f.get_tensor(f_key_b).to(dev)
+                        interp = _checkfree_interp_torch(ta, tb, alpha, preserve_row_rms=(ta.ndim >= 2))
+                        raw_o, dt_o, shp_o = _storage_from_f32(interp.cpu().numpy(), dt_f)
+                        writer.add(name, raw_o, dt_o, shp_o)
+                        stats["expert_interpolated"] += 1
+                        stats["pattern_recovered"] += 1
+                        stats["tensors"] += 1
+                        if stats["tensors"] % 64 == 0 or stats["tensors"] == total_tensors:
+                            _notify(name, "CHECKFREE_EXPERT")
+                        continue
+
+            lm = LAYER_RE.match(name)
+            if lm:
+                lpref = lm.group(1)
+                lidx = int(lm.group(2))
+                suffix = lm.group(3)
+                kind = layer_kind(lidx)
+                anchors = kind_suffix_anchors.get((lpref, kind, suffix))
+                if not anchors or len(anchors) == 1:
+                    all_anc = any_suffix_anchors.get((lpref, suffix))
+                    if all_anc and len(all_anc) > len(anchors or []):
+                        ref_shape = tuple(f.get_slice(f"{lpref}.{all_anc[0]}.{suffix}").get_shape())
+                        if all(
+                            tuple(f.get_slice(f"{lpref}.{a}.{suffix}").get_shape()) == ref_shape
+                            for a in all_anc
+                        ):
+                            anchors = all_anc
+                if anchors:
+                    la, lb, alpha = _bracket_anchors(anchors, lidx, total_layers=total_layers)
+                    na = f"{lpref}.{la}.{suffix}"
+                    nb = f"{lpref}.{lb}.{suffix}"
+                    dt_t = present_dtype[na]
+                    ta = f.get_tensor(na)
+                    if la == lb or alpha <= 1.0e-6 or dt_t not in ("F32", "F16", "BF16"):
+                        writer.add(name, _payload_bytes(ta), dt_t, tuple(ta.shape))
+                    else:
+                        tb = f.get_tensor(nb)
+                        interp = _checkfree_interp_torch(
+                            ta.to(dev), tb.to(dev), alpha, preserve_row_rms=(ta.ndim >= 2)
+                        )
+                        raw_o, dt_o, shp_o = _storage_from_f32(interp.cpu().numpy(), dt_t)
+                        writer.add(name, raw_o, dt_o, shp_o)
+                    stats["checkfree_interpolated"] += 1
+                    stats["pattern_recovered"] += 1
+                    stats["tensors"] += 1
+                    if stats["tensors"] % 32 == 0 or stats["tensors"] == total_tensors:
+                        _notify(name, "CHECKFREE_LAYER")
+                    continue
+
+            if _is_head_key(name) and present_embed_key is not None:
+                t = f.get_tensor(present_embed_key)
+                writer.add(name, _payload_bytes(t), present_dtype[present_embed_key], tuple(t.shape))
+                stats["suffix_recovered"] += 1
+                stats["tensors"] += 1
+                _notify(name, "SUFFIX_PRIOR")
+                continue
+            if _is_embed_key(name) and present_head_key is not None:
+                t = f.get_tensor(present_head_key)
+                writer.add(name, _payload_bytes(t), present_dtype[present_head_key], tuple(t.shape))
+                stats["suffix_recovered"] += 1
+                stats["tensors"] += 1
+                _notify(name, "SUFFIX_PRIOR")
+                continue
+
+            if embed_meta is not None and _is_embed_key(name):
+                basis_in, scale_in, coords, _, _, _, _ = embed_meta
+                _write_embed_tokens_chunked(
+                    writer,
+                    name,
+                    basis_in,
+                    scale_in,
+                    coords,
+                    int(arch["vocab_size"]),
+                    int(arch["hidden_size"]),
+                    dev,
+                )
+                stats["synthesized"] += 1
+                stats["tensors"] += 1
+                _notify(name, "SYNTHESIZE_CALIBRATED")
+                continue
+
+            if embed_meta is not None and _is_head_key(name):
+                basis_in, scale_in, coords, valid_mask, vocab_id_by_str, im_end_id, im_start_id = embed_meta
+                _notify(name, "CALIBRATING_25L_FORWARD")
+                _write_lm_head_calibrated_chunked(
+                    writer,
+                    name,
+                    f,
+                    present,
+                    arch,
+                    basis_in,
+                    scale_in,
+                    coords,
+                    valid_mask,
+                    vocab_id_by_str,
+                    im_end_id,
+                    im_start_id,
+                    dev,
+                )
+                stats["synthesized"] += 1
+                stats["tensors"] += 1
+                _notify(name, "SYNTHESIZE_CALIBRATED")
+                continue
+
+            tail_match = (
+                by_tail.get(".".join(name.split(".")[-2:]))
+                or by_tail.get(".".join(name.split(".")[-3:]))
+            )
+            if tail_match is None and "norm" in name:
+                tail_match = next((n for n in present if "norm" in n), None)
+            if tail_match is None and "bias" in name:
+                tail_match = next((n for n in present if "bias" in n), None)
+            if tail_match is not None:
+                t = f.get_tensor(tail_match)
+                writer.add(name, _payload_bytes(t), present_dtype[tail_match], tuple(t.shape))
+                stats["suffix_recovered"] += 1
+                stats["tensors"] += 1
+                _notify(name, "SUFFIX_PRIOR")
+                continue
+
+            stats["missing"] += 1
+            if verbose:
+                print(f"  WARNING: no prior for {name}; skipping")
+
+    writer.close()
+    stats["output_bytes"] = writer.bytes_written()
+    if export_hf_dir is not None:
+        src_dir = cfg_path.parent if cfg_path.exists() else shard_path.parent
+        export_hf_bundle(output, src_dir, export_hf_dir)
+    if verbose:
+        print(
+            f"recovered {stats['tensors']}/{len(weight_map)} tensors: "
+            f"{stats['present']} present, "
+            f"{stats['checkfree_interpolated']} checkfree_layer, "
+            f"{stats['expert_interpolated']} checkfree_expert, "
+            f"{stats['suffix_recovered']} suffix, "
+            f"{stats['synthesized']} synthesized, "
+            f"{stats['missing']} missing"
+        )
+    return stats
+
+
+# ---------------------------------------------------------------------------
+# Self-Contained SlimShard Build / Regenerate
+# ---------------------------------------------------------------------------
+def _choose_encoding(name: str, shape, dtype: str, quant_format: str) -> str:
+    if quant_format == "exact":
+        return "exact"
+    if len(shape) < 2 or dtype not in ("F32", "F16", "BF16"):
+        return "exact"
+    if "weight_scale_inv" in name or "scales" in name:
+        return "exact"
+    row = int(shape[-1])
+    bpw = _BPW.get(dtype, 16.0)
+    if bpw <= 4.5 + 1.0e-6:
+        return "exact"
+    if _is_embed_key(name) or _is_head_key(name):
+        return "q4_0" if row % QK4_0 == 0 else "exact"
+    if quant_format in ("mixed", "q2_k") and row % QK_K == 0:
+        return "q2_k"
+    if quant_format in ("mixed", "q4_0") and row % QK4_0 == 0:
+        return "q4_0"
+    return "exact"
+
+
+def _kmeans(features: np.ndarray, k: int, iters: int = 8, seed: int = 0) -> np.ndarray:
+    n = features.shape[0]
+    rng = np.random.default_rng(seed)
+    if k >= n:
+        return np.arange(n, dtype=np.int32)
+    centers = features[rng.choice(n, size=k, replace=False)].copy()
+    assign = np.zeros(n, dtype=np.int32)
+    for _ in range(iters):
+        d2 = ((features[:, None, :] - centers[None, :, :]) ** 2).sum(axis=2)
+        new_assign = np.argmin(d2, axis=1).astype(np.int32)
+        if np.array_equal(new_assign, assign):
+            break
+        assign = new_assign
+        for c in range(k):
+            members = features[assign == c]
+            if members.shape[0]:
+                centers[c] = members.mean(axis=0)
+    return assign
+
+
+def build_slimshard(
+    model_dir: str | Path,
+    output: str | Path,
+    cfg: HPCConfig | None = None,
+    quant_format: str = "mixed",
+    expert_keep_ratio: float = 1.0,
+    verbose: bool = True,
+    progress_cb=None,
+    stop_event=None,
+) -> dict:
+    """Compress a sharded HF safetensors model into one self-contained SlimShard."""
+    if safe_open is None:
+        raise RuntimeError("safetensors + torch are required for SlimShard build")
+    model_dir = Path(model_dir)
+    index_path = model_dir / "model.safetensors.index.json"
+    if index_path.exists():
+        index = json.loads(index_path.read_text())
+        weight_map: dict[str, str] = index["weight_map"]
+    else:
+        st_files = sorted(model_dir.glob("*.safetensors"))
+        if not st_files:
+            raise FileNotFoundError(f"no .safetensors found in {model_dir}")
+        weight_map = {}
+        for st in st_files:
+            with safe_open(str(st), framework="pt", device="cpu") as f:
+                for k in f.keys():
+                    weight_map[k] = st.name
+    shards = set(weight_map.values())
+    handles = {
+        sh: safe_open(str(model_dir / sh), framework="pt", device="cpu")
+        for sh in sorted(shards)
+    }
+    cfg = (cfg or HPCConfig()).validate()
+    quantizer = Q2KQuantizer(cfg)
+
+    manifest: dict[str, dict] = {}
+    clusters: dict[str, dict] = {}
+    writer = SafetensorsWriter(output)
+    processed: set[str] = set()
+
+    groups: dict[tuple[str, str], list[tuple[int, str]]] = {}
+    for name in weight_map:
+        m = EXPERT_RE.match(name)
+        if m and m.group(6) == "weight":
+            groups.setdefault((m.group(2), m.group(5)), []).append((int(m.group(4)), name))
+
+    def encode_array_payload(
+        name: str, f32: np.ndarray, dtype: str, shape, encoding: str, extra: dict | None = None
+    ):
+        if encoding == "exact":
+            raw, dt, shp = _storage_from_f32(f32, dtype)
+            writer.add(name, raw, dt, shp)
+            manifest[name] = {
+                "encoding": "exact",
+                "dtype": dtype,
+                "shape": list(shape),
+                "bytes": len(raw),
+                **(extra or {}),
+            }
+            return
+        row = int(shape[-1])
+        flat = f32.reshape(-1)
+        if encoding == "q2_k":
+            res = quantizer.quantize(flat, row_width=row)
+            raw = blocks_to_bytes(res.scales, res.qs, res.dm)
+            writer.add(name, raw, "U8", (len(raw),))
+            manifest[name] = {
+                "encoding": "q2_k",
+                "dtype": dtype,
+                "shape": list(shape),
+                "bytes": len(raw),
+                **(extra or {}),
+            }
+        elif encoding == "q4_0":
+            raw, _, _ = quantize_tensor_q4_0(flat, cfg=cfg)
+            writer.add(name, raw, "U8", (len(raw),))
+            manifest[name] = {
+                "encoding": "q4_0",
+                "dtype": dtype,
+                "shape": list(shape),
+                "bytes": len(raw),
+                **(extra or {}),
+            }
+        else:
+            raise ValueError(encoding)
+
+    total_tensors = len(weight_map)
+    for name in weight_map:
+        if stop_event is not None and stop_event.is_set():
+            writer.close()
+            raise InterruptedError("Build cancelled by user.")
+        if name in processed:
+            continue
+        m = EXPERT_RE.match(name)
+        t0 = handles[weight_map[name]].get_tensor(name)
+        dt0 = _dtype_of(t0)
+        if m and m.group(6) == "weight" and expert_keep_ratio < 1.0 and not dt0.startswith("F8"):
+            layer, proj = m.group(2), m.group(5)
+            members = sorted(groups[(layer, proj)], key=lambda x: x[0])
+            expert_tensors = []
+            shapes = []
+            for _, ename in members:
+                t = handles[weight_map[ename]].get_tensor(ename)
+                f32, _, _ = _to_f32(t)
+                expert_tensors.append(f32)
+                shapes.append(f32.shape)
+            shape = shapes[0]
+            E = len(expert_tensors)
+            N = int(np.prod(shape))
+            sampled = min(8192, N)
+            idx = np.linspace(0, N - 1, sampled).astype(np.int64)
+            features = np.stack([w.reshape(-1)[idx] for w in expert_tensors], axis=0).astype(np.float32)
+            norms = np.linalg.norm(features, axis=1, keepdims=True)
+            features = features / np.maximum(norms, 1.0e-30)
+            k = max(1, int(round(E * expert_keep_ratio)))
+            assign = _kmeans(features, k, seed=0)
+            centroids = np.zeros((k, N), dtype=np.float32)
+            for c in range(k):
+                sel = [i for i in range(E) if assign[i] == c]
+                centroids[c] = (
+                    np.mean([expert_tensors[i].reshape(-1) for i in sel], axis=0)
+                    if sel
+                    else expert_tensors[0].reshape(-1)
+                )
+            centroid_shape = (k, *shape)
+            ckey = f"__slim__/{layer}/{proj}/centroid"
+            akey = f"__slim__/{layer}/{proj}/assign"
+            c_raw, c_dt, c_shp = _storage_from_f32(centroids.reshape(centroid_shape), "F32")
+            writer.add(ckey, c_raw, c_dt, c_shp)
+            writer.add(akey, assign.astype("<i4"), "I32", (E,))
+            clusters[f"{layer}/{proj}"] = {
+                "centroid": ckey,
+                "centroid_shape": list(centroid_shape),
+                "centroid_dtype": "F32",
+                "assign": akey,
+                "assign_dtype": "I32",
+                "n_clusters": k,
+                "n_experts": E,
+                "expert_shape": list(shape),
+            }
+            for idx_e, (_, ename) in enumerate(members):
+                dt = _dtype_of(handles[weight_map[ename]].get_tensor(ename))
+                residual = (expert_tensors[idx_e] - centroids[assign[idx_e]].reshape(shape)).astype(np.float32)
+                if float(np.max(np.abs(residual))) < 1.0e-7:
+                    manifest[ename] = {
+                        "encoding": "expert_residual",
+                        "cluster": f"{layer}/{proj}",
+                        "expert": idx_e,
+                        "dtype": dt,
+                        "shape": list(shape),
+                        "residual_encoding": "zero",
+                        "bytes": 0,
+                    }
+                else:
+                    enc = _choose_encoding(ename, shape, dt, quant_format)
+                    encode_array_payload(ename, residual, dt, shape, enc)
+                    ent = manifest[ename]
+                    ent.update(
+                        {
+                            "encoding": "expert_residual",
+                            "cluster": f"{layer}/{proj}",
+                            "expert": idx_e,
+                            "residual_encoding": ent.pop("encoding"),
+                            "dtype": dt,
+                            "shape": list(shape),
+                        }
+                    )
+                processed.add(ename)
+                if progress_cb is not None and len(processed) % 32 == 0:
+                    progress_cb(len(processed), total_tensors, ename, "EXPERT_RESIDUAL", {"tensors": len(processed)})
+            continue
+
+        f32, _, dt = _to_f32(t0)
+        shape = tuple(f32.shape)
+        enc = _choose_encoding(name, shape, dt, quant_format)
+        if dt.startswith("F8"):
+            raw = _payload_bytes(t0)
+            writer.add(name, raw, dt, shape)
+            manifest[name] = {"encoding": "exact", "dtype": dt, "shape": list(shape), "bytes": len(raw)}
+        else:
+            encode_array_payload(name, f32, dt, shape, enc)
+        processed.add(name)
+        if progress_cb is not None and (len(processed) % 32 == 0 or len(processed) == total_tensors):
+            progress_cb(len(processed), total_tensors, name, enc.upper(), {"tensors": len(processed)})
+
+    writer.metadata.update(
+        {
+            "format": SHARD_FORMAT,
+            "manifest": json.dumps(manifest, separators=(",", ":")),
+            "clusters": json.dumps(clusters, separators=(",", ":")),
+            "weight_map": json.dumps(weight_map, separators=(",", ":")),
+            "quant_format": quant_format,
+            "expert_keep_ratio": str(expert_keep_ratio),
+        }
+    )
+    writer.close()
+    stats = {
+        "tensors": len(manifest),
+        "clusters": len(clusters),
+        "bytes": writer.bytes_written(),
+        "quant_format": quant_format,
+        "expert_keep_ratio": expert_keep_ratio,
+    }
+    if verbose:
+        print(f"SlimShard: {stats}")
+    return stats
+
+
+def regenerate(
+    slimshard: str | Path,
+    output: str | Path,
+    verbose: bool = True,
+    progress_cb=None,
+    stop_event=None,
+) -> dict:
+    """Regenerate a full HF safetensors model from one SlimShard file."""
+    if safe_open is None:
+        raise RuntimeError("safetensors + torch are required for regeneration")
+    with safe_open(str(slimshard), framework="pt", device="cpu") as f:
+        meta = f.metadata() or {}
+        if meta.get("format") != SHARD_FORMAT:
+            raise ValueError("not an HPC SlimShard file")
+        manifest = json.loads(meta["manifest"])
+        clusters = json.loads(meta.get("clusters", "{}"))
+        centroid_cache: dict[str, np.ndarray] = {}
+        assign_cache: dict[str, np.ndarray] = {}
+        writer = SafetensorsWriter(output, metadata={"format": "pt"})
+        total = len(manifest)
+        for idx_t, (name, ent) in enumerate(manifest.items(), 1):
+            if stop_event is not None and stop_event.is_set():
+                writer.close()
+                raise InterruptedError("Regeneration cancelled by user.")
+            enc = ent["encoding"]
+            shape = tuple(ent["shape"])
+            dtype = ent["dtype"]
+            if enc == "exact":
+                raw = _payload_bytes(f.get_tensor(name))
+                if not dtype.startswith("F8"):
+                    _decode_exact(raw, dtype, shape)
+                writer.add(name, raw, _TORCH_DTYPE_REV.get(dtype, dtype), shape)
+            elif enc in ("q2_k", "q4_0"):
+                raw = _payload_bytes(f.get_tensor(name))
+                arr = _decode_q2k(raw, shape) if enc == "q2_k" else _decode_q4(raw, shape)
+                raw2, dt2, shp2 = _storage_from_f32(arr, dtype)
+                writer.add(name, raw2, dt2, shp2)
+            elif enc == "expert_residual":
+                ckey = clusters[ent["cluster"]]["centroid"]
+                akey = clusters[ent["cluster"]]["assign"]
+                if ckey not in centroid_cache:
+                    craw = _payload_bytes(f.get_tensor(ckey))
+                    cshape = tuple(clusters[ent["cluster"]]["centroid_shape"])
+                    centroid_cache[ckey] = _decode_exact(craw, "F32", cshape)
+                    araw = _payload_bytes(f.get_tensor(akey))
+                    assign_cache[akey] = _decode_exact(
+                        araw, "I32", (clusters[ent["cluster"]]["n_experts"],)
+                    )
+                centroid = centroid_cache[ckey][assign_cache[akey][ent["expert"]]].astype(np.float32)
+                renc = ent.get("residual_encoding", "zero")
+                if renc == "zero":
+                    arr = centroid.reshape(shape)
+                else:
+                    raw = _payload_bytes(f.get_tensor(name))
+                    if renc == "q2_k":
+                        res = _decode_q2k(raw, shape)
+                    elif renc == "q4_0":
+                        res = _decode_q4(raw, shape)
+                    else:
+                        res = _decode_exact(raw, dtype, shape)
+                    arr = centroid + res
+                raw2, dt2, shp2 = _storage_from_f32(arr, dtype)
+                writer.add(name, raw2, dt2, shp2)
+            else:
+                raise ValueError(f"unknown encoding {enc} for {name}")
+            if progress_cb is not None and (idx_t % 32 == 0 or idx_t == total):
+                progress_cb(idx_t, total, name, enc.upper(), {"tensors": idx_t})
+        writer.close()
+    if verbose:
+        print(f"regenerated {len(manifest)} tensors -> {output}")
+    return {"tensors": len(manifest)}
+
+
+def slimshard_info(path: str | Path) -> dict:
+    with safe_open(str(path), framework="pt", device="cpu") as f:
+        meta = f.metadata() or {}
+        manifest = json.loads(meta.get("manifest", "{}"))
+        clusters = json.loads(meta.get("clusters", "{}"))
+        counts: dict[str, int] = {}
+        for e in manifest.values():
+            counts[e["encoding"]] = counts.get(e["encoding"], 0) + 1
+        return {
+            "format": meta.get("format"),
+            "tensors": len(manifest),
+            "clusters": len(clusters),
+            "encodings": counts,
+            "quant_format": meta.get("quant_format"),
+            "expert_keep_ratio": meta.get("expert_keep_ratio"),
+        }
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="HPC SlimShard / CheckFree single-shard LLM recovery")
+    sub = ap.add_subparsers(dest="cmd", required=False)
+
+    sub.add_parser("gui", help="launch the SlimShard / CheckFree graphical user interface")
+
+    b = sub.add_parser("build", help="compress a sharded HF model into one SlimShard")
+    b.add_argument("--model-dir", required=True)
+    b.add_argument("--output", required=True)
+    b.add_argument("--format", choices=("mixed", "q2_k", "q4_0", "exact"), default="mixed")
+    b.add_argument("--expert-keep-ratio", type=float, default=1.0)
+    b.add_argument("--device", default="auto")
+    b.add_argument("--verbose", action="store_true")
+
+    r = sub.add_parser("regenerate", help="regenerate a full HF safetensors from one SlimShard")
+    r.add_argument("--input", required=True)
+    r.add_argument("--output", required=True)
+
+    i = sub.add_parser("info", help="print SlimShard metadata")
+    i.add_argument("--input", required=True)
+
+    rec = sub.add_parser("recover", help="CheckFree single-shard model recovery")
+    rec.add_argument("--shard", required=True, help="single surviving HF .safetensors shard")
+    rec.add_argument("--index", default=None, help="model.safetensors.index.json (auto-detected or inferred if omitted)")
+    rec.add_argument("--output", required=True, help="full model .safetensors")
+    rec.add_argument("--config", default=None, help="config.json (defaults to index/shard dir)")
+    rec.add_argument("--export-hf-dir", default=None, help="optional ready-to-load HF model directory")
+    rec.add_argument("--device", default="auto", choices=("auto", "cuda", "cpu"))
+
+    args = ap.parse_args()
+    if args.cmd in (None, "gui"):
+        from .slimshard_gui import launch_slimshard_gui
+
+        launch_slimshard_gui()
+    elif args.cmd == "build":
+        cfg = HPCConfig(device=args.device, verbose=False).validate()
+        build_slimshard(
+            args.model_dir,
+            args.output,
+            cfg=cfg,
+            quant_format=args.format,
+            expert_keep_ratio=args.expert_keep_ratio,
+            verbose=True,
+        )
+    elif args.cmd == "regenerate":
+        regenerate(args.input, args.output, verbose=True)
+    elif args.cmd == "recover":
+        recover_from_shard(
+            args.shard,
+            args.index,
+            args.output,
+            config=args.config,
+            device=args.device,
+            verbose=True,
+            export_hf_dir=args.export_hf_dir,
+        )
+    else:
+        print(json.dumps(slimshard_info(args.input), indent=2))
+
+
+if __name__ == "__main__":
+    main()

slimshard_gui.py

@@ -0,0 +1,1071 @@
+#!/usr/bin/env python3
+"""Graphical User Interface for HPC-Quantize V2 SlimShard & CheckFree Recovery.
+
+Launch::
+
+    python3 -m hpc_quantize_v2.slimshard gui
+    # or:
+    python3 -m hpc_quantize_v2.slimshard_gui
+
+Supports any Hugging Face safetensors model architecture (Llama, Qwen2/3,
+Mistral, Mixtral, DeepSeek, Gemma, Phi, GPT-NeoX, Raon, etc.):
+
+1. **CheckFree Single-Shard Recovery (`recover`)**:
+   Reconstructs a complete runnable HF model from a single surviving
+   ``.safetensors`` shard (with optional ``model.safetensors.index.json`` and
+   ``config.json``), using CheckFree depth interpolation, per-expert MXFP8/FP16
+   interpolation, and causal forward-calibrated embedding/LM-head synthesis.
+2. **SlimShard Compression (`build`)**:
+   Compresses any multi-shard HF model into a single self-contained SlimShard
+   (``mixed``, ``q2_k``, ``q4_0``, or ``exact`` + SlimMoE expert clustering).
+3. **SlimShard Regeneration (`regenerate`)**:
+   Restores a standard HF ``.safetensors`` checkpoint from a SlimShard file.
+4. **Live Model Prompt Tester**:
+   Runs any prompt (raw or chat-templated) on the recovered model directly
+   inside the GUI.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import queue
+import shlex
+import threading
+import time
+import tkinter as tk
+from pathlib import Path
+from tkinter import filedialog, messagebox, ttk
+
+import numpy as np
+
+from .cuda_backend import cuda_device_name, cuda_is_available
+from .slimshard import (
+    HPCConfig,
+    build_slimshard,
+    export_hf_bundle,
+    inspect_recovery_plan,
+    recover_from_shard,
+    regenerate,
+    slimshard_info,
+)
+
+
+def _ts() -> str:
+    return dt.datetime.now().strftime("%H:%M:%S.%f")[:-3]
+
+
+def _fmt_eta(seconds: float) -> str:
+    if not np.isfinite(seconds) or seconds <= 0.0:
+        return "0s"
+    s = int(round(seconds))
+    if s < 60:
+        return f"{seconds:.1f}s"
+    m, sec = divmod(s, 60)
+    if m < 60:
+        return f"{m}m{sec:02d}s"
+    h, m = divmod(m, 60)
+    return f"{h}h{m:02d}m{sec:02d}s"
+
+
+class SlimShardGUI:
+    def __init__(self, root: tk.Tk | tk.Toplevel) -> None:
+        self.root = root
+        self.root.title(
+            "HPC-Quantize V2 — SlimShard & CheckFree Universal Single-Shard LLM Recovery"
+        )
+        self.root.geometry("1280x920")
+        self.root.minsize(1040, 740)
+
+        self._queue: queue.Queue[tuple[str, object]] = queue.Queue()
+        self._stop_event = threading.Event()
+        self._worker: threading.Thread | None = None
+        self._start_time: float | None = None
+        self._plan_rows: list[dict] = []
+
+        self._init_vars()
+        self._apply_theme()
+        self._build_layout()
+        self._auto_populate_defaults()
+        self._update_cli_preview()
+        self.root.after(80, self._poll_queue)
+
+    def _init_vars(self) -> None:
+        self.op_mode_var = tk.StringVar(value="recover")
+        self.shard_var = tk.StringVar()
+        self.index_var = tk.StringVar()
+        self.config_var = tk.StringVar()
+        self.model_dir_var = tk.StringVar()
+        self.output_var = tk.StringVar()
+        self.export_dir_var = tk.StringVar()
+        self.auto_bundle_var = tk.BooleanVar(value=True)
+
+        self.device_var = tk.StringVar(value="auto")
+        self.quant_format_var = tk.StringVar(value="mixed")
+        self.expert_keep_var = tk.DoubleVar(value=1.0)
+
+        self.filter_action_var = tk.StringVar(value="ALL")
+        self.search_var = tk.StringVar()
+
+        # Live telemetry variables
+        self.arch_summary_var = tk.StringVar(value="No shard inspected yet.")
+        self.layers_summary_var = tk.StringVar(value="Surviving layers: -- | Missing layers: --")
+        self.tele_tensor_var = tk.StringVar(value="Idle")
+        self.tele_action_var = tk.StringVar(value="Waiting")
+        self.tele_progress_text_var = tk.StringVar(value="0 / 0")
+        self.tele_breakdown_var = tk.StringVar(
+            value="present=0 | layer_interp=0 | expert_interp=0 | synth=0"
+        )
+        self.tele_speed_var = tk.StringVar(value="0.0 ten/s (ETA --)")
+        self.tele_elapsed_var = tk.StringVar(value="0.0s")
+        self.progress_var = tk.DoubleVar(value=0.0)
+        self.status_var = tk.StringVar(value="Ready.")
+        self.cli_preview_var = tk.StringVar()
+
+        # Prompt test variables
+        self.test_model_dir_var = tk.StringVar()
+        self.test_prompt_var = tk.StringVar(value="hello")
+        self.test_chat_mode_var = tk.BooleanVar(value=False)
+        self.test_max_tokens_var = tk.IntVar(value=24)
+
+        for v in (
+            self.op_mode_var,
+            self.shard_var,
+            self.index_var,
+            self.config_var,
+            self.model_dir_var,
+            self.output_var,
+            self.export_dir_var,
+            self.auto_bundle_var,
+            self.device_var,
+            self.quant_format_var,
+            self.expert_keep_var,
+        ):
+            v.trace_add("write", lambda *_: self._update_cli_preview())
+
+    def _apply_theme(self) -> None:
+        style = ttk.Style(self.root)
+        if "clam" in style.theme_names():
+            style.theme_use("clam")
+        bg = "#141820"
+        panel = "#1c222d"
+        fg = "#e6edf3"
+        accent = "#3b82f6"
+        self.root.configure(bg=bg)
+        style.configure(".", background=bg, foreground=fg, fieldbackground=panel)
+        style.configure("TFrame", background=bg)
+        style.configure("TLabelframe", background=bg, foreground=fg)
+        style.configure(
+            "TLabelframe.Label",
+            background=bg,
+            foreground="#93c5fd",
+            font=("Sans", 10, "bold"),
+        )
+        style.configure("TLabel", background=bg, foreground=fg)
+        style.configure(
+            "TeleKey.TLabel", background=bg, foreground="#9ca3af", font=("Sans", 9)
+        )
+        style.configure(
+            "TeleVal.TLabel",
+            background=bg,
+            foreground="#60a5fa",
+            font=("Monospace", 9, "bold"),
+        )
+        style.configure("TCheckbutton", background=bg, foreground=fg)
+        style.configure("TRadiobutton", background=bg, foreground=fg)
+        style.configure("TButton", background=panel, foreground=fg, padding=(10, 5))
+        style.map("TButton", background=[("active", accent)])
+        style.configure(
+            "Accent.TButton",
+            background=accent,
+            foreground="#ffffff",
+            font=("Sans", 10, "bold"),
+        )
+        style.configure(
+            "Treeview",
+            background=panel,
+            fieldbackground=panel,
+            foreground=fg,
+            rowheight=23,
+        )
+        style.configure(
+            "Treeview.Heading",
+            background="#262f3f",
+            foreground=fg,
+            font=("Sans", 9, "bold"),
+        )
+        style.map("Treeview", background=[("selected", accent)])
+
+    def _build_layout(self) -> None:
+        outer = ttk.Frame(self.root)
+        outer.pack(fill=tk.BOTH, expand=True)
+        outer.rowconfigure(0, weight=1)
+        outer.columnconfigure(0, weight=1)
+
+        self._canvas = tk.Canvas(outer, bg="#141820", highlightthickness=0)
+        v_scroll = ttk.Scrollbar(outer, orient=tk.VERTICAL, command=self._canvas.yview)
+        h_scroll = ttk.Scrollbar(
+            outer, orient=tk.HORIZONTAL, command=self._canvas.xview
+        )
+        self._canvas.configure(yscrollcommand=v_scroll.set, xscrollcommand=h_scroll.set)
+
+        self._canvas.grid(row=0, column=0, sticky=tk.NSEW)
+        v_scroll.grid(row=0, column=1, sticky=tk.NS)
+        h_scroll.grid(row=1, column=0, sticky=tk.EW)
+
+        main = ttk.Frame(self._canvas, padding=10)
+        self._canvas_win = self._canvas.create_window((0, 0), window=main, anchor=tk.NW)
+
+        def _on_frame_configure(_event=None) -> None:
+            self._canvas.configure(scrollregion=self._canvas.bbox("all"))
+
+        def _on_canvas_configure(event) -> None:
+            req_w = max(event.width, main.winfo_reqwidth())
+            req_h = max(event.height, main.winfo_reqheight())
+            self._canvas.itemconfigure(self._canvas_win, width=req_w, height=req_h)
+
+        main.bind("<Configure>", _on_frame_configure)
+        self._canvas.bind("<Configure>", _on_canvas_configure)
+
+        # 1. Mode & File Paths Card
+        io_frame = ttk.LabelFrame(
+            main,
+            text=" 1. Operation Mode & Model Paths (Works on Any HF Model Architecture) ",
+            padding=10,
+        )
+        io_frame.pack(fill=tk.X, pady=(0, 8))
+        io_frame.columnconfigure(1, weight=1)
+
+        mode_bar = ttk.Frame(io_frame)
+        mode_bar.grid(row=0, column=0, columnspan=3, sticky=tk.W, pady=(0, 8))
+        ttk.Label(mode_bar, text="Workflow:", font=("Sans", 9, "bold")).pack(
+            side=tk.LEFT, padx=(0, 10)
+        )
+        ttk.Radiobutton(
+            mode_bar,
+            text="CheckFree Single-Shard Recovery (1 Shard -> Full Model)",
+            variable=self.op_mode_var,
+            value="recover",
+        ).pack(side=tk.LEFT, padx=(0, 14))
+        ttk.Radiobutton(
+            mode_bar,
+            text="Build Self-Contained SlimShard (Multi-Shard -> 1 SlimShard)",
+            variable=self.op_mode_var,
+            value="build",
+        ).pack(side=tk.LEFT, padx=(0, 14))
+        ttk.Radiobutton(
+            mode_bar,
+            text="Regenerate from SlimShard",
+            variable=self.op_mode_var,
+            value="regenerate",
+        ).pack(side=tk.LEFT)
+
+        self._add_path_row(
+            io_frame,
+            1,
+            "Surviving Shard / Input (.safetensors):",
+            self.shard_var,
+            self._pick_shard,
+        )
+        self._add_path_row(
+            io_frame,
+            2,
+            "Index JSON (optional, auto-inferred if omitted):",
+            self.index_var,
+            self._pick_index,
+        )
+        self._add_path_row(
+            io_frame,
+            3,
+            "Config JSON (auto-detected from folder):",
+            self.config_var,
+            self._pick_config,
+        )
+        self._add_path_row(
+            io_frame,
+            4,
+            "Source Model Dir (for SlimShard Build):",
+            self.model_dir_var,
+            self._pick_model_dir,
+        )
+        self._add_path_row(
+            io_frame,
+            5,
+            "Output .safetensors File:",
+            self.output_var,
+            self._pick_output,
+        )
+        self._add_path_row(
+            io_frame,
+            6,
+            "Export Ready-to-Run HF Bundle Dir:",
+            self.export_dir_var,
+            self._pick_export_dir,
+        )
+
+        # 2. Options & Execution Controls
+        opt_frame = ttk.LabelFrame(
+            main, text=" 2. CheckFree / SlimShard Engine Parameters ", padding=10
+        )
+        opt_frame.pack(fill=tk.X, pady=(0, 8))
+
+        row_opt = ttk.Frame(opt_frame)
+        row_opt.pack(fill=tk.X)
+
+        gpu_lbl = (
+            f"CUDA ({cuda_device_name()})" if cuda_is_available() else "CPU only"
+        )
+        ttk.Label(row_opt, text=f"Compute Device [{gpu_lbl}]:").pack(
+            side=tk.LEFT, padx=(0, 6)
+        )
+        ttk.Combobox(
+            row_opt,
+            textvariable=self.device_var,
+            values=("auto", "cuda", "cpu"),
+            width=8,
+            state="readonly",
+        ).pack(side=tk.LEFT, padx=(0, 16))
+
+        ttk.Label(row_opt, text="SlimShard Format:").pack(side=tk.LEFT, padx=(0, 6))
+        ttk.Combobox(
+            row_opt,
+            textvariable=self.quant_format_var,
+            values=("mixed", "q2_k", "q4_0", "exact"),
+            width=9,
+            state="readonly",
+        ).pack(side=tk.LEFT, padx=(0, 16))
+
+        ttk.Label(row_opt, text="SlimMoE Expert Keep Ratio:").pack(
+            side=tk.LEFT, padx=(0, 6)
+        )
+        ttk.Spinbox(
+            row_opt,
+            from_=0.10,
+            to=1.00,
+            increment=0.05,
+            textvariable=self.expert_keep_var,
+            width=6,
+        ).pack(side=tk.LEFT, padx=(0, 16))
+
+        ttk.Checkbutton(
+            row_opt,
+            text="Export Ready-to-Load HF Directory (symlinks config/tokenizer + model.safetensors)",
+            variable=self.auto_bundle_var,
+        ).pack(side=tk.LEFT, padx=(0, 16))
+
+        btn_bar = ttk.Frame(opt_frame)
+        btn_bar.pack(fill=tk.X, pady=(8, 0))
+        ttk.Button(
+            btn_bar,
+            text="Inspect Shard & Recovery Plan",
+            command=self._inspect_plan,
+        ).pack(side=tk.LEFT, padx=(0, 8))
+        self.run_btn = ttk.Button(
+            btn_bar,
+            text="Run Recovery / Build",
+            style="Accent.TButton",
+            command=self._start_run,
+        )
+        self.run_btn.pack(side=tk.LEFT, padx=(0, 8))
+        self.stop_btn = ttk.Button(
+            btn_bar, text="Stop", command=self._stop_run, state=tk.DISABLED
+        )
+        self.stop_btn.pack(side=tk.LEFT, padx=(0, 14))
+        ttk.Entry(btn_bar, textvariable=self.cli_preview_var, state="readonly").pack(
+            side=tk.LEFT, fill=tk.X, expand=True
+        )
+
+        # 3. Telemetry Dashboard
+        tele = ttk.LabelFrame(main, text=" 3. Real-Time Telemetry ", padding=10)
+        tele.pack(fill=tk.X, pady=(0, 8))
+        tele.columnconfigure(1, weight=1)
+        tele.columnconfigure(3, weight=1)
+
+        ttk.Label(tele, text="Architecture:", style="TeleKey.TLabel").grid(
+            row=0, column=0, sticky=tk.W
+        )
+        ttk.Label(tele, textvariable=self.arch_summary_var, style="TeleVal.TLabel").grid(
+            row=0, column=1, columnspan=3, sticky=tk.W, padx=(6, 0)
+        )
+
+        ttk.Label(tele, text="Layer Coverage:", style="TeleKey.TLabel").grid(
+            row=1, column=0, sticky=tk.W, pady=(3, 0)
+        )
+        ttk.Label(
+            tele, textvariable=self.layers_summary_var, style="TeleVal.TLabel"
+        ).grid(row=1, column=1, columnspan=3, sticky=tk.W, padx=(6, 0), pady=(3, 0))
+
+        ttk.Label(tele, text="Active Tensor:", style="TeleKey.TLabel").grid(
+            row=2, column=0, sticky=tk.W, pady=(3, 0)
+        )
+        ttk.Label(tele, textvariable=self.tele_tensor_var, style="TeleVal.TLabel").grid(
+            row=2, column=1, sticky=tk.W, padx=(6, 0), pady=(3, 0)
+        )
+        ttk.Label(tele, text="Stage / Action:", style="TeleKey.TLabel").grid(
+            row=2, column=2, sticky=tk.W, pady=(3, 0)
+        )
+        ttk.Label(tele, textvariable=self.tele_action_var, style="TeleVal.TLabel").grid(
+            row=2, column=3, sticky=tk.W, padx=(6, 0), pady=(3, 0)
+        )
+
+        ttk.Label(tele, text="Progress:", style="TeleKey.TLabel").grid(
+            row=3, column=0, sticky=tk.W, pady=(3, 0)
+        )
+        ttk.Label(
+            tele, textvariable=self.tele_progress_text_var, style="TeleVal.TLabel"
+        ).grid(row=3, column=1, sticky=tk.W, padx=(6, 0), pady=(3, 0))
+        ttk.Label(tele, text="Throughput / ETA:", style="TeleKey.TLabel").grid(
+            row=3, column=2, sticky=tk.W, pady=(3, 0)
+        )
+        ttk.Label(tele, textvariable=self.tele_speed_var, style="TeleVal.TLabel").grid(
+            row=3, column=3, sticky=tk.W, padx=(6, 0), pady=(3, 0)
+        )
+
+        ttk.Label(tele, text="Breakdown:", style="TeleKey.TLabel").grid(
+            row=4, column=0, sticky=tk.W, pady=(3, 0)
+        )
+        ttk.Label(
+            tele, textvariable=self.tele_breakdown_var, style="TeleVal.TLabel"
+        ).grid(row=4, column=1, sticky=tk.W, padx=(6, 0), pady=(3, 0))
+        ttk.Label(tele, text="Elapsed:", style="TeleKey.TLabel").grid(
+            row=4, column=2, sticky=tk.W, pady=(3, 0)
+        )
+        ttk.Label(
+            tele, textvariable=self.tele_elapsed_var, style="TeleVal.TLabel"
+        ).grid(row=4, column=3, sticky=tk.W, padx=(6, 0), pady=(3, 0))
+
+        ttk.Progressbar(
+            tele, variable=self.progress_var, maximum=100.0, mode="determinate"
+        ).grid(row=5, column=0, columnspan=4, sticky=tk.EW, pady=(8, 0))
+
+        # 4. Tensor Recovery Plan Table
+        tbl_frame = ttk.LabelFrame(
+            main, text=" 4. Tensor Recovery Plan & Status ", padding=10
+        )
+        tbl_frame.pack(fill=tk.BOTH, expand=True, pady=(0, 8))
+
+        fbar = ttk.Frame(tbl_frame)
+        fbar.pack(fill=tk.X, pady=(0, 6))
+        ttk.Label(fbar, text="Filter Action:").pack(side=tk.LEFT, padx=(0, 6))
+        cb_filter = ttk.Combobox(
+            fbar,
+            textvariable=self.filter_action_var,
+            values=(
+                "ALL",
+                "PRESENT",
+                "CHECKFREE_LAYER",
+                "CHECKFREE_EXPERT",
+                "SYNTHESIZE_CALIBRATED",
+                "SUFFIX_PRIOR",
+            ),
+            width=22,
+            state="readonly",
+        )
+        cb_filter.pack(side=tk.LEFT, padx=(0, 14))
+        cb_filter.bind("<<ComboboxSelected>>", lambda *_: self._refresh_table())
+
+        ttk.Label(fbar, text="Search Tensor:").pack(side=tk.LEFT, padx=(0, 6))
+        ent_search = ttk.Entry(fbar, textvariable=self.search_var, width=32)
+        ent_search.pack(side=tk.LEFT, padx=(0, 8))
+        ent_search.bind("<KeyRelease>", lambda *_: self._refresh_table())
+
+        cols = ("idx", "name", "layer", "role", "shard", "action", "dtype", "status")
+        self.tree = ttk.Treeview(
+            tbl_frame, columns=cols, show="headings", height=10, selectmode="browse"
+        )
+        headers = {
+            "idx": ("#", 55),
+            "name": ("Tensor Name", 410),
+            "layer": ("Layer", 65),
+            "role": ("Role", 150),
+            "shard": ("Original Shard", 210),
+            "action": ("Recovery Strategy", 170),
+            "dtype": ("Dtype", 80),
+            "status": ("Status", 95),
+        }
+        for c, (label, w) in headers.items():
+            self.tree.heading(c, text=label)
+            self.tree.column(c, width=w, anchor=tk.W if c != "idx" else tk.E)
+
+        t_scroll = ttk.Scrollbar(tbl_frame, orient=tk.VERTICAL, command=self.tree.yview)
+        self.tree.configure(yscrollcommand=t_scroll.set)
+        self.tree.pack(side=tk.LEFT, fill=tk.BOTH, expand=True)
+        t_scroll.pack(side=tk.RIGHT, fill=tk.Y)
+
+        # 5. Universal Recovered Model Prompt Tester + Log
+        bottom_pane = ttk.PanedWindow(main, orient=tk.HORIZONTAL)
+        bottom_pane.pack(fill=tk.BOTH, expand=True)
+
+        test_frame = ttk.LabelFrame(
+            bottom_pane,
+            text=" 5. Test Recovered Model (Works on Any HF CausalLM) ",
+            padding=10,
+        )
+        bottom_pane.add(test_frame, weight=1)
+
+        t_row1 = ttk.Frame(test_frame)
+        t_row1.pack(fill=tk.X, pady=(0, 4))
+        ttk.Label(t_row1, text="Model Dir:").pack(side=tk.LEFT, padx=(0, 6))
+        ttk.Entry(t_row1, textvariable=self.test_model_dir_var).pack(
+            side=tk.LEFT, fill=tk.X, expand=True, padx=(0, 6)
+        )
+        ttk.Button(t_row1, text="Browse", command=self._pick_test_dir).pack(
+            side=tk.LEFT
+        )
+
+        t_row2 = ttk.Frame(test_frame)
+        t_row2.pack(fill=tk.X, pady=(0, 4))
+        ttk.Label(t_row2, text="Prompt:").pack(side=tk.LEFT, padx=(0, 6))
+        ttk.Entry(t_row2, textvariable=self.test_prompt_var).pack(
+            side=tk.LEFT, fill=tk.X, expand=True, padx=(0, 8)
+        )
+        ttk.Checkbutton(
+            t_row2, text="Chat Template", variable=self.test_chat_mode_var
+        ).pack(side=tk.LEFT, padx=(0, 8))
+        ttk.Label(t_row2, text="Max Tokens:").pack(side=tk.LEFT, padx=(0, 4))
+        ttk.Spinbox(
+            t_row2, from_=1, to=256, textvariable=self.test_max_tokens_var, width=5
+        ).pack(side=tk.LEFT, padx=(0, 8))
+        self.test_btn = ttk.Button(
+            t_row2,
+            text="Run Prompt",
+            style="Accent.TButton",
+            command=self._run_prompt_test,
+        )
+        self.test_btn.pack(side=tk.LEFT)
+
+        self.test_out_text = tk.Text(
+            test_frame,
+            height=8,
+            bg="#0f131a",
+            fg="#a7f3d0",
+            insertbackground="#ffffff",
+            font=("Monospace", 9),
+            wrap=tk.WORD,
+        )
+        self.test_out_text.pack(fill=tk.BOTH, expand=True)
+
+        log_frame = ttk.LabelFrame(bottom_pane, text=" 6. Event Log ", padding=10)
+        bottom_pane.add(log_frame, weight=1)
+        self.log_text = tk.Text(
+            log_frame,
+            height=8,
+            bg="#0f131a",
+            fg="#e6edf3",
+            insertbackground="#ffffff",
+            font=("Monospace", 9),
+            wrap=tk.WORD,
+        )
+        self.log_text.pack(fill=tk.BOTH, expand=True)
+
+    def _add_path_row(
+        self, parent: ttk.Frame, row: int, label: str, var: tk.StringVar, cmd
+    ) -> None:
+        ttk.Label(parent, text=label).grid(row=row, column=0, sticky=tk.W, pady=2)
+        ttk.Entry(parent, textvariable=var).grid(
+            row=row, column=1, sticky=tk.EW, padx=6, pady=2
+        )
+        ttk.Button(parent, text="Browse...", command=cmd).grid(
+            row=row, column=2, sticky=tk.E, pady=2
+        )
+
+    def _auto_populate_defaults(self) -> None:
+        cwd = Path.cwd()
+        raon_shard = cwd / "Raon-1-mini-preview" / "model-00001-of-00007.safetensors"
+        if raon_shard.exists():
+            self._set_shard_and_companions(raon_shard)
+        else:
+            shards = sorted(cwd.glob("*/*.safetensors"))
+            if shards:
+                self._set_shard_and_companions(shards[0])
+
+    def _set_shard_and_companions(self, shard_path: Path) -> None:
+        self.shard_var.set(str(shard_path))
+        parent = shard_path.parent
+        self.model_dir_var.set(str(parent))
+        idx = parent / "model.safetensors.index.json"
+        if idx.exists():
+            self.index_var.set(str(idx))
+        cfg = parent / "config.json"
+        if cfg.exists():
+            self.config_var.set(str(cfg))
+        if not self.output_var.get():
+            self.output_var.set(str(Path.cwd() / f"{parent.name}-recovered.safetensors"))
+        if not self.export_dir_var.get():
+            self.export_dir_var.set(str(Path.cwd() / f"recovered_{parent.name.lower().replace('-', '_')}"))
+            self.test_model_dir_var.set(self.export_dir_var.get())
+
+    def _pick_shard(self) -> None:
+        p = filedialog.askopenfilename(
+            title="Select Surviving .safetensors Shard",
+            filetypes=[("SafeTensors", "*.safetensors"), ("All files", "*.*")],
+        )
+        if p:
+            self._set_shard_and_companions(Path(p))
+            self._inspect_plan()
+
+    def _pick_index(self) -> None:
+        p = filedialog.askopenfilename(
+            title="Select model.safetensors.index.json",
+            filetypes=[("JSON", "*.json"), ("All files", "*.*")],
+        )
+        if p:
+            self.index_var.set(p)
+
+    def _pick_config(self) -> None:
+        p = filedialog.askopenfilename(
+            title="Select config.json",
+            filetypes=[("JSON", "*.json"), ("All files", "*.*")],
+        )
+        if p:
+            self.config_var.set(p)
+
+    def _pick_model_dir(self) -> None:
+        p = filedialog.askdirectory(title="Select HF Model Directory")
+        if p:
+            self.model_dir_var.set(p)
+
+    def _pick_output(self) -> None:
+        p = filedialog.asksaveasfilename(
+            title="Select Output .safetensors Path",
+            defaultextension=".safetensors",
+            filetypes=[("SafeTensors", "*.safetensors"), ("All files", "*.*")],
+        )
+        if p:
+            self.output_var.set(p)
+
+    def _pick_export_dir(self) -> None:
+        p = filedialog.askdirectory(title="Select Export HF Bundle Directory")
+        if p:
+            self.export_dir_var.set(p)
+            self.test_model_dir_var.set(p)
+
+    def _pick_test_dir(self) -> None:
+        p = filedialog.askdirectory(title="Select Recovered HF Model Directory")
+        if p:
+            self.test_model_dir_var.set(p)
+
+    def _update_cli_preview(self) -> None:
+        mode = self.op_mode_var.get()
+        cmd = ["python3", "-m", "hpc_quantize_v2.slimshard", mode]
+        if mode == "recover":
+            if self.shard_var.get():
+                cmd += ["--shard", self.shard_var.get()]
+            if self.index_var.get():
+                cmd += ["--index", self.index_var.get()]
+            if self.config_var.get():
+                cmd += ["--config", self.config_var.get()]
+            if self.output_var.get():
+                cmd += ["--output", self.output_var.get()]
+            if self.auto_bundle_var.get() and self.export_dir_var.get():
+                cmd += ["--export-hf-dir", self.export_dir_var.get()]
+            cmd += ["--device", self.device_var.get()]
+        elif mode == "build":
+            if self.model_dir_var.get():
+                cmd += ["--model-dir", self.model_dir_var.get()]
+            if self.output_var.get():
+                cmd += ["--output", self.output_var.get()]
+            cmd += [
+                "--format",
+                self.quant_format_var.get(),
+                "--expert-keep-ratio",
+                f"{self.expert_keep_var.get():.2f}",
+                "--device",
+                self.device_var.get(),
+            ]
+        else:
+            if self.shard_var.get():
+                cmd += ["--input", self.shard_var.get()]
+            if self.output_var.get():
+                cmd += ["--output", self.output_var.get()]
+        self.cli_preview_var.set(" ".join(shlex.quote(x) for x in cmd))
+
+    def _log(self, msg: str) -> None:
+        self.log_text.insert(tk.END, f"[{_ts()}] {msg}\n")
+        self.log_text.see(tk.END)
+
+    def _inspect_plan(self) -> None:
+        shard = self.shard_var.get().strip()
+        if not shard or not Path(shard).exists():
+            messagebox.showwarning("SlimShard", "Please select a valid .safetensors shard first.")
+            return
+        try:
+            plan = inspect_recovery_plan(
+                shard,
+                index=self.index_var.get().strip() or None,
+                config=self.config_var.get().strip() or None,
+            )
+        except Exception as exc:
+            messagebox.showerror("Inspect Failed", str(exc))
+            return
+
+        archs = ",".join(plan["architectures"]) or plan["model_type"]
+        self.arch_summary_var.set(
+            f"{archs} (type={plan['model_type']}, hidden={plan['hidden_size']}, "
+            f"layers={plan['num_hidden_layers']}, experts={plan['num_experts']}, "
+            f"vocab={plan['vocab_size']}, total_tensors={plan['total_tensors']})"
+        )
+        surv = plan["surviving_layers"]
+        miss = plan["missing_layers"]
+        self.layers_summary_var.set(
+            f"Surviving in shard ({len(surv)}): {surv[:12]}{'...' if len(surv) > 12 else ''}  |  "
+            f"Missing to CheckFree-reconstruct ({len(miss)}): {miss[:12]}{'...' if len(miss) > 12 else ''}"
+        )
+        c = plan["counts"]
+        self.tele_breakdown_var.set(
+            f"present={c.get('PRESENT', 0)} | layer_interp={c.get('CHECKFREE_LAYER', 0)} | "
+            f"expert_interp={c.get('CHECKFREE_EXPERT', 0)} | synth={c.get('SYNTHESIZE_CALIBRATED', 0)}"
+        )
+        self._plan_rows = plan["rows"]
+        self._refresh_table()
+        self._log(
+            f"Inspected {Path(shard).name}: {plan['present_tensors']}/{plan['total_tensors']} present, "
+            f"{len(miss)} layers to reconstruct via CheckFree."
+        )
+
+    def _refresh_table(self) -> None:
+        self.tree.delete(*self.tree.get_children())
+        f_act = self.filter_action_var.get()
+        q = self.search_var.get().strip().lower()
+        shown = 0
+        for idx, r in enumerate(self._plan_rows, 1):
+            if f_act != "ALL" and r["action"] != f_act:
+                continue
+            if q and q not in r["name"].lower() and q not in r["role"].lower():
+                continue
+            self.tree.insert(
+                "",
+                tk.END,
+                iid=r["name"],
+                values=(
+                    idx,
+                    r["name"],
+                    r["layer"],
+                    r["role"],
+                    r["shard"],
+                    r["action"],
+                    r["dtype"],
+                    "Planned",
+                ),
+            )
+            shown += 1
+            if shown >= 1500:
+                break
+
+    def _start_run(self) -> None:
+        if self._worker is not None and self._worker.is_alive():
+            return
+        mode = self.op_mode_var.get()
+        out = self.output_var.get().strip()
+        if not out:
+            messagebox.showwarning("SlimShard", "Please specify an output .safetensors path.")
+            return
+
+        self._stop_event.clear()
+        self._start_time = time.time()
+        self.progress_var.set(0.0)
+        self.run_btn.configure(state=tk.DISABLED)
+        self.stop_btn.configure(state=tk.NORMAL)
+
+        def progress_cb(done: int, total: int, tname: str, action: str, stats: dict) -> None:
+            self._queue.put(("progress", (done, total, tname, action, dict(stats))))
+
+        def worker() -> None:
+            try:
+                if mode == "recover":
+                    shard = self.shard_var.get().strip()
+                    idx = self.index_var.get().strip() or None
+                    cfg = self.config_var.get().strip() or None
+                    exp_dir = (
+                        self.export_dir_var.get().strip()
+                        if self.auto_bundle_var.get() and self.export_dir_var.get().strip()
+                        else None
+                    )
+                    res = recover_from_shard(
+                        shard,
+                        idx,
+                        out,
+                        config=cfg,
+                        device=self.device_var.get(),
+                        verbose=False,
+                        progress_cb=progress_cb,
+                        stop_event=self._stop_event,
+                        export_hf_dir=exp_dir,
+                    )
+                    if exp_dir:
+                        self._queue.put(("set_test_dir", exp_dir))
+                    self._queue.put(("done", ("CheckFree Recovery Complete", res)))
+                elif mode == "build":
+                    mdir = self.model_dir_var.get().strip()
+                    cfg_obj = HPCConfig(device=self.device_var.get(), verbose=False).validate()
+                    res = build_slimshard(
+                        mdir,
+                        out,
+                        cfg=cfg_obj,
+                        quant_format=self.quant_format_var.get(),
+                        expert_keep_ratio=float(self.expert_keep_var.get()),
+                        verbose=False,
+                        progress_cb=progress_cb,
+                        stop_event=self._stop_event,
+                    )
+                    self._queue.put(("done", ("SlimShard Build Complete", res)))
+                else:
+                    shard = self.shard_var.get().strip()
+                    res = regenerate(
+                        shard,
+                        out,
+                        verbose=False,
+                        progress_cb=progress_cb,
+                        stop_event=self._stop_event,
+                    )
+                    self._queue.put(("done", ("SlimShard Regeneration Complete", res)))
+            except Exception as exc:
+                self._queue.put(("error", str(exc)))
+
+        self._worker = threading.Thread(target=worker, daemon=True)
+        self._worker.start()
+        self._log(f"Started {mode} -> {out}")
+
+    def _stop_run(self) -> None:
+        self._stop_event.set()
+        self._log("Cancellation requested...")
+
+    def _run_prompt_test(self) -> None:
+        mdir = self.test_model_dir_var.get().strip() or self.export_dir_var.get().strip()
+        if not mdir or not Path(mdir).exists():
+            messagebox.showwarning(
+                "Model Tester",
+                "Please specify a valid Recovered HF Model Directory first.",
+            )
+            return
+        prompt = self.test_prompt_var.get()
+        use_chat = bool(self.test_chat_mode_var.get())
+        max_new = int(self.test_max_tokens_var.get())
+
+        self.test_btn.configure(state=tk.DISABLED)
+        self.test_out_text.delete("1.0", tk.END)
+        self.test_out_text.insert(
+            tk.END, f"Loading {mdir} and running prompt {prompt!r}...\n"
+        )
+
+        def test_worker() -> None:
+            try:
+                import torch
+                import torch.nn.functional as F
+                from safetensors.torch import safe_open
+                from transformers import AutoConfig, AutoModelForCausalLM, AutoTokenizer
+
+                t0 = time.time()
+                tok = AutoTokenizer.from_pretrained(
+                    mdir, trust_remote_code=True, local_files_only=True
+                )
+                cfg = AutoConfig.from_pretrained(
+                    mdir, trust_remote_code=True, local_files_only=True
+                )
+                st_file = Path(mdir) / "model.safetensors"
+                dev = "cuda:0" if torch.cuda.is_available() else "cpu"
+
+                # Fast on-demand expert streaming for MXFP8 MoE models, or standard load for generic models
+                q_cfg = getattr(cfg, "quantization_config", None) or {}
+                is_mxfp8 = (
+                    isinstance(q_cfg, dict) and q_cfg.get("quant_method") == "mxfp8"
+                ) or getattr(q_cfg, "quant_method", None) == "mxfp8"
+
+                if is_mxfp8 and st_file.exists():
+                    with torch.device("meta"):
+                        model = AutoModelForCausalLM.from_config(
+                            cfg, trust_remote_code=True, dtype=torch.bfloat16
+                        )
+                    sf = safe_open(str(st_file), framework="pt", device="cpu")
+                    for name, _ in list(model.named_parameters()):
+                        if ".moe.experts." in name:
+                            continue
+                        parts = name.split(".")
+                        mod = model
+                        for p in parts[:-1]:
+                            mod = getattr(mod, p)
+                        t = sf.get_tensor(name).to(device=dev)
+                        if t.dtype == torch.float32 and "e_score_correction_bias" not in name:
+                            t = t.to(torch.bfloat16)
+                        setattr(mod, parts[-1], torch.nn.Parameter(t, requires_grad=False))
+
+                    moe_layer = next(
+                        (l for l in model.model.layers if getattr(l, "is_moe", False)),
+                        None,
+                    )
+                    if moe_layer is not None:
+                        mod_cls = type(moe_layer.moe)
+                        raon_mod = __import__(
+                            mod_cls.__module__, fromlist=["dequantize_mxfp8", "situ_glu"]
+                        )
+                        dequantize_mxfp8 = raon_mod.dequantize_mxfp8
+                        situ_glu = raon_mod.situ_glu
+                        for lidx, layer in enumerate(model.model.layers):
+                            if getattr(layer, "is_moe", False):
+                                layer.moe._layer_idx = lidx
+
+                        def fast_moe_forward(self_moe, hidden: torch.Tensor) -> torch.Tensor:
+                            batch, seq, dim = hidden.shape
+                            flat = hidden.reshape(-1, dim)
+                            top, probs = self_moe.gate(flat)
+                            out = torch.zeros(
+                                flat.shape[0], dim, dtype=torch.float32, device=flat.device
+                            )
+                            hit = torch.bincount(
+                                top.flatten(), minlength=self_moe.num_experts
+                            )
+                            prefix = f"model.layers.{self_moe._layer_idx}.moe.experts"
+                            for expert_idx in hit.nonzero().flatten().tolist():
+                                rows, slot = torch.where(top == expert_idx)
+                                x = flat.index_select(0, rows)
+                                ep = f"{prefix}.{expert_idx}"
+                                gw = dequantize_mxfp8(
+                                    sf.get_tensor(f"{ep}.gate_proj.weight").to(dev, non_blocking=True),
+                                    sf.get_tensor(f"{ep}.gate_proj.weight_scale_inv").to(dev, non_blocking=True),
+                                    x.dtype,
+                                )
+                                uw = dequantize_mxfp8(
+                                    sf.get_tensor(f"{ep}.up_proj.weight").to(dev, non_blocking=True),
+                                    sf.get_tensor(f"{ep}.up_proj.weight_scale_inv").to(dev, non_blocking=True),
+                                    x.dtype,
+                                )
+                                dw = dequantize_mxfp8(
+                                    sf.get_tensor(f"{ep}.down_proj.weight").to(dev, non_blocking=True),
+                                    sf.get_tensor(f"{ep}.down_proj.weight_scale_inv").to(dev, non_blocking=True),
+                                    x.dtype,
+                                )
+                                act = situ_glu(
+                                    F.linear(x, gw),
+                                    F.linear(x, uw),
+                                    self_moe.gate_beta,
+                                    self_moe.value_beta,
+                                ).to(x.dtype)
+                                out.index_add_(
+                                    0,
+                                    rows,
+                                    F.linear(act, dw).float()
+                                    * probs[rows, slot].unsqueeze(-1),
+                                )
+                            out = out.to(hidden.dtype)
+                            if self_moe.shared_experts is not None:
+                                out = out + self_moe.shared_experts(flat)
+                            return out.reshape(batch, seq, dim)
+
+                        mod_cls.forward = fast_moe_forward
+                else:
+                    model = AutoModelForCausalLM.from_pretrained(
+                        mdir,
+                        trust_remote_code=True,
+                        local_files_only=True,
+                        dtype="auto",
+                        device_map="auto",
+                    )
+
+                model.eval()
+                with torch.no_grad():
+                    if use_chat and getattr(tok, "chat_template", None):
+                        inputs = tok.apply_chat_template(
+                            [{"role": "user", "content": prompt}],
+                            add_generation_prompt=True,
+                            tokenize=True,
+                            return_dict=True,
+                            return_tensors="pt",
+                            enable_thinking=False,
+                        ).to(dev)
+                        in_len = inputs["input_ids"].shape[-1]
+                        out_ids = model.generate(
+                            **inputs,
+                            max_new_tokens=max_new,
+                            do_sample=False,
+                            use_cache=True,
+                            pad_token_id=tok.eos_token_id,
+                        )
+                        decoded = tok.decode(out_ids[0][in_len:], skip_special_tokens=False)
+                    else:
+                        ids = tok(prompt, return_tensors="pt")["input_ids"].to(dev)
+                        out_ids = model.generate(
+                            ids,
+                            max_new_tokens=max_new,
+                            do_sample=False,
+                            use_cache=True,
+                            pad_token_id=tok.eos_token_id,
+                        )
+                        decoded = tok.decode(out_ids[0], skip_special_tokens=False)
+
+                dt_s = time.time() - t0
+                self._queue.put(
+                    (
+                        "test_done",
+                        f"Completed in {dt_s:.2f}s:\n{decoded}\n\nToken IDs: {out_ids[0].tolist()}",
+                    )
+                )
+            except Exception as exc:
+                self._queue.put(("test_done", f"Error: {exc}"))
+
+        threading.Thread(target=test_worker, daemon=True).start()
+
+    def _poll_queue(self) -> None:
+        try:
+            while True:
+                kind, payload = self._queue.get_nowait()
+                if kind == "progress":
+                    done, total, tname, action, stats = payload
+                    pct = 100.0 * float(done) / float(max(total, 1))
+                    self.progress_var.set(pct)
+                    self.tele_tensor_var.set(tname)
+                    self.tele_action_var.set(action)
+                    self.tele_progress_text_var.set(f"{done} / {total} ({pct:.1f}%)")
+                    elapsed = max(time.time() - (self._start_time or time.time()), 1.0e-3)
+                    rate = float(done) / elapsed
+                    eta = float(max(total - done, 0)) / max(rate, 1.0e-6)
+                    self.tele_speed_var.set(f"{rate:.1f} ten/s (ETA {_fmt_eta(eta)})")
+                    self.tele_elapsed_var.set(_fmt_eta(elapsed))
+                    if "present" in stats:
+                        self.tele_breakdown_var.set(
+                            f"present={stats.get('present', 0)} | "
+                            f"layer_interp={stats.get('checkfree_interpolated', 0)} | "
+                            f"expert_interp={stats.get('expert_interpolated', 0)} | "
+                            f"synth={stats.get('synthesized', 0)}"
+                        )
+                    if self.tree.exists(tname):
+                        vals = list(self.tree.item(tname, "values"))
+                        vals[-1] = "Done"
+                        self.tree.item(tname, values=vals)
+                elif kind == "set_test_dir":
+                    self.test_model_dir_var.set(str(payload))
+                elif kind == "done":
+                    title, stats = payload
+                    elapsed = time.time() - (self._start_time or time.time())
+                    self.progress_var.set(100.0)
+                    self.tele_action_var.set("Completed")
+                    self.tele_elapsed_var.set(_fmt_eta(elapsed))
+                    self.run_btn.configure(state=tk.NORMAL)
+                    self.stop_btn.configure(state=tk.DISABLED)
+                    self._log(f"{title} in {_fmt_eta(elapsed)}: {stats}")
+                elif kind == "error":
+                    self.tele_action_var.set("Error / Stopped")
+                    self.run_btn.configure(state=tk.NORMAL)
+                    self.stop_btn.configure(state=tk.DISABLED)
+                    self._log(f"ERROR: {payload}")
+                    messagebox.showerror("SlimShard Error", str(payload))
+                elif kind == "test_done":
+                    self.test_btn.configure(state=tk.NORMAL)
+                    self.test_out_text.delete("1.0", tk.END)
+                    self.test_out_text.insert(tk.END, str(payload))
+                    self._log("Prompt evaluation finished.")
+        except queue.Empty:
+            pass
+        self.root.after(80, self._poll_queue)
+
+
+def launch_slimshard_gui(parent: tk.Tk | None = None) -> SlimShardGUI:
+    if parent is not None:
+        win = tk.Toplevel(parent)
+        return SlimShardGUI(win)
+    root = tk.Tk()
+    app = SlimShardGUI(root)
+    root.mainloop()
+    return app
+
+
+if __name__ == "__main__":
+    launch_slimshard_gui()