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 index 1f4f6dc0..ed47b8cb 100644 --- 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 @@ -29,11 +29,51 @@ Definir um protocolo canonico de comunicacao guest <-> VM para operacoes VM-owne - compatibilidade com o ABI atual de slots; - determinismo por frame. +## Achados Consolidados Desta Rodada + +- 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 ` 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 `; + - `kind=vm` -> `INTRINSIC `. +- 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. Definir: - - ponto de entrada no bytecode (`INTRINSIC` com registry formal, ou outra forma); + - 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). @@ -51,16 +91,18 @@ Definir um protocolo canonico de comunicacao guest <-> VM para operacoes VM-owne - ownership; - lifecycle (`create`, `read`, `update`, `destroy`); - invariantes de validade. + - politica de singleton vs instancia alocada para builtins de snapshot (ex.: `Pad`, `Touch`). 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; + - 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. 5. Perfil de random no protocolo. Fechar: - - API minima (`getRandom` e variantes, se houver); + - API minima (`RndG.pcg32(seed) -> RngRef` e/ou `getRandom`), incluindo superficie inicial oficial; - PRNG deterministico e regras de seed; - politicas de reproducibilidade. @@ -93,6 +135,22 @@ Definir um protocolo canonico de comunicacao guest <-> VM para operacoes VM-owne - 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: @@ -102,6 +160,22 @@ Esta agenda deve discutir explicitamente, alem de input/random/window: - text input para apps com janelas; - notificacoes de sistema para app. +## 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`, 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? + ## Dependencias - `../virtual-machine/ISA_CORE.md`