REPRODUCE_SQG_W4A8.md

# Reproducing the GLM-5.2 BMM-Law SQG W4A8 build

This guide describes the exact production construction represented by
`brandonmusic/GLM-5.2-BMM-Law-SQG-Hessians`. It is a BF16-source-only SQG
build. It does not consume, preserve, or convert MCG payloads, scales, or
transforms.

For a smaller human-facing download, use
`brandonmusic/GLM-5.2-BMM-Law-SQG-Hessians-Canonical` at tag `canonical-v1`.
The original accepted archive remains authoritative for frozen-path replay.

## Immutable inputs and output contract

- BF16 source: `zai-org/GLM-5.2` at
  `b4734de4facf877f85769a911abafc5283eab3d9`.
- Calibration topology: TP1/PP8 with prompt rows retained in canonical
  `global_row_start` order.
- Routed layers: 3 through 78 inclusive; layer 78 is the MTP layer.
- Routed matrices: 256 experts x gate/up/down x 76 layers = 58,368 SQG
  matrices.
- Routed rate map: independent per tensor, exactly 384 K3 and 384 K4 matrices
  in each routed layer. This is not a uniform-K3 build and is not a single
  bit-width per expert.
- Routed H13: `0.75 * H_layer + 0.25 * H_local,e`; the local term is
  expert-specific and applied-gate weighted.
- Down calibration: exact upstream W4A8 candidate path, GLM
  `SiLU(gate) * up`, with candidate-specific `(H,B)` cross-term evidence.
- Non-routed matrices: shared-expert gate/up/down plus attention q_b/o in every
  layer 3 through 78, 380 matrices total, encoded as SQG K6.
- Weight endpoint: native exact E4M3 SQG labels.
- Activation endpoint: full W4A8, including both `h` and
  `SiLU(gate) * up`, with FP32 accumulation.
- Final census: 58,748 SQG matrices, zero MCG marker tensors, and topology-
  neutral transforms/scales. Standard ignored tensors remain direct BF16.

The authoritative machine-readable contracts are:

- `derived/lineage/reproducibility/SQG_REPRODUCIBILITY_CAMPAIGN.json`
- `derived/lineage/reproducibility/SQG_REPRODUCIBILITY_BUILD_BINDING.json`
- `HESSIAN_DATASET_MANIFEST.json`

The build binding contains the SHA-256 census for the calibration, Hessian,
encoding, quantization, scheduler, and materialization source trees. Verify
those hashes before running anything. Do not substitute similarly named files
from another checkout.

## Published source layout

The dataset includes the exact source used by the campaign:

- `reproduction/b300_remote/`: BF16 download/capture, TP1/PP8 streaming
  capture, MTP78 capture, persistent GPU workers, campaign scheduler, dense-K6
  encoder, dataset publication, and model publication.
- `reproduction/scripts/`: H13 construction, native profile construction,
  gate/up/down SQG encoding, candidate-specific W4A8 down calibration,
  retention, materialization, and full-checkpoint validation.
- `reproduction/src/`: calibration schemas, capture adapters, source binding,
  SQG codec/manifest/reference logic, and extension sealing.
- `reproduction/kquant/`: SQG codebooks, LDLQ/Viterbi CUDA extension sources,
  E4M3 tables, packing/materialization helpers, and reference logic.
- `reproduction/bmmlaw_r7_encoder/`: topology-neutral BMM-Law support code
  retained for provenance.

`reproduction/b300_remote/README.md` documents scheduler semantics, GPU/HBM
residency, durable receipts, and the one-work-unit adapters. The present file
is the shorter end-to-end production recipe.

## Hardware and software

The accepted paid build used eight NVIDIA B300 GPUs (SM103), CUDA 13.0,
Python 3.12, and the environment recorded in the build binding. Numerical
H13/H2/B construction, shrinkage, damping, factorizations, Hadamard work,
candidate replay, scoring accumulators, and SQG encoding run on CUDA with FP32
accumulation. CPU is used for orchestration, mmap/pinned prefetch, file I/O,
and compact receipt serialization only.

The KQuant extension must be built once for compute capability 10.3 and then
loaded only through the sealed prebuilt path. Workers must set:

```text
KQUANT_SQG_REQUIRE_PREBUILT=1
KQUANT_SQG_EXTENSION_PATH=<absolute sealed extension path>
KQUANT_SQG_EXTENSION_SHA256=<digest from sqg-extension-seal.json>
```

Do not allow workers to fall back to Torch JIT compilation.

## Restore the source and artifacts

Download the dataset at its accepted immutable tag after publication:

