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

Input Peripheral (VM-Owned Snapshot Input)

Domain: virtual hardware: input
Function: normative

Didactic companion: ../learn/mental-model-input.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.

9 Host/System Controls

Host/System controls are not part of the guest-visible input surface.

The Home/SystemOS request changes machine foreground authority. It must be handled by the host, firmware, or SystemOS before input is exposed to the Game. It must not be represented as pad.start, pad.select, a new pad field, a VM intrinsic, or a userland syscall.

For the desktop host, Esc is the primary keyboard mapping for the Home/SystemOS request. The physical Home key may be supported as an alias. Both mappings are host controls and must not mutate InputSignals.

When a Game leaves or re-enters foreground, pending Game input must be cleared or barriered so held or pressed input cannot leak across pause/resume boundaries. This barrier applies to the Game-facing snapshot; it does not change the meaning of host/system Home controls.