Document VAND GPS search graph

docs/compaction-handoff.md

@@ -1,14 +1,56 @@
 # Compaction Handoff
 
-Current date/time context: 2026-06-20/21, local timezone America/Chicago.
+Current date/time context: 2026-06-26, local timezone America/Chicago.
+
+## 2026-06-26 Static Update
+
+- 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`.
+- Current source has `kEnableGpsTrafficEdgeWeightPatch = false` and
+  `kEnableGpsLocalSearchHooks = false`.
+- The real route search is confirmed at `0x44f054`, called from
+  `0x44cc7c`. It is an A*/Dijkstra-style loop: validate packed handles, push
+  start state, pop best open-list state, traverse adjacent handles, call
+  provider filter slot `+0x08`, call provider edge-cost slot `+0x10`, update
+  predecessor/cost, then materialize handles through `0x44eb68`.
+- Both base and filtered cost-provider vtables point slot `+0x10` at
+  `0x44f838`. The provider vtable RVAs are still `0x2ae6120` (base) and
+  `0x2ae60f8` (filtered).
+- `0x44f838` computes geometric edge distance and multiplies by
+  `provider[0x08 + ((neighborPoint[0x13] & 0x3f) * 4)]`.
+- Base provider constructor `0x451158` fills all 64 class multipliers with
+  `1.0`. Filtered provider constructor `0x44b9b4` changes the vtable and
+  `0x44bda4` copies route masks/special zones into the provider, but ordinary
+  GPS route edge cost is still effectively geometric distance.
+- `0x44f7bc` is the heuristic helper, not edge cost. It returns distance to the
+  target scaled by the constant at `0x1431ef3a0` unless the special route-shape
+  helper supplies an adjusted distance.
+- `0x44eb68` only walks predecessor links and writes packed handles. The richer
+  final route records are produced afterward by `0x44cc7c`/query result code.
+- The packed handles resolve into `VAND` navigation blobs from
+  `base\worlds\03_night_city\_compiled\default\navigation_*.streamingsector`,
+  not directly into `all.traffic_persistent`. Final route records can still be
+  joined to `worldTrafficLanePersistent.nodeRefHash`, but that is downstream of
+  the search.
+- Added `tools/analyze_vand_navigation.py` to decode VAND blobs from extracted
+  streamingsector JSON. On the three extracted samples:
+  `files=3 blobs=300 points=5059 coords=5046`, all masks were `0x0003`, and
+  dominant classes were `1`, `4`, `5`, `3`.
+- Practical implication: traffic `maxSpeed` and `all.lane_connections`
+  probabilities are not the edge-cost surface. The next viable patch should
+  either hook `0x44f838` and classify edges spatially against precomputed
+  highway/arterial corridors, or patch the navigation VAND graph/classes after
+  extracting the relevant streamingsector resources.
 
 ## Current Installed State
 
-- Latest installed probe source: resolver-window probe. Use `git log -1
-  --oneline` for the exact checkpoint.
-- Installed RED4ext plugin:
-  `Cyberpunk 2077/red4ext/plugins/EdgeWeightGPS/EdgeWeightGPS.dll`.
-- Installed build is read-only. It should not alter route behavior.
+- Installed RED4ext plugin is disabled:
+  `Cyberpunk 2077/red4ext/plugins/EdgeWeightGPS/EdgeWeightGPS.dll.disabled`.
+- There is no active `EdgeWeightGPS.dll` in the plugin directory.
+- Source defaults are currently safe/read-only. They should not alter route
+  behavior unless rebuilt with hook toggles changed.
 - Latest archived test log:
   `logs/EdgeWeightGPS_resolve_handle_probe_4650.log`.
 - Game is cold as of the latest user message.
@@ -34,10 +76,12 @@ In `red4ext/EdgeWeightGPS/src/Main.cpp`:
 - `kEnableGpsQueryLifecycleHooks = true`
 - `kEnableGpsRouteJobLifecycleHooks = false`
 - `kEnableGpsRouteJobStartTrace = false`
-- `kEnableGpsLocalSearchHooks = true`
+- `kEnableGpsLocalSearchHooks = false`
 - `kEnableRouteUiTraceHooks = false`
 
-Active hooks:
+If rebuilt with the current defaults, active hooks are query/async lifecycle
+only. The local search/cost hooks below require `kEnableGpsLocalSearchHooks =
+true`:
 
 - query lifecycle:
   - `GPSQuerySubmit 0x70a42c`