A faster benchmark is not enough if caching, parsing, batching, or concurrency changes values, ordering, resource ownership, or user-visible behavior.

Performance work is unusually good at producing convincing partial evidence.

A benchmark gets faster. Memory falls. Fewer files are parsed. A cache hit rate rises. Those measurements are valuable—but they do not show that the optimized program preserved the behavior and boundaries that mattered.

Performance refactors need two contracts: the budget and the parity floor.

Measure the intended resource

The performance contract should name what is being improved:

wall time;
peak resident memory;
allocation volume;
repeated parsing;
network requests;
startup latency;
interaction latency;
cache retention;
concurrency and queue pressure.

Absolute wall-clock thresholds can be noisy across machines. Ratios between phases in the same run often provide a more portable guard against redundant work.

Memory and time budgets should preserve their provenance: workload, observed value, accepted budget, host class, and reason the threshold exists.

Never widen a budget silently

When a performance test fails, the change may have regressed or the workload may have grown legitimately.

Increasing the threshold without explaining which happened turns the test into decoration. A baseline update should carry the new measurement and its rationale.

The same principle applies to timeouts. A longer timeout may hide a deadlock or uncontrolled path rather than accommodate healthy work.

Optimization changes architecture

Common performance changes include:

memoizing source analysis;
sharing caches across requests;
sharding tests across processes;
adding bounded concurrency;
pruning repeated graph traversal;
replacing copies with shared buffers;
delaying initialization;
batching writes or network calls.

Each can change behavior. A cache may become stale. Shared state may leak between workspaces. Concurrency may reorder effects. A buffer optimization may expose mutation. Lazy initialization may move an error into a user flow.

Choose parity proportional to the change

A source-index cache may need deterministic repeat-run checks, freshness invalidation tests, and symbol-map equivalence. A browser replay optimization may need route, request, and visual states. A serialization optimization may need exact fixture comparison and known-limit tests.

Evidence can include:

structural graph comparison;
focused and full project tests;
module-load checks;
runtime trace replay;
route and interaction parity;
visual or scene observations;
cache lifecycle and cross-workspace isolation;
repeated-run determinism.

The contract should be selected before celebrating the benchmark result.

Performance harnesses need process discipline

Parallel test workers and browser servers can outlive an interrupted parent process. Orphaned workers consume CPU and distort later measurements.

A reliable harness tracks child process trees, responds to normal termination signals, detects orphaning, and cleans stale workers at the next run. It also separates tests whose process-global mocks or state cannot safely coexist.

Harness health belongs in the verdict. A fast result from a contaminated run is not performance evidence.

Report tradeoffs, not just wins

A useful performance result states:

workload and environment;
before and after measurements;
variance or ratio;
parity tiers run;
behavior and coverage gaps;
cache or concurrency changes;
any accepted memory-for-speed tradeoff;
whether the original workspace stayed unchanged.

KodeProof is intended to give agents a harness for exactly this kind of work. The agent can explore aggressive optimizations in isolation. Transfer depends on both the measured gain and the declared evidence that the gain did not purchase an unobserved regression.

Performance Refactors Need Parity Evidence