lib-bootstrap

lib-bootstrap is the allocation-free Rust owner of EriX's root-to-service startup envelope, boot configuration, service payload, and runtime capability inventory contracts.

EriX is a clean-room, capability-based microkernel operating system written entirely in Rust.

Technical requirements are tracked in the EriX requirements, conventions, and project documentation.

See:

• docs for design documents and the normative root-to-service handoff specification
• lib-capabi for capability transfer records and endpoint policy
• lib-ipc for canonical readiness report identifiers and optional IPC framing

Purpose of This Repository

The crate centralizes the byte and validation contracts shared by rootd and the services it launches. It exposes:

• a canonical 112-byte root-to-service envelope
• the fixed service bootstrap payload and role registry
• canonical descriptive executable-name selectors for the exact signed boot-store role set; post-mount and extension roles remain unmapped
• capability-transfer parsing and in-place role validation through lib-capabi, with malformed-table and role-policy failures kept distinct
• count-derived boot-configuration entry and dependency tables, filesystem metadata, offset-backed mount rows, and role-bound post-mount filesystem launch rows
• a loader-private startup tail carrying the authenticated SHA-256 digest and canonical VFS path of the packaged runtime graph
• a ttyd-private TTY1 startup tail carrying deployment-selected session, PTY, renderer byte/record, trusted-chrome byte/record, descriptive grant-view, distinct PTY input, canonical-line and output byte, event, cleanup, and initial-dimension capacities without defining protocol maxima
• version-two TTY1 adds independent framebuffer/serial terminal selection and optional mirroring, without selecting logd stamp routes. Its 96-byte layout retains storage offsets, uses flags at byte 88, and rejects unknown bits; canonical version one explicitly means both terminal paths mirrored
• launchd-private LCH1 and powerboxd-private PBX1 startup tails carrying authenticated deployment storage for transactions, manifests, selectors, grants, trusted prompts, replies, retryable authority cleanup, and one exact architecture-bounded transient capability-slot range without defining private protocol maxima; version-2 LCH1 reserves twelve disjoint capability slots per job for control, status, script, and resolver pairs plus a creator/source/receiver job broker and its held runtime cwd scope, two slots per authenticated launch-stream pair, and a nonempty tail for launch-intake receipts
• an authenticated FSL1 BootConfig tail that binds each admitted v1 post-mount service role to its canonical runtime-graph path and complete role-private policy: ttyd/TTY1, launchd/LCH1, or powerboxd/PBX1; rows contain no executable bytes or launch authority. The private RTC role is a deviced-driver node and is not an FSL1 row.
• canonical runtime role identities for launchd, powerboxd, drv-rtc-cmos, exsh, coreutils, and extop; recognizing these post-mount roles does not place their executables or service entries in the boot image
• the exact product seriald/fbcond readiness-marker set, exact borrowed-text membership, and an authority-free transport disposition derived only from report stage, build-mode facts, and endpoint presence; callers retain every logging route and capability
• private keyd material rows containing only kind, length, identifier, and material, plus e2fsd external-journal payload tails that select a same-disk GPT partition rather than persisting a runtime-generated device ID
• startup status values and checked range helpers
• distinct signed loader validation profiles for filesystem discovery, materialized-launch isolation, and cleanup-authority confinement; these values carry scenario selection only and grant no loader or process authority
• distinct signed input-readiness and multi-block-provider validation profiles; they replace build-feature discrimination while carrying no input, storage, or provider authority
• TRT1 and RTC1 private startup tails binding timed's sole RTC receiver and the CMOS driver's exact narrow-I/O and send-only provider slots. Deviced constructs the RTC1 child tail after exact loader materialization; it is not BootConfig filesystem metadata. Fixed ports are validated evidence.
• kind-aware runtime inventory validation has an explicit payload-tail variant; ordinary callers still reject every trailing byte, while private services must parse their complete versioned tail themselves
• runtime inventory validation through caller-provided capability queries
• optional parsing from a checked lib-ipc frame

Envelope validation rejects unknown identity/version/flags, non-zero reserved fields, invalid role values, size mismatches, and noncanonical payload placement. The payload begins immediately after the header and consumes the rest of the declared message; its transfer table precedes role-specific bytes. The obsolete alternate interpretation of that table as capability-intake policy has been removed.

BootConfig uses BOOTCFG_ENTRY_FLAG_PUBLISH_IN_NAMED to request publication after a declared service becomes ready. The flag grants no authority and does not authorize service-side self-registration; rootd must already hold the target-specific publication route defined by the capability ABI. Entries are emitted in canonical topological launch order and name dependencies through a separate contiguous role table. Key material, external-journal mappings, mount declarations, and post-mount filesystem launches are optional ordered tables whose row counts come from their encoded storage. Every filesystem launch entry binds one role-matching row in order, with no unused or aliased row. Provider identifiers have no library-wide ceiling. Borrowed table views expose their exact validated encoding so a coordinator can forward role-private payloads without copying rows or inventing another capacity. Entry records carry no poll timeout; typed runtime completion, rather than boot-image policy, owns launch termination.

