add agenda discussion

docs/runtime/agendas/017-vm-owned-builtins-protocol-and-system-services.md

@@ -0,0 +1,128 @@
+# 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.

docs/runtime/agendas/README.md

@@ -21,6 +21,7 @@ As agendas atuais são:
 - `014-gfx-fault-semantics-and-command-contract.md`
 - `015-system-fault-semantics-and-control-surface.md`
 - `016-filesystem-fault-semantics.md`
+- `017-vm-owned-builtins-protocol-and-system-services.md`
 
 ## Sequenciamento Recomendado
 
@@ -29,23 +30,25 @@ Ordem sugerida para discussão e futura execução:
 1. `007-single-canonical-architecture.md`
 2. `008-hardware-specs-reorganization.md`
 3. `006-break-monolith-runtime.md`
-4. `012-asset-fault-semantics-and-surface.md`
+4. `017-vm-owned-builtins-protocol-and-system-services.md`
-5. `013-audio-fault-semantics-and-surface.md`
+5. `012-asset-fault-semantics-and-surface.md`
-6. `014-gfx-fault-semantics-and-command-contract.md`
+6. `013-audio-fault-semantics-and-surface.md`
-7. `001-system-run-cart.md`
+7. `014-gfx-fault-semantics-and-command-contract.md`
-8. `015-system-fault-semantics-and-control-surface.md`
+8. `001-system-run-cart.md`
-9. `009-filesystem-surface-and-semantics.md`
+9. `015-system-fault-semantics-and-control-surface.md`
-10. `016-filesystem-fault-semantics.md`
+10. `009-filesystem-surface-and-semantics.md`
-11. `010-input-intrinsics-surface.md`
+11. `016-filesystem-fault-semantics.md`
-12. `011-input-frame-semantics-and-portability.md`
+12. `010-input-intrinsics-surface.md`
-13. `005-runtime-edge-test-plan.md`
+13. `011-input-frame-semantics-and-portability.md`
-14. `002-packed-cartridge-loader-pmc.md`
+14. `005-runtime-edge-test-plan.md`
+15. `002-packed-cartridge-loader-pmc.md`
 
 Justificativa curta:
 
 - `007` vem primeiro porque elimina ambiguidade sobre qual documento manda.
 - `008` vem em seguida porque reorganiza o terreno documental onde specs e arquitetura se apoiam.
 - `006` entra depois porque refactor estrutural grande sem documentação estável tende a cristalizar decisões erradas.
+- `017` entra cedo para fechar um protocolo VM-owned unico (input/random/window/builtins) sem contaminar a fronteira de syscall host-backed.
 - a decisao `003` ja fechou o contrato base para trafego de bytes VM-owned e agora deve ser consumida, nao rediscutida aqui.
 - a decisao `004` ja fechou a taxonomia base de falhas host-backed e agora deve ser consumida pelos dominios.
 - `012`, `013` e `014` quebram o refactor de fault semantics por dominio onde a dor ja esta visivel no codigo.
@@ -61,6 +64,7 @@ Dependências principais:
 
 - `008` depende de `007`
 - `006` depende de `007`
+- `017` depende de `007` e deve alinhar com `16`/`16a`, alem das decisoes `003` e `004`
 - `009` depende das decisoes `003` e `004`
 - `012` depende da decisao `004`
 - `013` depende da decisao `004`