187 lines
4.7 KiB
Markdown
187 lines
4.7 KiB
Markdown
# 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**
|