prometeu-runtime/docs/runtime/learn/mental-model-status-first-and-fault-thinking.md

Status-First and Fault Thinking

Status: pedagogical Companion specs:

• ../specs/16a-syscall-policies.md
• ../specs/04-gfx-peripheral.md
• ../specs/05-audio-peripheral.md
• ../specs/08-save-memory-and-memcard.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-audio-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-retired-fault-and-input-decisions.md

Use os snapshots para contexto historico. Use as specs para o contrato normativo atual.