# Backend Contract
`VyreBackend` is the only runtime interface required by vyre-conform. Any
backend, including wgpu, CUDA, Metal, TPU, or FPGA runtimes, conforms by
implementing this trait and returning the bytes required by the specification.
## Required Behavior
The suite can dispatch either complete WGSL or serialized vyre IR. Backends
that consume WGSL implement `dispatch`. Backends that consume IR, CUDA, PTX,
SPIR-V, MSL, or another native form should override `dispatch_program`.
```rust
fn name(&self) -> &str;
fn dispatch(
&self,
wgsl: &str,
input: &[u8],
output_size: usize,
config: DispatchConfig,
) -> Result<Vec<u8>, String>;
fn dispatch_program(
&self,
program: &[u8],
input: &[u8],
output_size: usize,
config: DispatchConfig,
) -> Result<Vec<u8>, String>;
fn max_convention(&self) -> Convention;
```
### `name`
Returns a human-readable backend identifier used in reports and certificates.
### `dispatch`
`wgsl` is ready-to-compile shader source. `input` is the exact input byte
buffer for the test case. `output_size` is the exact number of bytes the suite
expects back. `config` supplies workgroup size, workgroup count, calling
convention, optional lookup data, and output buffer initialization policy.
### `dispatch_program`
`program` is a serialized `ir::Program` blob produced by `Program::to_bytes()`.
The default implementation deserializes it, lowers it through
`vyre::lower::wgsl`, and calls `dispatch()`. That default is sufficient for
WGSL-only backends.
Native backends should override `dispatch_program()` and lower the IR directly
to their target, such as CUDA/PTX, SPIR-V, MSL, or an accelerator-specific
kernel format. A native override must preserve the same input, output,
`DispatchConfig`, and exact-byte result contract as `dispatch()`.
### `max_convention`
Returns the highest `Convention` version the backend supports. The default is
`Convention::V1`. The suite will not request a convention higher than this
value; doing so would be a suite bug, not a backend failure.
On success, both dispatch methods must return exactly `output_size` bytes.
Extra bytes, missing bytes, uninitialized bytes, and target-native padding are
conformance failures.
On failure, the backend must return an actionable error string that includes a
`Fix: ...` clause. Errors are part of the contract because they are how
implementors repair non-conformance.
## Acceptable Errors
`Err` is acceptable when the dispatch exceeds a documented backend resource
limit outside the conformance profile, such as an unsupported convention
version, unavailable required device feature at backend construction time, or a
test configuration larger than the backend's published maximum.
Resource availability must be checked at backend construction where possible. A
constructed `VyreBackend` is assumed ready to dispatch.
## Conformance-Violation Errors
`Err` is a conformance violation when the suite provides valid WGSL or valid
serialized IR, valid input bytes, a supported calling convention, and a dispatch
within the backend's declared resource limits. Compile failure, lowering
failure, pipeline creation failure, readback failure, timeout, device loss, or
unsupported valid input means the backend did not implement the contract.
Returning `Err` instead of wrong bytes does not make the test pass. Valid input
must produce valid output.
## Thread Safety
Thread safety is not required by the trait. The conformance suite treats a
backend instance as single-threaded unless a future version explicitly adds a
parallel backend contract. Backend implementations may use internal mutation
behind `&self`, but they must not leak state between dispatches in a way that
changes results.
## Lifetime
The backend is constructed once and used for the full suite run. Expensive
runtime setup, device selection, adapter selection, compiler initialization,
and feature validation belong in construction. `dispatch()` should execute the
provided shader and return the resulting bytes.