From 5984eaaf24c663acba2aa41b7b3bd0fdc611ac4f Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Tue, 21 Apr 2026 17:39:56 +0100 Subject: [PATCH] housekeeping and cleanup --- discussion/index.ndjson | 4 +- ...n-gates-must-be-owned-by-the-repository.md | 55 ++++ .../AGD-0001-runtime-edge-test-plan.md | 234 ------------------ ...time-edge-coverage-governance-by-domain.md | 213 ---------------- ...ime-edge-coverage-governance-foundation.md | 133 ---------- ...ost-dependent-domain-coverage-expansion.md | 135 ---------- ...untime-domain-suite-split-and-baselines.md | 132 ---------- 7 files changed, 57 insertions(+), 849 deletions(-) create mode 100644 discussion/lessons/DSC-0002-runtime-edge-test-plan/LSN-0037-domain-gates-must-be-owned-by-the-repository.md delete mode 100644 discussion/workflow/agendas/AGD-0001-runtime-edge-test-plan.md delete mode 100644 discussion/workflow/decisions/DEC-0020-runtime-edge-coverage-governance-by-domain.md delete mode 100644 discussion/workflow/plans/PLN-0037-runtime-edge-coverage-governance-foundation.md delete mode 100644 discussion/workflow/plans/PLN-0038-firmware-and-host-dependent-domain-coverage-expansion.md delete mode 100644 discussion/workflow/plans/PLN-0039-incremental-runtime-domain-suite-split-and-baselines.md diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 7ac2616e..bc6b5c22 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,10 +1,10 @@ -{"type":"meta","next_id":{"DSC":29,"AGD":29,"DEC":21,"PLN":40,"LSN":37,"CLSN":1}} +{"type":"meta","next_id":{"DSC":29,"AGD":29,"DEC":21,"PLN":40,"LSN":38,"CLSN":1}} {"type":"discussion","id":"DSC-0023","status":"done","ticket":"perf-full-migration-to-atomic-telemetry","title":"Agenda - [PERF] Full Migration to Atomic Telemetry","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["perf","runtime","telemetry"],"agendas":[{"id":"AGD-0021","file":"workflow/agendas/AGD-0021-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0008","file":"workflow/decisions/DEC-0008-full-migration-to-atomic-telemetry.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0007","file":"workflow/plans/PLN-0007-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0028","file":"lessons/DSC-0023-perf-full-migration-to-atomic-telemetry/LSN-0028-converging-to-single-atomic-telemetry-source.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} {"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"workflow/decisions/DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"workflow/plans/PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]} {"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]} {"type":"discussion","id":"DSC-0022","status":"done","ticket":"tile-bank-vs-glyph-bank-domain-naming","title":"Glyph Bank Domain Naming Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["gfx","runtime","naming","domain-model"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} {"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} -{"type":"discussion","id":"DSC-0002","status":"open","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-04-21","tags":[],"agendas":[{"id":"AGD-0001","file":"workflow/agendas/AGD-0001-runtime-edge-test-plan.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-20"}],"decisions":[{"id":"DEC-0020","file":"workflow/decisions/DEC-0020-runtime-edge-coverage-governance-by-domain.md","status":"in_progress","created_at":"2026-04-20","updated_at":"2026-04-21","ref_agenda":"AGD-0001"}],"plans":[{"id":"PLN-0037","file":"workflow/plans/PLN-0037-runtime-edge-coverage-governance-foundation.md","status":"done","created_at":"2026-04-20","updated_at":"2026-04-21","ref_decisions":["DEC-0020"]},{"id":"PLN-0038","file":"workflow/plans/PLN-0038-firmware-and-host-dependent-domain-coverage-expansion.md","status":"done","created_at":"2026-04-20","updated_at":"2026-04-20","ref_decisions":["DEC-0020"]},{"id":"PLN-0039","file":"workflow/plans/PLN-0039-incremental-runtime-domain-suite-split-and-baselines.md","status":"done","created_at":"2026-04-20","updated_at":"2026-04-20","ref_decisions":["DEC-0020"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0002","status":"done","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-04-21","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0037","file":"lessons/DSC-0002-runtime-edge-test-plan/LSN-0037-domain-gates-must-be-owned-by-the-repository.md","status":"done","created_at":"2026-04-21","updated_at":"2026-04-21"}]} {"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"workflow/agendas/AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0004","status":"open","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0003","file":"workflow/agendas/AGD-0003-system-run-cart.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"workflow/agendas/AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} diff --git a/discussion/lessons/DSC-0002-runtime-edge-test-plan/LSN-0037-domain-gates-must-be-owned-by-the-repository.md b/discussion/lessons/DSC-0002-runtime-edge-test-plan/LSN-0037-domain-gates-must-be-owned-by-the-repository.md new file mode 100644 index 00000000..127f21ed --- /dev/null +++ b/discussion/lessons/DSC-0002-runtime-edge-test-plan/LSN-0037-domain-gates-must-be-owned-by-the-repository.md @@ -0,0 +1,55 @@ +--- +id: LSN-0037 +ticket: runtime-edge-test-plan +title: Domain Gates Must Be Owned by the Repository +created: 2026-04-21 +tags: [tests, coverage, ci, governance] +--- + +## Context + +PROMETEU moved runtime-edge coverage governance away from a single workspace-wide percentage and toward canonical domain gates. That shift mattered not only for policy, but also for how CI logic is expressed and maintained. + +The resulting model now treats `system/runtime`, `fs`, `asset/bank`, `firmware`, and `host-dependent` as the operational coverage authorities for runtime-edge changes. + +## Key Decisions + +### Domain-first coverage governance + +**What:** +The authoritative CI gate is no longer a global aggregate percentage. The gate is evaluated per canonical domain, with `lines` coverage compared against the domain baseline, while scenario expectations remain the real acceptance contract. + +**Why:** +A single global number can hide risk in firmware transitions, boot flow, host integration, and other sensitive edges. Domain ownership makes the gate reflect where regressions actually matter. + +**Trade-offs:** +This model is more explicit and more honest, but it requires clearer mapping between code changes, domain responsibility, and test evidence. + +### Repository-owned CI helpers + +**What:** +Jenkins should call repository helpers such as `make ci-domains`, rather than reimplementing coverage policy inline in the pipeline file. + +**Why:** +The coverage contract evolves with the repository. When CI duplicates the decision logic, policy drifts and operational changes become harder to propagate consistently. + +**Trade-offs:** +The helper must remain readable and stable, because it becomes part of the repository contract rather than a local convenience script. + +## Patterns and Algorithms + +- Keep the policy in repository files (`Makefile`, coverage scripts, domain baseline config), and keep Jenkins as a thin caller. +- Use domain-scoped baselines as a quantitative gate, but keep mandatory scenarios as the governing behavioral rule. +- Publish operationally useful coverage output that emphasizes gate status first and only exposes deeper evidence on demand. + +## Pitfalls + +- Treating a global coverage increase as proof that a touched domain is adequately tested. +- Encoding gate math directly in Jenkins and forcing future policy changes to update multiple authorities. +- Letting verbose evidence output bury the actual pass/fail signal in CI logs. + +## Takeaways + +- Runtime-edge coverage is safer when CI enforces domain ownership instead of trusting a workspace aggregate. +- Scenario-first review and domain baselines complement each other; neither should replace the other. +- Coverage gates that live in repository helpers are easier to evolve, audit, and keep consistent than CI-local logic. diff --git a/discussion/workflow/agendas/AGD-0001-runtime-edge-test-plan.md b/discussion/workflow/agendas/AGD-0001-runtime-edge-test-plan.md deleted file mode 100644 index 742a6970..00000000 --- a/discussion/workflow/agendas/AGD-0001-runtime-edge-test-plan.md +++ /dev/null @@ -1,234 +0,0 @@ ---- -id: AGD-0001 -ticket: runtime-edge-test-plan -title: Agenda - Runtime Edge Test Plan -status: done -created: 2026-03-27 -resolved: 2026-04-20 -decision: DEC-0020 -tags: [] ---- - -# Agenda - Runtime Edge Test Plan - -## Problema - -A borda do runtime deixou de ser "quase sem testes", mas continua sem contrato claro de suficiência por dominio. - -Hoje já existe cobertura relevante para runtime edge, `VirtualFS`, asset/preload, status-first surfaces e parte do host. O problema atual não é ausência total de testes, e sim falta de uma régua explícita que diga quando um domínio está aceitavelmente coberto e que tipo de mudança deve obrigar novos testes. - -## Dor - -- Coverage global do workspace não prova que os domínios de maior risco estão realmente cobertos. -- Regressões de firmware, boot, host integration e superfícies status-first ainda podem passar com números globais "bons". -- Sem gates por domínio, futuras PRs tendem a melhorar percentuais agregados sem fechar cenários obrigatórios. -- A suíte atual está funcional, mas concentrada demais, o que dificulta enxergar lacunas e manter responsabilidade por domínio. - -## Alvo da Discussao - -Definir uma política mínima de cobertura para a borda do runtime proporcional ao risco da plataforma. - -Essa agenda deve produzir uma visão clara de: - -- quais domínios têm gate próprio; -- quais cenários mínimos cada domínio deve cobrir; -- como coverage entra como evidência operacional, sem substituir a matriz qualitativa; -- que mudanças devem obrigar teste novo antes de merge. - -## O Que Precisa Ser Definido - -1. Matriz de cobertura por domínio. - - system/runtime - - fs - - asset/bank - - firmware transitions - - host-dependent surfaces quando aplicável - -2. Tipos de teste. - - unitário puro - - integração entre runtime e VM - - testes de firmware - - testes host-dependentes isolados - -3. Gates de aceitação por domínio. - Cada domínio precisa definir ao menos: - - cenários obrigatórios; - - tipo de evidência esperada; - - leitura de coverage por domínio como evidência obrigatória de revisão; - - como o gate por domínio evolui ao longo do tempo sem bloquear a adoção inicial. - -4. Critério de severidade. - Que mudanças exigem teste novo obrigatório antes de merge, mesmo que o percentual global de coverage continue aceitável. - -5. Organização. - Onde os testes vivem para nao voltar a concentrar tudo em arquivos gigantes e para manter ownership claro por domínio. - -## O Que Ainda Precisa Ser Fechado - -- definição dos domínios canônicos e seus respectivos gates; -- definição dos cenários mínimos obrigatórios por domínio; -- política mínima para testes host-dependentes e `#[ignore]`; -- regra de convivência entre gate global de coverage e leitura segmentada por domínio; -- diretriz de organização para quebrar suites monolíticas de runtime. - -## Opcoes - -### Opcao A - Gate apenas global de coverage - -- **Abordagem:** manter somente o percentual agregado do workspace como barra de aceitação. -- **Pro:** simples de operar e fácil de automatizar no CI. -- **Con:** permite que domínios sensíveis continuem subcobertos enquanto o número global sobe. -- **Manutenibilidade:** boa operacionalmente, ruim como governança de risco. - -### Opcao B - Gate percentual rígido por domínio desde o início - -- **Abordagem:** exigir percentuais mínimos por domínio já na primeira versão da política. -- **Pro:** força disciplina quantitativa explícita por área. -- **Con:** cria atrito alto de adoção, exige segmentação mais sofisticada e pode travar a convergência inicial por falta de baseline confiável. -- **Manutenibilidade:** média; forte no longo prazo, pesada demais para o ponto atual do projeto. - -### Opcao C - Gate global de coverage + gate por domínio com coverage como evidência incremental - -- **Abordagem:** manter gate global obrigatório no CI e adotar gate por domínio baseado em cenários mandatórios e leitura de coverage segmentada como evidência. Baselines percentuais por domínio podem começar em `0` e subir com o tempo conforme a suíte amadurece. -- **Pro:** combina disciplina prática imediata com caminho realista para endurecer a barra por domínio sem bloquear a adoção. -- **Con:** exige revisão mais criteriosa, porque a aceitação não fica reduzida a um único número. -- **Manutenibilidade:** alta; permite endurecimento progressivo sem perder governança qualitativa. - -## Sugestao / Recomendacao - -Fechar esta agenda com a `Opcao C`: uma matriz pequena de domínios canônicos, gate global obrigatório de coverage e gate por domínio baseado em cenários mandatórios, usando leitura segmentada de `llvm-cov` como evidência de revisão e baseline quantitativo incremental. - -### Domínios canônicos propostos - -1. `system/runtime` -2. `fs` -3. `asset/bank` -4. `firmware` -5. `host-dependent` - -### Gates propostos por domínio - -#### `system/runtime` - -Cenários mínimos: - -- `init` -- `reset / cleanup` -- `trap vs panic` -- `pause / breakpoint` -- fronteira de `FRAME_SYNC` e budget - -Regra de aceitação: - -- qualquer mudança em lifecycle, tick, crash/report, pause/debug flow ou syscall de sistema deve adicionar ou ajustar testes desse domínio; -- coverage global não substitui a obrigação de cobrir o cenário alterado. - -#### `fs` - -Cenários mínimos: - -- happy path; -- path inválido / traversal; -- backend unhealthy; -- cleanup de handles e estado após reset/unmount quando aplicável. - -Regra de aceitação: - -- qualquer mudança em normalização de path, mount/unmount, handles ou contrato guest-host de filesystem deve adicionar ou ajustar testes desse domínio. - -#### `asset/bank` - -Cenários mínimos: - -- preload; -- `load / status / commit / cancel`; -- asset ausente; -- slot inválido; -- erro estrutural de bootstrap vs erro operacional em runtime. - -Regra de aceitação: - -- qualquer mudança em cartridge loader, preload, asset bridge, slot telemetry ou semântica status-first deve adicionar ou ajustar testes desse domínio. - -#### `firmware` - -Cenários mínimos: - -- fluxo de load do cart; -- branch por `AppMode`; -- falha de init levando ao crash path; -- coordenação básica de boot target e transição de estado. - -Regra de aceitação: - -- qualquer mudança em boot flow, cartridge launch, state transition ou crash path deve adicionar ou ajustar testes desse domínio. - -Observação: - -- este é o domínio com maior lacuna atual e deve ser a prioridade principal de expansão da suíte. - -#### `host-dependent` - -Cenários mínimos: - -- superfícies que dependem de socket, janela ou integração desktop devem ficar isoladas; -- quando possível, a parte determinística da regra deve existir também em teste console/runtime. - -Regra de aceitação: - -- testes `#[ignore]` são permitidos quando dependem de infraestrutura local real, mas devem trazer justificativa explícita; -- mudanças host-only não podem empurrar comportamento determinístico para testes exclusivamente desktop quando esse comportamento puder ser validado abaixo do host. - -Observação: - -- `host-dependent` não é um subsistema funcional paralelo a `fs` ou `firmware`; é um corte transversal de testabilidade e execução que governa onde certos testes podem viver e como devem ser justificados. - -### Uso de coverage - -- `coverage` global via `cargo llvm-cov` continua como gate operacional mínimo do CI; -- leitura segmentada por domínio deve ser usada como evidência obrigatória de revisão quando uma mudança tocar área sensível; -- percentuais por domínio podem começar em baseline `0` e subir progressivamente conforme o projeto estabiliza a segmentação e a matriz de testes; -- percentual global aceitável não dispensa cobertura dos cenários mandatórios do domínio afetado. - -### Prioridades sugeridas - -1. expandir cobertura de `firmware`; -2. consolidar política de `host-dependent`; -3. quebrar a suíte monolítica de `system/runtime` por responsabilidade, conforme os domínios forem sendo tocados; -4. manter `fs` e `asset/bank` como domínios já relativamente encaminhados, mas ainda sob gate explícito. - -### Barra sugerida para PRs - -- nenhum PR que altere domínio canônico deve entrar sem tocar testes do domínio afetado, ou sem justificar explicitamente por que o contrato observável não mudou; -- melhoria de coverage agregada é desejável, mas não conta como evidência suficiente sem cenário alinhado ao domínio alterado. - -## Perguntas em Aberto - -- Nenhuma ambiguidade arquitetural substantiva restante para fechar a política base. -- O endurecimento quantitativo por domínio fica explicitamente como evolução incremental a partir de baseline inicial `0`, sem bloquear a adoção imediata da política. - -## Estado Atual Relevante - -- O repositório já possui targets de coverage com `cargo llvm-cov` no `Makefile`. -- O CI já aplica gate global mínimo de coverage via Jenkins. -- O runtime já possui cobertura relevante para traps, status-first, assets, composer, audio, memcard e reset. -- `VirtualFS` já cobre parte importante do contrato de path normalization e rejeições antes do backend. -- Ainda falta tratar firmware transitions e superfícies host-dependent como domínios explicitamente governados pela agenda. - -## Fora de Escopo - -- benchmark/performance suite; -- fuzzing completo de toda a ISA; -- troca de ferramenta de coverage; -- perseguir 100% global como objetivo primário; -- transformar coverage percentual em substituto de cenários normativos. - -## Critério de Saida Desta Agenda - -Pode virar PR quando houver: - -- matriz de gates por domínio aprovada; -- lista de cenários mínimos por domínio; -- política explícita para testes host-dependent / `#[ignore]`; -- uso de `llvm-cov` encaixado como evidência operacional; -- barra clara para aceitar novas syscalls, mudanças de runtime e transições de firmware. diff --git a/discussion/workflow/decisions/DEC-0020-runtime-edge-coverage-governance-by-domain.md b/discussion/workflow/decisions/DEC-0020-runtime-edge-coverage-governance-by-domain.md deleted file mode 100644 index 6cc8dce9..00000000 --- a/discussion/workflow/decisions/DEC-0020-runtime-edge-coverage-governance-by-domain.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -id: DEC-0020 -ticket: runtime-edge-test-plan -title: Decision - Runtime Edge Coverage Governance by Domain -status: in_progress -created: 2026-04-20 -accepted: 2026-04-20 -agenda: AGD-0001 -plans: [PLN-0037, PLN-0038, PLN-0039] -tags: [tests, coverage, runtime, firmware, host] ---- - -## Status - -In progress. - -Derived from `AGD-0001`. - -This decision records the normative direction for runtime edge coverage governance. -It has been accepted and now drives one or more execution plans. - -## Contexto - -PROMETEU no longer has the same problem that originally motivated `AGD-0001`. -The runtime edge is no longer broadly untested. The repository now already contains meaningful coverage for runtime lifecycle paths, `VirtualFS`, asset/preload behavior, status-first surfaces, and part of the desktop host integration. - -The remaining problem is governance, not raw test absence. - -Global coverage metrics already exist through `cargo llvm-cov`. A single aggregated workspace gate proved useful, but insufficient on its own. A good aggregated number does not guarantee that firmware transitions, boot flow, host-dependent surfaces, or domain-specific status-first contracts are covered at the right level. - -The project therefore needs an explicit domain-based acceptance model for tests: - -- a small canonical domain set; -- mandatory scenarios per domain; -- a rule for when a change must add or adjust tests; -- a clear relationship between global coverage and domain-oriented evidence. - -## Decisao - -PROMETEU SHALL govern runtime-edge test sufficiency through a domain-first model: - -1. a mandatory CI gate enforced from the canonical runtime-edge domains; and -2. a domain-based acceptance gate driven by mandatory scenarios plus domain-scoped coverage evidence. - -The canonical domains SHALL be: - -1. `system/runtime` -2. `fs` -3. `asset/bank` -4. `firmware` -5. `host-dependent` - -`host-dependent` SHALL be treated as a transversal execution/testability slice, not as a product subsystem parallel to `fs`, `asset/bank`, or `firmware`. - -Domain gates SHALL be scenario-first. -Coverage percentages by domain MAY exist, but they SHALL start from an initial baseline of `0` and SHALL be tightened incrementally over time as segmentation and suites mature. - -No PR that changes the observable contract of a canonical domain SHALL be accepted without one of the following: - -- tests added or adjusted for that domain; or -- an explicit justification that the observable contract did not change. - -Improved aggregate coverage SHALL NOT be accepted as sufficient evidence on its own when the changed behavior belongs to a canonical domain with mandatory scenarios. -Workspace-wide aggregate coverage MAY still be generated as a report artifact, but it SHALL NOT be the authoritative CI acceptance gate. - -## Rationale - -### Why not global-only coverage - -A single global percentage is easy to automate, but too weak as a risk control. -It allows firmware and host-sensitive regressions to hide behind unrelated line execution elsewhere in the workspace. - -### Why not rigid per-domain percentages immediately - -The project does not yet have a stable enough domain segmentation baseline to enforce hard per-domain minimums from day one without adding friction disproportionate to the benefit. - -Starting from `0` preserves forward motion while still making domain evidence mandatory during review. - -### Why scenario-first - -The platform risk lies in behavioral contracts: - -- lifecycle boundaries, -- boot transitions, -- status-first surfaces, -- filesystem normalization and invalid-state handling, -- preload/bootstrap versus runtime operational failures, -- host-only integration boundaries. - -Those are not safely governed by percentages alone. - -### Why keep coverage in the model - -Coverage remains useful as: - -- an operational CI signal; -- a regression detector; -- a way to inspect whether the changed domain actually exercised the intended area. - -The correct role of coverage is supporting evidence, not sole authority. - -## Invariantes / Contrato - -### CI Coverage Contract - -- CI MUST enforce coverage from the canonical runtime-edge domains instead of a workspace-wide aggregate percentage. -- The current `llvm-cov` toolchain remains valid as the operational baseline. -- Changing the tooling is out of scope for this decision. -- The authoritative quantitative CI gate is each domain `baseline_percent`, evaluated against domain `lines` coverage. - -### Domain Gate Contract - -Each canonical domain MUST define mandatory scenarios and acceptance expectations. - -#### `system/runtime` - -Mandatory scenarios: - -- initialization; -- reset and cleanup; -- trap versus panic behavior; -- pause and breakpoint behavior; -- `FRAME_SYNC` and budget boundary behavior. - -#### `fs` - -Mandatory scenarios: - -- happy path; -- invalid path / traversal rejection; -- unhealthy backend behavior; -- cleanup of handles and state after reset/unmount when applicable. - -#### `asset/bank` - -Mandatory scenarios: - -- preload behavior; -- `load / status / commit / cancel`; -- missing asset handling; -- invalid slot handling; -- structural bootstrap failure versus operational runtime failure. - -#### `firmware` - -Mandatory scenarios: - -- cartridge load flow; -- `AppMode` branch behavior; -- VM/runtime initialization failure leading to crash path; -- basic boot-target and state-transition coordination. - -#### `host-dependent` - -Mandatory scenarios: - -- host-only behaviors that require real socket, window, or desktop integration MUST be isolated; -- deterministic parts of those rules SHOULD exist below the host layer whenever feasible. - -### Review Contract - -- Any PR touching a canonical domain MUST review the domain gate explicitly. -- Domain-scoped coverage inspection MUST be part of review evidence when the domain is materially touched. -- Domain percentage baselines MAY start at `0`, but they MUST be allowed to rise over time rather than remain permanently undefined. - -### Organization Contract - -- Test suites SHOULD move toward domain-oriented ownership. -- Monolithic suites MAY be split incrementally as touched by real work. -- This decision does NOT require a one-shot refactor of the entire current test tree. - -## Impactos - -### Spec - -- The testing policy now has a normative direction suitable for a future plan and eventual publication in the repository's process/spec surfaces if desired. - -### Runtime - -- Runtime-area changes gain an explicit expectation that domain tests move with behavior changes. - -### Firmware - -- Firmware transitions become a first-class governed testing domain rather than an implicit gap. - -### Host - -- Host-dependent tests become explicitly governed and justified, rather than ad hoc exceptions. - -### Tooling / CI - -- Existing `llvm-cov` and Jenkins integration remain valid. -- Jenkins MUST call repository helpers that compute and enforce the domain coverage gate. -- Workspace aggregate reports may continue to be published for inspection, but they are not the merge gate. - -## Referencias - -- `AGD-0001` -- `Makefile` -- `files/config/Jenkinsfile` -- `files/config/runtime-edge-coverage-domains.json` -- `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md` -- `crates/console/prometeu-system/src/virtual_machine_runtime/tests.rs` -- `crates/console/prometeu-system/src/services/fs/virtual_fs.rs` -- `crates/host/prometeu-host-desktop-winit/src/runner.rs` - -## Propagacao Necessaria - -- Create or revise execution plans that turn the domain model into concrete CI and review work items. -- Define how domain evidence will be gathered during review. -- Keep helper commands or scripts as the canonical interface for domain-oriented coverage inspection and CI enforcement. -- Prioritize firmware and host-dependent expansion first. -- Define an incremental split strategy for the monolithic runtime test suite. diff --git a/discussion/workflow/plans/PLN-0037-runtime-edge-coverage-governance-foundation.md b/discussion/workflow/plans/PLN-0037-runtime-edge-coverage-governance-foundation.md deleted file mode 100644 index 94eead3f..00000000 --- a/discussion/workflow/plans/PLN-0037-runtime-edge-coverage-governance-foundation.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -id: PLN-0037 -ticket: runtime-edge-test-plan -title: Plan - Runtime Edge Coverage Governance Foundation -status: done -created: 2026-04-20 -completed: 2026-04-20 -tags: [tests, coverage, governance, ci] ---- - -## Briefing - -This plan operationalizes the governance layer of `DEC-0020`. -Its goal is to turn the decision into concrete review and CI mechanics without changing the underlying coverage toolchain. - -## Decisions de Origem - -- `DEC-0020` - -## Alvo - -Define the repository-level mechanics for: - -- domain coverage gate enforcement in CI; -- domain-scoped coverage evidence during review; -- baseline tracking that can start at `0` per domain and tighten later; -- reviewer-visible rules for when domain tests are mandatory. - -## Escopo - -- Add repository commands or scripts for domain-oriented coverage evidence collection. -- Add repository-facing documentation that explains the domain gate plus domain evidence workflow. -- Align CI/coverage outputs with the new governance model without replacing `llvm-cov`. - -## Fora de Escopo - -- Expanding firmware tests. -- Refactoring the monolithic runtime suite. -- Introducing hard domain coverage percentages above baseline `0`. -- Replacing Jenkins or `cargo llvm-cov`. - -## Plano de Execucao - -### Step 1 - Define the domain evidence interface - -**What:** -Define how contributors and reviewers gather coverage evidence for `system/runtime`, `fs`, `asset/bank`, `firmware`, and `host-dependent`. - -**How:** -Add one repository-visible command path that produces: - -- existing global HTML/XML/JSON coverage artifacts; -- a documented procedure for mapping changed files/modules to one of the canonical domains; -- an initial baseline format that records per-domain coverage starting from `0`; -- a CI-friendly command that fails when a domain baseline is not met. - -**File(s):** -- `Makefile` -- `scripts/` -- `README.md` or another repository-facing process document if more appropriate - -### Step 2 - Add domain evidence helpers - -**What:** -Introduce helper commands or scripts that make domain evidence collection reproducible. - -**How:** -Prefer simple wrappers over new tooling. For example: - -- capture `llvm-cov` JSON/HTML consistently; -- filter or summarize target files/modules for a domain; -- emit review-friendly evidence artifacts while also enforcing the authoritative domain gate. - -**File(s):** -- `Makefile` -- `scripts/` - -### Step 3 - Document the PR acceptance rule - -**What:** -Publish the decision’s review contract in a place visible during development. - -**How:** -Document that any PR touching a canonical domain must either: - -- update/add tests for that domain; or -- justify why the observable contract did not change. - -Document that domain coverage evidence is mandatory review input even when domain thresholds are still at baseline `0`. -Document that Jenkins consumes the repository helper target directly instead of re-implementing the gate inline. - -**File(s):** -- `README.md` -- optional repo process document if the repository has a better canonical location - -### Step 4 - Align CI outputs with the governance model - -**What:** -Make the existing coverage pipeline clearly compatible with domain review and domain-based CI failure. - -**How:** -Make Jenkins call a repository helper target that runs the coverage pipeline, produces the existing artifacts, and fails from domain baselines. -If needed, archive additional summaries or helper outputs generated by the new scripts. - -**File(s):** -- `files/config/Jenkinsfile` -- `Makefile` - -## Criterios de Aceite - -- [ ] The repository exposes a documented way to collect domain-oriented coverage evidence and enforce domain baselines in CI. -- [ ] Review guidance explicitly states when domain tests are mandatory. -- [ ] Domain baselines are represented in a form that can start at `0` and increase later. -- [ ] Jenkins uses a repository-owned helper target for the coverage gate. - -## Tests / Validacao - -### Automated - -- Validate all added helper commands locally. -- Run the existing coverage pipeline end to end after the helper changes. - -### Evidence - -- Show that the global coverage artifacts still build. -- Show an example of domain evidence collection for at least one domain. -- Show that the domain gate fails when a baseline is missed. - -## Riscos - -- Overdesigning domain evidence collection before real reviewer usage patterns exist. -- Letting Jenkins re-encode policy logic instead of consuming the repository helper target. -- Spreading policy text across too many documents and making the rule hard to find. diff --git a/discussion/workflow/plans/PLN-0038-firmware-and-host-dependent-domain-coverage-expansion.md b/discussion/workflow/plans/PLN-0038-firmware-and-host-dependent-domain-coverage-expansion.md deleted file mode 100644 index 01dce05b..00000000 --- a/discussion/workflow/plans/PLN-0038-firmware-and-host-dependent-domain-coverage-expansion.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -id: PLN-0038 -ticket: runtime-edge-test-plan -title: Plan - Firmware and Host-Dependent Domain Coverage Expansion -status: done -created: 2026-04-20 -completed: 2026-04-20 -tags: [tests, firmware, host, coverage] ---- - -## Briefing - -This plan executes the priority expansion areas mandated by `DEC-0020`: `firmware` and `host-dependent`. -The objective is not blanket test growth, but closing the most important domain gaps first. - -## Decisions de Origem - -- `DEC-0020` - -## Alvo - -Expand automated evidence for: - -- firmware load and state-transition rules; -- `AppMode` branching; -- crash-path transitions from VM/runtime initialization and runtime execution; -- host-dependent desktop/debugger behaviors that legitimately require socket or window integration. - -## Escopo - -- Add or refine firmware tests in `prometeu-firmware`. -- Add or refine isolated host-dependent tests in the desktop host crate. -- Clarify which host behaviors must remain ignored/integration-style and which deterministic pieces should move below the host. - -## Fora de Escopo - -- Full test-tree reorganization across all runtime domains. -- Hard domain thresholds above baseline `0`. -- Reworking the public debugger protocol itself unless required by testability. - -## Plano de Execucao - -### Step 1 - Close firmware state-transition gaps - -**What:** -Expand firmware coverage around canonical state behavior, not only isolated happy paths. - -**How:** -Add tests around: - -- `Reset` to boot-target-driven transitions; -- `LaunchHub` behavior for `BootTarget::Hub` versus `BootTarget::Cartridge`; -- `LoadCartridge` branch behavior for `AppMode::Game` versus `AppMode::System`; -- transition to `AppCrashes` when initialization or runtime execution fails. - -**File(s):** -- `crates/console/prometeu-firmware/src/firmware/firmware.rs` -- `crates/console/prometeu-firmware/src/firmware/firmware_step_reset.rs` -- `crates/console/prometeu-firmware/src/firmware/firmware_step_launch_hub.rs` -- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs` -- `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs` -- `crates/console/prometeu-firmware/src/firmware/firmware_step_crash_screen.rs` - -### Step 2 - Delimit host-dependent versus deterministic behavior - -**What:** -Make the boundary between true host integration and lower-layer deterministic behavior explicit in tests. - -**How:** -Review existing desktop-host tests and classify them: - -- tests that truly require socket bind/connect or window integration remain host-dependent and may stay `#[ignore]`; -- deterministic logic should be covered in firmware/runtime/host-internal tests that do not require real integration. - -**File(s):** -- `crates/host/prometeu-host-desktop-winit/src/runner.rs` -- `crates/host/prometeu-host-desktop-winit/src/debugger.rs` - -### Step 3 - Strengthen the host-dependent suite without widening its scope - -**What:** -Keep real integration tests focused on behaviors the lower layers cannot prove. - -**How:** -Prioritize cases such as: - -- debugger socket open/handshake lifecycle; -- reconnect/refuse-second-connection behavior; -- resume/pause/disconnect coordination when the real host wiring is part of the rule. - -Avoid pushing general deterministic state logic into ignored desktop-only tests if it can be covered below the host. - -**File(s):** -- `crates/host/prometeu-host-desktop-winit/src/runner.rs` -- `crates/host/prometeu-host-desktop-winit/src/debugger.rs` - -### Step 4 - Capture evidence for the two priority domains - -**What:** -Produce explicit review evidence showing that `firmware` and `host-dependent` are now governed domains rather than implied gaps. - -**How:** -Use the governance helpers from `PLN-0037` if available, or temporary documented evidence if it lands first. - -**File(s):** -- firmware and host test targets -- coverage/report artifacts as defined by the governance plan - -## Criterios de Aceite - -- [ ] Firmware has explicit automated coverage for boot-target transitions, `AppMode` branching, and crash-path transitions. -- [ ] Host-dependent tests are clearly limited to behaviors that genuinely require desktop/socket integration. -- [ ] Deterministic behavior that does not need real host integration is covered below the host when feasible. -- [ ] Review evidence can point to firmware and host-dependent coverage separately from the global aggregate. - -## Tests / Validacao - -### Unit / Integration - -- Run `cargo test -p prometeu-firmware`. -- Run the relevant desktop host tests. - -### Host-Dependent - -- Run `cargo test -p prometeu-host-desktop-winit --lib -- --ignored`. - -### Evidence - -- Produce coverage evidence for touched firmware files and host-dependent integration paths. - -## Riscos - -- Adding host-only tests for behavior that belongs below the host boundary. -- Expanding firmware tests without aligning them to the state machine contract in the specs. -- Overfitting ignored integration tests to desktop timing details. diff --git a/discussion/workflow/plans/PLN-0039-incremental-runtime-domain-suite-split-and-baselines.md b/discussion/workflow/plans/PLN-0039-incremental-runtime-domain-suite-split-and-baselines.md deleted file mode 100644 index 55121b87..00000000 --- a/discussion/workflow/plans/PLN-0039-incremental-runtime-domain-suite-split-and-baselines.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -id: PLN-0039 -ticket: runtime-edge-test-plan -title: Plan - Incremental Runtime Domain Suite Split and Baselines -status: done -created: 2026-04-20 -completed: 2026-04-20 -tags: [tests, runtime, fs, asset, organization] ---- - -## Briefing - -This plan turns the current monolithic runtime-edge suite into clearer domain-owned test surfaces over time, while preserving the existing breadth of coverage already present in `prometeu-system`. - -## Decisions de Origem - -- `DEC-0020` - -## Alvo - -Establish clearer test ownership and baseline evidence for: - -- `system/runtime` -- `fs` -- `asset/bank` - -Do this incrementally, without a one-shot refactor of the whole runtime test tree. - -## Escopo - -- Split the current runtime-edge suite along canonical domain lines as work touches those areas. -- Preserve or improve current behavioral coverage while improving maintainability. -- Establish explicit baseline evidence for the non-priority domains, starting from `0` if needed. - -## Fora de Escopo - -- Rewriting all tests in one pass. -- Large behavioral refactors unrelated to test structure. -- Introducing strict non-zero domain thresholds immediately. - -## Plano de Execucao - -### Step 1 - Define the split targets for the existing monolithic suite - -**What:** -Map the current `virtual_machine_runtime/tests.rs` coverage into the canonical runtime domains. - -**How:** -Create a target decomposition for the current file, separating at least: - -- `system/runtime` lifecycle and tick behavior; -- `asset/bank` status-first and preload behavior; -- `fs` and memcard-adjacent runtime cases when they belong to runtime orchestration rather than `VirtualFS` internals. - -Do not move files blindly. First define the intended ownership map. - -**File(s):** -- `crates/console/prometeu-system/src/virtual_machine_runtime/tests.rs` -- `crates/console/prometeu-system/src/virtual_machine_runtime/` - -### Step 2 - Split the runtime suite incrementally - -**What:** -Reduce the monolithic test concentration without destabilizing current coverage. - -**How:** -As each domain is touched, move or extract tests into smaller modules with domain ownership. -Prefer incremental Rust module splits such as domain-focused test modules over an all-at-once rewrite. - -**File(s):** -- `crates/console/prometeu-system/src/virtual_machine_runtime/tests.rs` -- new sibling test modules under `crates/console/prometeu-system/src/virtual_machine_runtime/` - -### Step 3 - Preserve and expose `fs` and `asset/bank` baselines - -**What:** -Make existing stronger areas explicitly visible in the new governance model. - -**How:** -Use: - -- `crates/console/prometeu-system/src/services/fs/virtual_fs.rs` for filesystem contract evidence; -- runtime and loader tests for `asset/bank` scenario evidence. - -Capture baseline evidence even if the numeric threshold remains `0` initially. - -**File(s):** -- `crates/console/prometeu-system/src/services/fs/virtual_fs.rs` -- `crates/console/prometeu-system/src/virtual_machine_runtime/tests.rs` -- `crates/console/prometeu-hal/src/cartridge_loader.rs` -- `crates/console/prometeu-drivers/src/asset.rs` - -### Step 4 - Align future review with the new runtime-domain ownership - -**What:** -Ensure later PRs can tell which runtime-domain tests should move with the code. - -**How:** -Document or encode enough structure that maintainers can tell where to add tests for: - -- lifecycle/tick behavior; -- filesystem normalization and runtime cleanup; -- asset/bootstrap/status-first flows. - -**File(s):** -- runtime test modules -- repository guidance introduced by `PLN-0037` - -## Criterios de Aceite - -- [ ] The current monolithic runtime suite has an explicit decomposition into canonical domains. -- [ ] New or moved runtime tests follow domain ownership rather than returning to a single catch-all file. -- [ ] `fs` and `asset/bank` have baseline evidence captured under the governance model. -- [ ] The split is incremental and does not require a one-shot rewrite to start delivering value. - -## Tests / Validacao - -### Automated - -- Run `cargo test -p prometeu-system`. -- Run any focused tests for `prometeu-hal` and `prometeu-drivers` touched during the split. - -### Evidence - -- Show that the domain-oriented split preserves existing runtime behaviors. -- Produce baseline coverage evidence for `system/runtime`, `fs`, and `asset/bank`. - -## Riscos - -- Moving tests mechanically without improving domain clarity. -- Creating fragmented helpers that are harder to reuse than the current monolith. -- Treating structural cleanup as more important than preserving behavioral coverage.