152 lines
4.6 KiB
Markdown
152 lines
4.6 KiB
Markdown
# 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 `001-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:
|
|
|
|
- `012-asset-fault-semantics-and-surface.md`
|
|
- `013-audio-fault-semantics-and-surface.md`
|
|
- `014-gfx-fault-semantics-and-command-contract.md`
|
|
- `015-system-fault-semantics-and-control-surface.md`
|
|
- `016-filesystem-fault-semantics.md`
|
|
|
|
`016-filesystem-fault-semantics.md` so deve ser discutida depois da `009-filesystem-surface-and-semantics.md`.
|