sim/
lib.rs

1//! # sim: the SIM umbrella crate
2//!
3//! SIM is an expandable Rust runtime built around a small protocol kernel plus
4//! a large set of loadable libraries. The kernel defines contracts; libraries
5//! provide behavior. The data flow is:
6//!
7//! ```text
8//! tokens -> checked forms -> objects -> checked calls -> objects -> encoded forms
9//! ```
10//!
11//! SIM is a Rust runtime with multiple codec surfaces. Lisp is one codec, not
12//! the system identity. Everything above the kernel is a lib: syntax, codecs,
13//! classes, functions, number domains, checkers, evaluators, wasm adapters,
14//! loaders, and even the standard language surface. The standard distribution
15//! is just a set of libs loaded by default.
16//!
17//! ## Umbrella role
18//!
19//! This crate (`sim`) is the umbrella and entry point of the SIM constellation.
20//! The implementation crates live in sibling repositories; this crate
21//! aggregates them through optional dependencies and a feature map, re-exports
22//! them under stable module aliases (`sim::kernel`, `sim::shape`,
23//! `sim::codec`, the `sim::codec_*`, `sim::lib_*`, `sim::table_*`, and
24//! `sim::list_*` families), and ships the core runtime installer plus the
25//! authoring helpers (`functions`, `classes`, `macros`, `shapes`, and
26//! `runtime`, available with the `shape` feature). The default feature set is
27//! `core`, `codec-lisp`, and
28//! `numbers-f64`; the canonical, current feature map is this crate's
29//! `Cargo.toml`.
30//!
31//! ## Kernel boundary
32//!
33//! The central discipline is keeping the kernel small. The kernel may define
34//! identity and transport types (`Symbol`, `Expr`, `Value`, `Origin`, `Ref`,
35//! `Datum`, errors, stable ids), coordination types (`Cx`, `Registry`, `Lib`,
36//! `Linker`, `ExportRecord`, capabilities, claim/fact and handle stores, Card
37//! records, operation specs, event/effect ledgers, control policy, rank
38//! metadata), the object/callable/class/shape/factory/eval-policy/
39//! macro-expander behavior contracts, shape match and binding result types, and
40//! the ABI frame and manifest transport shapes. The kernel must not define
41//! concrete Lisp/JSON/Algol parsing, concrete number domains or arithmetic,
42//! concrete help/test/browse implementations, wasm guest behavior above the ABI
43//! transport, or remote transport and agent-product policy. New metadata is
44//! modeled as open `ExportRecord`-style data rather than new closed kernel
45//! enums. Concrete behavior is added as a lib through `Lib`, `Linker`, and
46//! `ExportRecord`.
47//!
48//! ## Load-bearing concepts
49//!
50//! - **`Shape`** is one shared engine for parsing, checking, binding, dispatch,
51//!   macro syntax, codec grammar, lambda locals, and overload selection. It is
52//!   a first-class kernel protocol (object-accessible via `as_shape`, callable
53//!   as a matcher); concrete shape behavior lives in `sim-shape` and other libs.
54//! - **Codecs are first-class runtime objects**, split into independent
55//!   decoders and encoders; encoders know their output position. General-purpose
56//!   expression codecs are total over the shared `Expr` graph and round-trip
57//!   every expression semantically; domain codecs round-trip only their domain
58//!   and fail closed outside it.
59//! - **`realize` and `EvalFabric`** are the location-transparent distributed
60//!   evaluation surface. Server and agent code targets these, never a
61//!   transport-specific API. Evaluation strategy itself is an injectable
62//!   `EvalPolicy` (eager, lazy, need, hybrid, no-op).
63//! - **Capability gating** makes power explicit: read-eval, native dynamic
64//!   loading, and host effects (file, network, clock, random, process) are
65//!   capabilities a host grants. **Read-construct** is the narrower
66//!   capability-gated path that backs Lisp `#(...)` literals; it is distinct
67//!   from broad **read-eval**, which evaluates during decode and is disabled by
68//!   default for untrusted input.
69//! - **Number domains, lists, and tables are pluggable libs**, not kernel
70//!   behavior; codecs delegate numeric literals to the active domains by parse
71//!   priority.
72//! - **Wasm** is a first-class runtime target and the portable plugin ABI.
73//!
74//! ## Embedding
75//!
76//! `runtime::install_core_runtime` (with the `shape` feature) is the entry
77//! point for embedding SIM.
78//! Build a `Cx` with an eval policy and a factory, install the core runtime,
79//! then install codecs and behavior libs through their `install_*` helpers or
80//! directly through `Lib` and `Linker`:
81//!
82//! ```ignore
83//! use std::sync::Arc;
84//! use sim::kernel::{Cx, DefaultFactory, EagerPolicy};
85//! use sim::runtime::install_core_runtime;
86//!
87//! let mut cx = Cx::new(Arc::new(EagerPolicy), Arc::new(DefaultFactory));
88//! install_core_runtime(&mut cx);
89//! // install codecs and libs, then cx.eval_expr(...).
90//! ```
91//!
92//! `install_core_runtime` loads the core runtime through the lib registry and
93//! installs the default number domain(s) for the enabled `numbers-*` features.
94#![deny(unsafe_code)]
95#![deny(missing_docs)]
96#![allow(deprecated)]
97extern crate self as sim;
98
99#[rustfmt::skip]
100#[cfg(any(feature = "femm-assembly", feature = "femm-codec", feature = "femm-core", feature = "femm-fixtures", feature = "femm-field", feature = "femm-flow", feature = "femm-function", feature = "femm-geometry", feature = "femm-material", feature = "femm-mesh", feature = "femm-ode", feature = "femm-physics", feature = "femm-post", feature = "femm-prelude", feature = "femm-sensitiv", feature = "femm-solve", feature = "femm-space", feature = "femm-tape"))]
101pub use femm_exports::*;
102#[rustfmt::skip] #[allow(unused_imports)] pub use numbers_exports::*;
103#[rustfmt::skip]
104#[cfg(any(feature = "codec-lisp", feature = "codec-json", feature = "codec-binary", feature = "codec-binary-base64", feature = "codec-bitwise", feature = "codec-bitwise-base64", feature = "codec-chat", feature = "codec-mcp", feature = "codec-algol"))]
105pub use sim_codec as codec;
106#[cfg(feature = "codec-algol")]
107pub use sim_codec_algol as codec_algol;
108#[cfg(feature = "codec-binary")]
109pub use sim_codec_binary as codec_binary;
110#[cfg(feature = "codec-binary-base64")]
111pub use sim_codec_binary_base64 as codec_binary_base64;
112#[cfg(feature = "codec-bitwise")]
113pub use sim_codec_bitwise as codec_bitwise;
114#[cfg(feature = "codec-bitwise-base64")]
115pub use sim_codec_bitwise_base64 as codec_bitwise_base64;
116#[cfg(feature = "codec-chat")]
117pub use sim_codec_chat as codec_chat;
118#[cfg(feature = "codec-json")]
119pub use sim_codec_json as codec_json;
120#[cfg(feature = "codec-lisp")]
121pub use sim_codec_lisp as codec_lisp;
122#[cfg(feature = "codec-mcp")]
123pub use sim_codec_mcp as codec_mcp;
124#[cfg(feature = "core")]
125pub use sim_kernel as kernel;
126#[cfg(feature = "standard-binding")]
127pub use sim_lib_binding as lib_binding;
128#[cfg(feature = "control")]
129pub use sim_lib_control as lib_control;
130#[cfg(feature = "core")]
131pub use sim_lib_core as lib_core;
132#[cfg(feature = "standard-dispatch")]
133pub use sim_lib_dispatch as lib_dispatch;
134#[cfg(feature = "standard-cl")]
135pub use sim_lib_lang_cl as lib_lang_cl;
136#[cfg(feature = "standard-clojure")]
137pub use sim_lib_lang_clojure as lib_lang_clojure;
138#[cfg(feature = "standard-islisp")]
139pub use sim_lib_lang_islisp as lib_lang_islisp;
140#[cfg(feature = "standard-julia")]
141pub use sim_lib_lang_julia as lib_lang_julia;
142#[cfg(feature = "standard-lua")]
143pub use sim_lib_lang_lua as lib_lang_lua;
144#[cfg(feature = "standard-ruby")]
145pub use sim_lib_lang_ruby as lib_lang_ruby;
146#[cfg(feature = "standard-scheme")]
147pub use sim_lib_lang_scheme as lib_lang_scheme;
148#[cfg(feature = "standard-typed-lazy")]
149pub use sim_lib_lang_typed_lazy as lib_lang_typed_lazy;
150#[cfg(feature = "logic-core")]
151pub use sim_lib_logic as lib_logic;
152#[cfg(feature = "mcp")]
153pub use sim_lib_mcp::{self as lib_mcp, install_mcp_lib};
154#[cfg(feature = "standard-mutation")]
155pub use sim_lib_mutation as lib_mutation;
156#[cfg(feature = "standard-namespace")]
157pub use sim_lib_namespace as lib_namespace;
158#[cfg(feature = "openai-server")]
159pub use sim_lib_openai_server as lib_openai_server;
160#[cfg(feature = "standard-pattern")]
161pub use sim_lib_pattern as lib_pattern;
162#[cfg(feature = "rank")]
163pub use sim_lib_rank as lib_rank;
164#[cfg(feature = "standard-sequence")]
165pub use sim_lib_sequence as lib_sequence;
166#[cfg(feature = "server")]
167pub use sim_lib_server::{self as lib_server, install_server_lib};
168#[cfg(feature = "skill")]
169pub use sim_lib_skill::{self as lib_skill, install_skill_lib};
170#[cfg(feature = "standard-core")]
171pub use sim_lib_standard_core as lib_standard_core;
172#[cfg(feature = "stream-audio")]
173pub use sim_lib_stream_audio as lib_stream_audio;
174#[cfg(feature = "stream-bridge")]
175pub use sim_lib_stream_bridge as lib_stream_bridge;
176#[cfg(feature = "stream-clock")]
177pub use sim_lib_stream_clock as lib_stream_clock;
178#[cfg(feature = "stream-combinators")]
179pub use sim_lib_stream_combinators as lib_stream_combinators;
180#[cfg(feature = "stream-core")]
181pub use sim_lib_stream_core as lib_stream_core;
182#[cfg(feature = "stream-fabric")]
183pub use sim_lib_stream_fabric as lib_stream_fabric;
184#[cfg(feature = "stream-file")]
185pub use sim_lib_stream_file as lib_stream_file;
186#[cfg(feature = "stream-host")]
187pub use sim_lib_stream_host as lib_stream_host;
188#[cfg(feature = "stream-midi")]
189pub use sim_lib_stream_midi as lib_stream_midi;
190#[cfg(feature = "stream-prelude")]
191pub use sim_lib_stream_prelude as lib_stream_prelude;
192#[cfg(feature = "web-bridge")]
193pub use sim_lib_web_bridge as lib_web_bridge;
194#[cfg(feature = "list-cell")]
195pub use sim_list_cell as list_cell;
196#[cfg(feature = "list-lazy")]
197pub use sim_list_lazy as list_lazy;
198#[cfg(feature = "shape")]
199pub use sim_shape as shape;
200#[cfg(feature = "table-db")]
201pub use sim_table_db as table_db;
202#[cfg(feature = "table-fs")]
203pub use sim_table_fs as table_fs;
204#[cfg(feature = "table-hash")]
205pub use sim_table_hash as table_hash;
206#[cfg(feature = "table-lazy")]
207pub use sim_table_lazy as table_lazy;
208#[cfg(feature = "table-override")]
209pub use sim_table_override as table_override;
210#[cfg(feature = "table-remote")]
211pub use sim_table_remote as table_remote;
212#[rustfmt::skip]
213#[cfg(any(feature = "server-net-http", feature = "agent-net", feature = "openai-server-http", feature = "standard", feature = "rank-codec-fallback", feature = "rank-expr", feature = "rank-learn", feature = "rank-music", feature = "rank-scatter", feature = "stream-bridge", feature = "stream-host"))]
214const _: bool = true;
215#[allow(unused_imports)]
216pub use roadmap11_exports::*;
217#[cfg(feature = "agent")]
218pub use sim_lib_agent::{self as lib_agent, install_agent_lib};
219/// Native class authoring helpers: a `Class` implementation plus the lib
220/// wrapper that registers a host-defined class, its constructor, and members.
221#[cfg(all(feature = "core", feature = "shape"))]
222pub mod classes;
223#[rustfmt::skip]
224#[cfg(all(test, feature = "shape", feature = "codec-lisp", feature = "codec-json", feature = "codec-binary", feature = "codec-binary-base64", feature = "codec-algol"))]
225mod codec_matrix_tests;
226/// Stable hashing of lib manifests, shapes, and codecs for compatibility
227/// checks across versions of the constellation.
228#[cfg(feature = "core")]
229pub mod compat;
230mod femm_exports;
231/// Function authoring helpers built on the shared `Shape` engine: overload
232/// cases, native function objects, and member-table construction.
233#[cfg(all(feature = "core", feature = "shape"))]
234pub mod functions;
235/// Lib loaders for the supported source formats (host, Lisp source, binary
236/// pack, native dynamic library, and wasm) plus the standard loader registry.
237#[cfg(feature = "core")]
238pub mod loaders;
239/// Macro authoring and expansion: the `LispMacro` contract, macro objects, the
240/// registry-backed expander, and shape constructors for macro syntax.
241#[cfg(all(feature = "core", feature = "shape"))]
242pub mod macros;
243/// End-to-end music rendering stack that lowers a score to MIDI and renders it
244/// to PCM audio through the sound libs.
245#[cfg(feature = "sound-music")]
246pub mod music_stack;
247mod numbers_exports;
248mod roadmap11_exports;
249/// Core runtime installer and the embedding entry point that wires classes,
250/// shapes, functions, and the default number domains into a `Cx`.
251#[cfg(all(feature = "core", feature = "shape"))]
252pub mod runtime;
253/// Shape authoring helpers: documented and value-backed shape wrappers plus
254/// shape registration and checking utilities.
255#[cfg(all(feature = "core", feature = "shape"))]
256pub mod shapes;
257#[cfg(feature = "proc-macros")]
258pub use sim_macros::*;
259#[cfg(feature = "wasm")]
260pub use sim_wasm_abi as wasm_abi;
261#[cfg(test)]
262mod feature_contract_tests;
263#[cfg(all(test, feature = "music-stack"))]
264mod music_stack_tests;
265#[cfg(all(test, feature = "skill"))]
266mod skill_tests;
sim/lib.rs

sim/
lib.rs
