mirror of
https://github.com/ruvnet/RuView
synced 2026-06-09 10:13:17 +00:00
rUv
81cc241b9e
The Rust port at v2/ has been the primary codebase since the rename in #427. The Python implementation at v1/ is no longer the active target; the only load-bearing path is the deterministic proof bundle at v1/data/proof/ (per ADR-011 / ADR-028 witness verification). Move the whole Python tree into archive/v1/ and document the policy in archive/README.md: no new features, bug fixes only when they affect a still-load-bearing path (currently just the proof), CI continues to verify the proof on every push and PR. Path references updated in 26 files via path-pattern sed (only matches v1/<known-child> patterns, never bare v1 or API URLs like /api/v1/). Two double-prefix typos (archive/archive/v1/) caught and hand-fixed in verify-pipeline.yml and ADR-011. Validated: - Python proof verify.py imports cleanly at archive/v1/data/proof/ (numpy/scipy still required; CI installs requirements-lock.txt from archive/v1/ now) - cargo test --workspace --no-default-features → 1,539 passed, 0 failed, 8 ignored (unaffected by Python tree relocation) - ESP32-S3 on COM7 untouched (no firmware paths changed) After-merge: contributors should re-run any local `python v1/...` commands as `python archive/v1/...` (CLAUDE.md and CHANGELOG already updated).
75 lines
3.3 KiB
Markdown
75 lines
3.3 KiB
Markdown
# Archive
|
||
|
||
Frozen, no-longer-active components of RuView preserved for historical
|
||
reference, reproducibility, and load-bearing legacy paths the active
|
||
codebase still depends on.
|
||
|
||
## What lives here
|
||
|
||
| Path | What it is | Why it's archived | Still load-bearing? |
|
||
|------|------------|-------------------|---------------------|
|
||
| `v1/` | Original Python implementation of RuView (CSI processing, hardware adapters, services, FastAPI) | Superseded by the Rust workspace at `v2/`; ~810× slower in benchmarks. Kept rather than deleted because the deterministic proof bundle (`v1/data/proof/`) is part of the pre-merge witness verification process per ADR-011 / ADR-028. | **Yes — for the proof bundle only.** Active code lives in `v2/`. |
|
||
|
||
## What "archived" means
|
||
|
||
- **Do not add new features here.** New work goes in `v2/`.
|
||
- **Do not refactor or modernize the archived code beyond what is
|
||
strictly necessary** to keep the load-bearing paths working. The
|
||
Python proof bundle is intentionally frozen so that its SHA-256
|
||
reproducibility holds across releases (per ADR-028's witness
|
||
verification requirement).
|
||
- **Bug fixes inside archived code are allowed** when the bug affects a
|
||
still-load-bearing path (currently: only the Python proof). All
|
||
other "bugs" in archived code are out-of-scope — they are part of
|
||
the historical record and any fix would unnecessarily churn the
|
||
witness hashes.
|
||
- **CI continues to verify the load-bearing paths.**
|
||
`.github/workflows/verify-pipeline.yml` runs the Python proof on
|
||
every push and PR; if you change anything inside `archive/v1/src/`
|
||
or `archive/v1/data/proof/`, expect the determinism check to flag
|
||
it.
|
||
|
||
## Quick reference for the load-bearing paths
|
||
|
||
```bash
|
||
# Run the deterministic Python proof (must print VERDICT: PASS)
|
||
python archive/v1/data/proof/verify.py
|
||
|
||
# Regenerate the expected hash (only if numpy/scipy version legitimately changed)
|
||
python archive/v1/data/proof/verify.py --generate-hash
|
||
|
||
# Run the full Python test suite (legacy, still maintained)
|
||
cd archive/v1&& python -m pytest tests/ -x -q
|
||
```
|
||
|
||
## Why we keep `v1/` rather than delete it
|
||
|
||
1. **Trust kill-switch.** The proof at `v1/data/proof/verify.py` feeds
|
||
a known reference signal through the full pipeline and hashes the
|
||
output. If the active code's behavior drifts, the hash changes and
|
||
CI fails. This is what stops accidental regression in the science
|
||
layer of the codebase.
|
||
|
||
2. **Witness verification.** ADR-028's witness-bundle process bundles
|
||
the proof, the rust workspace test results, and firmware hashes
|
||
into a tarball recipients can self-verify. Removing v1 would break
|
||
that chain.
|
||
|
||
3. **Historical reference.** ADR-011 documents the "no mocks in
|
||
production code" decision; the original violations and their fixes
|
||
live in this Python codebase. The ADRs reference these paths.
|
||
|
||
If the time comes to retire the proof bundle (e.g., a Rust port of
|
||
the proof exists and the Python version is no longer canonical), the
|
||
right move is a single follow-up that simultaneously: ports the
|
||
witness-bundle process, updates `verify-pipeline.yml`, and either
|
||
deletes `archive/v1/` or moves it to a separate read-only repository.
|
||
That decision belongs in its own ADR.
|
||
|
||
## See also
|
||
|
||
- `docs/adr/ADR-011-python-proof-of-reality-mock-elimination.md`
|
||
- `docs/adr/ADR-028-esp32-capability-audit.md`
|
||
- `archive/v1/data/proof/README.md` (if present)
|
||
- `docs/WITNESS-LOG-028.md`
|