# Portability Guarantees and Cross-Platform Execution

Domain: portability contract
Function: normative

Didactic companion: [`../learn/mental-model-portability-and-cross-platform.md`](../runtime/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**

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

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