diff --git a/docs/pbs/agendas/18.0. Backend VM Pipeline - Orchestration Agenda.md b/docs/pbs/agendas/18.0. Backend VM Pipeline - Orchestration Agenda.md index 1178c7ec..297f9ba2 100644 --- a/docs/pbs/agendas/18.0. Backend VM Pipeline - Orchestration Agenda.md +++ b/docs/pbs/agendas/18.0. Backend VM Pipeline - Orchestration Agenda.md @@ -1,6 +1,6 @@ # 18.0. Backend VM Pipeline - Orchestration Agenda -Status: Active (Draft) +Status: Ready for Closure (v1 Draft Text) ## Purpose @@ -12,7 +12,7 @@ Definir a ordem de fechamento arquitetural para o backend executável: ## Context -- O pipeline já prevê `LowerToVMPipelineStage` e `EmitBytecodePipelineStage`, mas ambos estão vazios. +- O pipeline já prevê `LowerToIRVMPipelineStage` e `EmitBytecodePipelineStage`, mas ambos estão vazios. - O runtime já impõe contratos concretos de loader/verifier/VM que precisam ser respeitados pelo backend. - Nesta rodada, `packer` está explicitamente fora de escopo. @@ -28,12 +28,72 @@ Definir a ordem de fechamento arquitetural para o backend executável: ## Core Questions -1. Quais decisões precisam ser fechadas antes de qualquer implementação de `LowerToVM`? +1. Quais decisões precisam ser fechadas antes de qualquer implementação de `LowerToIRVM`? 2. Quais invariantes são obrigatórias na fronteira `IRBackend` para evitar ambiguidade no backend? 3. Quais invariantes são obrigatórias na fronteira `IRVM` para emissão determinística? 4. Quais verificações devem ocorrer no compilador antes de delegar ao loader/verifier do runtime? 5. Como organizar testes de integração sem introduzir dependência de packer? +## Resolution (v1) + +Nao ha open questions bloqueantes remanescentes para fechamento da Agenda 18. + +As agendas `18.1`, `18.2` e `18.3` definem os contratos de entrada, lowering e marshaling. + +Esta agenda fecha a orquestracao end-to-end com pipeline canônico incluindo etapa de otimizacao de `IRVM`. + +## Normative Text (Draft for Closure) + +### 1) Pipeline canônico do backend executável + +O pipeline normativo v1 do backend executavel MUST seguir esta ordem: + +1. `FrontendPhase` produz `IRBackend`; +2. `LowerToIRVM` produz `IRVM`; +3. `OptimizeIRVM` transforma `IRVM -> IRVM` otimizado; +4. `EmitBytecode` transforma `IRVM` otimizado em `BytecodeModule` pre-load; +5. runtime loader aplica patching/resolucao (`HOSTCALL -> SYSCALL`) e verifier valida imagem final. + +### 2) Posicionamento de otimização + +1. A etapa `OptimizeIRVM` MUST ocorrer entre `LowerToIRVM` e `EmitBytecode`. +2. Otimizacao semantica/estrutural MUST ocorrer no backend (compile-time), nao no runtime. +3. Runtime permanece focado em load, validacao e execucao deterministica. + +### 3) Contratos de entrada e saida por etapa + +1. `LowerToIRVM` recebe `IRBackend` conforme Agenda `18.1` e MUST produzir `IRVM` conforme Agenda `18.2`. +2. `OptimizeIRVM` recebe `IRVM` valido para o `vm_profile` alvo e MUST produzir `IRVM` equivalente semanticamente. +3. `EmitBytecode` recebe `IRVM` (pos-otimizacao) sem opcodes internos nao-eliminados e MUST emitir artefato conforme Agenda `18.3`. + +### 4) Invariantes de seguranca da etapa OptimizeIRVM + +`OptimizeIRVM` MUST: + +1. preservar semantica observavel do programa; +2. preservar contratos de aridade/slots/retorno; +3. preservar determinismo para mesmo grafo de entrada; +4. nao introduzir opcodes fora do `vm_profile` executavel; +5. nao mover chamadas host/intrinsic para fronteira semantica incorreta. + +### 5) Criterio de aprovacao de pipeline + +Um backend so pode declarar fluxo "integration-ready" quando: + +1. `IRBackend -> IRVM -> IRVM otimizado -> BytecodeModule` estiver implementado; +2. fixtures Gate I cobrirem cenarios positivos e negativos definidos em `18.3`; +3. bytecode emitido inicializar e executar no runtime alvo sem packer. + +### 6) Deferrals explicitos + +Sem deferrals de perguntas abertas desta agenda. + +Permanecem fora de escopo: + +1. formato final de packer/cartucho; +2. politicas avancadas de otimizacao nao necessarias para conformidade v1; +3. redesign de loader/verifier/runtime. + ## Expected Spec Material 1. Nova spec de contrato `IRBackend -> IRVM` (backend-facing). @@ -50,7 +110,8 @@ Definir a ordem de fechamento arquitetural para o backend executável: ## Inputs -- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToVMPipelineStage.java` +- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToIRVMPipelineStage.java` +- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/OptimizeIRVMPipelineStage.java` - `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/EmitBytecodePipelineStage.java` - `docs/pbs/specs/13. Lowering IRBackend Specification.md` - `docs/general/specs/15. Bytecode and PBX Mapping Specification.md` @@ -58,4 +119,3 @@ Definir a ordem de fechamento arquitetural para o backend executável: - `../runtime/docs/runtime/virtual-machine/ISA_CORE.md` - `../runtime/crates/console/prometeu-vm/src/virtual_machine/loader.rs` - `../runtime/crates/console/prometeu-vm/src/verifier.rs` - diff --git a/docs/pbs/agendas/18.1. Backend Workshop 1 - IRBackend Input Contract.md b/docs/pbs/agendas/18.1. Backend Workshop 1 - IRBackend Input Contract.md index 6bc69bf1..80682fe1 100644 --- a/docs/pbs/agendas/18.1. Backend Workshop 1 - IRBackend Input Contract.md +++ b/docs/pbs/agendas/18.1. Backend Workshop 1 - IRBackend Input Contract.md @@ -1,6 +1,6 @@ # 18.1. Backend Workshop 1 - IRBackend Input Contract -Status: Active (Draft) +Status: Ready for Closure (v1 Draft Text) ## Purpose @@ -42,6 +42,96 @@ Fechar o `IRBackend` como contrato de entrada do backend executável, de forma s 5. Quais invariantes de estabilidade de ordenação são obrigatórias para conformance? 6. Quais campos mínimos de span/source mapping são mandatórios para erros backend-atribuíveis? +## Resolution (v1) + +Nao ha open questions bloqueantes para fechar o contrato de entrada `IRBackend` v1. + +As perguntas desta agenda ficam consideradas resolvidas para v1 pelos termos normativos abaixo. + +## Normative Text (Draft for Closure) + +### 1) Escopo e fronteira + +1. `IRBackend` e o contrato de entrada normativo do backend executavel. +2. O frontend MUST emitir `IRBackend` completo para toda unidade admitida no Gate U. +3. O backend MUST tratar `IRBackend` como fonte de verdade para `IRBackend -> IRVM`. +4. Esta agenda NAO define o formato de `IRVM` nem o encoding final de bytecode. + +### 2) Obrigacoes minimas por callable + +Para cada callable executavel emitido no `IRBackend`, o frontend MUST preservar: + +1. identidade estavel do callable no build atual; +2. assinatura observavel: + - aridade de entrada; + - shape de retorno observavel; +3. categoria de callable (ex.: funcao comum vs superficie reservada nao executavel); +4. ancora de atribuicao de fonte (`fileId`, `start`, `end`); +5. corpo backend-lowerable com semantica suficiente para emissao de chamadas e fluxo. + +`IRFunction` apenas com nome/contagem de parametros/span NAO satisfaz este contrato executavel. + +### 3) Classificacao obrigatoria de callsites + +Todo callsite executavel no `IRBackend` MUST estar classificado em exatamente uma categoria: + +1. `CALL_FUNC` (chamada de callable de programa); +2. `CALL_HOST` (fronteira host-backed); +3. `CALL_INTRINSIC` (operacao VM-owned). + +Implementacoes MUST NOT inferir a categoria por heuristica textual na fase `LowerToIRVM`. + +### 4) Contrato para host-backed + +Todo `CALL_HOST` MUST carregar identidade canonica: + +1. `abiModule`, +2. `abiMethod`, +3. `abiVersion`. + +Todo `CALL_HOST` MUST carregar declaracao de ABI: + +1. `arg_slots`, +2. `ret_slots`. + +O conjunto de bindings host-backed no `IRBackend` MUST ser deduplicado por `(module, name, version)` e ordenado por primeira ocorrencia deterministica. + +### 5) Contrato para VM-owned intrinsics e builtins + +Todo `CALL_INTRINSIC` MUST carregar identidade canonica VM-owned: + +1. `canonicalName`, +2. `canonicalVersion`. + +Builtin projections, builtin constants e intrinsic callsites VM-owned MUST NOT ser modelados como host binding. + +### 6) Metadados reservados obrigatorios + +`IRReservedMetadata` MUST preservar, no minimo: + +1. host bindings canonicos admitidos; +2. builtin type surfaces relevantes para lowering; +3. builtin const surfaces relevantes para lowering; +4. `requiredCapabilities` deterministico para assistencia de pipeline/packer. + +`requiredCapabilities` MUST ser deterministico para o mesmo grafo de entrada admitido. + +### 7) Diagnosticos e rejeicao deterministica + +Quando um modulo/callable nao satisfaz o contrato de entrada executavel: + +1. a rejeicao MUST ser deterministica; +2. o diagnostico MUST manter atribuicao de fonte acionavel; +3. o frontend/backend MUST NOT degradar silenciosamente para comportamento executavel diferente. + +### 8) Deferrals explicitos + +Ficam deferidos para agendas seguintes: + +1. shape estrutural completo de `IRVM` e algoritmo de lowering (Agenda 18.2); +2. layout/encoding final de `BytecodeModule` e marshaling PBX (Agenda 18.3); +3. estrategia de otimizacao de backend. + ## Expected Spec Material 1. Atualização de `docs/pbs/specs/13. Lowering IRBackend Specification.md` com adendo backend-facing. @@ -65,4 +155,3 @@ Fechar o `IRBackend` como contrato de entrada do backend executável, de forma s - `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md` - `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md` - `../runtime/docs/runtime/decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md` - diff --git a/docs/pbs/agendas/18.2. Backend Workshop 2 - LowerToVM and IRVM Contract.md b/docs/pbs/agendas/18.2. Backend Workshop 2 - LowerToVM and IRVM Contract.md index 301c4468..d762f852 100644 --- a/docs/pbs/agendas/18.2. Backend Workshop 2 - LowerToVM and IRVM Contract.md +++ b/docs/pbs/agendas/18.2. Backend Workshop 2 - LowerToVM and IRVM Contract.md @@ -1,6 +1,6 @@ -# 18.2. Backend Workshop 2 - LowerToVM and IRVM Contract +# 18.2. Backend Workshop 2 - LowerToIRVM and IRVM Contract -Status: Active (Draft) +Status: Ready for Closure (v1 Draft Text) ## Purpose @@ -42,12 +42,109 @@ Definir o contrato intermediário `IRVM` e as regras normativas de lowering `IRB 5. Como representar efeitos de stack no `IRVM` para detectar underflow/mismatch antes de emitir bytes? 6. Como versionar `IRVM` em relação à linha de ISA do runtime selecionada? +## Resolution (v1) + +Nao ha open questions bloqueantes remanescentes nesta agenda. + +As perguntas desta agenda ficam consideradas resolvidas para v1 pelos termos normativos abaixo. + +## Normative Text (Draft for Closure) + +### 1) Escopo e fronteira + +1. Esta agenda define o contrato intermediario `IRVM` e as regras obrigatorias de lowering `IRBackend -> IRVM`. +2. O objetivo do `IRVM` v1 e permitir emissao mecanica e deterministica de bytecode para runtime `core-v1`. +3. Esta agenda NAO define o marshaling binario final `IRVM -> BytecodeModule` (Agenda 18.3). + +### 2) Modelo de IRVM (quase-ISA estendido) + +1. `IRVM` v1 adota modelo quase-ISA: + - opcodes da Core ISA alvo; + - e opcodes internos estendidos (`IRVM_EXT`) quando necessarios para normalizacao/otimizacao. +2. `IRVM_EXT` MUST ser interno ao compilador e MUST NOT aparecer no artefato executavel final. +3. Todo opcode `IRVM_EXT` MUST declarar metadados estruturais equivalentes a spec de opcode: + - `pops`, + - `pushes`, + - `is_branch`, + - `is_terminator`. +4. O backend MUST expandir/reduzir todo `IRVM_EXT` para Core ISA antes da fase de emissao de bytecode. + +### 3) Controle de fluxo e labels + +1. O `IRVM` pode usar labels simbolicos internamente. +2. A resolucao final de labels para immediates `u32` de salto MUST ocorrer no `LowerToIRVM`. +3. O target final de salto MUST seguir contrato da VM: + - offset relativo ao inicio da funcao (`func_start + target_rel` em runtime). +4. Todo salto MUST apontar para fronteira valida de instrucao da funcao alvo. +5. Caminho alcancavel que cai no fim da funcao sem terminador MUST ser erro de compilacao. + +### 4) IDs deterministas de funcao + +1. O backend MUST produzir `func_id` deterministico para `CALL`, `SPAWN` e `MAKE_CLOSURE`. +2. Regra v1: + - entrypoint executavel no indice `0`; + - demais callables por ordenacao deterministica `(module_key, callable_name, source_start)`. +3. O mesmo grafo de entrada admitido MUST produzir os mesmos `func_id`. + +### 5) Contrato de chamadas + +1. `CALL` MUST referenciar `func_id` valido. +2. `SPAWN` MUST respeitar aridade exata da funcao de destino. +3. `CALL_HOST` no `IRBackend` MUST lower para `HOSTCALL ` em `IRVM` pre-load. +4. `CALL_INTRINSIC` no `IRBackend` MUST lower para `INTRINSIC ` em `IRVM`. +5. `CALL_CLOSURE` com callee nao determinavel estaticamente e proibido no v1. + +### 6) Contrato de slots por funcao + +Para cada funcao em `IRVM`, o backend MUST fixar: + +1. `param_slots`, +2. `local_slots`, +3. `return_slots`, +4. `max_stack_slots`. + +`RET` MUST ser consistente com `return_slots` em todos os caminhos alcancaveis. + +### 7) Pre-verificacao obrigatoria no compilador + +Antes de emitir bytecode, o compilador MUST executar pre-verificacao estrutural em `IRVM` (ja em Core ISA, sem `IRVM_EXT`), cobrindo no minimo: + +1. validade de target de saltos; +2. coerencia de altura de stack em joins; +3. ausencia de underflow e overflow contra `max_stack_slots`; +4. consistencia de `RET` com `return_slots`; +5. validade de `func_id` referenciado; +6. validade de aridade em `CALL`/`SPAWN`/`CALL_CLOSURE`; +7. regra de `YIELD` com stack vazia; +8. validade estrutural de `HOSTCALL`/`INTRINSIC` no shape de IR. + +O verificador do runtime permanece autoritativo e continua obrigatorio. + +### 8) Regra de YIELD + +`YIELD` com stack nao vazia MUST ser rejeitado no compilador como erro deterministico de lowering/verificacao. + +### 9) Versionamento do IRVM + +1. `IRVM` MUST carregar `vm_profile` explicito. +2. Para v1, o perfil normativo e `core-v1`. +3. Mismatch entre `vm_profile` e alvo de emissao/verificacao MUST falhar de forma deterministica. + +### 10) Deferrals explicitos + +Sem deferrals de perguntas abertas desta agenda. + +Permanecem fora de escopo por fronteira de agenda: + +1. formato binario final de `BytecodeModule` e seccionamento PBX (Agenda 18.3); +2. politicas avancadas de otimizacao nao necessarias para conformidade v1. + ## Expected Spec Material 1. Nova spec: `IRBackend -> IRVM` lowering contract. 2. Nova spec: `IRVM` model e invariantes. 3. Tabela de mapeamento `IRVM op -> ISA op` por linha de runtime suportada. -4. Critérios de testes unitários do `LowerToVMPipelineStage`. +4. Critérios de testes unitários do `LowerToIRVMPipelineStage`. ## Non-Goals @@ -58,7 +155,7 @@ Definir o contrato intermediário `IRVM` e as regras normativas de lowering `IRB ## Inputs -- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToVMPipelineStage.java` +- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToIRVMPipelineStage.java` - `../runtime/docs/runtime/virtual-machine/ISA_CORE.md` - `../runtime/docs/runtime/specs/02-vm-instruction-set.md` - `../runtime/docs/runtime/specs/02a-vm-values-and-calling-convention.md` @@ -66,4 +163,3 @@ Definir o contrato intermediário `IRVM` e as regras normativas de lowering `IRB - `../runtime/crates/console/prometeu-bytecode/src/opcode_spec.rs` - `../runtime/crates/console/prometeu-bytecode/src/decoder.rs` - `../runtime/crates/console/prometeu-vm/src/verifier.rs` - diff --git a/docs/pbs/agendas/18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md b/docs/pbs/agendas/18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md index 8493e357..90a90d2f 100644 --- a/docs/pbs/agendas/18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md +++ b/docs/pbs/agendas/18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md @@ -1,6 +1,6 @@ # 18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance -Status: Active (Draft) +Status: Ready for Closure (v1 Draft Text) ## Purpose @@ -44,6 +44,132 @@ Fechar o contrato de emissão de bytecode/PBX a partir de `IRVM`, com conformida 5. Como padronizar mensagens/erros de marshaling para manter diagnóstico determinístico? 6. Qual suíte mínima de integração prova “bytecode emitido roda no runtime” sem packer? +## Resolution (v1) + +Nao ha open questions bloqueantes remanescentes nesta agenda. + +As perguntas desta agenda ficam consideradas resolvidas para v1 pelos termos normativos abaixo. + +## Normative Text (Draft for Closure) + +### 1) Escopo e fronteira + +1. Esta agenda define o contrato normativo de marshaling `IRVM -> BytecodeModule` para runtime `core-v1`. +2. O backend executavel MUST produzir artefato pre-load compativel com loader e verifier do runtime. +3. Esta agenda nao define packer/cart assembly. + +### 2) Direcao JVM-inspired (adaptada) + +1. O backend adota modelo de referencia simbolica interna antes de indice numerico final: + - referencias simbolicas existem em `IRVM` e no emitter interno; + - indices finais (`func_id`, `sysc_index`, `intrinsic_id`) sao materializados de forma deterministica no marshaling. +2. O runtime continua numeric-only na execucao final. + +### 3) Contrato do BytecodeModule emitido + +O emitter MUST preencher: + +1. `const_pool`, +2. `functions`, +3. `code`, +4. `exports`, +5. `syscalls`, +6. `debug_info` conforme regra minima desta agenda. + +O emitter MUST gerar secao `SYSC` sempre presente (inclusive vazia), conforme contrato do loader. + +### 4) Politica de ordenacao e IDs + +1. A ordem de funcoes no artefato MUST seguir regra deterministica v1: + - entrypoint no indice `0`; + - demais funcoes por `(module_key, callable_name, source_start)`. +2. O mesmo grafo de entrada admitido MUST produzir os mesmos indices e offsets. +3. `SYSC` MUST ser deduplicado por `(module, name, version)` e ordenado por primeira ocorrencia. + +### 5) Layout de codigo por funcao + +1. O emitter SHOULD construir codigo por funcao (modelo method-local) e flatten apenas no passo final. +2. No artefato final: + - `code_offset` MUST ser crescente e unico por funcao; + - `code_len` MUST refletir exatamente o trecho da funcao; + - `code_offset + code_len` de cada funcao MUST estar dentro de `code.len`. +3. A concatenacao final MUST ser deterministica. + +### 6) Encoding de instrucao + +1. Encoding MUST ser little-endian. +2. Layout de instrucao MUST ser `[opcode: u16][immediate]`. +3. Saltos MUST usar imediato `u32` relativo ao inicio da funcao. +4. O emitter MUST respeitar tamanhos de imediato definidos pela Core ISA alvo. + +### 7) Pre-load vs executable image + +1. Para chamadas host-backed, o backend MUST emitir `HOSTCALL ` no artefato pre-load. +2. O backend MUST NOT emitir `SYSCALL ` bruto no artefato pre-load. +3. Chamadas VM-owned MUST seguir caminho de `INTRINSIC ` e permanecer distintas de `SYSC`/`HOSTCALL`/`SYSCALL`. +4. O backend MUST assumir que patch `HOSTCALL -> SYSCALL` e responsabilidade do loader. + +### 8) Coerencia ABI de host bindings + +1. Cada entrada `SYSC` MUST carregar `module`, `name`, `version`, `arg_slots`, `ret_slots`. +2. O emitter MUST validar coerencia de ABI declarada com metadado host conhecido no alvo de compilacao. +3. Mismatch detectavel no compile target MUST falhar no compilador antes da serializacao final. + +### 9) Debug minimo v1 (inspirado em line tables) + +1. `debug_info` v1 MUST incluir: + - `function_names` para todos os `func_idx` emitidos; + - `pc_to_span` para todo inicio de instrucao emitida. +2. O objetivo minimo e preservar atribuicao de fonte acionavel para falhas backend/runtime que permaneçam source-atribuiveis. + +### 10) Fronteira de validacao por camada + +Modelo inspirado em separacao JVM (format/link/verify), adaptado: + +1. emitter valida formato e invariantes de marshaling; +2. loader valida resolucao canonica, capability e ABI host; +3. verifier valida estrutura de controle e pilha na imagem patchada. + +O backend MUST executar prechecks de marshaling sem substituir a autoridade do loader/verifier. + +### 11) Taxonomia de erros de marshaling + +O backend MUST expor codigos estaveis para erros de marshaling em familias: + +1. `MARSHAL_FORMAT_*`, +2. `MARSHAL_LINKAGE_*`, +3. `MARSHAL_VERIFY_PRECHECK_*`. + +Quando atribuivel, diagnostico MUST incluir ancora de fonte primaria. + +### 12) Otimizacao: criterio de responsabilidade + +1. Otimizacao semantica/estrutural de programa MUST ocorrer no backend (compile-time). +2. Runtime MUST permanecer focado em carregamento, validacao e execucao deterministica. +3. Ajustes internos de runtime sao permitidos apenas se nao alterarem semantica do programa nem contrato observavel de bytecode. + +### 13) Suite minima Gate I (sem packer) + +A conformidade minima de integracao MUST incluir fixtures: + +1. `SYSC` presente e vazio (caso sem hostcall); +2. `HOSTCALL` valido com patch para `SYSCALL`; +3. `HOSTCALL` com indice fora de faixa; +4. `SYSC` declarado e nao usado; +5. `SYSCALL` bruto em artefato pre-load; +6. mismatch de ABI (`arg_slots`/`ret_slots`); +7. capability insuficiente em load-time; +8. caminho com `INTRINSIC` valido. + +### 14) Deferrals explicitos + +Sem deferrals de perguntas abertas desta agenda. + +Permanecem fora de escopo por fronteira: + +1. formato de packer/cartucho final; +2. superfices avancadas de simbolizacao alem do minimo v1. + ## Expected Spec Material 1. Atualização de `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`. @@ -69,4 +195,3 @@ Fechar o contrato de emissão de bytecode/PBX a partir de `IRVM`, com conformida - `../runtime/crates/console/prometeu-vm/src/verifier.rs` - `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md` - `docs/general/specs/15. Bytecode and PBX Mapping Specification.md` - diff --git a/docs/pbs/agendas/README.md b/docs/pbs/agendas/README.md index 80879afb..498d0a10 100644 --- a/docs/pbs/agendas/README.md +++ b/docs/pbs/agendas/README.md @@ -8,7 +8,7 @@ Closed agendas are moved to `docs/pbs/agendas/archive`. 1. `18.0. Backend VM Pipeline - Orchestration Agenda.md` 2. `18.1. Backend Workshop 1 - IRBackend Input Contract.md` -3. `18.2. Backend Workshop 2 - LowerToVM and IRVM Contract.md` +3. `18.2. Backend Workshop 2 - LowerToIRVM and IRVM Contract.md` 4. `18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md` ## Purpose diff --git a/docs/pbs/decisions/IRVM Optimization Stage Placement Decision.md b/docs/pbs/decisions/IRVM Optimization Stage Placement Decision.md new file mode 100644 index 00000000..654d5cbc --- /dev/null +++ b/docs/pbs/decisions/IRVM Optimization Stage Placement Decision.md @@ -0,0 +1,64 @@ +# IRVM Optimization Stage Placement Decision + +Status: Accepted +Date: 2026-03-07 +Related Agendas: + +- `docs/pbs/agendas/18.0. Backend VM Pipeline - Orchestration Agenda.md` +- `docs/pbs/agendas/18.2. Backend Workshop 2 - LowerToIRVM and IRVM Contract.md` +- `docs/pbs/agendas/18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md` + +## Context + +Ao fechar a trilha backend executavel (`IRBackend -> IRVM -> bytecode`), surgiu a necessidade de definir onde a otimizacao deve ocorrer. + +As opcoes praticas eram: + +1. otimizar no runtime, +2. otimizar durante emissao de bytecode, +3. otimizar em etapa dedicada sobre `IRVM` antes da emissao. + +O runtime atual privilegia determinismo, loader/verifier estritos e execucao numeric-only. + +## Decision + +PBS adota etapa dedicada de otimizacao entre lowering e emissao: + +1. `LowerToIRVM` gera `IRVM`; +2. `OptimizeIRVM` aplica transformacoes `IRVM -> IRVM` semanticamente equivalentes; +3. `EmitBytecode` serializa o `IRVM` otimizado em artefato pre-load. + +A etapa `OptimizeIRVM` passa a ser parte canônica do pipeline backend executavel. + +## Invariants + +1. `OptimizeIRVM` e compile-time, nao runtime. +2. `OptimizeIRVM` MUST preservar semantica observavel do programa. +3. `OptimizeIRVM` MUST preservar contratos de chamada/retorno/slots. +4. `OptimizeIRVM` MUST preservar determinismo para o mesmo grafo de entrada admitido. +5. `OptimizeIRVM` MUST respeitar `vm_profile` alvo e nao deixar opcodes internos nao-eliminados para a emissao final. +6. `EmitBytecode` continua responsavel por produzir artefato pre-load conforme contrato de loader/verifier. +7. Runtime nao assume papel de otimizador semantico do programa. + +## Explicit Non-Decisions + +1. Esta decisao nao define o catalogo completo de passes de otimizacao. +2. Esta decisao nao define heuristicas de custo/performance por alvo. +3. Esta decisao nao redefine regras de verifier/loader do runtime. +4. Esta decisao nao define fluxo de packer/cartucho. + +## Spec Impact + +1. A orquestracao de pipeline em `18.0` passa a incluir `OptimizeIRVM` entre `LowerToIRVM` e `EmitBytecode`. +2. A futura spec de `IRVM` (`18.2`) deve explicitar pre/post-condicoes da etapa de otimizacao. +3. A futura spec de marshaling (`18.3`) deve explicitar que a emissao opera sobre `IRVM` pos-otimizacao. +4. `docs/general/specs/19. Verification and Safety Checks Specification.md` deve refletir cobertura de regressao para pipeline com otimizacao intermediaria. + +## Validation Notes + +Para validacao minima da decisao: + +1. o pipeline executa na ordem `LowerToIRVM -> OptimizeIRVM -> EmitBytecode`; +2. fixtures equivalentes com e sem otimizacao produzem comportamento runtime equivalente; +3. casos negativos de loader/verifier continuam falhando de forma deterministica apos a introducao de `OptimizeIRVM`. + diff --git a/prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/BuilderPipelineService.java b/prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/BuilderPipelineService.java index 0c71a7d8..cb163940 100644 --- a/prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/BuilderPipelineService.java +++ b/prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/BuilderPipelineService.java @@ -19,7 +19,8 @@ public class BuilderPipelineService { new ResolveDepsPipelineStage(), new LoadSourcesPipelineStage(), new FrontendPhasePipelineStage(), - new LowerToVMPipelineStage(), + new LowerToIRVMPipelineStage(), + new OptimizeIRVMPipelineStage(), new EmitBytecodePipelineStage() ); INSTANCE = new BuilderPipelineService(stages); diff --git a/prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToVMPipelineStage.java b/prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToIRVMPipelineStage.java similarity index 87% rename from prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToVMPipelineStage.java rename to prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToIRVMPipelineStage.java index 2ec23556..828cf834 100644 --- a/prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToVMPipelineStage.java +++ b/prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToIRVMPipelineStage.java @@ -7,7 +7,7 @@ import p.studio.compiler.workspaces.PipelineStage; import p.studio.utilities.logs.LogAggregator; @Slf4j -public class LowerToVMPipelineStage implements PipelineStage { +public class LowerToIRVMPipelineStage implements PipelineStage { @Override public BuildingIssueSink run(BuilderPipelineContext ctx, LogAggregator logs) { return BuildingIssueSink.empty(); diff --git a/prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/OptimizeIRVMPipelineStage.java b/prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/OptimizeIRVMPipelineStage.java new file mode 100644 index 00000000..9bb20fd7 --- /dev/null +++ b/prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/OptimizeIRVMPipelineStage.java @@ -0,0 +1,15 @@ +package p.studio.compiler.workspaces.stages; + +import lombok.extern.slf4j.Slf4j; +import p.studio.compiler.messages.BuildingIssueSink; +import p.studio.compiler.models.BuilderPipelineContext; +import p.studio.compiler.workspaces.PipelineStage; +import p.studio.utilities.logs.LogAggregator; + +@Slf4j +public class OptimizeIRVMPipelineStage implements PipelineStage { + @Override + public BuildingIssueSink run(BuilderPipelineContext ctx, LogAggregator logs) { + return BuildingIssueSink.empty(); + } +}