Struct Program 

pub struct Program {
    pub entry_op_id: Option<String>,
    pub buffers: Arc<[BufferDecl]>,
    pub workgroup_size: [u32; 3],
    pub entry: Arc<Vec<Node>>,
    pub non_composable_with_self: bool,
    /* private fields */
}

A complete vyre program.

Contains everything needed to execute a GPU compute dispatch: buffer declarations, workgroup configuration, and the entry point body.

Example

A program that XORs two input buffers element-wise:

use vyre::ir::{Program, BufferDecl, BufferAccess, DataType, Node, Expr, BinOp};

let program = Program::wrapped(
    vec![
        BufferDecl::storage("a", 0, BufferAccess::ReadOnly, DataType::U32),
        BufferDecl::storage("b", 1, BufferAccess::ReadOnly, DataType::U32),
        BufferDecl::storage("out", 2, BufferAccess::ReadWrite, DataType::U32),
    ],
    [64, 1, 1],
    vec![
        Node::let_bind("idx", Expr::gid_x()),
        Node::if_then(
            Expr::lt(Expr::var("idx"), Expr::buf_len("out")),
            vec![
                Node::store("out", Expr::var("idx"),
                    Expr::bitxor(
                        Expr::load("a", Expr::var("idx")),
                        Expr::load("b", Expr::var("idx")),
                    ),
                ),
            ],
        ),
    ],
);
assert_eq!(program.buffers().len(), 3);

Fields

entry_op_id: Option<String>

Stable ID of the certified operation this program implements.

Runtime lowering must reject programs without an ID because anonymous IR cannot be tied back to a conform registry entry.

buffers: Arc<[BufferDecl]>

Buffer declarations. Each declares a named, typed, bound memory region.

workgroup_size: [u32; 3]

Workgroup size: [x, y, z]. Controls @workgroup_size in target-text.

entry: Arc<Vec<Node>>

Entry point body. Executes once per invocation.

non_composable_with_self: bool

When true, this program must not be fused with another copy of itself in the same megakernel. Parser programs that use workgroup-local scratch buffers set this to avoid state corruption when two invocations share the same workgroup memory.

Implementations

impl Program

pub const ROOT_REGION_GENERATOR: &'static str = "vyre.program.root"

Synthetic generator id used when callers submit a raw top-level body instead of an explicit Node::Region.

pub fn wrapped( buffers: Vec<BufferDecl>, workgroup_size: [u32; 3], entry: Vec<Node>, ) -> Self

Create a complete program from buffer declarations, workgroup size, and entry-point nodes, auto-wrapping the top-level body in a root Region when necessary.

This is the default construction path for runnable Programs.

Examples

use vyre::ir::{BufferAccess, BufferDecl, DataType, Node, Program};

let program = Program::wrapped(
    vec![BufferDecl::storage(
        "output",
        0,
        BufferAccess::ReadWrite,
        DataType::U32,
    )],
    [64, 1, 1],
    Vec::new(),
);

assert_eq!(program.workgroup_size(), [64, 1, 1]);
assert_eq!(program.buffers().len(), 1);
assert!(matches!(program.entry(), [Node::Region { .. }]));

pub fn new( buffers: Vec<BufferDecl>, workgroup_size: [u32; 3], entry: Vec<Node>, ) -> Self

👎Deprecated:

Program::new preserves raw top-level entry nodes. Use Program::wrapped for runnable programs; reserve Program::new for wire decode and negative tests.

Create a complete program from buffer declarations, workgroup size, and entry-point nodes.

Examples

use vyre::ir::{BufferAccess, BufferDecl, DataType, Program};

let program = Program::wrapped(
    vec![BufferDecl::storage(
        "output",
        0,
        BufferAccess::ReadWrite,
        DataType::U32,
    )],
    [64, 1, 1],
    Vec::new(),
);

assert_eq!(program.workgroup_size(), [64, 1, 1]);
assert_eq!(program.buffers().len(), 1);
assert!(matches!(program.entry(), [Node::Region { .. }]));

pub fn with_rewritten_entry(&self, entry: Vec<Node>) -> Self

Clone this program with a replacement entry body while preserving the existing buffer table, workgroup size, and optional certified op id.

pub fn with_rewritten_buffers(&self, buffers: Vec<BufferDecl>) -> Self

Clone this program with replacement buffer declarations while preserving the entry body, workgroup size, and metadata flags.

pub fn with_rewritten_workgroup_size_and_entry( &self, workgroup_size: [u32; 3], entry: Vec<Node>, ) -> Self

Clone this program with replacement dispatch dimensions and entry body while preserving the existing buffer table, indexes, and metadata flags.

pub fn into_entry_vec(self) -> Vec<Node>

Consume the program and return its entry nodes, reusing the backing vector when this program owns the entry body uniquely.

