improvements agendas and decisions

This commit is contained in:
2026-03-24 13:40:50 +00:00
parent 9f402de894
commit 38d551fe01
4 changed files with 113 additions and 72 deletions
@@ -0,0 +1,104 @@
# 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.
+1
View File
@@ -19,6 +19,7 @@ Decisoes ativas:
- `003-vm-owned-byte-transfer-protocol.md`
- `006-vm-owned-stateful-core-contract.md`
- `007-filesystem-fault-core-policy.md`
- `008-gfx-status-first-fault-and-return-contract.md`
Decisoes aposentadas que ja viraram spec: