# vyre-driver
Backend-neutral artifact materialization, typed binding, submission, completion,
capability, and lower-level dispatch contracts for Vyre.
Production execution enters this crate after whole-program compilation:
```text
Artifact + authenticated TargetPayload
-> registered ArtifactMaterializer
-> ArtifactInstance
-> BindingSet
-> Submission
-> Completion
```
`vyre-megakernel` owns artifact identity and pure target compilation. Concrete
driver crates own target formats, device acquisition, materialization, native
modules, and submission mechanics.
## Invariants
1. `ArtifactMaterializer` admits immutable authenticated target bytes for one
device generation.
2. `ArtifactInstance` accepts only bindings carrying its artifact digest.
3. `BindingSet` separates immutable artifact identity from runtime invocation
geometry and resident resource selection.
4. Device loss invalidates native modules and resident handles from that
generation. Recovery rematerializes target bytes without re-lowering.
5. Backend operation support derives from the foundation semantic operation
registry.
6. Direct `Program` dispatch is a lower-level oracle, capability, and driver
testing surface. Production callers use artifacts.
## Boundaries
`vyre-driver` owns:
- `BackendRegistration` and registered compiler/materializer facets;
- `ArtifactMaterializer`, `ArtifactInstance`, `BindingSet`, `Submission`, and
`Completion`;
- backend-neutral device identity, capability, resident-resource, validation,
scheduling, and diagnostic contracts;
- `VyreBackend`, `DispatchConfig`, and direct dispatch for intentional
lower-level consumers.
Concrete driver crates own runtime objects, target code generation, target
formats, device probes, native executable modules, and target-specific
terminology.
The public `vyre` facade does not re-export backend implementation traits,
dispatch configuration, compiled-pipeline handles, or the backend registry.
Import those contracts from `vyre-driver` only when using the lower-level
driver surface intentionally.
## Registered artifact execution
```rust
use vyre_driver::backend::backend_registration;
use vyre_driver::{BindingSet, BoundResource};
let registration = backend_registration(target_id)?;
let compiler = registration.target_compiler()?;
let payload = compiler.compile(&artifact)?;
let materializer = registration.materializer()?;
let instance = materializer.materialize(&artifact, &payload)?;
let mut bindings = BindingSet::new(artifact.digest());
bindings.insert(input_value, BoundResource::Host(input_bytes));
let completion = instance.submit(bindings)?.wait()?;
```
Use `vyre-runtime::ArtifactSession` when runtime compilation, target attachment,
admission, recovery, or persistence orchestration is required.
## Extension guide: adding a new backend
1. Create one concrete driver crate. Shared crates must not depend on it.
2. Implement a pure `TargetCompiler` that consumes compiler-selected artifact
modules and emits immutable target bytes.
3. Implement `ArtifactMaterializer` to authenticate the payload, acquire native
handles for one device generation, and return an `ArtifactInstance`.
4. Register the backend factory, operation support, compiler facet, and
materializer facet in one `BackendRegistration`.
5. Register target operation facets through the foundation semantic operation
registry.
6. Prove compile, materialize, typed submission, readback, device-loss
rematerialization, and reference parity through the conformance engine.
See `src/backend/artifact_lifecycle.rs`, `src/backend/registry/`, and
`vyre-megakernel::target` for the contracts. See [`docs/targets.md`](../docs/targets.md)
for the production lifecycle and extension checklist.
## 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
Define backend-neutral device, target compiler registration, artifact materialization, binding, submission, completion, capability, dispatch, and evidence contracts.
### Boundaries
The `backend-contract` owner maintains this `backend-neutral` crate at `vyre-driver`.
Its allowed internal production dependencies are: `vyre-foundation`, `vyre-macros`, `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/examples/vyre_driver_release_surface.rs`:
```console
CARGO_BUILD_JOBS=1 ./cargo_full run -p vyre-driver --example vyre_driver_release_surface
```
### Features
- Manifest features: `default`, `self-substrate-adapters`
- Default feature members: None
### Errors and unsupported behavior
Backend acquisition, capability, artifact, dispatch, and lifecycle failures retain actionable context. Shared contracts never substitute a concrete backend silently.
### Testing
Use [`docs/testing/vyre-driver.md`](../docs/testing/vyre-driver.md) for exact commands, Cargo targets, hardware
requirements, evidence outputs, expected skips, and failure semantics.
### Release status
`vyre-driver@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.