```bash
hf download brandonmusic/GLM-5.2-BMM-Law-SQG-Hessians \
  --repo-type dataset \
  --revision accepted-glm52-sqg-w4a8-b300-r1 \
  --local-dir /workspace/glm52-sqg-reproduction/dataset
```

Download the exact BF16 teacher separately:

```bash
hf download zai-org/GLM-5.2 \
  --revision b4734de4facf877f85769a911abafc5283eab3d9 \
  --local-dir /workspace/glm52-w4a8/inputs/GLM-5.2-BF16
```

Restore the published source tree under one project root. Preserve the
relative directory names:

```text
<project>/b300_remote
<project>/scripts
<project>/src
<project>/kquant/kquant
<project>/bmmlaw_r7_encoder
```

Restore the raw capture, MTP78 capture, dense Hessians, capture views, and
derived directories from the dataset into the absolute roots referenced by
the frozen campaign JSON, or edit only the path operands with
`reproduction/b300_remote/rebind_campaign_code_root.py`. That rebinder refuses
changes to the layer domain, final tensor census, scheduler contract, and
campaign identity.

## Build and seal the SM103 encoder dependency

Run the dependency builder on one visible B300:

```bash
CUDA_VISIBLE_DEVICES=0 TORCH_CUDA_ARCH_LIST=10.3 \
  /venv/main/bin/python \
  <project>/b300_remote/build_sm103_encoder_deps.py \
  --project-root <project> \
  --build-root /workspace/glm52-w4a8/work/sm103-encoder-build \
  --output-dir /workspace/glm52-w4a8/state/sm103-encoder-dependencies
```

The resulting `sqg-extension-seal.json` must report SM103, K2 through K6
smoke closure, `jit_allowed_in_workers: false`, and the exact extension SHA.

## Bind and run the campaign

Copy the frozen campaign contract, then rebind executable paths only:

```bash
cp \
  <dataset>/derived/lineage/reproducibility/SQG_REPRODUCIBILITY_CAMPAIGN.json \
  /workspace/glm52-w4a8/state/campaign.reproduction.json

/venv/main/bin/python \
  <project>/b300_remote/rebind_campaign_code_root.py \
  --campaign /workspace/glm52-w4a8/state/campaign.reproduction.json \
  --code-root <project> \
  --in-place
```

Inspect the resolved plan without launching:

```bash
/venv/main/bin/python <project>/b300_remote/campaign_supervisor.py plan \
  --config /workspace/glm52-w4a8/state/campaign.reproduction.json
```

Then run or resume the durable campaign:

```bash
B300_PROJECT_ROOT=<project> \
B300_CAMPAIGN_CONFIG=/workspace/glm52-w4a8/state/campaign.reproduction.json \
  <project>/b300_remote/run_b300_campaign.sh resume
```

The scheduler must close all 76 routed retention receipts and all 76
`SQG_K6_LAYER.json` receipts before materialization. A restart resumes from
those durable receipts; it must not delete or recreate completed layers.

## Materialize the BF16-source-only checkpoint

The frozen campaign runs this stage automatically. The equivalent explicit
command is:

```bash
/venv/main/bin/python <project>/scripts/materialize_full_sqg_checkpoint.py \
  --source-model /workspace/glm52-w4a8/inputs/GLM-5.2-BF16 \
  --production-root /workspace/sqg-run/final \
  --k6-root /workspace/sqg-run/k6 \
  --hessian-dataset-receipt \
    /workspace/glm52-w4a8/state/domain/hessian-upload-finish.json \
  --bf16-revision b4734de4facf877f85769a911abafc5283eab3d9 \
  --output /workspace/output/GLM-5.2-SQG-W4A8
```

The materializer streams official BF16 shards, replaces the selected routed
and K6 tensors, and retains only the standard direct-BF16 tensor set. It must
not begin from an MCG/EXL checkpoint.

## Required closure

Before publication, verify:

1. Routed retention receipts exist and their sidecar SHA files pass for every
   layer 3 through 78.
2. Every routed layer reports 384 K3, 384 K4, 768 SQG, zero MCG, and beta/local
   alpha 0.25.
3. Every dense layer reports five K6 matrices, GPU numerical work, and FP32
   accumulation.
4. `FULL_SQG_NATIVE_MANIFEST.json` reports activation endpoint `full-w4a8`,
   58,748 SQG matrices, zero MCG markers, TP1/PP8 construction, and inclusion
   of MTP78.
5. The public Hessian dataset and model are anonymous-readable at both `main`
   and `accepted-glm52-sqg-w4a8-b300-r1`, with the accepted tags resolving to
   the verified `main` commits.

This reproduction recipe intentionally does not run KLD, LAVD, or Estonia;
those were excluded from this owner-directed construction/publication run.