From 6ffaf8fd08bf6d21a81cbc974f45a96b9cb39412 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Sat, 7 Mar 2026 18:06:43 +0000 Subject: [PATCH] agendas discussion --- ...d-builtins-protocol-and-system-services.md | 103 ------------------ ...tem-fault-semantics-and-control-surface.md | 2 +- .../agendas/011-vm-owned-stateful-core.md | 89 +++++++++++++++ .../agendas/012-vm-owned-random-service.md | 69 ++++++++++++ docs/runtime/agendas/README.md | 30 ++--- 5 files changed, 176 insertions(+), 117 deletions(-) delete mode 100644 docs/runtime/agendas/001-vm-owned-builtins-protocol-and-system-services.md create mode 100644 docs/runtime/agendas/011-vm-owned-stateful-core.md create mode 100644 docs/runtime/agendas/012-vm-owned-random-service.md diff --git a/docs/runtime/agendas/001-vm-owned-builtins-protocol-and-system-services.md b/docs/runtime/agendas/001-vm-owned-builtins-protocol-and-system-services.md deleted file mode 100644 index 20fef1f0..00000000 --- a/docs/runtime/agendas/001-vm-owned-builtins-protocol-and-system-services.md +++ /dev/null @@ -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`, 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` 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. diff --git a/docs/runtime/agendas/010-system-fault-semantics-and-control-surface.md b/docs/runtime/agendas/010-system-fault-semantics-and-control-surface.md index ca4df76d..b4fe05c2 100644 --- a/docs/runtime/agendas/010-system-fault-semantics-and-control-surface.md +++ b/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 diff --git a/docs/runtime/agendas/011-vm-owned-stateful-core.md b/docs/runtime/agendas/011-vm-owned-stateful-core.md new file mode 100644 index 00000000..574ddbf8 --- /dev/null +++ b/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` 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` 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. + diff --git a/docs/runtime/agendas/012-vm-owned-random-service.md b/docs/runtime/agendas/012-vm-owned-random-service.md new file mode 100644 index 00000000..cca40ac7 --- /dev/null +++ b/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. + diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index de39bd53..f8d5ee8f 100644 --- a/docs/runtime/agendas/README.md +++ b/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` -2. `002-filesystem-surface-and-semantics.md` -3. `003-filesystem-fault-semantics.md` -4. `004-gfx-fault-semantics-and-command-contract.md` -5. `005-audio-fault-semantics-and-surface.md` -6. `006-asset-fault-semantics-and-surface.md` -7. `007-runtime-edge-test-plan.md` -8. `008-packed-cartridge-loader-pmc.md` -9. `009-system-run-cart.md` -10. `010-system-fault-semantics-and-control-surface.md` +1. `011-vm-owned-stateful-core.md` +2. `012-vm-owned-random-service.md` +3. `002-filesystem-surface-and-semantics.md` +4. `003-filesystem-fault-semantics.md` +5. `004-gfx-fault-semantics-and-command-contract.md` +6. `005-audio-fault-semantics-and-surface.md` +7. `006-asset-fault-semantics-and-surface.md` +8. `007-runtime-edge-test-plan.md` +9. `008-packed-cartridge-loader-pmc.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`