lib-time

lib-time is the no_std client helper library for the timed service.

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

Functionally, it exposes the time 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:

• accept source-qualified calibrated processor elapsed time for monotonic queries without treating that source as trusted UTC wall time
• expose the lib-time crate API for time behavior used by dependent components
• convert between checked proleptic-Gregorian UTC civil fields and Unix seconds
• classify v2 wall snapshots so callers cannot treat unavailable or synthetic values as trustworthy filesystem timestamps
• parse the exact POSIX touch -t and touch -d civil-time operands without allocation, including the 1969/2068 short-year split and checked fractions
• format the complete POSIX-locale strftime conversion set used by date, including its exact E and O modifier sets, into caller-owned storage
• convert fixed POSIX TZ values and monotonic or nanosecond observations with checked arithmetic
• 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.

Usage model

The caller owns transport details and supplies:

• destination endpoint slot
• encoded request send and response receive callback

lib-time owns snapshot request/response encoding, decoding, and contract validation. Blocking deadlines are deliberately absent until the kernel can deliver them asynchronously; callers retain their own scheduling and cancellation policy.

now_wall_v2 returns UTC Unix time for years 1970 through 9999 and an explicit source classification. Only HardwareRtc and Degraded snapshots are trusted for persistent ctime, mtime, and atime; Unavailable has zero civil fields, while Synthetic remains boot-relative and untrusted. Calendar conversion is allocation-free, rejects leap seconds, and follows Gregorian century rules. TimeWallV2::filesystem_timestamp converts only trusted values to the filesystem ABI's u64 Unix-nanosecond representation and rejects the portion of timed's year-9999 range that cannot fit without overflow.

The command-facing helpers remain pure algorithms. parse_touch_timestamp and parse_touch_date_time accept only the documented POSIX byte grammars and produce UTC values after a caller-supplied checked fixed offset. The fixed timezone parser accepts only stdoffset values without daylight or geographic rules; unsupported zones fail instead of triggering database lookup. format_posix_date implements the POSIX locale, performs a complete measuring pass before modifying output, and rejects extension flags and widths. Duration helpers normalize exact nanosecond values and convert monotonic counters without rounding up. A separate format preflight lets a command reject malformed syntax before it queries timed. None of these calls owns or discovers a timed endpoint, filesystem object, environment, locale database, or process route.

Build and test

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

Dependencies

• lib-ipc

No external crates are used.

Governance Principles

lib-time governance is scoped to reusable time 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-time 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.