refactor: clean up committedNetworks API and document geofencing state

Rename commitToNetwork to bindToNetwork to avoid confusion with the
committedNetworks set. Remove test-only setCommittedNetworks method.
Add javadoc to geofencing state fields in StateData and their public
getters on State.

Author: testower

street/src/main/java/org/opentripplanner/street/model/edge/StreetEdge.java

@@ -1267,10 +1267,10 @@ private State[] performGenericBoundaryFork(State s0, State genericState) {
       if (!isNetworkAllowedByRequest(network, request)) {
         continue;
       }
-      var committed = doTraverse(s0, s0.currentMode(), false);
-      if (committed != null) {
-        committed.commitToNetwork(network);
-        State commitState = committed.makeState();
+      var networkBranch = doTraverse(s0, s0.currentMode(), false);
+      if (networkBranch != null) {
+        networkBranch.bindToNetwork(network);
+        State commitState = networkBranch.makeState();
         if (commitState != null) {
           states.add(commitState);
         }

street/src/main/java/org/opentripplanner/street/search/state/State.java

@@ -485,10 +485,16 @@ public <T extends ExtensionRequestContext> Optional<T> getExtensionRequestContex
     return Optional.empty();
   }
 
+  /**
+   * The geofencing zones that currently contain this state's position.
+   */
   public Set<GeofencingZone> getCurrentGeofencingZones() {
     return stateData.currentGeofencingZones;
   }
 
+  /**
+   * Networks for which this generic state has already forked committed branches at zone boundaries.
+   */
   public Set<String> getCommittedNetworks() {
     return stateData.committedNetworks;
   }

street/src/main/java/org/opentripplanner/street/search/state/StateData.java

@@ -55,7 +55,19 @@ public class StateData implements Cloneable {
   /** This boolean is set to true upon transition from a normal street to a no-through-traffic street. */
   protected boolean enteredNoThroughTrafficArea;
 
+  /**
+   * The geofencing zones that currently contain this state's position. Updated at boundary
+   * crossings by {@link StateEditor#updateGeofencingZones}. Used to enforce per-field restrictions
+   * (no-traversal, no-drop-off) resolved via priority-based precedence.
+   */
   protected Set<GeofencingZone> currentGeofencingZones = Set.of();
+
+  /**
+   * Networks for which this generic (null-network) RENTING_FLOATING state has already forked
+   * committed branches at zone boundaries. Prevents duplicate forking at subsequent boundary
+   * crossings for the same network. Participates in dominance: a state whose committedNetworks
+   * is a superset dominates one with a subset (it has already explored more network options).
+   */
   protected Set<String> committedNetworks = Set.of();
 
   /** Private constructor, use static methods to get a set of initial states. */

street/src/main/java/org/opentripplanner/street/search/state/StateEditor.java

@@ -459,22 +459,20 @@ public void initializeGeofencingZones(Set<GeofencingZone> zones) {
     stateData.currentGeofencingZones = Set.copyOf(zones);
   }
 
-  public void setCommittedNetworks(Set<String> networks) {
-    if (networks.equals(stateData.committedNetworks)) {
-      return;
-    }
-    cloneStateDataAsNeeded();
-    stateData.committedNetworks = Set.copyOf(networks);
-  }
-
   /**
-   * Commit a generic RENTING_FLOATING state to a specific network at a boundary fork.
+   * Bind this state to a specific vehicle rental network. Transitions a generic (null-network)
+   * RENTING_FLOATING state into a network-specific state. Called on the forked branch in
+   * {@code performGenericBoundaryFork}.
    */
-  public void commitToNetwork(String network) {
+  public void bindToNetwork(String network) {
     cloneStateDataAsNeeded();
     stateData.vehicleRentalNetwork = network;
   }
 
+  /**
+   * Record that this generic state has already forked a committed branch for the given network.
+   * Prevents duplicate forking at subsequent boundary crossings for the same network.
+   */
   public void addCommittedNetwork(String network) {
     if (stateData.committedNetworks.contains(network)) {
       return;

street/src/test/java/org/opentripplanner/street/model/edge/StreetEdgeGeofencingTest.java

@@ -794,7 +794,9 @@ private State initialStateWithCommittedNetworks(
       null,
       false
     );
-    editor.setCommittedNetworks(committedNetworks);
+    for (var network : committedNetworks) {
+      editor.addCommittedNetwork(network);
+    }
     return editor.makeState();
   }
 }

street/src/test/java/org/opentripplanner/street/model/edge/VehicleRentalEdgeTest.java

@@ -408,7 +408,7 @@ void committedNetworkBlocksGenericPickup() {
     var arriveByReq = StreetSearchRequest.copyOf(request).withArriveBy(true).build();
     var editor = new org.opentripplanner.street.search.state.StateEditor(vertex, arriveByReq);
     editor.dropFloatingVehicle(SCOOTER, ELECTRIC, null, true);
-    editor.setCommittedNetworks(Set.of(vertex.getStation().network()));
+    editor.addCommittedNetwork(vertex.getStation().network());
     var genericState = editor.makeState();
 
     // The generic state has the station's network in committedNetworks
@@ -431,7 +431,7 @@ void uncommittedNetworkAllowsGenericPickup() {
     var arriveByReq = StreetSearchRequest.copyOf(request).withArriveBy(true).build();
     var editor = new org.opentripplanner.street.search.state.StateEditor(vertex, arriveByReq);
     editor.dropFloatingVehicle(SCOOTER, ELECTRIC, null, true);
-    editor.setCommittedNetworks(Set.of("some-other-network"));
+    editor.addCommittedNetwork("some-other-network");
     var genericState = editor.makeState();
 
     assertFalse(genericState.getCommittedNetworks().contains(vertex.getStation().network()));

street/src/test/java/org/opentripplanner/street/search/state/StateEditorGeofencingZoneTest.java

@@ -172,21 +172,6 @@ void updateGeofencingZonesArriveByFlipsDirection() {
     assertFalse(s2.getCurrentGeofencingZones().contains(ZONE));
   }
 
-  @Test
-  void setCommittedNetworks() {
-    var req = StreetSearchRequest.of().withMode(StreetMode.SCOOTER_RENTAL).build();
-    var v = intersectionVertex(1, 1);
-    var v2 = intersectionVertex(2, 2);
-    var edge = streetEdge(v, v2);
-    var s0 = new State(v, req);
-    var editor = s0.edit(edge);
-
-    editor.setCommittedNetworks(Set.of("tier", "bird"));
-
-    var s1 = editor.makeState();
-    assertEquals(Set.of("tier", "bird"), s1.getCommittedNetworks());
-  }
-
   @Test
   void addCommittedNetwork() {
     var req = StreetSearchRequest.of().withMode(StreetMode.SCOOTER_RENTAL).build();
@@ -197,7 +182,7 @@ void addCommittedNetwork() {
     var edge2 = streetEdge(v2, v3);
     var s0 = new State(v, req);
     var editor = s0.edit(edge);
-    editor.setCommittedNetworks(Set.of("tier"));
+    editor.addCommittedNetwork("tier");
     var s1 = editor.makeState();
 
     var editor2 = s1.edit(edge2);
@@ -217,7 +202,7 @@ void addCommittedNetworkNoOpIfAlreadyPresent() {
     var edge2 = streetEdge(v2, v3);
     var s0 = new State(v, req);
     var editor = s0.edit(edge);
-    editor.setCommittedNetworks(Set.of("tier"));
+    editor.addCommittedNetwork("tier");
     var s1 = editor.makeState();
 
     var editor2 = s1.edit(edge2);