feat(runtime): add host wall clock and administrative UTC timestamps
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
This commit is contained in:
+129
@@ -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.
|
||||
Reference in New Issue
Block a user