docs: move implemented status-first decisions from decisions to learn

This commit is contained in:
2026-03-24 13:40:51 +00:00
parent 7a81712005
commit 6a894b987d
5 changed files with 12 additions and 0 deletions
@@ -0,0 +1,104 @@
# Decision Record - GFX Status-First Fault and Return Contract
## Status
Accepted
## Contexto
A agenda `004-gfx-fault-semantics-and-command-contract.md` consolidou que o dominio `gfx` estava com ambiguidade entre:
- `Trap`/`Panic` desnecessarios para erro operacional;
- no-op silencioso;
- chamadas `void` em operacoes que podem falhar operacionalmente.
Para alinhar com `16a`, foi decidido fechar uma politica status-first no dominio `gfx`.
## Decisao
### 1. Fronteira de fault class em `gfx`
`gfx` 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 `gfx` precisa retornar `status`.
Regra canonica:
- se a operacao pode produzir erro operacional observavel, deve retornar `status: int` (`ret_slots >= 1`);
- se a operacao nao possui via real de erro operacional, pode permanecer `void`.
### 3. Tabela de status por operacao
Cada operacao `gfx` que retorna `status` deve declarar tabela de codigos inteiros propria.
A tabela deve cobrir, quando aplicavel:
- recurso ausente (`asset_not_found`);
- indice invalido (`invalid_sprite_index`);
- argumento fora de faixa (`invalid_arg_range`);
- sem efeito operacional (`no_effect`), quando houver.
### 4. Politica de no-op
No-op silencioso nao e permitido para operacoes com possibilidade de erro operacional.
Quando houver falha/ignoracao operacional:
- a chamada deve retornar `status` explicito;
- o resultado nao pode ser mascarado como sucesso implicito.
### 5. Contrato de `gfx.set_sprite`
`set_sprite` nao deve depender de fallback implicito para banco default.
Casos como:
- `asset_name` ausente/nao encontrado;
- `sprite_index` fora de faixa;
- `palette_id`/`priority` fora da faixa;
devem ser reportados por `status` conforme a tabela da operacao.
### 6. Higiene de panic
Erros de argumento de app nao devem escalar para `Panic`.
Helpers e dispatch devem mapear esses casos para:
- `Trap` (quando estrutural); ou
- `status` (quando operacional, para operacoes com retorno de status).
### 7. Compatibilidade e migracao
Nao ha requisito de compatibilidade retroativa para esta mudanca.
E permitido:
- ajustar assinaturas de syscall `gfx` (especialmente `ret_slots`);
- atualizar registry/loader/runtime em linha com a matriz final;
- regenerar artefatos de stress test com o contrato novo.
## Consequencias
### Positivas
- reduz `Trap`/`Panic` indevidos no dominio grafico;
- elimina comportamento silencioso em comandos com erro operacional;
- torna contratos de retorno mais consistentes e testaveis.
### Custos
- exige atualizacao de metadata de syscall e dispatch;
- exige atualizacao dos testes e do gerador de stress.
## Follow-up Obrigatorio
- agenda `004-gfx-fault-semantics-and-command-contract.md` deve ser considerada absorvida e removida;
- specs `04` e `16a` devem absorver o contrato final quando a implementacao estiver estavel;
- a matriz final por syscall (`void` vs `status`) e a tabela de codigos devem ser refletidas no registry de syscalls.
@@ -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`.
@@ -0,0 +1,122 @@
# Decision Record - Asset Status-First Fault and Return Contract
## Status
Accepted
## Contexto
A agenda `006-asset-fault-semantics-and-surface.md` evidenciou inconsistencia no dominio `asset`:
- `asset.status` ja usa status numerico;
- `asset.load` ainda escalava erro operacional para `Panic`;
- `asset.commit`/`asset.cancel` eram `void` com no-op silencioso para varios casos.
Para alinhar o dominio com `16a`, foi fechado contrato status-first para `asset`.
## Decisao
### 1. Fronteira de fault class em `asset`
`asset` segue:
- `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. Surface canonica do dominio
A surface final do MVP fica:
- `asset.load(name, kind, slot) -> (status:int, handle:int)`
- `asset.status(handle) -> status:int`
- `asset.commit(handle) -> status:int`
- `asset.cancel(handle) -> status:int`
Regras:
- `handle` so e valido quando `status == ASSET_OK`;
- em falha de `load`, `handle` deve ser `0`.
### 3. No-op silencioso proibido
No-op silencioso nao e permitido para operacoes com erro operacional possivel.
Casos como:
- handle desconhecido;
- transicao invalida de lifecycle;
- slot invalido;
- asset ausente;
devem retornar `status` explicito.
### 4. `asset.load` (request path)
Falhas operacionais de request devem virar `status`, incluindo:
- `ASSET_NOT_FOUND`;
- `SLOT_KIND_MISMATCH`;
- `SLOT_INDEX_INVALID`;
- `BACKEND_ERROR`.
`Panic` nao deve ser usado para falha operacional de `load`.
### 5. `asset.status` (lifecycle path)
`asset.status` permanece a fonte de verdade do lifecycle assíncrono.
Codigos de lifecycle devem cobrir:
- `PENDING`
- `LOADING`
- `READY`
- `COMMITTED`
- `CANCELED`
- `ERROR`
- `UNKNOWN_HANDLE`
### 6. `asset.commit` e `asset.cancel`
Ambas operacoes devem retornar `status`.
Tabela minima de resposta:
- `ASSET_OK` (acao aceita/concluida para o estado atual)
- `UNKNOWN_HANDLE`
- `INVALID_STATE`
### 7. Relacao com dominio `bank`
Erros de residency/slot permanecem no dominio `asset`.
`bank` permanece dominio de inspecao (`info`, `slot_info`) e nao absorve erros operacionais de mutacao de asset lifecycle.
### 8. Compatibilidade e migracao
Nao ha requisito de compatibilidade retroativa para esta mudanca.
E permitido:
- alterar `ret_slots` de `asset.load`, `asset.commit`, `asset.cancel`;
- ajustar registry/loader/dispatch/runtime com o novo contrato;
- regenerar stress test com as assinaturas novas.
## Consequencias
### Positivas
- remove `Panic` operacional indevido do dominio `asset`;
- torna fluxo de lifecycle observavel e consistente;
- elimina ambiguidade de no-op em `commit`/`cancel`.
### Custos
- exige migracao de ABI das syscalls `asset`;
- exige atualizacao de testes e artefatos gerados.
## Follow-up Obrigatorio
- agenda `006-asset-fault-semantics-and-surface.md` deve ser considerada absorvida e removida;
- specs `15` e `16a` devem absorver o contrato final quando a implementacao estiver estavel;
- registry de syscall deve refletir o shape final (`ret_slots`) das operacoes `asset`.
+3
View File
@@ -21,6 +21,9 @@ Ela existe para explicar o modelo mental da fantasy handheld, suas influências,
- [`portability-and-cross-platform.md`](portability-and-cross-platform.md)
- [`time-model-and-cycles.md`](time-model-and-cycles.md)
- [`retired-decisions-004-005-history.md`](retired-decisions-004-005-history.md)
- [`008-gfx-status-first-fault-and-return-contract.md`](008-gfx-status-first-fault-and-return-contract.md)
- [`009-audio-status-first-fault-and-return-contract.md`](009-audio-status-first-fault-and-return-contract.md)
- [`010-asset-status-first-fault-and-return-contract.md`](010-asset-status-first-fault-and-return-contract.md)
## Rules