fix(core): remove routing magic number, add BottleneckType::RoutingContention, harden analyzer and public API

[m2papierz]

What

Five targeted fixes across pirx-hw, pirx-core, and pirx-ir: remove the scalar routing magic number, add
#[must_use] to key public functions, document the TraceEvent size budget, add defensive clearing in the
analyzer, and align BottleneckType with the architecture spec.

Why

• overhead_fraction: The * 10.0 multiplier in scalar routing was an undocumented magic number. Users setting overhead_fraction = 0.5 in TOML had no way to know it meant 5 cycles without reading the source.
• #[must_use]: Engine::run(), run_monte_carlo(), ProfileAnalyzer::analyze(), validate(), and load() all return expensive results that are silently discarded if not captured — a common source of bugs in integration code.
• TraceEvent size: The bare assert!(size == 32) produced a cryptic error with no guidance on how to fix it when adding new variants.
• factory_starts: The analyzer relied on an implicit engine invariant (FactoryStarted always follows FactoryProduced/Failed). Clearing consumed starts makes it self-contained — correct regardless of trace ordering guarantees, future-proofing for external trace ingestion.
• BottleneckType: The spec (§4.5) defines four types including RoutingContention. The code had only three, and Balanced was semantically wrong (stall + factory failure instead of stall + routing contention). Factory failures are part of factory throughput, not a separate bottleneck dimension.

How

• overhead_fraction → overhead_cycles: RoutingConfig::Scalar now holds overhead_cycles: u32 (default 5, preserving the previous effective default). The from_config() conversion in pirx-core becomes a direct field copy. InvalidOverheadFraction error variant removed — u32 needs no range validation.
• #[must_use]: Annotations with descriptive messages on 5 public functions across 4 crates.
• TraceEvent: Added a block comment explaining memory budget (320 GB vs 480 GB at scale), cache efficiency (32 B = half a cache line), and three mitigation strategies. Separate assertion on TraceEventKind (24 bytes) pinpoints which part grew.
• factory_starts: FactoryProduced and FactoryFailed handlers set factory_starts[id] = None after consuming the start cycle. Naive reference in difference_array_matches_naive_reference updated to match.
• BottleneckType: Added RoutingContention variant. Replaced HAD_FAILURE with HAD_ROUTING tracking RoutingCompleted { latency > 0 }. Classification uses (has_stall, has_routing) match. Two new tests: routing_contention_detected (manhattan routing), balanced_when_stall_and_routing (synthetic trace).

Testing

• make ci passes locally (fmt + clippy + test + audit)
• New behavior has tests

Checklist

• PR description explains why, not just what
• No new unwrap()/expect() in production code
• No new allocations in the simulation hot loop
• Crate boundaries respected (pirx-core never imports from pirx-adapters)

[codspeed-hq]

Merging this PR will not alter performance

✅ 15 untouched benchmarks

---

_{Comparing feat/core-perf (de487af) with master (9ec9291)}