Prototype spatial GPS edge weights

docs/compaction-handoff.md

@@ -6,8 +6,8 @@ Current date/time context: 2026-06-26, local timezone America/Chicago.
 
 - Installed RED4ext state is safe: the game plugin directory contains
   `EdgeWeightGPS.dll.disabled`, not an active `EdgeWeightGPS.dll`.
-- Latest committed safe source before this update: `d68a874 Disable unstable
-  traffic scorer hook`.
+- Latest committed safe source before this update: `55f4087 Document VAND GPS
+  search graph`.
 - Current source has `kEnableGpsTrafficEdgeWeightPatch = false` and
   `kEnableGpsLocalSearchHooks = false`.
 - The real route search is confirmed at `0x44f054`, called from
@@ -44,6 +44,42 @@ Current date/time context: 2026-06-26, local timezone America/Chicago.
   highway/arterial corridors, or patch the navigation VAND graph/classes after
   extracting the relevant streamingsector resources.
 
+## 2026-06-26 Spatial Edge-Cost Prototype
+
+- Added `tools/generate_spatial_edge_grid.py`, which combines
+  `work/raw-segment-json/all.traffic_persistent.json` lane flags with
+  `work/traffic-companions/json/all.lane_polygons.json` polygons.
+- Generated
+  `red4ext/EdgeWeightGPS/src/GeneratedSpatialRoadGrid.hpp`. The grid is
+  332 x 361 cells at 32 m/cell, origin `(-4640, -7392)`, with final cell
+  counts `H=7574`, `R=19617`, `G=20`, `P=996`, `unknown=91645`.
+- Added disabled-by-default runtime plumbing behind
+  `kEnableGpsSpatialEdgeWeightPatch = false`. When enabled, it attaches only
+  `GPSRouteProducer 0x44cc7c` and `GPSEdgeCost 0x44f838` unless the old verbose
+  local-search probe is also enabled.
+- The patch reads search-state vectors as `(world X, height, world Y)`, samples
+  the current endpoint, neighbor endpoint, and midpoint, chooses the strongest
+  spatial road class, then applies a multiplier after native `0x44f838`
+  returns. Current test multipliers are highway `0.62`, road `1.0`,
+  GPS-only `1.20`, pavement `1.35`, unknown `1.05`.
+- The patch intentionally does not rewrite VAND point class bits. Static
+  materialization code branches on those bits later, so changing them in data is
+  riskier than adjusting cost at the edge-cost vtable slot.
+- Fixed `DetourGpsEdgeCost` logging: native `0x44f838` indexes the provider
+  cost table by neighbor point class, not source point class.
+- Build verification passed in the Fedora toolbox:
+  `toolbox run -c 2077 tools/build_red4ext_shim.sh`.
+- The resulting DLL remains uninstalled. Game install still has only
+  `EdgeWeightGPS.dll.disabled`, not an active plugin DLL.
+
+Important caveat:
+
+- Runtime logs show long visible GPS routes are decomposed into many
+  `0x44cc7c` local searches. The `ret_rva=0x70aa22` caller with
+  `query_f78=10` and `query_ptr98_rva=0x8d76c4` mostly produces tiny connector
+  searches, not the whole route. Do not gate the spatial patch only on that
+  caller unless a later test proves it covers the desired route segment.
+
 ## Current Installed State
 
 - Installed RED4ext plugin is disabled:
@@ -76,12 +112,14 @@ In `red4ext/EdgeWeightGPS/src/Main.cpp`:
 - `kEnableGpsQueryLifecycleHooks = true`
 - `kEnableGpsRouteJobLifecycleHooks = false`
 - `kEnableGpsRouteJobStartTrace = false`
+- `kEnableGpsSpatialEdgeWeightPatch = false`
 - `kEnableGpsLocalSearchHooks = false`
 - `kEnableRouteUiTraceHooks = false`
 
 If rebuilt with the current defaults, active hooks are query/async lifecycle
-only. The local search/cost hooks below require `kEnableGpsLocalSearchHooks =
-true`:
+only. The spatial edge-cost patch requires `kEnableGpsSpatialEdgeWeightPatch =
+true`. The full local search/cost hooks below require
+`kEnableGpsLocalSearchHooks = true`:
 
 - query lifecycle:
   - `GPSQuerySubmit 0x70a42c`