Option-B repro kit: prebuilt SM80 binary wheel (no CUDA/calibration source, audited), build receipt, repro script, license

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+fraqtl_runtime-0.2.0+sm80-py3-none-any.whl filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,15 @@
+fraQtl Verification License (v1, 2026-07-02)
+
+Copyright (c) 2026 Samuel Salfati / fraQtl. All rights reserved.
+
+Permission is granted, free of charge, to download, install, and execute this
+software solely to verify, benchmark, or evaluate the published fraQtl
+results. Redistribution of the software, use in production systems, and
+reverse engineering, decompilation, or disassembly of the binary components
+are not permitted without prior written permission.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.
+
+Contact: samuelsalfati@gmail.com

README.md

@@ -0,0 +1,61 @@
+---
+license: other
+license_name: fraqtl-verification
+license_link: LICENSE
+tags:
+  - kv-cache
+  - kv-cache-compression
+  - vllm
+  - a100
+  - fraqtl
+inference: false
+---
+
+# fraQtl SM80 runtime — prebuilt verification wheel
+
+Prebuilt binary wheel of the `fraqtl` vLLM runtime, published so anyone can independently reproduce the fraQtl KV-cache receipts on a rented A100 for ~$15 — **without the kernel or calibration source being distributed**.
+
+## What's inside
+
+- The fraQtl CUDA kernel as a compiled **SM80 (A100) binary** (`fraqtl/_native/libggml-cuda.so`). No `.cu`/`.c`/header source ships; the build hard-fails if any leaks in (see `wheel_build_receipt.json`).
+- The runtime Python surface (vLLM attention backend, model adapters, sidecar format readers), **Cython-compiled to binary modules**. Calibration and sidecar-factory code is not in the wheel in any form.
+- vLLM plugin auto-registration via the `vllm.general_plugins` entry point — `pip install` the wheel and vLLM's plugin loader finds the backend in every worker process.
+
+## Scope
+
+- **Hardware: A100 (SM80) only.** The binary will not run on H100, L4, or consumer GPUs.
+- **vLLM 0.20.2, CUDA 12.4, Python 3.11** — the exact receipt environment. Other versions are unsupported.
+- Purpose: verification of the published receipts. It is not a general-purpose release.
+
+## Use it
+
+Don't drive this by hand — use the one-command repro script (`fraqtl_repro_receipts.py`, in this repo and in the sidecar repos):
+
+```bash
+pip install modal && modal setup
+modal secret create huggingface HF_TOKEN=hf_...
+modal run fraqtl_repro_receipts.py
+```
+
+It installs this wheel, pulls the calibrated sidecars from
+[`fraQtl/mistral-7b-instruct-v0.3-kv-sidecars`](https://huggingface.co/fraQtl/mistral-7b-instruct-v0.3-kv-sidecars),
+runs the three-arm receipt (fraQtl D2 vs fp16 vs fp8-KV) at 8K and 32K with a
+needle-in-a-haystack gate per arm, and prints the table.
+
+### Honesty footnotes
+
+- **NIAH-verified, not "lossless."**
+- **vs-fp8 always visible** — fp8 KV is the real competitor.
+- **Batch-1 decode** for the published speed rows.
+
+## Files
+
+| File | What |
+|---|---|
+| `fraqtl_runtime-*.whl` | The prebuilt wheel (binary-only) |
+| `wheel_build_receipt.json` | Build provenance: sha256, source-leak audit result, module list |
+| `fraqtl_repro_receipts.py` | The one-command repro script |
+
+## License
+
+Proprietary; free to install and run for verification and evaluation. No reverse engineering. Sidecars and receipts in the companion repos are Apache 2.0.

fraqtl_repro_receipts.py

@@ -0,0 +1,303 @@
+"""fraQtl three-arm KV-cache receipt — independent reproduction script.
+
+Reproduces the published Mistral-7B-Instruct-v0.3 numbers (A100-80GB, vLLM
+0.20.2, CUDA graphs, batch 1, NIAH-gated) for the three arms:
+
+    D2    fraQtl compressed KV (prebuilt SM80 binary wheel + HF sidecars)
+    fp16  stock vLLM
+    fp8   vLLM with kv_cache_dtype="fp8" (the real competitor)
+
+Published rows this script regenerates (decode tok/s | NIAH | KV pool tokens):
+
+    ctx 8K :  D2 85.7  PASS 997,200 | fp16 90.39 PASS 412,544 | fp8 90.05 PASS 825,104
+    ctx 32K:  D2 76.84 PASS 937,568 | fp16 77.98 PASS 407,760 | fp8 82.81 PASS 799,952
+
+Speed numbers are hardware-run-to-run sensitive at the ±few-percent level;
+NIAH results and KV pool sizes are deterministic.
+
+USAGE — Modal (recommended, ~$10-15 of A100 time total):
+    pip install modal && modal setup
+    modal secret create huggingface HF_TOKEN=hf_...   # your token
+    modal run fraqtl_repro_receipts.py                # all arms, 8K + 32K
+    modal run fraqtl_repro_receipts.py --ctx 8k --arms D2,fp16
+
+USAGE — Docker fallback (your own A100-80GB box):
+    docker run --gpus all -it --rm -e HF_TOKEN=hf_... \
+        nvcr.io/nvidia/cuda:12.4.1-devel-ubuntu22.04 bash
+    # inside: install python3.11, then
+    pip install vllm==0.20.2 numpy huggingface_hub
+    python fraqtl_repro_receipts.py --local --ctx 8k
+
+Timing method (same as the published receipts): prefix caching OFF; pass A
+generates 1 token (prefill wall), pass B generates 33 tokens; decode tok/s =
+(output tokens - batch) / (wall_B - wall_A). NIAH gate runs per arm at the
+same context, temperature 0, before any timing: a tok/s number on an arm
+that drops the needle is a FAIL, not a win.
+"""
+
+WHEEL_REPO = "fraQtl/fraqtl-sm80-runtime"
+SIDECAR_REPO = "fraQtl/mistral-7b-instruct-v0.3-kv-sidecars"
+V_SIDECAR = "sidecar_real_u_mistral-7b-instruct-v0.3.bin"
+K_SIDECAR = "mistral-7b-instruct-v0.3-k16-int3.fraqtl-k-eigenbasis.bin"
+K_RECEIPT = "receipts/mistral_S2_exp16_k16_int3_receipt_2026-05-26.json"
+HF_MODEL = "mistralai/Mistral-7B-Instruct-v0.3"
+N_HEADS_Q = 32
+BLOCK_SIZE = 16
+PASSKEY = "48291"
+GPU_MEM_UTIL = 0.85
+DECODE_TOKENS = 32
+CTX_POINTS = {"8k": (9216, 8192), "32k": (32768, 32000)}  # (max_model_len, ctx)
+
+
+def _download_kit(d2: bool):
+    """Fetch the fraQtl wheel + sidecars from Hugging Face (D2 arm only)."""
+    import subprocess
+    import sys
+    from huggingface_hub import hf_hub_download, list_repo_files
+
+    if not d2:
+        return {}
+    whl_name = next(f for f in list_repo_files(WHEEL_REPO) if f.endswith(".whl"))
+    whl = hf_hub_download(WHEEL_REPO, whl_name)
+    subprocess.run([sys.executable, "-m", "pip", "install", "-q",
+                    "--no-deps", whl], check=True)
+    return {
+        "v": hf_hub_download(SIDECAR_REPO, V_SIDECAR),
+        "k": hf_hub_download(SIDECAR_REPO, K_SIDECAR),
+        "k_receipt": hf_hub_download(SIDECAR_REPO, K_RECEIPT),
+    }
+
+
+def _set_d2_env(paths, max_model_len):
+    """The exact runtime configuration recorded in the published receipts
+    (recipe: K 16 protected + INT4 tail, V 32 protected + INT4 tail,
+    logical rank 128; reader warptile_v32; split target 256)."""
+    import os
+    env = {
+        "FRAQTL_K_SIDECAR": paths["k"],
+        "FRAQTL_K_SIDECAR_RECEIPT": paths["k_receipt"],
+        "FRAQTL_V_SIDECAR": paths["v"],
+        "FRAQTL_N_HEADS_Q": str(N_HEADS_Q),
+        "FRAQTL_BLOCK_SIZE": str(BLOCK_SIZE),
+        "FRAQTL_MAX_N_TOKENS": str(max_model_len),
+        "FRAQTL_K_TAIL_BITS": "4",
+        "FRAQTL_V_TAIL_BITS": "3",
+        "FRAQTL_SINK_N": "8",
+        "FRAQTL_RESIDUAL_N": "1024",
+        "FRAQTL_ATTENTION_IMPL": "sm80_membrane",
+        "FRAQTL_DENSE_RANKSPACE_ATTENTION": "0",
+        "FRAQTL_SM80_MEMBRANE_PRODUCT_MODE": "1",
+        "FRAQTL_SM80_MEMBRANE_K16_PROD": "1",
+        "FRAQTL_SM80_MEMBRANE_WMMA_STAGED": "0",
+        "FRAQTL_SM80_MEMBRANE_DEBUG_SCALAR": "0",
+        "FRAQTL_SM80_KTAIL_FP16_RESCUE": "0",
+        "FRAQTL_SM80_V_THEOREM_PACKED": "1",
+        "FRAQTL_SM80_V_THEOREM_PROTECT": "32",
+        "FRAQTL_SM80_MEMBRANE_FLOAT_PV": "0",
+        "FRAQTL_SM80_MEMBRANE_FLOAT_QK": "0",
+        "FRAQTL_SM80_MEMBRANE_READER": "warptile_v32",
+        "FRAQTL_SM80_MEMBRANE_V32_VEC_STAGE": "0",
+        "FRAQTL_SM80_DEBUG_OUTPUT_SENTINEL": "0",
+        "FRAQTL_SM80_PROFILE_KERNELS": "0",
+        "FRAQTL_SM80_MEMBRANE_SPLIT_TARGET": "256",
+        "FRAQTL_SM80_PAIRDOT_FRAGMENT_REALPAGE_WITNESS": "0",
+        "FRAQTL_SM80_VTAIL_FRAGMENT_NATIVE": "0",
+        "FRAQTL_SM80_RETURN_DENSE_RV128": "0",
+        "FRAQTL_SM80_CHECK_SLOT_TABLE": "0",
+        "FRAQTL_SM80_COMPARE_PREFILL_PAGE": "0",
+        "FRAQTL_SM80_COMPARE_PREFILL_PAGE_LAYERS": "0",
+        "FRAQTL_SM80_DECODE_RV64_PARITY": "0",
+        "FRAQTL_SM80_DECODE_RV64_PARITY_LAYER": "31",
+        "FRAQTL_RANKSPACE_RK": "128",
+        "FRAQTL_RANKSPACE_RV": "128",
+        "FRAQTL_RANKSPACE_TAIL_MODE": "truncate",
+        "FRAQTL_RANKSPACE_K_PROTECT": "16",
+        "FRAQTL_RANKSPACE_V_PROTECT": "32",
+        "FRAQTL_RANKSPACE_FUSE_Q": "0",
+        "FRAQTL_RANKSPACE_FUSE_Q_UV": "0",
+        "FRAQTL_RANKSPACE_FUSE_WRITE_QUANT": "0",
+        "FRAQTL_RANKSPACE_UV_BLOCK_D": "32",
+        "FRAQTL_PACKED_PREPROJECT_Q": "1",
+        "FRAQTL_PACKED_DECODE_BN": "64",
+        "FRAQTL_PACKED_DECODE_SPLITS": "1",
+        "FRAQTL_PACKED_WRITER_FUSED_DOT": "0",
+        "FRAQTL_PACKED_PREFILL_WRITER_FUSED_DOT": "0",
+        "FRAQTL_PACKED_DECODE_WRITER_FUSED_DOT": "0",
+        "FRAQTL_PACKED_DECODE_WRITER_MODE": "prepack",
+        "FRAQTL_PACKED_V_LAYOUT": "dense3",
+        "FRAQTL_PACKED_DECODE_LANE": "pairk",
+        "FRAQTL_PACKED_DECODE_WORKSPACE_REUSE": "0",
+        "FRAQTL_FOLD_O_PROJ": "1",
+        "FRAQTL_FOLD_O_PROJ_DUAL": "0",
+        "FRAQTL_FOLD_O_PROJ_DUAL_SHADOW": "0",
+        "FRAQTL_FOLD_O_PROJ_DUAL_RANK_WEIGHT_DTYPE": "fp16",
+        "FRAQTL_FOLD_O_PROJ_PARITY": "0",
+        "FRAQTL_FOLD_O_PROJ_PARITY_LAYER": "0",
+        "FRAQTL_FOLD_O_PROJ_PARITY_MAX": "8",
+        "FRAQTL_D2_RANK_FP16_FASTPATH": "1",
+        "FRAQTL_D2_RANK_FP16_SYMMETRIC": "1",
+        "FRAQTL_PACKED_STAGE_TIMING": "0",
+        "FRAQTL_PACKED_STAGE_TIMING_LIMIT": "64",
+        "FRAQTL_PACKED_STAGE_TIMING_SKIP": "0",
+    }
+    os.environ.update(env)
+
+
+def _build_niah_prompt(tokenizer, target_tokens, passkey):
+    """Needle-in-a-haystack prompt, identical to the published receipts."""
+    filler = ("The grass is green. The sky is blue. The sun is bright. "
+              "We walk in the park every day. ")
+    needle = f" The pass key is {passkey}. Remember it. "
+    half = filler * max(1, target_tokens // (len(tokenizer(filler)["input_ids"]) * 2 or 1))
+    body = half + needle + half
+    q = "\n\nWhat is the pass key? The pass key is"
+    ids = tokenizer(body)["input_ids"]
+    if len(ids) > target_tokens - 64:
+        ids = ids[: target_tokens - 64]
+        body = tokenizer.decode(ids)
+        mid = len(body) // 2
+        body = body[:mid] + needle + body[mid:]
+    return body + q
+
+
+def _build_timing_prompt(tokenizer, target_tokens):
+    filler = ("The grass is green. The sky is blue. We walk in the park "
+              "every day and discuss the weather at length. ")
+    ids = tokenizer(filler)["input_ids"]
+    reps = max(1, (target_tokens - 64) // max(1, len(ids)))
+    ids = tokenizer(filler * reps)["input_ids"][: max(16, target_tokens - 64)]
+    return tokenizer.decode(ids) + "\n\nSummarize the above in one sentence:"
+
+
+def run_arm(mode: str, ctx_key: str) -> dict:
+    """One arm at one context point: engine init -> NIAH gate -> timing."""
+    import json
+    import re
+    import time
+
+    max_model_len, ctx_tokens = CTX_POINTS[ctx_key]
+    rep = {"mode": mode, "ctx": ctx_key, "model": HF_MODEL,
+           "max_model_len": max_model_len, "ctx_tokens": ctx_tokens,
+           "cuda_graphs": True, "prefix_caching": False, "batch": 1,
+           "gpu_memory_utilization": GPU_MEM_UTIL}
+
+    paths = _download_kit(d2=(mode == "D2"))
+    if mode == "D2":
+        _set_d2_env(paths, max_model_len)
+        from fraqtl.integrations.vllm_attention import register
+        register()
+
+    from vllm import LLM, SamplingParams
+
+    llm_kwargs = dict(model=HF_MODEL, dtype="float16",
+                      max_model_len=max_model_len, enforce_eager=False,
+                      gpu_memory_utilization=GPU_MEM_UTIL,
+                      enable_prefix_caching=False,
+                      enable_chunked_prefill=False)
+    if mode == "D2":
+        from vllm.config.attention import AttentionConfig
+        llm_kwargs["attention_config"] = AttentionConfig(backend="CUSTOM")
+    elif mode == "fp8":
+        llm_kwargs["kv_cache_dtype"] = "fp8"
+    elif mode != "fp16":
+        raise ValueError(f"unknown arm {mode!r}")
+
+    llm = LLM(**llm_kwargs)
+    num_blocks = int(llm.llm_engine.vllm_config.cache_config.num_gpu_blocks)
+    rep["kv_pool_tokens"] = num_blocks * BLOCK_SIZE
+    tok = llm.get_tokenizer()
+
+    # NIAH gate first — it gates the speed number.
+    niah = _build_niah_prompt(tok, ctx_tokens, PASSKEY)
+    out = llm.generate([niah], SamplingParams(max_tokens=16, temperature=0.0))
+    gen = out[0].outputs[0].text
+    rep["niah_generated"] = gen[:80]
+    rep["needle_found"] = re.search(rf"\b{PASSKEY}\b", gen) is not None
+    print(f"NIAH[{mode}/{ctx_key}] found={rep['needle_found']} gen={gen[:50]!r}",
+          flush=True)
+
+    # Two-pass prefill/decode split, batch 1.
+    prompt = _build_timing_prompt(tok, ctx_tokens)
+    n_prompt_tok = len(tok(prompt)["input_ids"])
+    sp_one = SamplingParams(max_tokens=1, temperature=0.0, ignore_eos=True)
+    sp_full = SamplingParams(max_tokens=DECODE_TOKENS + 1, temperature=0.0,
+                             ignore_eos=True)
+    t_a = time.time()
+    llm.generate([prompt], sp_one)
+    wall_prefill = time.time() - t_a
+    t_b = time.time()
+    outs = llm.generate([prompt], sp_full)
+    wall_total = time.time() - t_b
+    out_toks = sum(len(o.outputs[0].token_ids) for o in outs)
+    wall_decode = max(wall_total - wall_prefill, 1e-9)
+    rep.update({
+        "prefill_tok_s": round(n_prompt_tok / wall_prefill, 2),
+        "decode_tok_s": round((out_toks - 1) / wall_decode, 2),
+        "timing_design": ("two-pass subtractive; prefix cache disabled, "
+                          "decode ~= wall_full_decode - wall_one_token"),
+    })
+    print(f"ARM[{mode}/{ctx_key}] {json.dumps(rep, default=str)}", flush=True)
+    return rep
+
+
+def print_table(rows):
+    print("\narm    ctx  NIAH  decode_tok_s  prefill_tok_s  kv_pool_tokens")
+    for r in rows:
+        if "error" in r:
+            print(f"{r['mode']:<6} {r['ctx']:<4} ERROR {r['error'][:60]}")
+            continue
+        niah = "PASS" if r.get("needle_found") else "FAIL"
+        print(f"{r['mode']:<6} {r['ctx']:<4} {niah:<5} "
+              f"{r.get('decode_tok_s', ''):<13} {r.get('prefill_tok_s', ''):<14} "
+              f"{r.get('kv_pool_tokens', ''):,}")
+    print("\nNIAH-verified, not lossless. fp8 arm shown always. Batch-1 decode.")
+
+
+# ---------------------------------------------------------------- Modal path
+try:
+    import modal
+
+    app = modal.App("fraqtl-option-b-repro")
+    image = (
+        modal.Image.from_registry("nvidia/cuda:12.4.1-devel-ubuntu22.04",
+                                  add_python="3.11")
+        .pip_install("vllm==0.20.2", "numpy", "huggingface_hub",
+                     extra_options="--no-cache-dir")
+        .add_local_file(__file__, "/root/fraqtl_repro_receipts.py")
+    )
+
+    @app.function(image=image, gpu="A100-80GB", timeout=7200,
+                  secrets=[modal.Secret.from_name("huggingface")])
+    def modal_arm(mode: str, ctx_key: str) -> dict:
+        import sys
+        sys.path.insert(0, "/root")
+        from fraqtl_repro_receipts import run_arm
+        return run_arm(mode, ctx_key)
+
+    @app.local_entrypoint()
+    def main(arms: str = "D2,fp16,fp8", ctx: str = "8k,32k"):
+        rows = []
+        for ck in [c.strip().lower() for c in ctx.split(",") if c.strip()]:
+            for mode in [a.strip() for a in arms.split(",") if a.strip()]:
+                try:
+                    rows.append(modal_arm.remote(mode, ck))
+                except Exception as e:  # keep going; partial table still useful
+                    rows.append({"mode": mode, "ctx": ck, "error": str(e)[:200]})
+        print_table(rows)
+except ImportError:
+    pass
+
+
+if __name__ == "__main__":  # Docker / bare-metal fallback (--local)
+    import argparse
+
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--local", action="store_true", required=True)
+    ap.add_argument("--arms", default="D2,fp16,fp8")
+    ap.add_argument("--ctx", default="8k,32k")
+    a = ap.parse_args()
+    rows = []
+    for ck in [c.strip().lower() for c in a.ctx.split(",") if c.strip()]:
+        for mode in [m.strip() for m in a.arms.split(",") if m.strip()]:
+            rows.append(run_arm(mode, ck))
+    print_table(rows)

fraqtl_runtime-0.2.0+sm80-py3-none-any.whl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:898853a871bb63b78db77515f664110e0575d66a1f3620486fc9d67043b8916c
+size 249494500

wheel_build_receipt.json

@@ -0,0 +1,59 @@
+{
+  "arch": "80",
+  "version": "0.2.0+sm80",
+  "so": "/cache/prebuilt_so/ac84206530d0ffc6_sm80/libggml-cuda.so",
+  "so_size_mb": 227.0,
+  "staged_modules": [
+    "fraqtl/__init__.py",
+    "fraqtl/auth.py",
+    "fraqtl/integrations/__init__.py",
+    "fraqtl/integrations/cuda_bridge.py",
+    "fraqtl/integrations/kv_cache_spec.py",
+    "fraqtl/integrations/memory_proof.py",
+    "fraqtl/integrations/packed_rankspace_cache.py",
+    "fraqtl/integrations/paged_layout.py",
+    "fraqtl/integrations/rankspace_o_proj_runtime_parity.py",
+    "fraqtl/integrations/rankspace_output_fold.py",
+    "fraqtl/integrations/stack_identity.py",
+    "fraqtl/integrations/triton_flashdecode_paged_rankspace.py",
+    "fraqtl/integrations/triton_flashdecode_rankspace.py",
+    "fraqtl/integrations/triton_packed_rankspace_vllm.py",
+    "fraqtl/integrations/triton_rankspace_postprocess.py",
+    "fraqtl/integrations/triton_rankspace_query.py",
+    "fraqtl/integrations/triton_rankspace_vllm.py",
+    "fraqtl/integrations/triton_rankspace_writer.py",
+    "fraqtl/integrations/triton_vllm_decode.py",
+    "fraqtl/integrations/vllm_asym_flash_attn.py",
+    "fraqtl/integrations/vllm_attention.py",
+    "fraqtl/integrations/vllm_model_adapters.py",
+    "fraqtl/integrations/vllm_plugin.py",
+    "fraqtl/integrations/vllm_runtime_init.py",
+    "fraqtl/sidecar_factory/__init__.py",
+    "fraqtl/sidecar_factory/formats.py",
+    "fraqtl/sidecar_factory/manifest.py",
+    "fraqtl/sidecar_factory/model_config.py",
+    "fraqtl/sidecar_factory/self_test.py",
+    "fraqtl/utils.py"
+  ],
+  "native_libs": [
+    "libggml-base.so",
+    "libggml-base.so.0",
+    "libggml-base.so.0.10.0",
+    "libggml-cuda.so",
+    "libggml-cuda.so.0",
+    "libggml-cuda.so.0.10.0"
+  ],
+  "wheel": "fraqtl_runtime-0.2.0+sm80-py3-none-any.whl",
+  "wheel_size_mb": 249.5,
+  "files_in_wheel": 41,
+  "py_files_in_wheel": [
+    "fraqtl/__init__.py",
+    "fraqtl/integrations/__init__.py",
+    "fraqtl/sidecar_factory/__init__.py"
+  ],
+  "source_leaks": 0,
+  "resolved_so": "/usr/local/lib/python3.11/site-packages/fraqtl/_native/libggml-cuda.so",
+  "sha256": "898853a871bb63b78db77515f664110e0575d66a1f3620486fc9d67043b8916c",
+  "volume_path": "/cache/repro_kit/fraqtl_runtime-0.2.0+sm80-py3-none-any.whl",
+  "wall_s": 212.7
+}