SP0.10: AgentLoopDriver — paced sense-decide-act loop via SimulationController (#739)

* SP0.10: Add AgentLoopDriver — paced sense-decide-act loop via SimulationController

* SP0.10: fix review — off-thread-safe snapshot + contract KDoc

Address Important + Minor findings from PR #739 review (#732 SP0.10).

Issue 2 — DefaultNetworkPerceptionPort.snapshot() was not off-thread-safe:
it read plain non-volatile mutable sim fields and iterated the live
approwedTrains list, so an off-thread driver call could throw a
ConcurrentModificationException. Fix follows the spec's capture-on-sim-thread
model (never blocks/interrupts the kDisco kernel — no sim-thread lock):
  - Add @volatile latestCaptured cache; captureSnapshot() does the fresh
    on-thread read and publishes; snapshot() returns latestCaptured or
    SimulationSnapshot.EMPTY — a pure cached read that never touches live
    state, never throws, never blocks the kernel.
  - Add SimulationSnapshot.EMPTY companion (default before first capture).
  - Migrate ShuntingLoop's two on-thread snapshot() calls (admission +
    path-advancement) to captureSnapshot() — behavior-preserving (still fresh
    reads, plus the cache publish side-effect).
  - AgentLoopDriver keeps calling snapshot(), now genuinely off-thread-safe.

Issue 1 — contract drift: the :core KDoc on Dispatcher, SimulationController
and NetworkPerceptionPort still claimed single-kDisco-thread exclusivity,
contradicting the SP0.5 spec which runs the drive loop on the driver's own
thread. Updated to reflect that the kDisco kernel runs on its own single
thread while outside callers (the SP0.10 driver, future LLM) run in their
own threads; implementations must not rely on kDisco-thread exclusivity.

Minor 4 — rewrote the "mirrors DefaultSimulationContext" comment in
AgentLoopDriver.runCycle() without exact numbers and without the misleading
call-order claim (DefaultSimulationContext does throttle→awaitIfPaused; the
driver does awaitIfPaused→throttle); kept an accurate initial-delta
convention reference.

Tests: added captureSnapshot() to the two SimulationSnapshotTest stubs;
migrated the six fresh-read assertions in DefaultNetworkPerceptionPortTest
to captureSnapshot() and added two cached-snapshot() tests (returns EMPTY
before first capture; returns last capture and stays frozen through later
mutations). AgentLoopDriverTest unchanged (driver uses the mocked snapshot()).

Author: Copilot

core/src/commonMain/kotlin/cz/vutbr/fit/interlockSim/context/SimulationController.kt

@@ -18,18 +18,23 @@ package cz.vutbr.fit.interlockSim.context
  *
  * ## Threading Contract
  *
