156 lines
4.7 KiB
Markdown
156 lines
4.7 KiB
Markdown
# Status-First and Fault Thinking
|
|
|
|
Status: pedagogical
|
|
Companion specs:
|
|
|
|
- [`../specs/16a-syscall-policies.md`](../specs/16a-syscall-policies.md)
|
|
- [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
|
|
- [`../specs/05-audio-peripheral.md`](../specs/05-audio-peripheral.md)
|
|
- [`../specs/08-save-memory-and-memcard.md`](../specs/08-save-memory-and-memcard.md)
|
|
- [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
|
|
|
|
PROMETEU usa um modelo status-first para impedir que a borda host/runtime esconda erro operacional como silencio, `Trap` indevido ou `Panic` acidental.
|
|
|
|
## Core Split
|
|
|
|
O modelo mental certo e:
|
|
|
|
- `Trap` para violacao estrutural de contrato;
|
|
- `status` para resultado operacional observavel;
|
|
- `Panic` para quebra de invariante interna.
|
|
|
|
Uma forma curta de pensar:
|
|
|
|
- guest chamou errado: `Trap`;
|
|
- guest chamou certo, mas o dominio nao conseguiu concluir: `status`;
|
|
- runtime quebrou por dentro: `Panic`.
|
|
|
|
## Why This Exists
|
|
|
|
Sem essa separacao, sistemas host-backed tendem a degradar para uma mistura ruim de:
|
|
|
|
- `void` em operacoes que falham de verdade;
|
|
- fallback implicito;
|
|
- no-op silencioso;
|
|
- escalacao de erro de app para `Panic`.
|
|
|
|
Status-first existe para tornar o comportamento:
|
|
|
|
- observavel;
|
|
- deterministico;
|
|
- testavel;
|
|
- documentavel por dominio.
|
|
|
|
## Return Shape Rule
|
|
|
|
A regra pratica mais importante e simples:
|
|
|
|
- se a operacao pode falhar operacionalmente, ela deve retornar `status`;
|
|
- se a operacao nao tem caminho real de falha operacional, ela pode ser `void`.
|
|
|
|
Isso impede contratos em que o guest nao consegue distinguir:
|
|
|
|
- sucesso;
|
|
- rejeicao;
|
|
- ausencia de efeito;
|
|
- backend indisponivel;
|
|
- asset ou recurso ausente.
|
|
|
|
## Silent Failure Is Not Allowed
|
|
|
|
Em PROMETEU, erro operacional nao pode ser maquiado como:
|
|
|
|
- sucesso implicito;
|
|
- ignorar a chamada;
|
|
- fallback automatico para outro recurso;
|
|
- `Trap`, quando o problema nao e estrutural;
|
|
- `Panic`, quando o problema nao e interno.
|
|
|
|
Se o guest pode perceber a diferenca, essa diferenca deve aparecer como `status`.
|
|
|
|
## Reading The Boundary
|
|
|
|
Quando estiver lendo ou desenhando uma syscall, use esta sequencia:
|
|
|
|
1. A chamada esta estruturalmente correta?
|
|
2. O guest tem permissao/capability para usar a surface?
|
|
3. O dominio consegue executar a operacao com os recursos atuais?
|
|
4. Ha payload adicional que so faz sentido quando o `status` indica sucesso?
|
|
|
|
Essa leitura tende a produzir contratos mais limpos, por exemplo:
|
|
|
|
- `asset.load(...) -> (status, handle)`
|
|
- `mem.slot_read(...) -> (status, payload, bytes_read)`
|
|
- operacoes sem falha real continuam `void`
|
|
|
|
## Domain Intuition
|
|
|
|
### GFX
|
|
|
|
Em `gfx`, o problema tipico nao e "a syscall explodiu". O problema tipico e:
|
|
|
|
- sprite inexistente;
|
|
- indice fora da faixa operacional;
|
|
- argumento invalido para a operacao;
|
|
- chamada sem efeito real.
|
|
|
|
Esses casos pedem `status`, nao silencio.
|
|
|
|
### Audio
|
|
|
|
Em `audio`, o modelo impede coisas como:
|
|
|
|
- voz invalida ser ignorada;
|
|
- sample ausente virar fallback mudo;
|
|
- parametro fora de faixa parecer sucesso.
|
|
|
|
Audio deve se comportar como periferico finito e explicito, nao como "som automatico".
|
|
|
|
### Asset
|
|
|
|
Em `asset`, status-first separa melhor:
|
|
|
|
- erro de request;
|
|
- lifecycle assíncrono;
|
|
- commit/cancel invalido;
|
|
- handle desconhecido.
|
|
|
|
Isso combina com o modelo de request + poll + commit, em vez de fingir que carregamento e instantaneo.
|
|
|
|
### FS / MEMCARD
|
|
|
|
Em persistencia, status-first impede a pior categoria de erro: "pareceu salvar".
|
|
|
|
Casos como:
|
|
|
|
- slot vazio;
|
|
- storage cheio;
|
|
- conflito;
|
|
- corrupcao;
|
|
- backend indisponivel;
|
|
|
|
precisam aparecer como estado observavel, porque o jogo e o Hub/OS precisam reagir a isso.
|
|
|
|
## Design Smells
|
|
|
|
Sinais de que o contrato ainda esta ruim:
|
|
|
|
- a operacao pode falhar, mas retorna `void`;
|
|
- existe fallback implicito para recurso default;
|
|
- a documentacao depende de "na pratica nao deve acontecer";
|
|
- `Panic` aparece para erro de input do app;
|
|
- o mesmo dominio mistura no-op silencioso e status explicito;
|
|
- payload de retorno nao deixa claro quando e valido.
|
|
|
|
## Historical Anchors
|
|
|
|
Este guia consolida a intuicao que apareceu primeiro nestes snapshots historicos:
|
|
|
|
- [`historical-gfx-status-first-fault-and-return-contract.md`](historical-gfx-status-first-fault-and-return-contract.md)
|
|
- [`historical-audio-status-first-fault-and-return-contract.md`](historical-audio-status-first-fault-and-return-contract.md)
|
|
- [`historical-asset-status-first-fault-and-return-contract.md`](historical-asset-status-first-fault-and-return-contract.md)
|
|
- [`historical-game-memcard-slots-surface-and-semantics.md`](historical-game-memcard-slots-surface-and-semantics.md)
|
|
- [`historical-retired-fault-and-input-decisions.md`](historical-retired-fault-and-input-decisions.md)
|
|
|
|
Use os snapshots para contexto historico. Use as specs para o contrato normativo atual.
|