Raptor/.agents/invariants/PERFORMANCE_OPTIMIZATION_INVARIANT.md

Compiler Performance Optimization Invariant

Scope

This invariant applies to:

• ONNX-to-Spatial lowering;
• graph and trivial merge;
• PEFT scheduling;
• scheduled materialization;
• deferred communication;
• Spatial-to-PIM lowering;
• bufferization;
• memory coalescing;
• liveness planning;
• PIM code generation.

Invariant

A compiler compile-time or memory optimization must not reduce available hardware parallelism or worsen theoretical execution time. In the absence of a precise runtime model, it is forbidden to serialize independent work, reduce the number of simultaneously schedulable compute instances, replace parallel graph or core batches with sequential loops, introduce recomputation, add runtime copies, increase communication or instruction count, or lengthen the schedule critical path merely to reduce compiler time or memory usage.

An optimization is acceptable only when its static runtime proxies are equal or better.

Forbidden optimization trades

Do not:

• use fewer parallel lanes or cores to simplify IR;
• scalarize a valid graph or core batch;
• replace independent operations with one sequential loop;
• recompute values to reduce storage;
• add device/device or host/device copies to reduce peak memory;
• change hardware parameters to make a benchmark easier;
• reduce communication concurrency by imposing a global serial order;
• increase emitted instruction count to reduce compiler analysis;
• move PIM work to the host.

Required proof

Every performance change must report before and after:

• compiler wall time;
• compiler peak RSS;
• IR operation and value counts at the changed stage;
• logical compute-instance count;
• graph compute batch and scheduled batch lane counts;
• PEFT class and core assignment;
• maximum scheduled critical-path or step count;
• MVM/VMM and vector instruction counts;
• send and receive counts and bytes;
• total emitted instruction count;
• maximum instructions assigned to one core;
• number and size of runtime memory copies;
• final host, weights, logical-core, physical-core, and maximum-core memory;
• numerical validation.

Stop rule

If compile time or memory improves but a runtime proxy worsens, stop and reject the change.