implemented intrinsecs de input and specs adjustment

This commit is contained in:
2026-03-24 13:40:48 +00:00
parent 1bd921979f
commit 10dfc7bf15
17 changed files with 957 additions and 1089 deletions
@@ -1,135 +1,31 @@
# Agenda - Input Intrinsics Surface
# Agenda 010 - Input Intrinsics Surface (Fechada no v1)
## Problema
## Status
`input` ja esta conceitualmente do lado de intrinsics, nao de syscalls, mas a superficie concreta desse dominio ainda nao esta congelada.
Fechada para v1 pela decisao:
Nesta agenda, `input` significa o dominio formado por:
- `../decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
- `pad`;
- `touch`.
## O Que Foi Fechado
Sem uma agenda propria, o dominio de input corre o risco de ficar:
1. Input sai da fronteira de syscall e entra em VM-owned intrinsics.
2. Superficie obrigatoria do dominio: `button`, `pad`, `touch`.
3. Sem `axis` no v1.
4. Snapshot de input congelado no inicio do frame logico.
5. API de linguagem pode ser encadeada/ergonomica, mas o contrato normativo e language-agnostic.
6. Sem capability gate e sem custo de certificacao por syscall para leitura de input.
- espalhado pela spec de input;
- implícito no ISA;
- indefinido no verifier;
- lembrado tarde demais na fase de implementacao.
## Efeito Pratico
Hoje existe uma ambiguidade concreta no runtime:
- Toolchain/backend devem emitir `INTRINSIC <id_final>` para input.
- Syscalls de input legadas devem ser removidas/desativadas da superficie oficial.
- 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.
## Risco Residual
Exemplos atuais no runtime:
- Nenhum bloqueador do bytecode v1 permanece nesta agenda.
- Novas discussoes de input so devem reabrir em caso de mudanca de versao de contrato.
- `InputGetPad`
- `InputGetPadPressed`
- `InputGetPadReleased`
- `InputGetPadHold`
- `InputPadSnapshot`
- `InputTouchSnapshot`
- `TouchGetX`
- `TouchGetY`
- `TouchIsDown`
- `TouchIsPressed`
- `TouchIsReleased`
- `TouchGetHold`
- `TouchGetFinger`
- `PadGetUp` ate `PadGetSelect`
## Follow-up
## 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.
- Validar alinhamento de specs (`06`, `16`, `16a`) com a decisao `005`.
- Validar runtime/verifier contra IDs finais de input intrinsics.
@@ -1,95 +1,35 @@
# Agenda - Input Frame Semantics and Portability
# Agenda 011 - Input Frame Semantics and Portability (Fechada no v1)
## Problema
## Status
O dominio de input ja tem uma direcao documental, mas ainda precisa de fechamento operacional na borda runtime <-> plataforma.
Fechada para v1 pela decisao:
Nesta agenda, `input` significa o dominio formado por:
- `../decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
- `pad`;
- `touch`.
## O Que Foi Fechado
Sem isso, intrinsics de input podem existir com nome certo e semantica errada.
1. A amostragem de input ocorre antes do frame logico.
2. O estado observado pelo guest fica congelado durante todo o frame.
3. Semantica de `button`:
- `pressed` no frame de transicao up -> down
- `released` no frame de transicao down -> up
- `down` enquanto pressionado
- `hold` contando frames pressionado
4. `touch` e single-point no perfil handheld v1, com coordenadas `(x, y)` e persistencia do ultimo estado no snapshot vigente.
5. `pad` e `touch` sao obrigatorios como elementos do contrato de plataforma.
6. Leitura de input nao participa de capability gate de syscall nem de scoring de certificacao por syscall.
Hoje a dor nao eh apenas teorica:
## Efeito Pratico
- `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.
- O runtime deve expor input como leitura deterministica de snapshot VM-owned.
- O host deve fornecer os sinais necessarios para pad/touch a cada frame.
## Dor
## Risco Residual
- 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.
- Nenhum bloqueador de bytecode v1 permanece nesta agenda.
- Edge cases de app model/window system ficam para agendas futuras (fora de input v1).
## Alvo da Discussao
## Follow-up
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.
- Manter `06-input-peripheral.md` e `07-touch-peripheral.md` alinhadas com esta semantica.
- Cobrir no runtime testes de regressao para determinismo por frame.
@@ -1,180 +1,88 @@
# Agenda - VM-Owned Builtins Protocol and System Services
# Agenda - VM-Owned Stateful Protocol (Pos-v1)
## Problema
## Base Ja Fechada (Nao Reabrir Nesta Agenda)
O modelo de `syscall` atual atende bem chamadas host-backed e nao deve ser quebrado.
Esta agenda passa a considerar fechado no v1:
Ao mesmo tempo, falta um protocolo formal para chamadas e dados VM-owned entre guest e VM para casos como:
- input VM-owned por `INTRINSIC <id_final>`;
- sem tabela dedicada de preload VM-owned no v1;
- `HOSTCALL`/`SYSCALL` host-backed preservados sem redesign;
- surface de linguagem livre (exemplo PBS apenas ilustrativo, nao normativo);
- snapshot de input congelado por frame;
- input sem capability/telemetria de certificacao.
- input;
- random;
- window system integrado ao SO;
- builtins com leitura/escrita e lifecycle.
Fonte normativa do recorte v1:
Hoje ja existe base para bytes VM-owned (decisao `003`), mas ainda nao existe contrato equivalente para valores builtin, recursos tipados e handles VM-owned.
- `../decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
## Dor
## Problema Desta Agenda
- sem protocolo, cada dominio tende a criar shape ad-hoc de stack e retorno;
- surfaces de linguagem (FE) e backend podem divergir do runtime real;
- faltam regras canonicas para criar/ler/escrever/destruir recursos VM-owned;
- verifier e toolchain ficam sem alvo estavel para validacao de chamadas VM-owned;
- discussoes de input/random/window tendem a virar agendas grandes e misturadas.
Falta fechar o protocolo VM-owned para casos stateful que exigem recurso vivo, ownership e lifecycle, por exemplo:
- random com instancia/estado (`RngRef`);
- estruturas VM-owned (ex.: map/set/colecoes runtime-owned);
- window system para app model futuro;
- filas/eventos VM-owned.
Ja existe uma base de data plane low-level de bytes (decisao `003`), mas ainda falta o contrato stateful tipado para builtins/servicos com `HeapRef` ou handle equivalente VM-owned.
## Alvo da Discussao
Definir um protocolo canonico de comunicacao guest <-> VM para operacoes VM-owned, preservando:
Definir um protocolo canonico de recursos VM-owned stateful, preservando:
- `syscall` como fronteira host-backed existente;
- compatibilidade com o ABI atual de slots;
- determinismo por frame.
- fronteira host-backed atual intacta;
- ABI estavel por slots;
- versionamento e verificacao 1:1 por operacao;
- determinismo quando requerido pelo dominio.
## Achados Consolidados Desta Rodada
## O Que Ainda Precisa Ser Definido
- manter separacao por camadas:
- decisao `003` como `Byte Transfer Core` (data plane low-level);
- protocolo VM-owned desta agenda como `Service Control Plane` para builtins e servicos.
- o guest nao recebe handle host-owned e nao acessa memoria host-owned diretamente.
- servicos VM-owned podem internamente delegar para host/sistema operacional, sem expor essa borda para userland.
- `syscall` host-backed atual permanece valido; esta agenda nao redesenha essa fronteira.
- input e random passam a ser tratados como servicos VM-owned, com retorno de builtins/handles VM-owned.
- para input, a direcao preferida e leitura de snapshot congelado por frame com semantica de registrador (sem copia grande de dados por chamada).
## Consolidado Parcial - `HOSTCALL` com `kind` (`host` | `vm`)
- proposta candidata:
- manter `HOSTCALL <index>` no artefato pre-load;
- substituir `SYSC` por uma tabela unificada de bindings (nome provisorio: `CALLS`/`BIND`);
- cada entrada declara `kind`, `module`, `name`, `version`, `arg_slots`, `ret_slots`.
- regra de resolucao:
- a decisao `host` vs `vm` ocorre somente no loader;
- loader resolve e patcha deterministamente:
- `kind=host` -> `SYSCALL <id>`;
- `kind=vm` -> `INTRINSIC <id>`.
- o runtime nunca executa branch dinamico `host|vm` em tempo de execucao.
- `kind` separa semanticas sem colapsar contratos:
- `host` continua host-backed (capability/politicas do dominio host);
- `vm` segue contrato VM-owned (builtins/recursos/estado interno da VM).
- ponto tecnico critico identificado:
- o executor atual de intrinsic usa `fn(&[Value])` e nao recebe contexto da VM/runtime;
- servicos VM-owned stateful (input/map/window/random com recurso) exigem evolucao dessa interface.
- regra de ABI para VM-owned:
- operacoes devem mapear 1:1 para diretivas versionadas;
- `arg_slots` e `ret_slots` fixos por operacao/versao (sem shape dinamico).
- extensoes previstas (nao bloqueadoras do recorte inicial):
- lifecycle de handles VM-owned com anti-stale/generation;
- politica explicita de roots/GC para recursos vivos.
- ponto ainda pendente de fechamento nesta agenda:
- semantica de determinismo para random e, futuramente, fila/eventos de window system.
## O Que Precisa Ser Definido
1. Plano de chamada VM-owned.
1. Modelo canonico de recurso VM-owned stateful.
Definir:
- ponto de entrada no bytecode para VM-owned:
- `INTRINSIC` com registry formal; ou
- `HOSTCALL + kind=vm` com patch de loader para `INTRINSIC`;
- namespace de IDs;
- versionamento por operacao;
- metadados canonicos (`arg_slots`, `ret_slots`, layout, custo, efeito, determinismo).
- representacao de handle/referencia (`HeapRef<TBuiltin>`, handle tipado, ou hibrido);
- ownership e regra anti-stale (generation/version);
- lifecycle minimo (`create`, `read`, `update`, `destroy`).
2. Plano de dados builtin.
2. Evolucao da execucao de intrinsic para servicos stateful.
Definir:
- como builtins sao representados em slots;
- quando um builtin e inline e quando vira handle;
- regras de leitura/escrita/atualizacao em stack e heap;
- regras de compatibilidade de layout entre versoes.
- como a operacao intrinsic recebe contexto VM/runtime de forma segura;
- como manter compatibilidade com intrinsics atuais read-only.
3. Modelo de recursos VM-owned.
3. Contrato de ABI/meta para operacoes VM-owned stateful.
Definir:
- formato de handle (incluindo estrategia anti-stale);
- ownership;
- lifecycle (`create`, `read`, `update`, `destroy`);
- invariantes de validade.
- politica de singleton vs instancia alocada para builtins de snapshot (ex.: `Pad`, `Touch`).
- metadados canonicos por operacao (`arg_slots`, `ret_slots`, efeito, custo, determinismo);
- namespace/versionamento de IDs;
- criterio de compatibilidade binaria entre versoes.
4. Perfil de input no protocolo.
4. Perfil de random stateful.
Fechar:
- como `Input.getPad()` e `Input.getTouch()` mapeiam para o protocolo VM-owned;
- se a API retorna ref singleton (`Input.getPad() -> PadRef`) ou recebe destino (`Input.getPad(dst_ref)`), e por que;
- relacao com as syscalls atuais de input no periodo de transicao (se houver);
- garantia de snapshot congelado por frame para leitura deterministica.
- superficie minima (`seed` explicita, instancia, leitura de proximo valor);
- regra de determinismo/replay;
- politica de status/fault.
5. Perfil de random no protocolo.
Fechar:
- API minima (`RndG.pcg32(seed) -> RngRef` e/ou `getRandom`), incluindo superficie inicial oficial;
- PRNG deterministico e regras de seed;
- politicas de reproducibilidade.
6. Perfil de window system no protocolo.
5. Perfil de window system/app model.
Fechar contrato minimo para:
- criacao e destruicao de janelas;
- leitura/escrita de estado de janela;
- criacao/destruicao de janelas;
- leitura/escrita de estado;
- fila de eventos;
- relacao com foco e input.
- relacao com foco/input sem quebrar determinismo do runtime.
7. Modelo de fault/status.
6. Verifier/toolchain/disasm.
Definir:
- fronteira entre erro estrutural (`Trap`) e resultado operacional (`status`);
- como erros de handle/recurso/estado invalido sao expostos.
8. Integracao com verifier e toolchain.
Definir:
- validacoes estaticas minimas;
- regras de emissao no backend;
- requisitos para decode/disasm/assembler.
9. Politica de CAP, certificacao e telemetria para VM-owned.
Definir:
- se VM-owned usa ou nao capability;
- como custo entra em certificacao;
- o que e observavel em telemetria.
10. Migração.
Definir:
- como coexistem superficies antigas e novas;
- quando e como descontinuar chamadas legadas.
## Shape Inicial de Referencia (Nao Decisao)
Este shape e apenas base de discussao para fechar bytecode/ABI, sem efeito normativo ate decisao formal:
```text
vm_service_call(service_id, op_id, args...) -> (status, ret...)
```
Exemplos candidatos:
- `Input.getPad() -> (status, pad_ref)`
- `Input.getTouch() -> (status, touch_ref)`
- `RndG.pcg32(seed) -> (status, rng_ref)`
Onde `pad_ref`, `touch_ref` e `rng_ref` sao builtins/handles VM-owned.
## Sistemas Candidatos Para Cobertura
Esta agenda deve discutir explicitamente, alem de input/random/window:
- frame clock/tick index para consultas deterministicas de tempo de jogo;
- event queue VM-owned para UI/app;
- text input para apps com janelas;
- notificacoes de sistema para app.
- validacoes estaticas obrigatorias;
- requisitos de assembler/disassembler para intrinsics stateful;
- estrategia de diagnostico para mismatch de assinatura/layout.
## Open Questions de Arquitetura
1. Qual e o entrypoint de pre-load para VM-owned: `HOSTCALL + kind=vm` em tabela unificada, ou tabela dedicada?
2. Como representar retorno de builtin em slots: `HeapRef<TBuiltin>`, handle numerico tipado, ou forma hibrida?
3. Como evoluir a interface de intrinsic para receber contexto VM/runtime (alem de `args`) sem quebrar o que ja existe?
4. Input usa singleton por dispositivo/frame ou instancia nova por chamada?
5. Quais campos de `Pad` e `Touch` sao estritamente read-only para guest, e como bloquear escrita indevida?
6. Qual politica de lifetime dos snapshots de input entre frames (substituicao, aliasing, invalidacao)?
7. Random sera estritamente deterministico por seed explicitamente passado, ou existe modo sem seed (host entropy)?
8. Qual taxonomia canonica de `status` compartilhada entre servicos VM-owned (input/random/window)?
9. Como o verifier valida compatibilidade entre assinatura esperada pelo FE e metadados reais do service registry?
10. Como garantir compatibilidade binaria quando um builtin evoluir layout entre versoes?
11. Como tratar custo/certificacao para VM-owned sem reintroduzir modelo de capability desnecessario?
12. Window system exigira fila/event loop VM-owned; como evitar acoplamento indevido com scheduler do runtime?
13. Qual estrategia de migracao para remover chamadas legadas de input sem quebrar toolchain antiga?
1. `HeapRef<TBuiltin>` sera o padrao unico para recurso stateful ou teremos handles numericos tipados em alguns dominios?
2. Qual shape final da interface de intrinsic com contexto VM/runtime?
3. Qual politica de roots/GC/lifetime para recursos VM-owned vivos entre frames?
4. Como impedir aliasing perigoso quando multiplas referencias apontarem para o mesmo recurso stateful?
5. Random stateful deve permitir modo nao deterministico (entropy host) ou apenas deterministico por seed?
6. Qual taxonomia minima de `status` para servicos VM-owned stateful sem criar enum global monolitico?
7. Quais gatilhos tecnicos justificariam introduzir no futuro um mecanismo simbolico adicional (ex.: tabela dedicada), em vez de manter IDs finais?
8. Como garantir que extensoes para window/app model nao enrijeçam a base e continuem language-agnostic?
## Dependencias
@@ -183,20 +91,21 @@ Esta agenda deve discutir explicitamente, alem de input/random/window:
- `../specs/16a-syscall-policies.md`
- `../decisions/003-vm-owned-byte-transfer-protocol.md`
- `../decisions/004-host-fault-taxonomy.md`
- `../decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
## Fora de Escopo
- redesenhar o modelo de syscall host-backed;
- UX final do window manager;
- detalhes de compositor/renderizacao de UI;
- reabrir a decisao de input v1;
- redesenhar o caminho host-backed (`HOSTCALL`/`SYSCALL`);
- UX final de compositor/tema/desktop do window manager;
- protocolo de rede/distribuicao remota.
## Critério de Saida Desta Agenda
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- contrato canonico do protocolo VM-owned (call plane + data plane);
- shape e lifecycle de builtins/handles;
- perfil minimo fechado para input, random e window system;
- regras de fault/status e verificacao;
- plano de migracao sem quebra da fronteira de syscall existente.
- contrato stateful VM-owned (resource model + lifecycle);
- forma definitiva de referencia/handle com validade;
- evolucao do executor de intrinsic com contexto VM/runtime;
- perfil minimo fechado para random stateful e base de window resources;
- regras de verificacao e compatibilidade binaria por versao.