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 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

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.

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 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