prometeu-runtime/docs/runtime/learn/008-gfx-status-first-fault-and-return-contract.md

Decision Record - GFX Status-First Fault and Return Contract

Status

Accepted

Contexto

A agenda 004-gfx-fault-semantics-and-command-contract.md consolidou que o dominio gfx estava com ambiguidade entre:

• Trap/Panic desnecessarios para erro operacional;
• no-op silencioso;
• chamadas void em operacoes que podem falhar operacionalmente.

Para alinhar com 16a, foi decidido fechar uma politica status-first no dominio gfx.

Decisao

1. Fronteira de fault class em gfx

gfx segue a taxonomia:

• Trap: violacao estrutural de ABI/chamada (tipo, aridade, capability, shape).
• status (inteiro): erro operacional recuperavel de dominio.
• Panic: apenas quebra de invariante interna de runtime/host.

2. Politica de retorno por operacao

Nem toda syscall gfx precisa retornar status.

Regra canonica:

• se a operacao pode produzir erro operacional observavel, deve retornar status: int (ret_slots >= 1);
• se a operacao nao possui via real de erro operacional, pode permanecer void.

3. Tabela de status por operacao

Cada operacao gfx que retorna status deve declarar tabela de codigos inteiros propria.

A tabela deve cobrir, quando aplicavel:

• recurso ausente (asset_not_found);
• indice invalido (invalid_sprite_index);
• argumento fora de faixa (invalid_arg_range);
• sem efeito operacional (no_effect), quando houver.

4. Politica de no-op

No-op silencioso nao e permitido para operacoes com possibilidade de erro operacional.

Quando houver falha/ignoracao operacional:

• a chamada deve retornar status explicito;
• o resultado nao pode ser mascarado como sucesso implicito.

5. Contrato de gfx.set_sprite

set_sprite nao deve depender de fallback implicito para banco default.

Casos como:

• asset_name ausente/nao encontrado;
• sprite_index fora de faixa;
• palette_id/priority fora da faixa;

devem ser reportados por status conforme a tabela da operacao.

6. Higiene de panic

Erros de argumento de app nao devem escalar para Panic.

Helpers e dispatch devem mapear esses casos para:

• Trap (quando estrutural); ou
• status (quando operacional, para operacoes com retorno de status).

7. Compatibilidade e migracao

Nao ha requisito de compatibilidade retroativa para esta mudanca.

E permitido:

• ajustar assinaturas de syscall gfx (especialmente ret_slots);
• atualizar registry/loader/runtime em linha com a matriz final;
• regenerar artefatos de stress test com o contrato novo.

Consequencias

Positivas

• reduz Trap/Panic indevidos no dominio grafico;
• elimina comportamento silencioso em comandos com erro operacional;
• torna contratos de retorno mais consistentes e testaveis.

Custos

• exige atualizacao de metadata de syscall e dispatch;
• exige atualizacao dos testes e do gerador de stress.

Follow-up Obrigatorio

• agenda 004-gfx-fault-semantics-and-command-contract.md deve ser considerada absorvida e removida;
• specs 04 e 16a devem absorver o contrato final quando a implementacao estiver estavel;
• a matriz final por syscall (void vs status) e a tabela de codigos devem ser refletidas no registry de syscalls.