# Agenda - Input Intrinsics Surface

## Problema

`input` ja esta conceitualmente do lado de intrinsics, nao de syscalls, mas a superficie concreta desse dominio ainda nao esta congelada.

Nesta agenda, `input` significa o dominio formado por:

- `pad`;
- `touch`.

Sem uma agenda propria, o dominio de input corre o risco de ficar:

- espalhado pela spec de input;
- implícito no ISA;
- indefinido no verifier;
- lembrado tarde demais na fase de implementacao.

Hoje existe uma ambiguidade concreta no runtime:

- as specs tratam input como estado amostrado por frame;
- a linguagem/runtime quer expor `pad` e `touch` como surface built-in do guest;
- mas a implementacao ainda coleta esse estado por syscalls.

Exemplos atuais no runtime:

- `InputGetPad`
- `InputGetPadPressed`
- `InputGetPadReleased`
- `InputGetPadHold`
- `InputPadSnapshot`
- `InputTouchSnapshot`
- `TouchGetX`
- `TouchGetY`
- `TouchIsDown`
- `TouchIsPressed`
- `TouchIsReleased`
- `TouchGetHold`
- `TouchGetFinger`
- `PadGetUp` ate `PadGetSelect`

## Dor

- o runtime pode implementar intrinsics de input com shape arbitrario;
- custo, assinatura e IDs logicos podem divergir entre docs;
- o verifier pode aceitar chamadas sem contrato fechado;
- `button` pode ganhar peso desproporcional e esconder que ele eh apenas uma parte da surface de `pad`;
- o dominio de input fica misturado com decisoes de syscall, onde ele nao pertence.
- o runtime mantem duas historias ao mesmo tempo: input como estado latched e input como host service;
- a superficie explode em muitas syscalls pequenas para ler algo que ja esta disponivel como estado do hardware.

## Alvo da Discussao

Definir a superficie canonica dos intrinsics de input observavel pela VM.

`pad` e `touch` sao os dois blocos do dominio.
`button` entra aqui apenas como parte da surface de `pad`, nao como centro exclusivo da agenda.

Esta agenda tambem precisa decidir a migracao explicita:

- quais syscalls de input serao removidas;
- quais intrinsics as substituem;
- qual surface final o guest enxerga como built-in.

## O Que Precisa Ser Definido

1. Conjunto de intrinsics.
   Quais operacoes existem no MVP:
   - operacoes de `pad`;
   - operacoes de `touch`, se entrarem no MVP.

   No caso de `pad`, os candidatos iniciais sao:
   - `btn`
   - `btnp`
   - `btnr`
   - `axis`, se entrar ou nao.

2. Assinatura exata.
   Definir:
   - argumentos;
   - tipo de retorno;
   - custo/cycles;
   - comportamento para ID invalido;
   - comportamento para ausencia de suporte do dispositivo.

3. Superfícies do dominio.
   Fechar quais familias de input a VM pode consultar no contrato inicial:
   - pad;
   - axis;
   - touch.

4. Identificadores logicos.
   Fechar o conjunto de IDs logicos que a VM pode consultar.
   Isso inclui:
   - botoes do pad;
   - eixos, se existirem;
   - pontos/canais de touch, se existirem.

5. Integracao com ISA e verifier.
   Como os intrinsics sao referenciados, validados e emitidos no bytecode.

6. Migração da surface atual.
   Definir:
   - quais syscalls de input deixam de existir;
   - se toda leitura de `pad` e `touch` sai da ABI de syscall;
   - como a toolchain e a surface do guest passam a apontar apenas para intrinsics.

7. Observabilidade.
   O que entra em trace, certificacao e relatorios de custo.

## Dependencias

- ISA/intrinsic model da VM;
- spec de input para o dominio logico;
- definicao de fault ou resposta para IDs invalidos, se houver;
- alinhamento com a spec de touch, se o dominio entrar no MVP.

## Fora de Escopo

- mapeamento fisico de teclado/gamepad;
- pipeline de coleta de input no host;
- gestos de alto nivel;
- novos syscalls de input;
- transporte de bytes.

## Critério de Saida Desta Agenda

Pode virar PR quando houver decisao escrita sobre:

- lista final de intrinsics de input;
- assinatura e retorno de cada intrinsic;
- superfícies de input suportadas no MVP;
- IDs logicos suportados;
- lista das syscalls de input a serem removidas;
- integracao com ISA, verifier e tracing.