add agendas and decisions

This commit is contained in:
2026-03-24 13:42:24 +00:00
parent 2e640a14ae
commit f4073858b1
9 changed files with 467 additions and 17 deletions
@@ -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`.