fix(SP0.11): green-up clean build integrationTest — KMP break, dispatcher wiring, pacing tests

Four SP0.11 (thin ShuntingLoop shell, #733) regressions fixed; none were
covered by CI because this branch's workflow run was never approved
(goal-10's last green CI is SP0.10).

1. KMP metadata compile break: ShuntingLoop.startAction used JVM-only
   Thread/runBlocking in commonMain. New expect/actual
   platformStartDaemonThread (util/PlatformThread.kt): JVM = daemon Thread +
   runBlocking; native (linuxX64) = CoroutineScope(newSingleThreadContext).
   Local gemma4 review suggested kotlin.concurrent.thread(isDaemon=true) —
   rejected: that API is JVM-only, does not exist on Kotlin/Native.

2. Zero-train runs everywhere the async :dispatcher-agent stack isn't wired:
   SP0.11 removed inline admission/reservation policy but only desktop-ui's
   ExampleRegistry got the replacement wiring. New
   sim/SynchronousDispatcherWiring.wireSynchronousDispatcher(env, loop) —
   production RuleBasedDispatcher + core ports, deciding and applying
   synchronously on the sim thread each iteration (pre-SP0.11 semantics;
   deterministic by construction, immune to the PR #740/#742 async races).
   Used by :fast-sim production (Main, NativeExampleRegistry — fixes 7
   native integration tests + JVM/native parity) and by the bare-ShuntingLoop
   test suites (JvmParity, ShuntingLoopRegression, TrainReporter, Metrics,
   TrainCoverage, KoinGoldenOutput, SimulationSpeedGolden). Golden baselines
   pass unchanged — the synchronous wiring reproduces pre-SP0.11 outputs.

3. AgentLoopDriverTest pacing tests updated to the SP0.11 stagnant-snapshot
   contract runCycle gained (skip decide/throttle on a re-read of the same
   sim tick, pause still honoured): multi-cycle test now advances simTime per
   cycle; zero-delta test replaced by stagnantSimTimeSkipsCycle pinning the
   skip behaviour (no re-decide — that re-decide was the #740 race source).

4. RuleBasedDispatcherDeterminismTest flaked (~1 in 3 suite runs) because the
   free-running driver thread races the unthrottled headless sim — admission
   timing drifted with OS scheduling. The Goal 10 A3 gate asserts determinism
   of the DISPATCHER, so executeRun now runs a lock-step handshake: the sim
   thread grants the driver exactly one cycle per tick and drains its
   decisions in the same tick, all on production components. 5 consecutive
   suite runs green (50/50 repetitions).

Verified: ./gradlew clean build integrationTest --no-build-cache
(122 tasks, 120 executed) BUILD SUCCESSFUL — includes :core jvm+native
tests, :core purity gate, :desktop-ui, :dispatcher-agent, :fast-sim
linuxX64 tests, detekt, ktlint.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: bedaHovorka

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

@@ -28,7 +28,7 @@ import cz.vutbr.fit.interlockSim.objects.tracks.DynamicTrackBlock
 import cz.vutbr.fit.interlockSim.util.Util
 import cz.vutbr.fit.interlockSim.util.currentTimeMillisKMP
 import cz.vutbr.fit.interlockSim.util.platformSleep
-import kotlinx.coroutines.runBlocking
+import cz.vutbr.fit.interlockSim.util.platformStartDaemonThread
 import org.koin.core.component.KoinComponent
 
 /**
@@ -304,11 +304,9 @@ class ShuntingLoop(
 		// SP0.11: Launch the external agent-driver coroutine alongside the kDisco kernel.
 		// The action runs in a daemon thread so the JVM can exit cleanly when the
 		// simulation finishes; the loop inside the action checks [isSimActive].
+		// KMP: thread creation is JVM-only, hence the expect/actual indirection.
 		agentDriverAction?.let { action ->
-			val t = Thread { runBlocking { action() } }
-			t.isDaemon = true
-			t.name = "dispatcher-agent-driver"
-			t.start()
+			platformStartDaemonThread("dispatcher-agent-driver", action)
 		}
 	}
 

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

@@ -0,0 +1,115 @@
+/* Brno University of Technology
+ * Faculty of Information Technology
+ *
+ * BSc Thesis  2006/2007
+ *
+ * Railway Interlocking Simulator
+ *
+ * Bedrich Hovorka
+ */
+package cz.vutbr.fit.interlockSim.sim
+
+import cz.vutbr.fit.interlockSim.context.SimulationEnvironment
+import cz.vutbr.fit.interlockSim.ports.DefaultNetworkActuatorPort
+import cz.vutbr.fit.interlockSim.ports.DefaultNetworkPerceptionPort
+import cz.vutbr.fit.interlockSim.ports.RouteRequestResult
+import io.github.oshai.kotlinlogging.KotlinLogging
+
+private val logger = KotlinLogging.logger {}
+
+/**
+ * Wires a [ShuntingLoop] to a [RuleBasedDispatcher] that decides **and applies
+ * synchronously on the kDisco sim thread**, once per iteration.
+ *
+ * ## Why this exists (SP0.11 follow-up)
+ *
+ * The SP0.11 thin-shell refactor (Issue #733) removed all admission and
+ * route-reservation policy from [ShuntingLoop]. The full asynchronous stack
+ * (queue + applier + off-kernel driver thread, wired by `:desktop-ui`'s
+ * `ExampleRegistry.wireDispatcherAgent`) is JVM-only and lives in
+ * `:dispatcher-agent`. Consumers that cannot or need not run the async stack —
+ * the `:fast-sim` native CLI and every test that runs a bare `ShuntingLoop` —
+ * use this synchronous wiring instead; without it a bare loop admits zero trains.
+ *
+ * ## Semantics
+ *
+ * Identical decision logic to production ([RuleBasedDispatcher]) with the
+ * pre-SP0.11 timing: each [ShuntingLoop.iteration] publishes fresh observations,
+ * then the control-step listener decides and applies in the same tick. Because
+ * observation and application are never decoupled, the duplicate-decision races
+ * the async driver needs guards for (PR #740, Issue #742) cannot occur here by
+ * construction, and runs are fully deterministic.
+ *
+ * Usage (before `context.run()`):
+ * ```kotlin
+ * val loop = ShuntingLoop(context, endTime)
+ * wireSynchronousDispatcher(context, loop)
+ * context.setMainProcess(loop)
+ * context.run()
+ * ```
+ *
+ * @param env The simulation environment backing the ports
+ * @param loop The loop to wire; its [ShuntingLoop.snapshotCaptureHook] and
+ *   [ShuntingLoop.controlStepListener] are overwritten
+ * @param maxConcurrentTrains Admission cap, defaults to production's
+ *   [RuleBasedDispatcher.DEFAULT_MAX_CONCURRENT_TRAINS]
+ * @since Issue #733 / #742 follow-up (SP0.11 green-up)
+ */
+fun wireSynchronousDispatcher(
+	env: SimulationEnvironment,
+	loop: ShuntingLoop,
+	maxConcurrentTrains: Int = RuleBasedDispatcher.DEFAULT_MAX_CONCURRENT_TRAINS
+) {
+	val perceptionPort =
+		DefaultNetworkPerceptionPort(
+			env = env,
+			activeTrains = loop::getApprovedTrains
+		)
+	val actuatorPort = DefaultNetworkActuatorPort(env = env)
+	val dispatcher = RuleBasedDispatcher(maxConcurrentTrains = maxConcurrentTrains)
+
+	loop.snapshotCaptureHook = perceptionPort::captureSnapshot
+	loop.controlStepListener =
+		ControlStepListener {
+			val observation =
+				DispatchObservation(
+					snapshot = perceptionPort.snapshot(),
+					unapprovedTrains = loop.getQueuedTrains(),
+					innerBlockInputs = loop.getInnerBlockInputs(),
+					outerBlockInputs = loop.getOuterBlockInputs()
+				)
+			dispatcher.decide(observation).forEach { decision ->
+				applyDecision(decision, loop, actuatorPort)
+			}
+		}
+}
+
+private fun applyDecision(
+	decision: DispatchDecision,
+	loop: ShuntingLoop,
+	actuatorPort: DefaultNetworkActuatorPort
+) {
+	when (decision) {
+		is DispatchDecision.ApproveTrain -> loop.approveQueuedTrain(decision.trainId)
+		is DispatchDecision.ReservePath -> {
+			val result =
+				actuatorPort.requestRoute(
+					decision.trainId,
+					decision.fromSemaphoreName,
+					decision.toSeparatorName
+				)
+			when (result) {
+				is RouteRequestResult.Reserved -> loop.incrementBlockTransition(decision.trainId)
+				else -> {
+					// Blocked/conflict outcomes are routine "wait and retry next tick" contention.
+					logger.debug {
+						"wireSynchronousDispatcher: ReservePath ${decision.fromSemaphoreName} → " +
+							"${decision.toSeparatorName} for ${decision.trainId} not applied: $result"
+					}
+					loop.incrementFailedReservation()
+				}
+			}
+		}
+		is DispatchDecision.NoAction -> Unit
+	}
+}

core/src/commonMain/kotlin/cz/vutbr/fit/interlockSim/util/PlatformThread.kt

@@ -0,0 +1,19 @@
+package cz.vutbr.fit.interlockSim.util
+
+/**
+ * Starts a named daemon thread that runs [action] as a blocking coroutine.
+ *
+ * KMP expect/actual: the JVM implementation launches a daemon [Thread] wrapping
+ * `runBlocking { action() }`, so the JVM can exit cleanly when the simulation
+ * finishes. Used by the SP0.11 dispatcher-agent driver loop
+ * ([cz.vutbr.fit.interlockSim.sim.ShuntingLoop.agentDriverAction]), which is a
+ * JVM-only feature — the native target has no agent driver and its actual fails
+ * fast if ever invoked.
+ *
+ * @param name Thread name (for diagnostics, e.g. "dispatcher-agent-driver")
+ * @param action Suspend action to run for the thread's lifetime
+ */
+expect fun platformStartDaemonThread(
+	name: String,
+	action: suspend () -> Unit
+)

core/src/jvmMain/kotlin/cz/vutbr/fit/interlockSim/util/PlatformThread.kt

@@ -0,0 +1,13 @@
+package cz.vutbr.fit.interlockSim.util
+
+import kotlinx.coroutines.runBlocking
+
+actual fun platformStartDaemonThread(
+	name: String,
+	action: suspend () -> Unit
+) {
+	val t = Thread { runBlocking { action() } }
+	t.isDaemon = true
+	t.name = name
+	t.start()
+}

core/src/jvmTest/kotlin/cz/vutbr/fit/interlockSim/sim/JvmParityReferenceTest.kt

@@ -69,7 +69,9 @@ class JvmParityReferenceTest : KoinTestBase() {
 				stream.use { factory.createContext(it) }
 			).use { context ->
 				context.getInOuts()
-				context.setMainProcess(ShuntingLoop(context, END_TIME))
+				val loop = ShuntingLoop(context, END_TIME)
+				wireSynchronousDispatcher(context, loop)
+				context.setMainProcess(loop)
 				val reporter = TextReporter(Verbosity.DEFAULT) { output.add(it) }
 				context.addPropertyChangeListener(reporter)
 				context.run()

core/src/jvmTest/kotlin/cz/vutbr/fit/interlockSim/sim/ShuntingLoopRegressionTest.kt

@@ -80,6 +80,7 @@ class ShuntingLoopRegressionTest : KoinTestBase() {
 		// When: Run shunting loop simulation for 60 time units (enough for 1-2 trains)
 		logger.info { "Starting ShuntingLoop regression test (60 time units)" }
 		val shuntingLoop = ShuntingLoop(context, 60L)
+		wireSynchronousDispatcher(context, shuntingLoop)
 		context.setMainProcess(shuntingLoop)
 		context.run()
 
@@ -128,7 +129,9 @@ class ShuntingLoopRegressionTest : KoinTestBase() {
 
 		// When: Run simulation for 30 time units (short test for performance verification)
 		logger.info { "TEST: Creating ShuntingLoop..." }
-		context.setMainProcess(ShuntingLoop(context, 30L))
+		val loop = ShuntingLoop(context, 30L)
+		wireSynchronousDispatcher(context, loop)
+		context.setMainProcess(loop)
 		logger.info { "TEST: ShuntingLoop created, starting simulation..." }
 		val startWallTime = System.currentTimeMillis()
 		context.run()
@@ -159,6 +162,7 @@ class ShuntingLoopRegressionTest : KoinTestBase() {
 
 		// When: Run simulation for 100 time units (enough for 2-3 trains)
 		val shuntingLoop = ShuntingLoop(context, 100L)
+		wireSynchronousDispatcher(context, shuntingLoop)
 		context.setMainProcess(shuntingLoop)
 		context.run()
 

core/src/jvmTest/kotlin/cz/vutbr/fit/interlockSim/sim/TrainCoverageIntegrationTest.kt

@@ -111,7 +111,9 @@ class TrainCoverageIntegrationTest : KoinTestBase() {
 				}
 			)
 
-			ctx.setMainProcess(ShuntingLoop(ctx, 200L))
+			val loop = ShuntingLoop(ctx, 200L)
+			wireSynchronousDispatcher(ctx, loop)
+			ctx.setMainProcess(loop)
 			ctx.run()
 
 			assertThat(endEvents.get(), name = "train end events in extended sim")
@@ -138,7 +140,9 @@ class TrainCoverageIntegrationTest : KoinTestBase() {
 				}
 			)
 
-			ctx.setMainProcess(ShuntingLoop(ctx, 60L))
+			val loop = ShuntingLoop(ctx, 60L)
+			wireSynchronousDispatcher(ctx, loop)
+			ctx.setMainProcess(loop)
 			ctx.run()
 
 			assertThat(trainApproved.get(), name = "trains approved (exercising Front paths)")
@@ -272,7 +276,9 @@ class TrainCoverageIntegrationTest : KoinTestBase() {
 		fun lengthCheckerCheckExercisedThroughSimulation() {
 			val ctx = loadVyhybnaContext()
 
-			ctx.setMainProcess(ShuntingLoop(ctx, 30L))
+			val loop = ShuntingLoop(ctx, 30L)
+			wireSynchronousDispatcher(ctx, loop)
+			ctx.setMainProcess(loop)
 			ctx.run()
 
 			assertThat(ctx.getGraph()).isNotNull()

core/src/jvmTest/kotlin/cz/vutbr/fit/interlockSim/sim/TrainReporterIntegrationTest.kt

@@ -77,7 +77,9 @@ class TrainReporterIntegrationTest : KoinTestBase() {
 	fun trainReporterEnabledPathCoverage() {
 		// ShuntingLoop.ENABLED_REPORT_TYPES includes TRAIN_CONTINUOUS — no extra setup needed
 		loadVyhybnaContext().use { ctx ->
-			ctx.setMainProcess(ShuntingLoop(ctx, 30L))
+			val loop = ShuntingLoop(ctx, 30L)
+			wireSynchronousDispatcher(ctx, loop)
+			ctx.setMainProcess(loop)
 
 			val reportCount = countTrainContinuousEvents(ctx)
 
@@ -102,7 +104,9 @@ class TrainReporterIntegrationTest : KoinTestBase() {
 		// `ShuntingLoop(ctx, 10L)` runs until simulation time 10 (`endTime`),
 		// with at most 2 concurrent trains active at once.
 		loadVyhybnaContext().use { ctx ->
-			ctx.setMainProcess(ShuntingLoop(ctx, 10L))
+			val loop = ShuntingLoop(ctx, 10L)
+			wireSynchronousDispatcher(ctx, loop)
+			ctx.setMainProcess(loop)
 
 			val reportCount = countTrainContinuousEvents(ctx)
 
@@ -170,7 +174,9 @@ class TrainReporterIntegrationTest : KoinTestBase() {
 		// - Lower bound: >= 25 proves ~1 Hz cadence (not spurious single event)
 		// - Upper bound: < 100 (tighter than 300) — would catch hold(0.01) throttle bug
 		loadVyhybnaContext().use { ctx ->
-			ctx.setMainProcess(ShuntingLoop(ctx, 30L))
+			val loop = ShuntingLoop(ctx, 30L)
+			wireSynchronousDispatcher(ctx, loop)
+			ctx.setMainProcess(loop)
 
 			val reportCount = countTrainContinuousEvents(ctx)
 

core/src/jvmTest/kotlin/cz/vutbr/fit/interlockSim/sim/metrics/MetricsIntegrationTest.kt

@@ -16,6 +16,7 @@ import cz.vutbr.fit.interlockSim.context.DefaultSimulationContext
 import cz.vutbr.fit.interlockSim.context.SimulationContext
 import cz.vutbr.fit.interlockSim.context.SimulationContextFactory
 import cz.vutbr.fit.interlockSim.sim.ShuntingLoop
+import cz.vutbr.fit.interlockSim.sim.wireSynchronousDispatcher
 import cz.vutbr.fit.interlockSim.testutil.KoinTestBase
 import cz.vutbr.fit.interlockSim.testutil.TestFixtures
 import cz.vutbr.fit.interlockSim.util.Util
@@ -65,7 +66,9 @@ class MetricsIntegrationTest : KoinTestBase() {
 			}
 		// Initialize dynamic wrapper map (mirrors ShuntingLoopSmokeTest).
 		context.getInOuts()
-		context.setMainProcess(ShuntingLoop(context, endTime))
+		val loop = ShuntingLoop(context, endTime)
+		wireSynchronousDispatcher(context, loop)
+		context.setMainProcess(loop)
 		return context
 	}
 

core/src/nativeMain/kotlin/cz/vutbr/fit/interlockSim/util/PlatformThread.kt

@@ -0,0 +1,25 @@
+package cz.vutbr.fit.interlockSim.util
+
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.DelicateCoroutinesApi
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.newSingleThreadContext
+
+/**
+ * Native (linuxX64) actual: runs [action] on a dedicated background thread via a
+ * single-threaded coroutine dispatcher named [name].
+ *
+ * Daemon semantics match the JVM actual: a Kotlin/Native process exits when `main`
+ * returns regardless of live worker threads, so the driver loop never blocks
+ * process shutdown. The dispatcher is intentionally not closed — it lives for the
+ * driver's lifetime, exactly like the JVM daemon thread.
+ */
+@OptIn(DelicateCoroutinesApi::class, ExperimentalCoroutinesApi::class)
+actual fun platformStartDaemonThread(
+	name: String,
+	action: suspend () -> Unit
+) {
+	val dispatcher = newSingleThreadContext(name)
+	CoroutineScope(dispatcher).launch { action() }
+}