fix(ci): move flaky controlled-loop overhead check from JUnit gate to JMH

`:core:integrationTest` failed on run 29165254178 (725 tests, 1 failed).
The failure was DefaultSimulationContextControllerTest.controlledLoopOverheadIsNegligible,
a wall-clock microbenchmark living inside the CI correctness gate: it timed one
300s ShuntingLoop run per arm and asserted the ratio was < 5%. It measured 5.33%.

It could not have held up. One sample per arm, no JIT warmup (the baseline arm ran
first and absorbed it, biasing the ratio negative, so it passed for a reason unrelated
to the property it claimed to test), and a 5% threshold on a shared runner whose
CPU-steal variance far exceeds 5%.

Note TwoTrainConcurrencyTest passed 150/150 in that run and is not implicated; the
simulation is a single-threaded kDisco discrete-event loop with a seeded RNG, so there
is no race here to serialize.

- Delete the wall-clock assertion. The class keeps its four deterministic tests
  (throttle invoked per event, non-negative deltas, StopSimulation propagates,
  awaitIfPaused called), which is what a correctness gate should assert.

- Add ControlledLoopOverheadBenchmark to the existing :desktop-ui JMH harness, with
  two independently reported arms instead of one fragile ratio. Only ctx.run(controller)
  is timed; context construction sits in @setup(Level.Invocation). Mode is SingleShotTime:
  the payload is a single-use, millisecond-scale run, and under AverageTime the resulting
  context churn collides Koin scope ids, since DefaultSimulationContext derives its scope
  id from a (non-unique) identity hash code.

  Measured: baseline 0.699 +/- 0.103 ms/op, with-controller 0.685 +/- 0.062 ms/op.
  Indistinguishable -- the hook overhead is below the noise floor, so the original
  claim was true; only the instrument was broken.

- Fix a latent order-dependent bug in TwoTrainConcurrencyTest found en route. It matched
  train names by substring, and Train.countValue is a process-global counter that is never
  reset, so once names reach two digits "Train #1" matches "Train #12". Now compares
  extracted whole tokens and indexes by identity rather than List.indexOf.

Verified: :core:integrationTest 724/724 (was 725/1 failed), :core:jvmTest 2194/2194,
:desktop-ui:test + integrationTest green, detekt + ktlintCheck clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: bedaHovorka

core/src/jvmTest/kotlin/cz/vutbr/fit/interlockSim/context/DefaultSimulationContextControllerTest.kt

@@ -13,7 +13,6 @@ import assertk.assertThat
 import assertk.assertions.isEqualTo
 import assertk.assertions.isGreaterThan
 import assertk.assertions.isGreaterThanOrEqualTo
-import assertk.assertions.isLessThan
 import cz.vutbr.fit.interlockSim.sim.ShuntingLoop
 import cz.vutbr.fit.interlockSim.testutil.FakeSimulationController
 import cz.vutbr.fit.interlockSim.testutil.KoinTestBase
@@ -187,41 +186,18 @@ class DefaultSimulationContextControllerTest : KoinTestBase() {
 		assertThat(controller.awaitCalls).isGreaterThanOrEqualTo(1)
 	}
 
