lib-capabi

lib-capabi defines shared capability ABI primitives for EriX.

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

Functionally, it exposes the capability ABI 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-capabi crate API for capability ABI 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 slot/rights registries, descriptor types, validation helpers, split core service role constants (memd, vspaced, pagerd, procd), and default intake-spec tables for each core service role. It also exposes conservative role-policy helpers for whether a role currently requires a non-zero primary control slot during startup, including peer-only exceptions such as named, logd, crashd, seriald, inputd, and the PS/2 input translators. named's startup intake contract now explicitly requires RECV | GRANT on its local service endpoint, because lookup replies may materialize a resolved peer endpoint into a caller-selected slot. The capability-type registry now also includes CAP_TYPE_INSTALL_GRANT, whose allowed rights are GRANT | MINT, for staged child population through kernel-issued install grants. The v1 slot registry now also includes an extended startup-transfer range plus the dedicated procd driver-lifecycle endpoint slot (SLOT_PROCD_DRIVER_ENDPOINT = 2112) so procd and deviced can receive a second explicit endpoint cap without reusing canonical service slots. The phase4 private filesystem authority table now includes keyd and a canonical SLOT_E2FSD_LOCAL_KEYD_ENDPOINT_V1: e2fsd receives only its provider endpoint, provider-local blockd, and provider-local keyd, while fatd remains limited to its provider endpoint and provider-local blockd. The shared capability/type registry now also includes CAP_TYPE_DEVICE_FRAME for validated device MMIO frames, plus canonical roles and startup slots for the phase-4 storage stack (blockd, drv-virtio-block, and their dedicated block HAL / provider peers). deviced's reply-bearing public receive slots now also explicitly require GRANT where the service must return a materialized endpoint capability (seriald provider resolution and PS/2 driver reads), so reply transfers stay inside declared slot policy instead of depending on ambient reply authority. deviced's default intake policy in the current runtime slice is endpoint-only; it no longer advertises unused CNode/TCB/VSpace management intake. It also includes the dedicated timed kernel time-control endpoint slot (SLOT_KERNEL_TIME_ENDPOINT = 2128) so timed can receive a narrow primary control path instead of the ambient root endpoint, plus the dedicated irqd kernel IRQ-control endpoint slot (SLOT_KERNEL_IRQ_ENDPOINT = 2144) so irqd can receive interrupt-specific kernel authority without broad process or device-control access, plus the dedicated hotplugd kernel hotplug-control endpoint slot (SLOT_KERNEL_HOTPLUG_ENDPOINT = 2160) so hotplugd can wait on kernel hotplug events without broad root-endpoint authority, plus the dedicated platform-read endpoint slot (SLOT_KERNEL_PLATFORM_ENDPOINT = 2176) so probed and drv-acpi can access platform-read surfaces without the full root endpoint, plus the dedicated console/framebuffer endpoint slot (SLOT_KERNEL_CONSOLE_ENDPOINT = 2192) so fbcond can consume framebuffer and font surfaces without the broad root endpoint, plus the dedicated device-I/O endpoint slot (SLOT_KERNEL_DEVICE_IO_ENDPOINT = 2208) so drv-serial and drv-i8042 can access port-I/O and legacy-serial surfaces without the full root endpoint, plus the dedicated memory-control endpoint slot (SLOT_KERNEL_MEM_ENDPOINT = 2224) for memd, the dedicated vspace-control endpoint slot (SLOT_KERNEL_VSPACE_ENDPOINT = 2240) for vspaced, and the dedicated pager/fault-control endpoint slot (SLOT_KERNEL_PAGER_ENDPOINT = 2256) for pagerd, plus the dedicated kernel log/query endpoint slot (SLOT_KERNEL_LOG_ENDPOINT = 2272) so deviced can keep logging and local startup-cap validation on a narrow primary control path instead of receiving the broad root endpoint, plus the dedicated kernel process-control endpoint slot (SLOT_KERNEL_PROCESS_ENDPOINT = 2288) so procd can keep runtime process/capability lifecycle control on a bounded primary control path instead of carrying the broad root endpoint. procd's default intake policy is now endpoint-driven plus its explicit local image frame; it no longer advertises copied CNODE/TCB/VSPACE management intake. procd and pagerd also reserve the last local slot in their role stride as an explicit image-frame slot so spawn and fault-resolution flows no longer borrow the canonical boot-module-table slot ambiently. Those role-local control and driver endpoint slots are now the intended destination of explicit startup materialization: rootd installs rights-reduced local aliases into those slots rather than treating them as descriptor-only conventions. deviced's role-local slot registry also now reserves explicit narrow source slots so staged driver startup can install role-appropriate primary control caps without ambient access to the kernel root endpoint. That registry distinguishes dedicated PCI-config, ACPI-read, COM1-I/O, and i8042-I/O sources, with the older broad platform/device-I/O names retained only as compatibility aliases. The current deviced startup intake budget now allows all ten explicit send endpoints needed for the driver endpoint, named, logd, irqd, child-population, and the four narrow hardware source slots. loaderd remains peer-only: its intake now requires send-only vfsd and procd peers in canonical local slots so it can resolve files and hand validated plans to the process manager without receiving memory, VSPACE, provider, block, key, journal, or process-control authority.

