sim-shape

sim-shape is a package in the SIM constellation. The kernel owns the open Shape protocol; this crate supplies the concrete shapes and the one shared match, bind, and dispatch engine built on it. A shape both checks an expression or value and reports what it captured, so the same engine serves parsing, checking, binding, dispatch, codec grammar, lambda locals, and overload selection.

The engine spans atomic shapes and their combinators and object-grammar parsers (primitives), boolean and collection algebra (algebra), comparison and subsumption reasoning (compare), citizen integration that registers shapes as constructible objects (citizen), the callable shape object with overload selection (functions), and match-extension hooks (hooks).

Crates

sim-shape -- concrete Shape implementations and the shared match, bind, and dispatch engine: primitive shapes, shape algebra, comparison and subsumption, citizen integration, callable shape objects, and match hooks.

Validation

These commands run in the constellation workspace; only sim-kernel builds from a lone clone today (see DEVELOPING.md in sim-sdk). A single-repo build lands with the first crates.io publish.

cargo fmt --check && cargo test --workspace && cargo clippy --workspace -- -D warnings && cargo doc --workspace --no-deps
cargo run -p xtask -- simdoc --check

Documentation Lanes

cargo run -p xtask -- simdoc builds the public documentation lanes:

API docs: target/doc/
Agent cards: docs/agents/cards.jsonl and docs/agents/card-index.json
Human docs: docs/humans/
Diagrams: docs/diagrams/src/ and docs/diagrams/generated/

The same command writes split contract files under docs/generated/. Everything under docs/ is generated; do not hand-edit it.

Rustdoc conventions

Public API documentation in src/ follows one house style:

Every public item opens with a one-line summary sentence, then context.
The kernel defines the Shape protocol; this crate implements it as the one shared engine, so each surface (primitives, algebra, compare, citizen, functions, hooks) is framed by its role in that engine.
The first-reach types carry a # Examples doctest that compiles and passes.
Cross-reference with intra-doc links, and link back to this README rather than restating it.

The public API is documentation-gated: lib.rs denies missing_docs, so every public item, field, and variant must be documented for the crate to build.

Examples and recipes