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

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.