prometeu-runtime/docs/runtime/agendas/011-input-frame-semantics-and-portability.md

Agenda - Input Frame Semantics and Portability

Problema

O dominio de input ja tem uma direcao documental, mas ainda precisa de fechamento operacional na borda runtime <-> plataforma.

Nesta agenda, input significa o dominio formado por:

• pad;
• touch.

Sem isso, intrinsics de input podem existir com nome certo e semantica errada.

Hoje a dor nao eh apenas teorica:

• pad e touch ja sao latched no host no inicio do frame;
• Button ja eh a unidade de estado usada por pad e pelo toque ativo;
• mas o runtime ainda expoe a leitura desse estado por syscalls em vez de intrinsics.

Dor

• ambiguidades sobre quando o input e amostrado;
• risco de divergencia entre plataformas sobre pressed/held/released do pad;
• risco de divergencia sobre touch ativo, posicao, multitouch e ausencia de touch;
• replay, certificacao e reproducibilidade ficam dependentes de interpretacao;
• edge cases de foco, multiplos dispositivos e conflitos de direcao ficam sem dono.
• a borda guest pode acabar observando input como consulta host-driven, quando o modelo correto eh leitura de estado ja congelado no frame.

Alvo da Discussao

Fixar a semantica temporal e de portabilidade do dominio de input.

pad e touch sao os dois subconjuntos principais do contrato. button entra apenas como parte da semantica de pad.

O Que Precisa Ser Definido

1. Momento de amostragem. Em que ponto do frame o estado e capturado e congelado.

2. Semantica de estado. Definir formalmente:

   • pressed no pad;
   • released no pad;
   • held no pad;
   • transicao entre frames.

3. Semantica de touch. Definir formalmente, se touch fizer parte do contrato:

   • ponto ativo ou inativo;
   • coordenadas;
   • multitouch ou touch unico;
   • persistencia entre frames.

4. Determinismo e replay. Como input gravado, injetado ou reproduzido conversa com o runtime.

5. Regras de portabilidade. O que deve ser igual em todas as plataformas e o que pode variar.

6. Edge cases. Exemplos:

   • perda de foco;
   • multiplos devices;
   • direcoes opostas simultaneas no pad;
   • ausencia de determinado dispositivo fisico;
   • plataforma sem touch;
   • diferenca de resolucao ou area de toque.

7. Relacao com CAP e certificacao. Como consultas de input aparecem em custo e relatorios. Esta agenda tambem precisa decidir se input continua ou nao exigindo capability de syscall depois da migracao para intrinsic.

Dependencias

• 010-input-intrinsics-surface.md;
• spec de input;
• modelo de frame do runtime.

Fora de Escopo

• opcode ou encoding do intrinsic;
• mapeamento detalhado por plataforma;
• bytes e heap.

Critério de Saida Desta Agenda

Pode virar PR quando houver decisao escrita sobre:

• momento de amostragem;
• semantica formal dos intrinsics de input do MVP;
• regras de replay e reproducibilidade;
• edge cases minimos que o runtime precisa tratar;
• posicao explicita sobre a saida de input da fronteira de syscall;
• impactos em CAP e certificacao.