Crate sim_run_core

Expand description

Core command entry API for the SIM bootloader.

§Bootloader frame

The shipped sim binary is a bootloader frame, not a batteries-included runtime. run builds a LoadSession whose only registered loader is the in-process LoadSession::add_host_factory host loader: with no host factory and no injected artifact loader it can boot no codec and no library, so run(["sim", "run"]) fails with no codec 'lisp' available. This is by design: behavior lives in loadable libraries, not baked into the frame. The default frame loads a codec when an explicit source, cache artifact, registry resolver, or host factory supplies it.

A working session therefore comes from one of:

an explicitly provided source: --load path/to/artifact.simlib (needs an artifact loader registered via LoadSession::with_loader), or
a seeded cache resolved by the cache-only CratesIoResolver (it never reaches the network unless an explicit registry resolver is installed; the cache must otherwise already hold the artifact), or
a host factory registered through LoadSession::with_host_factory and driven via run_with_session – the path every functional test uses.

The registry feature adds a git registry artifact resolver, but it is active only when the host installs it. Nothing here bakes in a codec.

Modules§

device_options: Reusable route option models for device product verbs.

Structs§

AdapterTick: One scheduled adapter-loop tick.
Bootloader: A thin bootloader over LoadSession for a single-library product binary.
CliBoot: Parsed bootloader controls and payload data.
CliEntrypoint: A loaded function that owns command-line execution.
CliEnvelope: Data envelope supplied to the selected loaded-lib entrypoint.
CliError: Command-line error returned by the bootloader core.
ConfigLoadOptions: Source-selection options for runtime configuration discovery.
ConfigReportRequest: Request selected by the sim config ... CLI surface.
ConfigSourceReport: One config source and its discovery status.
CratesIoResolver: crates.io-style artifact resolver owned by the CLI layer.
CratesIoSpec: A parsed crates.io:NAME@REQ source.
DeviceAdapterLoopPlan: Pacing plan for a composed device adapter loop.
DeviceEdgeSession: Composed device host session returned to per-device verbs.
DeviceHostSpec: Input required to compose a device host session.
DevicePlacement: Placement plan for a device surface encoder and adapter pair.
DeviceProfile: Stream-facing profile advertised by a composed device route.
DeviceSite: Export-record-style descriptor for a device route site.
DeviceSurfaceHubJoin: Surface-hub join plan produced by device host composition.
LoadReceipt: Receipt for one library loaded by the bootloader.
LoadSession: Kernel-backed loader session used by the command entry API.
LoadedLibReport: One loaded library as it appears in a boot session report.
LoadedStateReport: Loaded-state report built from one LoadSession.
Payload: Payload preserved for loaded-lib behavior.
ResolvedCratesIoSource: A crates.io source resolved to a local artifact path.
RouteArg: Route selected by a product verb before device host composition.
RuntimeConfigState: Configuration layers discovered during a boot session.
StubProvider: Hardware-free provider used when no concrete device provider is installed.
StubSession: Hardware-free session used by headless device composition.
VersionReq: Version requirement syntax accepted by the CLI crates.io resolver.

Enums§

CliCommand: Top-level command selected by the bootloader parser.
ConfigReportKind: Config report variants supported by the bootloader.
DeviceConsentPolicy: Consent policy carried by device verbs into host composition.
DeviceHostStalePolicy: Policy applied when a device sample or rendered frame becomes stale.
DevicePlacementError: Device placement validation error.
DeviceProviderKind: Provider source selected during device host composition.
DeviceRateClass: Coarse rate class for pacing the device adapter loop.
DeviceSiteLocality: Placement locality advertised by a device site.
LibSourceSpec: Library source syntax accepted by the command line.
LoadReceiptRole: The role a loaded library serves in a boot session.
SourceStatus: Discovery status for one config source.

Constants§

CLI_MAIN_ENTRYPOINT: Symbol prefix a loaded lib claims to own command-line execution.
DEFAULT_CODEC_NAME: Codec name used when --codec is omitted.

Traits§

DeviceProvider: Provider that opens one composed device session.
DeviceSession: Open device session used by a composed route.

Functions§

boot_codec_name: Returns the selected codec name for a boot session.
cli_envelope_args: Extracts the UTF-8 payload arguments from a generic CLI envelope value.
cli_main_entrypoint_symbol: Builds the qualified cli/main/NAME entrypoint symbol for a named lib.
codec_lib_symbol: Returns the library symbol for a codec name.
compose_device_host: Composes a device host session using a hardware-free stub provider.
compose_device_host_with_provider: Composes a device host session using a supplied provider instance.
derive_device_rate_class: Derives the adapter-loop rate class from stream-facing device metadata.
format_config_sources: Renders a text config-source report.
format_config_sources_json: Renders a stable JSON config-source report.
format_config_status: Renders a text status report.
format_config_status_json: Renders a stable JSON status report.
format_effective_config: Renders one effective config table as config text.
format_effective_config_json: Renders one effective config table as stable JSON.
install_device_bases: Installs the base device boot requirements into an existing context.
load_config_sources: Loads config layers from files and site exports.
load_config_sources_with_probes: Loads config layers from probes, files, and site exports.
parse_args: Parses the minimal bootloader flags.
render_config_report: Renders the selected config report.
run: Runs the command entry API with process arguments.
run_command_with_session: Runs an already-parsed command with an injected loader session.
run_config_probe: Executes one config probe, applying any emitted layer and recording its report.
run_with_session: Runs the command entry API with an injected loader session.
version_line: Returns the version line printed by sim --version.