Goal 10 parent PR

.github/workflows/gradle-java21.yml

@@ -72,7 +72,7 @@ jobs:
       env:
         GITHUB_ACTOR: ${{ github.actor }}
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      run: ./gradlew :desktop-ui:ktlintCheck :core:ktlintCheck --no-daemon --stacktrace
+      run: ./gradlew :desktop-ui:ktlintCheck :core:ktlintCheck :dispatcher-agent:ktlintCheck --no-daemon --stacktrace
 
     - name: Run unit tests
       timeout-minutes: 10
@@ -111,6 +111,11 @@ jobs:
           core/build/test-results/jvmTest
           core/build/test-results/integrationTest
           core/build/reports/jacoco/jvmTest/jacocoTestReport.xml
+          dispatcher-agent/build/classes/kotlin/main
+          dispatcher-agent/build/classes/kotlin/test
+          dispatcher-agent/build/test-results/test
+          dispatcher-agent/build/test-results/integrationTest
+          dispatcher-agent/build/reports/jacoco/test/jacocoTestReport.xml
         retention-days: 7
         if-no-files-found: error
 

.github/workflows/sonarqube.yml

@@ -122,6 +122,7 @@ jobs:
         ./gradlew sonar \
           -x :desktop-ui:test -x :desktop-ui:integrationTest -x :desktop-ui:jacocoTestReport \
           -x :core:jvmTest -x :core:integrationTest -x :core:jacocoTestReport \
+          -x :dispatcher-agent:test -x :dispatcher-agent:integrationTest -x :dispatcher-agent:jacocoTestReport \
           -Dsonar.host.url=https://sonarcloud.io \
           -Dsonar.organization=$SONAR_ORGANIZATION \
           -Dsonar.token=$SONAR_TOKEN \

CLAUDE.md

