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

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
• dispatch.rs
• dispatch.rs

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.