-	// ── Overhead test ─────────────────────────────────────────────────────────
-
-	/**
-	 * Verifies that the controlled loop overhead (FakeSimulationController with no sleep)
-	 * is less than 5% compared to the [NoOpSimulationController] baseline.
-	 *
-	 * Both runs use a 300s ShuntingLoop at maximum speed.  The FakeSimulationController
-	 * does nothing in [throttle] and [awaitIfPaused], so any overhead is purely from the
-	 * additional method dispatch and bookkeeping in the `beforeEvent` hook.
-	 */
-	@Test
-	@Timeout(120, unit = TimeUnit.SECONDS)
-	@DisplayName("controlled loop overhead vs NoOpSimulationController is < 5%")
-	fun controlledLoopOverheadIsNegligible() {
-		// Baseline: NoOpSimulationController (zero overhead by definition)
-		val baselineNs = System.nanoTime()
-		loadShuntingLoop(300L).use { ctx ->
-			ctx.run(NoOpSimulationController)
-		}
-		val baselineMs = (System.nanoTime() - baselineNs) / 1_000_000.0
-
-		// With FakeSimulationController that does nothing (no sleep)
-		val fakeController = FakeSimulationController()
-		val withLoopNs = System.nanoTime()
-		loadShuntingLoop(300L).use { ctx ->
-			ctx.run(fakeController)
-		}
-		val withLoopMs = (System.nanoTime() - withLoopNs) / 1_000_000.0
-
-		val overheadPct = (withLoopMs - baselineMs) / baselineMs * 100.0
-		logger.info {
-			"Controlled loop overhead: ${"%.2f".format(overheadPct)}% " +
-				"(baseline=${"%.1f".format(baselineMs)}ms, withLoop=${"%.1f".format(withLoopMs)}ms, " +
-				"throttleCalls=${fakeController.throttleCalls})"
-		}
-		assertThat(overheadPct).isLessThan(5.0)
-	}
+	// ── Overhead ──────────────────────────────────────────────────────────────
+	//
+	// Controlled-loop overhead is a *performance* claim and is measured by
+	// `ControlledLoopOverheadBenchmark` in `desktop-ui/src/jmh`, not here.
+	//
+	// It previously lived in this class as `controlledLoopOverheadIsNegligible`,
+	// which timed two single ShuntingLoop runs and asserted the wall-clock ratio
+	// was < 5%. That is not a property a shared CI runner can honour: one sample
+	// per arm, no JIT warmup (the baseline arm ran first and absorbed it, biasing
+	// the ratio negative), and runner CPU-steal variance well above the 5%
+	// threshold. It failed CI at 5.33% on run 29165254178.
+	//
+	// Run the benchmark with:
+	//   ./gradlew :desktop-ui:jmh -Pjmh.includes='ControlledLoopOverhead'
 }

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

@@ -138,13 +138,26 @@ class TwoTrainConcurrencyTest : KoinTestBase() {
 
 		// Per-train: each train's TRAIN_APPROVED must precede its own "ends" event.
 		// Trains may run sequentially, so global ordering across both trains is not required.
+		//
+		// Train names come from a process-global counter that is never reset (Train.countValue),
+		// so by the time this test runs the numbers may be multi-digit. Names must therefore be
+		// compared as extracted whole tokens: a substring test would match "Train #1" inside
+		// "Train #12". Likewise, positions must come from withIndex() rather than List.indexOf(),
+		// which returns the first *equal* LogEntry rather than this one.
 		val trainNameRegex = Regex("""Train #\d+""")
+
+		fun LogEntry.trainName(): String? = trainNameRegex.find(message)?.value
+
+		val indexOfEntry: (LogEntry) -> Int = { target ->
+			log.withIndex().first { (_, entry) -> entry === target }.index
+		}
+
 		for (approvalEntry in approvedEntries) {
-			val trainName = trainNameRegex.find(approvalEntry.message)?.value ?: continue
-			val approvalIdx = log.indexOf(approvalEntry)
-			val endsEntry = endsEntries.firstOrNull { it.message.contains(trainName) }
+			val trainName = approvalEntry.trainName() ?: continue
+			val approvalIdx = indexOfEntry(approvalEntry)
+			val endsEntry = endsEntries.firstOrNull { it.trainName() == trainName }
 			requireNotNull(endsEntry) { "No 'ends' event found for $trainName" }
-			val endsIdx = log.indexOf(endsEntry)
+			val endsIdx = indexOfEntry(endsEntry)
 			assertThat(endsIdx).isGreaterThan(approvalIdx)
 		}
 	}

desktop-ui/src/jmh/kotlin/cz/vutbr/fit/interlockSim/benchmarks/ControlledLoopOverheadBenchmark.kt

@@ -0,0 +1,195 @@
+/* Brno University of Technology
+ * Faculty of Information Technology
+ *
+ * BSc Thesis  2006/2007
+ *
+ * Railway Interlocking Simulator - Performance Benchmarks
+ *
+ * Bedrich Hovorka
+ */
+package cz.vutbr.fit.interlockSim.benchmarks
+
+import cz.vutbr.fit.interlockSim.context.DefaultSimulationContext
+import cz.vutbr.fit.interlockSim.context.NoOpSimulationController
+import cz.vutbr.fit.interlockSim.context.SimulationContextFactory
+import cz.vutbr.fit.interlockSim.context.SimulationController
+import cz.vutbr.fit.interlockSim.di.interlockSimModule
+import cz.vutbr.fit.interlockSim.sim.ShuntingLoop
+import org.koin.core.context.startKoin
+import org.koin.core.context.stopKoin
+import org.koin.java.KoinJavaComponent
+import org.openjdk.jmh.annotations.Benchmark
+import org.openjdk.jmh.annotations.BenchmarkMode
+import org.openjdk.jmh.annotations.Fork
+import org.openjdk.jmh.annotations.Level
+import org.openjdk.jmh.annotations.Measurement
+import org.openjdk.jmh.annotations.Mode
+import org.openjdk.jmh.annotations.OutputTimeUnit
+import org.openjdk.jmh.annotations.Scope
+import org.openjdk.jmh.annotations.Setup
+import org.openjdk.jmh.annotations.State
+import org.openjdk.jmh.annotations.TearDown
+import org.openjdk.jmh.annotations.Warmup
+import org.openjdk.jmh.infra.Blackhole
+import java.io.InputStream
+import java.util.concurrent.TimeUnit
+
+/**
+ * Measures the cost of the controlled simulation loop in [DefaultSimulationContext.run].
+ *
+ * `run(controller)` invokes [SimulationController.throttle] and
+ * [SimulationController.awaitIfPaused] from the `beforeEvent` hook on every simulation
+ * event.  The question this benchmark answers is: how much does that hook cost when the
+ * controller does nothing at all?
+ *
+ * Two arms, reported independently rather than as a ratio:
+ *
+ * - [baselineNoOpController] passes [NoOpSimulationController], the `object` singleton.
+ *   Being a singleton it is monomorphic at the call site, so the JIT can devirtualize and
+ *   inline the empty bodies away.
+ * - [withBenchmarkController] passes a fresh [BenchmarkController], a distinct class whose
+ *   method bodies are equally empty.
+ *
+ * The delta between the two arms is therefore the real dispatch/bookkeeping cost of the
+ * hook, and it is exactly the asymmetry that the JUnit test which used to live in
+ * `DefaultSimulationContextControllerTest` was silently measuring.
+ *
+ * ## Why this is a benchmark and not a test
+ *
+ * This measurement used to be a JUnit assertion (`controlledLoopOverheadIsNegligible`),
+ * timing one run of each arm with [System.nanoTime] and asserting the wall-clock ratio was
+ * below 5%.  That cannot work on a shared CI runner: a single sample per arm, no JIT
+ * warmup — the baseline arm ran first and absorbed it, biasing the ratio negative — and
+ * runner CPU-steal variance far exceeding the 5% threshold.  It failed CI at 5.33%.
+ * JMH supplies the forks, warmup and measurement iterations that make the number mean
+ * something.  There is no threshold assertion here; read the numbers.
+ *
+ * ## Why SingleShotTime
+ *
+ * The payload is one whole simulation run against a single-use context, so each invocation
+ * needs a freshly built [DefaultSimulationContext]. Under [Mode.AverageTime] JMH drives tens
+ * of thousands of invocations per iteration, and that context churn hits a hard limit:
+ * [DefaultSimulationContext] derives its Koin scope id from an identity hash code
+ * (`platformIdentityCode(this)`), which is not unique, so at that volume ids collide and Koin
+ * throws `ScopeAlreadyCreatedException`. [Mode.SingleShotTime] measures one full run per
+ * invocation and keeps the number of contexts in the hundreds, which is both the honest shape
+ * for a millisecond-scale payload and well clear of the collision threshold.
+ *
+ * Run with:
+ * ```
+ * ./gradlew :desktop-ui:jmh -Pjmh.includes='ControlledLoopOverhead'
+ * ```
+ *
+ * @see DefaultSimulationContext.run
+ * @see NoOpSimulationController
+ */
+@State(Scope.Benchmark)
+@BenchmarkMode(Mode.SingleShotTime)
+@OutputTimeUnit(TimeUnit.MILLISECONDS)
+@Warmup(iterations = 10)
+@Measurement(iterations = 20)
+@Fork(value = 3)
+open class ControlledLoopOverheadBenchmark {
+	/**
+	 * Simulation end time, in simulated seconds.
+	 *
+	 * The retired JUnit test used 300s.  60s is used here to keep total benchmark
+	 * wall-time reasonable across 3 forks x (3 warmup + 5 measurement) iterations; the
+	 * per-event hook cost this benchmark isolates does not depend on the horizon.
+	 */
+	private val simulationEndTime: Long = 60L
+
+	@Setup(Level.Trial)
+	fun startDi() {
+		stopKoin() // Clean slate — a previous trial in this JVM may have left Koin running.
+		startKoin { modules(interlockSimModule) }
+	}
+
+	@TearDown(Level.Trial)
+	fun stopDi() {
+		stopKoin()
+	}
+
+	/**
+	 * Railway network XML stream. Uses vyhybna.xml (shunting loop), the standard test network.
+	 */
+	private fun railwayNetworkXml(): InputStream =
+		javaClass.getResourceAsStream("/cz/vutbr/fit/interlockSim/resource/vyhybna.xml")
+			?: error("Railway network XML not found on the benchmark classpath")
+
+	/**
+	 * The context under measurement, rebuilt before every invocation.
+	 *
+	 * A [DefaultSimulationContext] is single-use — [DefaultSimulationContext.run] consumes it —
+	 * so each invocation needs a fresh one. It is built in [prepareContext] rather than inside
+	 * the `@Benchmark` body so that XML parsing and context construction, which cost far more
+	 * than the per-event hook under test, stay *outside* the timed region. JMH excludes
+	 * [Level.Invocation] fixture time from the measurement.
+	 */
+	private var context: DefaultSimulationContext? = null
+
+	@Setup(Level.Invocation)
+	fun prepareContext() {
+		val factory =
+			KoinJavaComponent.get<SimulationContextFactory>(SimulationContextFactory::class.java)
+		val ctx = railwayNetworkXml().use { factory.createContext(it) } as DefaultSimulationContext
+		ctx.getInOuts()
+		ctx.setMainProcess(ShuntingLoop(ctx, simulationEndTime))
+		context = ctx
+	}
+
+	@TearDown(Level.Invocation)
+	fun releaseContext() {
+		context?.close()
+		context = null
+	}
+
+	/**
+	 * A [SimulationController] that does nothing, as a distinct class rather than a singleton.
+	 *
+	 * Deliberately not an `object`: the point of the second arm is to present the call site
+	 * with an implementation the JIT cannot assume is the only one.
+	 */
+	private class BenchmarkController : SimulationController {
+		override suspend fun awaitIfPaused() {
+			// No-op: never paused.
+		}
+
+		override fun throttle(simDeltaSeconds: Double) {
+			// No-op: no wall-clock pacing.
+		}
+
+		override fun isPaused(): Boolean = false
+
+		override fun pollStepEvent(): Boolean = false
+
+		override fun pollStepTime(): Double? = null
+
+		override fun requestPause() {
+			// No-op: benchmark runs headless.
+		}
+	}
+
+	/**
+	 * Baseline: the controlled loop driven by the [NoOpSimulationController] singleton.
+	 */
+	@Benchmark
+	fun baselineNoOpController(blackhole: Blackhole) {
+		val ctx = requireNotNull(context) { "prepareContext() must run before the benchmark body" }
+		ctx.run(NoOpSimulationController)
+		blackhole.consume(ctx)
+	}
+
+	/**
+	 * The controlled loop driven by a non-singleton no-op controller.
+	 *
+	 * The difference against [baselineNoOpController] is the hook's dispatch and bookkeeping
+	 * cost per simulation event.
+	 */
+	@Benchmark
+	fun withBenchmarkController(blackhole: Blackhole) {
+		val ctx = requireNotNull(context) { "prepareContext() must run before the benchmark body" }
+		ctx.run(BenchmarkController())
+		blackhole.consume(ctx)
+	}
+}