discussion framework migration
This commit is contained in:
@@ -0,0 +1,109 @@
|
||||
# Input Peripheral (VM-Owned Snapshot Input)
|
||||
|
||||
Domain: virtual hardware: input
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-input.md`](../runtime/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:
|
||||
|
||||
```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.
|
||||
Reference in New Issue
Block a user