# Agenda - VM-Owned Builtins Protocol and System Services

## Problema

O modelo de `syscall` atual atende bem chamadas host-backed e nao deve ser quebrado.

Ao mesmo tempo, falta um protocolo formal para chamadas e dados VM-owned entre guest e VM para casos como:

- input;
- random;
- window system integrado ao SO;
- builtins com leitura/escrita e lifecycle.

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.

## Dor

- 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.

## Alvo da Discussao

Definir um protocolo canonico de comunicacao guest <-> VM para operacoes VM-owned, preservando:

- `syscall` como fronteira host-backed existente;
- compatibilidade com o ABI atual de slots;
- determinismo por frame.

## O Que Precisa Ser Definido

1. Plano de chamada VM-owned.
   Definir:
   - ponto de entrada no bytecode (`INTRINSIC` com registry formal, ou outra forma);
   - namespace de IDs;
   - versionamento por operacao;
   - metadados canonicos (`arg_slots`, `ret_slots`, layout, custo, efeito, determinismo).

2. Plano de dados builtin.
   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.

3. Modelo de recursos VM-owned.
   Definir:
   - formato de handle (incluindo estrategia anti-stale);
   - ownership;
   - lifecycle (`create`, `read`, `update`, `destroy`);
   - invariantes de validade.

4. Perfil de input no protocolo.
   Fechar:
   - como `Input.getPad()` e `Input.getTouch()` mapeiam para o protocolo VM-owned;
   - relacao com as syscalls atuais de input no periodo de transicao;
   - garantia de snapshot congelado por frame para leitura deterministica.

5. Perfil de random no protocolo.
   Fechar:
   - API minima (`getRandom` e variantes, se houver);
   - PRNG deterministico e regras de seed;
   - politicas de reproducibilidade.

6. Perfil de window system no protocolo.
   Fechar contrato minimo para:
   - criacao e destruicao de janelas;
   - leitura/escrita de estado de janela;
   - fila de eventos;
   - relacao com foco e input.

7. Modelo de fault/status.
   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.

## 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.

## Dependencias

- `../virtual-machine/ISA_CORE.md`
- `../specs/16-host-abi-and-syscalls.md`
- `../specs/16a-syscall-policies.md`
- `../decisions/003-vm-owned-byte-transfer-protocol.md`
- `../decisions/004-host-fault-taxonomy.md`

## Fora de Escopo

- redesenhar o modelo de syscall host-backed;
- UX final do window manager;
- detalhes de compositor/renderizacao de UI;
- protocolo de rede/distribuicao remota.

## Critério 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.