agenda discussion and decisions
This commit is contained in:
@@ -0,0 +1,151 @@
|
||||
# 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`.
|
||||
@@ -17,3 +17,4 @@ Regra de uso:
|
||||
Decisoes atuais:
|
||||
|
||||
- `003-vm-owned-byte-transfer-protocol.md`
|
||||
- `004-host-fault-taxonomy.md`
|
||||
|
||||
Reference in New Issue
Block a user