diff --git a/docs/runtime/agendas/005-audio-fault-semantics-and-surface.md b/docs/runtime/agendas/005-audio-fault-semantics-and-surface.md deleted file mode 100644 index 2cfd18fe..00000000 --- a/docs/runtime/agendas/005-audio-fault-semantics-and-surface.md +++ /dev/null @@ -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. diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index eadc9df2..456ac57a 100644 --- a/docs/runtime/agendas/README.md +++ b/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` -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` +4. `006-asset-fault-semantics-and-surface.md` +5. `007-runtime-edge-test-plan.md` +6. `008-packed-cartridge-loader-pmc.md` +7. `009-system-run-cart.md` +8. `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 diff --git a/docs/runtime/decisions/009-audio-status-first-fault-and-return-contract.md b/docs/runtime/decisions/009-audio-status-first-fault-and-return-contract.md new file mode 100644 index 00000000..28ee5283 --- /dev/null +++ b/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`. diff --git a/docs/runtime/decisions/README.md b/docs/runtime/decisions/README.md index 3cf821ed..176caad0 100644 --- a/docs/runtime/decisions/README.md +++ b/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: