prometeu-runtime/docs/specs/runtime/11-portability-and-cross-platform-execution.md

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 surfaces (Debug Overlay/HUD)

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:

• operates on a logical RGBA8888 framebuffer
• uses an indexed palette
• does not depend on a specific GPU

The platform layer:

• only displays the framebuffer
• does not reinterpret graphics commands
• may overlay technical HUDs without modifying the logical framebuffer
• may transport the logical framebuffer into a host presentation surface where a host-only overlay layer is composed

The host presentation layer MUST treat RGBA8888 as the canonical logical framebuffer format. RGB565 conversion is not part of the normal host presentation contract.

Host presentation SHOULD be driven by published logical frames and explicit host-owned invalidation, not by perpetual redraw polling.

In particular:

• a stable logical frame 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 host-only overlay/debug 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 (like the Debug Overlay) are moved to the Host layer.

• 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, but Host overlays must not depend on them.

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