From 833798e14329f4bfd4f1ef22c271d12749e46972 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Sat, 7 Mar 2026 18:26:05 +0000 Subject: [PATCH] agendas discussion --- .../agendas/011-vm-owned-stateful-core.md | 97 ++-------- .../agendas/012-vm-owned-random-service.md | 5 +- docs/runtime/agendas/README.md | 29 ++- .../006-vm-owned-stateful-core-contract.md | 171 ++++++++++++++++++ docs/runtime/decisions/README.md | 1 + 5 files changed, 204 insertions(+), 99 deletions(-) create mode 100644 docs/runtime/decisions/006-vm-owned-stateful-core-contract.md diff --git a/docs/runtime/agendas/011-vm-owned-stateful-core.md b/docs/runtime/agendas/011-vm-owned-stateful-core.md index 574ddbf8..a61f4077 100644 --- a/docs/runtime/agendas/011-vm-owned-stateful-core.md +++ b/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; -- semantica propria de lifecycle; -- shape proprio de ABI/intrinsic; -- regras ad hoc de validacao/verifier. +## O Que Foi Fechado -## Alvo da Discussao +1. Modelo canonico com `HeapRef` e regra anti-stale por generation. +2. Lifecycle minimo (`create/read-update/destroy`) para servicos stateful. +3. Manutencao do caminho `INTRINSIC ` 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. - 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. +## Follow-up +- consolidar implementacao de identity/registry de intrinsic no frontend/backend/runtime; +- fechar random em `012-vm-owned-random-service.md`. diff --git a/docs/runtime/agendas/012-vm-owned-random-service.md b/docs/runtime/agendas/012-vm-owned-random-service.md index cca40ac7..fcaab4c5 100644 --- a/docs/runtime/agendas/012-vm-owned-random-service.md +++ b/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. - diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index f8d5ee8f..e8b9998a 100644 --- a/docs/runtime/agendas/README.md +++ b/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` -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` +1. `012-vm-owned-random-service.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` Justificativa curta: -- `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. +- `011` foi fechada pela decisao `006`. +- `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 `011` e de `16`/`16a` +- `012` depende da decisao `006` 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` diff --git a/docs/runtime/decisions/006-vm-owned-stateful-core-contract.md b/docs/runtime/decisions/006-vm-owned-stateful-core-contract.md new file mode 100644 index 00000000..d670b64e --- /dev/null +++ b/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`. +- 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 `. +- 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 +INTRINSIC +INTRINSIC +``` + +## 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. + diff --git a/docs/runtime/decisions/README.md b/docs/runtime/decisions/README.md index 16f4102f..91775f63 100644 --- a/docs/runtime/decisions/README.md +++ b/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: