Module surface 

Surface-pack card libs and idempotent install.

~92 crates hand-write an impl Lib that exports a set of value cards (tables with fields like symbol, layer, kind, role, …) and ~49 guard install with registry().lib(&id).is_some(). This is their shared substrate: declare the cards as data (SurfacePackSpec) and install once with install_once.

How to write a SIM lib

A host-registered SIM lib should keep its crate entrypoint thin, put the implementation in a focused runtime module, and expose one public install function named install_<crate>_lib after stripping the sim-lib- prefix and replacing hyphens with underscores. The install function should call install_once rather than hand-checking registry().lib(...), unless the crate is a documented aggregate or lower-layer exception in scripts/check-libs.sh.

Lib::manifest should use Version(env!("CARGO_PKG_VERSION").to_owned()), LibTarget::HostRegistered, explicit Export records for every registered class/function/value/codec/number-domain surface, and only the capabilities the lib itself requires at load time. Lib::load owns the actual linker registration and should avoid hidden global mutation beyond the registered runtime surface.

If the lib publishes value cards, prefer SurfacePackLib and SurfacePackSpec over hand-written card registration. If the lib ships recipes, keep the pure recipe data in sim-cookbook inputs and register the runtime projection from the higher-level lib. If it introduces object values, either derive/provide citizen read constructors or add an explicit #[non_citizen] exemption that names the descriptor strategy.

Structs

SurfacePackLib

A host-registered lib built from a SurfacePackSpec.

SurfacePackSpec

A pack of value cards exported by one host-registered lib.

SurfaceValueSpec

One exported value card: its symbol and its table fields.

Enums

SurfaceField

A typed card field value.

Functions

card_expr

Build the browse card map (an Expr) for one value spec – the shared core of the many hand-written *_card_expr builders. This is the Expr (data) counterpart of the Value card that SurfacePackLib registers.

install_once

Install lib only if its id is not already registered. Returns true if it was loaded, false if it was already present. Replaces the registry().lib(&id).is_some() early-return guard.

install_once_id

Install lib only if absent, returning the newly loaded id when it loads.

installed_lib_id

Return the loaded id for lib, if it is already registered.