ramfsd

ramfsd is the private in-memory filesystem provider used by vfsd for volatile mounts.

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

Exact-entry grants can create empty regular files without yielding content handles. Separate live-file handles support explicit truncation, zeroing removed bytes and newly exposed gaps; trusted timestamps are validated before mutation. Unknown OPEN mount identities remain distinct from missing filesystem entries.

This repository implements the EriX volatile memory filesystem provider. Its purpose in EriX is to provide volatile filesystem state behind vfsd 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 volatile memory filesystem runtime and state model
• validate startup authority before accepting IPC requests
• pin cwd directory/link components relative to live provider handles, with independently closable descriptions and raw pinned-link reads
• handle service operations through the assigned endpoint set and deployment-sized private state
• apply trusted descriptive provider timestamps without receiving or retaining timed, RTC, service-discovery, or clock-setting authority
• 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

The private directory-entry metadata operation accepts one retained directory handle and one validated immediate basename. It returns current metadata without reopening a parent pathname or granting file-content access. Closed handles, non-directory objects, and path selectors fail closed; public authorization remains owned by vfsd.

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 for the volatile memory filesystem provider path:

• volatile mount-instance creation
• exact deployment-owned mount, node, file-data, and open-handle storage
• generic provider ABI compatibility for mount and file/directory operations
• identity-bound exact-entry handles that retain the parent, target or absence, and admitted mutation or metadata operation while remaining unusable by ordinary handle operations
• authority-free startup and provider calls with complete unwanted receipt retirement and retained replies under transient backpressure
• directory and file mutation
• UTF-8 path and directory-entry names with unchanged v1 field sizes
• inline read/write I/O
• directory iteration, richer stat, rename, truncate, symlink/readlink, flagged metadata update, unlink, and rmdir; hard-link requests remain explicitly denied
• additive private provider v2 mutations with exact u64 Unix-nanosecond timestamps. Create initializes atime, mtime, ctime, and birth time; successful reads update atime; nonzero writes and every successful truncate update mtime and ctime; namespace changes update affected inode and parent timestamps. Epoch zero remains valid.
• unchanged v1 request/response compatibility with no automatic timestamp updates. V1 metadata requests apply only explicitly selected atime/mtime and preserve ctime; v2 metadata supplies independent trusted current ctime.
• selector-free exact stat and touch through the retained provider handle. Touch revalidates the vfsd-derived basename, silently preserves a proven absence under no-create, initializes a newly created file atomically, and accepts ctime only from the trusted V2 change-time field.
• unit coverage for startup validation, tree rules, dispatch, stateful I/O, and extended volatile-filesystem semantics
• test-only selector-race coverage that succeeds only when a retained exact parent prevents ordinary rename from replacing its path identity

The packaged service carries authenticated record sizes and explicit deployment counts. The image builder derives the number of mount records from the runtime mount table and supplies nodes per mount, file bytes per node, and provider handle records as deployment policy. ramfsd carves typed, non-overlapping slices from that exact arena; page padding stays unusable because the service has no general allocator. A failed create reserves both its node and handle record before changing either, so capacity exhaustion cannot leave residual filesystem state.

RAMFS keeps one node record per namespace entry and intentionally does not add a backing-inode alias layer. Both v1 and v2 hard-link requests are denied before state mutation; the v2 descriptive timestamp does not broaden that filesystem or authority contract.

The startup rendezvous and provider loop wait without daemon-local tick deadlines. Calls may not transfer capabilities. Complete unwanted receipts are retired from their explicit local destinations before rejection; malformed receipt state, uncertain cleanup, or a terminal accepted-reply failure requests process teardown so provider authority cannot remain in a quarantined task.

Validation

• cargo fmt
• cargo clippy --all-targets --all-features -- -D warnings
• cargo test --all-targets --all-features
• RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features

Dynamic Boot Artifact Evidence

The runtime image contract documents ramfsd as a dynamic boot artifact. The image build packages the RAM filesystem provider 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 through procd staged dynamic creation before dynlinkd; authority remains explicit memory-provider and VFS peers. 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. ramfsd receives only the documented startup endpoints, peers, and capabilities for its role.

Governance Principles

ramfsd governance is scoped to private volatile memory filesystem provider behavior.

The scoped governance rules are:

• It serves in-memory filesystem state only through authorized startup endpoints.
• It preserves generic provider ABI behavior used by vfsd.
• It keeps file data within explicitly packaged per-node extents and rejects malformed path operations.
• It accepts timestamps only as validated descriptive data on its authenticated vfsd provider route and retains no source classification or per-call time.
• It exposes no persistent storage or block-device authority.

Authority Boundaries

• ramfsd 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.