vyre-driver-wgpu 0.7.2

# vyre-driver-wgpu

wgpu backend for Vyre IR. It implements `vyre_driver::VyreBackend` and the registered target compiler and materializer facets on any wgpu-capable GPU (Vulkan, DX12, Metal, WebGPU).

This crate is the `0.7.2` portable GPU fallback backend. It is a GPU fallback
for systems where CUDA is not the target path, not a CPU fallback.

```
cargo add vyre vyre-driver vyre-driver-wgpu vyre-runtime
```

## Example

```rust
use vyre_driver::backend::backend_registration;
use vyre_driver_wgpu::WGPU_BACKEND_ID;
use vyre_runtime::ArtifactSession;

let registration = backend_registration(WGPU_BACKEND_ID)?;
let session = ArtifactSession::compile(registration, &request)?;
```

`request` is a validated whole-program `CompileRequest`. Bind inputs through a
typed `BindingSet`, submit through the session's `ArtifactInstance`, and wait
for completion before readback.

## Features

- Pipeline cache: reuses compiled WGSL pipelines across dispatches by content hash.
- Buffer pool: reuses GPU buffer allocations across dispatches.
- Validation cache: skips repeated capability checks for already-validated programs.
- Lowering happens in the registered target compiler. Materialization admits authenticated target payload bytes rather than compiling a caller-owned `Program`.
- Release evidence must prove feature-surface coverage, backend metadata, and conformance for `vyre-driver-wgpu@0.7.2`.

## Requirements

- A wgpu-capable GPU. This crate does NOT silently fall back to CPU. Absence of a GPU is surfaced as an actionable error, not a degradation.
- `wgpu = 25.x`. Pinned: major wgpu version bumps are a `vyre-driver-wgpu` major bump.

## MSRV

Rust 1.85.

## License

MIT OR Apache-2.0.

<!-- BEGIN GENERATED CLI CONTRACT -->
## Command-line interface

This section is generated from `docs/CLI.toml` and executable help output.

### `vyre-wgpu`

```console
./cargo_full run -p vyre-driver-wgpu --bin vyre-wgpu -- --help
```

Run the real GPU smoke path:

```console
./cargo_full run -p vyre-driver-wgpu --bin vyre-wgpu -- demo
# vyre demo gpu_u32=42
```

Commands: `demo`.

Hardware: The demo requires a Vulkan, Metal, DX12, or WebGPU compute device and never falls back to CPU.

Environment: Backend diagnostics honor the driver crate's VYRE_WGPU_TIMESTAMPS, VYRE_CACHE_DIR, VYRE_DUMP_KDESC, and VYRE_CAPTURE_FAILED_DESCRIPTOR controls.

Configuration: The demo has no config file. Device and dispatch configuration come from the WGPU backend defaults.

Failure behavior: Invalid arguments, missing devices, lowering failures, dispatch failures, and malformed output return status 1 with an actionable error.

Exit codes: 0 on help, version, or exact demo success; 1 on argument, device, dispatch, or output failure.
<!-- END GENERATED CLI CONTRACT -->

<!-- BEGIN GENERATED CRATE CONTRACT -->
## Crate contract

This section is generated by `python3 scripts/crate_readmes.py --write` from
the crate manifest, release train, ownership registry, and crate-guide metadata.

### Purpose

Own pure WGSL target compilation, portable GPU acquisition, materialization, dispatch, graph execution, and backend evidence.

### Boundaries

The `portable-driver` owner maintains this `concrete-backend` crate at `vyre-driver-wgpu`.
Its allowed internal production dependencies are: `vyre-driver`, `vyre-emit-naga`, `vyre-foundation`, `vyre-lower`, `vyre-megakernel`, `vyre-self-substrate`, `vyre-spec`.
Any other normal or build dependency requires an ownership-registry change.

### Minimal real example

Run the checked-in behavior from `vyre-driver-wgpu/examples/wgpu_release_surface.rs`:

```console
CARGO_BUILD_JOBS=1 ./cargo_full run -p vyre-driver-wgpu --example wgpu_release_surface
```

### Features

- Manifest features: `c-parser`, `default`, `matching-dfa`, `matching-nfa`, `matching-substring`, `math-linalg`, `math-scan`, `nn-attention`, `parity-testing`, `wgpu`
- Default feature members: None

### Errors and unsupported behavior

Device acquisition, lowering, allocation, and dispatch failures are explicit backend errors. A requested device path never falls back to another backend.

### Testing

Use [`docs/testing/vyre-driver-wgpu.md`](../docs/testing/vyre-driver-wgpu.md) for exact commands, Cargo targets, hardware
requirements, evidence outputs, expected skips, and failure semantics.

### Release status

`vyre-driver-wgpu@0.7.2` is a publishable crate on the current Vyre release train. Publication still requires the release evidence and user-approval gates.

### Ownership

`docs/CRATE_OWNERSHIP.toml` is authoritative for this crate's responsibility
and allowed internal edges. Regenerate `docs/CRATE_GRAPH.md` and
`docs/OWNERSHIP.md` after changing that registry.

### License

Licensed under either of

- Apache License, Version 2.0, or
- MIT license

at your option. See the workspace `LICENSE-APACHE` and `LICENSE-MIT` files.

<!-- END GENERATED CRATE CONTRACT -->