prometeu-runtime/docs/runtime/agendas/010-input-intrinsics-surface.md

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.