Document and validate BF16-shared online K6 revision

## Summary

Follow up the BF16-shared checkpoint revision with reproducible lineage,
independent runtime evidence, focused converter tests, and two metadata
corrections. This PR does not replace or upload any model shard.

## Metadata corrections

- Set safetensors `metadata.total_size` to **346,196,508,248**, the sum of all
186,905 tensor payloads parsed from the 157 shard headers. The current value
is 22,130,880 bytes too high.
- Preserve the old R7 assembly manifest as `SOURCE_R7_MANIFEST.json` and remove
its stale seals. It describes the parent layout (187,580 tensors and 75
rewritten carriers through layer 77), not the current BF16-shared layout
(186,905 tensors and 76 carriers through layer 78).

## Reproducibility and validation

- Add the source/donor revisions, hashes, central-shard identity, byte
accounting, validation totals, and an exact 228-tensor comparison of the
canonical central shard against the pinned BF16 donor.
- Add a converter matching the canonical central-shard layout and focused
tests for carrier rewriting, metadata ownership, and manifest lifecycle.
- Record the independent TP4 MTP0/MTP3, prefill, CUDA-graph, memory, and paired
KLD validation that motivated the canonical revision.

Checks: **3 passed**; Ruff check and format passed; all JSON parsed; the
corrected `total_size` was independently recomputed from every safetensors
header.

This supersedes PR #2, which was uploaded from the old parent concurrently
with the canonical BF16-shared commit and therefore conflicts with it.

.manifest_verified

@@ -1 +0,0 @@
-bfb6dc39f28da08c1cfc5b89603414046adf7003152d69e9ee350e11f7a1fa63

BF16_SHARED_ONLINE_K6_VALIDATION.md

