Experiment 013: static packed Q4/Q6/Q8 adoption study

.github/workflows/ci.yml

@@ -31,24 +31,24 @@ jobs:
           python-version: "3.11"
           version: "0.11.31"
       - name: Install
-        run: uv pip install --system -e ".[dev,eval]"
+        run: uv sync --frozen --all-extras
       - name: Verify frozen MBPP confirmation
         run: |
-          recurquant verify-confirmation \
+          uv run --frozen recurquant verify-confirmation \
             evidence/mbpp-v02-confirmation.json \
             evidence/mbpp-v02-confirmation-manifest.json \
             --expect-artifact-sha256 70394c419298fc872cdd08e8aec12d17d5a56aa20f7d3c9f09fe8fdbf26c6ba9 \
             --expect-artifact-evidence-sha256 2a652df92f99fa81f785244d966829e909d31f200e5a1520b76e6b46fb45d3e0
       - name: Verify frozen StateLease Stage-A record
         run: >-
-          recurquant verify-statelease-stage-a
+          uv run --frozen recurquant verify-statelease-stage-a
           evidence/experiment012-statelease-stage-a-666.json
       - name: Lint
-        run: ruff check .
+        run: uv run --frozen ruff check .
       - name: Test
-        run: pytest
+        run: uv run --frozen pytest
       - name: Check generated README assets
-        run: python scripts/generate_readme_assets.py --check
+        run: uv run --frozen python scripts/generate_readme_assets.py --check
 
   package:
     name: Build wheel and sdist

.gitignore

@@ -9,6 +9,7 @@ __pycache__/
 .pytest-of-*/
 .pytest/
 .ruff_cache/
+.cache/
 .coverage
 htmlcov/
 dist/

.gitleaks.toml

@@ -45,6 +45,14 @@ regexes = [
   '''"[A-Za-z0-9_./-]+\.md"\s*:\s*"[0-9a-f]{64}"''',
 ]
 
+[[allowlists]]
+description = "Pinned public RULER Git blob object IDs"
+targetRules = ["generic-api-key"]
+regexTarget = "line"
+regexes = [
+  '''"scripts/[A-Za-z0-9_./-]+"\s*:\s*\(?"[0-9a-f]{40}"''',
+]
+
 [[allowlists]]
 description = "Dtype assertions on recurrent-state buffers"
 targetRules = ["generic-api-key"]

README.md

@@ -281,6 +281,21 @@ This recomputes the metrics, storage contracts, and eight gate decisions
 offline. See the [result note](research/EXPERIMENT_012_STAGE_A_RESULT.md) for
 the full method table, storage breakdown, gate outcomes, and limits.
 
+The current `main` branch can also run that exact frozen StateLease-H5 row plan
+through the pinned model as an interactive smoke test:
+
+```bash
+recurquant qwen35 --policy statelease-h5 --device auto --max-new-tokens 16
+```
+
+This path reconstructs and authenticates all 1,976 promoted row identities,
+attaches the causal `Qwen35StateLeaseObserver` for the complete forward loop,
+and reports the full `3,454,664`-byte resident footprint: packed checkpoint
+(including its precision mask), query EMA, and replay capacity. It is a batch-one eager
+correctness/demo path. Its output is not new Experiment 012 or Stage-B evidence,
+and it does not support a fused-kernel, latency, peak-memory, or breakthrough
+claim.
+
 ## Scope
 
 The supported public surface is deliberately narrow:
@@ -306,12 +321,13 @@ beat all three same-byte random placements.
 
 That's one measured case study, not proof of novelty or general superiority.
 Q-Mamba already studies 4-bit persistent Mamba2 states, Quamba2 quantizes
-cached SSM states, and other mixed-precision and replay systems overlap parts
-of this design space. Experiment 009 adds a positive 32-task development result
-for a known right-RHT codec composed with CQER-32 — it isn't a new confirmation
-or evidence that Hadamard quantization is new. RecurQuant has no fused packed
-kernel or measured speed claim. So I don't present it as a breakthrough, a
-whole-model memory reduction, or a cross-model result. See the
+cached SSM states, SGLang compresses idle Mamba/GDN prefix checkpoints to INT8,
+and other mixed-precision, replay, and fused GDN systems overlap parts of this
+design space. Experiment 009 adds a positive 32-task development result for a
+known right-RHT codec composed with CQER-32 — it isn't a new confirmation or
+evidence that Hadamard quantization is new. RecurQuant has no fused packed
+StateLease kernel or measured speed claim. So I don't present it as a
+breakthrough, a whole-model memory reduction, or a cross-model result. See the
 [limits note](research/CLAIM_BOUNDARY.md) and
 [prior-art review](research/PRIOR_ART.md) for the exact comparison.
 
@@ -346,4 +362,4 @@ Reproducible compatibility reports, model-family adapters, and work toward a
 fused packed recurrent kernel are all welcome. Open an
 [issue](https://github.com/Labeeb2339/recurquant/issues) with a minimal
 reproducer and `cache.storage_summary()`; don't include access tokens, private
-prompts, or auth files.
+prompts, or authentication files.

docs/compatibility.md

@@ -29,7 +29,9 @@ development record remains available in
 implementation. Both default to the frozen v0.2 mixed policy: model layer 0 at
 INT8 and every other recurrent layer at INT4, with group size 128 and FP16
 scales. `--policy uniform-int4-stress` is retained only for reproducing the
-uniform INT4 stress baseline.
+uniform INT4 stress baseline. On the current branch,
+`--policy statelease-h5` selects the exact Experiment 012 row identity and keeps
+the causal StateLease observer active across prefill and decode.
 
 The command downloads the pinned model and tokenizer unless
 `--local-files-only` is supplied. It performs manual greedy decoding; the
@@ -62,6 +64,17 @@ path and reported 2,564,096 resident bytes, 18,874,368 FP32-reference bytes, a
 realized. This is a functional integration check, not a quality or latency
 benchmark.
 
+The StateLease-H5 installed-path smoke used the same pinned model revision,
+Python `3.11.15`, PyTorch `2.13.0+cpu`, Transformers `5.14.1`, and eager CPU
+decoding. A two-token continuation completed with all 18 layers observed, 36
+committed observations, and 18 checkpoints. An eight-token continuation also
+exercised the controller: 144 committed observations, 18 c4 decisions, and 36
+checkpoints. Both runs reported exactly `3,454,664` resident bytes including the
+packed checkpoint (which includes its precision mask), query EMA, and replay
+capacity. These are functional
+integration checks only; they are not CUDA validation, new Experiment 012
+evidence, or latency/quality benchmarks.
+
 The following paths are unsupported or not yet validated:
 
 - sampling, beam sampling, diverse or constrained beam search, assisted or

docs/reproducing.md

@@ -74,14 +74,14 @@ FP16 scales, and nearest rounding.
 
 ```powershell
 .venv\Scripts\python.exe -m recurquant.cli qwen35 `
-  --device cuda `
+  --device auto `
   --max-new-tokens 32 `
   --prompt "Explain recurrent-state quantization in two sentences."
 ```
 
 ```bash
 .venv/bin/python -m recurquant.cli qwen35 \
-  --device cuda \
+  --device auto \
   --max-new-tokens 32 \
   --prompt "Explain recurrent-state quantization in two sentences."
 ```
@@ -100,6 +100,40 @@ attention on one materialized device, and every forward must run inside
 [`compatibility.md`](compatibility.md) for unsupported generation and runtime
 modes.
 
+### Run the exact StateLease-H5 policy
+
+Install the current branch rather than the older `v0.2.0a1` tag, then select
+the frozen Experiment 012 policy explicitly:
+
+```powershell
+.venv\Scripts\python.exe -m recurquant.cli qwen35 `
+  --policy statelease-h5 `
+  --device cuda `
+  --max-new-tokens 16 `
+  --json
+```
+
+```bash
+.venv/bin/python -m recurquant.cli qwen35 \
+  --policy statelease-h5 \
+  --device cuda \
+  --max-new-tokens 16 \
+  --json
+```
+
+The factory authenticates the complete 1,976-row Experiment 012 precision
+identity, not only its per-layer quotas. The command keeps
+`Qwen35StateLeaseObserver` active across prefill and decode, then reports
+boundary choices, committed observations, checkpoint bytes, and the complete
+`3,454,664`-byte resident footprint. For application code, pair
+`create_qwen35_experiment012_statelease_h5_cache(model)` with
+`Qwen35StateLeaseObserver(model, caches=[cache])` around the entire model-call
+sequence.
+
+This is an interactive batch-one eager smoke path. It does not create a new
+experiment artifact, rerun Experiment 012, satisfy its unopened Stage-B
+protocol, measure peak accelerator memory, or establish kernel speed.
+
 ## 2. Reproduce the development evidence
 
 The committed calibration and prepared manifest are sufficient to repeat the
@@ -372,6 +406,7 @@ all eight gate decisions without importing the experiment runner:
   evidence/experiment012-statelease-stage-a-666.json
 ```
 
-No StateLease Stage-B command is published yet. Experiment 012's protocol
-requires a new three-workload identity and a genuine StateLease evaluator before
-any model-backed Stage-B run.
+The installed `qwen35 --policy statelease-h5` command above is a model-backed
+interactive smoke, not a Stage-B evaluator. No StateLease Stage-B command is
+published yet. Experiment 012's protocol requires a new three-workload identity
+and a genuine StateLease evaluator before any Stage-B evidence run.

pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["hatchling>=1.27"]
+requires = ["hatchling==1.31.0"]
 build-backend = "hatchling.build"
 
 [project]
@@ -63,7 +63,7 @@ recurquant = "recurquant.cli:main"
 packages = ["src/recurquant"]
 
 [tool.pytest.ini_options]
-addopts = "-q --basetemp ./.pytest-ci"
+addopts = "-q --basetemp ../.pytest-recurquant"
 testpaths = ["tests"]
 
 [tool.ruff]

requirements/experiment013-calibration.txt

@@ -0,0 +1,59 @@
+# Exact Windows/Python 3.11 calibration environment resolved on 2026-08-15.
+# The official CUDA wheel is URL- and SHA-256-pinned because PyPI's Windows
+# wheel is not the required CUDA 13.0 build. The sealed runtime manifest binds
+# every staged distribution file at point of use; this file freezes the 54
+# loadable distributions (setuptools is resolver-only and excluded from staging).
+annotated-doc==0.0.5
+aiohappyeyeballs==2.7.1
+aiohttp==3.14.3
+aiosignal==1.4.0
+anyio==4.14.2
+attrs==26.1.0
+certifi==2026.7.22
+charset-normalizer==3.4.9
+click==8.4.2
+colorama==0.4.6
+datasets==4.8.5
+dill==0.4.1
+filelock==3.32.2
+frozenlist==1.8.0
+fsspec==2026.2.0
+h11==0.16.0
+hf-xet==1.5.2
+httpcore==1.0.9
+httpx==0.28.1
+huggingface-hub==1.26.0
+idna==3.18
+Jinja2==3.1.6
+markdown-it-py==4.2.0
+MarkupSafe==3.0.3
+mdurl==0.1.2
+mpmath==1.3.0
+multidict==6.7.1
+multiprocess==0.70.19
+networkx==3.6.1
+numpy==2.4.6
+packaging==26.2
+pandas==3.0.5
+propcache==0.5.2
+pyarrow==25.0.0
+Pygments==2.20.0
+python-dateutil==2.9.0.post0
+PyYAML==6.0.3
+regex==2026.7.19
+requests==2.34.2
+rich==15.0.0
+safetensors==0.8.0
+shellingham==1.5.4
+six==1.17.0
+sympy==1.14.0
+tokenizers==0.22.2
+torch @ https://download-r2.pytorch.org/whl/cu130/torch-2.13.0%2Bcu130-cp311-cp311-win_amd64.whl#sha256=45e97bd9bc0416f4f4190b5098c55119a389fa5a7c8bbf2639f08f1d04e0a0dc
+tqdm==4.70.0
+transformers==5.14.1
+typer==0.27.0
+typing-extensions==4.16.0
+tzdata==2026.3
+urllib3==2.7.0
+xxhash==3.8.1
+yarl==1.24.5

requirements/experiment013-ruler.txt

@@ -0,0 +1,40 @@
+# Complete tokenizer-only environment used to generate the frozen Experiment
+# 013 RULER receipts. PyTorch is intentionally absent: this environment must
+# not load model weights.
+annotated-doc==0.0.5
+anyio==4.14.2
+beautifulsoup4==4.15.0
+certifi==2026.7.22
+click==8.4.2
+colorama==0.4.6
+defusedxml==0.7.1
+filelock==3.32.2
+fsspec==2026.7.0
+h11==0.16.0
+hf-xet==1.5.2
+html2text==2025.4.15
+httpcore==1.0.9
+httpx==0.28.1
+huggingface-hub==1.26.0
+idna==3.18
+joblib==1.5.3
+markdown-it-py==4.2.0
+mdurl==0.1.2
+nltk==3.8.1
+numpy==2.4.6
+packaging==26.2
+pygments==2.20.0
+PyYAML==6.0.3
+regex==2026.7.19
+rich==15.0.0
+safetensors==0.8.0
+scipy==1.17.1
+shellingham==1.5.4
+soupsieve==2.9.1
+tenacity==9.1.4
+tokenizers==0.22.2
+tqdm==4.70.0
+transformers==5.14.1
+typer==0.27.0
+typing-extensions==4.16.0
+wonderwords==3.0.1

research/CLAIM_BOUNDARY.md

@@ -121,11 +121,27 @@ no-replay codecs both had lower excess NLL on the task. This remains a narrow
 one-task method gate, not development evidence or a cross-window, cross-model,
 speed, deployment, practical-advantage, or breakthrough finding.
 
+The current installed smoke path can reconstruct the exact 1,976-row
+StateLease-H5 identity, attach the causal observer, run the pinned model, and
+report the complete `3,454,664`-byte resident footprint. That makes the frozen
+policy inspectable; it does not turn an interactive generation into a new
+experiment, Stage-B evidence, or a kernel benchmark.
+
+The defensible research question is correspondingly narrow: whether an
+exact-byte causal controller for the active, repeatedly updated Gated DeltaNet
+state can allocate physically packed row precision better than strong static,
+thresholded, stochastic-rounding, and checkpoint/replay controls. The present
+evidence does not answer that question beyond the one-task Stage-A screen.
+
 ## Claims prohibited without new evidence
 
 - "First recurrent-state quantization method."
+- "First quantized Gated DeltaNet state" or "first reduced-precision active
+  Gated DeltaNet state."
 - "First sub-8-bit recurrent model."
 - "First update-aware recurrent cache."
+- "First dynamic mixed-precision SSM cache."
+- "First fused Gated DeltaNet recurrence" or "fastest Gated DeltaNet serving."
 - "Lossless" unless exact output equivalence is demonstrated in the stated mode.
 - "Reduces total model memory by 7.36x." The measured ratio covers resident
   recurrent-state payloads and scales only.
@@ -138,8 +154,9 @@ speed, deployment, practical-advantage, or breakthrough finding.
 
 RecurQuant packages a physical low-bit recurrent-state cache, a frozen per-layer
 allocation policy, exact-byte controls, an independently checkable confirmation
-verifier, a preregistered evaluation protocol, and labelled evidence artifacts.
-Its scoped held-out result is reproducible without expanding the claim. The
-current Python path is not a fused low-bit recurrence kernel. RecurQuant does
-not claim authorship of Qwen3.5 or its architecture, which remain credited to
-the Qwen team.
+verifier, a preregistered evaluation protocol, labelled evidence artifacts, and
+an exact-plan StateLease smoke path. Its scoped held-out result is reproducible
+without expanding the claim. The current Python path materializes recurrent
+states and is not a fused low-bit recurrence kernel. RecurQuant does not claim
+authorship of Qwen3.5 or its architecture, which remain credited to the Qwen
+team.