# tests/SKILL.md — vyre-reference
Read `../../.internals/skills/testing/SKILL.md` first for the category contract.
## Purpose
`vyre-reference` is the **pure-Rust CPU interpreter**. Every GPU
backend's conformance proof is anchored against the byte-for-byte
output this crate produces for every witnessed input. Determinism
is the contract.
## Critical invariants
- **Determinism.** Same `Program` + same inputs + same reference
version → same output bytes, forever. No HashMap iteration
order, no random ordering, no thread-scheduler dependence.
- **Bit-identical to spec.** Every arithmetic / bitwise / atomic op
follows the exact semantics documented in `vyre-spec` +
`docs/memory-model.md`. Reference is the oracle.
- **Sequential workgroup ordering.** The reference runs workgroups
in index order; GPU can legally interleave, but the reference
fixes ONE legal interleaving so certificates are reproducible.
- **Zero unsafe.** The interpreter is pure safe Rust (unsafe is
denied crate-wide).
- **No panic on any validated program.** If `validate(p)` returns
`Ok`, `run(p, inputs)` never panics (errors may arise from
runtime conditions like OOB; those are structured errors).
## Adversarial surface
- Program with maximum-size workgroup memory — budget enforced
- Program with 10 000 loop iterations — bounded, no overflow
- Atomic operations on the same slot from every invocation in a
workgroup — serialization correct
- Shared memory write from invocation N visible to invocation N+1
(sequential semantics)
- Barrier semantics — invocations replay from the barrier
- Integer overflow on every arithmetic op — spec-defined wrap
## Active coverage
- Workgroup execution uses the hashmap interpreter oracle with
persistent locals for cheap subgroup snapshots.
- `NodeStorage` graph execution is covered by randomized DAG
tests that compare against an independent recursive oracle.
- Dual-reference coverage is enforced by the registry tests for the
bitwise primitives that currently publish independent references.
## Cross-crate contracts
- Backend conformance uses `vyre-driver::shadow::ReferenceExecutor`
to wire this interpreter without creating a driver/reference
dependency cycle.
- Consumes `vyre_foundation::Program`, `vyre_foundation::ir::*`
- Consumes `DialectLookup` (post-0.6) — routes `Expr::Call` through
the registry rather than matching on op-id strings
- Output `Value` is consumed by conform runners + byte-identity
proofs in every backend
## Bench targets
- `run_arena_reference` — programs / sec for small programs
- `run_hashmap_reference` (differential oracle) — programs / sec;
target 10× slower than arena reference is acceptable (that's
the oracle's whole point)
- Throughput under shared-memory loads
## Fuzz targets
- `run_fuzz` — arbitrary valid `Program` + arbitrary inputs → no
panic, never silent wrong answer
- `differential_fuzz` — same Program through `run_arena_reference`
and `run_hashmap_reference` → outputs match
## What NOT to test here
- GPU dispatch — concrete driver tests
- Wire format — `vyre-foundation/tests`
- Op metadata — `vyre-spec/tests`
## Running
```bash
cargo test -p vyre-reference
cargo test -p vyre-reference --test adversarial
cargo test -p vyre-reference --test property
cargo test -p vyre-reference --test gap
cargo test -p vyre-reference --test integration
cargo bench -p vyre-reference
cd vyre-reference/fuzz && cargo fuzz run differential_fuzz
```