EriX Pager Service (pagerd)

pagerd is the user-space paging/backing policy service. It provides page content and page-fault resolution policy for managed mappings.

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 pager service daemon. Its purpose in EriX is to provide the pager service role through explicit IPC and startup authority.

Functionally, it implements the daemon runtime, state model, IPC handling, and validation tests. The repository keeps the implementation, interface contracts, tests, and documentation for that behavior in one reviewable ownership boundary.

The maintained responsibilities are:

• implement the pager service runtime and state model
• validate startup authority before accepting IPC requests
• retain required peer-call and reply buffers through authoritative completion on the assigned endpoint set
• keep service behavior, tests, and authority invariants documented

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.

Implementation Status

Runtime baseline:

• no_std executable service binary (x86_64-unknown-none) with SysV entry ABI
• startup envelope parsing/validation via lib-bootstrap
• role/intake contract validation via lib-capabi
• runtime IPC server loop with distinct ingress endpoints for framed process-VSpace registration calls and unframed kernel fault notifications
• the public registration endpoint never accepts raw fault traffic, while the receive-only fault endpoint never interprets bytes as a caller request
• root's dedicated pager-control source SLOT_KERNEL_PAGER_ENDPOINT (2256) is copied into pagerd's role-local primary-control slot 206; the separate fault-delivery receive slot is 196
• executable mappings are materialized before process start; pagerd receives no generic image frame and resolves only registered anonymous demand-zero faults through memd
• each registration declares read-only or read-write, non-executable mapping rights; each kernel notification carries exactly one semantic access, and a fault outside the registered range or rights is terminated without backing
• process-vspace registration uses an exact startup-delegated binding slice sized by the deployment's managed-process record count; its local import window is validated against the capability-space ABI
• memd and vspaced are reached only through capabilities transferred into pagerd-local slots; the service performs no ambient name lookup or in-band startup logging from its fault-critical loop
• outgoing IPC calls encode the request extent in the message header while advertising the full writable buffer to the syscall, so larger typed replies and capability-transfer tables cannot be truncated to request size
• runtime transport uses the canonical 8 KiB IPC capacity; startup waits for its one required handoff without a service-local deadline, while the security-separated registration and fault endpoints are probed fairly without imposing an arbitrary per-endpoint latency; a registration probe reporting BUSY enters the kernel-required blocking rendezvous because that status proves a transfer-bearing caller is already waiting
• memd allocation replies must carry exactly one normalized FRAME receipt naming the dedicated anonymous-frame import slot with exactly the rights requested for that process (READ | MAP or READ | WRITE | MAP); pagerd validates that receipt and the installed local capability before use
• each allocation request asks the kernel-backed allocator for exactly the registered mapping rights plus MAP; pagerd never selects or forwards a physical address
• pagerd attenuates the transient anonymous frame to the registered mapping permissions plus MAP when forwarding it to vspaced; the reply from vspaced must match the active request and must not return authority
• nonzero service-owned downstream request identifiers correlate allocation and mapping replies independently of kernel fault identifiers

Authority cleanup status:

• pagerd accepts explicit register/unregister process-vspace requests from procd and rootd in disjoint canonical destination-slot partitions; its deployment arena covers the combined bounded pool
• an exact duplicate registration is idempotent, while policy drift or a cross-process destination collision retires the ambiguous alias and forces a fail-stop instead of retaining state that names an empty or replaced slot
• the unused public fault-resolution request/response is absent; ordinary service callers cannot ask pagerd to forward caller-selected resolution data to the kernel
• process-vspace registration remains a framed CALL path on the public registration endpoint; raw fixed-size fault notifications are accepted only on the separate receive-only fault-delivery endpoint
• runtime fault resolution maps through the registered delegated VSPACE cap, not by treating process_id as ambient VSPACE authority
• downstream vspaced map requests carry the explicit map operation and no compatibility process metadata or padding
• the anonymous runtime map path uses that compact request shape and does not reintroduce an ignored flag or compatibility process selector
• the registration contract carries only the process-specific anonymous range and non-executable page rights that pagerd is authorized to back
• the registered process-vspace table consumes only its deployment-sized state slice and the delegated child VSPACE aliases supplied by procd; it does not infer VSPACE authority from process identifiers or slot conventions
• each anonymous frame arrives in one explicit pager-local import slot under an exact normalized receipt; after transferring only the rights needed by the registered mapping to vspaced, pagerd drops that transient copy while the process VSpace owns the live mapping until teardown
• the kernel installs capability transfers only inside pagerd's CSpace window and preserves normalized receipt descriptors containing the actual installed rights; register requires exactly one matching VSPACE receipt and unregister requires none
• malformed or extra authority in downstream replies is cleaned before the fault is rejected; a cleanup failure exits pagerd so process teardown revokes any authority whose receipt could not be trusted
• every registration call accounts for the exact normalized receipt destinations installed by the kernel; unexpected or malformed receipts are dropped, while framing that cannot prove which destinations were installed causes pagerd to exit so kernel process teardown revokes the complete local CSpace
• valid registration calls do not scan the deployment-sized VSPACE import window; exact receipts and registered bindings are the authoritative inventory, avoiding work proportional to the managed-process capacity

Dynamic Boot Artifact Evidence

The image build packages pagerd as an ELF64 x86_64 ET_DYN executable with .erix_dynlink metadata in the signed dynlink-store and mirrors it under /lib/erix/dynlink with its required shared objects.

Startup remains rootd/kernel process-control before procd is available; authority remains the explicit pager endpoint and startup transfer set. Dynamic packaging and filesystem mirror records are evidence and launch inputs only; they do not grant filesystem, loader, object-store, service-discovery, provider-bypass, block-device, or dynlinkd authority. pagerd receives only the documented startup endpoints, peers, and capabilities for its role.

Governance Principles

pagerd governance is scoped to pager service behavior and fault-response policy.

The scoped governance rules are:

• It responds only to paging authority assigned by startup contracts.
• It keeps fault handling deterministic and bounded by process memory policy.
• It validates page requests before mapping or backing memory.
• It does not receive unrelated device, filesystem, or service-discovery authority.

Authority Boundaries

• pagerd operates only through startup-assigned service capabilities.
• New authority must be represented in bootstrap/capability validation and integration tests before use.

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.