Skip to content

SP0.9: Sim-thread applier draining ActuatorCommandQueue via actuator ports #731

Description

@bedaHovorka

Sub-issue of #535 (SP0 Refactor)

Objective

Drain ActuatorCommandQueue (SP0.8) on the kDisco sim thread and apply each
DispatchDecision through the SP0.6 actuator ports (NetworkActuatorPort,
TrainActuatorPort). All simulation mutation must stay on the sim thread.

Required first deliverable (gate before implementation)

Per spec §5, before writing the applier, post a short design-note PR comment on this
issue choosing between the two candidate mechanisms and answering:

  • Mechanism choice: (1) a kDisco Process applier in :dispatcher-agent,
    activated at sim startup via Koin/ExampleRegistry wiring, adding no hook in
    :core (preferred) — or (2) an additive control-step listener, interface in
    :core / implementation in :dispatcher-agent, only if (1) proves infeasible in
    kDisco, and only as a generic observer hook (never dispatcher logic in :core).
  • How the applier is activated on the kDisco thread at sim startup without a :core
    hook.
  • How the driver signals "command available" cross-thread in kDisco (or why a
    polling applier is acceptable).
  • How DispatchObservation (SP0.7) is built from SimulationSnapshot + the
    unapproved-train queue without exposing live mutable handles to the policy.
  • The exact DispatchDecision subtypes this slice introduces vs. those deferred to
    SP2b.1: Dispatcher interface + DispatchDecision (core/commonMain) #556 (SP2b.1).

This gate exists so the largest of the SP0.5 refactors doesn't land with an
under-designed concurrency seam.

Scope

  • Applier component draining the queue and applying via actuator ports, per the
    chosen mechanism above.

Tests

  • Concurrency: assert actuator calls execute on the sim thread (thread-identity
    assertion); assert no sim-state mutation originates from the driver thread.

Depends on

SP0.8.

Design context: docs/specs/2026-07-08-544-sp05-drive-loop-design.md §3.3, §5,
§7. Full context: #544.

Metadata

Metadata

Labels

agentGoal 10 agent runtime (:agent module)goal-10LLM Dispatchersub-taskSub-task of a parent goal/milestone issue

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions