Files
prometeu-runtime/docs/specs/runtime/11-portability-and-cross-platform-execution.md
T
bquarkz f1adf86dd5
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
feat(runtime): support Studio Play and separate integration gates
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.
2026-11-19 17:32:02 +00:00

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.