Crate sim 

sim-nest – the SIM umbrella crate (imported as sim)

Published on crates.io as sim-nest (the bare name sim is taken), but the library import identifier is sim. Add it as sim-nest = "0.1" (or, to make the rename explicit, sim = { package = "sim-nest", version = "0.1" }) and write use sim::... throughout; the #[sim::sim_lib] / #[sim::sim_fn] proc-macros resolve against it unchanged. Note: use sim_nest::... will NOT resolve – the crate’s library name is sim, so import sim, not sim_nest.

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_lib_agent as lib_agent;

pub use sim_wasm_abi as wasm_abi;

pub use sim_lib_femm_assembly as femm_assembly;

pub use sim_lib_femm_codec as femm_codec;

pub use sim_lib_femm_core as femm_core;

pub use sim_lib_femm_field as femm_field;

pub use sim_lib_femm_fixtures as femm_fixtures;

pub use sim_lib_femm_flow as femm_flow;

pub use sim_lib_femm_function as femm_function;

pub use sim_lib_femm_geometry as femm_geometry;

pub use sim_lib_femm_material as femm_material;

pub use sim_lib_femm_mesh as femm_mesh;

pub use sim_lib_femm_ode as femm_ode;

pub use sim_lib_femm_physics as femm_physics;

pub use sim_lib_femm_post as femm_post;

pub use sim_lib_femm_prelude as femm_prelude;

pub use sim_lib_femm_sensitiv as femm_sensitiv;

pub use sim_lib_femm_solve as femm_solve;

pub use sim_lib_femm_space as femm_space;

pub use sim_lib_femm_tape as femm_tape;

pub use sim_lib_numbers_ad as numbers_ad;

pub use sim_lib_numbers_arith as numbers_arith;

pub use sim_lib_numbers_bigint as numbers_bigint;

pub use sim_lib_numbers_bool as numbers_bool;

pub use sim_lib_numbers_cas as numbers_cas;

pub use sim_lib_numbers_cas_diff as numbers_cas_diff;

pub use sim_lib_numbers_cas_eval as numbers_cas_eval;

pub use sim_lib_numbers_codec as numbers_codec;

pub use sim_lib_numbers_complex as numbers_complex;

pub use sim_lib_numbers_core as numbers_core;

pub use sim_lib_numbers_exotic as numbers_exotic;

pub use sim_lib_numbers_f64 as numbers_f64;

pub use sim_lib_numbers_fixed as numbers_fixed;

pub use sim_lib_numbers_float as numbers_float;

pub use sim_lib_numbers_func as numbers_func;

pub use sim_lib_numbers_i64 as numbers_i64;

pub use sim_lib_numbers_numeric as numbers_numeric;

pub use sim_lib_numbers_prelude as numbers_prelude;

pub use sim_lib_numbers_quad as numbers_quad;

pub use sim_lib_numbers_rational as numbers_rational;

pub use sim_lib_numbers_rk as numbers_rk;

pub use sim_lib_numbers_tensor as numbers_tensor;

pub use sim_lib_numbers_tensor_bcast as numbers_tensor_bcast;

pub use sim_lib_numbers_tensor_bit as numbers_tensor_bit;

pub use sim_lib_numbers_tensor_cmplxf as numbers_tensor_cmplxf;

pub use sim_lib_numbers_tensor_f64 as numbers_tensor_f64;

pub use sim_lib_numbers_tensor_i64 as numbers_tensor_i64;

pub use sim_lib_numbers_tensor_linalg as numbers_tensor_linalg;

pub use sim_lib_numbers_tensor_rat64 as numbers_tensor_rat64;

pub use sim_codec as codec;

pub use sim_codec_algol as codec_algol;

pub use sim_codec_binary as codec_binary;

pub use sim_codec_binary_base64 as codec_binary_base64;

pub use sim_codec_bitwise as codec_bitwise;

pub use sim_codec_bitwise_base64 as codec_bitwise_base64;

pub use sim_codec_chat as codec_chat;

pub use sim_codec_json as codec_json;

pub use sim_codec_lisp as codec_lisp;

pub use sim_codec_mcp as codec_mcp;

pub use sim_kernel as kernel;

pub use sim_lib_binding as lib_binding;

pub use sim_lib_control as lib_control;

pub use sim_lib_core as lib_core;

pub use sim_lib_dispatch as lib_dispatch;

pub use sim_lib_lang_cl as lib_lang_cl;

pub use sim_lib_lang_clojure as lib_lang_clojure;

