NODEDC_MISSION_CORE/docs/adr/0015-simulation-polygon-qualification-boundary.md

# ADR 0015: Simulation Polygon as a qualification boundary

## Status

Accepted for architecture; SIM S0 qualification returned `GO` on 2026-07-24.
Navigation behavior, safety behavior and real actuator authority are not
accepted.

## Context

Mission Core has proven a K1 observation/archive/perception vertical, but the
perception outputs do not yet have a closed-loop consumer. Adding Gazebo, PX4,
ROS 2 and Nav2 directly to the web process or modeling every experiment as an
observation session would blur product ownership, lifecycle, evidence and
authority.

Replay, physics simulation, a digital twin, HIL and real shadow also have
different causal meaning. A recorded stream cannot react to a hypothetical
command, while a closed-loop world can. Calling both `SimulationRun` would make
reports easy to misuse.

## Decision

1. Polygon is a first-class Mission Core bounded context for autonomy
   qualification and assurance.
2. Mission Core owns scenarios, qualification-run lifecycle, authority policy,
   canonical contracts, provenance, evidence admission, evaluation and reports.
3. Gazebo, PX4 SITL, ROS 2, Nav2, Rerun and datasets are replaceable providers.
4. `QualificationRun` is the umbrella aggregate. Its kinds explicitly separate
   `simulation_closed_loop`, `replay_shadow`,
   `digital_twin_closed_loop`, `controller_in_loop`, `hil` and
   `physical_shadow`.
5. Simulation Orchestrator is the sole process-lifecycle owner. Gazebo and PX4
   do not run inside the Mission Core web process, and the browser has no direct
   PX4 channel.
6. Gazebo `/clock` is authoritative in closed-loop simulation. ROS 2 uses
   simulated time and PX4 uXRCE-DDS time synchronization is disabled for this
   profile.
7. Mission Core uses ENU/FLU. PX4 uses NED/FRD. Exactly one adapter boundary
   converts frames and requires golden tests.
8. The first command boundary permits only rover speed+steering and
   speed+yaw-rate profiles with sequence, TTL, heartbeat, watchdog and
   stop-on-loss behavior. Direct actuator setpoints are rejected.
9. Source-of-record, derived artifacts and presentation state remain separate.
   Reset creates a new immutable run/episode.
10. Ground truth is evaluator-only and is not visible to perception or planning.
11. SIM S0 targets the reviewed Windows 11 worker through a dedicated
    `MissionCore-Sim` WSL2 Ubuntu 24.04 distribution physically under
    `D:\NDC_MISSIONCORE`.
12. SIM S0 does not depend on the existing Docker Desktop runtime. Its WSL
    backend is C-backed and currently serves unrelated co-tenants.
13. S1 uses exact `px4_msgs` directly. The experimental
    `px4-ros2-interface-lib` is not a mandatory S1 dependency.
14. A top-level Polygon UI is gated on accepted contracts and a proven S1
    backend lifecycle with persisted run history.
15. Real actuator authority requires a new decision and physical safety gate.
16. S0 processes run inside an ephemeral loopback-only Linux network namespace.
    Micro XRCE-DDS Agent's UDP wildcard bind is acceptable only inside that
    boundary; no S0 listener may be reachable from the worker LAN or Windows
    host network.

## Consequences

- Perception can be measured by downstream decisions without granting it hidden
  behavior authority.
- Standard planners and future Mission Core planners can be compared on the
  same scenario and metric profiles.
- Replay cannot be presented as closed-loop safety evidence.
- Provider upgrades require explicit compatibility and evidence refresh.
- More up-front domain and artifact work is required before a visual demo.
- The AI worker must satisfy D-only, resource and coexistence constraints before
  installation is accepted.
- Simulation and HIL reduce risk but do not certify the real trike.

## First implementation

The qualification doctor is deliberately read-only:

- `simulation/s0/qualification-profile.yaml` is the accepted S0 stack,
  storage, clock, authority, port and process contract.
- `k1link.simulation.s0` strictly validates that contract and optional
  digest-bound worker evidence.
- `missioncore-sim s0 doctor` inspects the current host without installing,
  starting or modifying anything.
- MISSIONCOR-40 tracks factual worker qualification.

The first target bootstrap also includes `simulation/s0/worker-smoke.sh`. It
creates the reviewed loopback-only namespace, starts only the pinned stock-rover
providers, observes ROS 2 vehicle status and Gazebo clock, requests PX4 shutdown,
checks for owned-process residue and writes D-only factual artifacts. It never
arms the vehicle or sends an actuator command.

`simulation/s0/gazebo_time_control.py` owns the S0 pause/single-step/1×/2× RTF
and resource acceptance probe. `simulation/s0/build_evidence_manifest.py`
admits only exact-profile, D-confined, passing 1×/2× runs into the digest-bound
evidence generation. These scripts are qualification tooling; the S1
Simulation Orchestrator remains the future product lifecycle owner.

The doctor reports `INCOMPLETE` until it is running on the reviewed target with
resolved/accepted pins and all required evidence. On the accepted profile
generation and nine-claim confined evidence set it returned `GO`; it cannot
infer that result from repository state alone.

## S1A implementation

`k1link.simulation.contracts` now defines the first product-owned
`QualificationRun`, provider/authority/artifact provenance, canonical
Ackermann and Differential rover setpoints, and qualification events.
`k1link.simulation.run_store` persists them as an immutable manifest plus
one-file-per-sequence append-only journals. Exclusive creation and file/directory
fsync prevent partially acknowledged records; loading rejects gaps, identity
drift, non-regular records and illegal lifecycle history.

The aggregate derives its current state by replay. Terminal runs cannot accept
new events, commands or artifacts. A restart never silently resumes an active
run: reconciliation terminates it as `failed` with
`orchestrator-recovery-interrupted`. Reset requires a terminal parent and
creates a new linked run/episode. Commands are admitted only for a running
closed-loop virtual run with the current authority generation and bounded
simulation-time TTL. Replay/shadow commands, direct actuator authority and
ungated HIL/controller-in-loop admission fail closed.

This increment proves the local lifecycle/repository contract. It does not yet
own provider processes, transmit a PX4 setpoint, execute heartbeat/watchdog
failsafe behavior, or qualify navigation/safety behavior. The target
orchestrator must place the caller-supplied repository root under the accepted
D-only worker boundary.

## S1B ownership foundation

`k1link.simulation.orchestrator` now owns the application lifecycle through a
transport-neutral worker port. Start and stop requests are persisted with
idempotency identity, one active run owns a worker at a time, and
pause/resume/step/reset cannot bypass run-state validation. Provider start
failure, S0 profile drift, stop residue and restart interruption all become
explicit run events and terminal failures.

`k1link.simulation.process_supervisor` provides the worker-local POSIX ownership
primitive: shell-free argv, dedicated provider PGIDs, run-scoped logs, atomic
process registry, partial-start rollback and ascending shutdown order matching
the accepted S0 dependency graph. `k1link.simulation.worker` binds that
primitive to the exact accepted S0 profile digest and canonical D-only S1 run
artifact and process-runtime layouts.

This is not target-worker acceptance. Provider specifications, loopback network
namespace creation, live readiness probes, restart-safe PID/start-token
reconciliation and Gazebo world-control/PX4 command adapters remain open. The
worker port deliberately fixes ownership semantics without prematurely fixing
the eventual transport.