add agendas and decisions

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

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

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 <sysc_index>` em `IRVM` pre-load.
+4. `CALL_INTRINSIC` no `IRBackend` MUST lower para `INTRINSIC <id_final>` 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`
-

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 <sysc_index>` no artefato pre-load.
+2. O backend MUST NOT emitir `SYSCALL <id>` bruto no artefato pre-load.
+3. Chamadas VM-owned MUST seguir caminho de `INTRINSIC <id_final>` 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`
-

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

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

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);

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();

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();
+    }
+}