pub fn with_arena( arena: &ExprArena, buffers: Vec<BufferDecl>, workgroup_size: [u32; 3], ) -> ArenaProgram<'_>

Create an arena-backed program scaffold.

This constructor is the opt-in migration path for builders that want ExprRef handles instead of boxed expression trees. Program::new remains the boxed-tree constructor.

pub fn empty() -> Self

Create a minimal program with no buffers and an empty body.

Examples

use vyre::ir::Program;

let program = Program::empty();

assert!(program.buffers().is_empty());
assert_eq!(program.workgroup_size(), [1, 1, 1]);
assert!(program.is_explicit_noop());

pub fn with_entry_op_id(self, op_id: impl Into<String>) -> Self

Attach the stable operation ID whose conform registry entry certifies this program for runtime lowering.

pub fn entry_op_id(&self) -> Option<&str>

Stable operation ID required by the conform gate.

impl Program

pub fn canonicalized(&self) -> Self

Return the canonical IR shape used for security-sensitive cache keys.

Canonicalization preserves executable semantics while removing authoring-order noise: buffer declarations are sorted by their stable wire key, commutative expression operands are normalized, and Block wrappers that do not own local bindings are flattened.

pub fn canonical_wire_bytes(&self) -> Result<Vec<u8>, Error>

Serialize the canonical IR shape into stable VIR0 wire bytes.

Errors

Returns the same wire-format validation errors as Self::to_wire, but after canonical normalization has been applied.

pub fn canonical_wire_hash(&self) -> Result<Hash, Error>

BLAKE3 digest of Self::canonical_wire_bytes.

Errors

Returns a wire-format validation error if the canonical program cannot be represented by the current VIR0 encoder.

impl Program

pub fn reconcile_runnable_top_level(self) -> Self

Re-apply the same top-level Node::Region contract as Program::wrapped.

The region_inline_engine pass flattens small Category-A regions so CSE/DCE can see a single function-shaped body, which can leave a statement-shaped entry list. The standard optimizer run ends with this helper so the program remains in a runnable, validator/reference-interpreter–compatible form while still benefiting from the inline pass.

pub fn buffer(&self, name: &str) -> Option<&BufferDecl>

Look up a buffer declaration by name.

pub fn buffers(&self) -> &[BufferDecl]

Declared buffers.

pub fn structural_eq(&self, other: &Self) -> bool

Compare two programs by observable IR structure.

This walk intentionally ignores buffer declaration order and never consults arena-local allocation identity. Two programs are structurally equal when they declare the same buffers, workgroup size, optional entry op id, and entry body semantics.

pub fn workgroup_size(&self) -> [u32; 3]

Workgroup dimensions.

pub fn parallel_region_size(&self) -> [u32; 3]

Substrate-neutral alias for workgroup_size.

Naming: “parallel region” avoids picking a single target substrate’s word for one dispatch invocation grouping.

pub fn is_non_composable_with_self(&self) -> bool

Return true when this program must not be fused with another copy of itself in the same megakernel.

pub fn with_non_composable_with_self(self, flag: bool) -> Self

Mark this program as non-composable with itself.

pub fn set_workgroup_size(&mut self, workgroup_size: [u32; 3])

Set the workgroup dimensions in place. Used by harnesses that need to clone-and-rewrite a program’s workgroup size for fallback dispatch — the alternative was to reconstruct the entire Program, which is unnecessarily expensive when only one field changes.

pub fn set_parallel_region_size(&mut self, parallel_region_size: [u32; 3])

Substrate-neutral alias for set_workgroup_size.

pub fn entry(&self) -> &[Node]

Entry-point nodes.

pub fn entry_arc(&self) -> &Arc<Vec<Node>>

Shared entry-point body Arc for identity checks.

pub fn is_explicit_noop(&self) -> bool

Return true when this Program is the canonical no-op shape produced by Program::empty: no buffers and a single empty root Region.

pub fn is_top_level_region_wrapped(&self) -> bool

Return true when the program satisfies the top-level region-chain invariant: at least one top-level node, and every top-level node is a Node::Region.

pub fn top_level_region_violation(&self) -> Option<String>

Actionable error text describing why the top-level region invariant failed, or None when the entry is valid.

pub fn entry_mut(&mut self) -> &mut Vec<Node>

Mutable entry-point nodes for transformation passes.

pub fn fingerprint(&self) -> [u8; 32]

Stable BLAKE3 fingerprint of the canonical wire-format bytes.

pub fn vsa_fingerprint(&self) -> Vec<u32>

VSA-style hypervector fingerprint of the canonical wire-format bytes. Each u32 lane is one segment of the program’s blake3 hash; together they form an 8-lane hypervector suitable for approximate similarity search via hamming distance.

Use as the canonical cache key for approximate-match caches (e.g. validation cache, AOT artifact dedup); use Self::fingerprint for exact-match lookups.

