# Operation Specification Overview
An `OpSpec` is the complete identity of one vyre operation. It does not
describe an implementation strategy. It states what the operation is, how its
bytes are interpreted, which mathematical laws it must satisfy, and which
parts of the input space must be covered.
## Structure
Every operation specification contains:
- `id`: a stable hierarchical identifier such as `primitive.bitwise.xor`.
- `signature`: the input and output types.
- `cpu_fn`: the CPU reference function and point-query ground truth.
- `wgsl_fn`: the canonical WGSL operation fragment used by the harness.
- `laws`: algebraic laws that define structural truth.
- `equivalence_classes`: partitions of the input space.
- `boundary_values`: explicit edge inputs that must be tested.
- `comparator`: the byte comparison rule for CPU and backend outputs.
- `convention`: the calling convention required by the shader wrapper.
- `version`: the semantic version of this operation definition.
- `workgroup_size`: an optional preferred dispatch size for testing.
## Point Truth: `cpu_fn`
The CPU reference answers the question: for this exact input byte sequence,
what exact output byte sequence is correct? It is the authority for parity.
When a backend returns bytes that differ from `cpu_fn`, the backend is wrong
for that input unless the comparator explicitly defines a non-exact relation.
## Structural Truth: `laws`
Laws answer the question: what mathematical structure must this function have?
For XOR, commutativity, associativity, identity `0`, and self-inverse `0`
constrain the operation far more strongly than a list of examples. The algebra
checker verifies each declared law against the CPU reference and against the
backend behavior.
## Input Partitioning: `equivalence_classes`
Equivalence classes describe regions of the input space that share behavior.
For division, nonzero divisors and zero divisors are distinct classes. For
shift operations, shift amounts that differ only outside the low five bits
belong to masked-shift behavior. The suite must cover every class, not just
many random inputs from one easy class.
## Edge Coverage: `boundary_values`
Boundary values are mandatory examples at semantic edges: zero, one,
`u32::MAX`, overflow points, empty buffers, one-past-end indexes, and values
around masks or thresholds. They catch off-by-one, overflow, underflow, and
resource bugs that random generation often misses.
## How The Parts Work Together
`cpu_fn` anchors every individual input. `laws` constrain the function across
families of inputs. `equivalence_classes` ensure the generator reaches each
semantic region. `boundary_values` force the exact edges. A conforming backend
must pass all of them because each catches a different class of failure.