From 38d551fe01ae53aec1097387fc1836baa7f05599 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Mon, 9 Mar 2026 06:21:34 +0000 Subject: [PATCH] improvements agendas and decisions --- ...fx-fault-semantics-and-command-contract.md | 62 ----------- docs/runtime/agendas/README.md | 18 ++- ...-status-first-fault-and-return-contract.md | 104 ++++++++++++++++++ docs/runtime/decisions/README.md | 1 + 4 files changed, 113 insertions(+), 72 deletions(-) delete mode 100644 docs/runtime/agendas/004-gfx-fault-semantics-and-command-contract.md create mode 100644 docs/runtime/decisions/008-gfx-status-first-fault-and-return-contract.md diff --git a/docs/runtime/agendas/004-gfx-fault-semantics-and-command-contract.md b/docs/runtime/agendas/004-gfx-fault-semantics-and-command-contract.md deleted file mode 100644 index dd32dd73..00000000 --- a/docs/runtime/agendas/004-gfx-fault-semantics-and-command-contract.md +++ /dev/null @@ -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. diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index a9bf7ea3..eadc9df2 100644 --- a/docs/runtime/agendas/README.md +++ b/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 diff --git a/docs/runtime/decisions/008-gfx-status-first-fault-and-return-contract.md b/docs/runtime/decisions/008-gfx-status-first-fault-and-return-contract.md new file mode 100644 index 00000000..a04a14e0 --- /dev/null +++ b/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. diff --git a/docs/runtime/decisions/README.md b/docs/runtime/decisions/README.md index 042f79fd..3cf821ed 100644 --- a/docs/runtime/decisions/README.md +++ b/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: