EriX Documentation Repository

docs stores the normative EriX design documents, project plans, manuals, and cross-repository architecture records.

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 documentation component. Its purpose in EriX is to keep project design, manual, and roadmap material authoritative across repositories.

Functionally, it records architecture, interface, manual, and roadmap decisions that other repositories reference. The repository keeps the implementation, interface contracts, tests, and documentation for that behavior in one reviewable ownership boundary.

The maintained responsibilities are:

• maintain system design, manual, milestone, and validation documentation
• describe architecture decisions and authority rules for implementers and reviewers
• keep cross-repository project documentation reviewable outside component code

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.

Legal

All documentation is ISC licensed unless otherwise specified.

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.

Governance Principles

docs governance is scoped to project-wide design, manual, milestone, and validation documentation.

The scoped governance rules are:

• Documentation must describe implemented behavior, planned behavior, and non-goals without conflating them.
• Architecture and manual updates must preserve authority and validation rationale for reviewers.
• Cross-repository changes require matching documentation updates where user-visible contracts change.
• Milestone and roadmap material must not substitute for component-level README, architecture, or roadmap ownership.
• Filesystem encryption documentation must keep fscrypt policy parsing, keyd authority, unsupported-mode non-goals, runtime IPC handling, and integration validation aligned with component repositories.
• Runtime filesystem documentation must keep user_vfs, fs_ramfs, fs_e2fs, fs_fat, private keyd authority for ext fscrypt, and BootConfig MNT1 mount-policy rows aligned across component repositories. The current dev/release runtime mount policy is / on erix-data as ext4, /boot on erix-esp as FAT, and /tmp as ramfs.
• Runtime user-stack documentation must keep daemon toggles split from hardware driver toggles for serial, storage, and PS/2 input authority.
• Runtime image documentation must distinguish local VM harness runs that opt into RUNTIME_IMAGE_TEST_HARNESS=1 from packaged dev/release artifacts built with that harness disabled after the non-runtime VM gate passes. The disabled harness path includes debug-exit and rootd late VFS verifier probes.
• Program-loader documentation must distinguish the temporary summary-only bootstrap bridge from the Phase 4.7.7 loader image transfer ABI and the later procd mapping transaction.
• Program-loader validation documentation must keep the Phase 4.7.9 filesystem-unique execution proof aligned with integration: two distinct disk executable markers, stale-source launch rejection before process start, and host-side fingerprint absence from boot image service modules.
• Program-loader closure documentation must keep the Phase 4.7 final evidence set concrete: filesystem discovery, malformed ELF and invalid-plan rejection, true disk-byte execution, cleanup fault injection, unwanted-authority denial, and the focused phase4-loader-closure scenario group.
• Manual artifact documentation must keep the CI-built erix-technical-manual.pdf release asset, checksum, and branch/tag release routing aligned with the repository workflow.
• Runtime ready-stamp documentation must keep the packaged dev service-level surface explicit for fbcond, blockd, memory-provider, keyd, e2fsd, fatd, vfsd, and aggregate storage readiness, while leaving operation-level VFS mount/I/O proof stamps tied to local late-verifier or focused integration profiles. Packaged release images suppress every ready stamp except final ERIX_ROOTD:READY.
• Filesystem verity documentation must keep Linux descriptor parsing, salt-aware SHA-256 Merkle verification, private keyd trust-root authority, built-in signature parsing plus fail-closed policy, and fail-closed data/tree tamper validation aligned with component repositories, including rootd's targeted fsverity VM validation profile.
• Filesystem read-only feature documentation must keep ext4 readonly and shared_blocks mount policy, traversal-only operation set, mutation-handle denial, and targeted VM validation aligned with component repositories.
• Filesystem stable-inode documentation must keep ext4 stable_inodes, resize_inode, reserved GDT preservation, and UUID-bound encryption-state mutation denial aligned across component repositories and VM validation.
• Filesystem geometry documentation must keep the ext 1 KiB/2 KiB/4 KiB filesystem-block envelope, deliberate fail-closed rejection of larger ext blocks under the current 4 KiB provider ABI, and 128/256/512-byte inode record support aligned across component repositories and VM validation, including oversized block/inode negative media.
• Filesystem name documentation must keep casefold encoding policy, Unicode table versioning, and fail-closed malformed-name behavior aligned across the component repositories and manual.
• Filesystem encrypted-name documentation must keep fscrypt v2 keyd authority, encrypted casefold lookup/readdir semantics, fscrypt v1 non-goal status, and targeted VM validation aligned across component repositories and manual.
• Filesystem inline-data documentation must keep ext4 inline file/directory semantics, xattr preservation, growth conversion, and fail-closed malformed payload behavior aligned across component repositories and the manual.
• Filesystem xattr documentation must keep ext xattr/POSIX ACL handling provider-local: public list/get/set/remove xattr and ACL mutation endpoints are a permanent v1 non-goal, while host debugfs/e2fsck -fn VM checks prove preservation without granting namespace authority; getfattr/getfacl projection is used only when the host runner exposes FUSE.
• Filesystem feature-registry documentation must distinguish obsolete rejected Linux/e2fsprogs feature bits from planned implementation slices and keep high future plus undefined gap feature-bit fail-closed coverage visible.
• Filesystem advanced ext corpus documentation must keep implemented, rejected, obsolete-rejected, planned, and permanent non-goal feature classes distinct for fscrypt v1, fsverity built-in signatures, fast-commit indexed directories, sparse/unwritten extents, metadata mutation, and oversized geometry.
• Filesystem fast-commit documentation must keep supported replay TLVs, indexed and multi-block directory replay, multi-segment tail validation, full-commit ordering, provider-originated full-commit policy, and fail-closed malformed-record behavior aligned across component repositories and the manual.
• Filesystem external-journal documentation must keep explicit provider-local mapping requirements and standalone journal_dev volume rejection aligned across component repositories and the manual.
• Filesystem cross-cutting documentation must keep ext feature-registry policy, focused VM scenario groups, authority-negative coverage, and media module size boundaries aligned with the integration EXT-CROSS manifest.
• Filesystem interoperability documentation must keep the ext2/ext3/ext4 Linux/e2fsprogs corpus matrix aligned with feature bits, malformed media, host tools, provider mutation, and targeted VM scenario groups.
• Filesystem compliance documentation must keep the cross-format FAT12, FAT16, FAT32, VFAT, exFAT, ext2, ext3, and ext4 matrix aligned with read-write, read-only, rejected, obsolete-rejected, and planned status, host producer and verification tools, negative media categories, and the focused strict validation command. It must also keep operation-probe decisions aligned so preservation-only, read-only-visible, explicitly denied, planned, and permanent non-goal provider surfaces are not described as implemented mutation support.
• FAT documentation must keep FAT32 extended BPB validation, active-FAT selection, backup boot-sector validation, reserved-entry validation, dirty/hard-error read-only-only policy, FAT directory timestamp/attribute semantics, strict VFAT LFN/alias validation, ASCII-only standalone short-name parsing with VFAT OEM-alias acceptance, NT lowercase direct short entries, allocation-stress validation, referenced-chain fail-closed coverage, exFAT boot-region checksum and backup policy, exFAT active-FAT and volume-state policy, exFAT upcase-table Unicode lookup and NameHash validation, exFAT allocation-bitmap reconciliation and no-FAT-chain stream validation, exFAT valid-data-length zero-fill/truncate behavior, exFAT primary-entry timestamp/attribute stat and mutation behavior including UTC offsets and 10 ms increments, exFAT Volume Label/GUID metadata parsing, TexFAT padding policy, benign vendor-extension preservation, and unsupported critical/allocation entry fail-closed behavior, exFAT rename file and empty-directory replacement with destination allocation cleanup, exFAT primary percent-in-use recomputation and dirty partial-update fail-closed behavior, exFAT interoperability corpus coverage for varied cluster/FAT/bitmap/root-chain/path layouts, FAT rename file and empty-directory replacement, FAT regular-file truncate shrink/grow/zero-fill behavior with FAT32 FSInfo accounting, FAT timestamp/stat/set-metadata behavior for stat-only creation time, date-only atime, two-second mtime, and read-only attributes, and focused FAT-01/FAT-02/FAT-03/FAT-04/FAT-05/EXFAT-01/EXFAT-02/EXFAT-03/EXFAT-04/EXFAT-05/EXFAT-06/exFAT metadata/exFAT entry-type/exFAT rename/exFAT percent VM media coverage aligned across fatd, integration, and the manual, including fatd's stack-bounded runtime scratch and cached mount-time FAT-sector reads.
• VFS API documentation must keep the expanded rename/truncate/symlink/readlink, hard-link denial, richer stat, metadata-update, and xattr permanent non-goal policy aligned across lib-ipc, lib-vfs, vfsd, providers, and VM validation.
• Program-loader documentation must keep the Phase 4.7 contract slice aligned across lib-ipc, rootd, and integration: path-only launch requests, bounded argv/env payloads, deterministic loader failure codes, no inherited capability or peer/service endpoint grants, and explicit bootstrap-only static bridge policy before the Phase 5.4 dynamic-link final state.
• Program-loader boot/image documentation must keep the features.program_loader runtime toggle, loaderd BootConfig ordering after vfsd, explicit vfsd/procd peer grants, appliance disk-loader fixture installation, and optional omission behavior aligned across rootd, integration, and the manual without implying ambient filesystem or executable authority.
• Program-loader materialization documentation must keep the Phase 4.7.6 model explicit: loaderd owns VFS source validation and ordered byte transfer, while procd owns executable backing allocation, segment copy, zero-fill, W^X permission sealing, child address-space mapping, startup-state installation, and cleanup without acquiring VFS/provider authority.
• Program-loader closure documentation must keep Phase 5.4 separate: Phase 4.7 may retain only explicitly marked static bootstrap fixtures, while final non-bootloader executable crates remain scheduled for dynamic linking.
• Ext link-special documentation must keep e2fsd symlink/readlink, regular-file/symlink hard-link, metadata-only FIFO/socket/device inode representation, and special-file authority denial aligned across e2fsd, rootd, integration, and the manual.
• Ext truncate documentation must keep e2fsd regular-file shrink, zero-length shrink, zero-filled growth, block/cluster freeing, journal/quota writeback, denial policy, and focused ext-truncate VM validation aligned across e2fsd, rootd, integration, and the manual.
• Ext sparse documentation must keep e2fsd write-past-EOF range allocation, zero-filled hole reads without block materialization, touched unwritten-extent conversion, sparse truncate trimming, and focused ext-sparse VM validation aligned across e2fsd, rootd, integration, and the manual.
• Ext metadata documentation must keep e2fsd timestamp decoding, mode/owner mutation, user filesystem flag updates, immutable/append-only denial policy, checksum/journal/quota writeback, and focused ext-metadata VM validation aligned across e2fsd, rootd, integration, and the manual.
• Ext rename documentation must keep e2fsd file, directory, symlink, special-metadata, compatible-overwrite, cycle-rejection, HTree, checksum, journal, quota-sync, and targeted ext-rename VM coverage aligned across e2fsd, rootd, integration, and the manual.
• Ext indexed-directory documentation must keep depth-0/depth-1 operation, non-large_dir depth-2 rejection, ext4 large_dir depth-2 mutation, and malformed-index VM coverage aligned across component repositories.

Documentation Boundaries

• docs may describe component behavior, but component repositories remain authoritative for their implementation details.
• Shared policy belongs here only when it applies across repositories.

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.