@@ -0,0 +1,126 @@
+# BF16 shared experts with runtime-merged K6
+
+Date: 2026-08-10
+
+## Canonical checkpoint layout
+
+Revision `9ab9579774cc432df91567a36f6e9e863e0d4c9f` keeps the routed R7
+K3/K4/K5 expert payload and rotations unchanged. It removes the separate
+shared-expert K6 payloads from layers 3-77 and moves all original BF16 shared
+experts from layers 3-78 into one `model-sharedbf16.safetensors` shard.
+
+Header-only safetensors inspection of that revision found:
+
+| Check | Result |
+|---|---:|
+| BF16 shared tensors | 228 |
+| Covered layers | 3-78 |
+| Non-BF16 or unexpected tensors | 0 |
+| Tensor payload bytes | 5,737,807,872 |
+| Central shard file bytes | 5,737,837,256 |
+| Central shard SHA-256 | `ee1e7d9b2adb5d49c0895dc2f4b7d6d424b108cdb796879eee4c55d040408c6a` |
+
+The canonical central shard was also downloaded at the pinned revision and
+all 228 tensors were compared element-for-element with the pinned BF16 donor.
+Every tensor matched.
+
+The runtime concatenates each BF16 gate/up pair before online K6 encoding, so
+it executes one merged `gate_up_proj` instead of two separately encoded
+matrices. The first load writes a content-addressed cache; warm loads reuse it.
+
+## Independent runtime validation
+
+The independent POC used the same 228 BF16 tensors and the same runtime tensor
+map. Its only physical difference was storing layers 3-77 back in their layer
+carrier shards; physical shard placement does not change loaded tensors or
+kernel selection.
+
+All 228 BF16 tensors in the independent POC were also compared exactly with
+`willfalco/GLM-5.2-EXL3-TR3-3.42bpw@a350292cb2038f2c31732569a711a89e5d72fd46`
+and an independent 3.25 bpw lineage checkpoint. The conversion replaced 225
+prequantized tensors in layers 3-77 and validated the three existing BF16
+tensors in layer 78.
+
+A clean TP4 load encoded exactly 300 merged `gate_up_proj` and 300 `down_proj`
+matrices: 75 routed layers on four ranks. Warm restarts performed zero encodes.
+MTP0 and MTP3 both produced coherent output.
+
+### MTP0 decode
+
+Four RTX PRO 6000 Blackwell GPUs on independent PCIe root ports, TP4/DCP1,
+A16, online K6, NVFP4 DS-MLA KV, 20-second sustained runs:
+
+| Concurrency | Separate shared K6 | BF16 + merged K6 | Delta |
+|---:|---:|---:|---:|
+| C1 | 50.62 tok/s | 53.67 tok/s | +6.0% |
+| C4 | 157.34 tok/s | 170.04 tok/s | +8.1% |
+| C8 | 258.81 tok/s | 279.75 tok/s | +8.1% |
+
+A separate 40-second C1 run measured 54.03 tok/s. This controlled MTP0 A/B
+isolates the merged shared-expert change.
+
+### Prefill
+
+| Prompt | Separate shared K6 | BF16 + merged K6 | Delta |
+|---:|---:|---:|---:|
+| 8.2k | 3,280 tok/s | 3,265 tok/s | -0.5% |
+| 64.4k | 3,034 tok/s | 3,254 tok/s | +7.3% |
+
+The 8k result is parity. Each 64k value is one long sample, so that uplift is
+indicative rather than a standalone release claim.
+
+### Quality
+
+The paired 2,047-position full-vocabulary test used the same BF16 teacher, FP8
+KV cache, and three repeats per candidate.
+
+| Candidate | Mean KLD | Run SD |
+|---|---:|---:|
+| Original R7 + online K6 | 0.064467 | 0.001973 |
+| BF16 source + online K6 | 0.065339 | 0.001285 |
+
+The absolute mean difference is 0.000873, smaller than observed run-to-run
+variation, and the run distributions overlap. This independent gate found no
+measurable quality regression from the BF16-source merge. The repository README
+also records the canonical revision's separate five-run KLD gate.
+
+### CUDA graphs and memory
+
+- MTP0 target steps were captured in full CUDA graphs.
+- MTP3 target verification and all three draft forwards were captured in full
+  CUDA graphs, with no eager fallback in the trace.
+- No new host synchronization or K6 bottleneck appeared.
+- At a 65,536-token model limit, MTP0 at GMU 0.97 exposed 79,104 KV tokens.
+- MTP3 at GMU 0.98 exposed 75,072 KV tokens.
+
+## Metadata correction
+
+The first BF16-shared commit wrote `metadata.total_size=346218639128` in the
+safetensors index. Parsing all 157 safetensors headers gives exactly
+`346196508248` tensor payload bytes, a difference of 22,130,880 bytes. The
+follow-up uses the computed tensor-byte value.
+
+The old `MANIFEST.json` describes the parent R7 assembly: 187,580 tensors and
+75 rewritten carriers ending at layer 77. The BF16-shared revision has 186,905
+tensors and rewrites 76 carriers through layer 78. Rather than silently mutate
+the old schema, the follow-up preserves it as `SOURCE_R7_MANIFEST.json` and
+removes its no-longer-current verification seals.
+
+## Reproduction
+
+The converter and focused tests are under `reproducibility/bf16-shared/`:
+
+```bash
+python reproducibility/bf16-shared/build_shared_bf16_revision.py \
+  --source /path/to/parent-c55c1cd \
+  --source-repo-id brandonmusic/GLM-5.2-EXL3-TR3v4-3.5bpw-MTP78 \
+  --source-revision c55c1cd4ca4216c27b0dddb51a4c6757c1765d1e \
+  --donor /path/to/GLM-5.2-EXL3-TR3-3.42bpw \
+  --donor-repo-id willfalco/GLM-5.2-EXL3-TR3-3.42bpw \
+  --donor-revision a350292cb2038f2c31732569a711a89e5d72fd46 \
+  --output /path/to/output
+```
+
+Serve through the compatible Gilded Gnosis R7 helper with
+`MODEL_FAMILY=glm52-exl3`, `QUANTIZATION=exl3`, and
+`ONLINE_QUANT=exl3-b6`. Keep `JIT_CACHE` persistent.

