agendas discussion
This commit is contained in:
parent
6ffaf8fd08
commit
833798e143
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -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<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.
|
||||
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.
|
||||
## Follow-up
|
||||
|
||||
- consolidar implementacao de identity/registry de intrinsic no frontend/backend/runtime;
|
||||
- fechar random em `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.
|
||||
|
||||
|
||||
@ -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`
|
||||
|
||||
171
docs/runtime/decisions/006-vm-owned-stateful-core-contract.md
Normal file
171
docs/runtime/decisions/006-vm-owned-stateful-core-contract.md
Normal file
@ -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.
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user