# 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`.