# CPU Reference Functions
The CPU reference function is ground truth for point queries. For a given input
byte sequence, the function returns the exact output byte sequence required of
every conforming backend. The function is not an example implementation of the
spec; the function is the spec for that point.
## Requirements
CPU references are written in standard Rust and must be simple enough to verify
by inspection. They should use direct integer operations, explicit byte
decoding and encoding, and clear branches for defined edge cases. A reviewer
should be able to read the function and know what happens for zero, maximum
values, empty inputs, short inputs, overflow, and out-of-bounds cases.
The reference must handle every input accepted by the operation signature. It
must not panic on malformed, empty, or short byte slices produced by an
adversarial generator. If missing bytes have defined semantics, decode them
according to that operation's rule. If a generator can reach an edge case, the
reference must define it.
The reference must satisfy every declared law. vyre-conform self-tests the CPU
reference against the operation's law set before treating backend results as
meaningful. If the reference violates a declared law, the specification is
internally inconsistent and the operation cannot be certified.
## Style
Use the Rust standard library and obvious operations. Prefer `wrapping_add`,
`wrapping_sub`, and `wrapping_mul` when wrapping behavior is required. Spell
out special cases such as division by zero and masked shifts. Avoid clever bit
tricks unless the operation being specified is itself the bit trick and the
expression is still easier to inspect than a lookup table.
CPU references must not call backend code, GPU code, target-specific intrinsics,
random generators, clocks, filesystem APIs, network APIs, or global mutable
state. They are deterministic pure functions from bytes to bytes.
## Edge Cases
Every reference must define behavior for empty inputs, zero values, maximum
values, one-past-boundary values, overflow, underflow, masked shifts, division
by zero, modulo by zero, and variable-length buffers when those cases are
reachable for the operation. Defined behavior is mandatory even when hardware
would normally trap, return vendor-specific data, or leave memory unchanged.
For vyre IR, important permanent examples include `Div(a, 0) = 0`,
`Mod(a, 0) = 0`, `Shl(a, b) = a << (b & 31)`, `Shr(a, b) = a >> (b & 31)`,
out-of-bounds loads returning zero, and out-of-bounds stores having no effect.
## Consequence
When a backend disagrees with the CPU reference on a valid input, that is a
conformance failure. The error should identify the operation, input, expected
bytes, actual bytes, and a fix direction. The backend must change, or the
operation must be versioned with a new permanent definition; the existing
reference is never silently reinterpreted.