83 lines
3.9 KiB
Markdown
83 lines
3.9 KiB
Markdown
# 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.
|