rrt/docs/atlas/route-entry-and-trackers.md

# Route Entry and Trackers

Primary atlas sources:

- [input-save-load-and-simulation.md](/home/jan/projects/rrt/docs/control-loop-atlas/input-save-load-and-simulation.md)

This note isolates the lower route-entry, linked-site, route-link, and auxiliary tracker families
that are easy to lose inside the broader runtime section.

Current grounded owners:

- `city_connection_try_build_route_with_optional_direct_site_placement`
- `route_entry_collection_try_build_path_between_optional_endpoint_entries`
- `route_entry_collection_search_path_between_entry_or_coord_endpoints`
- `route_entry_collection_create_endpoint_entry_from_coords_and_policy`
- `route_entry_collection_map_track_lay_mode_to_endpoint_policy_byte`
- `aux_route_entry_tracker_collection_refresh_route_entry_group_membership`
- `aux_route_entry_tracker_collection_try_split_route_entry_chain_into_fresh_group`
- `aux_route_entry_tracker_route_entry_pair_pass_adjacent_chain_transfer_gate`
- `aux_route_entry_tracker_collection_try_transfer_adjacent_chain_between_groups`
- `aux_route_entry_tracker_collection_reseed_group_from_route_entry_component`
- `aux_route_entry_tracker_collection_refresh_component_labels_and_reseed_invalid_groups`
- `aux_route_entry_tracker_query_tracker_component_labels_match`
- `aux_route_entry_tracker_collection_query_component_label_by_tracker_id`
- `aux_route_entry_tracker_collection_refresh_owner_adjacent_compatible_group_links`
- `aux_route_entry_tracker_dispatch_route_entry_pair_metric_query`
- `aux_route_entry_tracker_query_route_entry_pair_metric_via_weighted_recursive_search`
- `aux_route_entry_tracker_query_route_entry_pair_metric_via_recursive_neighbor_walk`
- `aux_route_entry_tracker_query_best_route_entry_pair_metric_with_endpoint_fallbacks`
- `placed_structure_route_link_rebuild_route_style_grid_counters_and_endpoint_state`
- `placed_structure_rebuild_route_style_candidate_scores_and_peer_links`

Current bounded policy split:

- policy byte `1`: single-track endpoint synthesis and direct linked-site anchor create or replace
- policy byte `2`: broader linked-site anchor rebuild plus tracker regrouping
- policy byte `4`: double-track endpoint synthesis with the larger track-laying-capacity charge

Current bounded tracker side:

- allocator at `0x004a42b0`
- refcount or destroy path at `0x004a4340`
- group-id setter at `0x00489f80`
- endpoint-membership probe at `0x00494ed0`
- bind helper at `0x00494f00`
- latch refresh at `0x00494fb0`
- cached-match refresh at `0x00495020`
- adjacent transfer gate at `0x004a4c00`
- component-label refresh sweep at `0x004a5fc0`
- component-label equality test at `0x004a62c0`
- component-label query at `0x004a6320`
- owner-adjacent compatible-group refresh at `0x004a6360`
- pair-metric dispatcher at `0x004a65b0`
- weighted recursive metric branch at `0x004a5280`
- alternate recursive neighbor-walk branch at `0x004a5900`
- endpoint-fallback chooser at `0x004a6630`

Current bounded time-side cutover:

- `runtime_query_hundredths_scaled_build_version` at `0x00482e00` is the shared rounded
  hundredths-scaled executable or session build-version query above the `>= 0x67` branch in
  `0x004a65b0`
- it is not a gameplay progress flag; in the local path it comes from the `RT3.EXE` version-info
  source through `0x00482d10`, then `+0.0001`, `*100.0`, and round, while the multiplayer path
  delegates through `0x0046a4b0`
- the recovered `>= 0x67`, `>= 0x68`, `>= 0x69`, and `>= 0x6a` caller pattern now lines up with
  executable build values `1.03`, `1.04`, `1.05`, and `1.06`
- that makes the tracker cutover read more cleanly too:
  `0x004a65b0` is now best treated as a pre-`1.03` versus `1.03+` route-metric compatibility
  dispatcher, not as any gameplay-time or era-side mode switch
- the branch source is session-aware too:
  when multiplayer state is active, the same cutover can follow the session-side build path rather
  than only the local executable version, so mixed-version compatibility is now the strongest
  current explanation for why this lower metric split exists at all
- nearby callers now make two more compatibility reads concrete:
  build `1.04+` keeps one `Recycling Plant` stem-specific branch alive inside `0x004101e0`, and
  build `1.05+` skips one older descriptor-side attenuation fallback in that same rebuild family
- the adjacent world-side compatibility lane is bounded too:
  build `1.03+` can skip one older recursive connected-component bounds walk through
  `0x004160c0 -> 0x00415f20` when scenario field `[0x006cec78+0x46c38]` is already active
- the wrapper above that compatibility read is bounded now too:
  `0x00416170` maps the current tile rectangle into the component table rooted at `0x0062ba7c`
  and only re-enters `0x004160c0` when the current owner still lacks cached bounds and the local
  suppressor gates stay clear
- the higher neighboring projected-rectangle lane is tighter too:
  `0x00418610` refreshes the temporary sample band at `0x0062b7d0`, republishes the surviving
  rectangle through `0x0044d410`, and on the single-sample path re-enters `0x004185a0` to toggle
  mask bit `0x01` for the corresponding non-sentinel cells
- the owner split above that lane is bounded now too:
  `0x00418be0` is the broader local-runtime record builder from candidate stem plus projected
  scratch, while `0x00418a60` is the smaller current-subject clone path over the same
  mask-refresh and component-bounds helpers
- the scratch tail is tighter now too:
  `0x00416620` publishes the projected rectangle into the shared local-runtime globals, validates
  route-entry coverage through `0x00494240`, can branch into the special projected-slot picker
  `0x00415570`, and refreshes the compact per-cell side tables through `0x00414e10`
- the last side helpers under that local-runtime branch are bounded now too:
  `0x00414470` is just the projected-slot cache setter above the subject-clone path, while
  `0x00418040` is the optional local-runtime overlay-payload renderer sampled by the broader
  stem-based builder at `0x00418be0`
- the higher local-runtime owner chain is bounded now too:
  `0x004133b0` first drains the temporary placed-structure id queue through `0x00414480` and
  `0x00413f50`, rebuilding cloned local-runtime records through `0x0040e450`, and then sweeps all
  live placed structures through `0x0040ee10`
- the owner context above that local-runtime refresh is tighter now too:
  inside the `Setting up Players and Companies...` `319` lane of
  `world_run_post_load_generation_pipeline`, the pipeline refreshes the route-entry collection
  `0x006cfca8`, then the auxiliary route-entry tracker collection `0x006cfcb4`, then
  `0x004133b0`, then a flagged world-grid cleanup sweep through `0x00448af0/0x00533fe0`, and only
  after that the later route-entry post-pass at `0x00491c20`
- the side refresh split is tighter now too:
  `0x0040ee10` publishes one local position/scalar triplet through `0x00530720` and then tails
  into `0x0040e360`, whose current grounded subtype-`1`, class-`3` branch recomputes a linked-site
  anchor triplet from the peer route-entry anchor when that anchor is still live
- the heavier sibling above that side refresh is bounded now too:
  `0x0040eba0` is the world-coordinate mutation helper that rewrites cached grid coordinates,
  updates the subtype-`4` proximity-bucket family when needed, rebuilds the same triplet, and then
  tails into `0x0040e360`

What this note is for:

- Route-search ownership and quality gates
- Linked-site route-anchor rebuilds
- Auxiliary route-entry tracker regrouping semantics
- Route-style peer-link emission and route-link state
- Track-laying-capacity interactions with route synthesis

Latest local closure:

- The linked-transit cache split is now locally bounded rather than just suggestive:
  the pre-`1.03` versus `1.03+` tracker metric dispatcher still matters for the weighted
  autoroute cache lanes at `company_rebuild_linked_transit_autoroute_site_score_cache`
  `0x00407bd0`, but the grounded downstream chain now stops at route choice rather than company
  pressure. Cache lane `+0x16` feeds the owned-site selector
  `company_select_best_owned_linked_transit_site_by_autoroute_score` `0x00408280`, and the
  weighted peer-side bands then feed `company_build_linked_transit_autoroute_entry`
  `0x00408380`; train-side append and add-train helpers `0x00409770` and `0x00409830` only
  inherit that weighted choice by calling the builder. By contrast, the company-wide roster target
  at `company_compute_owned_linked_transit_site_score_total` `0x00408f70` still sums only raw
  cache `+0x12` before `company_balance_linked_transit_train_roster` `0x00409950` reacts. So this
  local semantic edge is effectively closed: the compatibility split perturbs ranked site choice
  and seeded autoroute peer choice, not the later train-count target, and any further
  weighted-lane consumer would have to live outside the currently grounded local chain.