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

