prometeu-runtime/discussion/workflow/agendas/AGD-0001-runtime-edge-test-plan.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0001	runtime-edge-test-plan	Agenda - Runtime Edge Test Plan	done	2026-03-27	2026-04-20	DEC-0020

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.