# SIM.md -- architecture and conformance contract
This is the authored architecture contract for the SIM runtime and the document
the `sim-conformance` suite checks itself against. It is not generated; it states
the data flow, the kernel-contract claims the executable suite verifies, and the
surfaces that are covered versus the surfaces that are not yet covered.
The companion narrative lives in `README.md`. This file is the machine-checked
half: the conformance harness loads SIM.md through the public facade only and
fails closed when a claim named here is no longer described, so the document and
the executable checks cannot silently drift apart.
## What SIM is
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 fixed:
```text
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, optimizers, checkers, evaluators, wasm adapters,
dynamic loaders, and the standard language surface.
## The conformance suite
`sim-conformance` is a test-only crate that depends on `sim` through the public
facade only (`default-features = false` plus an explicit feature set). It turns
the runtime's architecture claims into executable checks. It exercises behavior,
not source text: every assertion drives the facade or the runtime and observes a
result. The only document it reads is this file, to keep the claim list honest.
## Kernel-contract claims the suite verifies
The suite protects the checkable architecture claims below. A regression in any
of them fails the suite, and every new current architecture claim gets a matching
conformance assertion.
- **codec totality** over the shared `Expr` graph: every general-purpose codec
round-trips every `Expr` variant and quote mode semantically.
- **class semantics**: every registered class exposes the callable class
protocol and constructs instances through the facade.
- **number-domain replaceability**: the number domains named by the runtime
parse their literals and promote through the published lattice.
- **capability gating**: read-eval and read-construct are gated separately by
capability and trust level.
- **eval policy**: the named eval policies (eager, lazy, lazy-by-need,
strict-by-shape, hybrid) are present and selectable.
- **loader behavior**: the loader backends named by the runtime accept their
source kinds (binary, lisp source, native dylib, and wasm).
- **reversible library lifecycle**: load/unload/reload produce observable,
equal registry snapshots, and dependents refuse or cascade in order.
- **boot receipt replay**: boot receipts encode, decode, and replay to an equal
state.
- the **wasm ABI scope**: wasm ABI v1 executes functions and marks richer
exports (class, codec, shape, number-domain) explicitly unsupported.
- **stream transport conformance**: streams record, replay, and bridge across
the transport layers with explicit skip diagnostics for unsupported pairs.
## Conformance matrices
The library lifecycle conformance matrix lives at
`crates/sim-conformance/tests/spec/lib_lifecycle.rs`.
The stream conformance matrix lives at
`crates/sim-conformance/tests/spec/stream_matrix.rs`. It covers L0 through L7
with PCM, MIDI, diagnostics, data, cancel, done, overflow, timeout, reconnect,
and refused-profile fixtures.
The placement conformance matrix lives at
`crates/sim-conformance/tests/spec/placement.rs`. It covers single-site,
multi-thread, and multi-process deterministic placement with golden report and
audio hashes.
## Stream cassette publishability
Stream cassettes carry a `to_expr`/`from_expr` serialization that round-trips
through any general-purpose codec. The suite guards that round-trip in memory and
validates the structural invariants a cassette must satisfy before it could be
published as a golden fixture (finite trace, sequenced envelopes, replay- or
preview-only transport, and no unredacted payload or host-device name). These are
in-memory invariant checks, not comparisons against a committed `.simcassette`
corpus on disk.
## Surfaces covered versus not covered
Covered by executable conformance in this suite, with the listed feature set on:
- the kernel codec, class, number, capability, eval-policy, loader, lifecycle,
and wasm-ABI contracts;
- the stream-core, stream-combinators, stream-fabric, stream-file, stream-host,
and web-bridge transport surfaces;
- the topology placement surface and the CLI boot surface.
Linted as offline, deterministic recipe corpora (not full runtime replays): the
`30-agents` and `40-atelier` recipe sets, whose `(quote ...)` setup forms are
decoded and evaluated through the lisp codec and compared to their expected
forms.
Not yet covered by executable conformance here (their features are off by
default in this suite, tracked separately): the agents, MCP, music, audio-FEMM,
logic, and discrete surfaces. Their absence is intentional and named so the suite
does not over-claim coverage it does not have.