Probe native GPS query helpers

docs/traffic-system-debrief.md

@@ -4,6 +4,67 @@ This is based on the public NativeDB RTTI dump, WolvenKit exports from the local
 Steam install, and the generated `all.traffic_persistent` resource from the
 Phantom Liberty archive.
 
+## Current Working Theory
+
+The first hypothesis was that the in-game car GPS routes over the generated
+traffic lane graph and consumes lane metadata such as `maxSpeed`, highway flags,
+and lane connection probabilities. Live tests have not supported that:
+
+- boosting highway `maxSpeed` changed freeway traffic speed but did not change
+  player GPS route choice
+- changing `all.lane_connections` exit probabilities did not change player GPS
+  route choice
+- probing the obvious `TrafficSystem_Pathfinding` and
+  `StartPathfinding`/`StopPathfinding` string-xref wrappers did not fire during
+  deliberate world-map route plotting
+
+The stronger current theory is that player GPS route selection goes through a
+native GPS/mappin query path, with traffic data used by traffic simulation and
+possibly as an input to cooked GPS data, but not as a live route-cost graph that
+can be steered by simple resource weighting.
+
+## Static GPS Query Candidates
+
+Static disassembly of `Cyberpunk2077.exe` found script/native registration
+thunks for `RunGPSQuery` and `UpdateGPSQuery`. The string xrefs themselves are
+registration code, but their registered function pointers lead to more
+interesting native wrappers:
+
+```text
+RunGPSQuery string rva:       0x2cd9978
+RunGPSQuery registration xref: 0x147d068
+RunGPSQuery wrapper rva:      0x29bd5ac
+RunGPSQuery helper rva:       0x29bcf14
+
+UpdateGPSQuery string rva:       0x2cd9968
+UpdateGPSQuery registration xref: 0x147cfb4
+UpdateGPSQuery wrapper rva:      0x29bd6c8
+UpdateGPSQuery helper rva:       0x29bd254
+```
+
+`RunGPSQueryHelper` appears to read source/target vector-ish script arguments,
+resolve a target object/mappin, build temporary bitsets/sets, and call helpers
+near `0x204abdc` and `0x204ac1c`. Its return value is used as a success flag by
+the wrapper.
+
+`UpdateGPSQueryHelper` appears related but takes a request type and target. Its
+return value is also used as a success flag.
+
+The next RED4ext probe should hook these helpers with return-value-preserving
+signatures, not the registration thunks:
+
+```cpp
+bool RunGPSQueryHelper(void* this_, void* from, void* to, void* debugText,
+                       void* resultText, float maxDistance);
+bool UpdateGPSQueryHelper(void* this_, uint32_t requestType, void* target,
+                          void* debugText);
+```
+
+These signatures are inferred from the wrapper call sites and Windows x64
+calling convention. If either helper fires exactly when a map destination is
+selected, it is a much better path into the actual route computation than the
+traffic-pathfinding probes.
+
 ## The High-Level Shape
 
 Cyberpunk appears to split "navigation" into at least two major domains: