diff --git a/docs/runtime/pull-requests/PR001-spec-core-sync-16-and-16a.md b/docs/runtime/pull-requests/PR001-spec-core-sync-16-and-16a.md new file mode 100644 index 00000000..fc584569 --- /dev/null +++ b/docs/runtime/pull-requests/PR001-spec-core-sync-16-and-16a.md @@ -0,0 +1,39 @@ +# PR001 - Spec Core Sync 16 and 16a + +## Briefing + +As decisions `007`, `008`, `009` e `010` fixaram um modelo status-first por dominio. + +Precisamos consolidar esse nucleo em specs de ABI/policy para evitar interpretacao divergente durante implementacao. + +## Alvo + +Atualizar as specs base para refletir: + +- fronteira canonica `Trap`/`status`/`Panic`; +- regra de quando syscall pode permanecer `void`; +- regra de quando `status:int` em retorno e obrigatorio; +- proibicao de no-op silencioso quando ha erro operacional observavel. + +Arquivos principais: + +- `docs/runtime/specs/16-host-abi-and-syscalls.md` +- `docs/runtime/specs/16a-syscall-policies.md` + +## Fora de Escopo + +- mudanca de implementacao em runtime; +- mudanca de assinatura de syscall em codigo; +- atualizacao de stress cart. + +## Critérios de Aceite + +- `16` e `16a` citam explicitamente o contrato status-first como politica transversal; +- `16a` documenta regra de retorno por operacao (`void` vs `status`); +- `16a` documenta no-op silencioso proibido para erros operacionais; +- texto nao conflita com decisions `007`/`008`/`009`/`010`. + +## Tests + +- revisao de consistencia documental (diff + leitura cruzada com decisions); +- verificador de links markdown do repositorio, se aplicavel. diff --git a/docs/runtime/pull-requests/PR002-gfx-status-first-surface-and-fault-matrix.md b/docs/runtime/pull-requests/PR002-gfx-status-first-surface-and-fault-matrix.md new file mode 100644 index 00000000..99281496 --- /dev/null +++ b/docs/runtime/pull-requests/PR002-gfx-status-first-surface-and-fault-matrix.md @@ -0,0 +1,47 @@ +# PR002 - GFX Status-First Surface and Fault Matrix + +## Briefing + +A decision `008` fechou politica status-first em `gfx`, incluindo: + +- sem no-op silencioso para erro operacional; +- retorno `status` quando houver possibilidade real de falha; +- `Trap` apenas estrutural e `Panic` apenas invariante. + +## Alvo + +Implementar o contrato de `gfx` no runtime e atualizar spec do dominio. + +Arquivos principais: + +- `docs/runtime/specs/04-gfx-peripheral.md` +- `crates/console/prometeu-hal/src/syscalls/domains/gfx.rs` +- `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs` + +## Escopo Funcional + +- fechar matriz por syscall (`void` vs `status`); +- remover fallback implicito em `gfx.set_sprite`; +- mapear casos operacionais para status inteiros por operacao; +- remover `Panic` acidental por argumento de app no dominio `gfx`. + +## Fora de Escopo + +- redesign de pipeline grafico; +- mudancas de feature fora do conjunto atual de syscalls `gfx`. + +## Critérios de Aceite + +- metadata de syscall `gfx` (arg/ret slots) alinhada com matriz definida; +- `set_sprite` nao usa fallback implicito para banco default; +- casos operacionais invalidos retornam `status` e nao no-op silencioso; +- testes cobrindo pelo menos: + - sprite index invalido; + - asset ausente; + - faixas invalidas de parametro. + +## Tests + +- `cargo test -p prometeu-system` +- `cargo test -p prometeu-hal` +- testes de regressao especificos de `dispatch` e dominio `gfx`. diff --git a/docs/runtime/pull-requests/PR003-audio-status-first-surface-and-fault-matrix.md b/docs/runtime/pull-requests/PR003-audio-status-first-surface-and-fault-matrix.md new file mode 100644 index 00000000..6bcc43f9 --- /dev/null +++ b/docs/runtime/pull-requests/PR003-audio-status-first-surface-and-fault-matrix.md @@ -0,0 +1,43 @@ +# PR003 - Audio Status-First Surface and Fault Matrix + +## Briefing + +A decision `009` fixou que `audio` deve seguir status-first. + +No MVP atual, `audio.play` e `audio.play_sample` devem retornar `status:int`. + +## Alvo + +Aplicar a decisao `009` em spec e runtime para o dominio `audio`. + +Arquivos principais: + +- `docs/runtime/specs/05-audio-peripheral.md` +- `crates/console/prometeu-hal/src/syscalls/domains/audio.rs` +- `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs` +- `crates/console/prometeu-drivers/src/audio.rs` + +## Escopo Funcional + +- mudar surface de retorno de `audio.play` e `audio.play_sample` para `status`; +- remover fallback implicito e no-op silencioso para erros operacionais; +- validar faixas normativas (`volume`, `pan`, `pitch`) com status explicito; +- limpar caminhos que poderiam escalar para `Panic` por input de app. + +## Fora de Escopo + +- novos comandos de audio (stop/set pan/set pitch etc) fora do contrato atual; +- mudanca de arquitetura do mixer host. + +## Critérios de Aceite + +- `ret_slots` de `audio.play` e `audio.play_sample` atualizados no registry; +- casos operacionais retornam status inteiro canonico; +- `voice_id` invalido e asset/sample ausente nao ficam silenciosos; +- sem `Panic` operacional no dominio. + +## Tests + +- `cargo test -p prometeu-system` +- `cargo test -p prometeu-drivers` +- cenarios com `voice_id` invalido, asset ausente e range invalido. diff --git a/docs/runtime/pull-requests/PR004-asset-status-first-surface-and-lifecycle.md b/docs/runtime/pull-requests/PR004-asset-status-first-surface-and-lifecycle.md new file mode 100644 index 00000000..95e41211 --- /dev/null +++ b/docs/runtime/pull-requests/PR004-asset-status-first-surface-and-lifecycle.md @@ -0,0 +1,54 @@ +# PR004 - Asset Status-First Surface and Lifecycle + +## Briefing + +A decision `010` fechou a superficie final de `asset`: + +- `asset.load(name, kind, slot) -> (status, handle)` +- `asset.status(handle) -> status` +- `asset.commit(handle) -> status` +- `asset.cancel(handle) -> status` + +Sem no-op silencioso e sem `Panic` operacional. + +## Alvo + +Implementar o contrato de `asset` em spec, registry e runtime. + +Arquivos principais: + +- `docs/runtime/specs/15-asset-management.md` +- `crates/console/prometeu-hal/src/syscalls/domains/asset.rs` +- `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs` +- `crates/console/prometeu-drivers/src/asset.rs` +- `crates/console/prometeu-hal/src/asset_bridge.rs` (se necessario) + +## Escopo Funcional + +- substituir `Err -> Panic` de `asset.load` por status operacional; +- tornar `asset.commit` e `asset.cancel` retornos explicitos de status; +- explicitar `UNKNOWN_HANDLE` em `asset.status`; +- validar slot index/kind no request path de `load`; +- manter erros de residency/slot no dominio `asset` (nao migrar para `bank`). + +## Fora de Escopo + +- redesign da politica interna de residencia; +- novos dominios de asset alem de `TILES` e `SOUNDS`. + +## Critérios de Aceite + +- assinaturas de syscall `asset` alinhadas com decision `010`; +- `asset.load` nao produz `Panic` para falha operacional; +- `commit`/`cancel` nao ficam em no-op silencioso; +- tabela de status por operacao documentada e testada. + +## Tests + +- `cargo test -p prometeu-system` +- `cargo test -p prometeu-drivers` +- cenarios de: + - handle desconhecido; + - transicao invalida; + - asset nao encontrado; + - slot invalido/kind mismatch. diff --git a/docs/runtime/pull-requests/PR005-abi-verifier-loader-and-stress-regeneration.md b/docs/runtime/pull-requests/PR005-abi-verifier-loader-and-stress-regeneration.md new file mode 100644 index 00000000..215dd814 --- /dev/null +++ b/docs/runtime/pull-requests/PR005-abi-verifier-loader-and-stress-regeneration.md @@ -0,0 +1,43 @@ +# PR005 - ABI Verifier Loader and Stress Regeneration + +## Briefing + +As PRs verticais (`gfx`, `audio`, `asset`) alteram `ret_slots` e shape de chamadas. + +Precisamos sincronizar ABI/tooling para evitar divergencia entre spec, loader, verifier e artefatos. + +## Alvo + +Atualizar pipeline de bytecode/runtime e regenerar stress artifacts. + +Arquivos principais (esperados): + +- `crates/console/prometeu-hal/src/syscalls/*` +- `crates/console/prometeu-vm/src/virtual_machine/loader.rs` +- `crates/console/prometeu-vm/src/virtual_machine.rs` (validacoes de ABI) +- `crates/tools/pbxgen-stress/*` +- fixtures/snapshots relacionados a stress test + +## Escopo Funcional + +- garantir validacao consistente de `arg_slots`/`ret_slots`; +- atualizar declarações de syscall geradas pelo stress cart; +- regenerar bytecode de stress alinhado ao novo contrato; +- manter somente o stress test como referencia obrigatoria de compatibilidade. + +## Fora de Escopo + +- novas features de VM; +- compatibilidade retroativa com assinaturas antigas. + +## Critérios de Aceite + +- loader/verifier aceitam os novos contratos e rejeitam shape antigo quando esperado; +- stress cart regenerado com assinaturas novas; +- stress test executa sem mismatch de syscall metadata. + +## Tests + +- `cargo test -p prometeu-vm` +- `cargo test -p prometeu-system` +- execucao dos testes de stress/cart conforme fluxo atual do repositorio. diff --git a/docs/runtime/pull-requests/README.md b/docs/runtime/pull-requests/README.md index 8cf460ff..2863a953 100644 --- a/docs/runtime/pull-requests/README.md +++ b/docs/runtime/pull-requests/README.md @@ -33,3 +33,21 @@ Uma PR deste diretório deve: - explicitar o que está fora de escopo quando houver risco de expansão; - estabelecer critérios objetivos de aceite; - definir a estratégia de teste proporcional ao risco da mudança. + +## Roadmap Publicado + +PRs propostas para execucao da rodada atual: + +1. `PR001-spec-core-sync-16-and-16a.md` +2. `PR002-gfx-status-first-surface-and-fault-matrix.md` +3. `PR003-audio-status-first-surface-and-fault-matrix.md` +4. `PR004-asset-status-first-surface-and-lifecycle.md` +5. `PR005-abi-verifier-loader-and-stress-regeneration.md` +6. `PR006-conformance-regression-suite-fault-status.md` + +Sequenciamento recomendado: + +- `PR001` primeiro; +- `PR002`, `PR003` e `PR004` em paralelo; +- `PR005` depois das tres verticais; +- `PR006` por ultimo para consolidacao de regressao.