Wires the substrate’s #29 hypervector primitive into Program itself — every Program now carries its own VSA fingerprint without callers having to reach into the substrate explicitly.

pub fn output_buffer_indices(&self) -> &[u32]

Indices of read-write buffers in buffers() order.

pub fn has_indirect_dispatch(&self) -> bool

True when the entry walk discovers any indirect dispatch node.

pub fn has_buffer(&self, name: &str) -> bool

Check whether a named buffer exists.

pub fn buffer_count(&self) -> usize

Number of declared buffers.

pub fn mark_structurally_validated(&self)

Mark this program as successfully validated structurally.

pub fn is_structurally_validated(&self) -> bool

Return true once structural validation has succeeded for this program shape.

pub fn mark_validated_on(&self, backend_id: &str)

Mark this program as successfully validated for a specific backend.

pub fn is_validated_on(&self, backend_id: &str) -> bool

Return true if this program has been validated for the given backend.

pub fn is_validated(&self) -> bool

👎Deprecated:

use is_structurally_validated or is_validated_on

Deprecated: use is_structurally_validated or is_validated_on.

pub fn mark_validated(&self)

👎Deprecated:

use mark_structurally_validated or mark_validated_on

Deprecated: use mark_structurally_validated or mark_validated_on.

pub fn validate(&self) -> Result<()>

Validate the program and cache the successful result on the program.

Errors

Returns crate::Error::WireFormatValidation with every validation message joined when the structural validator rejects the program.

pub fn estimate_peak_vram_bytes(&self) -> u64

Estimate the peak VRAM byte size of this Program.

Innovation I.11: Static VRAM Pressure Analysis. Returns the total bytes required by all storage and uniform buffers declared in the Program. Optimizer passes use this to automatically partition workloads if they would exceed a backend-specific safety margin.

pub fn peak_intensity(&self) -> OpIntensity

Return the peak computational intensity found in any instruction.

impl Program

pub fn stats(&self) -> &ProgramStats

Return cached statistics for this program, computing them on first call.

impl Program

pub fn to_text(&self) -> Result<String, TextParseError>

Serialize to the canonical vyre IR text format.

Errors

Returns TextParseError::WireEncodeFailed when the inner binary wire encoder fails. This cannot happen for a program produced by a successful Program::new because every field of Program is a valid wire input by construction; the error path exists only for programs synthesized through unsafe means or a wire-format breaking change.

pub fn from_text(input: &str) -> Result<Self, TextParseError>

Parse the canonical vyre IR text format.

Errors

Returns a TextParseError describing the first parse failure. Parsing is total — no panic path.

impl Program

pub fn to_wire(&self) -> Result<Vec<u8>, Error>

Serialize this IR program into the stable VIR0 IR wire format.

Errors

Returns crate::error::Error::WireFormatValidation when a count cannot be represented in the versioned wire format or when a public enum variant has no registered stable wire tag. The message field carries the actionable diagnostic prose including a Fix: hint.

pub fn to_wire_into(&self, dst: &mut Vec<u8>) -> Result<(), Error>

Serialize this IR program into the stable VIR0 IR wire format, appending to an existing buffer.

Errors

Returns crate::error::Error::WireFormatValidation when a count cannot be represented in the versioned wire format or when a public enum variant has no registered stable wire tag. The message field carries the actionable diagnostic prose including a Fix: hint.

pub fn to_bytes(&self) -> Vec<u8>

Serialize this IR program into bytes.

This compatibility wrapper preserves the pre-to_wire API name.

On an encoding error, an empty vector is returned after logging the failure. Use Program::to_wire when the caller needs to handle the error explicitly.

pub fn from_wire(bytes: &[u8]) -> Result<Self, Error>

Deserialize an IR program from the stable VYRE IR wire format.

Errors

Returns crate::error::Error::VersionMismatch when the payload advertises a schema version this runtime does not understand. Returns crate::error::Error::WireFormatValidation for any other decode failure — truncated bytes, unknown enum tag, integrity digest mismatch, or malformed structural section.

pub fn from_bytes(bytes: &[u8]) -> Result<Self, Error>

Deserialize an IR program from bytes.

This compatibility wrapper preserves the pre-from_wire API name.

Errors

Returns the same actionable decode errors as Program::from_wire.

pub fn content_hash(&self) -> [u8; 32]

Stable content hash of this Program, used as a cache identity.

Computed as BLAKE3 of the canonical wire-format encoding. This is the exact-match identity for persistent-cache consumers that need a deterministic key per Program without re-implementing canonicalization. On canonical wire-encoding failure, the value is a domain-separated error digest rather than an all-zero sentinel, so malformed programs do not collapse into the same cache identity.

Trait Implementations

impl Clone for Program

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Program

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Program

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for Program

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Program