vyre_aot/lib.rs
1#![forbid(unsafe_code)]
2//! vyre-aot - Ahead-of-time compilation for vyre Programs.
3//!
4//! Vyre is a JIT-friendly substrate: at runtime, a `Program` is lowered
5//! through `vyre-driver` to a backend-specific module loaded by the GPU
6//! driver. That works when the consumer can ship the entire vyre runtime
7//! alongside the artifact.
8//!
9//! For embedded targets and code-budget-constrained submissions
10//! (parameter-golf is the motivating case: `code_bytes + compressed_model_bytes
11//! ≤ 16,000,000`) we need the compiler to disappear at runtime. Only the
12//! pre-emitted target bytes plus a tiny backend loader should ship.
13//!
14//! ## Public API
15//!
16//! Three functions:
17//!
18//! - [`mod@compile`]: lower a `Program` to a [`CompiledArtifact`] containing
19//! target-specific kernel bytes, the buffer-binding
20//! table, and the dispatch config.
21//! - [`emit_launcher_rust`]: generate a self-contained Rust launcher crate
22//! source tree that loads the artifact via raw driver-API FFI and
23//! dispatches it.
24//! - [`mod@bundle`]: package an artifact + weight bytes + launcher source into
25//! the final on-disk submission tree.
26//!
27//! Concrete driver crates register AOT emitters through `vyre-driver`.
28
29#![deny(missing_docs)]
30
31pub mod artifact;
32pub mod bundle;
33/// Runtime-cache compatibility for AOT-emitted artifacts (audit P0 #26).
34pub mod cache;
35pub mod compile;
36pub mod launcher;
37pub mod manifest;
38
39pub use artifact::{
40 BufferAccessKind, BufferEntry, BufferMemoryKind, CompiledArtifact, DispatchGeometry, Target,
41};
42pub use bundle::{bundle, Bundle, BundleError};
43pub use compile::{compile, CompileError};
44pub use launcher::{emit_launcher_rust, LauncherError, LauncherOpts};
45pub use manifest::Manifest;
46
47/// Crate version surfaced into emitted artifacts and manifests.
48pub const VERSION: &str = env!("CARGO_PKG_VERSION");
49
50/// Snapshot the driver-tier observability surface from inside vyre-aot.
51/// Exposes substrate counters + decision histograms so callers
52/// emitting AOT bundles can include them in their build provenance.
53#[must_use]
54pub fn observability_snapshot() -> vyre_driver::observability::DriverObservability {
55 vyre_driver::observability::DriverObservability::snapshot()
56}
57
58/// VSA-fingerprint a Program with the same key family AOT artifacts
59/// persist on `CompiledArtifact::vsa_fingerprint`. Producers use this
60/// to pre-check whether the artifact already exists before paying
61/// the compile cost.
62#[must_use]
63pub fn program_fingerprint(program: &vyre_foundation::ir::Program) -> Vec<u32> {
64 vyre_driver::program_vsa_fingerprint(program)
65}