diff --git a/docs/pbs/pull-requests/INDEX.md b/docs/pbs/pull-requests/INDEX.md index a975b06f..593ca947 100644 --- a/docs/pbs/pull-requests/INDEX.md +++ b/docs/pbs/pull-requests/INDEX.md @@ -40,3 +40,18 @@ Cada documento e auto contido e inclui: `Briefing`, `Target`, `Method`, `Accepta 31. `PR-029-pbs-builtin-slot-inference-and-layout-semantics.md` 32. `PR-030-pbs-host-admission-capability-gating.md` 33. `PR-031-pbs-dependency-scoped-fail-fast-admission.md` + +## Backend VM Pipeline PR Sequence (Agenda 18) + +Esta sequencia organiza implementacao atomica para `IRBackend -> IRVM -> OptimizeIRVM -> EmitBytecode`, com trilha de montagem do output para o input (bytecode ate IRBackend). + +34. `PR-032-backend-bytecode-module-serializer-baseline.md` +35. `PR-033-backend-bytecode-function-layout-and-debug-minimum.md` +36. `PR-034-backend-emitter-hostcall-sysc-contract.md` +37. `PR-035-backend-emit-stage-pipeline-wiring.md` +38. `PR-036-backend-irvm-core-model-and-validator.md` +39. `PR-037-backend-optimize-irvm-noop-stage-and-guards.md` +40. `PR-038-irbackend-v2-executable-contract-model.md` +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` diff --git a/docs/pbs/pull-requests/PR-032-backend-bytecode-module-serializer-baseline.md b/docs/pbs/pull-requests/PR-032-backend-bytecode-module-serializer-baseline.md new file mode 100644 index 00000000..ebc79018 --- /dev/null +++ b/docs/pbs/pull-requests/PR-032-backend-bytecode-module-serializer-baseline.md @@ -0,0 +1,37 @@ +# PR-032 - Backend BytecodeModule Serializer Baseline + +## Briefing + +Implementar a base de marshaling binario de `BytecodeModule` no compilador, alinhada ao contrato v1 de `const_pool`, `functions`, `code`, `exports`, `syscalls` e secao `SYSC` obrigatoria. + +## Target + +- Criar modelo interno de emissao de `BytecodeModule` no backend Java. +- Implementar serializacao little-endian com tabela de secoes deterministica. +- Garantir `SYSC` sempre presente no artefato pre-load, inclusive vazia. + +## Method + +- Introduzir pacote backend de bytecode com modelos equivalentes aos campos normativos da spec 15. +- Implementar serializer com layout de header e secoes deterministico. +- Introduzir erros deterministas de formato (`MARSHAL_FORMAT_*`) para falhas detectaveis antes da escrita final. +- Referenciar comportamento-alvo dos contratos existentes em `../runtime/crates/console/prometeu-bytecode/src/model.rs`. + +## Acceptance Criteria + +1. O backend serializa `BytecodeModule` sempre em little-endian. +2. A secao `SYSC` e sempre emitida. +3. Mesma entrada produz bytes identicos. +4. Erros de formato em dados invalidos sao deterministicos e estaveis. + +## Tests + +1. Teste unitario de serializacao minima (sem syscalls) com `SYSC` vazio presente. +2. Teste unitario de determinismo de bytes para mesma entrada. +3. Teste unitario de rejeicao `MARSHAL_FORMAT_*` para dados malformados detectaveis no emitter. + +## Affected Documents + +- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md` +- `docs/general/specs/19. Verification and Safety Checks Specification.md` + diff --git a/docs/pbs/pull-requests/PR-033-backend-bytecode-function-layout-and-debug-minimum.md b/docs/pbs/pull-requests/PR-033-backend-bytecode-function-layout-and-debug-minimum.md new file mode 100644 index 00000000..b5f85454 --- /dev/null +++ b/docs/pbs/pull-requests/PR-033-backend-bytecode-function-layout-and-debug-minimum.md @@ -0,0 +1,37 @@ +# PR-033 - Backend Function Layout and Debug Minimum + +## Briefing + +Implementar o builder de layout final de funcoes (`code_offset`, `code_len`) e o contrato minimo de debug (`function_names`, `pc_to_span`) antes de integrar com stages do pipeline. + +## Target + +- Construir flatten deterministico de codigo por funcao. +- Preencher `functions[]` com offsets/len coerentes. +- Preencher `debug_info` minimo v1. + +## Method + +- Adicionar um layout builder que recebe codigo por funcao e produz `code` unico. +- Garantir `code_offset` monotonicos e unicos. +- Garantir `code_len` exato por funcao. +- Gerar `debug_info.function_names` e `debug_info.pc_to_span` no momento de materializacao final. +- Seguir invariantes de consumo do runtime (`ProgramImage` e verifier). + +## Acceptance Criteria + +1. `code_offset + code_len` de cada funcao fica dentro de `code.len`. +2. Ordem de flatten e offsets sao deterministicos. +3. `function_names` contem todos os `func_idx` emitidos. +4. `pc_to_span` cobre cada inicio de instrucao emitida. + +## Tests + +1. Teste unitario de layout com multiplas funcoes. +2. Teste unitario de limites invalidos rejeitados deterministicamente. +3. Teste unitario de cobertura de debug minimo. + +## Affected Documents + +- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md` + diff --git a/docs/pbs/pull-requests/PR-034-backend-emitter-hostcall-sysc-contract.md b/docs/pbs/pull-requests/PR-034-backend-emitter-hostcall-sysc-contract.md new file mode 100644 index 00000000..04f425ab --- /dev/null +++ b/docs/pbs/pull-requests/PR-034-backend-emitter-hostcall-sysc-contract.md @@ -0,0 +1,39 @@ +# PR-034 - Backend Emitter HOSTCALL and SYSC Contract + +## Briefing + +Fechar o contrato de emissao host-backed e intrinsic no emitter: deduplicacao canonica de `SYSC`, ordenacao por primeira ocorrencia, `HOSTCALL` em pre-load e rejeicao de `SYSCALL` bruto. + +## Target + +- Implementar materializacao de `syscalls` no artefato. +- Implementar map `host binding -> sysc_index`. +- Preservar caminho de `INTRINSIC` distinto de host. + +## Method + +- Deduplicar `SYSC` por `(module,name,version)` e manter ordem da primeira ocorrencia. +- Emitir chamadas host-backed como `HOSTCALL `. +- Rejeitar candidatas que contenham `SYSCALL` em imagem pre-load (`MARSHAL_LINKAGE_*`). +- Validar mismatch detectavel de ABI (`arg_slots`, `ret_slots`) com metadado de compilacao. + +## Acceptance Criteria + +1. `SYSC` deduplicado e ordenado por primeira ocorrencia. +2. Nao existe `SYSCALL` bruto no artefato pre-load emitido. +3. Caminho intrinsic nao polui `SYSC`. +4. Falhas de linkage sao deterministicas. + +## Tests + +1. Teste positivo com chamadas host repetidas gerando um unico `SYSC`. +2. Teste negativo de `SYSCALL` bruto no pre-load. +3. Teste negativo de mismatch ABI em host binding. +4. Teste positivo de intrinsic sem entradas em `SYSC`. + +## Affected Documents + +- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md` +- `docs/general/specs/19. Verification and Safety Checks Specification.md` +- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md` + diff --git a/docs/pbs/pull-requests/PR-035-backend-emit-stage-pipeline-wiring.md b/docs/pbs/pull-requests/PR-035-backend-emit-stage-pipeline-wiring.md new file mode 100644 index 00000000..dd5d06fe --- /dev/null +++ b/docs/pbs/pull-requests/PR-035-backend-emit-stage-pipeline-wiring.md @@ -0,0 +1,37 @@ +# PR-035 - EmitBytecode Stage Pipeline Wiring + +## Briefing + +Integrar o emitter ao pipeline real: `EmitBytecodePipelineStage` deixa de ser stub e passa a receber `IRVM` otimizado, executar checks de marshaling e produzir bytes finais no contexto do build. + +## Target + +- Atualizar `BuilderPipelineContext` com superficies de saida de backend (`irvm`, `optimizedIrvm`, `bytecodeModule`, `bytecodeBytes`). +- Implementar `EmitBytecodePipelineStage`. +- Registrar falhas de emissao em `BuildingIssueSink`. + +## Method + +- Introduzir service de emissao usado pela stage. +- Fazer a stage validar precondicoes (`optimizedIrvm` presente, sem opcodes internos restantes). +- Persistir resultado no contexto para fases posteriores/consumo externo. +- Propagar codigos deterministas `MARSHAL_*` em diagnosticos de build. + +## Acceptance Criteria + +1. Stage falha deterministicamente quando precondicoes nao sao satisfeitas. +2. Stage produz `bytecodeBytes` para entradas validas. +3. Stage nao depende de packer. +4. Integracao da stage nao altera ordem canonica do pipeline. + +## Tests + +1. Teste unitario da stage com input valido. +2. Teste unitario da stage sem `optimizedIrvm`. +3. Teste unitario da stage com opcode interno nao eliminado. + +## Affected Documents + +- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md` +- `docs/general/specs/21. IRVM Optimization Pipeline Specification.md` + diff --git a/docs/pbs/pull-requests/PR-036-backend-irvm-core-model-and-validator.md b/docs/pbs/pull-requests/PR-036-backend-irvm-core-model-and-validator.md new file mode 100644 index 00000000..baf398b5 --- /dev/null +++ b/docs/pbs/pull-requests/PR-036-backend-irvm-core-model-and-validator.md @@ -0,0 +1,42 @@ +# PR-036 - Backend IRVM Core Model and Validator + +## Briefing + +Criar o modelo `IRVM` quase-ISA e validador estrutural compile-time, base para `LowerToIRVM`, `OptimizeIRVM` e `EmitBytecode`. + +## Target + +- Introduzir tipos de `IRVM` (modulo, funcao, instrucao, operandos, labels). +- Suportar opcodes Core ISA e opcodes internos (`IRVM_EXT`) com metadados obrigatorios. +- Implementar validacao estrutural minima de controle/pilha/calls. + +## Method + +- Criar API de instrucao com `pops`, `pushes`, `is_branch`, `is_terminator`. +- Implementar verificador de fronteira compiler-side: + - alvo de salto valido, + - join de stack consistente, + - underflow/overflow, + - retorno coerente com `return_slots`, + - validade de `func_id`. +- Definir contrato de serializacao bloqueando `IRVM_EXT` na fronteira de emissao. + +## Acceptance Criteria + +1. `IRVM` suporta representacao de Core ISA e extensoes internas eliminaveis. +2. Validador detecta inconsistencias estruturais requeridas pela spec 20. +3. Falhas sao deterministicas e categorizadas como `MARSHAL_VERIFY_PRECHECK_*` quando aplicavel. +4. Resultado do validador pode ser consumido por stages de optimize/emissao. + +## Tests + +1. Teste unitario para salto invalido e salto para meio de instrucao. +2. Teste unitario para mismatch de stack em join. +3. Teste unitario para retorno com shape invalido. +4. Teste unitario para `IRVM_EXT` residual bloqueando emissao. + +## Affected Documents + +- `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md` +- `docs/general/specs/19. Verification and Safety Checks Specification.md` + diff --git a/docs/pbs/pull-requests/PR-037-backend-optimize-irvm-noop-stage-and-guards.md b/docs/pbs/pull-requests/PR-037-backend-optimize-irvm-noop-stage-and-guards.md new file mode 100644 index 00000000..eef78f35 --- /dev/null +++ b/docs/pbs/pull-requests/PR-037-backend-optimize-irvm-noop-stage-and-guards.md @@ -0,0 +1,37 @@ +# PR-037 - OptimizeIRVM No-op Stage and Guards + +## Briefing + +Implementar `OptimizeIRVMPipelineStage` com baseline no-op deterministico, preservando contratos semanticos e adicionando guardas obrigatorias antes da emissao. + +## Target + +- Implementar stage real de otimizacao no pipeline. +- Garantir preservacao de semantica, slots e determinismo para a baseline. +- Preparar superficie para passes futuros sem quebrar contrato. + +## Method + +- Criar service `OptimizeIRVMService` com pass manager inicial contendo pass no-op. +- Executar validacao pre e pos-pass para garantir equivalencia estrutural minima. +- Garantir que a saida segue compativel com `vm_profile` alvo. +- Publicar `optimizedIrvm` no `BuilderPipelineContext`. + +## Acceptance Criteria + +1. Pipeline executa `LowerToIRVM -> OptimizeIRVM -> EmitBytecode`. +2. Com mesma entrada, saida otimizada e deterministica. +3. Stage falha deterministicamente para violacoes de contrato. +4. Stage pode operar como no-op sem ser pulada. + +## Tests + +1. Teste unitario de pass no-op preservando estrutura e metadados. +2. Teste unitario de rejeicao quando pass introduz forma fora do profile. +3. Teste unitario de integracao da ordem de stages no `BuilderPipelineService`. + +## Affected Documents + +- `docs/general/specs/21. IRVM Optimization Pipeline Specification.md` +- `docs/pbs/decisions/IRVM Optimization Stage Placement Decision.md` + diff --git a/docs/pbs/pull-requests/PR-038-irbackend-v2-executable-contract-model.md b/docs/pbs/pull-requests/PR-038-irbackend-v2-executable-contract-model.md new file mode 100644 index 00000000..ee09c402 --- /dev/null +++ b/docs/pbs/pull-requests/PR-038-irbackend-v2-executable-contract-model.md @@ -0,0 +1,39 @@ +# PR-038 - IRBackend v2 Executable Contract Model + +## Briefing + +Evoluir `IRBackend` para contrato executavel v2, adicionando corpo lowerable, classificacao de callsites e metadado canonico para host/intrinsic sem heuristica textual no backend. + +## Target + +- Expandir modelos em `prometeu-frontend-api` para incluir: + - callable identity estavel, + - corpo lowerable, + - callsites com categoria explicita (`CALL_FUNC`, `CALL_HOST`, `CALL_INTRINSIC`), + - metadado canonico host/intrinsic por callsite. +- Preservar compatibilidade de agregacao e ordenacao deterministica. + +## Method + +- Introduzir novas records/classes v2 e adaptar agregador de `IRBackend`. +- Manter fronteira clara entre metadado reservado global e metadado operacional por callsite. +- Introduzir chave deterministica de ordenacao de funcao: `(module_key, callable_name, source_start)`. + +## Acceptance Criteria + +1. `IRBackend` v2 carrega informacao suficiente para `LowerToIRVM` sem heuristica textual. +2. Cada callsite executavel pertence a exatamente uma categoria. +3. Identidade canonica host/intrinsic fica preservada por callsite. +4. Agregacao multi-arquivo continua deterministica. + +## Tests + +1. Testes unitarios de modelo para classificacao de callsites. +2. Testes unitarios de agregacao deterministica de funcoes. +3. Testes unitarios de preservacao de metadados host/intrinsic. + +## Affected Documents + +- `docs/pbs/specs/13. Lowering IRBackend Specification.md` +- `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md` + diff --git a/docs/pbs/pull-requests/PR-039-pbs-frontend-irbackend-v2-lowering.md b/docs/pbs/pull-requests/PR-039-pbs-frontend-irbackend-v2-lowering.md new file mode 100644 index 00000000..60a7a8c1 --- /dev/null +++ b/docs/pbs/pull-requests/PR-039-pbs-frontend-irbackend-v2-lowering.md @@ -0,0 +1,37 @@ +# PR-039 - PBS Frontend Lowering to IRBackend v2 + +## Briefing + +Atualizar o frontend PBS para emitir `IRBackend` v2 executavel, incluindo corpo lowerable e classificacao de chamadas conforme contrato normativo da agenda 18.1. + +## Target + +- Atualizar `PbsFrontendCompiler` e servicos correlatos para emitir IR v2. +- Materializar callsites classificados no lowering frontend. +- Preservar ancoras de fonte por instrucao/callsite para diagnostico backend. + +## Method + +- Extrair do AST/semantica as operacoes necessarias ao corpo lowerable. +- Mapear chamadas para `CALL_FUNC`/`CALL_HOST`/`CALL_INTRINSIC`. +- Anexar metadado canonico de host/intrinsic por callsite com validacao de coerencia. +- Preservar fail-fast dependency-scoped ja existente na agregacao. + +## Acceptance Criteria + +1. Frontend PBS produz `IRBackend` v2 para modulos executaveis. +2. Chamadas host/intrinsic saem classificadas e com metadado canonico. +3. Diagnosticos permanecem deterministicos e com atribuicao de fonte. +4. SDK interface continua sem emissao de corpo executavel quando aplicavel. + +## Tests + +1. Testes de frontend para classificacao correta de callsites. +2. Testes negativos para metadado reservado invalido. +3. Testes de regressao para fail-fast em modulos dependentes. + +## Affected Documents + +- `docs/pbs/specs/13. Lowering IRBackend Specification.md` +- `docs/general/specs/13. Conformance Test Specification.md` + diff --git a/docs/pbs/pull-requests/PR-040-backend-lower-to-irvm-stage-implementation.md b/docs/pbs/pull-requests/PR-040-backend-lower-to-irvm-stage-implementation.md new file mode 100644 index 00000000..93c9d87c --- /dev/null +++ b/docs/pbs/pull-requests/PR-040-backend-lower-to-irvm-stage-implementation.md @@ -0,0 +1,41 @@ +# PR-040 - LowerToIRVM Stage Implementation + +## Briefing + +Implementar `LowerToIRVMPipelineStage` real, convertendo `IRBackend` v2 em `IRVM` com IDs deterministicos, lowering de controle de fluxo e lowering de chamadas compativel com runtime/ISA. + +## Target + +- Implementar service de lowering `IRBackend -> IRVM`. +- Implementar atribuicao deterministica de `func_id` com entrypoint em `0`. +- Resolver labels para offsets `u32` relativos ao inicio da funcao. + +## Method + +- Ordenar funcoes por regra normativa `(module_key, callable_name, source_start)` com entrypoint fixo. +- Lowering de chamadas: + - `CALL_FUNC -> CALL `, + - `CALL_HOST -> HOSTCALL `, + - `CALL_INTRINSIC -> INTRINSIC `. +- Aplicar pre-verificacao estrutural obrigatoria antes de publicar `irvm` no contexto. +- Registrar falhas com familias de erro deterministas. + +## Acceptance Criteria + +1. Stage produz `IRVM` valido para entradas admitidas. +2. Mapeamento de funcao e callsite e deterministico. +3. Labels nao resolvidas e saltos invalidos sao rejeitados deterministicamente. +4. Stage preenche `ctx.irvm` para consumo da etapa `OptimizeIRVM`. + +## Tests + +1. Teste unitario de ordenacao deterministica de funcoes. +2. Teste unitario de lowering de callsites por categoria. +3. Teste unitario de rejeicao para fluxo nao terminado. +4. Teste unitario de offsets de salto relativos ao inicio da funcao. + +## Affected Documents + +- `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md` +- `docs/general/specs/19. Verification and Safety Checks Specification.md` + diff --git a/docs/pbs/pull-requests/PR-041-backend-gate-i-runtime-compat-integration-fixtures.md b/docs/pbs/pull-requests/PR-041-backend-gate-i-runtime-compat-integration-fixtures.md new file mode 100644 index 00000000..2b7452e6 --- /dev/null +++ b/docs/pbs/pull-requests/PR-041-backend-gate-i-runtime-compat-integration-fixtures.md @@ -0,0 +1,45 @@ +# PR-041 - Backend Gate I Runtime Compatibility Fixtures + +## Briefing + +Fechar a evidencia de integracao executavel com fixtures Gate I cobrindo os cenarios normativos da agenda 18.3, sem depender de packer. + +## Target + +- Criar suite de integracao para `LowerToIRVM -> OptimizeIRVM -> EmitBytecode`. +- Cobrir cenarios positivos e negativos de loader/verifier esperados. +- Publicar status S-I (`pass` ou `deferred`) com evidencia reproduzivel. + +## Method + +- Construir fixtures que validam o artefato emitido e suas falhas esperadas. +- Alinhar cenarios com erros observados no runtime em: + - `../runtime/crates/console/prometeu-vm/src/virtual_machine/loader.rs`, + - `../runtime/crates/console/prometeu-vm/src/verifier.rs`, + - `../runtime/crates/console/prometeu-vm/src/vm_init_error.rs`. +- Padronizar assertions nas familias `MARSHAL_FORMAT_*`, `MARSHAL_LINKAGE_*`, `MARSHAL_VERIFY_PRECHECK_*`. + +## Acceptance Criteria + +1. Fixture cobre os 8 cenarios minimos definidos em 18.3. +2. Resultados sao deterministicos entre execucoes. +3. Pelo menos um caminho positivo produz artefato inicializavel no runtime alvo. +4. Suite independe de packer. + +## Tests + +1. `SYSC` presente e vazio. +2. `HOSTCALL` valido com patch esperado. +3. `HOSTCALL` fora de faixa. +4. `SYSC` declarado e nao usado. +5. `SYSCALL` bruto em pre-load. +6. Mismatch ABI de host. +7. Capability insuficiente. +8. Caminho `INTRINSIC` valido. + +## Affected Documents + +- `docs/general/specs/19. Verification and Safety Checks Specification.md` +- `docs/general/specs/13. Conformance Test Specification.md` +- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md` +