agendas discussion

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

@@ -1,89 +1,26 @@
-# Agenda - VM-Owned Stateful Core
+# Agenda 011 - VM-Owned Stateful Core (Fechada)
 
-## Problema
+## Status
 
-O runtime ja tem VM-owned intrinsics read-only (input), mas ainda nao tem contrato canonico para recursos VM-owned stateful.
+Fechada pela decisao:
 
-Sem esse core, cada novo servico tende a inventar:
+- `../decisions/006-vm-owned-stateful-core-contract.md`
 
-- modelo proprio de handle/referencia;
+## O Que Foi Fechado
-- semantica propria de lifecycle;
-- shape proprio de ABI/intrinsic;
-- regras ad hoc de validacao/verifier.
 
-## Alvo da Discussao
+1. Modelo canonico com `HeapRef<TBuiltinState>` e regra anti-stale por generation.
+2. Lifecycle minimo (`create/read-update/destroy`) para servicos stateful.
+3. Manutencao do caminho `INTRINSIC <id_final>` sem tabela adicional.
+4. Metadata obrigatoria por operacao (`arg_slots`, `ret_slots`, efeito, determinismo, custo).
+5. Fronteira de fault (`status` operacional, `Trap` estrutural, `Panic` interno).
+6. Direcao de verifier/disasm/compatibilidade binaria para intrinsic stateful.
 
-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.
+## Efeito Pratico
 
-## O Que Precisa Ser Definido
+- Agenda `012` passa a consumir essa base para fechar random.
+- Implementacoes VM-owned stateful devem seguir a decisao `006` como contrato.
 
-1. Modelo de referencia stateful.
+## Follow-up
-   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.
 
+- consolidar implementacao de identity/registry de intrinsic no frontend/backend/runtime;
+- fechar random em `012-vm-owned-random-service.md`.

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

@@ -6,7 +6,7 @@ Precisamos de random como primeiro consumidor stateful VM-owned, mas sem fechar
 
 ## Alvo da Discussao
 
-Fechar o perfil minimo de random VM-owned em cima do core da agenda `011`.
+Fechar o perfil minimo de random VM-owned em cima do core definido na decisao `006`.
 
 ## O Que Precisa Ser Definido
 
@@ -46,7 +46,7 @@ Fechar o perfil minimo de random VM-owned em cima do core da agenda `011`.
 
 ## Dependencias
 
-- `011-vm-owned-stateful-core.md`
+- `../decisions/006-vm-owned-stateful-core-contract.md`
 - `../virtual-machine/ISA_CORE.md`
 - `../specs/16-host-abi-and-syscalls.md`
 - `../specs/16a-syscall-policies.md`
@@ -66,4 +66,3 @@ Pode virar PR quando houver decisao escrita sobre:
 - contrato de determinismo/replay;
 - fault/status de random;
 - IDs/versionamento e validacoes de verifier para as operacoes do dominio.
-

docs/runtime/agendas/README.md

@@ -19,29 +19,27 @@ 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. `011-vm-owned-stateful-core.md`
+1. `012-vm-owned-random-service.md`
-2. `012-vm-owned-random-service.md`
+2. `002-filesystem-surface-and-semantics.md`
-3. `002-filesystem-surface-and-semantics.md`
+3. `003-filesystem-fault-semantics.md`
-4. `003-filesystem-fault-semantics.md`
+4. `004-gfx-fault-semantics-and-command-contract.md`
-5. `004-gfx-fault-semantics-and-command-contract.md`
+5. `005-audio-fault-semantics-and-surface.md`
-6. `005-audio-fault-semantics-and-surface.md`
+6. `006-asset-fault-semantics-and-surface.md`
-7. `006-asset-fault-semantics-and-surface.md`
+7. `007-runtime-edge-test-plan.md`
-8. `007-runtime-edge-test-plan.md`
+8. `008-packed-cartridge-loader-pmc.md`
-9. `008-packed-cartridge-loader-pmc.md`
+9. `009-system-run-cart.md`
-10. `009-system-run-cart.md`
+10. `010-system-fault-semantics-and-control-surface.md`
-11. `010-system-fault-semantics-and-control-surface.md`
 
 Justificativa curta:
 
-- `011` vem primeiro para fechar o protocolo stateful VM-owned reutilizavel, sem mexer na fronteira host-backed.
+- `011` foi fechada pela decisao `006`.
-- `012` vem em seguida para fechar random como primeiro consumidor do core stateful.
+- `012` e o primeiro consumidor da base stateful VM-owned fechada em `006`.
 - `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.
@@ -50,8 +48,7 @@ Justificativa curta:
 
 Dependências principais:
 
-- `011` deve alinhar com `06`, `16` e `16a`, alem da decisao `003`
+- `012` depende da decisao `006` e de `16`/`16a`
-- `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`

docs/runtime/decisions/006-vm-owned-stateful-core-contract.md

@@ -0,0 +1,171 @@
+# Decision Record - VM-Owned Stateful Core Contract
+
+## Status
+
+Accepted
+
+## Contexto
+
+O runtime ja possui intrinsics VM-owned read-only (input), mas faltava um contrato canonico para recursos VM-owned stateful.
+
+Sem esse contrato, cada dominio novo tende a divergir em:
+
+- referencia/handle;
+- lifecycle;
+- shape de ABI por operacao;
+- politica de fault/status;
+- validacao de verifier/disasm.
+
+## Decisao
+
+### 1. Fronteira host-backed permanece inalterada
+
+- `HOSTCALL`/`SYSCALL` continuam sendo o caminho host-backed.
+- Esta decisao nao introduz redesign de host boundary.
+
+### 2. Modelo canonico de recurso stateful
+
+- Recurso stateful VM-owned e representado por `HeapRef<TBuiltinState>`.
+- Validade da referencia segue `index + generation` (anti-stale).
+- Nao sera introduzido, nesta etapa, um modelo paralelo de handle numerico tipado.
+
+### 3. Lifecycle minimo obrigatorio
+
+Todo dominio stateful deve explicitar:
+
+- `create`;
+- `read/query`;
+- `update`;
+- `destroy`.
+
+### 4. Forma de invocacao
+
+- O caminho de execucao permanece `INTRINSIC <id_final>`.
+- Nao ha tabela adicional de pre-load para VM-owned stateful.
+- IDs finais continuam versionados por operacao.
+
+### 5. Metadata canonica por operacao intrinsic stateful
+
+Cada operacao deve declarar, no minimo:
+
+- `arg_slots`;
+- `ret_slots`;
+- `effect` (read/create/update/destroy);
+- `determinism`;
+- `may_allocate`;
+- `cost_hint`.
+
+### 6. Fault model para VM-owned stateful
+
+- `Trap` para erro estrutural (shape de chamada invalido, stale handle, kind invalido).
+- `status` para falha operacional de dominio.
+- `Panic` apenas para inconsistencia interna do runtime.
+
+### 7. GC/lifetime e aliasing
+
+- Recursos stateful vivem na heap VM e seguem roots normais de GC.
+- `destroy` existe para encerramento explicito quando o dominio exigir.
+- Multipla referencia para o mesmo recurso nao muda semantica de ownership; validade segue regras de `HeapRef`.
+
+### 8. Verifier/toolchain/disasm
+
+- Verifier deve validar assinatura (`arg_slots`/`ret_slots`) e identidade da operacao.
+- Disasm deve expor identidade canonica (nome + versao), nao apenas id numerico.
+- Mudanca breaking exige nova versao da operacao.
+
+### 9. Compatibilidade binaria
+
+- Mesma versao de operacao nao muda contrato de slots nem efeito.
+- Operacao inexistente/incompativel deve falhar em carga/verificacao.
+
+## Estado Atual do Frontend PBS (Studio)
+
+Estado observado:
+
+- SDK interface ja modela VM-owned builtin surfaces com `declare builtin type` + `IntrinsicCall`.
+- Lowering ja emite `CALL_INTRINSIC` e pipeline ja converte para opcode `INTRINSIC`.
+
+Lacunas relevantes para stateful:
+
+- resolucao de intrinsic no frontend ainda e indexada por `sourceMethodName` simples;
+- ids de intrinsic no frontend ainda usam `hash(canonicalName#version)` como placeholder.
+
+Direcao exigida por esta decisao:
+
+- resolucao de intrinsic deve considerar identidade canonica sem ambiguidade de receiver;
+- ids finais de intrinsic devem vir de registry canonico FE/backend/runtime, nao de hash provisoria.
+
+## Exemplos (Ilustrativos, nao normativos)
+
+### Exemplo A - Surface de SDK para random stateful na PBS
+
+```text
+[BuiltinType(name = "random", version = 1)]
+declare builtin type Random() {
+  [IntrinsicCall(name = "new", version = 1)]
+  fn new(seed: int) -> RandomRng;
+}
+
+[BuiltinType(name = "random.rng", version = 1)]
+declare builtin type RandomRng() {
+  [IntrinsicCall(name = "next", version = 1)]
+  fn next() -> int;
+
+  [IntrinsicCall(name = "destroy", version = 1)]
+  fn destroy() -> int; // status
+}
+
+[BuiltinConst(target = "random", name = "global", version = 1)]
+declare const Random: Random;
+```
+
+### Exemplo B - Uso em userland PBS
+
+```text
+import { Random } from @sdk:random;
+
+fn tick() -> void {
+  let rng = Random.new(12345);
+  let a = rng.next();
+  let b = rng.next();
+  let _s = rng.destroy();
+}
+```
+
+### Exemplo C - Contraste de lowering
+
+```text
+CALL_INTRINSIC random.new@1
+CALL_INTRINSIC random.rng.next@1
+CALL_INTRINSIC random.rng.destroy@1
+```
+
+No bytecode final:
+
+```text
+INTRINSIC <id_random_new_v1>
+INTRINSIC <id_random_rng_next_v1>
+INTRINSIC <id_random_rng_destroy_v1>
+```
+
+## Consequencias
+
+### Positivas
+
+- cria base unica para dominios stateful VM-owned;
+- evita proliferacao de protocolos ad hoc por servico;
+- preserva fronteira host-backed atual;
+- prepara random como primeiro consumidor sem redesenho posterior.
+
+### Custos
+
+- exige evolucao de registry/identity de intrinsic no frontend/backend;
+- exige endurecimento de verifier/disasm para contrato stateful;
+- exige disciplina de versionamento por operacao.
+
+## Follow-up Obrigatorio
+
+- agenda `011-vm-owned-stateful-core.md` deve ser considerada fechada por esta decisao;
+- agenda `012-vm-owned-random-service.md` passa a ser o primeiro consumidor desta base;
+- specs `16`/`16a` devem absorver o contrato stateful quando a implementacao ficar estavel.
+

docs/runtime/decisions/README.md

@@ -17,6 +17,7 @@ Regra de uso:
 Decisoes ativas:
 
 - `003-vm-owned-byte-transfer-protocol.md`
+- `006-vm-owned-stateful-core-contract.md`
 
 Decisoes aposentadas que ja viraram spec: