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