vyre-runtime

Artifact admission, persistent resident queues, resource residency, and Linux zero-copy IO for Vyre.

What this crate provides

The runtime authenticates compiler envelopes, materializes target payloads, binds artifact ABI resources, submits typed work, and rematerializes the same artifact after device loss.

Quick start

use vyre_driver::backend::BackendRegistration;
use vyre_runtime::resident_work_queue::{self, ResidentWorkQueue};
use vyre_runtime::{PersistentExecutor, ResidentQueueState};

fn run(
    backend: &'static BackendRegistration,
    envelope: &[u8],
) -> Result<(), Box<dyn std::error::Error>> {
    let initial = ResidentQueueState {
        control: ResidentWorkQueue::try_encode_control(false, 1, 0)?,
        ring: ResidentWorkQueue::try_encode_empty_ring(256)?,
        debug_log: ResidentWorkQueue::try_encode_empty_debug_log(
            resident_work_queue::debug::RECORD_CAPACITY,
        )?,
        io_queue: resident_work_queue::io::try_encode_empty_io_queue(
            resident_work_queue::io::IO_SLOT_COUNT,
        )?,
    };
    let executor = PersistentExecutor::from_bytes(backend, envelope, initial.clone())?;
    let completed = executor.submit_and_wait(initial)?;
    assert!(!completed.state.control.is_empty());
    Ok(())
}

Own resource residency

Admit verified immutable bytes once, then allocate independently leased mutable state:

use std::sync::Arc;
use vyre_driver::backend::{ArtifactInstance, ArtifactMaterializer};
use vyre_runtime::resource_residency::{
    ArtifactInstanceBinding, ImmutableResourceUpload, MutableStateSpec,
    ResourceResidency, ResourceSetAdmission, ResourceSetKey,
};

fn admit_resources(
    materializer: Arc<dyn ArtifactMaterializer>,
    instance: Arc<dyn ArtifactInstance>,
    source_digest: [u8; 32],
    immutable_bytes: &[u8],
) -> Result<(), Box<dyn std::error::Error>> {
    let key = ResourceSetKey {
        source_digest,
        artifact_digest: instance.artifact().0,
    };
    let budget = u64::try_from(immutable_bytes.len())?
        .checked_add(4096)
        .ok_or_else(|| std::io::Error::other("resource residency budget overflow"))?;
    let residency = ResourceResidency::new(materializer, budget);
    residency.admit_resource_set(ResourceSetAdmission {
        key,
        immutable_resources: vec![ImmutableResourceUpload {
            name: "immutable.table",
            bytes: immutable_bytes,
            blake3: *blake3::hash(immutable_bytes).as_bytes(),
        }],
        artifacts: vec![ArtifactInstanceBinding::new("execute", instance, 0)],
    })?;
    let state = residency.start_state(
        key,
        &[MutableStateSpec {
            name: "cache",
            byte_len: 4096,
        }],
    )?;
    let reset = residency.reset_state(state)?;
    residency.finish_state(reset)?;
    residency.evict_resource_set(key)?;
    Ok(())
}

Cold admission verifies each immutable-resource digest before allocation. A warm admission reuses only an exact source and artifact key. Allocation or upload failure rolls back all earlier resources. Cancellation, completion, and reset release or zero mutable state, and generation checks reject stale leases. Eviction refuses a resource set while any state lease remains active.

Safetensors parsing, shard indexes, compiler requirement matching, and checkpoint identity live in the downstream vyre-safetensors adapter.

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 compile-to-materialize orchestration, artifact sessions, recovery, persistence, residency, scheduling, caches, telemetry, readback, and IO.

Boundaries

The runtime owner maintains this runtime crate at vyre-runtime. Its allowed internal production dependencies are: vyre-driver, vyre-foundation, vyre-megakernel, vyre-self-substrate. Any other normal or build dependency requires an ownership-registry change.

Minimal real example

Run the checked-in behavior from vyre-runtime/examples/vyre_runtime_release_surface.rs:

CARGO_BUILD_JOBS=1 ./cargo_full run -p vyre-runtime --example vyre_runtime_release_surface

Features

• Manifest features: default, megakernel-batch, remote-cache, self-substrate-adapters, subgroup-ops, uring-cmd-nvme
• Default feature members: None

Errors and unsupported behavior

Invalid plans, stale artifacts, unavailable selected backends, IO failures, and illegal state transitions are operator-visible errors.

Testing

Use docs/testing/vyre-runtime.md for exact commands, Cargo targets, hardware requirements, evidence outputs, expected skips, and failure semantics.

Release status

This crate is an active experimental runtime surface in the 0.7.2 workspace. Its public contracts follow the Vyre release train.

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.