vyre_foundation/lib.rs
1//! vyre-foundation - substrate-neutral compiler foundation.
2//!
3//! Defines the vyre IR (`Expr`, `Node`, `Program`), the type system, the
4//! memory model, the wire format, visitor traits, and extension resolvers.
5//! Every other vyre crate depends on this one; this crate depends only on
6//! `vyre-spec`, `vyre-macros`, and lightweight third-party data crates.
7//! It never knows about concrete driver APIs, a dialect, or a backend.
8
9// Foundation owns the IR arena (`ir_inner::model::arena`), which uses two
10// `unsafe` blocks to extend bumpalo lifetimes inside a single arena owner.
11// Every other unsafe usage is forbidden by `check_lib_rs_headers.sh`.
12#![allow(unsafe_code)]
13#![allow(
14 clippy::duplicate_mod,
15 clippy::too_many_arguments,
16 clippy::double_must_use,
17 clippy::module_inception,
18 clippy::should_implement_trait,
19 clippy::type_complexity
20)]
21
22extern crate self as vyre;
23
24/// Structured optimizer diagnostics surfaced to IDEs and CI annotators.
25///
26/// Lightweight diagnostic type used by foundation optimizer passes.
27///
28/// Drivers embed these into their richer diagnostic surface; foundation
29/// only needs a human-readable message plus an optional pass/op location
30/// so that pass-scheduling errors can be rendered without pulling in
31/// driver-tier dependencies.
32pub mod diagnostics {
33
34 /// Error-level diagnostic with an optional location hint.
35 #[derive(Debug, Clone)]
36 pub struct Diagnostic {
37 /// Human-readable diagnostic message.
38 pub message: String,
39 /// Optional op/pass location the diagnostic refers to.
40 pub location: Option<OpLocation>,
41 }
42
43 impl Diagnostic {
44 /// Build an error-level diagnostic with no location.
45 #[must_use]
46 pub fn error(msg: impl Into<String>) -> Self {
47 Self {
48 message: msg.into(),
49 location: None,
50 }
51 }
52
53 /// Attach an op/pass location to this diagnostic.
54 #[must_use]
55 pub fn with_location(mut self, loc: OpLocation) -> Self {
56 self.location = Some(loc);
57 self
58 }
59 }
60
61 /// Location handle pointing at a specific pass or op id.
62 #[derive(Debug, Clone)]
63 pub struct OpLocation {
64 /// Stable pass or op identifier.
65 pub op_id: String,
66 }
67
68 impl OpLocation {
69 /// Construct a location hint from an op id.
70 #[must_use]
71 pub fn op(op_id: impl Into<String>) -> Self {
72 Self {
73 op_id: op_id.into(),
74 }
75 }
76 }
77}
78
79pub mod ir {
80 //! The vyre intermediate representation.
81 /// Backend-neutral literal evaluation for optimizer passes and lowerings.
82 pub mod eval {
83 // Audit cleanup A16 (2026-04-30): replaced `pub use crate::ir_eval::*`
84 // wildcard with explicit named re-exports per
85 // organization_contracts::foundation_wildcard_pub_reexports_are_baselined.
86 pub use crate::runtime::ir_eval::{
87 fold_binary_literal, fold_cast_literal, fold_fma_literal, fold_literal_tree,
88 fold_unary_literal,
89 };
90 }
91 pub use crate::ir_inner::model;
92 pub use crate::ir_inner::model::arena::{ArenaProgram, ExprArena, ExprRef};
93 pub use crate::ir_inner::model::expr::{Expr, ExprNode, Ident};
94 pub use crate::ir_inner::model::node::{Node, NodeExtension};
95 pub use crate::ir_inner::model::node_kind::{
96 EvalError, InterpCtx, NodeId, NodeStorage, OpId, RegionId, Value, VarId,
97 };
98 pub use crate::ir_inner::model::program::{
99 BufferDecl, CacheLocality, LinearType, MemoryHints, MemoryKind, Program, ShapePredicate,
100 NORMALIZED_PROGRAM_CACHE_DIGEST_VERSION,
101 };
102 /// Per-Node-variant bit-position constants for `ProgramStats::node_kinds_present`.
103 /// Compose with `ProgramStats::has_any_node_kind` for O(1) `analyze_impl` gates.
104 pub mod stats {
105 pub use crate::ir_inner::model::program::{
106 NODE_KIND_ALL_GATHER, NODE_KIND_ALL_REDUCE, NODE_KIND_ASSIGN, NODE_KIND_ASYNC_LOAD,
107 NODE_KIND_ASYNC_STORE, NODE_KIND_ASYNC_WAIT, NODE_KIND_BARRIER, NODE_KIND_BLOCK,
108 NODE_KIND_BROADCAST, NODE_KIND_EXPRESSION_BEARING_MASK, NODE_KIND_IF,
109 NODE_KIND_INDIRECT_DISPATCH, NODE_KIND_LET, NODE_KIND_LOOP, NODE_KIND_OPAQUE,
110 NODE_KIND_REDUCE_SCATTER, NODE_KIND_REGION, NODE_KIND_RESUME, NODE_KIND_RETURN,
111 NODE_KIND_STORE, NODE_KIND_TRAP,
112 };
113 }
114 pub use crate::ir_inner::model::program::ProgramStats;
115 pub use crate::ir_inner::model::types::{
116 AtomicOp, BinOp, BufferAccess, CollectiveOp, CommGroup, Convention, DataType, OpSignature,
117 SubgroupReduceOp, UnOp,
118 };
119 pub use crate::memory_model;
120 pub use crate::memory_model::MemoryOrdering;
121 pub use crate::optimizer::passes::fusion_cse::{cse, dce};
122 pub use crate::optimizer::pre_lowering::optimize;
123 pub use crate::serial::text;
124 pub use crate::transform::inline::{
125 inline_calls, inline_calls_with_mode, inline_calls_with_resolver, inline_composite_calls,
126 OpResolver, UnresolvedCalls,
127 };
128 pub use crate::validate::depth::{
129 LimitState, DEFAULT_MAX_CALL_DEPTH, DEFAULT_MAX_NESTING_DEPTH, DEFAULT_MAX_NODE_COUNT,
130 };
131 pub use crate::validate::validate::validate;
132 pub use crate::validate::validation_error::ValidationError;
133}
134
135// Audit cleanup A12 (2026-04-30): grouped 13 loose `pub mod` decls into
136// 4 logical subdirs. Back-compat `pub use` aliases below preserve the
137// historical `vyre_foundation::<file>::*` paths so external callers
138// don't break during the transition.
139
140/// Runtime / evaluation surface (cpu_op, cpu_references, ir_eval,
141/// match_result, memory_model, perf, program_caps).
142pub mod runtime;
143
144/// Dispatch surface (dialect_lookup, extension, extern_registry).
145pub mod dispatch;
146
147/// Algebraic-laws surface (algebraic_law_registry, composition).
148pub mod algebra;
149
150/// Static-analysis surface (graph_view).
151pub mod analysis;
152
153/// Substrate-neutral allocation reservation arithmetic shared by hot paths.
154pub mod allocation;
155
156// ---- Back-compat re-exports (old `vyre_foundation::<file>` paths) -----
157pub use algebra::algebraic_law_registry;
158pub use algebra::algebraic_law_registry::{
159 has_law, is_associative, is_commutative, laws_for_op, AlgebraicLaw, AlgebraicLawRegistration,
160};
161pub use analysis::graph_view;
162pub use dispatch::dialect_lookup;
163pub use dispatch::extern_registry;
164pub use runtime::memory_model;
165pub use runtime::memory_model::MemoryOrdering;
166
167/// Endian-fixed encode/decode helpers for `Expr::Opaque` / `Node::Opaque` payloads.
168pub mod opaque_payload;
169
170/// Packed AST (VAST) wire layout + host-side tree walks (`docs/parsing-and-frontends.md`).
171pub mod vast;
172
173pub use analysis::graph_view::{
174 from_graph, to_graph, DataEdge, DataflowKind, EdgeKind, GraphNode, GraphValidateError,
175 NodeGraph,
176};
177pub use dispatch::dialect_lookup::{
178 dialect_lookup, install_dialect_lookup, intern_string, AttrSchema, AttrType, Category,
179 DialectLookup, InternedOpId, LoweringCtx, LoweringTable, NativeModule, NativeModuleBuilder,
180 OpDef, PrimaryBinaryBuilder, PrimaryTextBuilder, ReferenceKind, SecondaryTextBuilder,
181 Signature, TextModule, TypedParam,
182};
183pub use dispatch::extern_registry::{
184 all_ops as all_extern_ops, dialects as extern_dialects,
185 ops_in_dialect as extern_ops_in_dialect, verify as verify_extern_registry, ExternDialect,
186 ExternOp, ExternVerifyError,
187};
188
189// V7-API-017: `ir_inner` is intentionally private - the public surface
190// re-exports through `pub mod ir` above. The internal name is pinned by
191// the `vyre_macros::vyre_ast_registry!` proc-macro, which emits literal
192// `crate::ir_inner::model::*` paths for the generated decoder cascades.
193// Renaming `ir_inner` to `ir` requires a coordinated proc-macro rewrite
194// + every dialect that uses `vyre_ast_registry!` recompiling against the
195// new path. Tracked for the next semver-major.
196mod ir_inner {
197 pub mod model;
198}
199// composition / cpu_op / cpu_references / extension / ir_eval / match_result
200// / perf / program_caps relocated in audit cleanup A12 (2026-04-30) - they
201// now live under runtime/, dispatch/, algebra/, analysis/. Back-compat
202// re-exports for external `vyre_foundation::<file>::*` paths land further
203// up via `pub use runtime::memory_model;` etc.
204pub use algebra::composition;
205pub use dispatch::extension;
206pub use runtime::cpu_op;
207pub use runtime::cpu_references;
208pub(crate) use runtime::ir_eval;
209pub use runtime::match_result;
210pub use runtime::match_result::ByteRange;
211pub use runtime::perf;
212
213/// Host-side IR engine helpers (prefix arrays, token filters).
214pub mod engine;
215/// Deterministic field framing for content-addressed hashes.
216pub mod hashing;
217/// Legacy lower helpers (transition surface pending driver-tier extraction).
218pub mod lower;
219/// Pass-orchestration optimizer framework.
220pub mod optimizer;
221/// Binary wire format + canonical text serialization.
222pub mod serial;
223/// IR → IR passes: inline, cse, dce, parallelism, compiler primitives.
224pub mod transform;
225/// Structural + semantic validation of vyre `Program`s.
226pub mod validate;
227/// Visitor traits + blanket adapters routing Expr/Node variants.
228pub mod visit;
229
230/// Self-substrate primitives that the optimizer + scheduler call into.
231/// Moved in-tree from vyre-libs to break a cross-workspace dep cycle.
232pub mod pass_substrate;
233
234/// Program → substrate-neutral execution planning for fusion, readback,
235/// provenance, autotune, and accuracy guard decisions.
236pub mod execution_plan;
237/// Program → required-capability analysis (used by backends and conform
238/// harnesses to skip ops whose lowering needs a capability the backend
239/// does not advertise, without maintaining hardcoded exempt lists).
240/// Relocated to `runtime/` in audit cleanup A12 (2026-04-30).
241pub use runtime::program_caps;
242
243/// Unified error type for validation, wire format, lowering, and execution.
244pub mod error;
245pub use error::{Error, Result};
246
247/// Soundness lattice for dataflow primitives. Canonical home - dataflow
248/// engines and composition crates consume from here per the LEGO discipline
249/// (consumers always
250/// calls vyre, vyre never calls anything else).
251pub mod soundness;
252
253/// Test utilities shared across optimizer and transform test suites.
254/// `pub(crate)` because they are an internal contract - no consumer
255/// outside vyre-foundation should depend on these helpers.
256#[cfg(test)]
257pub(crate) mod test_util;