diff --git a/docs/pbs/pull-requests/INDEX.md b/docs/pbs/pull-requests/INDEX.md index 82e00d26..ae0cea5c 100644 --- a/docs/pbs/pull-requests/INDEX.md +++ b/docs/pbs/pull-requests/INDEX.md @@ -114,3 +114,14 @@ Prerequisito de execucao: concluir a Onda O5.0. 6. `PR-05.6-optimize-irvm-real-deterministic-passes.md` 7. `PR-05.7-gate-i-runtime-backed-mandatory-in-ci.md` 8. `PR-05.8-backend-spec-to-test-conformance-matrix.md` + +### Onda O6 - JVM-Grade Score Evolution (8.0 -> 9.0+) + +Foco: fechar `partial/deferred` relevantes da matriz normativa e endurecer evidencia de conformidade. + +1. `PR-06.1-source-attribution-and-diagnostics-evidence-hardening.md` +2. `PR-06.2-optimize-irvm-semantic-equivalence-harness.md` +3. `PR-06.3-irvm-ext-contract-and-elimination-fixtures.md` +4. `PR-06.4-gate-i-runtime-line-repeatability-ci.md` +5. `PR-06.5-conformance-matrix-hard-gate-policy.md` +6. `PR-06.6-spawn-yield-v1-or-claim-rescope.md` diff --git a/docs/pbs/pull-requests/PR-06.1-source-attribution-and-diagnostics-evidence-hardening.md b/docs/pbs/pull-requests/PR-06.1-source-attribution-and-diagnostics-evidence-hardening.md new file mode 100644 index 00000000..3aa13b04 --- /dev/null +++ b/docs/pbs/pull-requests/PR-06.1-source-attribution-and-diagnostics-evidence-hardening.md @@ -0,0 +1,72 @@ +# PR-06.1 - Source Attribution and Diagnostics Evidence Hardening + +## Briefing + +Ha cobertura parcial para preservacao de `source attribution` em rejeicoes backend e no handoff executavel. + +Esta PR fecha os gaps de evidencia para requisitos de atribuicao de origem e estabilidade de diagnostico. + +## Motivation + +### Dor atual que esta PR resolve + +1. Falta de prova forte de que erros backend preservam `file/start/end` quando acionaveis pelo usuario. +2. Parte da matriz marca `partial` para requisitos de atribuicao (`G20-11.3`, `PBS13-12.1.4`). +3. Revisao de regressao de spans depende de inspeccao manual. + +## Target + +Cobertura automatizada para atribuicao de origem em diagnosticos de falha backend e no contrato executavel. + +## Dependencies + +Prerequisitos recomendados: + +1. `PR-05.5` (stack effects reais host/intrinsic). +2. `PR-05.8` (matriz de conformidade existente). + +## Scope + +1. Testes de atribuicao de origem para falhas deterministicas no `LowerToIRVM`. +2. Testes de atribuicao para falhas de pipeline (`BACKEND_LOWER_IRVM` e `BACKEND_EMIT_BYTECODE`) quando aplicavel. +3. Atualizacao da matriz para migrar `G20-11.3` e `PBS13-12.1.4` de `partial` para `pass` se houver cobertura completa. + +## Non-Goals + +1. Nao altera semantica de linguagem. +2. Nao introduz novas classes de diagnostico. + +## Method + +### O que deve ser feito explicitamente + +1. Criar fixtures negativas onde erro e claramente source-actionable e verificar: + - `code` estavel, + - `phase` estavel, + - `file/start/end` presentes e coerentes. +2. Garantir que spans de instrucoes/callsites sejam propagadas ativamente para as mensagens de falha. +3. Atualizar a matriz com referencias exatas de teste. + +## Acceptance Criteria + +1. Falhas source-actionable do backend expõem atribuicao de origem valida. +2. Requisitos `G20-11.3` e `PBS13-12.1.4` saem de `partial` se cobertura completa for atingida. +3. Nenhuma regressao em testes existentes de taxonomia de erro. + +## Tests + +1. Novos testes unitarios/integracao para spans em diagnosticos de falha. +2. Reexecucao obrigatoria: + - `:prometeu-compiler:prometeu-build-pipeline:test` + - `:prometeu-compiler:prometeu-frontend-api:test` + +## Affected Documents + +1. `docs/general/specs/19. Verification and Safety Checks Specification.md` +2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md` +3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md` +4. `docs/pbs/specs/13. Lowering IRBackend Specification.md` + +## Open Questions + +Sem bloqueios arquiteturais. diff --git a/docs/pbs/pull-requests/PR-06.2-optimize-irvm-semantic-equivalence-harness.md b/docs/pbs/pull-requests/PR-06.2-optimize-irvm-semantic-equivalence-harness.md new file mode 100644 index 00000000..b9b25c10 --- /dev/null +++ b/docs/pbs/pull-requests/PR-06.2-optimize-irvm-semantic-equivalence-harness.md @@ -0,0 +1,75 @@ +# PR-06.2 - OptimizeIRVM Semantic Equivalence Harness + +## Briefing + +A etapa `OptimizeIRVM` ja possui passes reais, mas a prova de equivalencia semantica ainda esta parcial. + +Esta PR cria harness sistematico para validar comportamento observavel com `opt on/off`. + +## Motivation + +### Dor atual que esta PR resolve + +1. Evidencia de equivalencia semantica ainda e fixture-level limitada. +2. Itens `G21-6.2`, `G21-7.1` e `G21-9.1` permanecem `partial`. +3. Risco de pass regressivo sem deteccao ampla. + +## Target + +Harness de equivalencia deterministica com corpus de CFG e chamadas host/intrinsic. + +## Dependencies + +Prerequisitos diretos: + +1. `PR-05.6` (pass manager real). +2. `PR-05.7` (Gate I estrito em CI). + +## Scope + +1. Framework de comparacao `optimized` vs `non-optimized`. +2. Fixtures representativas: + - sequencias lineares, + - condicional com joins, + - loops simples, + - hostcall/intrinsic. +3. Assercoes de invariantes: + - semantica observavel equivalente, + - determinismo de output, + - contratos de slots preservados. + +## Non-Goals + +1. Nao inclui prova formal completa. +2. Nao adiciona otimizacoes agressivas interprocedurais. + +## Method + +### O que deve ser feito explicitamente + +1. Expor no teste caminho `optimize on/off` para o mesmo `IRVMProgram`. +2. Comparar resultado observavel em nivel de artefato e checagens Gate I/S-U. +3. Cobrir casos negativos em que pass invalido deve falhar por perfil/contrato. +4. Atualizar a matriz para converter requisitos `partial` quando cobertos. + +## Acceptance Criteria + +1. Existe harness reutilizavel de equivalencia `opt on/off`. +2. Cobertura de CFG e chamadas host/intrinsic com assercao de equivalencia. +3. `G21-6.2`, `G21-7.1`, `G21-9.1` evoluem para `pass` se cobertura completa. + +## Tests + +1. Novos testes no pacote `backend/irvm` e/ou `integration`. +2. Reexecucao obrigatoria: + - `:prometeu-compiler:prometeu-build-pipeline:test` + +## Affected Documents + +1. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md` +2. `docs/general/specs/19. Verification and Safety Checks Specification.md` +3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md` + +## Open Questions + +Sem bloqueios arquiteturais. diff --git a/docs/pbs/pull-requests/PR-06.3-irvm-ext-contract-and-elimination-fixtures.md b/docs/pbs/pull-requests/PR-06.3-irvm-ext-contract-and-elimination-fixtures.md new file mode 100644 index 00000000..7736d66a --- /dev/null +++ b/docs/pbs/pull-requests/PR-06.3-irvm-ext-contract-and-elimination-fixtures.md @@ -0,0 +1,69 @@ +# PR-06.3 - IRVM_EXT Contract and Elimination Fixtures + +## Briefing + +O contrato de `IRVM_EXT` esta parcialmente coberto apenas pelo `INTERNAL_EXT` atual. + +Esta PR amplia cobertura para garantir metadados estruturais e eliminacao antes da emissao. + +## Motivation + +### Dor atual que esta PR resolve + +1. Requisito `G20-6.2` permanece `partial`. +2. Falta evidencia para mais de um formato de extensao interna. +3. Dificuldade de evoluir extensoes com seguranca sem regressao de precheck. + +## Target + +Suite de fixtures para contrato de `IRVM_EXT` e precondicao de eliminacao no caminho de emissao. + +## Dependencies + +Prerequisitos diretos: + +1. `PR-05.6` (otimizador ativo). +2. `PR-05.4` (coerencia de programa sem bypass). + +## Scope + +1. Fixtures com multiplas op variantes internas (ou metadados distintos equivalentes). +2. Validacao explicita de metadados estruturais (`pops/pushes/branch/terminator`). +3. Prova de rejeicao quando opcode interno residual chega ao emit. + +## Non-Goals + +1. Nao define novas extensoes de runtime. +2. Nao altera ISA core publicado. + +## Method + +### O que deve ser feito explicitamente + +1. Adicionar cenarios de teste para `IRVM_EXT` alem do caso trivial existente. +2. Verificar que `OptimizeIRVM` elimina extensoes internas em caminho canônico. +3. Verificar que `EmitBytecode` falha deterministicamente quando extensao residual permanece. +4. Atualizar a matriz para `G20-6.2` conforme cobertura final. + +## Acceptance Criteria + +1. Contrato estrutural de `IRVM_EXT` fica provado por testes dedicados. +2. Caminho de eliminacao pre-emissao e coberto com positivo/negativo. +3. `G20-6.2` evolui para `pass` se cobertura completa. + +## Tests + +1. `IRVMValidatorTest` e `OptimizeIRVMServiceTest` com novos casos. +2. `EmitBytecodePipelineStageTest` para residual interno. +3. Reexecucao: + - `:prometeu-compiler:prometeu-build-pipeline:test` + +## Affected Documents + +1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md` +2. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md` +3. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md` + +## Open Questions + +Sem bloqueios arquiteturais. diff --git a/docs/pbs/pull-requests/PR-06.4-gate-i-runtime-line-repeatability-ci.md b/docs/pbs/pull-requests/PR-06.4-gate-i-runtime-line-repeatability-ci.md new file mode 100644 index 00000000..3defce55 --- /dev/null +++ b/docs/pbs/pull-requests/PR-06.4-gate-i-runtime-line-repeatability-ci.md @@ -0,0 +1,68 @@ +# PR-06.4 - Gate I Runtime-Line Repeatability in CI + +## Briefing + +Gate I ja suporta modo estrito runtime-backed, mas a prova de repetibilidade por runtime line ainda esta parcial. + +Esta PR endurece CI para validar repetibilidade em mais de uma linha de runtime suportada. + +## Motivation + +### Dor atual que esta PR resolve + +1. `G19-5.2.8` permanece `partial`. +2. Falta evidencia de comportamento repetivel entre linhas de runtime. +3. Claim de integracao forte fica fragil sem execucao multi-line. + +## Target + +Pipeline CI com Gate I estrito e validacao de repetibilidade em matrix de runtime line. + +## Dependencies + +Prerequisitos diretos: + +1. `PR-05.7` (modo estrito runtime-backed). +2. disponibilidade de pelo menos duas linhas de runtime executaveis no CI. + +## Scope + +1. Configuracao CI para `PROMETEU_GATE_I_STRICT=true`. +2. Parametrizacao de `PROMETEU_RUNTIME_CHECK_CMD` por runtime line. +3. Registro de evidencia de execucao por linha (log/sumario de job). + +## Non-Goals + +1. Nao altera implementacao do runtime. +2. Nao define politica de suporte de longo prazo entre linhas. + +## Method + +### O que deve ser feito explicitamente + +1. Adicionar jobs ou matrix de CI para linhas de runtime alvo. +2. Garantir falha obrigatoria quando runtime-backed nao estiver ativo. +3. Adicionar teste/documentacao que explicite `adapterMode`, `runtimeLine` e motivo. +4. Atualizar matriz de conformidade para `G19-5.2.8`. + +## Acceptance Criteria + +1. CI falha se Gate I cair em fallback em modo estrito. +2. CI executa Gate I em >= 2 linhas de runtime declaradas. +3. `G19-5.2.8` evolui para `pass` se repetibilidade multi-line for comprovada. + +## Tests + +1. Testes de adapter strict ja existentes continuam verdes. +2. Execucao obrigatoria de Gate I em matrix CI com runtime-backed real. + +## Affected Documents + +1. `docs/general/specs/13. Conformance Test Specification.md` +2. `docs/general/specs/19. Verification and Safety Checks Specification.md` +3. `docs/general/specs/17. Compatibility and Evolution Policy.md` +4. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md` + +## Open Questions + +1. Definir oficialmente quais runtime lines entram na matrix minima obrigatoria. diff --git a/docs/pbs/pull-requests/PR-06.5-conformance-matrix-hard-gate-policy.md b/docs/pbs/pull-requests/PR-06.5-conformance-matrix-hard-gate-policy.md new file mode 100644 index 00000000..dc96b585 --- /dev/null +++ b/docs/pbs/pull-requests/PR-06.5-conformance-matrix-hard-gate-policy.md @@ -0,0 +1,68 @@ +# PR-06.5 - Conformance Matrix Hard-Gate Policy + +## Briefing + +A matriz de conformidade existe e possui lint basico, mas ainda nao bloqueia de forma forte PRs que degradam evidencia. + +Esta PR transforma a matriz em hard gate processual para mudancas FE/BE com impacto de conformidade. + +## Motivation + +### Dor atual que esta PR resolve + +1. Possibilidade de drift entre comportamento real e status da matriz. +2. Risco de PR alterar pipeline sem atualizar rastreabilidade normativa. +3. Revisao depende demais de disciplina manual. + +## Target + +Politica automatizada que rejeita PR backend sem atualizacao de matriz quando ha impacto de conformidade. + +## Dependencies + +Prerequisitos diretos: + +1. `PR-05.8` (matriz + lint documental inicial). + +## Scope + +1. Regra de CI/revisao para detectar mudanca relevante em FE/BE backend. +2. Exigencia de atualizacao da matriz quando requisito normativo e impactado. +3. Politica clara para `partial/missing/deferred` e justificativa obrigatoria. + +## Non-Goals + +1. Nao substituir julgamento tecnico de revisao. +2. Nao bloquear PR puramente documental sem impacto tecnico. + +## Method + +### O que deve ser feito explicitamente + +1. Definir regra objetiva de impacto (arquivos/pacotes gatilho). +2. Implementar verificacao automatica em CI para forcar update da matriz quando gatilho ocorrer. +3. Exigir no PR referencia explicita aos Requirement IDs alterados. +4. Atualizar docs de contribuicao/qualidade com o novo gate. + +## Acceptance Criteria + +1. PR com mudanca backend relevante e sem update de matriz e rejeitada. +2. PR que altera status de requisito exige justificativa e testes referenciados. +3. Processo de revisao fica reproduzivel e auditavel. + +## Tests + +1. Testes de lint/matriz existentes continuam passando. +2. Teste de politica (script/check) com cenarios: + - mudanca relevante sem matriz -> fail, + - mudanca relevante com matriz -> pass. + +## Affected Documents + +1. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md` +2. `docs/general/specs/13. Conformance Test Specification.md` +3. `docs/pbs/specs/2. Governance and Versioning.md` + +## Open Questions + +1. Definir lista final de caminhos de codigo que acionam hard gate de matriz. diff --git a/docs/pbs/pull-requests/PR-06.6-spawn-yield-v1-or-claim-rescope.md b/docs/pbs/pull-requests/PR-06.6-spawn-yield-v1-or-claim-rescope.md new file mode 100644 index 00000000..a2dd1a5e --- /dev/null +++ b/docs/pbs/pull-requests/PR-06.6-spawn-yield-v1-or-claim-rescope.md @@ -0,0 +1,76 @@ +# PR-06.6 - SPAWN/YIELD v1 or Claim Rescope + +## Briefing + +Os requisitos `G20-9.4.2` e `G20-9.4.3` estao `deferred` porque `SPAWN/YIELD` nao fazem parte do surface executavel v1 atual. + +Esta PR fecha a pendencia por uma de duas trilhas exclusivas: + +1. implementar `SPAWN/YIELD` em v1 com testes; ou +2. ajustar claim/perfil/spec para remover obrigacao deste escopo no v1 claimado. + +## Motivation + +### Dor atual que esta PR resolve + +1. Nota JVM-grade fica penalizada por requisitos deferidos. +2. Claim de conformidade pode ficar ambiguo para auditoria externa. +3. Planejamento tecnico fica travado entre implementacao e re-scope. + +## Target + +Decisao implementada e test-backed para encerrar `deferred` com status claro. + +## Dependencies + +Prerequisitos variam por trilha: + +1. Trilha A (implementar): depende de extensao do modelo `IRBackend/IRVM` para opcodes e verificacao. +2. Trilha B (re-scope): depende de alinhamento normativo com specs/decision. + +## Scope + +1. Trilha A: + - adicionar suporte `SPAWN/YIELD`, + - validar aridade e stack constraints, + - cobrir com testes positivos/negativos. +2. Trilha B: + - ajustar documentos para deixar explicito que nao e parte do profile v1 claimado, + - atualizar matriz e policy de claim. + +## Non-Goals + +1. Nao introduzir modelo completo de concorrencia/corrotina alem do minimo normativo. +2. Nao conflitar com autoridade de runtime/ISA. + +## Method + +### O que deve ser feito explicitamente + +1. Escolher uma trilha oficial (A ou B) por decisao registrada. +2. Executar implementacao ou re-scope end-to-end (codigo + specs + matriz). +3. Garantir que `G20-9.4.2` e `G20-9.4.3` saiam de `deferred` para `pass` (A) ou status normativo explicitamente nao-aplicavel no claim v1 (B). + +## Acceptance Criteria + +1. Nao existe mais ambiguidade sobre `SPAWN/YIELD` no claim atual. +2. Matriz e specs refletem exatamente o comportamento implementado e claimado. +3. Gate de conformidade nao deixa regressao silenciosa nesses itens. + +## Tests + +1. Trilha A: + - testes de lowering/validator para `SPAWN` arg count e `YIELD` stack constraint. +2. Trilha B: + - testes de integridade documental/policy com checks de claim. + +## Affected Documents + +1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md` +2. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md` +3. `docs/general/specs/17. Compatibility and Evolution Policy.md` +4. `docs/pbs/decisions/*` (decision de escopo, quando aplicavel) + +## Open Questions + +1. Qual trilha oficial deve ser adotada: implementacao v1 (A) ou re-scope de claim (B)?