Audio Status-First Surface and Fault Matrix

This commit is contained in:
2026-03-24 13:40:52 +00:00
parent fd5a5cd22c
commit 9cb0e77b01
5 changed files with 166 additions and 54 deletions
@@ -1,43 +0,0 @@
# PR003 - Audio Status-First Surface and Fault Matrix
## Briefing
A decision `009` fixou que `audio` deve seguir status-first.
No MVP atual, `audio.play` e `audio.play_sample` devem retornar `status:int`.
## Alvo
Aplicar a decisao `009` em spec e runtime para o dominio `audio`.
Arquivos principais:
- `docs/runtime/specs/05-audio-peripheral.md`
- `crates/console/prometeu-hal/src/syscalls/domains/audio.rs`
- `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`
- `crates/console/prometeu-drivers/src/audio.rs`
## Escopo Funcional
- mudar surface de retorno de `audio.play` e `audio.play_sample` para `status`;
- remover fallback implicito e no-op silencioso para erros operacionais;
- validar faixas normativas (`volume`, `pan`, `pitch`) com status explicito;
- limpar caminhos que poderiam escalar para `Panic` por input de app.
## Fora de Escopo
- novos comandos de audio (stop/set pan/set pitch etc) fora do contrato atual;
- mudanca de arquitetura do mixer host.
## Critérios de Aceite
- `ret_slots` de `audio.play` e `audio.play_sample` atualizados no registry;
- casos operacionais retornam status inteiro canonico;
- `voice_id` invalido e asset/sample ausente nao ficam silenciosos;
- sem `Panic` operacional no dominio.
## Tests
- `cargo test -p prometeu-system`
- `cargo test -p prometeu-drivers`
- cenarios com `voice_id` invalido, asset ausente e range invalido.
@@ -192,6 +192,13 @@ In the current MVP:
- `audio.play` returns `status:int`;
- `audio.play_sample` returns `status:int`.
Return-shape matrix in v1 syscall surface:
| Syscall | Return | Policy basis |
| --------------------- | ------------ | -------------------------------------- |
| `audio.play` | `status:int` | operational rejection is observable |
| `audio.play_sample` | `status:int` | operational rejection is observable |
### 11.2 Minimum status table for `play`/`play_sample`
- `0` = `OK`
@@ -205,4 +212,5 @@ Operational rules:
- no fallback to default bank when an asset cannot be resolved;
- no silent no-op for invalid `voice_id`;
- invalid `voice_id` must return `VOICE_INVALID`, not `ARG_RANGE_INVALID`;
- invalid numeric ranges (e.g. `volume`, `pan`, `pitch`) must return explicit status.