improvements agendas and decisions

This commit is contained in:
2026-03-24 13:40:50 +00:00
parent 38d551fe01
commit d8422d26af
4 changed files with 118 additions and 72 deletions
@@ -1,63 +0,0 @@
# Agenda - Audio Fault Semantics and Surface
## Problema
O dominio `audio` hoje se comporta como comando deterministico com forte tendencia a no-op/fallback, mas essa politica ainda nao esta escrita como contrato.
Exemplos atuais:
- `AudioPlay` cai para `bank_id = 0` quando o asset nao e encontrado;
- o driver retorna sem efeito quando `voice_id` esta fora da faixa;
- samples nao resolvidos nao produzem fault terminal.
## Dor
- a semantica real de erro fica escondida em detalhes de implementacao;
- nao esta claro quando `audio` deve ser no-op, `status`, `Trap` ou `Panic`;
- futuras mudancas podem cristalizar `Panic` onde hoje o dominio tolera ausencia de recurso.
## Hotspots Atuais
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L340)
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L359)
- [audio.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/audio.rs#L170)
## Alvo da Discussao
Fechar a politica de fault e surface de `audio` para o MVP.
## O Que Precisa Ser Definido
1. `voice_id` invalido.
Decidir entre:
- no-op deterministico;
- `status`;
- `Trap`.
2. Sample/bank ausente.
Decidir entre:
- no-op deterministico;
- `status`;
- `Trap`.
3. Voice unavailable.
Decidir se o dominio precisa retorno de `status` para esse caso ou se politica de voz resolve isso sem retorno.
4. Surface.
Decidir se `AudioPlay`/`AudioPlaySample` continuam `void` no MVP.
5. Faixas numericas.
Decidir a politica para pitch/pan/volume fora da faixa normativa.
## Dependencias
- `../specs/16a-syscall-policies.md`
- spec de audio
## Critério de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- matriz de `status`/`Trap`/`Panic` para `audio`;
- posicao explicita sobre no-op deterministico no dominio;
- shape final de retorno de `AudioPlay` e `AudioPlaySample` no MVP.
+7 -9
View File
@@ -10,7 +10,6 @@ Objetivo:
As agendas atuais são:
- `005-audio-fault-semantics-and-surface.md`
- `006-asset-fault-semantics-and-surface.md`
- `007-runtime-edge-test-plan.md`
- `008-packed-cartridge-loader-pmc.md`
@@ -27,12 +26,11 @@ Ordem sugerida para discussão e futura execução:
1. `012-vm-owned-random-service.md`
2. `013-game-memcard-slots-surface-and-semantics.md`
3. `014-app-home-filesystem-surface-and-semantics.md`
4. `005-audio-fault-semantics-and-surface.md`
5. `006-asset-fault-semantics-and-surface.md`
6. `007-runtime-edge-test-plan.md`
7. `008-packed-cartridge-loader-pmc.md`
8. `009-system-run-cart.md`
9. `010-system-fault-semantics-and-control-surface.md`
4. `006-asset-fault-semantics-and-surface.md`
5. `007-runtime-edge-test-plan.md`
6. `008-packed-cartridge-loader-pmc.md`
7. `009-system-run-cart.md`
8. `010-system-fault-semantics-and-control-surface.md`
Justificativa curta:
@@ -42,7 +40,8 @@ Justificativa curta:
- `014` fecha o contrato de `home` para apps sem abrir FS global.
- a decisao `007` fixa o nucleo de fault policy de `fs`; os detalhes ficam distribuidos em `013` e `014`.
- a decisao `008` fixa o contrato status-first de `gfx`.
- `005` e `006` consolidam fault semantics por dominio com base em `16a`.
- a decisao `009` fixa o contrato status-first de `audio`.
- `006` consolida fault semantics do dominio `asset` com base em `16a`.
- a agenda `007` vem depois para transformar as decisoes em cobertura de regressao na borda do runtime.
- `008` e importante, mas nao bloqueia bytecode/backend agora.
- `009` e `010` ficam no fim porque `run_cart` nao e objetivo do ciclo atual.
@@ -52,7 +51,6 @@ Dependências principais:
- `012` depende da decisao `006` e de `16`/`16a`
- `013` depende das decisoes `003`/`007`, de `16a`, de `08` (memcard), de `12` (Hub/OS) e de `13` (`app_mode`)
- `014` depende das decisoes `003`/`007`, de `16a`, de `12` (Hub/OS) e de `13` (`app_mode`)
- `005` depende de `16a`
- `006` depende de `16a`
- `007` depende da estabilizacao minima das agendas de superficie/fault por dominio
- `008` depende de contrato fechado de `13-cartridge.md` + comportamento equivalente ao loader de diretorio