sim/
lib.rs

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

sim/
lib.rs
