diff --git a/docs/runtime/agendas/017-vm-owned-builtins-protocol-and-system-services.md b/docs/runtime/agendas/017-vm-owned-builtins-protocol-and-system-services.md new file mode 100644 index 00000000..1f4f6dc0 --- /dev/null +++ b/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. diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index 42a25312..09388988 100644 --- a/docs/runtime/agendas/README.md +++ b/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` -5. `013-audio-fault-semantics-and-surface.md` -6. `014-gfx-fault-semantics-and-command-contract.md` -7. `001-system-run-cart.md` -8. `015-system-fault-semantics-and-control-surface.md` -9. `009-filesystem-surface-and-semantics.md` -10. `016-filesystem-fault-semantics.md` -11. `010-input-intrinsics-surface.md` -12. `011-input-frame-semantics-and-portability.md` -13. `005-runtime-edge-test-plan.md` -14. `002-packed-cartridge-loader-pmc.md` +4. `017-vm-owned-builtins-protocol-and-system-services.md` +5. `012-asset-fault-semantics-and-surface.md` +6. `013-audio-fault-semantics-and-surface.md` +7. `014-gfx-fault-semantics-and-command-contract.md` +8. `001-system-run-cart.md` +9. `015-system-fault-semantics-and-control-surface.md` +10. `009-filesystem-surface-and-semantics.md` +11. `016-filesystem-fault-semantics.md` +12. `010-input-intrinsics-surface.md` +13. `011-input-frame-semantics-and-portability.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`