wave2-polish: CPU unit tests, clippy fixes, and CI for the Rust host crate

[Peterc3-dev]

Conservative polish pass on cube-memory (research/experiment code backing a published negative-result paper). No experiment logic, algorithms, or reported numbers were changed. Scope was limited to tests for pure reference functions, lint fixes, CI, and doc accuracy.

Changes

Tests (new)

• Added 9 CPU-only unit tests for the FHRR / Cube-Memory reference primitives in shaders/cube-memory-host/src/cpu.rs:
  • cmul matches manual complex multiply; cconj negates the imaginary part.
  • bind then unbind is identity for unit phasors (the core FHRR property); bind is commutative.
  • unitize produces unit modulus (incl. zero-vector eps safety); superpose output is unit modulus.
  • cleanup snaps a self-query back to the exact codebook entry.
  • retrieve output is a convex combination of the gathered value rows / approaches a dominant slot.
• These run on stable Rust with no GPU, and pin the ground truth that the existing GPU tests/parity.rs compares against.

Lint / clippy

• Fixed all clippy warnings in cube-memory-host (lib + tests), behaviour unchanged:
  • field_reassign_with_default → struct-literal init of wgpu::Limits (gpu.rs).
  • cloned_ref_to_slice_refs → std::slice::from_ref (gpu.rs).
  • manual div_ceil → u32::div_ceil (4 sites in parity.rs).
  • index-loop → iter_mut().enumerate() in cube_memory_retrieve (cpu.rs).
  • scoped #[allow(clippy::too_many_arguments)] on the intentional test-only run_pair harness, with rationale.
• cargo clippy -p cube-memory-host --all-targets -- -D warnings is now clean.

CI (new)

• .github/workflows/ci.yml:
  • Rust job — build + clippy -D warnings + cargo test --lib (the new CPU tests) on the stable toolchain.
  • Python job — compileall syntax check + ruff lint (non-blocking).
  • Documents what is deliberately excluded and why (see below).

Docs

• README: corrected the shaders run instructions to distinguish the CPU --lib tests from the GPU parity tests, and updated the "no CI" line under Limitations.

Verified vs UNVERIFIED (honest)

Verified locally (stable Rust 1.95, this machine):

• cargo build -p cube-memory-host — passes.
• cargo clippy -p cube-memory-host --all-targets -- -D warnings — clean.
• cargo test -p cube-memory-host --lib — 9 passed, 0 failed.
• python3 -m compileall over all 43 Python files — passes (syntax only).
• CI YAML parses (yaml.safe_load).

UNVERIFIED (could not run here):

• The rust-gpu shader build (cube-memory-shader{,-builder}) — requires the pinned nightly nightly-2026-04-11 with rust-src/rustc-dev/llvm-tools, not installed on this machine. Not touched.
• The GPU/CPU parity tests in tests/parity.rs — require a Vulkan adapter and the prebuilt .spv. Not run.
• ruff lint — ruff is not installed locally, so the Python lint job's output is unverified (it is non-blocking in CI by design).
• The CI workflow itself has not executed on GitHub Actions yet.
• Python experiment scripts/tests were not modified or executed (need PyTorch + local model checkpoints; conservative-mode untouched).

Not done / TODO

• No packaging (pyproject.toml / pinned requirements.txt) added — the scripts have no single entry point and pull models from local paths; packaging them risks implying a usable library, which the README explicitly disclaims. Left as-is intentionally.
• Pre-existing rustfmt drift in gpu.rs/parity.rs (wider line width than default) was left untouched to keep the diff minimal; only newly added code is rustfmt-clean.

🤖 Generated with Claude Code

[Peterc3-dev]

Independent verification — VERDICT: solid, ready to merge

Reviewed the full diff (296+/12-, 5 files) and reproduced every load-bearing claim on stable Rust 1.95.0 / Python 3.11. No regressions, no overclaims found.

Confirmed locally

• cargo build -p cube-memory-host — passes (stable, with rustup override set stable as CI does).
• cargo clippy -p cube-memory-host --all-targets -- -D warnings — clean.
• cargo test -p cube-memory-host --lib — 9 passed, 0 failed, exactly as reported.
• cargo test -p cube-memory-host --no-run — parity.rs test binary still compiles after the div_ceil refactor.
• python3 -m compileall over all 43 .py files — passes. The CI subset (phase0 phase1 rubik-gen *.py) fully covers all 43; the other top-level dirs contain no Python.
• CI ci.yml parses as valid YAML.

Correctness review

• gpu.rs (struct-literal Limits, slice::from_ref) and parity.rs ((n+63)/64 → u32::div_ceil(64)) refactors are behavior-preserving.
• cpu.rs sims loop (iter_mut().enumerate()) is equivalent to the indexed original.
• The 9 new tests correctly match the actual function semantics (verified against source): bind/unbind identity, commutativity, unit-modulus invariants, cleanup self-query snap, and the softmax convex-combination bounds check are all mathematically sound.
• No experiment logic, paper numbers, phase0/phase1/rubik-gen, or algorithms were touched — the --no experiment logic changed claim holds.

Notes (non-blocking)

• The rust-toolchain.toml in shaders/ pins nightly-2026-04-11 and does apply to bare cargo invocations from that dir (a bare cargo build here tried to auto-download that nightly). The PR's inline comments claiming it 'only applies to crates that opt in via build profile' are technically inaccurate — BUT the CI workflow correctly sidesteps this with rustup override set stable before building, so CI is sound. Worth correcting the comment wording eventually; not a blocker.
• ruff surfaces 33 pre-existing lint errors in the experiment scripts; the CI step is ruff check . || true (non-blocking) and this is accurately documented in the PR body and workflow comments.

All UNVERIFIED items in the PR body (rust-gpu shader build, GPU parity run) are honestly flagged and out of scope. Verification done by an independent reviewer agent.