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

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

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

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.
   - 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;
   - 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 (`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.
   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.

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

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

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