improvements agendas and decisions

docs/runtime/agendas/004-gfx-fault-semantics-and-command-contract.md

@@ -1,62 +0,0 @@
-# Agenda - Gfx Fault Semantics and Command Contract
-
-## Problema
-
-`gfx` parece dominio command-style com pouca necessidade de status, mas a politica concreta entre `Trap`, no-op deterministico e fallback ainda nao esta consolidada.
-
-Exemplos atuais:
-
-- `GfxSetSprite` usa fallback estavel quando asset nao e encontrado;
-- indices fora da faixa podem virar no-op em vez de fault;
-- argumentos ausentes ainda sobem como `Panic` por detalhe de helper.
-
-## Dor
-
-- a surface de `gfx` pode ficar inconsistente entre comandos;
-- detalhes acidentais de implementacao podem ser confundidos com politica de dominio;
-- `Panic` pode vazar para o app em casos que sao apenas erro de comando ou comando ignoravel.
-
-## Hotspots Atuais
-
-- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L178)
-- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L213)
-- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L227)
-
-## Alvo da Discussao
-
-Fixar a politica de fault de `gfx` como dominio de comando.
-
-## O Que Precisa Ser Definido
-
-1. Erros estruturais.
-   Confirmar o que continua `Trap`:
-   - tipo invalido;
-   - aridade invalida;
-   - capability ausente.
-
-2. Parametros fora da faixa.
-   Decidir por comando:
-   - clamp;
-   - no-op;
-   - `Trap`.
-
-3. Asset/sprite name ausente em `set_sprite`.
-   Decidir se fallback atual vira contrato oficial.
-
-4. Indices fora da faixa.
-   Decidir se sprite index invalido e no-op ou `Trap`.
-
-5. Panic cleanup.
-   Remover `Panic` acidental por argumento ausente/helper onde isso nao representa falha estrutural do runtime.
-
-## Dependencias
-
-- `../specs/16a-syscall-policies.md`
-
-## Critério de Saida Desta Agenda
-
-Pode virar PR quando houver decisao escrita sobre:
-
-- matriz de `Trap`/no-op/fallback para `gfx`;
-- politica de `set_sprite`;
-- reducao de `Panic` acidental no dominio.

docs/runtime/agendas/README.md

@@ -10,7 +10,6 @@ Objetivo:
 
 As agendas atuais são:
 
-- `004-gfx-fault-semantics-and-command-contract.md`
 - `005-audio-fault-semantics-and-surface.md`
 - `006-asset-fault-semantics-and-surface.md`
 - `007-runtime-edge-test-plan.md`
@@ -28,13 +27,12 @@ Ordem sugerida para discussão e futura execução:
 1. `012-vm-owned-random-service.md`
 2. `013-game-memcard-slots-surface-and-semantics.md`
 3. `014-app-home-filesystem-surface-and-semantics.md`
-4. `004-gfx-fault-semantics-and-command-contract.md`
-5. `005-audio-fault-semantics-and-surface.md`
-6. `006-asset-fault-semantics-and-surface.md`
-7. `007-runtime-edge-test-plan.md`
-8. `008-packed-cartridge-loader-pmc.md`
-9. `009-system-run-cart.md`
-10. `010-system-fault-semantics-and-control-surface.md`
+4. `005-audio-fault-semantics-and-surface.md`
+5. `006-asset-fault-semantics-and-surface.md`
+6. `007-runtime-edge-test-plan.md`
+7. `008-packed-cartridge-loader-pmc.md`
+8. `009-system-run-cart.md`
+9. `010-system-fault-semantics-and-control-surface.md`
 
 Justificativa curta:
 
@@ -43,7 +41,8 @@ Justificativa curta:
 - `013` fecha o contrato de memcard para jogos (`32 x 32KB`, ownership, identidade e copia fora do jogo).
 - `014` fecha o contrato de `home` para apps sem abrir FS global.
 - a decisao `007` fixa o nucleo de fault policy de `fs`; os detalhes ficam distribuidos em `013` e `014`.
-- `004`, `005` e `006` consolidam fault semantics por dominio com base em `16a`.
+- a decisao `008` fixa o contrato status-first de `gfx`.
+- `005` e `006` consolidam fault semantics por dominio com base em `16a`.
 - a agenda `007` vem depois para transformar as decisoes em cobertura de regressao na borda do runtime.
 - `008` e importante, mas nao bloqueia bytecode/backend agora.
 - `009` e `010` ficam no fim porque `run_cart` nao e objetivo do ciclo atual.
@@ -53,7 +52,6 @@ Dependências principais:
 - `012` depende da decisao `006` e de `16`/`16a`
 - `013` depende das decisoes `003`/`007`, de `16a`, de `08` (memcard), de `12` (Hub/OS) e de `13` (`app_mode`)
 - `014` depende das decisoes `003`/`007`, de `16a`, de `12` (Hub/OS) e de `13` (`app_mode`)
-- `004` depende de `16a`
 - `005` depende de `16a`
 - `006` depende de `16a`
 - `007` depende da estabilizacao minima das agendas de superficie/fault por dominio

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

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

docs/runtime/decisions/README.md

@@ -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: