lib-handoff

lib-handoff is the allocation-free Rust owner of EriX's versioned bootloader-to-kernel and kernel-to-root byte layouts.

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 normative handoff specifications
• lib-bootstrap for the separate root-to-service startup protocol

Purpose of This Repository

This repository provides one implementation boundary for the byte contracts that cross EriX's first two boot transitions. It exposes:

• little-endian decoders for the two fixed headers
• checked table and range validation
• allocation-free iterators over memory, module, RAM allocator extent, framebuffer, and dynamic-catalog records
• a required boot-calibrated processor-clock frequency for explicit hardware-deadline conversion in the kernel
• constants for the encoded record sizes, identifiers, kinds, and flags
• the x86_64 recursive-page-table index shared by the bootloader and kernel

validate_blob rejects incompatible versions, size mismatches, native-width conversion failures, metadata that overlaps a header or another metadata range, malformed entry sizes, unknown record values, forbidden writable and executable segment combinations, a missing processor-clock frequency, and non-zero reserved fields. Semantic launch, memory-map, capability, and dependency-graph policy remains with the receiving component.

Direct Cargo consumers are bootloader, kernel, and rootd.

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 has no dependencies.

Governance Principles

lib-handoff governance is limited to shared boot-transition representation and structural validation:

• Wire sizes are explicit constants, not values derived from host layout.
• Every wire offset is checked before conversion to native indexing.
• Full validation covers every referenced descriptor before success.
• The crate performs no I/O, allocation, service discovery, or policy action.
• Root-to-service startup messages have one owner, lib-bootstrap; they are not duplicated here.
• Format changes require coordinated consumer updates. Pre-release formats do not retain unused compatibility fields or aliases.

Library Boundaries

lib-handoff carries metadata, including capability-slot identifiers, but holds no authority. Callers remain responsible for proving that metadata corresponds to installed capabilities and for enforcing boot policy.

Contact

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

Maintainers can be reached at admin@erikinkinen.fi.