lib-capabi now also publishes two fail-closed helper maps for centralized process authority:

• role_primary_control_source_slot_v1(role) returns the only approved source slot for that role's primary control endpoint
• role_expected_primary_control_endpoint_kind_v1(role) returns the required endpoint kind that local startup validation must confirm before trusting the received slot

These helpers eliminate per-repo fallback tables that silently substituted SLOT_ROOT_ENDPOINT or broad shared control endpoints when a role mapping was missing.

lib-capabi now also publishes role_expected_explicit_endpoint_kind_v1(role, dest_slot) plus centralized explicit endpoint-transfer tables that bind each non-repeatable delegated endpoint to its declared source slot, destination slot, rights, and, where needed, exact endpoint kind. Shared startup validators can therefore reject a cap that lands in the right local slot but came from the wrong source or carries the wrong kernel-control surface.

The canonical kernel->root v1 slot table now also treats the narrow runtime endpoint inventory as the required contract. The preinstalled procd driver, time, IRQ, hotplug, PCI-config, ACPI, console, COM1, i8042, memory, vspace, pager, log, process, and child-populate endpoints are required. The legacy SLOT_ROOT_ENDPOINT constant remains numerically reserved for source/ABI stability, but it is no longer part of the published kernel->root capability contract and MUST remain absent at runtime.

The current slot and intake registry also covers the filesystem slice: vfsd receives the public service endpoint contract plus explicit private provider startup peer slots selected by boot policy. Providers remain private roles with no named publication contract.

Filesystem provider work extends that policy to a bounded provider endpoint window for vfsd. The memory provider, e2fsd, and fatd are private providers; e2fsd receives only canonical blockd and keyd provider-local peer slots, fatd receives only canonical blockd, and vfsd receives send-only provider endpoints for the selected providers while rejecting extra authority through the shared intake validator.

The Phase 4.7 loader policy adds loaderd as a peer-only service role. It receives one service receive endpoint plus required send-only peer endpoints from public vfsd and procd into SLOT_LOADERD_LOCAL_VFSD_ENDPOINT_V1 and SLOT_LOADERD_LOCAL_PROCD_ENDPOINT_V1; no block, provider, key, journal, named, memory, VSPACE, or process-control authority is part of the default intake bundle.

New authority-centralization slots reserve:

• a shared transfer-source slot for the kernel CHILD_POPULATE endpoint
• a canonical local deviced slot that holds the delegated child-population endpoint instead of the broad process-control endpoint
• canonical deviced local source slots for PCI config, ACPI read, COM1 I/O, and i8042 I/O instead of one shared broad platform/device-I/O source
• canonical split public deviced endpoint slots for probed, drv-acpi, hotplugd, drv-serial, seriald, inputd, and the PS/2 translators, plus matching root-owned source slots and deviced-local receive slots; the child-launched driver peers (drv-acpi, drv-serial, and the PS/2 translators) retain SEND | RECV locally so deviced can re-delegate the narrowed send cap during staged launch, and phase3-input mode leaves room for the extra named materialization peer alongside logd and irqd
• exact endpoint-transfer policy for startup validation: endpoint caps must now land in their declared destination slot with their declared rights instead of matching a wildcard endpoint class/count rule
• exact source-slot and optional endpoint-kind policy for explicit endpoint transfers, so startup validation no longer accepts misrouted delegated peers or auxiliary narrow-control aliases that merely match endpoint type and rights

Governance Principles

lib-capabi governance is scoped to reusable capability ABI 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-capabi 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.