Document momentum routing direction

docs/compaction-handoff.md

@@ -2,6 +2,67 @@
 
 Current date/time context: 2026-06-27, local timezone America/Chicago.
 
+## 2026-06-27 Momentum/Corridor Direction
+
+- The user reframed the target objective: player GPS should optimize for
+  keeping speed and momentum, not for legal driving or traffic-sim behavior.
+  The player often ignores speed limits, stop signs, and normal traffic flow;
+  in a fast car, any long clean corridor can be a high-speed corridor.
+- Highway preference is still a useful proxy, and likely valuable for
+  AutoDrive, but it is not the true goal for manual player routing. Short
+  highway hops can lose time on ramps, deceleration, awkward merges, and
+  airtime. Some side streets, especially long straight corridors around
+  Heywood, can be better than nearby highways.
+- Real bad-route signatures to target:
+  stairstepping, repeated 90-degree turns, stop-start intersection chains,
+  short-segment churn, unnecessary ramp/on-off transitions, high-conflict
+  traffic areas, and airborne or steep offramp/hill segments where the car loses
+  acceleration.
+- This means the next model should be a momentum/corridor cost model, not a
+  pure road-class model:
+  distance plus turn penalties, intersection/conflict penalties, short-edge
+  churn penalties, ramp transition penalties, grade/airtime risk penalties,
+  with bonuses for long straight corridor continuity and modest
+  highway/arterial continuity.
+- The proven inline patch at `0x40bb98` only sees the current node flags. It can
+  prove and tune `Highway` preference, but it cannot distinguish staying
+  straight through a corridor from diving through a ramp, hairpin, or
+  intersection chain. That limitation explains why highway-only tuning has a
+  narrow useful range and can become pathological.
+- Next RE target should be the edge expansion/relaxation cluster, especially
+  `0x40b304`, `0x40b540`, and `0x40ba58`, where the solver has current and
+  neighbor handles and assembles the tentative `g` cost. Identify live registers
+  and struct fields for current state, neighbor state, positions, predecessor or
+  inbound direction, node flags, and degree/intersection hints.
+- Feasibility tiers:
+  - Proven/easy: road-class multiplier at `0x40bb98`.
+  - Very feasible next: additive penalties at edge relaxation for short edges,
+    intersections, highway/non-highway churn, and slope if endpoint positions
+    are visible.
+  - Biggest likely win: turn-angle or corridor-continuity penalties if
+    predecessor/current/neighbor positions or equivalent direction vectors are
+    accessible.
+  - Possible but harder: airtime/grade risk based on vertical deltas and road
+    curvature.
+  - Probably not worth first: true velocity/acceleration state in A*/Dijkstra,
+    because that expands solver state and risks breaking assumptions.
+- Keep the traffic-sim/spatial road-class work as supplemental data. It can
+  still label highway, arterial, road, pavement, and unknown areas, but it
+  should feed a broader cost function rather than act as the whole objective.
+- Suggested prototype order after compaction:
+  1. Static analyze the edge relaxation cluster around `0x40b304` and
+     `0x40ba58`.
+  2. Build a low-noise trace or inline probe around route-windowed calls only;
+     do not reintroduce pathological hot-loop logging.
+  3. First patch nonnegative additive costs only, so vanilla A*/Dijkstra
+     ordering remains sane.
+  4. Start with short-edge and turn/continuity penalties, then add ramp churn
+     and slope/airtime penalties if the required fields are available.
+  5. Validate on the fixed El Coyote city-center set plus long cross-town
+     routes: Violence, No-Tell Motel, The Gig/Cassius Rider, Aldecaldo/Badlands,
+     and the unfinished-highway cyberpsycho route. Also verify AutoDrive is not
+     accidentally given a different cost surface from manual driving.
+
 ## 2026-06-27 Tuning Status And Safe Installed State
 
 - The mod is disabled on disk for the next game launch. Active