Document GPS route handoff analysis

docs/traffic-system-debrief.md

@@ -20,11 +20,17 @@ and lane connection probabilities. Live tests have not supported that:
 - probing the obvious `RunGPSQuery` and `UpdateGPSQuery` helpers also did not
   fire during deliberate world-map route plotting
 
-The stronger current theory is that player GPS route selection goes through a
-native world-map mappin tracking path, which then updates native GPS state
-downstream. Traffic lane data is still likely used somewhere in the final route
-line, but the tested `maxSpeed` and lane-exit probability fields are traffic
-simulation inputs, not the live player-GPS edge-cost knobs.
+The stronger current theory is that player GPS route selection has two
+front-doors:
+
+- quest/objective pins are committed by updating the native journal's tracked
+  entry
+- custom/player pins are committed through native mappin tracking
+
+Both eventually update native GPS state downstream. Traffic lane data is still
+likely used somewhere in the final route line, but the tested `maxSpeed` and
+lane-exit probability fields are traffic simulation inputs, not the live
+player-GPS edge-cost knobs.
 
 ## Static GPS Query Candidates
 
@@ -145,23 +151,103 @@ moving back to empty map space fired `SetSelectedMappinWrapper` and
 fire `FrameMappinPath`, `TrackCustomPositionMappin`, `TrackMappin`, the tracked
 mappin slots, or any of the custom-position slots.
 
-That pushes the search one layer higher, into the world-map controller script
+That pushed the search one layer higher, into the world-map controller script
 methods around tracking an objective or setting a waypoint. Static REDscript
-strings name these relevant methods:
+decompilation now gives a clear high-level route action path:
 
 ```text
-WorldMapMenuGameController.TryTrackQuestOrSetWaypoint
-WorldMapMenuGameController.UpdateTrackedQuest
-WorldMapMenuGameController.UpdateTravelDestination
-WorldMapMenuGameController.TrackQuestMappin
 WorldMapMenuGameController.OnPressInput
-WorldMapMenuGameController.OnHoldInput
+  -> HandlePressInput
+    -> TryTrackQuestOrSetWaypoint
+      -> TrackQuestMappin
+        -> JournalManager.TrackEntry
 ```
 
-The current read-only REDscript probe wraps the no-argument route/tracking
-methods plus `TrackQuestMappin`. If those fire on route plotting, the next step
-is to trace their native calls or wrap the specific player-quest/custom-waypoint
-operation they delegate to.
+For non-quest/player pins the same `TryTrackQuestOrSetWaypoint` function calls
+`TrackMappin`. For custom pins it calls `TrackCustomPositionMappin`, which
+creates or updates a custom-position mappin and then tracks it.
+
+Live result: custom waypoint routing fired the native custom-position path:
+
+```text
+TrackCustomPositionMappin wrapper/core
+MappinSystem create-custom-position slot 0x2f0
+TrackMappin core
+MappinSystem set-tracked slot 0x220
+```
+
+Quest/objective route plotting did not fire those mappin hooks. The script
+decomp explains why: quest pins go through `JournalManager.TrackEntry`, not
+`TrackMappin`.
+
+## REDscript Route Surface
+
+The decompiled `WorldMapMenuGameController` is useful as an input-routing map,
+not as the planner implementation.
+
+Important script observations:
+
+- `HandlePressInput` calls `TryTrackQuestOrSetWaypoint` for
+  `world_map_menu_track_waypoint`.
+- `TrackQuestMappin` extracts the selected mappin's journal entry and calls
+  `JournalManager.TrackEntry`.
+- `UpdateTrackedQuest` reads `JournalManager.GetTrackedEntry`, asks the mappin
+  system for quest mappin positions with `GetQuestMappinPositionsByObjective`,
+  and updates world-map UI text/position state. It does not compute the GPS
+  route.
+- `GPSSystem` is present as a native class, but its REDscript surface is empty.
+- `GPSSettings` is presentation/refresh data: line effects, fixed path offsets,
+  refresh intervals, and display length.
+- `NavigationFunctionalTests.GetPathOnNavmesh`, `RunGPSQuery`, and
+  `UpdateGPSQuery` exist, but runtime tests showed they are not called by normal
+  map route plotting.
+
+The remaining route planner target is therefore native code reacting to either
+tracked-journal-entry changes or mappin tracking changes.
+
+Native direct-call scanning supports that split:
+
+```text
+RunGPSQuery helper        RVA 0x29bcf14  direct callers: 1 wrapper caller
+UpdateGPSQuery helper     RVA 0x29bd254  direct callers: 1 wrapper caller
+JournalManager.TrackEntry RVA 0x5944fc   direct callers: 13
+```
+
+The GPS query helpers appear to be exposed helper/test surfaces, not the route
+path used by the world map. `TrackEntry` is now the highest-confidence native
+handoff for quest/objective route plotting.
+
+## Native False Positives
+
+Static string scans found a tempting traffic/pathfinding cluster around RVA
+`0x512000` with messages such as:
+
+```text
+Pathfinding Algorithm Failed
+Find Straight Path Failed
+No Path Found in Traffic
+There's no point found to reach traffic
+```
+
+Disassembly around the string xrefs shows those strings being loaded into a
+large constructor/settings/result-description table rather than a solver loop.
+Related functions around `0x50f680`, `0x50fc24`, `0x513430`, and
+`0x513824` clearly touch traffic/path data, but their direct caller context
+references vehicle behavior and stuck-detection settings:
+
+```text
+vehicles.common.stuck_detection_check_distance
+vehicles.common.stuck_detection_interval
+DriveState*
+```
+
+That cluster is likely autonomous vehicle traffic/path behavior. It may share
+the same road graph as GPS, but it is not yet evidence of the player map-route
+planner.
+
+The `GPSSystem/Tick` string is also mostly a profiling/event landmark. Nearby
+code builds profiling scopes and RTTI/type registration scaffolding; it has not
+yet exposed a clean planner function.
 
 ## The High-Level Shape