# 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–46 engineer-days, excluding waits for hardware, external accounts or a
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 committed on the Polygon branch;
- SIM S0 has a strict accepted qualification profile and read-only doctor;
- the dedicated D-only worker distribution has been created and the accepted
  PX4/Gazebo/ROS 2/Nav2 stack has been installed without using Docker;
- PX4 v1.17.0 and the stock Ackermann rover have completed repeated factual
  smoke runs with ROS 2 vehicle status, Gazebo clock and clean shutdown;
- the exact accepted-profile generation has passed pause freeze, one 2 ms
  single-step, 1×/2× speed and structured resource cases;
- all nine digest-bound S0 evidence claims validate and the target doctor
  returns `GO` for profile SHA-256
  `aeecf5005301db230e1340b85215cbbd862b72974a22b8c43767c28be8453e2f`;
- `actuator_authority=false`;
- `navigation_or_safety_accepted=false`.

The doctor reports `GO` only on the matching target with the exact confined
worker evidence. A repository manifest alone remains insufficient.

## 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 accepted line is:

- Windows 11 AI worker;
- dedicated `MissionCore-Sim` WSL2 Ubuntu 24.04 distribution physically on D;
- no Docker dependency in S0, so active shared Docker co-tenants remain untouched;
- ROS 2 Jazzy;
- Gazebo Harmonic;
- PX4 Autopilot v1.17.0;
- matching `px4_msgs` v1.17.0 generation;
- Micro XRCE-DDS Agent v2.4.3;
- Nav2 Jazzy;
- PX4 Gazebo stock rover models.

The exact source commits and package versions are resolved in the profile.
Target installation, PX4 build, DDS telemetry, Nav2/ROS package discovery and
repeated 1×/2× stock-rover evidence have moved every component pin to
`accepted`. A future pin change creates a new profile generation and invalidates
evidence tied to the prior SHA-256.

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:

- the dedicated `MissionCore-Sim` WSL distribution/VHD;
- Docker data and images if a later profile elects to use containers; the S0
  profile explicitly does not;
- 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.

S0 runtime processes execute in a new loopback-only Linux network namespace.
Micro XRCE-DDS Agent v2.4.3 has no address-selection flag and therefore binds
UDP wildcard inside that namespace; the namespace contains only `lo`, so the
effective exposure remains loopback-only. ROS domain 0 is isolated by the same
boundary. This distinction is part of the port evidence and must not be
misreported as a host-wide `127.0.0.1` bind.

The stock rover world declares a 2 ms physics step. S0 pause acceptance permits
zero simulation-time advance; single-step requires exactly +2,000,000 ns and
+1 iteration. Speed factors 1× and 2× are measured over four seconds with a
±20% RTF tolerance. Resource sampling runs every 500 ms with an owned-process
budget of 2 GiB RSS and 800% CPU, at least 8 GiB available WSL memory and the
existing 200 GiB D stop floor. GPU values are recorded as global co-tenant
context and are not misattributed to headless S0.

## 16. Delivery plan

| Phase | Estimate | Exit condition |
| --- | ---: | --- |
| P0 | 2–4 days | Product thesis, SRS, ADR and canonical contracts accepted |
| S0 | 3–5 days | Target compatibility, D-only runtime, exact pins, clock/process/resource evidence |
| S1 | 7–12 days | Stock Ackermann and Differential lifecycle/control/failsafe evidence |
| S2 | 15–25 days | LiDAR/odometry/Nav2 baseline, evaluator and obstacle scenarios |
| S2B | 5–8 days | Representative 30-world BARN pilot |
| S3 | 20–35 days | K1-like virtual sensors and Mission Core perception closed loop |
| S4 | 10–20 days | Canonical replay/shadow adapters and reports |
| S5 | 20–40 days | Attested RAVNOVES00 digital twin |
| S6 | 20–40+ days | Trike model, controller-in-loop/HIL and physical-shadow gate |

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 of the dedicated WSL VHD, sources, builds, caches
  and artifacts;
- confirmation that S0 uses the dedicated D-only WSL and does not use the
  existing C-backed Docker Desktop runtime;
- 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× resource baseline;
- 2× resource baseline;
- explicit `GO`, `INCOMPLETE` 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.
