improvements agendas and decisions

docs/runtime/agendas/005-audio-fault-semantics-and-surface.md

@@ -1,63 +0,0 @@
-# Agenda - Audio Fault Semantics and Surface
-
-## Problema
-
-O dominio `audio` hoje se comporta como comando deterministico com forte tendencia a no-op/fallback, mas essa politica ainda nao esta escrita como contrato.
-
-Exemplos atuais:
-
-- `AudioPlay` cai para `bank_id = 0` quando o asset nao e encontrado;
-- o driver retorna sem efeito quando `voice_id` esta fora da faixa;
-- samples nao resolvidos nao produzem fault terminal.
-
-## Dor
-
-- a semantica real de erro fica escondida em detalhes de implementacao;
-- nao esta claro quando `audio` deve ser no-op, `status`, `Trap` ou `Panic`;
-- futuras mudancas podem cristalizar `Panic` onde hoje o dominio tolera ausencia de recurso.
-
-## Hotspots Atuais
-
-- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L340)
-- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L359)
-- [audio.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/audio.rs#L170)
-
-## Alvo da Discussao
-
-Fechar a politica de fault e surface de `audio` para o MVP.
-
-## O Que Precisa Ser Definido
-
-1. `voice_id` invalido.
-   Decidir entre:
-   - no-op deterministico;
-   - `status`;
-   - `Trap`.
-
-2. Sample/bank ausente.
-   Decidir entre:
-   - no-op deterministico;
-   - `status`;
-   - `Trap`.
-
-3. Voice unavailable.
-   Decidir se o dominio precisa retorno de `status` para esse caso ou se politica de voz resolve isso sem retorno.
-
-4. Surface.
-   Decidir se `AudioPlay`/`AudioPlaySample` continuam `void` no MVP.
-
-5. Faixas numericas.
-   Decidir a politica para pitch/pan/volume fora da faixa normativa.
-
-## Dependencias
-
-- `../specs/16a-syscall-policies.md`
-- spec de audio
-
-## Critério de Saida Desta Agenda
-
-Pode virar PR quando houver decisao escrita sobre:
-
-- matriz de `status`/`Trap`/`Panic` para `audio`;
-- posicao explicita sobre no-op deterministico no dominio;
-- shape final de retorno de `AudioPlay` e `AudioPlaySample` no MVP.

docs/runtime/agendas/README.md

@@ -10,7 +10,6 @@ Objetivo:
 
 As agendas atuais são:
 
-- `005-audio-fault-semantics-and-surface.md`
 - `006-asset-fault-semantics-and-surface.md`
 - `007-runtime-edge-test-plan.md`
 - `008-packed-cartridge-loader-pmc.md`
@@ -27,12 +26,11 @@ 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. `005-audio-fault-semantics-and-surface.md`
+4. `006-asset-fault-semantics-and-surface.md`
-5. `006-asset-fault-semantics-and-surface.md`
+5. `007-runtime-edge-test-plan.md`
-6. `007-runtime-edge-test-plan.md`
+6. `008-packed-cartridge-loader-pmc.md`
-7. `008-packed-cartridge-loader-pmc.md`
+7. `009-system-run-cart.md`
-8. `009-system-run-cart.md`
+8. `010-system-fault-semantics-and-control-surface.md`
-9. `010-system-fault-semantics-and-control-surface.md`
 
 Justificativa curta:
 
@@ -42,7 +40,8 @@ Justificativa curta:
 - `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`.
 - a decisao `008` fixa o contrato status-first de `gfx`.
-- `005` e `006` consolidam fault semantics por dominio com base em `16a`.
+- a decisao `009` fixa o contrato status-first de `audio`.
+- `006` consolida fault semantics do dominio `asset` 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.
@@ -52,7 +51,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`)
-- `005` depende de `16a`
 - `006` depende de `16a`
 - `007` depende da estabilizacao minima das agendas de superficie/fault por dominio
 - `008` depende de contrato fechado de `13-cartridge.md` + comportamento equivalente ao loader de diretorio

docs/runtime/decisions/009-audio-status-first-fault-and-return-contract.md

@@ -0,0 +1,110 @@
+# Decision Record - Audio Status-First Fault and Return Contract
+
+## Status
+
+Accepted
+
+## Contexto
+
+A agenda `005-audio-fault-semantics-and-surface.md` mostrou ambiguidade no dominio `audio`:
+
+- no-op/fallback silencioso para falhas operacionais;
+- operacoes `void` mesmo quando ha possibilidade real de falha;
+- risco de escalar erro de app para `Panic`.
+
+Para alinhar com `16a`, o dominio `audio` adota politica status-first.
+
+## Decisao
+
+### 1. Fronteira de fault class em `audio`
+
+`audio` 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 precisa retornar `status`.
+
+Regra canonica:
+
+- se a operacao pode falhar operacionalmente, deve retornar `status: int` (`ret_slots >= 1`);
+- se a operacao nao possui via real de erro operacional, pode permanecer `void`.
+
+Para o MVP atual:
+
+- `audio.play` deve retornar `status`;
+- `audio.play_sample` deve retornar `status`.
+
+### 3. No-op e fallback
+
+No-op silencioso nao e permitido em operacoes com possibilidade de erro operacional.
+
+Fallback implicito tambem nao e permitido quando mascara erro de dominio.
+
+Exemplos proibidos:
+
+- fallback implicito para `bank_id` default quando asset nao e encontrado;
+- ignorar `voice_id` invalido sem retorno explicito.
+
+### 4. Tabela de status por operacao
+
+Cada operacao `audio` que retorna `status` deve declarar codigos inteiros de forma normativa.
+
+Tabela minima para `play`/`play_sample` deve cobrir, quando aplicavel:
+
+- `OK`;
+- `VOICE_INVALID`;
+- `ASSET_NOT_FOUND`;
+- `SAMPLE_NOT_FOUND`;
+- `ARG_RANGE_INVALID`;
+- `NO_EFFECT` (somente quando houver sem efeito operacional valido e explicito).
+
+### 5. Faixas numericas
+
+Entradas numericas com faixa normativa (`volume`, `pan`, `pitch`) devem ter politica explicita.
+
+Quando fora da faixa aceita:
+
+- retornar `status` de erro de faixa;
+- nao mascarar como sucesso silencioso.
+
+### 6. Higiene de panic
+
+Erros de argumento de app nao devem escalar para `Panic`.
+
+Esses casos devem ser classificados como:
+
+- `Trap` (estrutural); ou
+- `status` (operacional, conforme a operacao).
+
+### 7. Compatibilidade e migracao
+
+Nao ha requisito de compatibilidade retroativa para esta mudanca.
+
+E permitido:
+
+- ajustar assinaturas de syscall `audio` (incluindo `ret_slots`);
+- atualizar registry/loader/runtime com o contrato novo;
+- regenerar o stress test com as assinaturas finais.
+
+## Consequencias
+
+### Positivas
+
+- reduz comportamento silencioso em erros operacionais de audio;
+- torna chamadas de audio observaveis e testaveis;
+- alinha `audio` com o modelo geral de `16a`.
+
+### Custos
+
+- exige mudanca de ABI das syscalls de audio;
+- exige atualizacao de testes e artefatos de stress.
+
+## Follow-up Obrigatorio
+
+- agenda `005-audio-fault-semantics-and-surface.md` deve ser considerada absorvida e removida;
+- specs `05` e `16a` devem absorver o contrato final quando a implementacao estiver estavel;
+- registry de syscall deve refletir `ret_slots` e codigos de status finais para `audio`.

docs/runtime/decisions/README.md

@@ -20,6 +20,7 @@ Decisoes ativas:
 - `006-vm-owned-stateful-core-contract.md`
 - `007-filesystem-fault-core-policy.md`
 - `008-gfx-status-first-fault-and-return-contract.md`
+- `009-audio-status-first-fault-and-return-contract.md`
 
 Decisoes aposentadas que ja viraram spec: