feat(shortestpath): harden the pathfinder engine

runelite-client/src/main/java/net/runelite/client/plugins/microbot/shortestpath/PlannerSelectionMode.java

@@ -0,0 +1,48 @@
+package net.runelite.client.plugins.microbot.shortestpath;
+
+/**
+ * Explicit production planner rollout state.
+ *
+ * <p>A single mode prevents contradictory combinations such as selecting the upstream planner while
+ * comparison telemetry is disabled. The canary is deliberately limited to resolved F2P policy; members
+ * routes remain local until their own evidence gate is accepted.</p>
+ */
+public enum PlannerSelectionMode
+{
+	/** Run only the local Microbot planner. */
+	LOCAL,
+	/** Keep the local planner authoritative and compare the pinned upstream planner asynchronously. */
+	SHADOW,
+	/** Select a semantically matching upstream result for F2P routes, with an automatic local fallback. */
+	UPSTREAM_F2P_CANARY;
+
+	public boolean comparisonEnabled()
+	{
+		return this != LOCAL;
+	}
+
+	public boolean f2pCanaryEnabled()
+	{
+		return this == UPSTREAM_F2P_CANARY;
+	}
+
+	public static PlannerSelectionMode fromConfigValue(Object value, PlannerSelectionMode defaultValue)
+	{
+		if (value instanceof PlannerSelectionMode)
+		{
+			return (PlannerSelectionMode) value;
+		}
+		if (value instanceof String)
+		{
+			try
+			{
+				return PlannerSelectionMode.valueOf(((String) value).trim().toUpperCase());
+			}
+			catch (IllegalArgumentException ignored)
+			{
+				// Invalid test/plugin-message overrides fail closed to the persisted/default mode.
+			}
+		}
+		return defaultValue;
+	}
+}

runelite-client/src/main/java/net/runelite/client/plugins/microbot/shortestpath/PurchasableItemCatalog.java

@@ -22,7 +22,7 @@
  * consulted here — transports.tsv carries a duplicate-row OR (item row + currency-twin row) so the
  * pathfinder already plans through the transport for either holding.
  *
- * <p>Parsing is lenient like {@code LearnedBlockedEdges}: a malformed row is logged and skipped,
+ * <p>Parsing is lenient: a malformed row is logged and skipped,
  * never fatal.
  */
 @Slf4j

runelite-client/src/main/java/net/runelite/client/plugins/microbot/shortestpath/ShortestPathConfig.java

@@ -904,4 +904,18 @@ default boolean useLiveCollision() {
     default boolean resetLearnedCollision() {
         return false;
     }
+
+	@ConfigItem(
+			keyName = "plannerSelectionMode",
+			name = "Planner rollout mode",
+			description = "Local is the production default. Shadow compares the pinned upstream planner. "
+					+ "The F2P canary selects only semantically matching upstream routes and automatically "
+					+ "falls back to local; members routes remain local.",
+			position = 3,
+			section = sectionDeveloper,
+			hidden = true
+	)
+	default PlannerSelectionMode plannerSelectionMode() {
+		return PlannerSelectionMode.LOCAL;
+	}
 }

runelite-client/src/main/java/net/runelite/client/plugins/microbot/shortestpath/ShortestPathPlugin.java

@@ -402,7 +402,8 @@ public boolean isNearPath(WorldPoint location) {
             "minBankRouteSavings",
             "bankTripWhenCacheUnavailable",
             "preferTransportToTarget",
-            "maxSimilarTransportDistance"
+            "maxSimilarTransportDistance",
+            "plannerSelectionMode"
     );
     private static final String RELOAD_TRANSPORT_DEFINITIONS_KEY = "reloadTransportDefinitions";
     private static final String RESET_LEARNED_COLLISION_KEY = "resetLearnedCollision";
@@ -969,6 +970,15 @@ private Color override(String configOverrideKey, Color defaultValue) {
 		return defaultValue;
 	}
 
