diff --git a/docs/pbs/pull-requests/INDEX.md b/docs/pbs/pull-requests/INDEX.md index 593ca947..b37ba166 100644 --- a/docs/pbs/pull-requests/INDEX.md +++ b/docs/pbs/pull-requests/INDEX.md @@ -55,3 +55,29 @@ Esta sequencia organiza implementacao atomica para `IRBackend -> IRVM -> Optimiz 41. `PR-039-pbs-frontend-irbackend-v2-lowering.md` 42. `PR-040-backend-lower-to-irvm-stage-implementation.md` 43. `PR-041-backend-gate-i-runtime-compat-integration-fixtures.md` + +## JVM-Grade Remediation Waves (Execution Plan) + +Esta trilha organiza as PRs por ondas para execucao incremental com rollback simples por item. + +### Onda O1 - Conformance and Correctness Hardening + +1. `PR-O1.1-backend-diagnostics-taxonomy-and-attribution.md` +2. `PR-O1.2-irbackend-executable-contract-hardening.md` +3. `PR-O1.3-pbs-executable-lowering-fidelity.md` +4. `PR-O1.4-lower-to-irvm-callsite-prechecks.md` +5. `PR-O1.5-bytecode-debug-minimum-completeness.md` +6. `PR-O1.6-gate-su-safety-matrix-completion.md` + +### Onda O2 - JVM-Inspired Verification and Linking Boundaries + +1. `PR-O2.1-bytecode-link-precheck-stage.md` +2. `PR-O2.2-bytecode-preload-verifier.md` +3. `PR-O2.3-optimize-irvm-pass-manager-and-equivalence.md` +4. `PR-O2.4-gate-i-runtime-backed-compat-harness.md` + +### Onda O3 - Evolution and Scale + +1. `PR-O3.1-irvm-control-flow-lowering-label-resolution.md` +2. `PR-O3.2-bytecode-constpool-symbol-interning-determinism.md` +3. `PR-O3.3-irvm-profile-evolution-and-feature-gates.md` diff --git a/docs/pbs/pull-requests/PR-O1.1-backend-diagnostics-taxonomy-and-attribution.md b/docs/pbs/pull-requests/PR-O1.1-backend-diagnostics-taxonomy-and-attribution.md new file mode 100644 index 00000000..1c1bbb23 --- /dev/null +++ b/docs/pbs/pull-requests/PR-O1.1-backend-diagnostics-taxonomy-and-attribution.md @@ -0,0 +1,30 @@ +# PR-O1.1 - Backend Diagnostics Taxonomy and Attribution + +## Briefing + +Fechar lacunas de consistencia diagnostica no backend executavel, padronizando familias de erro (`MARSHAL_FORMAT_*`, `MARSHAL_LINKAGE_*`, `MARSHAL_VERIFY_PRECHECK_*`) e regras minimas de atribuicao de fonte quando o erro for acionavel pelo usuario. + +## Target + +- `prometeu-compiler/prometeu-build-pipeline` (stages e servicos de lowering/optimize/emit). +- Contratos de excecao/codigos de erro no backend. +- Mapeamento de falhas para mensagens estaveis no pipeline. + +## Method + +- Consolidar codigos de erro de backend em taxonomia unica e estavel. +- Garantir que erros source-atribuiveis propaguem `fileId/span` quando disponivel no `IRBackend`. +- Alinhar mensagens de stage para manter determinismo de identificacao entre execucoes. + +## Acceptance Criteria + +- Falhas de backend relevantes caem em uma das 3 familias normativas. +- O mesmo input gera o mesmo `error code` e mesma fase reportada. +- Erros source-atribuiveis carregam ancora primaria de fonte. +- Gate de build nao mascara codigo original do erro backend. + +## Tests + +- Unit tests para mapeamento de excecoes em cada stage (`LowerToIRVM`, `OptimizeIRVM`, `EmitBytecode`). +- Fixtures negativos garantindo estabilidade de `code`/fase/mensagem base. +- Caso com span disponivel validando atribuicao no diagnostico final. diff --git a/docs/pbs/pull-requests/PR-O1.2-irbackend-executable-contract-hardening.md b/docs/pbs/pull-requests/PR-O1.2-irbackend-executable-contract-hardening.md new file mode 100644 index 00000000..025a8e14 --- /dev/null +++ b/docs/pbs/pull-requests/PR-O1.2-irbackend-executable-contract-hardening.md @@ -0,0 +1,30 @@ +# PR-O1.2 - IRBackend Executable Contract Hardening + +## Briefing + +Endurecer o contrato de entrada do backend (`IRBackendExecutableFunction`) para reduzir ambiguidade e rejeitar estados inconsistentes antes de `LowerToIRVM`. + +## Target + +- `prometeu-compiler/prometeu-frontend-api` (`IRBackend`, `IRBackendExecutableFunction`). +- Validacoes de construcao do modelo executavel. +- Testes de contrato de modelo na API. + +## Method + +- Adicionar validacoes estruturais obrigatorias (identidade, slots, limites e metadados minimos por instrucao). +- Tornar explicita a politica para campos em branco (`moduleKey`, nomes de callsites, metadado host/intrinsic). +- Rejeitar estados impossiveis no proprio modelo, nao no emissor tardio. + +## Acceptance Criteria + +- Modelo recusa funcoes/instrucoes com combinacoes invalidas de campos. +- Contrato de `CALL_FUNC`/`CALL_HOST`/`CALL_INTRINSIC` fica mutuamente exclusivo e completo. +- Campos de slot/stack nao aceitam valores negativos. +- Testes de contrato cobrem casos validos e invalidos deterministas. + +## Tests + +- `IRBackendExecutableContractTest` ampliado para validacoes novas. +- Testes de construtor para cada kind de instrucao com metadados obrigatorios. +- Testes de regressao para aceitar payloads validos atuais. diff --git a/docs/pbs/pull-requests/PR-O1.3-pbs-executable-lowering-fidelity.md b/docs/pbs/pull-requests/PR-O1.3-pbs-executable-lowering-fidelity.md new file mode 100644 index 00000000..a604ebb8 --- /dev/null +++ b/docs/pbs/pull-requests/PR-O1.3-pbs-executable-lowering-fidelity.md @@ -0,0 +1,30 @@ +# PR-O1.3 - PBS Executable Lowering Fidelity + +## Briefing + +Elevar fidelidade do lowering executavel no frontend PBS para garantir classificacao correta de callsites e eliminacao de heuristicas que possam produzir `callee` ambiguo (``) no `IRBackend`. + +## Target + +- `prometeu-compiler/frontends/prometeu-frontend-pbs` (`PbsFrontendCompiler`). +- Coleta/travessia de callsites em blocos/expressoes compostas. +- Integracao com metadado reservado host/intrinsic. + +## Method + +- Revisar travessia de AST para callsites com foco em completude e null-safety. +- Substituir fallback ambiguo por rejeicao diagnostica deterministica quando identidade nao puder ser resolvida. +- Garantir ordenacao deterministica de instrucoes coletadas para o mesmo AST admitido. + +## Acceptance Criteria + +- Frontend nao emite callsite executavel com callee ambiguo. +- Chamadas host/intrinsic sao classificadas sem heuristica textual fragil. +- Coleta de callsites em `if/switch/handle/block expr` permanece deterministica. +- Casos sem resolucao de identidade falham com diagnostico estavel. + +## Tests + +- Novos testes em `PbsFrontendCompilerTest` para callsites complexos. +- Regressao para `handle/switch` com blocos terminais. +- Fixture negativa para callee nao-resolvido no lowering executavel. diff --git a/docs/pbs/pull-requests/PR-O1.4-lower-to-irvm-callsite-prechecks.md b/docs/pbs/pull-requests/PR-O1.4-lower-to-irvm-callsite-prechecks.md new file mode 100644 index 00000000..fdcc78c1 --- /dev/null +++ b/docs/pbs/pull-requests/PR-O1.4-lower-to-irvm-callsite-prechecks.md @@ -0,0 +1,30 @@ +# PR-O1.4 - LowerToIRVM Callsite Prechecks + +## Briefing + +Implementar prechecks obrigatorios de chamada em `LowerToIRVM` (consistencia de assinatura/slots e validade de destino) para cumprir integralmente o contrato de verificacao pre-emissao. + +## Target + +- `prometeu-compiler/prometeu-build-pipeline` (`LowerToIRVMService`, `IRVMValidator`). +- Taxonomia de erros de lowering/verificacao. +- Testes unitarios de lowering negativo. + +## Method + +- Introduzir validacao de aridade/shape de retorno em `CALL_FUNC` usando metadados das funcoes alvo. +- Rejeitar inconsistencias de chamada antes do emissor. +- Preservar determinismo de `func_id` e diagnostico para falhas de precheck. + +## Acceptance Criteria + +- `CALL_FUNC` invalido por contrato de slots falha no `LowerToIRVM` com codigo estavel. +- Falhas de callsite nao avancam para `EmitBytecode`. +- Verificador cobre func-id, stack e contrato de chamada no mesmo passe. +- Testes existentes de lowering continuam verdes. + +## Tests + +- Novos testes em `LowerToIRVMServiceTest` para mismatch de param/ret slots. +- Regressao para caminho valido com host/intrinsic. +- Teste de estabilidade de codigo de erro para mesma entrada invalida. diff --git a/docs/pbs/pull-requests/PR-O1.5-bytecode-debug-minimum-completeness.md b/docs/pbs/pull-requests/PR-O1.5-bytecode-debug-minimum-completeness.md new file mode 100644 index 00000000..c3364d88 --- /dev/null +++ b/docs/pbs/pull-requests/PR-O1.5-bytecode-debug-minimum-completeness.md @@ -0,0 +1,30 @@ +# PR-O1.5 - Bytecode Debug Minimum Completeness + +## Briefing + +Garantir conformidade integral com o minimo de debug v1: `function_names` para todas as funcoes e `pc_to_span` para todo inicio de instrucao emitida. + +## Target + +- `BytecodeEmitter` e `BytecodeFunctionLayoutBuilder`. +- Estrutura `BytecodeModule.DebugInfo`. +- Testes de emissao/debug. + +## Method + +- Registrar spans de todas as instrucoes emitidas (nao apenas host/intrinsic). +- Definir fallback deterministico para instrucoes sem span source-especifico. +- Validar que toda funcao emitida possui nome em `function_names`. + +## Acceptance Criteria + +- `pc_to_span` cobre 100% dos instruction starts do modulo emitido. +- `function_names` cobre 100% dos `func_idx`. +- Falha de integridade de debug e detectada antes da serializacao final. +- Output permanece deterministico entre execucoes. + +## Tests + +- Testes em `BytecodeFunctionLayoutBuilderTest` e `BytecodeEmitterTest` para cobertura completa de PCs. +- Fixture com multiplas funcoes e misto de opcodes. +- Teste negativo para span fora de faixa. diff --git a/docs/pbs/pull-requests/PR-O1.6-gate-su-safety-matrix-completion.md b/docs/pbs/pull-requests/PR-O1.6-gate-su-safety-matrix-completion.md new file mode 100644 index 00000000..8f573477 --- /dev/null +++ b/docs/pbs/pull-requests/PR-O1.6-gate-su-safety-matrix-completion.md @@ -0,0 +1,29 @@ +# PR-O1.6 - Gate S-U Safety Matrix Completion + +## Briefing + +Fechar cobertura minima de seguranca em testes unitarios por stage (`LowerToIRVM`, `OptimizeIRVM`, `EmitBytecode`) conforme especificacao de verificacao/safety. + +## Target + +- Suite de testes do modulo `prometeu-build-pipeline`. +- Evidencia Gate S-U para casos positivos e negativos deterministas. + +## Method + +- Consolidar matriz de casos obrigatorios por stage. +- Cobrir invariantes de determinismo, precheck estrutural e rejeicoes normativas. +- Garantir que cada familia de erro relevante tenha pelo menos um fixture dedicado. + +## Acceptance Criteria + +- Gate S-U cobre os checks minimos exigidos pela spec 19. +- Cada stage possui testes de sucesso e falha com codigos estaveis. +- Pipeline order e contratos de fronteira permanecem testados. +- Nao ha `deferred` em checks S-U obrigatorios para backend executavel. + +## Tests + +- Expansao de `LowerToIRVMServiceTest`, `IRVMValidatorTest`, `OptimizeIRVMPipelineStageTest`, `EmitBytecodePipelineStageTest`. +- Testes deterministas (mesmo input, mesmo output/erro). +- Tabela de cobertura Gate S-U documentada em assertions/fixures. diff --git a/docs/pbs/pull-requests/PR-O2.1-bytecode-link-precheck-stage.md b/docs/pbs/pull-requests/PR-O2.1-bytecode-link-precheck-stage.md new file mode 100644 index 00000000..1347f227 --- /dev/null +++ b/docs/pbs/pull-requests/PR-O2.1-bytecode-link-precheck-stage.md @@ -0,0 +1,30 @@ +# PR-O2.1 - Bytecode Link Precheck Stage (JVM-Inspired) + +## Briefing + +Adicionar etapa de precheck de linkagem do artefato emitido, separando responsabilidades de formatacao e vinculacao (inspirado no modelo JVM de fronteiras claras). + +## Target + +- Novo servico/stage de precheck apos emissao. +- Validacoes de referencias cruzadas em `BytecodeModule` (`functions`, `code`, `exports`, `syscalls`). +- Integracao no pipeline sem alterar autoridade do runtime. + +## Method + +- Implementar verificador leve de consistencia de indices/offsets no artefato pre-load. +- Validar referencias de export, limites de funcao e uso de `sysc_index`. +- Manter determinismo de erro e taxonomia `MARSHAL_VERIFY_PRECHECK_*`. + +## Acceptance Criteria + +- Artefatos malformados por linkagem interna falham antes de handoff externo. +- Rejeicoes sao estaveis e reproduziveis. +- Stage e opcional por feature flag, mas habilitado no perfil normativo. +- Nenhuma sobreposicao com validacoes que sao exclusivamente do runtime. + +## Tests + +- Testes unitarios do novo verificador com casos de offsets/indices invalidos. +- Testes de pipeline garantindo execucao da etapa na ordem correta. +- Regressao para artefatos validos atualmente emitidos. diff --git a/docs/pbs/pull-requests/PR-O2.2-bytecode-preload-verifier.md b/docs/pbs/pull-requests/PR-O2.2-bytecode-preload-verifier.md new file mode 100644 index 00000000..f7981c06 --- /dev/null +++ b/docs/pbs/pull-requests/PR-O2.2-bytecode-preload-verifier.md @@ -0,0 +1,30 @@ +# PR-O2.2 - Bytecode Preload Verifier (JVM-Inspired) + +## Briefing + +Introduzir verificador estrutural de pre-load no compilador para antecipar rejeicoes triviais e fortalecer qualidade de artefato antes de runtime. + +## Target + +- Novo componente de verificacao estrutural em `prometeu-build-pipeline`. +- Regras de controle de fluxo/stack no artefato (quando observaveis no pre-load). +- Integração com Gate S-U/S-I. + +## Method + +- Definir subconjunto de verificacoes que o compilador pode garantir sem substituir o verifier oficial do runtime. +- Reusar taxonomia de erros de precheck. +- Garantir que o verificador rode de modo deterministico e sem heuristicas dependentes de ambiente. + +## Acceptance Criteria + +- Verificador captura classes de erro estruturais detectaveis localmente. +- Rejeicoes compilador e runtime convergem para os casos de intersecao. +- Falhas nao mascaram erros anteriores de lowering/emissao. +- Overhead de execucao permanece controlado (baseline no-op em casos validos). + +## Tests + +- Fixtures com bytecode invalido estruturalmente (stack/control-flow simplificado). +- Regressao com artefatos validos cobrindo hostcall/intrinsic. +- Teste de estabilidade de codigos e mensagens base. diff --git a/docs/pbs/pull-requests/PR-O2.3-optimize-irvm-pass-manager-and-equivalence.md b/docs/pbs/pull-requests/PR-O2.3-optimize-irvm-pass-manager-and-equivalence.md new file mode 100644 index 00000000..c58e3301 --- /dev/null +++ b/docs/pbs/pull-requests/PR-O2.3-optimize-irvm-pass-manager-and-equivalence.md @@ -0,0 +1,30 @@ +# PR-O2.3 - OptimizeIRVM Pass Manager and Equivalence Harness + +## Briefing + +Evoluir `OptimizeIRVM` de no-op para estrutura de pass manager deterministica, mantendo preservacao semantica e compatibilidade de perfil. + +## Target + +- `OptimizeIRVMService`. +- Infraestrutura de registro/execucao de passes. +- Suite de equivalencia entre pipeline otimizado vs baseline. + +## Method + +- Criar contrato de pass (`name`, `enabled`, `apply`, validacao pos-pass). +- Manter no-op como pass default, mas com trilha para adicao incremental de passes reais. +- Adicionar harness de regressao comparando invariantes de saida e comportamento esperado. + +## Acceptance Criteria + +- Pipeline suporta multiplos passes com ordem deterministica. +- Cada pass roda sob validacao estrutural pre e pos. +- Saida otimizada preserva contratos de slots/calls/profile. +- Existe suite de equivalencia minima para impedir regressao semantica. + +## Tests + +- Testes de pass manager (ordem, habilitacao, falha curta). +- Testes de equivalencia entre `OptimizeIRVM` ativo vs no-op. +- Regressao de perfil invalido e determinismo de output. diff --git a/docs/pbs/pull-requests/PR-O2.4-gate-i-runtime-backed-compat-harness.md b/docs/pbs/pull-requests/PR-O2.4-gate-i-runtime-backed-compat-harness.md new file mode 100644 index 00000000..c5101352 --- /dev/null +++ b/docs/pbs/pull-requests/PR-O2.4-gate-i-runtime-backed-compat-harness.md @@ -0,0 +1,30 @@ +# PR-O2.4 - Gate I Runtime-Backed Compatibility Harness + +## Briefing + +Trocar verificador mock de integracao por harness aderente ao runtime line alvo, mantendo os cenarios normativos de Gate I e evidencias repetiveis. + +## Target + +- Testes de integracao backend (`BackendGateIIntegrationTest` e correlatos). +- Adaptador para checagem realista de compatibilidade de pre-load. +- Vinculacao explicita com runtime line suportado. + +## Method + +- Encapsular checagem de compatibilidade em adaptador substituivel (mock/local/runtime-backed). +- Preservar cenarios minimos normativos (hostcall valido, OOB, unused SYSC, raw syscall, ABI mismatch, capability, intrinsic). +- Registrar runtime line e perfil usados nos testes para rastreabilidade. + +## Acceptance Criteria + +- Gate I deixa de depender exclusivamente de checador interno ad-hoc. +- Suite segue estavel e reproduzivel no ambiente de CI. +- Cenarios normativos da spec 19 permanecem cobertos. +- Evidencia inclui runtime line explicita no relatorio/test metadata. + +## Tests + +- Rework de testes de integracao para usar adaptador de compatibilidade. +- Regressao completa dos 8 cenarios de Gate I. +- Teste de fallback para modo local quando runtime externo nao estiver disponivel. diff --git a/docs/pbs/pull-requests/PR-O3.1-irvm-control-flow-lowering-label-resolution.md b/docs/pbs/pull-requests/PR-O3.1-irvm-control-flow-lowering-label-resolution.md new file mode 100644 index 00000000..6f256378 --- /dev/null +++ b/docs/pbs/pull-requests/PR-O3.1-irvm-control-flow-lowering-label-resolution.md @@ -0,0 +1,30 @@ +# PR-O3.1 - IRVM Control-Flow Lowering and Label Resolution + +## Briefing + +Expandir lowering para cobrir controle de fluxo com labels simbolicos internos e resolucao deterministica para offsets finais, alinhando o backend ao perfil quasi-ISA. + +## Target + +- `LowerToIRVMService` e modelo de instrucao IRVM. +- Resolucao de labels para `JMP/JMP_IF_*`. +- Validacoes de alvo de salto em fronteira de instrucao. + +## Method + +- Introduzir representacao intermediaria de labels no lowering. +- Resolver labels para `u32` relativo ao inicio da funcao antes da emissao. +- Integrar com `IRVMValidator` para garantir alvos validos e paths terminados. + +## Acceptance Criteria + +- Fluxos com desvio condicional/incondicional sao emitidos corretamente. +- Todos os saltos resolvidos apontam para fronteiras validas. +- Caminhos alcancaveis sem terminador sao rejeitados deterministicamente. +- Mesmo input gera mesmos offsets finais. + +## Tests + +- Testes novos de lowering/validator com CFG linear e com joins. +- Casos negativos para alvo invalido e mismatch de altura de pilha em join. +- Regressao para funcoes sem saltos. diff --git a/docs/pbs/pull-requests/PR-O3.2-bytecode-constpool-symbol-interning-determinism.md b/docs/pbs/pull-requests/PR-O3.2-bytecode-constpool-symbol-interning-determinism.md new file mode 100644 index 00000000..92c15fab --- /dev/null +++ b/docs/pbs/pull-requests/PR-O3.2-bytecode-constpool-symbol-interning-determinism.md @@ -0,0 +1,30 @@ +# PR-O3.2 - Bytecode ConstPool and Symbol Interning Determinism + +## Briefing + +Estabelecer estrategia deterministica de internacao para constantes/simbolos no emissor, reduzindo redundancia e preparando evolucao do formato sem quebrar reproducibilidade. + +## Target + +- `BytecodeEmitter` e mapeamento de `const_pool`/simbolos. +- Contratos internos de deduplicacao e ordem de materializacao. +- Testes de reproducibilidade de modulo. + +## Method + +- Definir politica canonical para internacao (tipo + valor + ordem deterministica). +- Materializar indices finais em etapa unica de fechamento do artefato. +- Garantir bytecode identico para entradas semanticamente identicas. + +## Acceptance Criteria + +- `const_pool` nao depende de ordem incidental de estruturas nao deterministicas. +- Emissoes repetidas do mesmo input produzem bytes identicos. +- Duplicacao desnecessaria de constantes e reduzida sem alterar semantica. +- Falhas de internacao invalidas retornam erro deterministico. + +## Tests + +- Testes de snapshot binario para entradas repetidas. +- Casos com constantes repetidas em multiplas funcoes. +- Testes negativos para entradas de constante fora de contrato. diff --git a/docs/pbs/pull-requests/PR-O3.3-irvm-profile-evolution-and-feature-gates.md b/docs/pbs/pull-requests/PR-O3.3-irvm-profile-evolution-and-feature-gates.md new file mode 100644 index 00000000..2cbeaf19 --- /dev/null +++ b/docs/pbs/pull-requests/PR-O3.3-irvm-profile-evolution-and-feature-gates.md @@ -0,0 +1,30 @@ +# PR-O3.3 - IRVM Profile Evolution and Feature Gates + +## Briefing + +Definir trilha de evolucao controlada do `IRVM` quasi-ISA com feature gates por perfil, protegendo compatibilidade entre pipeline de compilacao e runtime line. + +## Target + +- Modelo `IRVMModule.vmProfile` e validacoes de perfil. +- Poltica de habilitacao de opcodes/extensoes internas por perfil. +- Documentacao de compatibilidade/rollout. + +## Method + +- Formalizar matriz de features por `vm_profile` (ex.: `core-v1`, futuros perfis). +- Bloquear introducao de opcode fora do perfil selecionado. +- Expor gates de evolucao para rollout incremental e rollback seguro. + +## Acceptance Criteria + +- Backend rejeita artefato com opcode nao permitido no perfil ativo. +- Mapeamento perfil->feature e deterministico e testado. +- Evolucao de perfil nao quebra caminho `core-v1` existente. +- Decisao de compatibilidade fica rastreavel em specs/decisions. + +## Tests + +- Testes de validacao por perfil com opcodes permitidos/proibidos. +- Regressao do pipeline completo em `core-v1`. +- Fixtures cobrindo ativacao/desativacao de feature gate.