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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user