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
@@ -19,6 +19,11 @@ It covers:
## 2 System Base Clock
Administrative UTC timestamps use the separate
[host wall clock](11-portability-and-cross-platform-execution.md#41-administrative-host-wall-clock).
Civil clock adjustments do not change logical time or cycle accounting. Host
timeouts use monotonic elapsed time, independent of that adjustable civil clock.
PROMETEU operates with a fixed **60 Hz** logical clock.
This means:
@@ -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
@@ -99,7 +99,10 @@ The Hub does not execute bytecode directly. It always delegates execution setup
For v1, the local games library is Game-only. Hub/Home must not expose Shell or
System cartridges from the games root. The internal library entry must retain
the loaded manifest data, `title`, `app_id`, `app_version`, the cartridge path,
and discovery metadata such as a timestamp or equivalent discovery marker.
and `discovered_at` as unsigned 64-bit UTC seconds from the selected
[host wall clock](11-portability-and-cross-platform-execution.md#41-administrative-host-wall-clock).
Discovery captures one reading per scan and assigns it to every entry in that
scan. A later scan samples the clock again, including any backward adjustment.
The Home UI may display only `title`, `app_id`, and `app_version`. Path and
operational metadata may remain internal.