prometeu-runtime/docs/runtime/specs/06-input-peripheral.md

Input Peripheral (VM-Owned Snapshot Input)

Domain: virtual hardware: input
Function: normative

Didactic companion: ../learn/input-mental-model.md

1 Scope

This chapter defines the runtime-facing input contract of PROMETEU.

Core contract:

• input is exposed as VM-owned snapshot state;
• sampling happens at a deterministic point of each logical frame;
• queries are deterministic inside the same frame;
• input access uses VM-owned intrinsics (not host syscalls in v1).

2 Devices and Surface

For v1, the input domain includes:

• pad
• touch
• button (as a nested state surface used by pad and touch)

No analog axis is part of the v1 input contract.

3 Frame Sampling Model

Input state is captured at the beginning of each logical frame, before update logic runs.

Conceptual flow:

FRAME N:
SAMPLE_INPUT
UPDATE
DRAW
AUDIO
SYNC

Within the same frame:

• input state is immutable;
• repeated reads return the same values.

4 State Semantics

button exposes:

• pressed: bool (true only on transition up -> down in this frame)
• released: bool (true only on transition down -> up in this frame)
• down: bool (true while physically pressed in this frame snapshot)
• hold: int (count of consecutive pressed frames)

pad is a fixed set of buttons:

• up, down, left, right
• a, b, x, y
• l, r, start, select

touch exposes:

• x: int
• y: int
• button with the same pressed/released/down/hold semantics

PROMETEU handheld v1 uses single-touch active pointer semantics.

5 Access Model

Input is VM-owned in v1:

• frontend surfaces may be ergonomic and language-specific;
• lowering maps to VM-owned INTRINSIC <id_final>;
• no input syscall is required in the host ABI path.

Illustrative (language-level) shape:

Input.pad().up().hold()
Input.touch().x()

The normative contract is intrinsic identity/version and semantics, not source syntax.

6 Determinism and Replay

Given the same per-frame input snapshots, execution must produce the same observable results.

This enables:

• deterministic replay;
• deterministic certification analysis;
• controlled input injection in tests/tooling.

7 Capability and Certification

Input reads are not capability-gated by syscall capability policy in v1.

Input access is VM-owned and should not be reported as host syscall consumption.

8 Portability

All platforms must provide the mandatory input elements (pad, touch, button) to the runtime.

Platform differences in physical device mapping are resolved outside VM semantics.