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:

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

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 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:

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 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.