ROWM API Reference — Crate-by-Crate Guide
Version: 1.0.0
Status: Normative
Authors: Ahmad Ali Parr, Jessica SNAPKITTYWEST
Overview
ROWM consists of 8 core Rust crates, each with distinct responsibilities. This document provides quick reference for each crate's public API.
For detailed implementation, see source files in crates/*/src/.
1. subleq-vm — Virtual Machine Core
Location: crates/subleq-vm/
Purpose: Execute SUBLEQ bytecode with mutation tracking and checkpointing
Public Types
pub struct Memory {
cells: Vec<i64>, // Von Neumann unified address space
}
pub struct VirtualMachine {
memory: Memory,
instruction_pointer: usize,
mutations: Vec<MutationEvent>,
checkpoints: VecDeque<Checkpoint>,
}
pub struct MutationEvent {
pub address: usize,
pub old_value: i64,
pub new_value: i64,
pub timestamp: u64,
}
pub struct Checkpoint {
pub id: Uuid,
pub memory_snapshot: Vec<i64>,
pub instruction_pointer: usize,
pub timestamp: u64,
pub hash: String, // Blake3
}
Public Methods
impl VirtualMachine {
pub fn new(program: Vec<i64>) -> Self;
pub fn execute(&mut self) -> Result<ExecutionResult>;
pub fn step(&mut self) -> Result<Option<MutationEvent>>;
pub fn create_checkpoint(&mut self) -> Uuid;
pub fn rollback(&mut self, checkpoint_id: Uuid) -> Result<()>;
pub fn get_mutations(&self) -> &[MutationEvent];
pub fn memory_at(&self, address: usize) -> i64;
pub fn set_memory(&mut self, address: usize, value: i64);
pub fn get_telemetry(&self) -> TelemetrySnapshot;
}
pub struct ExecutionResult {
pub status: ExecutionStatus, // Normal | Timeout | ViolationHalt
pub final_memory: Vec<i64>,
pub mutation_count: usize,
pub checkpoint_count: usize,
pub total_cycles: u64,
}
pub enum ExecutionStatus {
Normal,
Timeout,
ViolationHalt,
InvariantViolation(String),
}
2. subleq-ir — Intermediate Representation
Location: crates/subleq-ir/
Purpose: Parse source code to AST, compile to bytecode, lower to SUBLEQ
Public Types
pub enum Expr {
Const(i64),
Var(String),
BinOp(BinOp, Box<Expr>, Box<Expr>),
UnOp(UnOp, Box<Expr>),
If(Box<Expr>, Box<Expr>, Box<Expr>),
Call(String, Vec<Expr>),
}
pub enum Stmt {
Let(String, Expr),
Assign(String, Expr),
If(Expr, Vec<Stmt>, Vec<Stmt>),
While(Expr, Vec<Stmt>),
Return(Expr),
FunctionDef(String, Vec<String>, Vec<Stmt>),
}
pub struct Program {
pub statements: Vec<Stmt>,
pub functions: HashMap<String, Function>,
}
pub enum Bytecode {
LoadConst(i64),
LoadVar(String),
Store(String),
BinOp(BinOp),
Jump(usize),
JumpIfZero(usize),
Call(String),
Return,
}
pub struct Type {
pub kind: TypeKind, // Int64 | Array | Function | Unknown
pub nullable: bool,
}
Public Methods
impl Program {
pub fn from_ast(ast: Vec<Stmt>) -> Result<Self>;
pub fn to_bytecode(&self) -> Result<Vec<Bytecode>>;
pub fn to_subleq(&self) -> Result<Vec<i64>>;
pub fn validate(&self) -> Result<Vec<ValidationError>>;
}
pub struct BytecodeCompiler;
impl BytecodeCompiler {
pub fn compile(ast: &Program) -> Result<Vec<Bytecode>>;
pub fn allocate_registers(bytecode: &[Bytecode]) -> RegisterMap;
}
pub struct SubleqCodegen;
impl SubleqCodegen {
pub fn lower(bytecode: &[Bytecode], register_map: &RegisterMap) -> Vec<i64>;
}
3. polyglot-frontend — Multi-Language Parsing
Location: crates/polyglot-frontend/
Purpose: Parse 30+ languages, normalize to unified AST
Public Types
pub enum Language {
// Tier 1 (Full)
Rust, Python, JavaScript, Subleq,
// Tier 2 (Solid)
Haskell, Ada, Agda, Lean,
// Tier 3 (Supported)
Prolog, Lisp, Scheme, Bqn,
// Tier 4 (Partial)
C, Go, Zig, Apl, Forth,
// Tier 5 (Experimental)
Factor, Brainfuck, J, Holyc, Emojicode,
}
pub struct LanguageRegistry {
parsers: HashMap<Language, Box<dyn Parser>>,
}
pub trait Parser: Send + Sync {
fn parse(&self, source: &str) -> Result<Ast>;
fn language(&self) -> Language;
}
pub struct Ast {
pub root: AstNode,
pub source_hash: String, // Blake3(source)
}
pub enum AstNode {
Program(Vec<AstNode>),
Function(FunctionDef),
Statement(Statement),
Expression(Expression),
}
Public Methods
impl LanguageRegistry {
pub fn new() -> Self;
pub fn register(&mut self, language: Language, parser: Box<dyn Parser>);
pub fn parse(&self, language: Language, source: &str) -> Result<Ast>;
pub fn detect_language(&self, source: &str) -> Option<Language>;
pub fn supported_languages(&self) -> Vec<Language>;
}
pub struct PytonParser;
impl Parser for PythonParser {
fn parse(&self, source: &str) -> Result<Ast>;
fn language(&self) -> Language { Language::Python }
}
pub struct RustParser;
impl Parser for RustParser {
fn parse(&self, source: &str) -> Result<Ast>;
fn language(&self) -> Language { Language::Rust }
}
4. invariant-extractor — Symbolic Execution & Verification
Location: crates/invariant-extractor/
Purpose: Extract loop invariants, generate proof obligations
Public Types
pub enum SymbolicValue {
Const(i64),
Mem(usize), // memory address
Reg(usize), // register index
BinOp(BinOp, Box<SymbolicValue>, Box<SymbolicValue>),
UnOp(UnOp, Box<SymbolicValue>),
}
pub enum Predicate {
True,
False,
Eq(SymbolicValue, SymbolicValue),
Le(SymbolicValue, SymbolicValue),
And(Box<Predicate>, Box<Predicate>),
Or(Box<Predicate>, Box<Predicate>),
Not(Box<Predicate>),
}
pub struct SymbolicState {
pub registers: HashMap<usize, SymbolicValue>,
pub memory: HashMap<usize, SymbolicValue>,
pub assumptions: Vec<Predicate>,
}
pub struct ProofObligation {
pub id: String,
pub name: String, // InvariantPreservation, etc
pub formula: Predicate,
pub status: ProofStatus,
}
pub enum ProofStatus {
Unknown,
Proved,
Disproved,
Manual,
}
pub struct Invariant {
pub loop_id: usize,
pub predicate: Predicate,
pub proof_strategy: ProofStrategy,
}
Public Methods
pub struct InvariantExtractor;
impl InvariantExtractor {
pub fn extract(&self, bytecode: &[Bytecode]) -> Result<Vec<Invariant>>;
pub fn generate_proof_obligations(&self, program: &Program) -> Vec<ProofObligation>;
pub fn compute_abstract_domain(bytecode: &[Bytecode]) -> AbstractDomain;
}
pub struct SymbolicExecutor;
impl SymbolicExecutor {
pub fn trace(bytecode: &[Bytecode]) -> Result<Vec<ExecutionPath>>;
pub fn evaluate(&self, expr: &SymbolicValue, state: &SymbolicState) -> SymbolicValue;
}
pub struct AbstractInterpreter;
impl AbstractInterpreter {
pub fn fixpoint(bytecode: &[Bytecode]) -> HashMap<usize, Interval>;
pub fn widen(v1: Interval, v2: Interval) -> Interval;
pub fn narrow(v: Interval, constraint: &Predicate) -> Interval;
}
5. proof-validator — Proof Checking & WORM Rollback
Location: crates/proof-validator/
Purpose: Type-check proofs (Curry-Howard), manage checkpoints for rollback
Public Types
pub enum ProofTerm {
Var(String),
Abs(String, Box<ProofTerm>), // lambda
App(Box<ProofTerm>, Box<ProofTerm>), // application
Const(Constant),
Pair(Box<ProofTerm>, Box<ProofTerm>),
Fst(Box<ProofTerm>), // projection
Snd(Box<ProofTerm>),
}
pub struct ProofContext {
pub assumptions: Vec<(String, ProofTerm)>,
}
pub struct ProofObligation {
pub id: String,
pub theorem: Predicate,
pub required_by_stage: String, // "compiled" | "executed" | "verified"
}
pub struct RollbackManager {
checkpoints: VecDeque<Checkpoint>,
max_checkpoints: usize,
}
pub struct ProofValidator;
Public Methods
pub struct TypeChecker;
impl TypeChecker {
pub fn check(&self, term: &ProofTerm, expected_type: &Type, ctx: &ProofContext) -> Result<()>;
pub fn infer(&self, term: &ProofTerm, ctx: &ProofContext) -> Result<Type>;
}
impl RollbackManager {
pub fn new(max_checkpoints: usize) -> Self;
pub fn push(&mut self, checkpoint: Checkpoint) -> Result<()>;
pub fn pop(&mut self) -> Option<Checkpoint>;
pub fn rollback_to(&mut self, checkpoint_id: Uuid) -> Result<()>;
pub fn list_checkpoints(&self) -> Vec<CheckpointSummary>;
}
pub struct ProofValidator;
impl ProofValidator {
pub fn validate_obligation(&self, obligation: &ProofObligation) -> Result<ProofStatus>;
pub fn emit_audit(&self, event: ProofEvent) -> Result<()>;
}
pub enum ProofEvent {
Validated { obligation_id: String, result: ProofStatus },
Violated { obligation_id: String, evidence: String },
RolledBack { checkpoint_id: Uuid },
}
6. m4-morph — Macro Engine & Self-Modification
Location: crates/m4-morph/
Purpose: GNU M4 macro expansion with sandboxing and state feedback
Public Types
pub struct SandboxLimits {
pub max_expansion_depth: usize, // default 100
pub max_output_size: usize, // default 1MB
pub max_recursion: usize, // default 50
pub timeout_ms: u64, // default 5000
}
pub enum SandboxPreset {
Permissive, // for trusted sources
Strict, // for untrusted sources
}
pub struct FeedbackBuffer {
pub definitions: VecDeque<(String, String)>, // bounded 50
pub outputs: VecDeque<String>, // bounded 100
}
pub struct M4Engine {
pub sandbox: SandboxConfig,
pub feedback: FeedbackBuffer,
}
pub struct M4Engine {
pub sandbox: SandboxConfig,
}
Public Methods
impl M4Engine {
pub fn new(limits: SandboxLimits) -> Self;
pub fn expand(&mut self, source: &str) -> Result<String>;
pub fn define(&mut self, name: &str, value: &str);
pub fn get_definition(&self, name: &str) -> Option<&str>;
pub fn set_sandbox(&mut self, config: SandboxConfig);
}
pub struct FeedbackBuffer;
impl FeedbackBuffer {
pub fn push_definition(&mut self, name: String, value: String);
pub fn push_output(&mut self, output: String);
pub fn get_recent_outputs(&self, n: usize) -> Vec<String>;
pub fn get_all_definitions(&self) -> Vec<(String, String)>;
}
7. notebook-kernel — Jupyter Protocol & Cell Execution
Location: crates/notebook-kernel/
Purpose: Jupyter protocol implementation, cell-to-cell communication, execution ring
Public Types
pub enum JupyterMessageType {
ExecuteRequest,
ExecuteReply,
DisplayData,
Stream,
Error,
Status,
}
pub struct JupyterMessage {
pub message_type: JupyterMessageType,
pub metadata: HashMap<String, String>,
pub content: serde_json::Value,
}
pub struct NotebookKernel {
pub kernel_id: String,
pub execution_ring: ExecutionRing,
pub ipc_channels: HashMap<usize, IpcChannel>,
}
pub struct CellConfig {
pub cell_id: String,
pub language: Language,
pub kernel: String,
pub visibility: CellVisibility,
}
pub enum CellVisibility {
Visible,
Hidden,
Collapsed,
}
pub struct ExecutionRing {
pub work_queue: VecDeque<CellInstruction>,
pub active_cells: HashSet<String>,
}
pub struct IpcChannel {
pub shared_buffer: Arc<RwLock<Vec<u8>>>,
}
Public Methods
impl NotebookKernel {
pub fn new(kernel_id: String) -> Self;
pub fn handle_message(&mut self, msg: JupyterMessage) -> Result<()>;
pub fn execute_cell(&mut self, cell: CellConfig, source: &str) -> Result<CellOutput>;
pub fn get_execution_status(&self) -> ExecutionStatus;
}
impl ExecutionRing {
pub fn enqueue(&mut self, instruction: CellInstruction);
pub fn dequeue(&mut self) -> Option<CellInstruction>;
pub fn poll(&mut self) -> Vec<ExecutionEvent>;
}
impl IpcChannel {
pub fn send(&self, data: &[u8]) -> Result<()>;
pub fn recv(&self) -> Result<Vec<u8>>;
}
8. notebook-orchestrator — Non-Recursive Receipt Chain
Location: crates/notebook-orchestrator/
Purpose: 8-stage pipeline, receipt generation, Prolog integration
Public Types
pub struct Instruction {
pub id: String, // SHA-256
pub agent: String,
pub capability: String,
pub runtime: String,
pub permission: String,
pub payload: Vec<u8>,
}
pub enum Stage {
Receive,
Translate,
Verify,
Dispatch,
Execute,
Encode,
Seal,
Complete,
}
pub struct Receipt {
pub id: String, // Blake3(contents)
pub sequence: usize,
pub instruction_hash: String,
pub stage: Stage,
pub result: ExecutionResult,
pub timestamp: u64,
pub signature: String, // Ed25519
pub previous_receipt_hash: String, // chain link
}
pub struct Orchestrator {
pub work_queue: VecDeque<Instruction>,
pub receipts: Vec<Receipt>,
pub prolog_engine: PrologBridge,
}
Public Methods
pub struct Orchestrator;
impl Orchestrator {
pub fn new(prolog_path: &str) -> Result<Self>;
pub fn process_instruction(&mut self, instr: Instruction) -> Result<Receipt>;
pub fn get_receipt_chain(&self) -> Vec<Receipt>;
pub fn verify_chain_integrity(&self) -> bool;
pub fn emit_receipt(&mut self, receipt: Receipt) -> Result<()>;
}
pub struct PrologBridge;
impl PrologBridge {
pub fn query(&self, predicate: &str, args: &[&str]) -> Result<Vec<String>>;
pub fn assert_fact(&self, fact: &str) -> Result<()>;
pub fn check_authorization(&self, agent: &str, cap: &str, runtime: &str, perm: &str) -> Result<bool>;
pub fn is_release_ready(&self) -> Result<bool>;
}
impl Receipt {
pub fn compute_hash(contents: &[u8]) -> String;
pub fn verify_signature(&self, pubkey: &str) -> Result<bool>;
}
Error Handling
All public methods return Result<T, Error> where Error implements std::error::Error.
pub enum Error {
ParseError(String),
TypeError(String),
ExecutionError(String),
ProofError(String),
AuthorizationError(String),
TimeoutError(String),
ReceiptError(String),
}
Examples
Execute SUBLEQ Bytecode
use subleq_vm::{VirtualMachine, ExecutionStatus};
let program = vec![
0, 0, 3, // M[0] -= M[0]; IP=3
100, 100, 106, // M[100] -= M[100]; IP=106
// ... rest of program
];
let mut vm = VirtualMachine::new(program);
let result = vm.execute()?;
match result.status {
ExecutionStatus::Normal => println!("Success: {} mutations", result.mutation_count),
ExecutionStatus::Timeout => println!("Timed out"),
ExecutionStatus::ViolationHalt => println!("Invariant violated"),
}
Parse Python and Compile to SUBLEQ
use polyglot_frontend::{LanguageRegistry, Language};
use subleq_ir::Program;
let mut registry = LanguageRegistry::new();
let python_parser = PythonParser::new();
registry.register(Language::Python, Box::new(python_parser));
let source = r#"
x = 10
y = 20
z = x + y
"#;
let ast = registry.parse(Language::Python, source)?;
let program = Program::from_ast(ast)?;
let bytecode = program.to_bytecode()?;
let subleq = program.to_subleq()?;
Extract Invariants and Generate Proofs
use invariant_extractor::InvariantExtractor;
let extractor = InvariantExtractor::new();
let invariants = extractor.extract(&bytecode)?;
let obligations = extractor.generate_proof_obligations(&program)?;
for obligation in obligations {
println!("Obligation: {}", obligation.name);
println!("Formula: {:?}", obligation.formula);
}
For detailed implementation examples, consult crate-specific documentation in each source directory.
"LOC WRITES. LEDGER CERTIFIES. METATRON SEALS."