improvements agendas and decisions
This commit is contained in:
@@ -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`.
|
||||
@@ -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:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user