- * - [awaitIfPaused] is called from the simulation coroutine (kDisco dispatcher thread).
- *   It suspends (not blocks) so the coroutine yields while paused.
- * - [throttle] is called from the simulation coroutine to apply wall-clock pacing.
- * - [isPaused] is called from the simulation coroutine to check pause state.
- * - [pollStepEvent] is called from the simulation coroutine; returns `true` once if
- *   a step-event was requested, then resets.
- * - [pollStepTime] is called from the simulation coroutine; returns the pending
- *   time-delta once, then resets.
+ * The kDisco simulation kernel runs on its own single thread. The methods below
+ * are invoked from one of several outside callers, which may run concurrently
+ * with each other and with the kernel:
+ * - the **simulation coroutine** — the controlled event loop in
+ *   `DefaultSimulationContext` (GUI/animated runs) — calls [awaitIfPaused],
+ *   [throttle], [isPaused], [pollStepEvent], [pollStepTime];
+ * - the **external driver coroutine** — the SP0.10 drive-loop driver (#732), which
+ *   paces its own sense→decide→act cycle independently of the kernel — calls
+ *   [awaitIfPaused] and [throttle];
+ * - [requestPause] is called by external agents (e.g. the collision detection
+ *   service) from arbitrary threads.
  *
- * The GUI/control thread sets pause state and enqueues step requests via its own
- * implementation (e.g., `SimulationRunner`). The simulation coroutine polls these
- * values through this interface.
+ * Implementations must be thread-safe across all of these callers: the
+ * GUI/control thread sets pause state and enqueues step requests, while the
+ * simulation coroutine and the external driver coroutine poll. The interface
+ * itself stays KMP-pure (see below); platform-specific synchronisation lives in
+ * implementations such as `SimulationRunner` / `NoOpSimulationController`.
  *
  * ## KMP Purity
  *
@@ -44,18 +49,19 @@ interface SimulationController {
 	/**
 	 * Suspends the simulation coroutine while the controller is in paused state.
 	 *
-	 * Called from the simulation coroutine at each iteration of the controlled loop.
-	 * When paused, this function suspends until the controller resumes or a step
-	 * is requested. Uses `suspend` (not blocking) so it cooperates with kDisco's
-	 * coroutine-based dispatcher.
+	 * Called from the simulation coroutine or the external driver coroutine at each
+	 * iteration of the controlled loop. When paused, this function suspends until
+	 * the controller resumes or a step is requested. Uses `suspend` (not blocking)
+	 * so it cooperates with kDisco's coroutine-based dispatcher.
 	 */
 	suspend fun awaitIfPaused()
 
 	/**
 	 * Applies wall-clock throttling to pace the simulation relative to real time.
 	 *
-	 * Called from the simulation coroutine after advancing the simulation clock.
-	 * The implementation may delay execution to match the desired speed multiplier.
+	 * Called from the simulation coroutine or the external driver coroutine after
+	 * advancing the simulation clock. The implementation may delay execution to
+	 * match the desired speed multiplier.
 	 *
 	 * @param simDeltaSeconds the simulation time that has just elapsed (in seconds)
 	 */
@@ -64,8 +70,8 @@ interface SimulationController {
 	/**
 	 * Returns the current pause state.
 	 *
-	 * Called from the simulation coroutine to determine whether to enter the
-	 * pause-wait loop.
+	 * Called from the simulation coroutine or the external driver coroutine to
+	 * determine whether to enter the pause-wait loop.
 	 *
 	 * @return `true` if the simulation is currently paused
 	 */

core/src/commonMain/kotlin/cz/vutbr/fit/interlockSim/ports/DefaultNetworkPerceptionPort.kt

@@ -51,9 +51,17 @@ import cz.vutbr.fit.interlockSim.util.DynamicWrapperUtils
  *
  * ## Thread-safety
  *
- * This class is **not thread-safe**.  Both the [SimulationEnvironment] state and the
- * [activeTrains] list are mutated by the kDisco simulation thread; all queries must be
- * issued from the same thread.
+ * The kDisco simulation kernel runs on its own single thread; both the
+ * [SimulationEnvironment] state and the [activeTrains] list are mutated by that
+ * thread without synchronisation. [captureSnapshot] and the `allXxx()` /
+ * single-query methods read that live state and **must** be called on the kDisco
+ * thread.
+ *
+ * [snapshot] is the exception: it reads only a `@Volatile` reference to the most
+ * recent snapshot published by [captureSnapshot], so it is safe to call from any
+ * thread (including the SP0.10 drive-loop driver) — it never blocks or interrupts
+ * the kDisco kernel and never throws. Before the first [captureSnapshot] it returns
+ * [SimulationSnapshot.EMPTY].
  *
  * @param env The simulation environment to read semaphore and block state from.
  * @param activeTrains A supplier that returns the list of currently active (approved
@@ -231,29 +239,58 @@ class DefaultNetworkPerceptionPort(
 	// ── Full snapshot ─────────────────────────────────────────────────────
 
 	/**
-	 * Captures a frozen [SimulationSnapshot] of the complete observable network state.
+	 * The most recent snapshot published by [captureSnapshot], or `null` before the
+	 * first on-thread capture.
+	 *
+	 * `@Volatile` so an off-thread [snapshot] caller (the SP0.10 drive-loop driver)
+	 * observes the latest published reference without locking; the published
+	 * [SimulationSnapshot] is itself immutable, so once a reference is seen it is safe
+	 * to read concurrently. Written only from [captureSnapshot] on the kDisco thread.
+	 */
+	@kotlin.concurrent.Volatile
+	private var latestCaptured: SimulationSnapshot? = null
+
+	/**
+	 * Returns the most recent snapshot captured on the kDisco thread, safe to call
+	 * from any thread (see [NetworkPerceptionPort.snapshot]).
+	 *
+	 * This is the **off-thread-safe** accessor: it reads only [latestCaptured] and
+	 * never touches live simulation state, so it cannot block or interrupt the kDisco
+	 * kernel and cannot throw. Before the first [captureSnapshot] it returns
+	 * [SimulationSnapshot.EMPTY].
+	 */
+	override fun snapshot(): SimulationSnapshot = latestCaptured ?: SimulationSnapshot.EMPTY
+
+	/**
+	 * Captures a fresh, consistent [SimulationSnapshot] of the complete observable
+	 * network state on the kDisco thread and publishes it to [latestCaptured].
 	 *
 	 * Calls each `allXxx()` bulk query in sequence.  Because kDisco runs on a single
 	 * simulation thread, all four calls observe the same simulation state — no events
-	 * interleave between them during a normal tick.
+	 * interleave between them during a normal tick. The result is published via
+	 * [latestCaptured] so off-thread [snapshot] callers see a consistent picture.
 	 *
 	 * [SimulationSnapshot.simTime] is set from [Process.time]; if called outside an
 	 * active kDisco simulation (e.g. in unit tests), the resulting [DiscoException]
 	 * is caught and `simTime` falls back to `0.0`. Any other exception propagates.
 	 */
-	override fun snapshot(): SimulationSnapshot =
-		SimulationSnapshot(
-			simTime =
-				try {
-					Process.time()
-				} catch (_: DiscoException) {
-					0.0
-				},
-			semaphores = allSignalAspects(),
-			blocks = allBlockOccupancies(),
-			trainPositions = allTrainPositions(),
-			timetables = allTrainTimetables()
-		)
+	override fun captureSnapshot(): SimulationSnapshot {
+		val captured =
+			SimulationSnapshot(
+				simTime =
+					try {
+						Process.time()
+					} catch (_: DiscoException) {
+						0.0
+					},
+				semaphores = allSignalAspects(),
+				blocks = allBlockOccupancies(),
+				trainPositions = allTrainPositions(),
+				timetables = allTrainTimetables()
+			)
+		latestCaptured = captured
+		return captured
+	}
 
 	// ── Grid scan ─────────────────────────────────────────────────────────
 

core/src/commonMain/kotlin/cz/vutbr/fit/interlockSim/ports/NetworkPerceptionPort.kt

@@ -40,8 +40,13 @@ import cz.vutbr.fit.interlockSim.objects.cells.Signal
  * - **Core-only**: this interface lives in `:core` with no dependency on Koog, Ollama,
  *   or any agent framework. The agent framework wiring happens in `:dispatcher-agent`
  *   (SP1 Issues #546–#551).
- * - **Thread-safety**: implementations are expected to be called from the single kDisco
- *   simulation thread.  No external synchronisation is required.
+ * - **Thread-safety**: the kDisco simulation kernel runs on its own single thread;
+ *   callers outside the simulation (e.g. the SP0.10 drive-loop driver) run on their
+ *   own threads. [snapshot] is safe to call from any thread — it returns the most
+ *   recent snapshot captured on the kDisco thread (off-thread, possibly stale, and
+ *   it never blocks the kernel). [captureSnapshot] and the individual `allXxx()` /
+ *   single-query methods read live simulation state and must be called on the
+ *   kDisco thread.
  *
  * @see DefaultNetworkPerceptionPort
  * @since Issue #541 (SP0.2 — Goal 10 sensor ports)
@@ -132,27 +137,52 @@ interface NetworkPerceptionPort {
 	// ── Full snapshot ─────────────────────────────────────────────────────
 
 	/**
-	 * Capture a frozen [SimulationSnapshot] of the complete observable network state.
+	 * Return the most recent snapshot captured on the kDisco thread, safe to call from
+	 * any thread including the external driver thread (SP0.10).
+	 *
+	 * This is the **off-thread-safe** sense call: it does **not** read live simulation
+	 * state — it returns the snapshot most recently published by [captureSnapshot],
+	 * so it never blocks or interrupts the kDisco kernel and never throws. The
+	 * returned value is a frozen, immutable [SimulationSnapshot] but may be stale
+	 * relative to the current simulation time; before the first [captureSnapshot] an
+	 * empty snapshot (simulation time at the start baseline, empty lists) is returned.
+	 * Callers that hold it across `hold()` boundaries must treat it as potentially
+	 * stale.
+	 *
+	 * For a fresh, consistent, on-thread snapshot, call [captureSnapshot] (kDisco
+	 * thread only).
+	 *
+	 * @return An immutable [SimulationSnapshot] containing all observable state.
+	 *
+	 * @since Issue #543 (SP0.4 — Goal 10 observable simulation state); made
+	 *   off-thread-safe (cached) in Issue #732 (SP0.10 — Goal 10)
+	 */
+	fun snapshot(): SimulationSnapshot
+
+	/**
+	 * Capture a fresh, consistent [SimulationSnapshot] by reading live network state,
+	 * and publish it as the latest snapshot returned by [snapshot].
 	 *
 	 * Calls all `allXxx()` bulk queries in sequence and bundles the results together
-	 * with the current simulation time into a single immutable value.  Use this method
-	 * when you need a **consistent, frozen picture** of the entire network at one
-	 * moment — for example, to hand to an LLM dispatcher, to log the full state for
-	 * debugging, or to compare two tick states.
+	 * with the current simulation time into a single immutable value, then publishes
+	 * it so an off-thread [snapshot] caller (e.g. the SP0.10 drive-loop driver) sees
+	 * a consistent picture without reading live state itself. Use this method when you
+	 * need a **consistent, frozen picture** of the entire network at one moment — for
+	 * example, to log the full state for debugging, or to compare two tick states.
+	 *
+	 * Must be called on the kDisco simulation thread (it reads mutable simulation state
+	 * that is not synchronised for off-thread access). Returns the same freshly-captured
+	 * snapshot it published, so on-thread callers (e.g. `ShuntingLoop`) get a
+	 * consistent, frozen picture identical to the previous single-threaded `snapshot`
+	 * behaviour.
 	 *
 	 * For one-off queries (e.g. "is block k1 free right now?") prefer the individual
 	 * methods on this interface.
 	 *
-	 * ## Thread-safety
-	 *
-	 * As with all methods on this interface, implementations are expected to be called
-	 * from the single kDisco simulation thread.  The snapshot is consistent within
-	 * a single-threaded call (no interleaved simulation events), but callers that hold
-	 * the snapshot across `hold()` boundaries must treat it as potentially stale.
+	 * @return An immutable [SimulationSnapshot] capturing the network state at the
+	 *   current simulation time.
 	 *
-	 * @return An immutable [SimulationSnapshot] containing all observable state.
-	 *
-	 * @since Issue #543 (SP0.4 — Goal 10 observable simulation state)
+	 * @since Issue #732 (SP0.10 — Goal 10 off-thread-safe perception)
 	 */
-	fun snapshot(): SimulationSnapshot
+	fun captureSnapshot(): SimulationSnapshot
 }

core/src/commonMain/kotlin/cz/vutbr/fit/interlockSim/ports/SimulationSnapshot.kt

@@ -65,4 +65,23 @@ data class SimulationSnapshot(
 	val blocks: List<BlockOccupancyReading>,
 	val trainPositions: List<TrainPositionReading>,
 	val timetables: List<TimetableReading>
-)
+) {
+	companion object {
+		/**
+		 * Empty snapshot returned by [NetworkPerceptionPort.snapshot] before the first
+		 * on-thread [NetworkPerceptionPort.captureSnapshot] has published a real one.
+		 *
+		 * Safe to hand to a dispatcher from any thread: it carries no live state and
+		 * carries no active trains or signal changes, so a well-behaved dispatcher
+		 * responds with a no-op decision.
+		 */
+		val EMPTY: SimulationSnapshot =
+			SimulationSnapshot(
+				simTime = 0.0,
+				semaphores = emptyList(),
+				blocks = emptyList(),
+				trainPositions = emptyList(),
+				timetables = emptyList()
+			)
+	}
+}

core/src/commonMain/kotlin/cz/vutbr/fit/interlockSim/sim/Dispatcher.kt

@@ -37,8 +37,14 @@ package cz.vutbr.fit.interlockSim.sim
  * pre-hold state.
  *
  * ## Thread-safety
- * [decide] is always called from the single kDisco dispatcher thread — no
- * synchronisation is required inside an implementation.
+ *
+ * The kDisco simulation kernel runs on its own single thread, but [decide] is
+ * invoked from **outside** the kernel — by the external drive-loop driver (SP0.10,
+ * #732) on its own thread/coroutine, not the kDisco thread. Implementations must
+ * therefore not rely on kDisco-thread exclusivity: keep them pure and stateless
+ * ([DispatchObservation] already carries everything the policy needs — invariant 4
+ * of the SP0.5 design spec, `docs/specs/2026-07-08-544-sp05-drive-loop-design.md`),
+ * or synchronise any mutable state held across calls.
  *
  * @see RuleBasedDispatcher
  * @see DispatchObservation

core/src/commonMain/kotlin/cz/vutbr/fit/interlockSim/sim/ShuntingLoop.kt

@@ -382,7 +382,7 @@ class ShuntingLoop(
 	 */
 	private fun buildAdmissionObservation(): DispatchObservation =
 		DispatchObservation(
-			snapshot = perceptionPort.snapshot(),
+			snapshot = perceptionPort.captureSnapshot(),
 			unapprovedTrains =
 				unapprowedTrains.map { train ->
 					QueuedTrainObservation(train.name, train.timetableDestinationName)
@@ -403,7 +403,7 @@ class ShuntingLoop(
 	 */
 	private fun buildPathAdvancementObservation(): DispatchObservation =
 		DispatchObservation(
-			snapshot = perceptionPort.snapshot(),
+			snapshot = perceptionPort.captureSnapshot(),
 			unapprovedTrains = emptyList(),
 			innerBlockInputs =
 				innerTrackBlocks.flatMap { block ->

core/src/commonTest/kotlin/cz/vutbr/fit/interlockSim/ports/SimulationSnapshotTest.kt

@@ -163,6 +163,9 @@ class SimulationSnapshotTest {
 				trainPositions = allTrainPositions(),
 				timetables = allTrainTimetables()
 			)
+
+		// Stub is not a caching port; both accessors return the same fixed snapshot.
+		override fun captureSnapshot(): SimulationSnapshot = snapshot()
 	}
 
 	@Test
@@ -207,6 +210,9 @@ class SimulationSnapshotTest {
 						trainPositions = allTrainPositions(),
 						timetables = allTrainTimetables()
 					)
+
+				// Stub is not a caching port; both accessors return the same fixed snapshot.
+				override fun captureSnapshot(): SimulationSnapshot = snapshot()
 			}
 		val snap = emptyPort.snapshot()