//! Package 4 of CUBELinux-2: cubevm / cubecode — code/data mapping over the
//! CZYX cube (PDF "cubevm or cubecode").
//!
//! The PDF's intent: "use the cube as a substrate for storing and
//! introspecting code and AI artifacts. Treat each function, module, or model
//! component as a record ... Use association flags and CZYX links for: call
//! graphs, dependency edges, variant implementations, version history."
//!
//! Resolution of the interesting tension: the PDF also says "body: bytecode,
//! machine code, or serialized model weights" and imagines "a scripting
//! language or DSL whose runtime walks cube links to load and dispatch
//! functions." The second clause is the load-bearing one for the design — it
//! is about *addressable, introspectable code-as-data*. We therefore build a
//! **safe, deterministic, cube-addressed bytecode VM** rather than a
//! machine-code JIT:
//!
//!   * Each function/leaf is a record whose body is bytecode (`opcode.rs`).
//!   * The call graph *is* the cube's association graph: `CALL_LINK n`
//!     executes `linked_records[n]` (`vm.rs`). No foreign machine code is ever
//!     executed; the body is always decoded through the codec first, so the
//!     cube never runs something that didn't survive `decode`.
//!   * AI artifacts (layers, checkpoints) are first-class `Kind`s so they
//!     address into the same cube the code lives in (`cell.rs`).
//!
//! This runs on the metal here, needs no elevated privileges, and is fully
//! deterministic — a prerequisite for the PDF's "navigate and reconstruct
//! experiments" use case. A real model registry would point `Kind::Layer`
//! records at weight blobs (stored as record bodies) and link them into a
//! graph the VM can traverse.
//!
//! Scope note: `cubetrace`/`cubedbt`/`cubeai` (execution capture + replay +
//! ML over traces) are the *next* layer and are excluded on this hardware;
//! they would consume `cubecode`'s records as their input.

#![forbid(unsafe_code)]
#![warn(missing_docs)]

pub mod cb;
pub mod cell;
pub mod ballindex;
pub mod opcode;
pub mod trace;
pub mod vm;

pub use cb::{Behavior, C_OS_EFFECT, C_OS_KERNEL, HEADER_FLAG_BEHAVIOR};

pub use cell::{CodeCell, Kind};
pub use opcode::{decode, encode, CodeError, Op};
pub use ballindex::{ball_stats, build, Vec3, VP_SPACE};
pub use trace::{capture_golden, lineage, replay_trace, store_trace, verify_golden, LineageHop};
pub use vm::{replay, Fault, RunResult, Vm, SYS_DEGREE, SYS_LINKED_EXISTS, SYS_NOP, SYS_TRACE};