Module interpreter 

Tree-walking interpreter for LOGOS imperative code.

This module provides runtime execution of parsed LOGOS programs by walking the AST and executing statements/expressions directly. The interpreter is async-capable to support VFS operations.

Architecture

LOGOS AST
    │
    ▼
┌────────────┐
│ Interpreter│ ──▶ Evaluate expressions
│            │ ──▶ Execute statements
│            │ ──▶ Manage scopes
└────────────┘
    │
    ▼
RuntimeValue results

Runtime Values

The interpreter uses RuntimeValue to represent all values at runtime:

• Primitives: Int, Float, Bool, Text, Char
• Collections: List, Tuple, Set, Map
• User types: Struct, Inductive (kernel-defined types)

Async Support

The interpreter is async to support VFS file operations (OPFS on WASM, tokio::fs on native). All statement execution is async fn.

Structs

ClosureValue

First-class closure value (boxed to reduce enum size).

FunctionDef

Stored function definition for user-defined functions.

InductiveValue

Kernel inductive value (boxed to reduce enum size).

Interpreter

InterpreterResult

Result from program interpretation.

QuantityValue

The payload of a RuntimeValue::Quantity: the physical quantity (magnitude in SI base + dimension) plus the unit it should be displayed in. Equality/hashing are by physical value (SI magnitude + dimension) — the display unit is presentation only, so 2 inches equals 5.08 centimetres.

StructValue

Runtime values during LOGOS interpretation.

Enums

ClosureBodyRef

Side-table entry storing a closure body AST reference. The index into the closure_bodies Vec on the interpreter is stored in ClosureValue::body_index.

ControlFlow

Control flow signals returned from statement execution.

ListRepr

The List payload behind RuntimeValue::List: homogeneous all-Int and all-Float lists store UNBOXED vectors (cache-dense, and the JIT can pin a raw pointer to them); anything else boxes. The repr lives INSIDE the Rc<RefCell<…>>, so promotion re-tags the payload in place and every alias observes it — reference semantics and Rc identity are untouched. An EMPTY list is vacuously Ints and re-tags freely on its first push.

RuntimeValue

Functions

needs_async

Type Aliases

MapStorage

The Map payload behind RuntimeValue::Map. INSERTION-ORDERED (IndexMap): iteration, display, and marshaling follow the order keys were first inserted — the LOGOS Map contract, identical across the tree-walker, the VM, the AOT LogosMap, and the direct-WASM linear map. FxHash instead of the standard library’s SipHash: map-heavy programs hash on every get/insert, and the keys here are small values (ints, short texts) where Fx is several times faster — with no DoS-resistance requirement (a single-program interpreter hashing its own program’s keys). NOTE: removal must go through shift_remove (order-preserving), never swap_remove.

OutputCallback

Callback type for streaming output from the interpreter. Called each time Show executes with the output line.