lib-bootstrap

lib-bootstrap defines shared bootstrap startup contracts for root task and early critical services.

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, specifications, and development plans.
• Related architecture repositories for kernel, services, libraries, drivers, and integration tooling.

Purpose of This Repository

This repository implements the EriX bootstrap library. Its purpose in EriX is to provide reusable bootstrap primitives and contracts to EriX components.

Functionally, it exposes the bootstrap APIs, validation tests, and documentation used by dependent repositories. The repository keeps the implementation, interface contracts, tests, and documentation for that behavior in one reviewable ownership boundary.

The maintained responsibilities are:

• expose the lib-bootstrap crate API for bootstrap behavior used by dependent components
• keep data formats, constants, and validation helpers documented and tested
• preserve clean-room, no-external-crate implementation boundaries
• maintain compatibility expectations for downstream repositories

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.

This repository follows the project roadmap and the validation rules documented in its own roadmap.

Status

Implemented baseline.

Current crate includes RootServiceStartEnvelopeV1, split-role constants for memd/vspaced/pagerd/procd, strict parse/validation helpers, optional IPC framing integration, BootConfig parse/encode/validate helpers (including validation_profile=none for runtime images), fixture-based tests, and startup-payload semantics where primary_control_slot is a role-scoped primary control slot that may be zero for roles with no direct control-plane endpoint, plus a shared runtime inventory validator that lets zero-control-slot services confirm actual local slot type/rights through caller-provided local query hooks.

The runtime inventory layer now also has a kind-aware validator for roles that do receive primary_control_slot: the caller-provided query hook must confirm endpoint type, required rights, and the exact expected endpoint kind published by lib-capabi, so startup fails closed when a role is handed the wrong control surface.

The published role registry now also includes the phase-4 storage pair blockd and drv-virtio-block, allowing rootd, deviced, and integration tooling to encode mediated block bring-up without out-of-band role IDs.

Endpoint inventory validation is now also exact-slot for non-repeatable endpoint transfers. Shared startup validators reject undeclared peer endpoints, wrong destination slots, or wrong endpoint rights even when the older class and count totals would have matched.

That shared runtime inventory path now also consults lib-capabi's explicit endpoint policy for every delegated endpoint transfer, not only the primary control slot. If a startup bundle misroutes an auxiliary narrow endpoint from the wrong source slot or installs the wrong endpoint kind into a declared local slot, validation fails closed before the service trusts the received authority.

The current registry also covers the volatile filesystem bring-up contract: SERVICE_ROLE_VFSD, the SERVICE_ROLE_MEMORY_PROVIDER role for the in-memory provider, the BOOTCFG_FS_PROVIDER_KIND_MEMORY provider kind, the phase4-vfs-memory boot-config validation profile, and the additive rootd stage IDs for MEMORY_PROVIDER_READY, VFSD_READY, VFS_MOUNT_READY, and VFS_IO_READY.

Filesystem provider work extends the same contracts with SERVICE_ROLE_E2FSD, SERVICE_ROLE_FATD, SERVICE_ROLE_KEYD, boot-config minor metadata for private filesystem providers, key/trust descriptors, external ext journal device mappings, provider kind/index/mount flag validation, and a phase4-e2fs-fat validation profile. BootConfig minor version 2 adds the bounded MNT1 runtime mount table so boot images can declare ordered path/provider/device mount rows without changing fixed service entries. Provider and key rows must not request named publication.

The Phase 4.7 filesystem-discovery slice adds SERVICE_ROLE_LOADERD, the phase4-loader-fs-discovery boot-config validation profile, and the additive rootd stage ID for LOADERD_READY. loaderd is a peer-only service in this slice: its startup payload uses primary_control_slot = 0, and its filesystem authority comes from the explicit vfsd peer declared by lib-capabi.

The crate also defines private startup payload tails appended after fixed service bootstrap payloads. Existing service payload sizes and provider/VFS operations are unchanged; non-participating roles continue to require an exact fixed payload. keyd can validate a bounded KYD1 key/trust tail for explicit e2fsd authority, rootd can validate a bounded BootConfig MNT1 mount tail for runtime VFS policy, and e2fsd can validate a bounded EJRN external-journal mapping tail for provider-local journal devices.

Governance Principles

lib-bootstrap governance is scoped to reusable bootstrap contracts shared by dependent repositories.

The scoped governance rules are:

• It must expose narrow, documented APIs rather than component-specific policy.
• It keeps wire formats, constants, parsers, and validation helpers deterministic and testable.
• It preserves clean-room implementation boundaries and does not introduce external crate dependencies.
• Breaking API or format changes require coordinated updates in every dependent repository.

Library Boundaries

• lib-bootstrap carries no runtime authority by itself; authority is held by callers that use the library.
• The crate must not hide ambient I/O, allocation policy, or service discovery behind helper APIs.

Contact

Development occurs in EriX organization and discussions happen in issues and design documents.

No decisions are considered valid without documented rationale.

Maintainers can be reached via email: admin@erikinkinen.fi.