# ADR 0015: Simulation Polygon as a qualification boundary

## Status

Accepted for architecture and SIM S0 implementation 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/WSL2 AI worker with all mutable bytes
    physically under `D:\NDC_MISSIONCORE`.
12. S1 uses exact `px4_msgs` directly. The experimental
    `px4-ros2-interface-lib` is not a mandatory S1 dependency.
13. A top-level Polygon UI is gated on accepted contracts and a proven S1
    backend lifecycle with persisted run history.
14. Real actuator authority requires a new decision and physical safety gate.

## 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 first implementation is deliberately read-only:

- `simulation/s0/qualification-profile.yaml` is the candidate 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 doctor reports `INCOMPLETE` until it is running on the reviewed target with
resolved/accepted pins and all required evidence. It cannot infer `GO` from the
repository state.