Release packed RecurQuant cache with held-out MBPP confirmation

.github/ISSUE_TEMPLATE/qwen35_compatibility.yml

@@ -0,0 +1,104 @@
+name: Qwen3.5 compatibility report
+description: Record a reproducible working, partial, or failing Qwen3.5 configuration.
+title: "[Qwen3.5] "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This form maps real compatibility; it does not certify output quality or production readiness. **Never paste access tokens, authentication files, private prompts, proprietary model data, or other secrets.** Use a short public or synthetic prompt.
+
+  - type: dropdown
+    id: outcome
+    attributes:
+      label: Outcome
+      options:
+        - Works for the reported path
+        - Partially works or gives incorrect behavior
+        - Fails with an exception
+    validations:
+      required: true
+
+  - type: input
+    id: recurquant_version
+    attributes:
+      label: RecurQuant version or commit
+      placeholder: 0.2.0a1 or full commit hash
+    validations:
+      required: true
+
+  - type: input
+    id: checkpoint
+    attributes:
+      label: Exact Qwen3.5 checkpoint and revision
+      description: Include both the model ID and immutable revision hash.
+      placeholder: Qwen/Qwen3.5-0.8B-Base @ dc7cdfe2ee4154fa7e30f5b51ca41bfa40174e68
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Software and hardware
+      placeholder: |
+        OS: Windows 11
+        Python: 3.11.x
+        PyTorch: 2.x (include CUDA suffix)
+        Transformers: 5.14.1
+        Device: NVIDIA GPU model or CPU
+        CUDA runtime and driver: version or not applicable
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: execution
+    attributes:
+      label: Execution configuration
+      description: Report values even when the run succeeds.
+      placeholder: |
+        Dtype: bfloat16
+        Attention implementation: eager
+        Device map or placement: one CUDA device
+        Batch size: 1
+        Path: direct forward, greedy generation, beam search, etc.
+        Prefill tokens: 32
+        Decode or generated tokens: 32
+        Cache: bits=4, group_size=128, rounding=nearest
+        Layer overrides: none
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproducer
+    attributes:
+      label: Minimal public reproducer
+      description: Use a public or synthetic prompt and include model loading, cache creation, and the failing or working call.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: result
+    attributes:
+      label: Result
+      description: For a failure, include the complete traceback. For a working path, state exactly what completed; do not infer quality, speed, or memory improvements.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: storage_summary
+    attributes:
+      label: Cache storage summary
+      description: Paste `cache.storage_summary()` after at least one cache update when available.
+      render: shell
+
+  - type: checkboxes
+    id: disclosure
+    attributes:
+      label: Submission check
+      options:
+        - label: I used a public or synthetic prompt and removed secrets, access tokens, authentication files, private prompts, and proprietary data.
+          required: true
+        - label: I reported the exact checkpoint revision and did not turn a successful run into a quality, speed, peak-memory, or production-readiness claim.
+          required: true

.github/ISSUE_TEMPLATE/reproducible_bug.yml

