SP0.13a (#749): gate findNextReservationTarget on reservation-eligibility (~9% fast-sim win)

[bedaHovorka]

Closes #749.

Split out of #738, which is now closed as not-reproducible — the claimed 0.2 s → 0.6 s regression does
not exist in any release build (see the close-out
for the full bisect). What the investigation did find is this: a real, measurable ~9% of fast-sim wall
time spent on graph searches whose results are thrown away.

The problem

ShuntingLoop.toBlockInputObservation resolved BlockInputObservation.toSeparatorName by calling
PathReservationService.findNextReservationTarget(to) for every block input on every tick — including
inputs that provably cannot take a forward reservation.

That call is a BFS (findNextSemaphoresVia) plus a full topological-path enumeration per candidate
(isPathAvailable → findAllTopologicalPaths). Measured on vyhybna, example shuntingLoop 300:

findNextReservationTarget calls	906
...discarded unread by the dispatcher	892 (98.5%)
cost	30.3 ms of 342 ms (~9%)

RuleBasedDispatcher.checkInput already returns null for exactly those inputs — FREE -> null,
!isApproachingThisInput -> null, pathAlreadyExtendedBeyond -> null. The value was computed and then
dropped on the floor.

The fix

Gate the search on eligibility. The three facts it needs are already computed a few lines above, so the gate
costs nothing:

val canReserveForward =
    !pathAlreadyExtendedBeyond && (isApproachingThisInput || pathSetUpTowardThisInput)
val toSeparatorName =
    if (canReserveForward) pathReservationService.findNextReservationTarget(to)?.let(::nameOf) else null

Sensor-port contract change (deliberate, documented)

This narrows the BlockInputObservation contract: toSeparatorName is populated only where a forward
reservation is possible, and is null elsewhere without the search having run.

For RuleBasedDispatcher this is behaviour-preserving by construction. For a future LLM dispatcher the
distinction matters, so it is now spelled out in BlockInputObservation's KDoc: a null means "no
forward-reservation target applies", not "the search found nothing" — a dispatcher must not read it as
evidence that the track ahead is occupied. Both cases call for the same response anyway (no reservation this
tick).

Results

Native linuxX64 release, example shuntingLoop 300, median of 7:

build	wall
tip before fix	341 ms
this PR	318 ms
SP0.4 c3eb0f66 (pre-seam baseline)	307–329 ms

The seam's per-tick overhead is now back inside baseline noise.

Golden output is byte-for-byte identical — 90/90 event lines, 5 trains, 211.1 s sim time.

Tests

New ShuntingLoopReservationTargetLazinessTest (:core, @Tag("integration-test")) locks the contract:
no non-eligible input may carry a toSeparatorName, and a FREE input never carries one. Verified to
fail 2/2 without the gate (k1->doA1=A resolves), and pass with it.

gate	result
:core:jvmTest	2194 ✅
:core:integrationTest	725 ✅
:core:heavyTest (required — touches sim/)	1001 ✅
:dispatcher-agent:test	51 ✅
:desktop-ui:test	650 ✅
:desktop-ui:integrationTest	247 ✅
checkCoreCommonMainPurity / detekt / ktlintCheck	✅

0 failures across all suites.

Not in this PR

The investigation found that ~60–70% of fast-sim wall time is kDisco RKF45 continuous integration
(1.85M Motor.derivatives() calls/run, caused by dtMax = 1e-3 acting as the event-detection resolution).
That is a much larger and much riskier change — filed as #750 (model side) and
kdisco#67 (engine side). Also spawned: #751, #752, #753.

🤖 Generated with Claude Code

[bedaHovorka]

@copilot : some tips for clean code, please fix it

[Copilot]

@copilot : some tips for clean code, please fix it

Fixed in 2fcb2f5: I extracted the reservation-target eligibility/lookup into a small helper in ShuntingLoop, so toBlockInputObservation() stays cleaner without changing behavior.

[bedaHovorka]

oK