Files
prometeu-runtime/docs/specs/runtime/11-portability-and-cross-platform-execution.md
T
bquarkz 4f10f6e584
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
feat: add headless automation protocol and CLI
2026-09-28 15:36:22 +01:00

11 KiB

Portability Guarantees and Cross-Platform Execution

Domain: portability contract Function: normative

Didactic companion: ../learn/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
  • 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

PROMETEU does not use:

  • operating system timers
  • high-resolution clocks
  • CPU-specific instructions
  • uncontrolled graphics acceleration

All performance is measured in PROMETEU cycles, not in milliseconds.

5 Floating Point Precision

To guarantee numerical consistency:

  • PROMETEU defines explicit mathematical operations
  • avoids dependence on specific FPUs
  • standardizes number behavior

This avoids:

  • divergences between architectures
  • unpredictable cumulative errors
  • subtle differences between platforms

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 external tooling boundary is specified separately in Headless Automation Protocol v1. 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.
  • 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.