Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Add the windowless Studio host with authenticated binary control/frame channels, managed input, pause/resume/stop, frame ownership and save-aware shutdown. Preserve deterministic headless execution and add protocol/process fixtures. Separate unit CI and coverage from opt-in integration/socket qualification, retaining the prior combined coverage floors in the configuration history. Validation: tooling make verify passed runtime ci-domains and integration.
378 lines
17 KiB
Markdown
378 lines
17 KiB
Markdown
# Portability Guarantees and Cross-Platform Execution
|
|
|
|
Domain: portability contract
|
|
Function: normative
|
|
|
|
Didactic companion: [Portability mental model](../../../discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md)
|
|
|
|
## 1 Scope
|
|
|
|
This chapter defines the portability contract of the PROMETEU machine across supported hosts.
|
|
|
|
Portability means:
|
|
|
|
- same cartridge;
|
|
- same machine rules;
|
|
- same logical inputs;
|
|
- same logical results.
|
|
|
|
The contract is about logical behavior, not identical physical latency or throughput.
|
|
|
|
## 2 Separation of Responsibilities
|
|
|
|
```
|
|
+----------------------------+
|
|
| CARTRIDGE |
|
|
| (bytecode + assets) |
|
|
+-------------+--------------+
|
|
|
|
|
+-------------v--------------+
|
|
| PROMETEU VM |
|
|
| (logic, time, memory) |
|
|
+-------------+--------------+
|
|
|
|
|
+-------------v--------------+
|
|
| PLATFORM LAYER |
|
|
| window, audio, input, FS |
|
|
+----------------------------+
|
|
```
|
|
|
|
### 2.1 What the machine controls
|
|
|
|
- bytecode execution
|
|
- logical time (frames, cycles)
|
|
- memory (stack, heap)
|
|
- determinism
|
|
- costs and metrics
|
|
|
|
### 2.2 What the host provides
|
|
|
|
- pixel display
|
|
- 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
|
|
|
|
The host provides realization of machine surfaces. It does not redefine cartridge semantics.
|
|
|
|
## 3 Determinism as the Basis of Portability
|
|
|
|
PROMETEU guarantees determinism through:
|
|
|
|
- fixed logical clock (60 Hz)
|
|
- abstract cycles, not real time
|
|
- input sampled per frame
|
|
- absence of implicit concurrency
|
|
- absence of system-dependent operations
|
|
|
|
## 4 Independence from Real Hardware
|
|
|
|
Deterministic gameplay and cycle accounting **do not depend on**:
|
|
|
|
- operating system timers
|
|
- high-resolution clocks
|
|
- CPU-specific instructions
|
|
- uncontrolled graphics acceleration
|
|
|
|
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
|
|
|
|
[Numeric execution](02d-gameplay-math-and-numeric-semantics.md) uses finite
|
|
binary64 software arithmetic, explicit rounding, signed zeros and subnormals.
|
|
Supported hosts MUST agree on result bits, numeric faults and virtual cycles.
|
|
The mathematical precision bound for trigonometry is not a tolerance between
|
|
hosts. Native acceleration requires exact equivalence to the reference.
|
|
|
|
Qualification evidence identifies runtime build/revision, target, profile,
|
|
dependency resolution and catalog snapshot. The current independent numeric
|
|
delivery qualifies available macOS/aarch64 in debug/release.
|
|
Comparative macOS/x86_64 and Linux/x86_64 execution remains pending; recognizing
|
|
the same intrinsic IDs or successfully cross-compiling does not certify a
|
|
new host. Unavailable hardware does not weaken the contract or require a new
|
|
graphical/audio backend for mathematical qualification.
|
|
|
|
## 6 Cross-Platform Input
|
|
|
|
PROMETEU abstracts physical input into **logical state**.
|
|
|
|
- keyboard, gamepad, and touch are mapped externally
|
|
- the cartridge only sees logical buttons and axes
|
|
- the reading moment is fixed per frame
|
|
|
|
## 7 Cross-Platform Audio
|
|
|
|
The audio system:
|
|
|
|
- defines channels and mixing logically
|
|
- uses native APIs only as output
|
|
- maintains per-frame synchronization
|
|
|
|
Hardware differences:
|
|
|
|
- do not change logical timing
|
|
- do not change sound sequence
|
|
- do not affect certification
|
|
|
|
## 8 Cross-Platform Graphics
|
|
|
|
The graphics system:
|
|
|
|
- produces typed logical render submissions that render to RGBA8888 output
|
|
- consumes Game submissions through either a local synchronous consumer or a
|
|
render worker, both of which publish owned `OwnedRgba8888Frame` values
|
|
- uses an indexed palette
|
|
- does not depend on a specific GPU
|
|
|
|
The platform layer:
|
|
|
|
- exposes typed service facades for render submission, render backend
|
|
execution, Game 2D composition, input, audio, assets, and telemetry
|
|
- consumes closed render submissions through a render-surface implementation
|
|
- transports published `OwnedRgba8888Frame` pixels into a host presentation
|
|
surface without
|
|
injecting host-owned debug overlay pixels
|
|
- is the runtime-facing portability boundary; runtime and firmware code must not
|
|
depend on a monolithic hardware bridge or on a concrete hardware aggregate
|
|
|
|
The host presentation layer MUST treat RGBA8888 as the canonical logical
|
|
framebuffer format. RGB565 conversion is not part of the normal host
|
|
presentation contract.
|
|
|
|
Native upload and present belong to the host event loop. The render worker MUST
|
|
NOT own or require a native window, swapchain, `pixels` surface, SDL texture, or
|
|
host GPU texture as part of its contract. The worker output is an owned
|
|
RGBA8888 frame; the host decides how to upload that frame to the native
|
|
presentation API for the current platform.
|
|
|
|
Host presentation SHOULD be driven by published render submissions and explicit
|
|
host-owned invalidation, not by perpetual redraw polling.
|
|
|
|
In particular:
|
|
|
|
- a stable published submission MAY remain visible across multiple host wakeups without recomposition;
|
|
- a host MAY redraw the same logical frame again when its own surface is invalidated by resize, expose, or debugger-visible host changes;
|
|
- a host MUST NOT invent intermediate logical frames or require continuous redraw merely to discover whether a new logical frame exists.
|
|
|
|
## 9 Debug and Inspection Isolation
|
|
|
|
To preserve portability and certification purity, technical inspection tools are host-owned and must not inject pixels into Game or Shell output.
|
|
|
|
- **Host-exclusive:** These tools are only implemented where they are relevant (e.g., Desktop) and do not exist in the logical machine.
|
|
- **Non-intrusive:** They must not consume machine cycles or alter memory state.
|
|
- **Consistent Results:** A cartridge will produce the same logical results and certification metrics regardless of the Host's inspection capabilities.
|
|
- **Contract Boundary:** Emulated graphics primitives such as `fill_rect` and
|
|
`draw_text` remain part of the machine contract; host diagnostics must not
|
|
depend on them for visual injection.
|
|
|
|
### 9.1 Atomic Telemetry Interface
|
|
|
|
Inspection is facilitated by a lockless, push-based atomic interface:
|
|
|
|
1. **Host-Independent:** The VM updates atomic counters in every frame.
|
|
2. **Asynchronous Observation:** The Host layer reads snapshots of these counters at its own display frequency.
|
|
3. **Loop Purity:** This ensures that the VM execution loop remains deterministic and free from synchronization overhead (locks) that could vary across host architectures.
|
|
|
|
Reading host-owned telemetry does not imply a perpetual presentation loop. The host may wake on its own schedule for inspection purposes while still presenting the logical framebuffer only when a published frame or host-owned invalidation requires it.
|
|
|
|
## 10 File System and Persistence
|
|
|
|
PROMETEU defines a **sandbox logical filesystem**:
|
|
|
|
- virtual paths
|
|
- size limits
|
|
- deterministic behavior
|
|
|
|
The platform maps this filesystem to:
|
|
|
|
- disk
|
|
- mobile storage
|
|
- persistent memory
|
|
|
|
Without changing semantics.
|
|
|
|
## 11 Certification and Portability
|
|
|
|
The host-owned **PROMETEU Certification** is valid for all platforms.
|
|
|
|
If a cartridge:
|
|
|
|
- passes on one platform
|
|
- with the same inputs
|
|
|
|
It:
|
|
|
|
- will pass on all
|
|
- will produce the same reports
|
|
|
|
## 12 What PROMETEU Does Not Guarantee
|
|
|
|
PROMETEU **does not promise**:
|
|
|
|
- identical absolute performance (real FPS)
|
|
- identical physical latency
|
|
- equivalent energy consumption
|
|
|
|
PROMETEU promises:
|
|
|
|
- **identical logical behavior**
|
|
- **reproducible technical decisions**
|
|
|
|
## 13 Deterministic Headless Control
|
|
|
|
The interactive desktop host also supports Studio-owned realtime execution without
|
|
a native game window, specified by [Studio Play Protocol v1](11b-studio-play-protocol.md).
|
|
This mode retains interactive pacing, native audio and the existing firmware/VM;
|
|
it is not the deterministic automation host. Its frame transport workers must not
|
|
block machine advancement on UI/video consumption. This addition does not change
|
|
the headless controls below, guest capabilities or canonical frame ownership.
|
|
|
|
The external tooling boundary is specified separately in
|
|
[Headless Automation Protocol v1](11a-headless-automation-protocol.md). It preserves
|
|
the in-process semantics in this section and does not extend the guest ABI.
|
|
|
|
The headless host is a separate, generic Prometeu host for in-process
|
|
automation. It runs the same directory cartridge, firmware, active VM session,
|
|
capability checks, normalized input, render submissions, and fault model as an
|
|
interactive host. A cartridge cannot detect or request headless execution, and
|
|
headless execution grants no additional guest capability.
|
|
|
|
The headless host requires no native window, display server, physical input,
|
|
physical audio device, or realtime frame pacing. It uses the explicit local
|
|
synchronous Game render consumer. A successful logical-frame advance returns
|
|
only after the exact canonical `OwnedRgba8888Frame` for that advance has been
|
|
published. It does not start or wait for an asynchronous render worker, and
|
|
publication correctness does not use spinning, yielding, sleeping, or a
|
|
wall-clock timeout.
|
|
|
|
### 13.1 Control contract
|
|
|
|
- `boot(path)` loads a normal directory cartridge and stops on entry to
|
|
`GameRunning`, before the first game instruction. A second boot attempt
|
|
requires `reset()` and otherwise returns `AlreadyBooted`.
|
|
- `reset()` enters the normal firmware reset boundary and clears input, active
|
|
sessions, structured faults, and headless frame correlation. Capture is
|
|
unavailable until the new run completes a frame.
|
|
- `pause()` and `resume()` control the active VM session. `step()` executes one
|
|
VM instruction and finishes paused without reporting a completed logical
|
|
frame.
|
|
- `set_input()` retains one complete `InputSignals` snapshot, including the
|
|
digital pad and touch signal/coordinates. `clear_input()` restores its
|
|
default. The normal begin-frame input sampling defined by the input
|
|
peripheral derives `pressed`, `released`, `down`, and `hold` state.
|
|
- `advance_frame()` advances internal firmware ticks until exactly one logical
|
|
frame closes through `FrameSync` or `EndOfRom`, or until a structured fault or
|
|
lifecycle termination prevents completion. Internal cycle-slice exhaustion
|
|
continues the same frame; it is not itself a frame boundary.
|
|
- `advance_frames(n)` is repeated `advance_frame()`. It reports the requested
|
|
and completed counts plus completed-all, fault, or termination. Zero is a
|
|
no-op; fault or termination preserves partial completed progress.
|
|
- A frame advance finishes paused and clears its host-owned debug-step request,
|
|
including when lifecycle termination interrupts the advance. Guest faults
|
|
are outcomes represented by `CrashReport`; host precondition and publication
|
|
failures are host errors. A deterministic headless-host watchdog also bounds
|
|
the number of firmware ticks spent advancing one logical frame. Its limit is
|
|
tooling policy, not a guest cycle budget, runtime fault, or wall-clock
|
|
performance requirement.
|
|
- If a successful memcard bootstrap still blocks the active VM on its queued or
|
|
running native publication, the headless owner coordinates lane progress outside
|
|
machine ticks, in requested waits of at most 5 ms. The same advance retains its
|
|
request and a single 2 s outer deadline from first wait admission; wakes/reentry
|
|
do not reset it. Native 500 ms cancellation and 1 s escalation remain authoritative.
|
|
A native action-required boundary takes precedence; unresolved IO at the outer
|
|
deadline returns a memcard `restart_required` host error with a native snapshot.
|
|
Every return pauses execution and clears the host's step request. IO-only polls
|
|
and waits do not add guest ticks/frames, enlarge the 100,000 firmware-tick
|
|
watchdog, rerun bootstrap, or synchronize unrelated gameplay commits. Waiting
|
|
does not establish IO cessation or permit release of worker-owned resources.
|
|
- `capture_frame()` returns an owned clone of the canonical frame paired with
|
|
the latest successful advance. The explicit `{logical_frame_index, FrameId}`
|
|
pair is authoritative; no numeric equality or fixed offset is implied.
|
|
- `get_state()` classifies execution as running, paused, terminated, or faulted
|
|
and exposes the overlapping debugger state. `get_fault()` returns structured
|
|
`CrashReport` data rather than requiring log or summary parsing.
|
|
- Valid audio commands pass through normal runtime semantics. The headless host
|
|
drains them into a null/discard sink; it does not synthesize PCM or require an
|
|
output device.
|
|
|
|
### 13.2 Deterministic oracle
|
|
|
|
Deterministic comparison includes the logical-frame index and paired `FrameId`,
|
|
canonical framebuffer pixels (or a stable pixel hash) and dimensions/stride,
|
|
guest-visible PC/stack/app state, structured execution status and fault data,
|
|
and deterministic counters describing simulated execution.
|
|
|
|
The oracle excludes wall-clock or boot-time timestamps, real elapsed duration,
|
|
host CPU time, thread-scheduling measurements, presentation cadence,
|
|
render-worker timing telemetry, and host-owned identities without simulated
|
|
machine meaning. The same cartridge, initial machine state, and per-frame input
|
|
timeline must produce the same included observations on independent runs and
|
|
after reset.
|
|
|
|
AI tooling may consume this generic host API from outside the machine. It does
|
|
not create an AI mode, testing mode, replay protocol, gameplay introspection
|
|
surface, or guest capability.
|
|
|
|
## Random core integration
|
|
|
|
[PCG64 random](02e-vm-owned-random-core.md) fixes unsigned wrapping state, seed-bit conversion and software Float output across targets. Qualification records only executed targets; no platform-selected RNG or host entropy is permitted.
|