Introduce PathResult sealed class to distinguish permanent vs temporary path unavailability (#352)

* Update test files to use PathResult sealed class instead of nullable Path

- Added PathResult import to all affected test files
- Changed assertions from isNotNull() to isInstanceOf(PathResult.Available::class)
- Extract path from Available result using: val path = (result as PathResult.Available).path
- Changed null assertions to appropriate PathResult variants:
  - PathResult.OwnershipConflict: when blocks owned by different train or no reservation
  - PathResult.NoTopologicalPath: when network topology doesn't support path
- Updated test comments and descriptions to mention PathResult variants

Files updated:
- TrainNavigationServiceTest.kt (14 Available, 9 OwnershipConflict, 4 NoTopologicalPath)
- TrainPathReservationIntegrationTest.kt (5 Available, 7 OwnershipConflict)
- PathDynamicReferencesTest.kt (2 Available)
- NavigationModuleKoinTest.kt (2 Available, 1 OwnershipConflict)

Total: 23 Available, 17 OwnershipConflict, 4 NoTopologicalPath instances

* Implement PathResult sealed class to distinguish permanent vs temporary path unavailability
* Fix type mismatch: extract Path from PathResult.Available before passing to extractNavigationBlocks
* Fix remaining 3 test assertions: change isNotNull to isInstanceOf(PathResult.Available)

---------

Co-authored-by: bedaHovorka <5263405+bedaHovorka@users.noreply.github.com>

Author: Copilot

src/main/kotlin/cz/vutbr/fit/interlockSim/context/navigation/DefaultTrainNavigationService.kt

@@ -10,6 +10,8 @@
 package cz.vutbr.fit.interlockSim.context.navigation
 
 import cz.vutbr.fit.interlockSim.context.SimulationContext
+import cz.vutbr.fit.interlockSim.objects.cells.CellUtilities
+import cz.vutbr.fit.interlockSim.objects.cells.NodeCell
 import cz.vutbr.fit.interlockSim.objects.core.OrientedPathSeparator
 import cz.vutbr.fit.interlockSim.objects.core.PathSeparator
 import cz.vutbr.fit.interlockSim.objects.paths.ArrayPath
@@ -77,7 +79,7 @@ class DefaultTrainNavigationService(
 	override fun findReservedPathForTrain(
 		trainId: String,
 		separator: PathSeparator
-	): Path? {
+	): PathResult {
 		logger.info {
 			"findReservedPathForTrain: train '$trainId' requesting path from $separator"
 		}
@@ -88,21 +90,25 @@ class DefaultTrainNavigationService(
 			logger.info {
 				"findReservedPathForTrain: no PathInfo registered for train '$trainId'"
 			}
-			return null
+			return if (hasTopologicalContinuation(separator)) {
+				PathResult.OwnershipConflict
+			} else {
+				PathResult.NoTopologicalPath
+			}
 		}
 
 		// Step 2: Determine next track section from PathInfo
 		val dynamicSeparator = context.toDynamic(separator)
 		val nextTrackSection = determineNextFromPathInfo(dynamicSeparator, pathInfo)
 
-		// If separator not in PathInfo, return null (train should wait for proper reservation)
+		// If separator not in PathInfo, return OwnershipConflict (train should wait for proper reservation)
 		// Issue #296 Phase 8: Removed fallback mechanism - it returned wrong-direction blocks
 		if (nextTrackSection == null) {
 			logger.info {
 				"findReservedPathForTrain: separator $separator not in PathInfo, " +
-					"returning null (train should wait for new path reservation)"
+					"returning OwnershipConflict (train should wait for new path reservation)"
 			}
-			return null
+			return PathResult.OwnershipConflict
 		}
 
 		logger.trace {
@@ -115,7 +121,8 @@ class DefaultTrainNavigationService(
 			logger.debug {
 				"findReservedPathForTrain: no path found from $separator with direction $nextTrackSection"
 			}
-			return null
+			// No topological path = permanent condition
+			return PathResult.NoTopologicalPath
 		}
 
 		// Step 3.5: Handle path transitions (Issue #296 Phase 9)
@@ -152,7 +159,8 @@ class DefaultTrainNavigationService(
 					"findReservedPathForTrain: block $block is not reserved for train '$trainId' " +
 						"(owner: ${owner ?: "none"}), path not available"
 				}
-				return null // Block not owned by this train, return null (train waits)
+				// Block not owned by this train, return OwnershipConflict (train waits)
+				return PathResult.OwnershipConflict
 			}
 		}
 
@@ -161,7 +169,7 @@ class DefaultTrainNavigationService(
 			"findReservedPathForTrain: train '$trainId' owns all ${blocks.size} blocks in path, " +
 				"path length ${finalPath.length()}"
 		}
-		return finalPath
+		return PathResult.Available(finalPath)
 	}
 
 	override fun isPathReservedForTrain(
@@ -172,44 +180,16 @@ class DefaultTrainNavigationService(
 			"isPathReservedForTrain: checking availability for train '$trainId' from $separator"
 		}
 
-		// Step 1: Get PathInfo for this train (Issue #295/#296 Phase 5)
-		val pathInfo = registry.getPathInfo(trainId)
-		if (pathInfo == null) {
-			logger.trace { "isPathReservedForTrain: no PathInfo registered for train '$trainId'" }
-			return false
-		}
-
-		// Step 2: Determine next track section from PathInfo
-		val dynamicSeparator = context.toDynamic(separator)
-		val nextTrackSection = determineNextFromPathInfo(dynamicSeparator, pathInfo)
-		if (nextTrackSection == null) {
-			logger.trace { "isPathReservedForTrain: cannot determine next track section from PathInfo" }
-			return false
-		}
-
-		// Step 3: Build path using known direction
-		val candidatePath = buildPathWithDirection(dynamicSeparator, nextTrackSection, pathInfo)
-		if (candidatePath == null) {
-			logger.trace { "isPathReservedForTrain: no path found with direction" }
-			return false
-		}
-
-		// Step 4: Extract blocks (reuse existing method)
-		val blocks = extractDynamicTrackBlocks(candidatePath)
+		// Delegate to findReservedPathForTrain and check result type
+		val result = findReservedPathForTrain(trainId, separator)
+		val isAvailable = result is PathResult.Available
 
-		// Step 5: Check ownership (early exit on first conflict)
-		for (block in blocks) {
-			val owner = registry.getOwner(block)
-			if (owner != trainId) {
-				logger.trace {
-					"isPathReservedForTrain: block $block not owned by train '$trainId' (owner: ${owner ?: "none"})"
-				}
-				return false // Early exit on first conflict
-			}
+		logger.trace {
+			val string = if (isAvailable) "IS" else "IS NOT"
+			"isPathReservedForTrain: path $string available for train '$trainId' (result: ${result::class.simpleName})"
 		}
 
-		logger.trace { "isPathReservedForTrain: path IS available for train '$trainId'" }
-		return true
+		return isAvailable
 	}
 
 	/**
@@ -519,4 +499,19 @@ class DefaultTrainNavigationService(
 		}
 		return seen.toList()
 	}
+
+	/**
+	 * Check if there is a topological continuation for the given separator.
+	 *
+	 * This method uses the TopologyNavigator to determine if there is a valid
+	 * next track block in the topology, starting from the given separator.
+	 *
+	 * @param separator The separator to check for topological continuation
+	 * @return True if there is a topological continuation, false otherwise
+	 */
+	private fun hasTopologicalContinuation(separator: PathSeparator): Boolean {
+		val navigator = context.getTopologyNavigator()
+		val nodeCell = (separator as? NodeCell) ?: CellUtilities.assertNodeCell(separator)
+		return navigator.getNextTrackBlock(nodeCell, null) != null
+	}
 }

src/main/kotlin/cz/vutbr/fit/interlockSim/context/navigation/PathResult.kt

@@ -0,0 +1,116 @@
+/* Brno University of Technology
+ * Faculty of Information Technology
+ *
+ * BSc Thesis  2006/2007
+ *
+ * Railway Interlocking Simulator
+ *
+ * Bedrich Hovorka
+ */
+package cz.vutbr.fit.interlockSim.context.navigation
+
+import cz.vutbr.fit.interlockSim.objects.paths.Path
+
+/**
+ * Result type for train navigation path requests.
+ *
+ * ## Purpose
+ *
+ * Distinguishes between different reasons why a path might not be available,
+ * enabling better error handling and diagnostics.
+ *
+ * ## Variants
+ *
+ * - **Available**: Path exists and all blocks are reserved for the requesting train
+ * - **NoTopologicalPath**: No path exists in the network topology (permanent condition)
+ * - **OwnershipConflict**: Path exists but blocks are reserved for a different train (temporary condition)
+ *
+ * ## Semantics
+ *
+ * ### Permanent vs Temporary Conditions
+ *
+ * - **NoTopologicalPath** represents a permanent condition:
+ *   - Network topology doesn't allow a path from current position to target
+ *   - No amount of waiting will resolve this condition
+ *   - Train should either stop (dead-end) or take alternative route
+ *
+ * - **OwnershipConflict** represents a temporary condition:
+ *   - Path exists topologically but blocks are currently reserved for different train
+ *   - Condition may resolve when other train releases blocks
+ *   - Train should wait and retry periodically
+ *
+ * ## Usage Example
+ *
+ * ```kotlin
+ * val result = trainNavService.findReservedPathForTrain(trainId, separator)
+ * when (result) {
+ *     is PathResult.Available -> {
+ *         // Path is ready, continue moving
+ *         accelerateToSignal(semaphore, result.path)
+ *     }
+ *     is PathResult.NoTopologicalPath -> {
+ *         // Permanent condition - no path exists
+ *         logger.error("Train $trainId: No topological path from $separator")
+ *         stopAndReportError()
+ *     }
+ *     is PathResult.OwnershipConflict -> {
+ *         // Temporary condition - wait for blocks to become available
+ *         logger.debug("Train $trainId: Path blocked, waiting for dispatcher")
+ *         fireStop()
+ *         hold(5.0) // Wait and retry
+ *     }
+ * }
+ * ```
+ *
+ * ## Migration from Nullable Path
+ *
+ * Previous API returned nullable `Path?`:
+ * - `null` → now either `NoTopologicalPath` or `OwnershipConflict`
+ * - `Path` → now `Available(path)`
+ *
+ * This sealed class provides better type safety and clearer semantics than
+ * overloading `null` to mean multiple different conditions.
+ *
+ * @see TrainNavigationService.findReservedPathForTrain
+ * @since Issue #311 (Null Path Semantics Clarification)
+ */
+sealed class PathResult {
+	/**
+	 * Path is available and all blocks are reserved for the requesting train.
+	 *
+	 * @param path Complete path from current position to next semaphore
+	 */
+	data class Available(val path: Path) : PathResult()
+
+	/**
+	 * No topological path exists from current position to target.
+	 *
+	 * This is a **permanent** condition - the network topology doesn't allow
+	 * a path between the current position and the target. No amount of waiting
+	 * will resolve this condition.
+	 *
+	 * Possible causes:
+	 * - Dead-end track with no continuation
+	 * - Disconnected network segments
+	 * - Single InOut with no outbound connections
+	 * - Malformed network topology
+	 *
+	 * Train behavior: Should stop permanently or take alternative route.
+	 */
+	data object NoTopologicalPath : PathResult()
+
+	/**
+	 * Path exists topologically but blocks are reserved for a different train.
+	 *
+	 * This is a **temporary** condition - blocks may become available when
+	 * the other train releases them.
+	 *
+	 * Possible causes:
+	 * - Blocks reserved for different train
+	 * - No PathInfo registered for this train (dispatcher hasn't reserved path yet)
+	 * - Partial ownership (train owns some but not all blocks in path)
+	 *
+	 * Train behavior: Should wait and retry periodically.
+	 */
+	data object OwnershipConflict : PathResult()
+}

src/main/kotlin/cz/vutbr/fit/interlockSim/context/navigation/TrainNavigationService.kt

@@ -10,7 +10,6 @@
 package cz.vutbr.fit.interlockSim.context.navigation
 
 import cz.vutbr.fit.interlockSim.objects.core.PathSeparator
-import cz.vutbr.fit.interlockSim.objects.paths.Path
 
 /**
  * Service for train-specific path navigation within reserved blocks.
@@ -82,45 +81,52 @@ interface TrainNavigationService {
 	 * 1. Build path from separator through next section to next semaphore (existing pathToNextSemaphore logic)
 	 * 2. Extract all track blocks from path
 	 * 3. For each block, validate it is RESERVED for trainId (via PathReservationRegistry)
-	 * 4. If ANY block is not owned by this train, return null (train waits)
-	 * 5. If all blocks are owned, return complete path (train continues)
+	 * 4. If no topological path exists, return NoTopologicalPath (permanent condition)
+	 * 5. If ANY block is not owned by this train, return OwnershipConflict (temporary condition)
+	 * 6. If all blocks are owned, return Available with complete path (train continues)
+	 *
+	 * ## Result Semantics
+	 *
+	 * - **Available(path)**: Path exists and all blocks are reserved for this train
+	 * - **NoTopologicalPath**: Network topology doesn't allow a path (permanent, train should stop)
+	 * - **OwnershipConflict**: Blocks are reserved for different train (temporary, train should wait)
 	 *
 	 * ## Ownership Validation
 	 *
 	 * ```kotlin
 	 * for (block in path.blocks) {
 	 *     val owner = registry.getOwner(block)
 	 *     if (owner != trainId) {
-	 *         return null  // Block reserved for different train or not reserved
+	 *         return PathResult.OwnershipConflict  // Block reserved for different train
 	 *     }
 	 * }
-	 * return path  // All blocks owned by this train
+	 * return PathResult.Available(path)  // All blocks owned by this train
 	 * ```
 	 *
-	 * ## Waiting Behavior
-	 *
-	 * When this method returns null:
-	 * - Train should halt (fireStop)
-	 * - Train waits for path to become available (waitUntil with condition)
-	 * - Train retries periodically (via semaphore signal or timer)
-	 *
 	 * ## Example Usage
 	 *
 	 * ```kotlin
 	 * // In Train.Front.semaphoreAction():
-	 * val path = env.getTrainNavigationService().findReservedPathForTrain(
+	 * val result = env.getTrainNavigationService().findReservedPathForTrain(
 	 *     trainId = toString(),  // "Train #1"
-	 *     separator = semaphore,
-	 *     next = next
+	 *     separator = semaphore
 	 * )
 	 *
-	 * if (path == null) {
-	 *     // Path not reserved for this train, halt and wait
-	 *     fireStop()
-	 *     waitUntil { pathBecomesAvailable(separator, next) }
-	 * } else {
-	 *     // Path is reserved for us, continue
-	 *     accelerateToSignal(semaphore, path)
+	 * when (result) {
+	 *     is PathResult.Available -> {
+	 *         // Path is reserved for us, continue
+	 *         accelerateToSignal(semaphore, result.path)
+	 *     }
+	 *     is PathResult.NoTopologicalPath -> {
+	 *         // No path exists (dead-end or disconnected network)
+	 *         logger.error("No topological path from $separator")
+	 *         stopAndReportError()
+	 *     }
+	 *     is PathResult.OwnershipConflict -> {
+	 *         // Blocks reserved for different train, wait
+	 *         fireStop()
+	 *         hold(5.0) // Wait and retry
+	 *     }
 	 * }
 	 * ```
 	 *
@@ -133,19 +139,20 @@ interface TrainNavigationService {
 	 * val path = env.pathToNextSemaphore(separator, next)
 	 *
 	 * // New approach (with ownership validation):
-	 * val path = trainNavService.findReservedPathForTrain(trainId, separator, next)
+	 * val result = trainNavService.findReservedPathForTrain(trainId, separator)
 	 * ```
 	 *
-	 * The core path-finding logic remains unchanged; this method adds train-specific filtering.
+	 * The core path-finding logic remains unchanged; this method adds train-specific filtering
+	 * and better error reporting.
 	 *
 	 * @param trainId Unique identifier for the train (typically Train.toString())
 	 * @param separator Starting point (semaphore, InOut)
-	 * @return Path to next semaphore if all blocks are reserved for this train, null otherwise
+	 * @return PathResult indicating success (Available) or reason for failure
 	 */
 	fun findReservedPathForTrain(
 		trainId: String,
 		separator: PathSeparator
-	): Path?
+	): PathResult
 
 	/**
 	 * Check if a path to the next semaphore is currently reserved for the specified train.