Add signed MSRT campaign DAGs and TP-aware EXL3 cartridge artifacts

.github/workflows/ci.yml

@@ -71,7 +71,7 @@ jobs:
           VIRTUAL_ENV=.venv-base uv pip install dist/*.whl
           VIRTUAL_ENV=.venv-base uv pip list | grep -qi '^numpy ' \
             && { echo "numpy leaked into the base install"; exit 1; } || true
-          for cmd in fq-repack fq-assemble fq-fetch fq-prime fq-verify fq-release fq-eps; do
+          for cmd in fq-repack fq-assemble fq-assemble-lora fq-combine-cartridges fq-measure-mse-fruit fq-fetch fq-prime fq-verify fq-release fq-eps; do
             echo "--- $cmd --help"
             ./.venv-base/bin/$cmd --help > /dev/null
           done

CHANGELOG.md

@@ -59,14 +59,95 @@ measured, what is implemented, and what is not.
   does *not*, and what an attacker with full control of the artifact
   repository can and cannot do under fingerprint pinning.
 - **JSON Schemas** in [`schemas/`](schemas/) for `fq-segment/1` (segment
-  metadata and index), `fq-attestation/1`, `fq-manifest/1`, `fq-policy/2`
-  and `fq-release/1` — derived from real emitted artifacts and re-validated
-  against freshly emitted documents on every CI run.
+  metadata and index), `fq-attestation/1`, `fq-manifest/1`, `fq-policy/2`,
+  `fq-cartridge/2`, `fq-cartridge-adapter/3`, `fq-cartridge-assembly/2`, and
+  `fq-release/1` — derived
+  from real emitted artifacts and re-validated against freshly emitted
+  documents on every CI run.
 - **Packaging** — `pyproject.toml` with console entry points (`fq-repack`,
   `fq-assemble`, `fq-fetch`, `fq-prime`, `fq-verify`, `fq-release`,
   `fq-eps`), a hashed universal dev lock (`requirements-dev.txt`), and
   GitHub Actions CI running the suite on ubuntu-latest and macos-latest for
   Python 3.11 / 3.12 / 3.13, plus wheel-build and trust-root jobs.
+- **MSRT cartridge campaign tools** — `fq-assemble-lora` encodes a whole
+  `fq-cartridge/2` graph in one pass over the weights: every declared base
+  tier becomes a complete EXL3 checkpoint, and every stage is a rescaled
+  trellis residual against the reconstruction of the `parent` it names, so
+  seven loadable products spanning 26 bits per weight cost seven quantization
+  passes emitting 12 (measured on real GLM-5.2 experts: 1.58x less trellis
+  kernel time and 2.17x fewer bytes than encoding each product separately; the
+  nine-product graph is 1.83x and 2.5x). Subcommands
+  `plan` / `skeleton` / `encode` / `finalize`; reads standard indexed Hugging
+  Face shards or per-layer shards without ever loading a whole shard; work is
+  addressed as (layer, 32-expert block), owned by an `flock` the kernel releases
+  however the owner dies, and committed as one atomic unit, so an interrupted or
+  preempted run resumes at block granularity and `--devices` runs one worker per
+  GPU over disjoint blocks. One campaign directory takes one launcher and one
+  signing key, both enforced rather than advised, and publication cannot overlap
+  encoding. `fq-combine-cartridges` turns one published
+  assembly plan into a self-contained `fq-cartridge-adapter/3` cartridge under
+  a pinned signer, narrowing a full-expert stage to the experts a consumer
+  actually wants — decided from the signed plan before any payload is read, and
+  checked against the base checkpoint it will be loaded onto.
+  `fq-measure-mse-fruit` compares the actual SIQ checkpoint against every
+  graph node through the production encoder itself. `fq-promote-campaign`
+  publishes a staged campaign to `main` in a single commit of server-side
+  copies, after verifying the branch carries every file the finalized campaign
+  holds. These custom cartridges are explicitly not standard PEFT/LoRA adapters
+  and require an EXL3 MSRT-aware runtime.
+- **Source-byte provenance is one transaction** — skeleton repacks and raw
+  encoder reads copy and SHA-256 one `O_NOFOLLOW` regular-file fd into private
+  `0600` staging, validate the inode before/after, deserialize only staged
+  bytes, and attest that observed digest directly. Hub/manifest digests and the
+  resume cache are strict expectations rather than substitutes for
+  observation; symlinks, FIFOs, nonregular files, source drift and stale cache
+  entries are refused.
+- **Versioned MSRT runtime binding** — the pre-merge closed
+  `fq-cartridge-assembly/2` and `fq-cartridge-adapter/3` contracts bind an
+  ordered residual chain to exact per-layer logical base identities plus a
+  TP-layout-invariant family root. Adapter/3 fixes base-owned rotations,
+  packed int16 trellis plus scalar float32 scale semantics, and an explicit
+  full-vs-rank-sharded layout/rank/axis map (unambiguous even at world size
+  one). Every shard carries size and SHA-256; producer/runtime share config,
+  shard, and total-size limits. `producer_verified_signer` records combiner
+  provenance only, not runtime authentication. The paired vLLM loader rejects
+  unversioned, incomplete, tampered, wrong-base, or wrong-TP cartridges before
+  tensor deserialization.
+- **Two recipes for GLM-5.2, priced against each other.**
+  `recipes/glm52-k2k3-dag.json` ships nine products including two that sell a
+  +1-bit upgrade to an installed 3 or 4 bpw tier;
+  `recipes/glm52-k2k3-lean.json` drops those two. Measured on 168 comparisons
+  across real GLM-5.2 layers and on all 88 blocks of a proxy rehearsal, the
+  narrow-step path they serve is 9.0% (K2 family) and 6.8% (K3) worse than
+  fetching the wider residual at the same bitrate, while costing twice the
+  kernel time — so the lean graph is the recommended rental: **132.6 GPU-hours
+  against 186.9**, both measured back to back on one RTX 5090.
+- **[tools/msrt_campaign.sh](tools/msrt_campaign.sh)** — the campaign as one
+  checked driver: window staging with last-use source retention, skeleton,
+  encode, retirement, and a `PHASE=finalize` pass for a CPU machine. Refuses a
+  `WINDOWS` list that does not cover the recipe exactly once, refuses to start
+  without an explicit `DEVICES`, and refuses to let the GPU fleet be released
+  until every prerequisite for finishing the campaign is on one persistent
+  filesystem.
+- **Signed provenance for every encoded fragment.** Each shard ships a
+  `fq-attestation/1` line beside it: `encode-of` for expert shards, naming the
+  sha256 of each expert's contiguous byte range, the encoder bundle (Python
+  modules *and* the compiled extension), the determinism scope, the effective
+  quant arguments, and the exact parent shard digest the residual corrects;
+  `repack-of` for skeleton shards, naming per-tensor digests and the source
+  file the bytes were copied from. Shard payloads carry no timestamp, so
+  re-encoding inside the declared scope reproduces them byte for byte.
+  `finalize` re-hashes all of it before publishing anything and refuses a
+  campaign that spans two signers or two encoder builds, whose stages do not
+  name the parents this campaign published, or that holds shards the recipe
+  does not describe. It is also resumable: a preemption during that
+  multi-terabyte pass costs the re-read, not the campaign.
+- **[docs/MSRT-CAMPAIGN.md](docs/MSRT-CAMPAIGN.md)** — the GLM-5.2 campaign
+  runbook: per-K trellis cost, both graphs measured as full 32-expert blocks on
+  real GLM-5.2 weights, the resulting 133 GPU-hour / 1.147 TB projection with
+  its measured/derived/unmeasured labels, exact window geometry from the pinned
+  index, fleet sizing, the gates to run before renting, and the resume, publish
+  and verification procedure — rehearsed end to end on a proxy.
 - **[docs/PRIOR-ART.md](docs/PRIOR-ART.md)** — commissioned independent
   prior-art review, and the single narrow claim this project makes.
 

README.md

@@ -543,6 +543,55 @@ The encoder driver and capture tooling are documented at the immutable
 [research revision `69fbef710e558e9cf8e2ad634eccc774f9a806fb`](https://github.com/malaiwah/vllm-voipmonitor/tree/69fbef710e558e9cf8e2ad634eccc774f9a806fb/research/fungible-quant);
 they are not a supported runtime component of this repository.
 
+## Encode a progressive cartridge graph (`fq_assemble_lora`)
+
+A segment tree ships one bit-width per expert. An **MSRT cartridge graph**
+ships several, from one pass over the weights: a `fq-cartridge/2` recipe
+declares complete base tiers and *rescaled trellis residual stages*, each
+naming the `parent` reconstruction it corrects, so the products share their
+ancestors' work instead of re-encoding it.
+
+```bash
+# seven loadable products (K2, K3, and K4/K5-like cartridges over both bases)
+# in seven quantization passes emitting 12 bits per weight
+uv run tools/fq_assemble_lora.py plan --source <bf16-dir> \
+  --recipe recipes/glm52-k2k3-lean.json --block-size 32
+uv run tools/fq_assemble_lora.py skeleton --source <bf16-dir> \
+  --recipe recipes/glm52-k2k3-lean.json --out ./campaign --sign-key ~/.fq_keys/c.key
+uv run tools/fq_assemble_lora.py encode --source <bf16-dir> \
+  --recipe recipes/glm52-k2k3-lean.json --out ./campaign \
+  --encoder-source <exllamav3-pkg> --sign-key ~/.fq_keys/c.key \
+  --devices cuda:0,cuda:1
+uv run tools/fq_assemble_lora.py finalize --source <bf16-dir> \
+  --recipe recipes/glm52-k2k3-lean.json --out ./campaign --sign-key ~/.fq_keys/c.key
+
+# consumer: one product, narrowed to the experts you actually want upgraded,
+# under a pinned signer, checked against the base it will be loaded onto
+uv run tools/fq_combine_cartridges.py --root ./campaign \
+  --assembly k2-k4like-direct --out ./k4like-hot96 --experts 0-95 \
+  --trust-key <64-hex campaign signer> --base ./campaign/base/k2
+```
+
+For a whole campaign, `tools/msrt_campaign.sh` runs that sequence window by
+window with source retention, then hands off to a CPU machine for `finalize` and
+`fq-promote-campaign`, which publishes the result in one commit.
+
+Work is addressed as (layer, 32-expert block) and committed as one atomic unit,
+so a preempted run resumes at block granularity and `--devices` runs one worker
+per GPU over disjoint blocks. Block ownership is an `flock`, so a crashed worker
+frees its block and no launcher has to guess whether a claim is stale; one
+campaign directory takes one launcher and one signing key. Every shard ships a
+signed `fq-attestation/1` line naming the sha256 of each expert's byte range, the
+encoder bundle that produced it and — for a residual — the exact parent shard
+digest it corrects; `finalize` re-hashes all of it before publishing and the
+combiner re-checks it under a key you pin. Measured on real GLM-5.2 experts, the
+shared-parent graph costs **1.58x less trellis kernel time and 2.17x fewer
+bytes** than encoding the same seven products separately (1.83x and 2.5x for the
+nine-product `glm52-k2k3-dag.json`, whose two extra products sell +1-bit upgrades
+at measurably worse error — [docs/MSRT-CAMPAIGN.md](docs/MSRT-CAMPAIGN.md) §1.1
+prices the choice, and carries the per-K cost table, the full-campaign
+projection and the runbook).
+
 ## Status & roadmap
 
 | Piece | Status |
@@ -558,6 +607,8 @@ they are not a supported runtime component of this repository.
 | Mixed-size (true mixed-K) assembly + loader metadata | offline assembly is working and tested; serving an output remains subject to the runtime's TP4-only / EP-and-DP refusal and hardware constraints |
 | Four tiers in the artifact tree (K2/K3/K4/K5) | root K3 is complete (layers 3–78); root K2/K4/K5 are `encode-of` tiers; nested `sources/willfalco-*` contains community-primed material for layers 3–10. For current coverage, use `per_k[K].layer_coverage.layers` (`fq-layer-coverage/1`) or signed index keys for older manifests; `per_k[K].layers` is legacy extrema only |
 | Runtime progressive loader + live bit-width reallocation (vLLM/GG) | separate experimental research, TP-only and not wired as an end-to-end supported workflow; no live-reallocation claim is made by these tools |
+| MSRT cartridge graph (`fq_assemble_lora`, `fq_combine_cartridges`) | working, tested; encode→decode parity proven against the runtime's own `ext.reconstruct` on real GLM-5.2 experts. Publishing a full GLM-5.2 graph is costed and gated in [docs/MSRT-CAMPAIGN.md](docs/MSRT-CAMPAIGN.md) but **not yet run** |
+| Serving an MSRT cartridge | **blocked on runtime**: the reference EXL3 MSRT implementation ([local-inference-lab/vllm#299](https://github.com/local-inference-lab/vllm/pull/299)) is draft, TP=1, one model-wide slot, and materializes dense FP16 shadow weights, which GLM-5.2's 734 G routed weights do not fit on one node |
 | Packaging, CI (ubuntu + macOS, py3.11–3.13), JSON Schemas | landed this release |
 
 ## Prior art and positioning