Add disabled GPS momentum penalty prototype

docs/compaction-handoff.md

@@ -2,6 +2,40 @@
 
 Current date/time context: 2026-06-27, local timezone America/Chicago.
 
+## 2026-06-27 Disabled Momentum Penalty Prototype
+
+- Static disassembly of the full async solver relaxation cluster is updated.
+  `0x40ba58` has exactly four direct callers:
+  `0x40b175`, `0x40b4ac`, `0x40b6d5`, and `0x40bca7`.
+- The ordinary adjacency walkers are still the clean first patch surface:
+  `0x40b304` reaches relax at `0x40b4ac`, and `0x40b540` reaches relax at
+  `0x40b6d5`. Both compute vanilla tentative `g` in `xmm6`, copy it to
+  `xmm3`, write `f = g + h` at `[rsp+0x20]`, and then call `0x40ba58`.
+- Patch starts are `0x40b49a` for list A and `0x40b6c3` for list B. Each
+  replaces 23 bytes ending at the vanilla `0x40ba58` call and jumps to a
+  private executable cave. The cave reproduces the overwritten vanilla math,
+  adds a fixed nonnegative cost to `xmm6`, recomputes `f` from the penalized
+  `g`, calls vanilla `0x40ba58`, and jumps back after the overwritten block.
+- Added a disabled-by-default RED4ext prototype in
+  `red4ext/EdgeWeightGPS/src/Main.cpp`:
+  `kEnableGpsMomentumPenaltyInlinePatch = false`,
+  `kGpsMomentumFixedEdgePenalty = 8.0f`.
+- This first prototype is only a short-segment/churn lever. It adds a fixed
+  per-edge penalty on ordinary neighbor expansion, so routes that stair-step
+  through many small pieces become more expensive without making highways
+  cheaper. It does not yet compute turn angle, ramp transition cost, or
+  predecessor/current/neighbor geometry.
+- The first prototype intentionally leaves the two non-ordinary relax paths
+  vanilla:
+  `0x40b175` appears to be a target/terminal candidate path, and `0x40bca7`
+  appears to be a special continuation/end-candidate path from `0x40bbbc`.
+  Patch them only after the ordinary expansion test proves stable.
+- Build verification passed in toolbox:
+  `toolbox run -c 2077 ./tools/build_red4ext_shim.sh`.
+- The prototype was not installed into the live game directory. To test later,
+  flip `kEnableGpsMomentumPenaltyInlinePatch` to `true`, rebuild, install only
+  after the game is cold, and compare against the fixed El Coyote route set.
+
 ## 2026-06-27 Routing Literature And Engine Research
 
 - Added `docs/gps-routing-research.md` as the durable summary of the GPS

docs/gps-routing-research.md

@@ -403,18 +403,33 @@ Add tests targeted at the new model:
 
 ## Practical Next Step
 
-Before coding the full patch, do one static pass to finish the field map around
-`0x40b304`, `0x40b540`, and `0x40ba58`:
+The static pass around `0x40b304`, `0x40b540`, and `0x40ba58` is complete
+enough for the first prototype:
+
+- `0x40ba58` has four direct callers: `0x40b175`, `0x40b4ac`, `0x40b6d5`,
+  and `0x40bca7`.
+- The ordinary adjacency walkers are the two clean first patch sites:
+  `0x40b4ac` from `0x40b304`, and `0x40b6d5` from `0x40b540`.
+- At both ordinary sites, the live context contains solver, current state,
+  neighbor state, current node, neighbor node, current progress, neighbor
+  progress, vanilla `g`, and vanilla `f`.
+- A disabled-by-default RED4ext prototype now patches the two ordinary sites by
+  adding a fixed nonnegative per-edge penalty before calling vanilla
+  `0x40ba58`.
+
+Remaining static work before the full momentum model:
 
 - Confirm candidate vector layout at `0x40b8f0`/state allocation.
-- Confirm predecessor state pointer/index path from `state+0x1e`.
 - Confirm route-mode values at `solver+0xc4` for manual driving vs AutoDrive.
 - Identify a cheap way to detect road-class transition from current/neighbor
   node flags.
-- Decide whether the first prototype patches only the two main relax callsites
-  (`0x40b4ac`, `0x40b6d5`) or also the special/helper relax paths
-  (`0x40b175`, `0x40bca7`).
+- Decode predecessor geometry from `state+0x1e` well enough to compute
+  predecessor/current/neighbor turn angle.
+- Decide whether the later turn/ramp model should also patch the special/helper
+  relax paths (`0x40b175`, `0x40bca7`) or keep them vanilla.
 
-After that, implement the smallest live-tunable prototype with additive
-penalties only. Keep highway multiplier support available as a diagnostic knob,
-but do not use it as the primary default behavior.
+Next implementation step is to enable and test the smallest additive prototype
+with route-result comparisons. If the fixed per-edge penalty moves paths in the
+right direction and remains stable, extend it into a live-tunable cost file and
+then add turn/continuity penalties. Keep highway multiplier support available as
+a diagnostic knob, but do not use it as the primary default behavior.