boot_store_executable_name_v1 maps only the 29 early service roles admitted to the signed boot store. Its returned bytes select a manifest entry; they do not confer module access, executable mapping, process creation, or capability transfer authority. Filesystem-launched roles and extensions return None.

The six PHASE5_*_SERVICE_ROLES_V1 catalogs are the sole authority-free membership and ordering contract for all 33 Phase 5 bootstrap services: Foundation, Core, Hardware, MountRoot storage, the pre-staged StartRuntime pair, and its ext4-launched suffix. phase5_service_phase_v1 classifies only those roles. It rejects ordinary programs, extensions, and unknown values and does not authorize launch or capability transfer.

The five PHASE5_*_SERVICE_LAUNCHES_V1 catalogs bind all 33 bootstrap roles to their canonical readiness report and signed BootConfig launch owner. The Foundation, Core, Hardware, MountRoot, and combined StartRuntime arrays preserve the semantic launch order, including the pre-staged pair before four ext4 rows. phase5_service_launch_v1 rejects every ordinary-program, extension, and unknown role; the narrower early lookup still excludes storage and post-mount roles. The shared rows are descriptive input validation: they cannot invoke rootd, deviced, loaderd, dynlinkd, or a process service and cannot carry capability authority.

rootd_product_ready_marker_v1 and rootd_product_ready_stamp_disposition_v1 own the closed product readiness policy for seriald and fbcond. Their returned strings and booleans are descriptive instructions only. They contain no endpoint slot, request identity, buffer, retry state, or logging authority, and Integration may extend the marker set only inside its build-gated policy library.

The library carries capability-slot metadata but performs no capability operation. rootd installs authority; each service queries its own local inventory and uses this crate to compare the observed capability type, rights, source slot, destination slot, and endpoint kind with the declared transfer bundle.

Clean-Room Policy

EriX follows a strict clean-room philosophy:

• No external source code may be copied.
• No external Rust crates are allowed.
• No code generation tools that embed third-party code.
• All code must be authored within the project.

Violations will result in rejection of the contribution.

License

All EriX repositories are licensed under the ISC License.

Development Model

EriX development is modular, deterministic, reproducible, authority-explicit, security-first, and self-hosting oriented.

Repository validation requires:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
RUSTFLAGS="-D warnings" cargo test --all-targets --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
RUSTFLAGS="-D warnings" cargo build --target x86_64-unknown-none --all-features

The crate is no_std, denies unsafe code and missing public documentation, and uses only EriX-owned dependencies pinned by full 40-character commit rev values.

Governance Principles

lib-bootstrap governance is limited to shared startup representation and structural or observed-inventory validation:

• Every externally supplied offset, size, count, enum, flag, and reserved field is checked before use.
• Wire constants are explicit; host Rust layout does not define encoded size.
• TTY1 capacities come only from authenticated startup bytes. Renderer, trusted chrome, descriptive grant-view rows, PTY input, canonical-line, and PTY output bytes are distinct pools. The former word at byte 60 now sizes the grant-view mirror but conveys no grant authority. Empty storage, a PTY capacity smaller than the session capacity, or a PTY pool unable to give every configured PTY a nonempty extent fails before service state exists; larger values face no private library ceiling.
• LCH1 and PBX1 capacities also come only from authenticated startup bytes. Every required pool is nonempty, reserved bytes are zero, and the records carry neither capabilities nor local policy defaults.
• FSL1 rows are canonical path-plus-policy declarations. They neither embed an executable nor authorize filesystem lookup, process creation, capability installation, or start.
• Startup authority is accepted only through explicit transfer descriptors and caller-provided local capability queries.
• The library performs no I/O, allocation, discovery, launch, cleanup, or lifecycle action.
• The fixed Phase 5 signed-entry order and launch-owner classification are descriptive library contracts. Actual launch scheduling, restart policy, capability delegation, and service behavior remain with callers.
• Pre-release contracts do not preserve dead aliases, duplicate interpretations, or unused compatibility fields.

Library Boundaries

BootConfig and runtime capability inventory validation traverse caller-provided encoded tables in place, so their capacity is the encoded input and wire count rather than private scratch arrays. Mount and filesystem-launch paths use offset/length ranges while retaining the VFS transport's semantic path-width limit. Filesystem-launch policy bytes immediately follow their path, so gaps, aliases, and unreferenced configuration are rejected. Key rows retain the key service's semantic per-material byte width, but their row count is count-derived. The fixed-width TTY1, version-2 LCH1, and PBX1 records describe caller-provided runtime storage; they do not allocate that storage, carry capabilities, or turn their numeric values into authority. The LCH1 stream capacity is an exact storage/CSpace partition input, not permission to create an endpoint without launchd's separately delegated factory route.

Contact

Development occurs in the EriX organization. Decisions require documented rationale in issues or design documents.

Maintainers can be reached at admin@erikinkinen.fi.