lib-block

lib-block is the canonical no-std block IPC and client crate for the storage stack. Block services, drivers, filesystem providers, and root orchestration share its exact wire views and explicit-authority transport helpers.

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 block library. Its purpose in EriX is to provide reusable block primitives and contracts to EriX components.

Functionally, it exposes the block 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-block crate API for block 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.

Validation

• cargo test
• cargo fmt
• strict clippy with warnings denied

Governance Principles

lib-block governance is scoped to reusable block-device 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-block 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.
• Filesystem providers share one BlockDevice abstraction and BlockClient; retained transport remains explicit through caller-supplied IPC/yield callbacks, call-message storage, transfer storage, and endpoint slot. It retries transient pre-acceptance backpressure without an arbitrary local ceiling and retains delegated message storage after acceptance until the authoritative reply arrives.
• Read and write payloads use exact borrowed slices instead of padded, library-sized arrays. BlockClient divides a logical operation only where its caller-owned transfer slice or the canonical kernel transport envelope requires another message. No full-envelope request or response buffer is hidden on the caller's stack. Each read borrows only its exact response header plus checked fragment bytes: a 512-byte metadata read needs a 592-byte IPC call capacity, while full data fragments retain the existing transport bound.
• Enumeration carries independent full-width provider and provider-private namespace cursors. The library does not pack either cursor into a smaller integer domain or impose a provider-count or namespace-size policy.
• BlockDevice::read_partition_info resolves an explicitly selected partition under an already identified parent. BlockClient streams the block namespace until that selector is found, so callers do not persist opaque runtime device IDs or inherit a local enumeration ceiling.

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.