+	public static PlannerSelectionMode override(
+			String configOverrideKey, PlannerSelectionMode defaultValue) {
+		if (!configOverride.isEmpty()) {
+			return PlannerSelectionMode.fromConfigValue(
+					configOverride.get(configOverrideKey), defaultValue);
+		}
+		return defaultValue;
+	}
+
 	public static int override(String configOverrideKey, int defaultValue) {
 		if (!configOverride.isEmpty()) {
 			Object value = configOverride.get(configOverrideKey);

runelite-client/src/main/java/net/runelite/client/plugins/microbot/shortestpath/Transport.java

@@ -16,6 +16,11 @@
  */
 @Slf4j
 public class Transport {
+    public static final int TOTAL_LEVEL_INDEX = Skill.values().length;
+    public static final int COMBAT_LEVEL_INDEX = TOTAL_LEVEL_INDEX + 1;
+    public static final int QUEST_POINTS_INDEX = COMBAT_LEVEL_INDEX + 1;
+    public static final int REQUIREMENT_LEVEL_COUNT = QUEST_POINTS_INDEX + 1;
+
     //START microbot variables
     @Getter
 	@Setter
@@ -46,7 +51,7 @@ public class Transport {
      * The skill levels required to use this transport
      */
     @Getter
-    private final int[] skillLevels = new int[Skill.values().length];
+    private final int[] skillLevels = new int[REQUIREMENT_LEVEL_COUNT];
 
     /**
      * The quests required to use this transport
@@ -55,14 +60,19 @@ public class Transport {
     private Map<Quest, QuestState> quests = new HashMap<>();
 
     /**
-     * The ids of items required to use this transport.
-     * If the player has **any** of the matching list of items,
-     * this transport is valid
+     * Compatibility view of the item IDs required to use this transport. New code should use
+     * {@link #getItemRequirements()} so AND groups and quantities are not discarded.
      */
     @Getter
-    @Setter
     private Set<Set<Integer>> itemIdRequirements = new HashSet<>();
 
+    /**
+     * Lossless item requirements. Entries are AND-ed; alternatives within an entry are OR-ed.
+     * {@link #itemIdRequirements} remains as the compatibility view used by older callers.
+     */
+    @Getter
+    private List<TransportItemRequirement> itemRequirements = new ArrayList<>();
+
     /**
      * The type of transport
      */
@@ -138,6 +148,8 @@ public Transport(Transport origin, Transport destination) {
 
         this.itemIdRequirements.addAll(origin.itemIdRequirements);
         this.itemIdRequirements.addAll(destination.itemIdRequirements);
+        this.itemRequirements.addAll(origin.itemRequirements);
+        this.itemRequirements.addAll(destination.itemRequirements);
 
         this.type = origin.type;
 
@@ -186,7 +198,13 @@ public Transport(WorldPoint origin, WorldPoint destination, String displayInfo,
      * Object interaction Transport constructor
      */
     public Transport(WorldPoint origin, WorldPoint destination, String displayInfo, TransportType transportType, boolean isMember, String action, String target, int objectId) {
-        this(origin, destination, displayInfo, transportType, isMember, 1);
+		this(origin, destination, displayInfo, transportType, isMember, action, target, objectId, 1);
+	}
+
+	/** Object interaction transport with an explicit planner cost in ticks. */
+	public Transport(WorldPoint origin, WorldPoint destination, String displayInfo, TransportType transportType,
+	                 boolean isMember, String action, String target, int objectId, int duration) {
+		this(origin, destination, displayInfo, transportType, isMember, duration);
         this.action = action;
         this.name = target;
         this.objectId = objectId;
@@ -198,7 +216,7 @@ public Transport(WorldPoint origin, WorldPoint destination, String displayInfo,
     public Transport(WorldPoint destination, String displayInfo, TransportType transportType, boolean isMember, int maxWildernessLevel, Set<Set<Integer>> itemIdRequirements) {
         this(null, destination, displayInfo, transportType, isMember, 1);
         this.maxWildernessLevel = maxWildernessLevel;
-        this.itemIdRequirements = itemIdRequirements != null ? new HashSet<>(itemIdRequirements) : new HashSet<>();
+        setItemIdRequirements(itemIdRequirements);
     }
 
     /**
@@ -244,10 +262,17 @@ public Transport(WorldPoint destination, String displayInfo, TransportType trans
         if ((value = fieldMap.get("menuOption menuTarget objectID")) != null && !value.trim().isEmpty()) {
             value = value.trim(); // Remove leading/trailing spaces
 
-            // Regex pattern for semicolon-separated values
-            String regex = "^([^;]+);([^;]+);(\\d+)$";
-            java.util.regex.Pattern pattern = java.util.regex.Pattern.compile(regex);
-            java.util.regex.Matcher matcher = pattern.matcher(value);
+            // Microbot historically used semicolons while upstream uses whitespace. In the
+            // whitespace form the option is one token, the object id is the final numeric token,
+            // and the target may contain spaces.
+            java.util.regex.Matcher matcher = java.util.regex.Pattern
+                    .compile("^([^;]+);([^;]+);(\\d+)$")
+                    .matcher(value);
+            if (!matcher.matches()) {
+                matcher = java.util.regex.Pattern
+                        .compile("^(\\S+)\\s+(.+?)\\s+(\\d+)$")
+                        .matcher(value);
+            }
 
             if (matcher.matches()) {
                 // Extract matched groups
@@ -276,35 +301,68 @@ public Transport(WorldPoint destination, String displayInfo, TransportType trans
             String[] skillRequirements = value.split(DELIM_MULTI);
 
             for (String requirement : skillRequirements) {
-                String[] levelAndSkill = requirement.split(DELIM);
+                String[] levelAndSkill = requirement.trim().split("\\s+", 2);
 
                 if (levelAndSkill.length < 2) {
                     continue;
                 }
 
                 int level = Integer.parseInt(levelAndSkill[0]);
-                String skillName = levelAndSkill[1];
+                String skillName = levelAndSkill[1].trim();
 
+                boolean resolved = false;
                 Skill[] skills = Skill.values();
                 for (int i = 0; i < skills.length; i++) {
                     if (skills[i].getName().equals(skillName)) {
                         skillLevels[i] = level;
+                        resolved = true;
                         break;
                     }
                 }
+                String normalizedSkillName = skillName.toLowerCase(Locale.ROOT);
+                if (normalizedSkillName.startsWith("total")) {
+                    skillLevels[TOTAL_LEVEL_INDEX] = level;
+                    resolved = true;
+                } else if (normalizedSkillName.startsWith("combat")) {
+                    skillLevels[COMBAT_LEVEL_INDEX] = level;
+                    resolved = true;
+                } else if (normalizedSkillName.startsWith("quest")) {
+                    skillLevels[QUEST_POINTS_INDEX] = level;
+                    resolved = true;
+                }
+                // A requirement we cannot resolve used to vanish without a word, and an unset level is
+                // indistinguishable from "no requirement" — so the transport became usable by everyone.
+                // That is how "42 Agility<spaces>7" (a Duration separated by spaces instead of a tab)
+                // turned the Draynor underwall tunnel into a free shortcut: the name read as
+                // "Agility      7", matched nothing, and the 42 was silently dropped. Worse than a
+                // no-op, because blocksWalkingEdgeWhenUnavailable would otherwise have routed AROUND
+                // an unusable shortcut; with the gate erased the planner actively prefers it.
+                if (!resolved) {
+                    throw new IllegalArgumentException("Unresolved transport skill requirement '"
+                            + requirement.trim() + "' in raw field '" + value.trim() + "'");
+                }
             }
         }
 
-        if ((value = fieldMap.get("Item IDs")) != null && !value.trim().isEmpty()) {
-            String[] itemIdsList = value.split(DELIM_MULTI);
-            for (String listIds : itemIdsList) {
-                Set<Integer> multiitemList = new HashSet<>();
-                String[] itemIds = listIds.split(DELIM);
-                for (String item : itemIds) {
-                    int itemId = Integer.parseInt(item);
-                    multiitemList.add(itemId);
+        if ((value = fieldMap.get("Items")) != null && !value.trim().isEmpty()) {
+            setItemRequirements(TransportItemRequirement.parseRequirements(value));
+        } else if ((value = fieldMap.get("Item IDs")) != null && !value.trim().isEmpty()) {
+            if (value.contains("=") || value.contains("&") || value.contains("|")) {
+                setItemRequirements(TransportItemRequirement.parseRequirements(value));
+            } else {
+                Set<Set<Integer>> legacyGroups = new LinkedHashSet<>();
+                for (String listIds : value.split(DELIM_MULTI)) {
+                    Set<Integer> group = new LinkedHashSet<>();
+                    for (String item : listIds.trim().split("\\s+")) {
+                        if (!item.isEmpty()) {
+                            group.add(Integer.parseInt(item));
+                        }
+                    }
+                    if (!group.isEmpty()) {
+                        legacyGroups.add(group);
+                    }
                 }
-                itemIdRequirements.add(multiitemList);
+                setItemIdRequirements(legacyGroups);
             }
         }
 
@@ -376,7 +434,11 @@ public Transport(WorldPoint destination, String displayInfo, TransportType trans
             }
         }
 
-        if ((value = fieldMap.get("Varplayers")) != null && !value.trim().isEmpty()) {
+        value = fieldMap.get("Varplayers");
+        if ((value == null || value.trim().isEmpty())) {
+            value = fieldMap.get("VarPlayers");
+        }
+        if (value != null && !value.trim().isEmpty()) {
             for (String varplayerCheck : value.split(DELIM_MULTI)) {
                 if (varplayerCheck.isBlank()) {
                     continue;
@@ -428,6 +490,53 @@ private int getRequiredLevel(Skill skill) {
         return skillLevels[skill.ordinal()];
     }
 
+    public int getRequiredTotalLevel() {
+        return skillLevels[TOTAL_LEVEL_INDEX];
+    }
+
+    public int getRequiredCombatLevel() {
+        return skillLevels[COMBAT_LEVEL_INDEX];
+    }
+
+    public int getRequiredQuestPoints() {
+        return skillLevels[QUEST_POINTS_INDEX];
+    }
+
+    /**
+     * Updates the legacy compatibility view. Historically every ID in this structure was treated as
+     * an alternative, regardless of its nested set, so preserve that behavior as one OR requirement.
+     */
+    public void setItemIdRequirements(Set<Set<Integer>> requirements) {
+        Set<Set<Integer>> copied = new LinkedHashSet<>();
+        Set<Integer> alternatives = new LinkedHashSet<>();
+        if (requirements != null) {
+            for (Set<Integer> group : requirements) {
+                if (group == null || group.isEmpty()) {
+                    continue;
+                }
+                Set<Integer> copiedGroup = new LinkedHashSet<>(group);
+                copied.add(Collections.unmodifiableSet(copiedGroup));
+                alternatives.addAll(copiedGroup);
+            }
+        }
+        this.itemIdRequirements = copied;
+        this.itemRequirements = alternatives.isEmpty()
+                ? new ArrayList<>()
+                : new ArrayList<>(Collections.singletonList(
+                        TransportItemRequirement.legacyAlternatives(alternatives)));
+    }
+
+    private void setItemRequirements(List<TransportItemRequirement> requirements) {
+        this.itemRequirements = requirements == null
+                ? new ArrayList<>()
+                : new ArrayList<>(requirements);
+        Set<Set<Integer>> compatibility = new LinkedHashSet<>();
+        for (TransportItemRequirement requirement : this.itemRequirements) {
+            compatibility.add(Collections.unmodifiableSet(new LinkedHashSet<>(requirement.getAllItemIds())));
+        }
+        this.itemIdRequirements = compatibility;
+    }
+
     /**
      * Whether the transport has one or more quest requirements
      */
@@ -639,6 +748,7 @@ public String toString() {
                 ", skillLevels=" + Arrays.toString(skillLevels) +
                 ", quests=" + quests +
                 ", itemIdRequirements=" + itemIdRequirements +
+                ", itemRequirements=" + itemRequirements +
                 ", type=" + type +
                 ", duration=" + duration +
                 ", displayInfo='" + displayInfo + '\'' +