@@ -472,6 +472,7 @@ View build status: [GitHub Actions](https://github.com/bedaHovorka/interlockSim/
 - `CZECH_RAILWAY_TERMINOLOGY.md` - Czech terminology verification and translation guide (373 lines)
 - `TRAIN_PASSIVATION_FIX.md` - Train physics passivation fix (Issue #291)
 - `KOIN_SCOPE_LIFECYCLE_TESTS.md` - Koin scope lifecycle test documentation (Issue #220)
+- `GOAL_10_SP3_1_LLM_MODEL_EVALUATION.md` - LLM model comparison for the Goal 10 DISPATCHER agent (Issue #534, SP3.1; TRAIN agents are algorithmic-only, never LLM)
 
 ## Known Issues
 

Dockerfile

@@ -70,6 +70,7 @@ COPY --chown=builder:builder detekt-strict.yml /build/interlockSim/
 COPY --chown=builder:builder .editorconfig /build/interlockSim/
 COPY --chown=builder:builder core/build.gradle.kts /build/interlockSim/core/
 COPY --chown=builder:builder core-test/build.gradle.kts /build/interlockSim/core-test/
+COPY --chown=builder:builder dispatcher-agent/build.gradle.kts /build/interlockSim/dispatcher-agent/
 COPY --chown=builder:builder desktop-ui/build.gradle.kts /build/interlockSim/desktop-ui/
 
 # All subsequent Gradle commands run as the builder user.
@@ -97,6 +98,7 @@ RUN --mount=type=cache,target=/home/builder/.gradle/caches,id=app-gradle-v2,uid=
 COPY --chown=builder:builder desktop-ui/src/ /build/interlockSim/desktop-ui/src/
 COPY --chown=builder:builder core/src/ /build/interlockSim/core/src/
 COPY --chown=builder:builder core-test/src/ /build/interlockSim/core-test/src/
+COPY --chown=builder:builder dispatcher-agent/src/ /build/interlockSim/dispatcher-agent/src/
 
 # Layer 5: Compile and package with cache mount (no tests).
 # Tests are decoupled from the app image build and run in the separate

build.gradle.kts

@@ -67,11 +67,11 @@ val checkKdisco by tasks.registering {
 // ===========================================
 
 tasks.register("test") {
-    dependsOn(":core:jvmTest", ":desktop-ui:test")
+    dependsOn(":core:jvmTest", ":desktop-ui:test", ":dispatcher-agent:test")
 }
 
 tasks.register("integrationTest") {
-    dependsOn(":core:integrationTest", ":desktop-ui:integrationTest")
+    dependsOn(":core:integrationTest", ":desktop-ui:integrationTest", ":dispatcher-agent:integrationTest")
 }
 
 listOf(
@@ -101,19 +101,21 @@ sonar {
         property("sonar.projectName", "interlockSim - Railway Interlocking Simulator")
         property("sonar.projectVersion", version.toString())
 
-        // Source and test paths (desktop-ui + :core KMP subproject).
+        // Source and test paths (desktop-ui + :core KMP subproject + :dispatcher-agent).
         // Kept in sync with sonar-project.properties (used for local sonar-scanner runs).
         property(
             "sonar.sources",
             "desktop-ui/src/main/kotlin,core/src/commonMain/kotlin," +
-                "core/src/jvmMain/kotlin,core/src/nativeMain/kotlin",
+                "core/src/jvmMain/kotlin,core/src/nativeMain/kotlin," +
+                "dispatcher-agent/src/main/kotlin",
         )
         property(
             "sonar.tests",
-            "desktop-ui/src/test/kotlin,core/src/commonTest/kotlin,core/src/jvmTest/kotlin",
+            "desktop-ui/src/test/kotlin,core/src/commonTest/kotlin,core/src/jvmTest/kotlin," +
+                "dispatcher-agent/src/test/kotlin",
         )
-        property("sonar.java.binaries",  "desktop-ui/build/classes/kotlin/main,core/build/classes/kotlin/jvm/main")
-        property("sonar.java.test.binaries", "desktop-ui/build/classes/kotlin/test,core/build/classes/kotlin/jvm/test")
+        property("sonar.java.binaries",  "desktop-ui/build/classes/kotlin/main,core/build/classes/kotlin/jvm/main,dispatcher-agent/build/classes/kotlin/main")
+        property("sonar.java.test.binaries", "desktop-ui/build/classes/kotlin/test,core/build/classes/kotlin/jvm/test,dispatcher-agent/build/classes/kotlin/test")
 
         property("sonar.java.source", javaVersion)
         property("sonar.java.target", javaVersion)
@@ -125,13 +127,16 @@ sonar {
             "desktop-ui/build/test-results/test," +
                 "desktop-ui/build/test-results/integrationTest," +
                 "core/build/test-results/jvmTest," +
-                "core/build/test-results/integrationTest",
+                "core/build/test-results/integrationTest," +
+                "dispatcher-agent/build/test-results/test," +
+                "dispatcher-agent/build/test-results/integrationTest",
         )
         property(
             "sonar.coverage.jacoco.xmlReportPaths",
             listOf(
                 file("desktop-ui/build/reports/jacoco/test/jacocoTestReport.xml"),
                 file("core/build/reports/jacoco/jvmTest/jacocoTestReport.xml"),
+                file("dispatcher-agent/build/reports/jacoco/test/jacocoTestReport.xml"),
             ).joinToString(",") { it.absolutePath },
         )
 
@@ -161,6 +166,7 @@ tasks.named("sonar") {
     dependsOn(
         ":desktop-ui:test", ":desktop-ui:integrationTest", ":desktop-ui:jacocoTestReport",
         ":core:jvmTest", ":core:integrationTest", ":core:jacocoTestReport",
+        ":dispatcher-agent:test", ":dispatcher-agent:integrationTest", ":dispatcher-agent:jacocoTestReport",
     )
 }
 
@@ -175,18 +181,21 @@ val jacocoAggregatedReport by tasks.registering(JacocoReport::class) {
     dependsOn(
         ":core:jvmTest", ":core:integrationTest",
         ":desktop-ui:test", ":desktop-ui:integrationTest",
+        ":dispatcher-agent:test", ":dispatcher-agent:integrationTest",
     )
 
     executionData.setFrom(
         fileTree("core/build").include("jacoco/*.exec"),
         fileTree("desktop-ui/build").include("jacoco/*.exec"),
+        fileTree("dispatcher-agent/build").include("jacoco/*.exec"),
     )
     sourceDirectories.setFrom(
-        files("core/src/commonMain/kotlin", "core/src/jvmMain/kotlin", "desktop-ui/src/main/kotlin")
+        files("core/src/commonMain/kotlin", "core/src/jvmMain/kotlin", "desktop-ui/src/main/kotlin", "dispatcher-agent/src/main/kotlin")
     )
     classDirectories.setFrom(
         fileTree("core/build/classes/kotlin/jvm/main"),
         fileTree("desktop-ui/build/classes/kotlin/main"),
+        fileTree("dispatcher-agent/build/classes/kotlin/main"),
     )
 
     reports {

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
 	 */