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

---
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.