# 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.