prometeu-studio/docs/compiler/general/specs/21. IRVM Optimization Pipeline Specification.md

PBS IRVM Optimization Pipeline Specification

Status: Draft v1 (Pipeline Baseline)
Applies to: placement and invariants of the OptimizeIRVM stage between lowering and bytecode emission

1. Purpose

This document defines the normative placement and safety invariants of the OptimizeIRVM stage.

Its purpose is to allow optimization in the backend pipeline without transferring semantic optimization responsibility to runtime.

2. Scope

This document defines:

• canonical stage placement for OptimizeIRVM,
• input/output contracts of optimization stage boundaries,
• semantic-preservation invariants for optimization passes,
• profile-compatibility obligations (vm_profile) across optimization and emission,
• and minimum validation expectations for optimization-stage regressions.

This document does not define:

• a mandatory list of optimization passes,
• pass scheduling heuristics,
• or runtime dynamic optimization/JIT policies.

3. Authority and Precedence

Normative precedence:

1. Runtime authority (docs/specs/hardware/topics/chapter-2.md, chapter-3.md, chapter-9.md, chapter-12.md, chapter-16.md)
2. Bytecode authority (docs/specs/bytecode/ISA_CORE.md)
3. 20. IRBackend to IRVM Lowering Specification.md
4. 15. Bytecode and PBX Mapping Specification.md
5. This document

If a rule here conflicts with higher-precedence authorities, it is invalid.

4. Normative Inputs

This document depends on:

• 20. IRBackend to IRVM Lowering Specification.md
• 15. Bytecode and PBX Mapping Specification.md
• 19. Verification and Safety Checks Specification.md
• docs/pbs/decisions/IRVM Optimization Stage Placement Decision.md

5. Canonical Backend Pipeline Order

For executable backends, the canonical order is:

1. LowerToVM: IRBackend -> IRVM,
2. OptimizeIRVM: IRVM -> IRVM optimized,
3. EmitBytecode: optimized IRVM -> BytecodeModule pre-load artifact.

OptimizeIRVM must not be skipped in a pipeline that claims this profile unless explicitly configured as a no-op stage that still preserves contracts.

6. Input and Output Contracts

6.1 Input contract

OptimizeIRVM input must:

1. satisfy lowering obligations from 20,
2. carry selected vm_profile,
3. and remain structurally valid for optimizer analyses.

6.2 Output contract

OptimizeIRVM output must:

1. be semantically equivalent to input under the selected vm_profile,
2. preserve callable/slot/return contracts,
3. preserve deterministic mapping behavior required by emission,
4. and be valid for bytecode emission and subsequent runtime verification.

7. Optimization Invariants

Optimization passes must satisfy all of:

1. semantic preservation of observable program behavior,
2. determinism for the same admitted input graph and selected profile,
3. profile compatibility (no introduction of out-of-profile executable opcode forms),
4. preservation of host-backed vs VM-owned call-boundary classification,
5. and preservation of diagnostics/source-attribution hooks required at v1 minimum.

8. Runtime Responsibility Boundary

1. Semantic/structural program optimization belongs to compile-time backend stages.
2. Runtime remains responsible for load, patch, verify, and execute responsibilities.
3. Runtime-internal micro-optimizations are allowed only when they do not alter bytecode-observable semantics or contract behavior.

9. Validation Expectations

At minimum, optimization-stage validation must include:

1. equivalence-oriented regression fixtures across optimized vs non-optimized pipeline outputs,
2. preservation of known negative loader/verifier rejection behavior,
3. and deterministic reproduction of artifact-level invariants required by 15.

10. Explicit Deferrals

The following are intentionally deferred:

• target-specific optimization profitability models,
• advanced interprocedural pipelines beyond v1 baseline,
• and formal equivalence proof frameworks.

11. Non-Goals

• Defining runtime JIT or adaptive execution.
• Replacing loader/verifier contracts.
• Mandating one optimizer architecture or pass framework.

12. Exit Criteria

This document is healthy when:

1. stage placement is explicit and implemented in pipeline order,
2. optimization invariants are explicit and test-backed,
3. backend/runtime responsibility boundary is explicit,
4. and integration safety evidence references this stage concretely.