R7_BF16_SHARED_DERIVATION.json

@@ -0,0 +1,33 @@
+{
+  "added_bf16_tensor_bytes": 5737807872,
+  "canonical_revision": "9ab9579774cc432df91567a36f6e9e863e0d4c9f",
+  "canonical_tensors_compared_to_donor": 228,
+  "central_shard": {
+    "file_bytes": 5737837256,
+    "path": "model-sharedbf16.safetensors",
+    "sha256": "ee1e7d9b2adb5d49c0895dc2f4b7d6d424b108cdb796879eee4c55d040408c6a",
+    "tensor_bytes": 5737807872,
+    "tensors": 228
+  },
+  "donor_config_sha256": "7d42e3a21873412b39c3741e5b9166362d25b05f40c0e66a968e79d422c7dea1",
+  "donor_index_sha256": "b34398df3830a13d23e25a9582112d38f7da982a48d50b95bc7e0867c94e9fdc",
+  "donor_repo_id": "willfalco/GLM-5.2-EXL3-TR3-3.42bpw",
+  "donor_revision": "a350292cb2038f2c31732569a711a89e5d72fd46",
+  "indexed_tensors": 186905,
+  "output_tensor_bytes": 346196508248,
+  "removed_source_shared_tensor_bytes": 2202551172,
+  "replaced_layers": "3-78",
+  "replaced_projections": ["down_proj", "gate_proj", "up_proj"],
+  "runtime_intent": "ONLINE_QUANT=exl3-b6",
+  "source_config_sha256": "a231e816fb3495a33ba4f89b5cb7d2ffc86f0c66f71a42a0e792dead3868bf5c",
+  "source_index_sha256": "3077bb6d01f0831c62775d0504b06c45989d2efe8fec944ab50ed911902e5678",
+  "source_manifest_sha256": "df2f4c87b22c21c5234ef216149f5b5adc556820bb97ae4bc6dd7f4f0647b8db",
+  "source_repo_id": "brandonmusic/GLM-5.2-EXL3-TR3v4-3.5bpw-MTP78",
+  "source_revision": "c55c1cd4ca4216c27b0dddb51a4c6757c1765d1e",
+  "validation": {
+    "bf16_shared_tensors": 228,
+    "covered_layers": [3, 78],
+    "non_bf16_or_unexpected_tensors": 0,
+    "stale_shared_exl3_records": 0
+  }
+}

README.md

