vyre-runtime 0.7.2

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

| Module | Purpose |
|--------|---------|
| `artifact_admission` | Envelope authentication, exact target selection, materialization, and retained sessions |
| `persistent_executor` | Resident queue submission over retained artifact bindings |
| `resident_work_queue` | Ring protocol, host mirrors, queue sizing, IO, and telemetry |
| `pipeline_cache` | Content-addressed storage keyed by neutral artifact digest |
| `resource_residency` | Immutable resources, artifact instances, admission budgets, and generation-checked mutable state |
| `uring` | Linux registered-buffer and direct NVMe ingest |

## Quick start

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

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

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

```console
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`](../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.

<!-- END GENERATED CRATE CONTRACT -->