feat(runtime): add host wall clock and administrative UTC timestamps
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-10-13 09:16:15 +01:00
parent 3e39a90083
commit 23dc6fc66d
21 changed files with 603 additions and 51 deletions
@@ -0,0 +1,129 @@
---
id: LSN-0065
ticket: host-clock-interface-for-runtime-utc-timestamps
title: Civil Time Is Not Ordering or Elapsed Time
created: 2026-10-13
tags: [clock, host, runtime]
---
## Context
The published runtime now obtains administrative civil time from a host-selected
`WallClock` through `RuntimePlatform`. Desktop uses its OS clock; headless and
test platforms default to an explicitly controlled source. Game-library discovery
uses this interface for its `discovered_at` values.
Source record: the accepted DEC-0053 contract was executed by PLN-0184, originating
in AGD-0066 / DSC-0063. The workflow artifacts were completed and pruned after
publication. The normative reference is the
[administrative host wall-clock contract](../../../docs/specs/runtime/11-portability-and-cross-platform-execution.md#41-administrative-host-wall-clock).
This lesson explains that implemented boundary; it does not replace the spec.
## Three Clocks Answer Three Different Questions
Civil time answers what date the host reports. Monotonic elapsed time answers
how long an operation has been running. Logical runtime time answers how many
machine frames or cycles have executed. These meanings remain separate even
when one OS supplies their underlying mechanisms.
Moving a civil clock backwards is a normal administrative adjustment. Keeping
the maximum of previous readings would hide that adjustment and produce an
invented date. Conversely, using that civil clock for a timeout could extend or
shorten the operation's allowance. Sequences, rather than timestamps, identify
publication order; monotonic elapsed time drives host deadlines; logical cycles
preserve gameplay behavior.
A clock that is always present need not be accurate. The implemented interface
returns a number even when the system date is wrong. Range handling saturates
pre-epoch values to zero and overflow to u64::MAX. These endpoints are dates in
the chosen representation, not errors or unavailable-source indicators. None of
these properties makes timestamps unique IDs.
## Provider Ownership Is Part of the Boundary
The [HAL trait](../../../crates/console/prometeu-hal/src/wall_clock.rs) is deliberately
small. [Hardware](../../../crates/console/prometeu-drivers/src/hardware.rs) requires
an explicitly supplied provider and delegates reads to it. This keeps the
runtime from silently selecting an OS clock while a wrapper advertises a fake.
The [desktop provider](../../../crates/host/prometeu-host-desktop-winit/src/wall_clock.rs)
reads local SystemTime and converts at the boundary. Its read does not enqueue
work or depend on an IO worker. The
[controlled provider](../../../crates/console/prometeu-drivers/src/wall_clock.rs)
uses one atomic load per read; native set and saturating advance are explicit.
Clock synchronization is not part of the read path.
The headless API retains the selected source across runtime lifecycle changes.
`controlled_wall_clock()` exposes controls for the default fake; it returns
None for a caller-injected provider because the caller owns those controls.
That optional control handle is not an optional timestamp: the selected source
always returns u64.
## Deterministic Tests Control Civil Time Independently
A fake that advances on every read makes behavior depend on how often code
inspects time. A fake tied to frames cannot independently simulate a paused game
whose system clock continues, or a user correcting the date backwards. The
implemented fake therefore changes only through native set/advance controls.
For example, a harness can set the clock to 1,000, advance several game frames
and still read 1,000. It can pause the game, advance civil time by 60 seconds,
and observe 1,060 after resume. Setting the source back to 10 leaves publication
ordering and logical execution untouched. Resetting the runtime does not
replace the host-owned source.
The [headless integration tests](../../../crates/host/prometeu-host-headless/tests/deterministic_control.rs)
exercise this timeline twice and also verify injected-source ownership across
lifecycle operations.
## Sample Once for One Administrative Event
[Game discovery](../../../crates/console/prometeu-system/src/services/game_library.rs)
reads the selected clock once per scan and assigns the resulting u64 to every
entry. A scan is one administrative event; sampling separately for each entry
would make timestamp differences depend on enumeration and disk timing.
A counting provider verifies the single sample, and a later scan after a
backwards adjustment records the new date. The maximum u64 value passes through
without reconstruction as an OS time type. Existing sorting, diagnostics and
launch behavior remain covered by the runtime/firmware tests.
## Validation and Performance Evidence
Executed on macOS/aarch64 (`aarch64-apple-darwin`), rustc 1.98.1, on 2026-10-13:
- `cargo fmt -- --check`: passed.
- `cargo clippy --workspace --all-features`: passed without warnings.
- `cargo test --workspace --all-targets --all-features --no-fail-fast`: 946 passed,
zero failed, nine existing ignored tests across 53 reported test suites.
- `cargo bench -p prometeu-host-desktop-winit --bench wall_clock`: optimized local
dynamic-dispatch benchmark, 101 batches of 10,000 reads after warm-up.
- Documentation workflow-reference scan, lesson-link checks, `git diff --check`
and discussion validation passed.
| Provider | Median batch mean, ns/read | p95 batch mean | Maximum batch mean |
| --- | ---: | ---: | ---: |
| OS civil clock | 30.83 | 57.14 | 138.00 |
| Controlled clock | 0.93 | 3.30 | 4.52 |
These measurements include loop/dynamic-dispatch overhead. They are observed
batch averages under local validation load, not per-call tail guarantees,
worst-case latency bounds, or qualification of a handheld/other OS. The
[benchmark source](../../../crates/host/prometeu-host-desktop-winit/benches/wall_clock.rs)
allows the same experiment on another host. Inspection of the provider paths
establishes the absence of disk/network/async-work waits; fast timings alone
would not establish that property.
## Consumer Boundaries
The generic clock and library consumer are delivered. Memory-card timestamp
publication, slot aggregation under clock regressions, identity generation and
legacy-format transition remain work of the memory-card discussion. The old
save UUID path uses nanoseconds; mechanically replacing it with whole seconds
would not establish a sound identity policy. Temporary-path naming in test and
benchmark infrastructure and monotonic host clocks were outside this migration.
The useful pattern is to publish the small provider contract, demonstrate a real
consumer and deterministic tests, and leave each further consumer responsible
for when it captures and persists the reading. Completion of a source service
is not completion of all its consumers.