This commit is contained in:
2026-03-24 13:40:49 +00:00
parent a99f11027c
commit 75edde476b
14 changed files with 82 additions and 291 deletions
@@ -1,151 +0,0 @@
# Decision Record - Host Fault Taxonomy
## Status
Accepted
## Contexto
A fronteira host-backed do runtime misturava quatro coisas diferentes:
- fault recuperavel de servico;
- quebra terminal do app/VM;
- falha estrutural grave do runtime;
- indisponibilidade do host.
Ao mesmo tempo, a decisao `003-vm-owned-byte-transfer-protocol.md` ja fixou uma direcao importante:
- quando existir contrato funcional de retorno, o protocolo deve preferir `status`;
- `Trap` nao deve ser usado para carregar erro operacional comum;
- `Panic` deve ficar restrito a inconsistencia interna.
O codigo atual ainda revela severidade errada em varios pontos, por exemplo:
- `AssetLoad` promovendo erro operacional para `Panic`;
- helpers de extracao promovendo argumento ausente para `Panic`;
- `VmFault::Unavailable` sendo degradado para `Panic` no loop da VM.
## Decisao
### 1. Classes canonicas
A taxonomia canonica na fronteira host-backed passa a ser:
- `status`
- `Trap`
- `Panic`
`Unavailable` deixa de ser classe desejada do modelo.
### 2. `status`
- `status` representa fault recuperavel do servico.
- Cada dominio pode ter seus proprios codigos/status.
- Nao sera criado enum global unico de status para todos os dominios.
- Quando a surface da operacao comportar retorno funcional, deve-se preferir `status` ao maximo.
Exemplos:
- recurso ausente;
- handle desconhecido de dominio;
- path nao encontrado;
- permissao negada;
- EOF;
- escrita parcial/falha operacional;
- indisponibilidade funcional recuperavel.
### 3. `Trap`
- `Trap` quebra a VM/app atual.
- O firmware assume a partir da tela de crash.
- `Trap` deve ser usado para erro estrutural de chamada, uso incorreto da ABI ou contrato que o guest nao recupera em runtime.
Exemplos:
- tipo de argumento errado;
- aridade invalida;
- syscall ou intrinsic invalido;
- capability ausente;
- shape de chamada impossivel para a ABI.
### 4. `Panic`
- `Panic` representa falha estrutural grave do runtime.
- `Panic` nao descreve erro do app, e sim risco de quebra do proprio Prometeu/runtime/host integration.
- `Panic` fica reservado para bug interno ou inconsistencia de implementacao.
Exemplos:
- metadata incoerente;
- mismatch entre `ret_slots` declarados e retorno efetivo;
- invariantes internas quebradas;
- branch impossivel do runtime.
### 5. `Unavailable`
- `Unavailable` torna-se candidato a remocao do modelo.
- A direcao aceita e:
- indisponibilidade funcional recuperavel deve virar `status`;
- colapso estrutural de integracao host/runtime deve virar `Panic`;
- `Unavailable` nao deve ser expandido para novos dominios.
## Aplicacao por Dominio
### Assets
- `assets` e dominio `status-first`.
- `AssetLoad` nao deve promover erro operacional comum para `Panic`.
- `AssetStatus` confirma que o dominio ja tem semantica de status.
- `commit`/`cancel` podem precisar de surface mais rica para evitar `Panic` indevido.
### Audio
- `audio` e dominio command-driven.
- A direcao aceita e `Trap` estrutural + no-op/fallback deterministico ou `status` quando a surface passar a expor isso.
- `audio` nao deve ser `panic-first`.
### Gfx
- `gfx` e dominio command-style.
- A direcao aceita e `Trap` para erro estrutural de chamada e no-op/fallback/clamp para casos de dominio, conforme a semantica de cada comando.
- `Panic` em `gfx` deve ficar restrito a colapso estrutural do runtime grafico.
### System
- `system` deve evitar `Panic` para falhas funcionais normais.
- A taxonomia final de `run_cart` depende da agenda `009-system-run-cart.md`.
### Byte transfer
Para `read`/`write` e ops que reutilizem a decisao `003`:
- erros observaveis do protocolo devem virar `status`;
- `Trap` praticamente sai da jogada;
- `Panic` fica restrito a inconsistencia interna.
## Consequencias
### Positivas
- o runtime separa erro recuperavel de colapso terminal;
- dominios host-backed ficam livres para usar `HostReturn` de forma rica;
- `Panic` encolhe e passa a carregar gravidade real;
- crash reports e telemetria ficam semanticamente melhores.
### Custos
- algumas surfaces publicas podem precisar mudar para devolver `status`;
- o uso atual de `VmFault` precisara de limpeza por dominio;
- o loop da VM precisara deixar de tratar `Unavailable` como caminho normal.
## Follow-up Obrigatorio
As seguintes agendas derivam desta decisao:
- `006-asset-fault-semantics-and-surface.md`
- `005-audio-fault-semantics-and-surface.md`
- `004-gfx-fault-semantics-and-command-contract.md`
- `010-system-fault-semantics-and-control-surface.md`
- `003-filesystem-fault-semantics.md`
`003-filesystem-fault-semantics.md` so deve ser discutida depois da `002-filesystem-surface-and-semantics.md`.
@@ -1,114 +0,0 @@
# Decision Record - V1 VM-Owned Input Intrinsics and Language-Agnostic Surface
## Status
Accepted
## Contexto
Para destravar bytecode/backend no v1, precisamos fechar o caminho de input sem:
- quebrar a fronteira host-backed atual (`HOSTCALL`/`SYSCALL`);
- copiar estruturas grandes de input na stack a cada consulta;
- acoplar a decisao a uma unica linguagem de frontend.
As discussoes das agendas historicas de input (intrinsics surface + frame semantics) e da agenda VM-owned convergiram para:
- input deve sair do caminho de syscall legado;
- input deve ser VM-owned, leitura-only e deterministico por frame;
- a linguagem pode expor API encadeada ergonomica (ex.: PBS), mas isso nao define o contrato normativo do runtime.
## Decisao
### 1. Fronteira host-backed permanece inalterada
- `HOSTCALL` + tabela `SYSC` + `SYSCALL` continuam como caminho host-backed oficial.
- Esta decisao nao unifica nem altera o contrato de syscall atual.
### 2. Input v1 e VM-owned por intrinsics finais
- Input v1 e exposto por intrinsics VM-owned.
- O backend emite `INTRINSIC <id_final>` diretamente.
- Nao sera introduzida tabela de pre-load adicional para VM-owned no v1.
### 3. Surface de linguagem e livre (nao hardcoded)
- O contrato normativo e de VM/bytecode, nao de sintaxe de uma linguagem.
- Frontends podem expor APIs diferentes, desde que mapeiem 1:1 para intrinsics versionados.
- Exemplo PBS (nao normativo): `Input.pad().up().hold()`.
### 4. Semantica de snapshot por frame
- O host captura estado de input no inicio do frame logico.
- A VM usa esse snapshot congelado durante todo o frame.
- Leitura repetida no mesmo frame retorna o mesmo valor observavel.
### 5. Modelo de dispositivos v1
- Elementos obrigatorios de input em todas as plataformas: `button`, `pad`, `touch`.
- Perfil Prometeu handheld v1: um `pad` e um `touch` single-point.
- `touch` preserva ultimo valor conhecido (incluindo arraste) conforme snapshot vigente.
### 6. Politica de acesso e fault
- Input e leitura-only para userland.
- Nao ha capability gate nem impacto de certificacao para leitura de input.
- Falhas operacionais devem seguir a taxonomia de fault vigente (`status` quando aplicavel; `Trap` para erro estrutural).
### 7. Consequencia de arquitetura imediata
- Builtins de input devem ser tratados como referencias/superficies VM-owned, sem copia "mastodonte" por chamada.
- O executor de intrinsic atual pode atender casos read-only de snapshot no v1.
- Casos stateful com alocacao/lifecycle (ex.: RNG com instancia, mapas VM-owned, window resources) ficam para agenda posterior.
## Exemplo de Mapeamento (Ilustrativo, nao normativo)
Objetivo da linguagem:
```text
Input.pad().up().hold()
```
Possivel lowering:
```text
INTRINSIC input.pad@1
INTRINSIC input.pad.up@1
INTRINSIC input.button.hold@1
```
Os nomes acima sao apenas ilustrativos; o contrato real e o ID/versionamento canonico do intrinsic definido pelo toolchain/runtime.
## Consequencias
### Positivas
- destrava o fechamento do bytecode para backend no v1;
- elimina dependencia de syscall para consulta de input;
- preserva compatibilidade da infraestrutura host-backed existente;
- evita acoplamento prematuro a uma unica linguagem.
### Custos
- exige registry de intrinsics VM-owned consistente entre FE/backend/runtime;
- exige disciplina de versionamento 1:1 por operacao;
- adia para etapa posterior o protocolo stateful completo com `HeapRef`.
## Fora de Escopo
- protocolo generico VM-owned stateful com lifecycle de recursos;
- random com instancia alocada e ownership explicito;
- window system/app model completo;
- redesign de `HOSTCALL`/`SYSCALL`.
## Follow-up Obrigatorio
- as agendas historicas de input (`010-input-intrinsics-surface.md` e `011-input-frame-semantics-and-portability.md`) foram encerradas e seu conteudo foi absorvido por esta decisao;
- agenda `001-vm-owned-builtins-protocol-and-system-services.md` fica restrita a pos-v1 (stateful/`HeapRef`).
Specs a alinhar/confirmar:
- `../virtual-machine/ISA_CORE.md`
- `../specs/16-host-abi-and-syscalls.md`
- `../specs/06-input-peripheral.md`
- `../specs/07-touch-peripheral.md`
+10 -3
View File
@@ -14,8 +14,15 @@ Regra de uso:
- decision records existem para registrar o que foi decidido;
- quando uma agenda for resolvida, ela deve sair de `agendas/` e virar decision record aqui.
Decisoes atuais:
Decisoes ativas:
- `003-vm-owned-byte-transfer-protocol.md`
- `004-host-fault-taxonomy.md`
- `005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
Decisoes aposentadas que ja viraram spec:
- `004-host-fault-taxonomy.md` -> `../specs/16a-syscall-policies.md`
- `005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md` -> `../specs/06-input-peripheral.md`, `../specs/16-host-abi-and-syscalls.md`, `../specs/16a-syscall-policies.md`
Racional historico (nao normativo):
- `../learn/retired-decisions-004-005-history.md`