Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
3
0
Fork 0
Code Pull Requests Activity

agendas discussion

Browse Source
This commit is contained in:
bQUARKz 2026-03-07 18:06:43 +00:00
parent 75edde476b
commit 6ffaf8fd08
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
5 changed files with 176 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

@ -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

89
docs/runtime/agendas/011-vm-owned-stateful-core.md Normal file
View File

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

69
docs/runtime/agendas/012-vm-owned-random-service.md Normal file
View File

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

30
docs/runtime/agendas/README.md
View File

@ -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`