@@ -0,0 +1,105 @@
+name: Reproducible bug
+description: Report a RecurQuant defect with enough detail to reproduce it.
+title: "[Bug] "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reducing the problem. **Do not include access tokens, authentication files, private prompts, proprietary model data, or other secrets.** Replace private inputs with a minimal public example before submitting.
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Affected area
+      options:
+        - Packed cache integration
+        - Quantization or byte accounting
+        - Qwen3.5 factory or generation
+        - CLI or packaging
+        - Evaluation tooling
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: recurquant_version
+    attributes:
+      label: RecurQuant version or commit
+      description: Use `python -c "import recurquant; print(recurquant.__version__)"` or provide the full commit hash.
+      placeholder: 0.2.0a1 or 0123456789abcdef...
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Include every line and replace only values that truly do not apply.
+      placeholder: |
+        OS: Windows 11
+        Python: 3.11.x
+        PyTorch: 2.x (include CUDA suffix)
+        Transformers: 5.14.1
+        Device: NVIDIA GPU model or CPU
+        Dtype: bfloat16, float16, or float32
+        Attention implementation: eager
+        Batch size: 1
+        Execution mode: direct forward, greedy generation, beam search, etc.
+    validations:
+      required: true
+
+  - type: textarea
+    id: model
+    attributes:
+      label: Model and cache configuration
+      description: Give the exact model ID, revision, cache bits, group size, rounding mode, and any layer overrides. Write `not applicable` for a model-independent bug.
+      placeholder: |
+        Model: Qwen/Qwen3.5-0.8B-Base
+        Revision: dc7cdfe2ee4154fa7e30f5b51ca41bfa40174e68
+        Cache: bits=4, group_size=128, rounding=nearest
+        Layer overrides: none
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproducer
+    attributes:
+      label: Minimal reproducer
+      description: Provide one self-contained example using public or synthetic input.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: observed
+    attributes:
+      label: Observed behavior and traceback
+      description: Paste the complete traceback or exact incorrect output. Remove secrets and private paths where possible.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: State the behavior you expected and why.
+    validations:
+      required: true
+
+  - type: textarea
+    id: storage_summary
+    attributes:
+      label: Storage summary
+      description: For packing or byte-accounting bugs, paste `cache.storage_summary()`. Otherwise write `not applicable`.
+      render: shell
+
+  - type: checkboxes
+    id: disclosure
+    attributes:
+      label: Submission check
+      options:
+        - label: I used a minimal public or synthetic input and removed secrets, access tokens, authentication files, private prompts, and proprietary data.
+          required: true
+        - label: I checked the current compatibility boundary and am not presenting an unsupported mode as validated.
+          required: true

.github/workflows/ci.yml

@@ -2,6 +2,8 @@ name: CI
 
 on:
   push:
+    branches:
+      - main
   pull_request:
 
 permissions:
@@ -13,15 +15,83 @@ jobs:
     timeout-minutes: 20
     steps:
       - uses: actions/checkout@v7.0.1
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@v7.0.0
         with:
           python-version: "3.11"
       - uses: astral-sh/setup-uv@v9.0.0
         with:
           python-version: "3.11"
+          version: "0.11.31"
       - name: Install
         run: uv pip install --system -e ".[dev]"
+      - name: Verify frozen MBPP confirmation
+        run: |
+          recurquant verify-confirmation \
+            evidence/mbpp-v02-confirmation.json \
+            evidence/mbpp-v02-confirmation-manifest.json \
+            --expect-artifact-sha256 70394c419298fc872cdd08e8aec12d17d5a56aa20f7d3c9f09fe8fdbf26c6ba9 \
+            --expect-artifact-evidence-sha256 2a652df92f99fa81f785244d966829e909d31f200e5a1520b76e6b46fb45d3e0
       - name: Lint
         run: ruff check .
       - name: Test
         run: pytest
+      - name: Check generated README assets
+        run: python scripts/generate_readme_assets.py --check
+
+  package:
+    name: Build wheel and sdist
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          version: "0.11.31"
+      - name: Build distributions
+        run: uv build
+      - name: Check distribution metadata
+        run: uvx --from "twine==6.2.0" twine check --strict dist/*
+      - uses: actions/upload-artifact@v7.0.1
+        with:
+          name: recurquant-dist
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 7
+
+  wheel-install:
+    name: Wheel import / ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    needs: package
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 35
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python-version: "3.11"
+          - os: ubuntu-latest
+            python-version: "3.13"
+          - os: windows-latest
+            python-version: "3.11"
+    steps:
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: actions/download-artifact@v8.0.1
+        with:
+          name: recurquant-dist
+          path: dist
+      - name: Install CPU PyTorch
+        run: python -m pip install "torch>=2.7" --index-url https://download.pytorch.org/whl/cpu
+      - name: Install the built wheel
+        run: >-
+          python -c "import pathlib, subprocess, sys;
+          wheel = next(pathlib.Path('dist').glob('*.whl'));
+          subprocess.check_call([sys.executable, '-m', 'pip', 'install', str(wheel)])"
+      - name: Validate import and console entry point
+        run: |
+          python -c "import importlib.metadata as m, recurquant; assert m.version('recurquant') == recurquant.__version__ == '0.2.0a1'; print(recurquant.__version__)"
+          recurquant demo --bits 4 --group-size 16

.gitleaks.toml

@@ -11,3 +11,11 @@ regexes = [
   '''"token_ids_sha256":\s*"[0-9a-f]{64}"''',
   '''"tokenizer_revision":\s*"[0-9a-f]{40}"''',
 ]
+
+[[allowlists]]
+description = "Prepared-manifest token ID digests"
+targetRules = ["generic-api-key"]
+regexTarget = "line"
+regexes = [
+  '''"(?:code_token_ids_sha256|prompt_token_ids_sha256|token_manifest_sha256)"\s*:\s*"[0-9a-f]{64}"''',
+]

CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+This file records user-visible package changes. RecurQuant is pre-release
+software, so compatibility can still change between development versions.
+
+## [0.2.0a1] - 2026-07-22
+
+### Added
+
+- Physical INT4 nibble packing and INT8 payload storage for persistent Gated
+  DeltaNet recurrent states, with grouped FP16 or FP32 scales.
+- `PackedRecurrentStateCache` for keeping recurrent states packed between layer
+  calls, with opt-in evidence recording and exact resident-byte accounting.
+- A guarded Qwen3.5 cache factory, pinned Qwen3.5 quickstart, and compatibility
+  checks for the tested Transformers release and eager, single-device
+  inference path.
+- A reusable frozen v0.2 mixed-policy cache helper and an installed
+  `recurquant qwen35` workflow shared with the source-tree quickstart. Uniform
+  INT4 remains available only as an explicitly named stress baseline.
+- Machine-readable `recurquant qwen35 --json` output, a one-click Colab
+  notebook, and a hash-anchored reproduction and extension guide.
+- Offline `recurquant verify-artifact` checks for strict JSON, whole-file
+  SHA256 anchors, and canonical evidence hashes.
+- `recurquant verify-confirmation` independently checks the frozen MBPP
+  manifest, artifact, quality gates, and optional raw checkpoint arrays. It
+  distinguishes verified pass/fail outcomes from unanchored evidence.
+- Frozen MBPP calibration and development evaluation workflows with pinned
+  dataset/model revisions, prepared token manifests, canonical evidence hashes,
+  equal-byte baselines, and resumable per-task checkpoints.
+- Held-out confirmation evidence on all 500 frozen MBPP test tasks and 30,244
+  teacher-forced reference-code tokens. The mixed layer-0 INT8 plus 17-layer
+  INT4 layout reduced task-macro excess NLL by 72.75% relative to uniform INT4
+  while using exactly 2,564,096 resident recurrent-state bytes; every
+  preregistered quality gate passed.
+- A compressed release attachment containing the retained raw confirmation
+  checkpoint for independent reconstruction of every reported gate.
+- Unit coverage for packing parity, byte accounting, cache integration, public
+  data split discipline, and the supported Qwen3.5 factory path.
+
+### Changed
+
+- Scale-storage emulation now uses the declared physical FP16 or FP32 format;
+  superseding diagnostic results retain the earlier record instead of rewriting
+  it.
+- The Transformers dependency is pinned to exactly `5.14.1` while the alpha
+  package depends on that release's internal linear-attention cache contract.
+- FP16 scale storage is identified as the evaluated default. FP32 scale storage
+  remains supported for experiments but is not covered by full-model evidence.
+
+### Fixed
+
+- Beam-cache reordering now permutes packed INT4/INT8 payloads and scales
+  directly instead of dequantizing and requantizing the recurrent state.
+
+### Known limitations
+
+- The current Python path materializes one recurrent state while its layer
+  executes. It does not establish faster inference, lower whole-model memory,
+  or lower peak CUDA memory.
+- Full-model evidence is currently limited to the pinned
+  `Qwen/Qwen3.5-0.8B-Base` revision and the environment described in
+  [docs/compatibility.md](docs/compatibility.md).
+- The held-out result is limited to teacher-forced likelihood on the pinned
+  Qwen3.5 checkpoint and MBPP construction. It does not establish generated-code
+  correctness, novelty, cross-model generality, or a breakthrough.

CITATION.cff

@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+message: "If you use RecurQuant, cite this software repository."
+title: RecurQuant
+type: software
+authors:
+  - name: "Muhammad Labeeb Aryan"
+version: 0.2.0a1
+date-released: 2026-07-22
+repository-code: "https://github.com/Labeeb2339/recurquant"
+url: "https://github.com/Labeeb2339/recurquant"
+license: Apache-2.0