Crate sim_citizen

Expand description

Citizen support outside the SIM kernel.

A citizen is a public SIM-facing runtime value with a class-backed read constructor, constructor encoding, conformance fixture, and census row. Domain values usually opt in with #[derive(Citizen)]; hard cases may register hand-written citizens, and live handles carry inline #[non_citizen(reason = "...", kind = "...", descriptor = "...")] exemptions that name their descriptor strategy.

This crate owns only the shared support layer: registry rows, runtime installation helpers, fixture checks, generated census rendering, and the semantic equality helpers used by the strict citizen gate. Read-construct remains capability-gated by the codec/runtime path, not by this crate.

§Surface

Conformance fixtures check a citizen’s read-construct round trip; the field and equality traits encode citizen fields and back the strict semantic equality gate; the registry and runtime helpers install citizens into a library and a context; the card and census helpers render browse and census output for both citizens and explicit non-citizen exemptions; and a reference citizen value is provided as an example.

§Explicit registration

Inventory-backed discovery is convenient for normal host binaries. Strict release, LTO, and wasm checks can instead build a CitizenRegistry by calling CitizenRegistry::register for each expected citizen type, load that registry as a kernel library, and call run_registry_conformance_expecting. The expected-symbol guard reports a missing row instead of letting a shorter registry pass.

Re-exports§

pub use ::inventory;

Structs§

CitizenInfo: One inventory-registered citizen’s static registry row.
CitizenLib: A kernel Lib that loads registered citizens into a context.
CitizenRegistry: An explicit citizen registry built by naming the citizen types a crate owns.
NonCitizenInfo: One inventory-registered explicit non-citizen exemption.

Traits§

Citizen: Static citizen identity: the metadata #[derive(Citizen)] supplies.
CitizenEq: Semantic equality between citizen field values for the strict gate.
CitizenField: Encodes and decodes a Rust type as one citizen constructor field.
CitizenRuntime: A fully runnable citizen: identity plus kernel object and read-construct.

Functions§

arity_error: Builds the standard error for a wrong read-constructor argument count.
check_default_fixture: Checks the citizen’s default CitizenRuntime::example fixture round trip.
check_fixture: Checks one runtime fixture’s read-construct round trip and failure paths.
check_value_fixture: Checks an already-built citizen Value’s read-construct round trip.
check_value_fixture_with_wrong_version: Asserts the full citizen read-construct contract for one value.
citizen_card: Builds the browse Card record for one registered citizen.
citizen_census_markdown: Renders the full census of inventory-registered citizens as Markdown.
citizen_registry_census_markdown: Renders the supplied explicit registry’s citizens as Markdown.
constructor_expr: Encodes a citizen value as its read-construct Expr extension form.
decode_version: Checks that a citizen’s version argument equals the expected version.
expr_citizen_eq: Compares two Exprs under citizen equality.
field_error: Builds a citizen field <field>: <message> evaluation error.
install_all: Installs every registered citizen’s class into linker.
install_derived: Installs a derived citizen T as a class value in linker.
install_namespace: Installs only the registered citizens whose symbol is in namespace.
non_citizen_card: Builds the browse Card record (a core table) for one non-citizen exemption.
non_citizen_census_markdown: Renders the full census of inventory-registered non-citizen exemptions as Markdown.
parse_symbol: Parses namespace/name text into a kernel Symbol.
registered_citizens: Iterates every CitizenInfo registered through inventory.
registered_non_citizens: Iterates every NonCitizenInfo registered through inventory.
render_citizen_census: Renders the supplied citizen rows as a generated Markdown census table.
render_non_citizen_census: Renders the supplied non-citizen exemption rows as a generated Markdown census table.
run_registered_conformance: Loads every registered citizen and runs each citizen’s conformance fixture.
run_registered_conformance_expecting: Runs inventory-backed conformance after checking expected symbols.
run_registry_conformance: Loads an explicit registry and runs each row’s conformance fixture.
run_registry_conformance_expecting: Runs explicit-registry conformance after checking expected symbols.
text_read_construct_expr: Builds the citizen/read-construct Expr for a v1 text citizen form.
value_from_expr: Builds a runtime Value from an Expr using cx’s factory.
value_to_expr: Projects a runtime Value to an Expr, tagging errors with field.
values_citizen_eq: Compares two citizen Values for semantic equality.

Type Aliases§

InstallFn: Installs a citizen’s class into a kernel Linker.