# Agenda - VM-Owned Stateful Protocol (Pos-v1)

## Escopo Ja Fechado (Nao Reabrir)

Input VM-owned v1 ja foi fechado na decisao abaixo e saiu desta agenda:

- `../decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`

## Problema Desta Agenda

Falta fechar o protocolo VM-owned para casos stateful que exigem recurso vivo, ownership e lifecycle, por exemplo:

- random com instancia/estado (`RngRef`);
- estruturas VM-owned (ex.: map/set/colecoes runtime-owned);
- window system para app model futuro;
- filas/eventos VM-owned.

Ja existe uma base de data plane low-level de bytes (decisao `003`), mas ainda falta o contrato stateful tipado para builtins/servicos com `HeapRef` ou handle equivalente VM-owned.

## Alvo da Discussao

Definir um protocolo canonico de recursos VM-owned stateful, preservando:

- fronteira host-backed atual intacta;
- ABI estavel por slots;
- versionamento e verificacao 1:1 por operacao;
- determinismo quando requerido pelo dominio.

## O Que Ainda Precisa Ser Definido

1. Modelo canonico de recurso VM-owned stateful.
   Definir:
   - representacao de handle/referencia (`HeapRef<TBuiltin>`, handle tipado, ou hibrido);
   - ownership e regra anti-stale (generation/version);
   - lifecycle minimo (`create`, `read`, `update`, `destroy`).

2. Evolucao da execucao de intrinsic para servicos stateful.
   Definir:
   - como a operacao intrinsic recebe contexto VM/runtime de forma segura;
   - como manter compatibilidade com intrinsics atuais read-only.

3. Contrato de ABI/meta para operacoes VM-owned stateful.
   Definir:
   - metadados canonicos por operacao (`arg_slots`, `ret_slots`, efeito, custo, determinismo);
   - namespace/versionamento de IDs;
   - criterio de compatibilidade binaria entre versoes.

4. Perfil de random stateful.
   Fechar:
   - superficie minima (`seed` explicita, instancia, leitura de proximo valor);
   - regra de determinismo/replay;
   - politica de status/fault.

5. Perfil de window system/app model.
   Fechar contrato minimo para:
   - criacao/destruicao de janelas;
   - leitura/escrita de estado;
   - fila de eventos;
   - relacao com foco/input sem quebrar determinismo do runtime.

6. Verifier/toolchain/disasm.
   Definir:
   - validacoes estaticas obrigatorias;
   - requisitos de assembler/disassembler para intrinsics stateful;
   - estrategia de diagnostico para mismatch de assinatura/layout.

## Open Questions de Arquitetura

1. `HeapRef<TBuiltin>` sera o padrao unico para recurso stateful ou teremos handles numericos tipados em alguns dominios?
2. Qual shape final da interface de intrinsic com contexto VM/runtime?
3. Qual politica de roots/GC/lifetime para recursos VM-owned vivos entre frames?
4. Como impedir aliasing perigoso quando multiplas referencias apontarem para o mesmo recurso stateful?
5. Random stateful deve permitir modo nao deterministico (entropy host) ou apenas deterministico por seed?
6. Qual taxonomia minima de `status` para servicos VM-owned stateful sem criar enum global monolitico?
7. Quais gatilhos tecnicos justificariam introduzir no futuro um mecanismo simbolico adicional (ex.: tabela dedicada), em vez de manter IDs finais?
8. Como garantir que extensoes para window/app model nao enrijeçam a base e continuem language-agnostic?

## 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`
- `../decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`

## Fora de Escopo

- reabrir a decisao de input v1;
- redesenhar o caminho host-backed (`HOSTCALL`/`SYSCALL`);
- UX final de compositor/tema/desktop do window manager;
- protocolo de rede/distribuicao remota.

## Criterio de Saida Desta Agenda

Pode virar PR quando houver decisao escrita sobre:

- contrato stateful VM-owned (resource model + lifecycle);
- forma definitiva de referencia/handle com validade;
- evolucao do executor de intrinsic com contexto VM/runtime;
- perfil minimo fechado para random stateful e base de window resources;
- regras de verificacao e compatibilidade binaria por versao.