# 18.0. Backend VM Pipeline - Orchestration Agenda

Status: Ready for Closure (v1 Draft Text)

## Purpose

Definir a ordem de fechamento arquitetural para o backend executável:

1. contrato de entrada `IRBackend` vindo do frontend,
2. lowering `IRBackend -> IRVM`,
3. marshaling `IRVM -> bytecode/PBX` executável no runtime.

## Context

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

## Decisions to Produce

1. Ordem oficial de workshops e critérios de saída por etapa.
2. Fronteiras normativas entre:
   - frontend (`IRBackend`),
   - backend (`IRVM` + emissão),
   - runtime (loader/verifier/execução).
3. Critérios de “backend integration-ready” para um artefato bytecode mínimo rodar no runtime.
4. Estratégia de fechamento em docs (`agendas -> decisions -> specs -> PR`).

## Core Questions

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).
2. Nova spec de contrato de `IRVM` (shape, invariantes, diagnóstico).
3. Atualização de `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`.
4. Atualização de `docs/general/specs/19. Verification and Safety Checks Specification.md`.

## Non-Goals

- Definir formato final de packer/cartucho.
- Redesenhar ISA do runtime.
- Redesenhar loader/verifier do runtime.
- Fechar otimizações de backend (peephole, SSA, etc.).

## Inputs

- `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`
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
- `../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`