# 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`
- `discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.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.