@@ -0,0 +1,535 @@
# Mission Core Polygon: product definition and system requirements
Status: canonical working SRS, 2026-07-24.
Ops source of truth:
- [MISSIONCOR-38 ](https://ops.nodedc.ru/nodedc/browse/MISSIONCOR-38 ) is the
product epic and original simulation-branch scope.
- [MISSIONCOR-39 ](https://ops.nodedc.ru/nodedc/browse/MISSIONCOR-39 ) is the
canonical, changeable architecture plan.
- [MISSIONCOR-40 ](https://ops.nodedc.ru/nodedc/browse/MISSIONCOR-40 ) is the
active SIM S0 implementation and qualification gate.
This document and ADR 0015 are the repository truth. A material change to run
kinds, authority, clocks, frames, source-of-record, provider boundaries or phase
gates must update the ADR/SRS and MISSIONCOR-39 together.
## 1. Product thesis
Polygon is Mission Core's autonomy qualification and assurance layer. It is not
a simulator embedded for visual effect and it is not a second observation
viewer.
Polygon makes one product promise:
> Given a versioned scenario and qualification profile, Mission Core can run or
> replay the autonomy stack, preserve exact provenance and evidence, explain
> each control/safety decision and compare outcomes without granting undeclared
> authority.
The product value appears in increments:
| Gate | Value |
| --- | --- |
| P0/S0 | Makes the stack installable, inspectable and reproducible rather than an ad hoc lab |
| S1 | Proves Mission Core can own a complete virtual rover run lifecycle |
| S2 | Produces the first useful navigation baseline and comparable safety/latency evidence |
| S3 | Connects Mission Core perception to a closed-loop consumer and exposes product differentiation |
| S4 | Makes recorded real data useful for regression and shadow-policy analysis |
| S5/S6 | Reduces risk before a real vehicle, without claiming real-world safety certification |
The first product-useful baseline is P0 through S2. The current estimate is
27–
resolved worker-access blocker.
## 2. Current truth
The repository's proven vertical remains K1 observation, durable archive,
recorded perception and diagnostic motion evidence through LAB E26. It has not
accepted navigation behavior, safety behavior or real actuator control.
Polygon is now a parallel product branch. As of this document:
- P0 architecture and SRS are being committed;
- SIM S0 has a strict candidate qualification profile and read-only doctor;
- no target-worker S0 evidence has been admitted;
- PX4/Gazebo/ROS 2/Nav2 have not been installed or accepted by this repository;
- no stock rover run has been accepted;
- `actuator_authority=false` ;
- `navigation_or_safety_accepted=false` .
The doctor must report `INCOMPLETE` until exact worker evidence is supplied. A
repository manifest is never enough for a `GO` .
## 3. Goals
### 3.1 Product goals
- Turn perception and planning work into measurable sense-plan-act experiments.
- Compare standard and Mission Core planners against the same versioned inputs.
- Preserve failures, limitations and uncertainty as first-class evidence.
- Reuse the same scenario/run/report concepts across simulation, replay, digital
twin, controller-in-loop, HIL and physical shadow.
- Keep physics, autopilot, middleware, planner and viewer replaceable.
- Create a controlled path toward a future trike without silently widening
authority.
### 3.2 Engineering goals
- Deterministic lifecycle ownership with no orphan simulator processes.
- Exact version, environment, input and artifact provenance.
- Explicit clock-domain and coordinate-frame conversions.
- Fail-closed setpoint validity, TTL, heartbeat, watchdog and loss behavior.
- Append-only run history and digest-bound source/derived artifacts.
- Side-effect-free infrastructure diagnosis before installation.
## 4. Non-goals
The first delivery does not:
- grant real actuator authority;
- expose PX4 directly to the browser;
- use direct actuator setpoints;
- certify Nav2, PX4 or Mission Core as a real-time safety system;
- treat replay as closed-loop evidence;
- import all 300 BARN worlds before a stock-world baseline;
- download complete CODa, JRDB or NCLT collections;
- build a custom physics engine;
- make `px4-ros2-interface-lib` mandatory for S1;
- overload the observation-session model for qualification runs;
- implement a top-level UI before the backend S1 gate.
## 5. Product and system boundaries
### 5.1 Mission Core ownership
Mission Core owns:
- scenario definitions and profile selection;
- qualification-run identity and lifecycle;
- command authority and safety policy;
- canonical state, setpoint, decision and event contracts;
- orchestration of replaceable providers;
- evidence admission, provenance and immutable history;
- evaluation, comparison and qualification reports.
### 5.2 Provider ownership
Providers remain replaceable:
- Gazebo owns simulated world state, sensors, contacts and physics.
- PX4 SITL owns rover control loops, constraints, offboard lifecycle and
autopilot failsafe.
- ROS 2 transports typed telemetry and commands.
- Nav2 supplies the first mature planning/costmap/collision-checking baseline.
- Rerun or another viewer presents derived evidence and never becomes a queue,
orchestrator or source-of-record.
- Dataset adapters expose recorded streams but never pretend alternative
commands changed future recorded observations.
### 5.3 Neighboring Mission Core contexts
- Observation owns real and recorded sensor streams plus perception layers.
- Polygon owns scenarios, qualification runs, decisions, simulated state and
comparisons.
- Missions owns goals and routes that may later target a virtual or real
vehicle.
- Data owns source-of-record, derived artifacts, retention and report access.
Observation `SessionStatus` and its modality model are not extended to describe
simulation. Shared UI components require an explicit data-source contract.
## 6. Target architecture
```text
Mission Core UI
|
Simulation API
|
Simulation Orchestrator
+---- scenario/profile registry
+---- run state machine and authority gate
+---- clock, namespace, port and process ownership
+---- artifact/provenance store and evaluator
|
+---- Gazebo adapter ---- Gazebo world/physics/sensors
+---- PX4 adapter ------- PX4 SITL rover controller/failsafe
+---- ROS 2 adapter ----- Micro XRCE-DDS and canonical topics
+---- planner adapter --- Nav2 or Mission Core planner
+---- viewer adapter ---- canonical state/derived report
```
Gazebo and PX4 never run inside the web process. The browser never owns process
lifecycle or command authority. Losing the browser cannot terminate the only
copy of run state and cannot bypass the server-side authority gate.
## 7. Canonical domain model
### 7.1 Versioned inputs
`ScenarioDefinition` contains identifiers and references for:
- world and deterministic actor placement;
- vehicle profile;
- sensor profile;
- route/goal;
- planner profile;
- fault profile;
- metric profile;
- seed and reproducibility tier.
`VehicleProfile` , `SensorProfile` , `PlannerProfile` , `FaultProfile` and
`MetricProfile` are independently versioned. A run stores the exact resolved
generation and hashes, not only mutable names.
### 7.2 QualificationRun
`QualificationRun` is the umbrella aggregate. `SimulationRun` is not used as
the common type because replay, HIL and physical shadow are not simulations.
Required identity:
- immutable run ID and episode ID;
- run kind;
- scenario/profile generations and hashes;
- Mission Core commit;
- provider versions, commits or image digests;
- host and resource profile;
- seed and reproducibility tier;
- authority profile;
- start/end UTC provenance;
- authoritative clock domain.
Reset creates a new episode/run identity. It never reuses a completed identity
or overwrites artifacts.
### 7.3 Run kinds
| Kind | Commands affect future inputs | Actuator authority |
| --- | --- | --- |
| `simulation_closed_loop` | Yes, through virtual physics | Virtual only |
| `replay_shadow` | No | None |
| `digital_twin_closed_loop` | Yes, through an attested twin | Virtual only |
| `controller_in_loop` | Yes, through a bounded controller interface | Lab-specific |
| `hil` | Yes, with hardware in the loop | Separate gate |
| `physical_shadow` | No | None |
No result may be promoted from one kind to another by changing report wording.
### 7.4 Canonical streams
- `VehicleState` : pose, twist, acceleration, steering/wheel state, estimator
state and source frames.
- `PerceptionWorldState` : occupancy, objects, motion, confidence, unknown and
uncertainty.
- `ControlSetpoint` : profile, sequence, issued time, validity deadline,
speed/steering or speed/yaw-rate and authority scope.
- `SafetyDecision` : allow/slow/stop, reason, active constraint, TTC/clearance
evidence and input generation.
- `QualificationEvent` : lifecycle, collision/contact, reset, deadline miss,
data loss, watchdog, failsafe and evaluator events.
- `QualificationReport` : verdict, metrics, violations, limitations and evidence
links.
## 8. Lifecycle requirements
The minimum lifecycle is:
```text
admitted -> starting -> running <-> paused -> stopping -> completed
| |
+--------------------+-> failed
```
Cancellation is a requested transition, not evidence that processes stopped.
A run reaches a terminal state only after:
- child-process ownership is reconciled;
- stop/failsafe outcome is captured;
- source artifacts are sealed;
- derived indexes are generated or explicitly marked absent;
- the report records the final limitations.
Process shutdown order is explicit and deterministic. Orchestrator shutdown is
last. An orphan process is an S0/S1 failure.
## 9. Clock contract
For `simulation_closed_loop` :
- Gazebo `/clock` is authoritative.
- ROS 2 consumers use `use_sim_time=true` .
- PX4 uXRCE-DDS time synchronization is disabled when Gazebo time is used.
- Canonical timestamps are integer nanoseconds and include their clock domain.
- UTC is provenance only.
- TTL, deadline and watchdog calculations declare whether they use simulation
or monotonic host time.
- Pause, resume, single-step and real-time-factor changes are qualification
cases, not UI-only behavior.
Wall clock must not appear implicitly in planner or safety calculations.
## 10. Coordinate-frame contract
Mission Core navigation uses:
- `map` and `odom` : ENU;
- `base_link` : FLU.
PX4 uses:
- world/local: NED;
- body: FRD.
All PX4 conversion happens at one adapter boundary. Pose, vector, yaw, yaw-rate
and covariance transformations require golden tests. Every canonical message
identifies source and target frame. A frame mismatch fails closed and cannot be
reclassified as planner noise.
## 11. Authority and safety requirements
Until a new physical-control card and formal safety gate:
- `simulation_or_shadow_only=true` ;
- `actuator_authority=false` ;
- `navigation_or_safety_accepted=false` ;
- direct actuator setpoints are rejected;
- supported S1 command profiles are `rover-speed-steering/v1` and
`rover-speed-yaw-rate/v1` ;
- each command carries a monotonic sequence and explicit expiry;
- heartbeat loss, TTL expiry, invalid state, planner timeout or link loss causes
a stop/failsafe transition;
- unknown occupancy never becomes free space by omission;
- ground truth is unavailable to the planner and perception runtime;
- ground truth is separately available to the evaluator.
Nav2 Collision Monitor is an additional software safety layer. It is not a
hard-real-time certified safety controller.
## 12. Evidence and data requirements
### 12.1 Source-of-record
The minimum source set is:
- exact scenario and qualification profiles;
- stack/version lock;
- run manifest and authority profile;
- PX4 ULog;
- Gazebo log or equivalent world-state/contact evidence;
- rosbag2/MCAP for admitted canonical streams;
- factual host/resource and process-lifecycle evidence.
### 12.2 Derived artifacts
Derived data includes:
- normalized metrics;
- evaluator outputs;
- comparison tables;
- Rerun recording;
- qualification report.
Presentation state is not source evidence. Derived artifacts are rebuildable and
must retain input hashes. Source and derived generations are append-only.
### 12.3 Required metrics
Each applicable run reports:
- completion and terminal reason;
- collision/contact count and minimum clearance;
- path length, elapsed simulation time and efficiency;
- route/pose error;
- speed/steering tracking;
- stop time and distance;
- TTC and constraint activation;
- replans and oscillation;
- dropped/late messages and deadline misses;
- stage latency p50/p95/max and queue depth;
- real-time factor;
- CPU, GPU, RAM, VRAM and disk usage.
Inapplicable metrics are explicit, not silently zero.
## 13. Reproducibility
- R0: exact inputs and versions are retained; outcome may vary.
- R1: the same inputs/seed/version lock reproduce the same verdict within
declared tolerances.
- R2: defined metrics remain within accepted tolerance bands.
Bitwise-identical physics is not promised. Comparison is rejected when scenario
schema, metric profile, provider generation or reproducibility tier are
incompatible.
## 14. Upstream baseline
The S0 candidate line is:
- Windows 11 AI worker;
- WSL2 Ubuntu 24.04;
- ROS 2 Jazzy;
- Gazebo Harmonic;
- PX4 Autopilot v1.17.0;
- matching `px4_msgs` v1.17.0 generation;
- Micro XRCE-DDS Agent v2.4.3 candidate;
- Nav2 Jazzy;
- PX4 Gazebo stock rover models.
The exact source commits already resolved in the candidate profile do not become
accepted merely because they are present. ROS/Gazebo package versions and every
candidate build remain pending target-worker qualification.
S1 uses direct exact `px4_msgs` integration. The experimental
`px4-ros2-interface-lib` is evaluated later and is not on the S1 critical path.
## 15. Storage and runtime placement
All mutable worker bytes must be physically placed under
`D:\NDC_MISSIONCORE` , including:
- WSL distribution/VHD;
- Docker data and images;
- sources and build products;
- package/model caches;
- runtime and logs;
- bags, ULog and Gazebo evidence;
- datasets and reports.
The WSL view is `/mnt/d/NDC_MISSIONCORE` . C-drive placement is a blocking
failure. S0 requires at least 300 GiB free before installation and a stop-below
threshold of 200 GiB. Full external datasets are out of S0 scope.
## 16. Delivery plan
| Phase | Estimate | Exit condition |
| --- | ---: | --- |
| P0 | 2–
| S0 | 3–
| S1 | 7–
| S2 | 15–
| S2B | 5–
| S3 | 20–
| S4 | 10–
| S5 | 20–
| S6 | 20–
Implementation cards follow this order:
1. Product SRS and ADR.
2. D-only inventory and stack lock.
3. Clock, frame and authority contracts.
4. Orchestrator lifecycle and artifact store.
5. PX4 stock rover control and failsafe.
6. Nav2 adapter and truth baseline.
7. Evaluator, report and BARN pilot.
8. Virtual K1 and perception.
9. Replay/shadow datasets.
10. RAVNOVES00 twin.
11. Trike, HIL and safety gate.
## 17. SIM S0 acceptance
SIM S0 requires all of the following factual evidence:
- worker inventory;
- physical D-only placement, including WSL and Docker VHD;
- exact component/package pins and licenses;
- one stock PX4 rover launch;
- ROS 2 telemetry;
- authoritative simulation clock;
- pause, resume, single-step and speed-factor behavior;
- clean stop with no orphan processes;
- 1×
- 2×
- explicit `GO` , `PAUSE` or `BLOCKED` report.
The repository profile and doctor implement preflight and evidence admission.
They do not install packages, start processes, open ports or write a target
report.
Run the local read-only preflight:
```bash
uv run missioncore-sim s0 doctor --json
```
An optional evidence manifest uses
`missioncore.simulation-s0-evidence/v1` . Each required claim points to a
confined regular artifact and supplies its SHA-256. The profile SHA-256 must
match the exact candidate generation.
## 18. S1 and S2 acceptance outline
### S1
- Ackermann primary and Differential reference launch from the orchestrator.
- Start, pause, resume, step, reset and stop are server-owned.
- Straight, turn, reverse, deceleration and emergency-stop cases pass.
- TTL, heartbeat, offboard loss and link loss produce a captured safe outcome.
- Pose, speed, steering/controller state and failsafe telemetry are retained.
- Reset creates a new run/episode.
- A repeated seed produces the declared R1 verdict tolerance.
K1, Nav2 and top-level UI do not block S1 backend acceptance.
### S2
- Gazebo LiDAR/odometry feed the ROS 2/Nav2 baseline.
- Ackermann uses MPPI plus Smac Hybrid/Lattice or an explicitly justified
equivalent.
- Static wall, corridor, bypass, narrow passage, no-data, planner timeout and
control-loss scenarios produce comparable reports.
- PX4 waypoint following without obstacle avoidance and Nav2 are measured on
the same profiles.
- A 30-world BARN pilot follows stock-world acceptance; only geometry, maps,
paths and difficulty are imported from the legacy runtime.
## 19. Replay and dataset policy
Recorded datasets support detector, segmentation, tracking, occupancy and
shadow-policy regression. They do not react to alternative commands and cannot
prove a closed-loop avoidance maneuver.
- CODa and JRDB non-commercial/share-alike restrictions prohibit treating them
as unrestricted commercial runtime dependencies.
- NCLT is large and must be admitted by a size/license manifest.
- SCAND supplies social-navigation demonstrations but remains replay evidence.
- RAVNOVES00 first enters as canonical replay/shadow; only S5 may turn an
attested reconstruction into a digital-twin world.
Unknown or unobserved space remains unknown/occupied according to the selected
safety policy.
## 20. UI gate
Polygon is planned as the seventh top-level bounded context:
```text
Center | Fleet | Observation | Polygon | Missions | Data | System
```
Top-level UI implementation begins only after:
1. this SRS and the clock/frame/authority contracts are accepted;
2. S1 backend lifecycle is proven;
3. run history is persisted independently of a browser session.
The future UI may present Scenarios, Run, Control, History, Compare and Report.
It cannot own provider processes, bypass authority checks or write directly to
PX4.
## 21. Change control
A material change requires:
1. an ADR/SRS diff;
2. an update to MISSIONCOR-39;
3. migration and compatibility notes;
4. new or updated tests;
5. fresh evidence before a previously accepted gate remains accepted.
No checkbox is closed from intent alone. A commit plus factual validation or
admitted evidence is required.
DCCONSTRUCTIONS