pub use sim_lib_lang_islisp as lib_lang_islisp;

pub use sim_lib_lang_julia as lib_lang_julia;

pub use sim_lib_lang_lua as lib_lang_lua;

pub use sim_lib_lang_ruby as lib_lang_ruby;

pub use sim_lib_lang_scheme as lib_lang_scheme;

pub use sim_lib_lang_typed_lazy as lib_lang_typed_lazy;

pub use sim_lib_logic as lib_logic;

pub use sim_lib_mcp as lib_mcp;

pub use sim_lib_mutation as lib_mutation;

pub use sim_lib_namespace as lib_namespace;

pub use sim_lib_openai_server as lib_openai_server;

pub use sim_lib_pattern as lib_pattern;

pub use sim_lib_rank as lib_rank;

pub use sim_lib_sequence as lib_sequence;

pub use sim_lib_server as lib_server;

pub use sim_lib_skill as lib_skill;

pub use sim_lib_standard_core as lib_standard_core;

pub use sim_lib_stream_audio as lib_stream_audio;

pub use sim_lib_stream_bridge as lib_stream_bridge;

pub use sim_lib_stream_clock as lib_stream_clock;

pub use sim_lib_stream_combinators as lib_stream_combinators;

pub use sim_lib_stream_core as lib_stream_core;

pub use sim_lib_stream_fabric as lib_stream_fabric;

pub use sim_lib_stream_file as lib_stream_file;

pub use sim_lib_stream_host as lib_stream_host;

pub use sim_lib_stream_midi as lib_stream_midi;

pub use sim_lib_stream_prelude as lib_stream_prelude;

pub use sim_lib_web_bridge as lib_web_bridge;

pub use sim_list_cell as list_cell;

pub use sim_list_lazy as list_lazy;

pub use sim_shape as shape;

pub use sim_table_db as table_db;

pub use sim_table_fs as table_fs;

pub use sim_table_hash as table_hash;

pub use sim_table_lazy as table_lazy;

pub use sim_table_override as table_override;

pub use sim_table_remote as table_remote;

pub use sim_citizen as citizen;

pub use sim_citizen_derive as citizen_derive;

pub use sim_lib_agent_runner_core as lib_agent_runner_core;

pub use sim_lib_audio_dsp as lib_audio_dsp;

pub use sim_lib_audio_graph_core as lib_audio_graph_core;

pub use sim_lib_audio_graph_live as lib_audio_graph_live;

pub use sim_lib_daw_session as lib_daw_session;

pub use sim_lib_intent as lib_intent;

pub use sim_lib_midi_ble as lib_midi_ble;

pub use sim_lib_midi_core as lib_midi_core;

pub use sim_lib_midi_live as lib_midi_live;

pub use sim_lib_midi_rtmidi as lib_midi_rtmidi;

pub use sim_lib_midi_shapes as lib_midi_shapes;

pub use sim_lib_midi_smf as lib_midi_smf;

pub use sim_lib_midi_sysex as lib_midi_sysex;

pub use sim_lib_midi_wasm_frame as lib_midi_wasm_frame;

pub use sim_lib_music_analysis as lib_music_analysis;

pub use sim_lib_music_combinators as lib_music_combinators;

pub use sim_lib_music_core as lib_music_core;

pub use sim_lib_music_lift as lib_music_lift;

pub use sim_lib_music_lower as lib_music_lower;

pub use sim_lib_music_notation as lib_music_notation;

pub use sim_lib_music_shapes as lib_music_shapes;

pub use sim_lib_music_synth as lib_music_synth;

pub use sim_lib_music_transform as lib_music_transform;

pub use sim_lib_music_wasm_frame as lib_music_wasm_frame;

pub use sim_lib_pitch_chord as lib_pitch_chord;

pub use sim_lib_pitch_core as lib_pitch_core;

pub use sim_lib_pitch_dissonance as lib_pitch_dissonance;

pub use sim_lib_pitch_namer as lib_pitch_namer;

pub use sim_lib_pitch_namer_forte as lib_pitch_namer_forte;

pub use sim_lib_pitch_namer_jazz as lib_pitch_namer_jazz;

pub use sim_lib_pitch_namer_riemann as lib_pitch_namer_riemann;

pub use sim_lib_pitch_namer_roman as lib_pitch_namer_roman;

pub use sim_lib_pitch_scale as lib_pitch_scale;

pub use sim_lib_pitch_set as lib_pitch_set;

pub use sim_lib_pitch_shapes as lib_pitch_shapes;

