clean up
This commit is contained in:
@@ -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`.
|
||||
-114
@@ -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`
|
||||
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user