⚡ Bolt: Avoid expensive default evaluation in HullKVCache rebuild

.jules/bolt.md

@@ -0,0 +1,4 @@
+## 2024-05-14 - Eager Evaluation in dict.setdefault
+
+**Learning:** When `dict.setdefault(key, complex_default)` is used inside a loop, Python eagerly evaluates the `complex_default` argument on *every* iteration before calling the method, even if the key already exists. In `src/geometry/hull_kv.py`, this caused a list of `Fraction(0)` objects to be instantiated repeatedly, leading to significant overhead in the `_rebuild_if_needed` loop.
+**Action:** Avoid `setdefault` for complex default values (lists, objects, function calls) in hot paths. Instead, use an explicit membership check (`if key not in dict: dict[key] = complex_default()`) to ensure lazy evaluation and avoid unnecessary allocations.

src/geometry/hull_kv.py

@@ -17,7 +17,6 @@
     HardmaxResult,
     NumberLike,
     ValueLike,
-    _as_fraction,
     _coerce_key,
     _coerce_value,
     _normalize_number,
@@ -205,10 +204,10 @@ def _rebuild_if_needed(self) -> None:
         total_value_sum = [Fraction(0) for _ in range(self._value_width or 0)]
 
         for index, (key, value) in enumerate(self._entries):
-            bucket = aggregates.setdefault(
-                key,
-                {"value_sum": [Fraction(0) for _ in value], "count": 0, "entry_indices": []},
-            )
+            # Performance: avoid eager evaluation of complex default (Fraction allocations) on every iteration
+            if key not in aggregates:
+                aggregates[key] = {"value_sum": [Fraction(0) for _ in value], "count": 0, "entry_indices": []}
+            bucket = aggregates[key]
             for coord_index, coord in enumerate(value):
                 bucket["value_sum"][coord_index] += coord
                 total_value_sum[coord_index] += coord