pub use sim_lib_pitch_wasm_frame as lib_pitch_wasm_frame;

pub use sim_lib_plugin_clap as lib_plugin_clap;

pub use sim_lib_plugin_core as lib_plugin_core;

pub use sim_lib_plugin_lv2 as lib_plugin_lv2;

pub use sim_lib_plugin_vst3 as lib_plugin_vst3;

pub use sim_lib_scene as lib_scene;

pub use sim_lib_sound_audio_lift as lib_sound_audio_lift;

pub use sim_lib_sound_bridge as lib_sound_bridge;

pub use sim_lib_sound_core as lib_sound_core;

pub use sim_lib_sound_dissonance as lib_sound_dissonance;

pub use sim_lib_sound_gm as lib_sound_gm;

pub use sim_lib_sound_render as lib_sound_render;

pub use sim_lib_sound_shapes as lib_sound_shapes;

pub use sim_lib_sound_spectrum as lib_sound_spectrum;

pub use sim_lib_sound_timbre as lib_sound_timbre;

pub use sim_lib_sound_tuning as lib_sound_tuning;

pub use sim_lib_sound_wasm_frame as lib_sound_wasm_frame;

pub use sim_lib_stream_alsa as lib_stream_alsa;

pub use sim_lib_stream_asio as lib_stream_asio;

pub use sim_lib_stream_coreaudio as lib_stream_coreaudio;

pub use sim_lib_stream_jack as lib_stream_jack;

pub use sim_lib_stream_pipewire as lib_stream_pipewire;

pub use sim_lib_stream_portaudio as lib_stream_portaudio;

pub use sim_lib_topology as lib_topology;

pub use sim_lib_view as lib_view;

pub use sim_lib_view_daw as lib_view_daw;

pub use sim_lib_view_doc as lib_view_doc;

pub use sim_lib_web_layout as lib_web_layout;

Modules

classes

Native class authoring helpers: a Class implementation plus the lib wrapper that registers a host-defined class, its constructor, and members.

compat

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

functions

Function authoring helpers built on the shared Shape engine: overload cases, native function objects, and member-table construction.

loaders

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

macros

Macro authoring and expansion: the LispMacro contract, macro objects, the registry-backed expander, and shape constructors for macro syntax.

music_stack

End-to-end music rendering stack that lowers a score to MIDI and renders it to PCM audio through the sound libs.

runtime

Core runtime installer and the embedding entry point that wires classes, shapes, functions, and the default number domains into a Cx.

shapes

Shape authoring helpers: documented and value-backed shape wrappers plus shape registration and checking utilities.

Functions

install_agent_lib

Installs the agent library into cx, pulling in the server lib, registering the agent address resolver and line driver, and loading AgentLib.

install_mcp_lib

Installs McpLib into cx, loading it once if not already present.

install_server_lib

Installs the server lib into cx exactly once, registering its functions and CLI exports.

install_skill_lib

Installs the skill library into cx once and publishes its browse metadata.

Attribute Macros

case

Marks a function inside a #[sim_lib] module as a test case. It is consumed by #[sim_lib]; applied on its own it leaves the item unchanged.

shape

Attaches a shape literal to an item inside a #[sim_lib] module. It is consumed by #[sim_lib]; applied on its own it leaves the item unchanged.

sim_class

Marks a struct inside a #[sim_lib] module as a SIM class. It is consumed by #[sim_lib]; applied on its own it leaves the item unchanged.

sim_codec

Marks a codec export inside a #[sim_lib] module. The marker names the codec symbol plus decoder and encoder functions that are called by generated native ABI dispatch.

sim_constructor

Marks a function inside a #[sim_lib] module as a class constructor. It is consumed by #[sim_lib]; applied on its own it leaves the item unchanged.

sim_fn

Marks a function inside a #[sim_lib] module as a SIM operation. It is consumed by #[sim_lib]; applied on its own it leaves the item unchanged.

sim_lib

Expands an inline module into a SIM library.

sim_macro

Marks a macro export inside a #[sim_lib] module. The marker names the macro symbol plus the expansion function called by host registration and generated native ABI dispatch.

sim_number_domain

Marks a number-domain export inside a #[sim_lib] module. The marker names the domain symbol plus guest functions that are called by generated native ABI dispatch for parsing, literal encoding, and optional scalar operations.

sim_site

Marks a site export inside a #[sim_lib] module. The marker names the site symbol plus the function called by generated native ABI dispatch for realization requests.