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.
collection
crypto: Real cryptography — BLAKE3 hashing and Ed25519 signatures — as blue’s own surface.
dispatch
doc_sources: Where blue check --fix finds a definition’s intent outside its own file: the verb graph (bidamas/mokuroku/graph/*.b), read once per graph directory as data and never run.
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.
receipt: Receipts on disk: each named by the BLAKE3 hash of its bytes, and checked by recomputing that name.
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.
timings: Wall time per pipeline stage, recorded only when a door asks for it.
uses: use("name") — how a blue program consumes a bidama.
xml

Structs§

Account: The account a run gives of itself besides its value, filled while it runs and read after it ends, whether it returned or raised.
ExecutionBounds: How much a blue program may do before it is refused: nested calls and evaluation steps.
Frame: A hold as an artifact names it.
Hold: What a run is held to: the frame it may reach the host through, and the capabilities pure providers stand in for.
HostIo: Host calls made through granted host names, per process of one node.
Identities: Each definition key’s def_hash (b3:<hex>), computed on first ask.
Receipt: One actor’s or one run’s account of itself.

Constants§

BREACH: The kind of the fatal error a capability breach raises.
BREACH_EXIT: The exit status a run that ended on a capability breach returns: EX_NOPERM (sysexits.h). blue run and an appliance both answer it.

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_accounted: Give interp a node whose processes are held to hold, when there is one, and give account of them: each child’s host calls tally into its ledger, its identities name each trace’s and receipt’s definition, and with a receipts directory every held process writes a receipt there when an incarnation ends.
attach_node_held: attach_node_in_frame with the hold’s providers bound in every child.
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.
breach: The fatal error a call to name raises when who does not grant cap. No rescue catches it: the run ends.
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.
is_breach: Is e a capability breach?
lower_to_spanned: Lift spanless forms into what the evaluator eats.
provided_name: The name a scoped provider binds the host name word under. No blue source can write it, so only the references Hold::rebind_scoped moves onto it reach the provider.
refuse_host_names: Bind each of refused that interp defines to a breach naming who.
refuse_host_names_noting: refuse_host_names, calling note with the host, the capability and the name before each breach is raised.
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.
ungranted_host_names: Every host name frame does not grant, with its capability.

Type Aliases§

Identified: The table of a lowered program’s identities, computed when first asked.
Identify: Given a checked program, its lowered tree and the key of the entry’s main if it has one: each definition key with its def_hash, and receipt::RUN with the run’s, computed only when first asked. blue-lang-mondou computes it; this crate only calls it.