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
@@ -51,6 +51,7 @@ The contract is about logical behavior, not identical physical latency or throug
- audio output
- physical input collection
- access to the sandbox file system
- a local civil clock for administrative UTC timestamps
- technical inspection and debugger integrations that do not modify presented
Game or Shell pixels
@@ -68,14 +69,71 @@ PROMETEU guarantees determinism through:
## 4 Independence from Real Hardware
PROMETEU **does not use**:
Deterministic gameplay and cycle accounting **do not depend on**:
- operating system timers
- high-resolution clocks
- CPU-specific instructions
- uncontrolled graphics acceleration
All performance is measured in **PROMETEU cycles**, not in milliseconds.
Guest execution cost is measured in **PROMETEU cycles**. Native host cost
measurements do not redefine those weights.
Host administration can read civil time through the interface below. Host
deadlines and diagnostics can measure monotonic elapsed time; neither source
changes guest cycle weights or logical frame advancement.
### 4.1 Administrative host wall clock
Didactic companion: [Civil time, ordering and elapsed time](../../../discussion/lessons/DSC-0063-host-clock-interface-for-runtime-utc-timestamps/LSN-0065-civil-time-is-not-ordering-or-elapsed-time.md).
The HAL defines `WallClock::utc_unix_seconds(&self) -> u64`.
`RuntimePlatform::wall_clock(&self) -> &dyn WallClock` MUST return the
host-selected provider. The host MUST keep that provider alive while the
platform uses it. A missing provider MUST NOT be hidden behind a default zero
timestamp. Hardware aggregates and platform wrappers delegate to the selected
source; they do not select an OS clock on the runtime's behalf.
The result is whole UTC seconds since `1970-01-01T00:00:00Z`, with fractional
seconds discarded. Hosts MUST saturate pre-epoch dates to `0` and values above
the unsigned range to `u64::MAX`, without wrapping or panicking. Both endpoints
are timestamps, not error sentinels. A provider always returns a value: an
incorrect system date does not become an absent clock. This interface does not
certify synchronization, authenticity, accuracy, uniqueness, or commit order.
A read MUST be synchronous, local and bounded. It MUST NOT wait for disk,
network, `async_work`, external time synchronization, a worker, or an unbounded
lock. Hosts may maintain local clock state, but MUST reflect civil adjustments,
including backward changes. Repeated reads within a second can be equal.
Real civil time continues during game pause; resume observes current host time.
Host deadlines MUST use their monotonic source rather than this adjustable
clock. No guest time syscall is introduced.
The desktop provider reads the OS clock locally. The headless host and
`TestPlatform` default to a controlled clock at epoch zero. Its native `set`
operation allows backward changes; `advance` adds seconds with saturation.
Reads, ticks, frames, pause/resume and runtime reset MUST NOT implicitly advance
or replace that controlled source. A harness can explicitly advance it while
the game is paused. These native controls do not extend remote automation or
guest capabilities.
Headless supports an explicitly injected `WallClock`, including a real source,
without depending on the desktop host crate. `controlled_wall_clock()` exposes
the default provider's controls; for an injected provider it returns `None`
because the caller owns its controls. The clock reading itself is always a
`u64`. `new_with_wall_clock(...)` preserves the injected source across lifecycle
operations. Future handheld hosts MUST supply their own conforming provider;
desktop/headless support does not qualify an unimplemented hardware backend.
Game-library discovery captures one reading per scan and stores it as the
`u64` `discovered_at` of each entry. This field is not converted back into an
OS-specific time type. Memory-card timestamp integration is a separate pending
consumer; the existing save-identity path is not migrated by the clock service.
Provider qualification MUST check numerical limits, adjustment behavior,
local access without IO waits, deterministic controls and native read cost on
the executed host/profile. Batch timing observations are not universal latency
or individual-read worst-case guarantees.
## 5 Floating Point Precision