# Input Peripheral (VM-Owned Snapshot Input)

Domain: virtual hardware: input  
Function: normative

Didactic companion: [`../learn/input-mental-model.md`](../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:

```text
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:

```text
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.