agendas discussion

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

@@ -1,103 +0,0 @@
-# Agenda - VM-Owned Stateful Protocol (Pos-v1)
-
-## Escopo Ja Fechado (Nao Reabrir)
-
-Input VM-owned v1 ja foi fechado nas specs abaixo e saiu desta agenda:
-
-- `../specs/06-input-peripheral.md`
-- `../specs/16-host-abi-and-syscalls.md`
-- `../specs/16a-syscall-policies.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`
-- `../specs/06-input-peripheral.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.

docs/runtime/agendas/010-system-fault-semantics-and-control-surface.md

@@ -8,7 +8,7 @@ Hoje:
 
 - `SystemHasCart` responde diretamente;
 - `SystemRunCart` ainda nao tem efeito real;
-- a agenda `001` resolve semantica funcional, mas nao fecha por si so a politica de fault do dominio.
+- a agenda `009` resolve semantica funcional, mas nao fecha por si so a politica de fault do dominio.
 
 ## Dor
 

docs/runtime/agendas/011-vm-owned-stateful-core.md

@@ -0,0 +1,89 @@
+# Agenda - VM-Owned Stateful Core
+
+## Problema
+
+O runtime ja tem VM-owned intrinsics read-only (input), mas ainda nao tem contrato canonico para recursos VM-owned stateful.
+
+Sem esse core, cada novo servico tende a inventar:
+
+- modelo proprio de handle/referencia;
+- semantica propria de lifecycle;
+- shape proprio de ABI/intrinsic;
+- regras ad hoc de validacao/verifier.
+
+## Alvo da Discussao
+
+Fechar o contrato base de recursos VM-owned stateful que sera reutilizado por dominios como random, colecoes runtime-owned e futuros recursos de app model.
+
+## O Que Precisa Ser Definido
+
+1. Modelo de referencia stateful.
+   Definir:
+   - `HeapRef<TBuiltin>` como padrao ou alternativa canonica;
+   - regra anti-stale (generation/version);
+   - ownership e validade de referencia.
+
+2. Lifecycle minimo.
+   Definir contrato de:
+   - `create`;
+   - `read/query`;
+   - `update`;
+   - `destroy`.
+
+3. Execucao de intrinsic stateful.
+   Definir:
+   - como o executor recebe contexto VM/runtime;
+   - como manter compatibilidade com intrinsics atuais read-only.
+
+4. ABI/meta por operacao.
+   Definir metadados obrigatorios:
+   - `arg_slots`;
+   - `ret_slots`;
+   - efeito;
+   - custo;
+   - determinismo.
+
+5. Verifier/toolchain/disasm.
+   Definir:
+   - validacoes estaticas obrigatorias;
+   - regras de diagnostico para mismatch de assinatura/layout;
+   - compatibilidade binaria por versao.
+
+6. Politica de fault/status.
+   Definir fronteira entre:
+   - `status` operacional de dominio;
+   - `Trap` estrutural;
+   - `Panic` por inconsistencia interna.
+
+## Open Questions de Arquitetura
+
+1. `HeapRef<TBuiltin>` sera obrigatorio para todos os recursos stateful?
+2. Como evitar aliasing perigoso com multiplas referencias para o mesmo recurso?
+3. Como roots/GC/lifetime se comportam para recursos vivos entre frames?
+4. Quais gatilhos justificariam mecanismo simbolico adicional no futuro (alem de IDs finais)?
+5. Qual contrato minimo de metadata precisamos versionar para garantir 1:1 FE/backend/runtime?
+
+## Dependencias
+
+- `../virtual-machine/ISA_CORE.md`
+- `../specs/16-host-abi-and-syscalls.md`
+- `../specs/16a-syscall-policies.md`
+- `../specs/06-input-peripheral.md`
+- `../decisions/003-vm-owned-byte-transfer-protocol.md`
+
+## Fora de Escopo
+
+- surface especifica de random (fica na agenda `012`);
+- window/app model detalhado;
+- redesign de `HOSTCALL`/`SYSCALL`;
+- UX de linguagens de frontend.
+
+## Criterio de Saida Desta Agenda
+
+Pode virar PR quando houver decisao escrita sobre:
+
+- contrato stateful VM-owned reutilizavel;
+- forma definitiva de referencia/validade/lifecycle;
+- metadados canonicos de ABI para intrinsic stateful;
+- regras de verifier/disasm/compatibilidade binaria.
+

docs/runtime/agendas/012-vm-owned-random-service.md

@@ -0,0 +1,69 @@
+# Agenda - VM-Owned Random Service
+
+## Problema
+
+Precisamos de random como primeiro consumidor stateful VM-owned, mas sem fechar um contrato minimo o dominio pode nascer incoerente e nao deterministico.
+
+## Alvo da Discussao
+
+Fechar o perfil minimo de random VM-owned em cima do core da agenda `011`.
+
+## O Que Precisa Ser Definido
+
+1. Surface minima do servico.
+   Fechar operacoes como:
+   - `new(seed) -> rng_ref`;
+   - `next(rng_ref) -> int`;
+   - `destroy(rng_ref)`.
+
+2. Determinismo e replay.
+   Definir:
+   - seed explicita obrigatoria;
+   - regra de reproducao frame a frame;
+   - comportamento esperado em replay.
+
+3. Lifecycle e validade.
+   Definir:
+   - como lidar com `rng_ref` invalido/stale;
+   - relacao com GC;
+   - destruicao explicita vs cleanup por GC.
+
+4. Fault/status do dominio.
+   Definir:
+   - quais erros sao `status`;
+   - quais casos viram `Trap`;
+   - inexistencia de `Panic` operacional.
+
+5. Metadados e versionamento.
+   Definir IDs/version das operacoes de random para garantir mapeamento 1:1 FE/backend/runtime.
+
+## Open Questions de Arquitetura
+
+1. v1 aceita apenas modo deterministico por seed ou tambem entropy host?
+2. `next` retorna apenas `int` ou precisamos variantes (`u32`, `float`) no mesmo ciclo?
+3. precisamos de clone/split de gerador no MVP?
+4. destruicao explicita deve ser obrigatoria para certificacao/custo ou opcional?
+
+## Dependencias
+
+- `011-vm-owned-stateful-core.md`
+- `../virtual-machine/ISA_CORE.md`
+- `../specs/16-host-abi-and-syscalls.md`
+- `../specs/16a-syscall-policies.md`
+
+## Fora de Escopo
+
+- entropy nao deterministica como contrato base;
+- PRNGs multiplos no mesmo ciclo de fechamento;
+- APIs de colecoes stateful;
+- window/app model.
+
+## Criterio de Saida Desta Agenda
+
+Pode virar PR quando houver decisao escrita sobre:
+
+- surface minima de random VM-owned;
+- contrato de determinismo/replay;
+- fault/status de random;
+- IDs/versionamento e validacoes de verifier para as operacoes do dominio.
+

docs/runtime/agendas/README.md

@@ -10,7 +10,6 @@ Objetivo:
 
 As agendas atuais são:
 
-- `001-vm-owned-builtins-protocol-and-system-services.md`
 - `002-filesystem-surface-and-semantics.md`
 - `003-filesystem-fault-semantics.md`
 - `004-gfx-fault-semantics-and-command-contract.md`
@@ -20,25 +19,29 @@ As agendas atuais são:
 - `008-packed-cartridge-loader-pmc.md`
 - `009-system-run-cart.md`
 - `010-system-fault-semantics-and-control-surface.md`
+- `011-vm-owned-stateful-core.md`
+- `012-vm-owned-random-service.md`
 
 ## Sequenciamento Recomendado
 
 Ordem sugerida para discussão e futura execução:
 
-1. `001-vm-owned-builtins-protocol-and-system-services.md`
+1. `011-vm-owned-stateful-core.md`
-2. `002-filesystem-surface-and-semantics.md`
+2. `012-vm-owned-random-service.md`
-3. `003-filesystem-fault-semantics.md`
+3. `002-filesystem-surface-and-semantics.md`
-4. `004-gfx-fault-semantics-and-command-contract.md`
+4. `003-filesystem-fault-semantics.md`
-5. `005-audio-fault-semantics-and-surface.md`
+5. `004-gfx-fault-semantics-and-command-contract.md`
-6. `006-asset-fault-semantics-and-surface.md`
+6. `005-audio-fault-semantics-and-surface.md`
-7. `007-runtime-edge-test-plan.md`
+7. `006-asset-fault-semantics-and-surface.md`
-8. `008-packed-cartridge-loader-pmc.md`
+8. `007-runtime-edge-test-plan.md`
-9. `009-system-run-cart.md`
+9. `008-packed-cartridge-loader-pmc.md`
-10. `010-system-fault-semantics-and-control-surface.md`
+10. `009-system-run-cart.md`
+11. `010-system-fault-semantics-and-control-surface.md`
 
 Justificativa curta:
 
-- `001` vem primeiro para fechar o protocolo VM-owned stateful que destrava extensoes como random/window resources sem mexer em syscall host-backed.
+- `011` vem primeiro para fechar o protocolo stateful VM-owned reutilizavel, sem mexer na fronteira host-backed.
+- `012` vem em seguida para fechar random como primeiro consumidor do core stateful.
 - `002` e `003` ficam na sequencia para fechar `fs` com superficie e fault semantics consistentes.
 - `004`, `005` e `006` consolidam fault semantics por dominio com base em `16a`.
 - `007` vem depois para transformar as decisoes em cobertura de regressao na borda do runtime.
@@ -47,7 +50,8 @@ Justificativa curta:
 
 Dependências principais:
 
-- `001` deve alinhar com `06`, `16` e `16a`, alem da decisao `003`
+- `011` deve alinhar com `06`, `16` e `16a`, alem da decisao `003`
+- `012` depende da `011` e de `16`/`16a`
 - `002` depende da decisao `003` e de `16a`
 - `003` depende da decisao `003`, de `16a` e da `002`
 - `004` depende de `16a`