Crate blue_lang_runtime

Expand description

The blue runtime — one definition of what a blue program runs against.

Before this crate existed, every consumer hand-rolled its own Interpreter::new() + install_primitives(...) pair — three of them, in three crates — and they had silently drifted: none of them loaded the Lisp stdlib. So 6 % 3 lowered correctly to (mod 6 3), mod was genuinely defined, and the program still died with unbound symbol: mod, because the definition lived in a stdlib nobody loaded.

That is the duplication tax in its usual shape: the bug is not in any one copy, it is in there being copies. One function now owns the answer.

§Layers

A blue interpreter is built in two layers, and both are required:

Rust primitives — arithmetic, comparison, list ops, I/O.
The full tatara stdlib — primitives, higher-order functions (map/filter/fold), maps, channels, fibers, type-check, and everything tatara defines in tatara-lisp itself (mod, rem, first, inc, even?, the actor and transducer helpers, …). Loading it is not optional garnish: blue’s own operator lowering depends on it.
blue’s own core (stdlib) — strings and number conversion, which tatara-lisp does not have in any form. A Ruby-surface language without length or upcase is not usable, and the semantics are Ruby’s (characters, not bytes), which is why they are blue’s and not the substrate’s.
JSON (json) and cryptography (crypto) — pure computation, installed unconditionally, so the wasm consumer keeps them.
The host layer (sys, behind the sys feature) — every name in it is a host import.
Processes (attach_node) — spawn, send, receive and the rest of blue_lang_proc::node’s words, bound to a node of the interpreter’s own, so the program is that node’s root process.

Re-exports§

pub use erase::erase_types;
pub use erase::to_sexps;
pub use inputs::declarations;
pub use inputs::install_input_primitives;
pub use inputs::Declaration;
pub use inputs::InputError;
pub use inputs::Inputs;
pub use pipeline::parse;
pub use pipeline::parse_tree_with_depth;
pub use pipeline::parse_with_depth;
pub use pipeline::run;
pub use pipeline::run_with_inputs;
pub use pipeline::Run;
pub use pipeline::RunError;
pub use stdlib::install_blue_stdlib;

Modules§

alloc: How many allocations a stretch of a blue program made, and how many bytes.
crypto: Real cryptography — BLAKE3 hashing and Ed25519 signatures — as blue’s own surface.
docs: One line for every name a blue program can call without a use.
domain: Blue as the authoring surface for Rust types: a blue value becomes a #[derive(TataraDomain)] struct.
erase: Type erasure — the step that makes the sliding scale actually slide.
errors
host_surface
hosted: Embedding blue in a Rust host: load a program into an interpreter the host built, then call its definitions by name.
inputs: Build inputs — the macro phase’s only channel to the outside world.
json: JSON — parse, stringify, and read back — as blue’s own surface.
literal: Runtime values as canonical blue source.
messages: Runtime errors in blue’s words.
nix
observe: Watching a blue program run: the call stack a runtime error reports, and the per-definition counters blue profile, blue test --coverage and blue trace read.
paths
pipeline: The blue pipeline: parse → check → erase → run, in that order, once.
project_rules: The rule-plugin ABI: how a check rule written in blue is called.
session: One evaluation session: the function the REPL, blue eval, blue serve and an editor all call (theory/BLUE-TOOLING.md §2, §4).
spread
stdlib: blue’s string and number core.
uses: use("name") — how a blue program consumes a bidama.

Structs§

ExecutionBounds: How much a blue program may do before it is refused: nested calls and evaluation steps.

Functions§

attach_node: Give interp a process node of its own: its program becomes the node’s root, and spawn starts processes in this node and no other.
attach_node_in_frame: attach_node for a program that runs under frame: every process it starts is held to the same frame, so a host name the program may not call is refused in its children too. Without this a spawned child would run on the full runtime and a frame would be one spawn away from meaningless.
execution_bounds: The bounds interpreters are built with.
interpreter: Build an interpreter with the complete blue runtime installed.
interpreter_hostless: The common host-free case.
lower_to_spanned: Lift spanless forms into what the evaluator eats.
set_execution_bounds: Name the bounds for this process. The CLI calls this once with the resolved BlueConfig, before any interpreter is built; an embedder that never calls it runs under ExecutionBounds::DEFAULT. Only the first call counts, like sys::set_program_args.