Crate sim 

sim: the SIM umbrella crate

SIM is an expandable Rust runtime built around a small protocol kernel plus a large set of loadable libraries. The kernel defines contracts; libraries provide behavior. The data flow is:

tokens -> checked forms -> objects -> checked calls -> objects -> encoded forms

SIM is a Rust runtime with multiple codec surfaces. Lisp is one codec, not the system identity. Everything above the kernel is a lib: syntax, codecs, classes, functions, number domains, checkers, evaluators, wasm adapters, loaders, and even the standard language surface. The standard distribution is just a set of libs loaded by default.

Umbrella role

This crate (sim) is the umbrella and entry point of the SIM constellation. The implementation crates live in sibling repositories; this crate aggregates them through optional dependencies and a feature map, re-exports them under stable module aliases (sim::kernel, sim::shape, sim::codec, the sim::codec_*, sim::lib_*, sim::table_*, and sim::list_* families), and ships the core runtime installer plus the authoring helpers (functions, classes, macros, shapes, and runtime, available with the shape feature). The default feature set is core, codec-lisp, and numbers-f64; the canonical, current feature map is this crate’s Cargo.toml.

Kernel boundary

The central discipline is keeping the kernel small. The kernel may define identity and transport types (Symbol, Expr, Value, Origin, Ref, Datum, errors, stable ids), coordination types (Cx, Registry, Lib, Linker, ExportRecord, capabilities, claim/fact and handle stores, Card records, operation specs, event/effect ledgers, control policy, rank metadata), the object/callable/class/shape/factory/eval-policy/ macro-expander behavior contracts, shape match and binding result types, and the ABI frame and manifest transport shapes. The kernel must not define concrete Lisp/JSON/Algol parsing, concrete number domains or arithmetic, concrete help/test/browse implementations, wasm guest behavior above the ABI transport, or remote transport and agent-product policy. New metadata is modeled as open ExportRecord-style data rather than new closed kernel enums. Concrete behavior is added as a lib through Lib, Linker, and ExportRecord.

Load-bearing concepts

• Shape is one shared engine for parsing, checking, binding, dispatch, macro syntax, codec grammar, lambda locals, and overload selection. It is a first-class kernel protocol (object-accessible via as_shape, callable as a matcher); concrete shape behavior lives in sim-shape and other libs.
• Codecs are first-class runtime objects, split into independent decoders and encoders; encoders know their output position. General-purpose expression codecs are total over the shared Expr graph and round-trip every expression semantically; domain codecs round-trip only their domain and fail closed outside it.
• realize and EvalFabric are the location-transparent distributed evaluation surface. Server and agent code targets these, never a transport-specific API. Evaluation strategy itself is an injectable EvalPolicy (eager, lazy, need, hybrid, no-op).
• Capability gating makes power explicit: read-eval, native dynamic loading, and host effects (file, network, clock, random, process) are capabilities a host grants. Read-construct is the narrower capability-gated path that backs Lisp #(...) literals; it is distinct from broad read-eval, which evaluates during decode and is disabled by default for untrusted input.
• Number domains, lists, and tables are pluggable libs, not kernel behavior; codecs delegate numeric literals to the active domains by parse priority.
• Wasm is a first-class runtime target and the portable plugin ABI.

Embedding

runtime::install_core_runtime (with the shape feature) is the entry point for embedding SIM. Build a Cx with an eval policy and a factory, install the core runtime, then install codecs and behavior libs through their install_* helpers or directly through Lib and Linker:

use std::sync::Arc;
use sim::kernel::{Cx, DefaultFactory, EagerPolicy};
use sim::runtime::install_core_runtime;

let mut cx = Cx::new(Arc::new(EagerPolicy), Arc::new(DefaultFactory));
install_core_runtime(&mut cx);
// install codecs and libs, then cx.eval_expr(...).

install_core_runtime loads the core runtime through the lib registry and installs the default number domain(s) for the enabled numbers-* features.

Re-exports

pub use sim_codec as codec;

pub use sim_codec_lisp as codec_lisp;

pub use sim_kernel as kernel;

pub use sim_lib_core as lib_core;

pub use sim_lib_numbers_arith as numbers_arith;

pub use sim_lib_numbers_core as numbers_core;

pub use sim_lib_numbers_f64 as numbers_f64;

Modules

compat

Stable hashing of lib manifests, shapes, and codecs for compatibility checks across versions of the constellation.

loaders

Lib loaders for the supported source formats (host, Lisp source, binary pack, native dynamic library, and wasm) plus the standard loader registry.