@@ -100,6 +100,10 @@ The pre-update revision remains available at
 [`c55c1cd4ca42`](https://huggingface.co/brandonmusic/GLM-5.2-EXL3-TR3v4-3.5bpw-MTP78/tree/c55c1cd4ca4216c27b0dddb51a4c6757c1765d1e)
 if you need the old offline-encoded shared payloads.
 
+The exact source lineage, independent TP4 validation, conversion tool, and
+focused tests are recorded in
+[BF16_SHARED_ONLINE_K6_VALIDATION.md](./BF16_SHARED_ONLINE_K6_VALIDATION.md).
+
 ## Run it
 
 Docker image (public on Docker Hub):

MANIFEST.sha256 → SOURCE_R7_MANIFEST.sha256

@@ -1 +1 @@
-df2f4c87b22c21c5234ef216149f5b5adc556820bb97ae4bc6dd7f4f0647b8db  MANIFEST.json
+df2f4c87b22c21c5234ef216149f5b5adc556820bb97ae4bc6dd7f4f0647b8db  SOURCE_R7_MANIFEST.json

model.safetensors.index.json

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:9fd852f69ed64442e31dce1cbc5fe7acd0a76bfb848e945d272fe98d00d0c9cd
-size 16284633
+oid sha256:20ed38193742d442a5ba444b07945527d49b5d68f152aa88131adf668ca54727
+size 16284634

reproducibility/bf16-shared/build_shared_bf16_revision.py

@@ -0,0 +1,368 @@
+#!/usr/bin/env python3
+"""Build the R7 BF16-shared checkpoint from its parent and BF16 donor."""
+
+from __future__ import annotations
+
+import argparse
+import copy
+import hashlib
+import json
+import os
+import shutil
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import torch
+from safetensors import safe_open
+from safetensors.torch import save_file
+
+
+PROJECTIONS = ("down_proj", "gate_proj", "up_proj")
+SHARED_LAYERS = tuple(range(3, 79))
+QUANTIZED_SHARED_LAYERS = tuple(range(3, 78))
+CENTRAL_SHARD = "model-sharedbf16.safetensors"
+
+
+def _json(path: Path) -> dict[str, Any]:
+    with path.open(encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def _atomic_json(path: Path, value: Any) -> None:
+    fd, temporary_name = tempfile.mkstemp(
+        dir=path.parent, prefix=f".{path.name}.", suffix=".tmp"
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(value, handle, indent=1)
+            handle.write("\n")
+        os.replace(temporary_name, path)
+    except BaseException:
+        try:
+            os.unlink(temporary_name)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def _atomic_text(path: Path, value: str) -> None:
+    fd, temporary_name = tempfile.mkstemp(
+        dir=path.parent, prefix=f".{path.name}.", suffix=".tmp"
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(value)
+        os.replace(temporary_name, path)
+    except BaseException:
+        try:
+            os.unlink(temporary_name)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _shared_prefix(layer: int) -> str:
+    return f"model.layers.{layer}.mlp.shared_experts."
+
+
+def _bf16_names(layer: int) -> tuple[str, ...]:
+    prefix = _shared_prefix(layer)
+    return tuple(f"{prefix}{projection}.weight" for projection in PROJECTIONS)
+
+
+def _copy_tree_with_hardlinked_weights(source: Path, output: Path) -> None:
+    if output.exists():
+        raise FileExistsError(f"output already exists: {output}")
+    if (source / CENTRAL_SHARD).exists():
+        raise ValueError("source already contains the BF16 shared shard")
+    output.mkdir(parents=True)
+    for source_path in source.rglob("*"):
+        relative = source_path.relative_to(source)
+        output_path = output / relative
+        if source_path.is_dir():
+            output_path.mkdir(exist_ok=True)
+        elif source_path.suffix == ".safetensors":
+            os.link(source_path, output_path)
+        else:
+            shutil.copy2(source_path, output_path)
+
+
+def _strip_shared_from_carrier(
+    *, layer: int, source_file: Path, output_file: Path
+) -> tuple[list[str], int]:
+    prefix = _shared_prefix(layer)
+    expected = 12 if layer in QUANTIZED_SHARED_LAYERS else 3
+    with safe_open(source_file, framework="pt", device="cpu") as handle:
+        keys = list(handle.keys())
+        removed = [key for key in keys if key.startswith(prefix)]
+        if len(removed) != expected:
+            raise ValueError(
+                f"layer {layer}: expected {expected} shared tensors, "
+                f"found {len(removed)}"
+            )
+        tensors = {
+            key: handle.get_tensor(key) for key in keys if not key.startswith(prefix)
+        }
+        removed_bytes = sum(
+            handle.get_tensor(key).numel() * handle.get_tensor(key).element_size()
+            for key in removed
+        )
+        metadata = handle.metadata()
+
+    temporary = output_file.with_name(f".{output_file.name}.rewrite.tmp")
+    try:
+        save_file(tensors, temporary, metadata=metadata)
+        os.replace(temporary, output_file)
+    finally:
+        temporary.unlink(missing_ok=True)
+    return removed, removed_bytes
+
+
+def _load_donor_shared(
+    donor: Path, donor_weight_map: dict[str, str]
+) -> dict[str, torch.Tensor]:
+    wanted = {name for layer in SHARED_LAYERS for name in _bf16_names(layer)}
+    by_file: dict[str, list[str]] = {}
+    for name in wanted:
+        by_file.setdefault(donor_weight_map[name], []).append(name)
+
+    tensors: dict[str, torch.Tensor] = {}
+    for file_name, names in sorted(by_file.items()):
+        with safe_open(donor / file_name, framework="pt", device="cpu") as handle:
+            for name in sorted(names):
+                tensor = handle.get_tensor(name)
+                if tensor.dtype != torch.bfloat16:
+                    raise TypeError(f"{name} is {tensor.dtype}, expected bfloat16")
+                tensors[name] = tensor
+    if len(tensors) != len(SHARED_LAYERS) * len(PROJECTIONS):
+        raise ValueError(f"expected 228 donor tensors, found {len(tensors)}")
+    return tensors
+
+
+def _patch_config(
+    source_config: dict[str, Any],
+    *,
+    quantized_shared_layers: tuple[int, ...] = QUANTIZED_SHARED_LAYERS,
+) -> dict[str, Any]:
+    config = copy.deepcopy(source_config)
+    storage = config["quantization_config"]["tensor_storage"]
+    removed = [
+        key
+        for key in storage
+        if ".mlp.shared_experts." in key
+        and int(key.split(".layers.", 1)[1].split(".", 1)[0]) in quantized_shared_layers
+    ]
+    if len(removed) != len(quantized_shared_layers) * len(PROJECTIONS):
+        raise ValueError(f"expected 225 shared storage records, found {len(removed)}")
+    for key in removed:
+        del storage[key]
+    return config
+
+
+def _archive_source_manifest(output: Path) -> str | None:
+    manifest = output / "MANIFEST.json"
+    if not manifest.exists():
+        (output / "MANIFEST.sha256").unlink(missing_ok=True)
+        (output / ".manifest_verified").unlink(missing_ok=True)
+        return None
+
+    digest = _sha256(manifest)
+    archived = output / "SOURCE_R7_MANIFEST.json"
+    manifest.replace(archived)
+    _atomic_text(
+        output / "SOURCE_R7_MANIFEST.sha256",
+        f"{digest}  {archived.name}\n",
+    )
+    (output / "MANIFEST.sha256").unlink(missing_ok=True)
+    (output / ".manifest_verified").unlink(missing_ok=True)
+    return digest
+
+
+def _actual_weight_map(checkpoint: Path) -> tuple[dict[str, str], int]:
+    weight_map: dict[str, str] = {}
+    tensor_bytes = 0
+    for shard in sorted(checkpoint.glob("*.safetensors")):
+        with safe_open(shard, framework="pt", device="cpu") as handle:
+            for key in handle.keys():
+                previous = weight_map.setdefault(key, shard.name)
+                if previous != shard.name:
+                    raise ValueError(f"tensor {key} occurs in two shards")
+                tensor = handle.get_tensor(key)
+                tensor_bytes += tensor.numel() * tensor.element_size()
+    return weight_map, tensor_bytes
+
+
+def _validate(*, source: Path, donor: Path, output: Path) -> dict[str, int]:
+    source_config = _json(source / "config.json")
+    output_config = _json(output / "config.json")
+    if (
+        source_config["quantization_config"]["r7_routed_experts"]
+        != output_config["quantization_config"]["r7_routed_experts"]
+    ):
+        raise ValueError("r7_routed_experts metadata changed")
+    if output_config["quantization_config"] != _json(
+        output / "quantization_config.json"
+    ):
+        raise ValueError("embedded and standalone quantization configs differ")
+
+    stale_storage = [
+        key
+        for key in output_config["quantization_config"]["tensor_storage"]
+        if ".mlp.shared_experts." in key
+    ]
+    if stale_storage:
+        raise ValueError(f"stale shared storage entries: {stale_storage[:4]}")
+
+    index = _json(output / "model.safetensors.index.json")
+    actual, tensor_bytes = _actual_weight_map(output)
+    if index["weight_map"] != actual:
+        raise ValueError("safetensors index does not match checkpoint files")
+    if index["metadata"]["total_size"] != tensor_bytes:
+        raise ValueError("index total_size does not equal tensor payload bytes")
+
+    shared = {
+        key: file_name
+        for key, file_name in actual.items()
+        if ".mlp.shared_experts." in key
+    }
+    if len(shared) != 228 or set(shared.values()) != {CENTRAL_SHARD}:
+        raise ValueError("shared experts are not isolated in the central shard")
+
+    donor_map = _json(donor / "model.safetensors.index.json")["weight_map"]
+    compared = 0
+    with safe_open(
+        output / CENTRAL_SHARD, framework="pt", device="cpu"
+    ) as output_handle:
+        for name in sorted(shared):
+            if output_handle.get_tensor(name).dtype != torch.bfloat16:
+                raise TypeError(f"{name} is not BF16")
+            with safe_open(
+                donor / donor_map[name], framework="pt", device="cpu"
+            ) as donor_handle:
+                if not torch.equal(
+                    output_handle.get_tensor(name), donor_handle.get_tensor(name)
+                ):
+                    raise ValueError(f"derived tensor differs from donor: {name}")
+            compared += 1
+
+    return {
+        "indexed_tensors": len(actual),
+        "tensor_bytes": tensor_bytes,
+        "bf16_shared_tensors": len(shared),
+        "donor_tensors_compared": compared,
+    }
+
+
+def build(args: argparse.Namespace) -> dict[str, Any]:
+    source = args.source.resolve()
+    donor = args.donor.resolve()
+    output = args.output.resolve()
+    _copy_tree_with_hardlinked_weights(source, output)
+
+    source_index_path = source / "model.safetensors.index.json"
+    source_index = _json(source_index_path)
+    donor_index = _json(donor / "model.safetensors.index.json")
+    weight_map = copy.deepcopy(source_index["weight_map"])
+    removed_bytes = 0
+
+    for layer in SHARED_LAYERS:
+        old_names = [key for key in weight_map if key.startswith(_shared_prefix(layer))]
+        expected = 12 if layer in QUANTIZED_SHARED_LAYERS else 3
+        if len(old_names) != expected:
+            raise ValueError(
+                f"layer {layer}: expected {expected} indexed shared tensors, "
+                f"found {len(old_names)}"
+            )
+        source_files = {weight_map[name] for name in old_names}
+        if len(source_files) != 1:
+            raise ValueError(f"layer {layer}: shared tensors span {source_files}")
+        source_file_name = source_files.pop()
+        removed, removed_layer_bytes = _strip_shared_from_carrier(
+            layer=layer,
+            source_file=source / source_file_name,
+            output_file=output / source_file_name,
+        )
+        if set(removed) != set(old_names):
+            raise ValueError(f"layer {layer}: index and carrier disagree")
+        removed_bytes += removed_layer_bytes
+        for name in old_names:
+            del weight_map[name]
+
+    shared = _load_donor_shared(donor, donor_index["weight_map"])
+    temporary = output / f".{CENTRAL_SHARD}.tmp"
+    try:
+        save_file(shared, temporary)
+        os.replace(temporary, output / CENTRAL_SHARD)
+    finally:
+        temporary.unlink(missing_ok=True)
+    added_bytes = sum(
+        tensor.numel() * tensor.element_size() for tensor in shared.values()
+    )
+    for name in shared:
+        weight_map[name] = CENTRAL_SHARD
+
+    source_total = int(source_index["metadata"]["total_size"])
+    source_index["metadata"]["total_size"] = source_total - removed_bytes + added_bytes
+    source_index["weight_map"] = dict(sorted(weight_map.items()))
+    _atomic_json(output / "model.safetensors.index.json", source_index)
+
+    patched_config = _patch_config(_json(source / "config.json"))
+    _atomic_json(output / "config.json", patched_config)
+    _atomic_json(
+        output / "quantization_config.json", patched_config["quantization_config"]
+    )
+    source_manifest_sha256 = _archive_source_manifest(output)
+    validation = _validate(source=source, donor=donor, output=output)
+
+    derivation = {
+        "created_utc": datetime.now(timezone.utc).isoformat(),
+        "source": str(source),
+        "source_repo_id": args.source_repo_id,
+        "source_revision": args.source_revision,
+        "source_config_sha256": _sha256(source / "config.json"),
+        "source_index_sha256": _sha256(source_index_path),
+        "source_manifest_sha256": source_manifest_sha256,
+        "donor": str(donor),
+        "donor_repo_id": args.donor_repo_id,
+        "donor_revision": args.donor_revision,
+        "donor_config_sha256": _sha256(donor / "config.json"),
+        "donor_index_sha256": _sha256(donor / "model.safetensors.index.json"),
+        "removed_source_shared_tensor_bytes": removed_bytes,
+        "added_bf16_tensor_bytes": added_bytes,
+        "runtime_intent": "ONLINE_QUANT=exl3-b6",
+        "validation": validation,
+    }
+    _atomic_json(output / "R7_BF16_SHARED_DERIVATION.json", derivation)
+    return derivation
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--source", type=Path, required=True)
+    parser.add_argument("--donor", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--source-repo-id")
+    parser.add_argument("--source-revision")
+    parser.add_argument("--donor-repo-id")
+    parser.add_argument("--donor-revision")
+    return parser.parse_args()
+
+
+def main() -> int:
+    result = build(parse_args())
+    print(json.dumps(result, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

reproducibility/bf16-shared/independent-kld-summary.json

@@ -0,0 +1,66 @@
+{
+  "kv_cache_dtype": "fp8",
+  "label": "bf16-shared-online-k6-fp8-r3",
+  "mean_kld": 0.06533933927615483,
+  "model": "R7 BF16-shared runtime-equivalent POC",
+  "quantization_config": {
+    "ignore": [
+      "re:.*\\.fused_qkv_a_proj$",
+      "re:.*\\.q_a_proj$",
+      "re:.*kv_a_proj_with_mqa",
+      "re:.*\\.mlp\\.gate$",
+      "model.layers.78.eh_proj",
+      "lm_head"
+    ],
+    "linear": {
+      "weight": "mxfp8"
+    },
+    "shared_experts": {
+      "weight": "mxfp8"
+    }
+  },
+  "reference_logits": "paired BF16 teacher fixture",
+  "results": [
+    {
+      "elapsed_sec": 139.84551430889405,
+      "mean_kld": 0.06484639644622803,
+      "positions": 2047,
+      "run": 1,
+      "sd_across_positions": 0.25165143609046936
+    },
+    {
+      "elapsed_sec": 177.6037294138223,
+      "mean_kld": 0.06437408179044724,
+      "positions": 2047,
+      "run": 2,
+      "sd_across_positions": 0.2576864957809448
+    },
+    {
+      "elapsed_sec": 101.13696675701067,
+      "mean_kld": 0.06679753959178925,
+      "positions": 2047,
+      "run": 3,
+      "sd_across_positions": 0.27730751037597656
+    }
+  ],
+  "run_sd": 0.0012847300899035373,
+  "supports_prompt_logits": false,
+  "token_first16": [
+    284,
+    8396,
+    425,
+    10960,
+    465,
+    284,
+    14721,
+    8396,
+    425,
+    10960,
+    465,
+    374,
+    458,
+    6364,
+    4531,
+    1154
+  ]
+}

reproducibility/bf16-shared/test_build_shared_bf16_revision.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import os
+from pathlib import Path
+
+import torch
+from safetensors import safe_open
+from safetensors.torch import save_file
+
+
+SCRIPT = Path(__file__).with_name("build_shared_bf16_revision.py")
+SPEC = importlib.util.spec_from_file_location("build_shared_bf16_revision", SCRIPT)
+assert SPEC is not None and SPEC.loader is not None
+MODULE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(MODULE)
+
+
+def test_strip_quantized_shared_tensors_preserves_other_tensors(
+    tmp_path: Path,
+) -> None:
+    layer = 3
+    prefix = MODULE._shared_prefix(layer)
+    source_file = tmp_path / "source.safetensors"
+    output_file = tmp_path / "output.safetensors"
+    tensors = {"model.layers.3.other.weight": torch.arange(8, dtype=torch.float16)}
+    for projection in MODULE.PROJECTIONS:
+        tensors[f"{prefix}{projection}.mcg"] = torch.tensor(0, dtype=torch.int32)
+        tensors[f"{prefix}{projection}.suh"] = torch.arange(4, dtype=torch.float16)
+        tensors[f"{prefix}{projection}.svh"] = torch.arange(2, dtype=torch.float16)
+        tensors[f"{prefix}{projection}.trellis"] = torch.arange(
+            8, dtype=torch.int16
+        ).reshape(2, 2, 2)
+    save_file(tensors, source_file, metadata={"origin": "r7"})
+    os.link(source_file, output_file)
+
+    removed, removed_bytes = MODULE._strip_shared_from_carrier(
+        layer=layer, source_file=source_file, output_file=output_file
+    )
+
+    assert len(removed) == 12
+    assert removed_bytes == sum(
+        value.numel() * value.element_size()
+        for name, value in tensors.items()
+        if name.startswith(prefix)
+    )
+    with safe_open(source_file, framework="pt", device="cpu") as handle:
+        assert len([name for name in handle.keys() if name.startswith(prefix)]) == 12
+    with safe_open(output_file, framework="pt", device="cpu") as handle:
+        assert handle.metadata() == {"origin": "r7"}
+        assert not any(name.startswith(prefix) for name in handle.keys())
+        assert torch.equal(
+            handle.get_tensor("model.layers.3.other.weight"),
+            tensors["model.layers.3.other.weight"],
+        )
+
+
+def test_patch_config_changes_only_shared_tensor_ownership() -> None:
+    storage = {
+        f"model.layers.3.mlp.shared_experts.{projection}": {"format": "exl3"}
+        for projection in MODULE.PROJECTIONS
+    }
+    storage["model.layers.3.self_attn.o_proj"] = {"format": "exl3"}
+    config = {
+        "quantization_config": {
+            "tensor_storage": storage,
+            "r7_routed_experts": {"schema": "preserve"},
+            "ignore": ["lm_head"],
+            "exl3_dense": {"include_prefixes": list(storage)},
+        }
+    }
+
+    original_include = list(
+        config["quantization_config"]["exl3_dense"]["include_prefixes"]
+    )
+    patched = MODULE._patch_config(config, quantized_shared_layers=(3,))
+
+    assert patched["quantization_config"]["tensor_storage"] == {
+        "model.layers.3.self_attn.o_proj": {"format": "exl3"}
+    }
+    assert (
+        patched["quantization_config"]["exl3_dense"]["include_prefixes"]
+        == original_include
+    )
+    assert patched["quantization_config"]["ignore"] == ["lm_head"]
+    assert len(config["quantization_config"]["tensor_storage"]) == 4
+
+
+def test_archive_source_manifest_removes_stale_seals(tmp_path: Path) -> None:
+    manifest = b'{"schema":"r7"}\n'
+    (tmp_path / "MANIFEST.json").write_bytes(manifest)
+    (tmp_path / "MANIFEST.sha256").write_text("stale\n", encoding="utf-8")
+    (tmp_path / ".manifest_verified").write_text("stale\n", encoding="utf-8")
+
+    digest = MODULE._archive_source_manifest(tmp_path)
+
+    assert digest == hashlib.sha256(manifest).hexdigest()
+    assert not (tmp_path / "MANIFEST.json").exists()
+    assert not (tmp_path / "MANIFEST.sha256").exists()
+    assert not (tmp_path / ".manifest_verified").exists()
+    assert (tmp_path / "SOURCE_R7_MANIFEST.json").read_bytes() == manifest
+    assert (tmp_path / "SOURCE_R7_MANIFEST.sha256").read_text(
+        encoding="utf-8"
+    ) == f"{digest}  SOURCE_R7_MANIFEST.json\n"