# ADR 0017: Provider-neutral simulation and Unreal evaluation

## Status

Accepted for architecture on 2026-07-25. The provider contract is implemented
on the Polygon branch. Gazebo remains the accepted regression baseline. No
Unreal integration, Unreal runtime profile or choice between native Unreal,
CARLA and Project AirSim is accepted by this decision.

## Context

The first Polygon vertical proved that Mission Core can own a virtual Ackermann
run, display canonical ENU/FLU state in React, persist evidence and deliver
bounded virtual-only rover commands through PX4. That proof used one concrete
stack: Gazebo Harmonic, PX4 SITL, ROS 2 and Micro XRCE-DDS.

Treating that stack as the product architecture would make later work expensive:

- a realistic vehicle, road surface, terrain and sensor model may be easier to
  build and inspect in Unreal;
- reconstructed Gaussian scenes are primarily visual evidence and do not by
  themselves supply collision, friction, road or navigation geometry;
- native Unreal, CARLA and Project AirSim have different vehicle, sensor,
  controller, platform and lifecycle assumptions;
- a browser cannot and should not execute the full physics/autopilot stack;
- replacing Gazebo must not replace Mission Core run identity, authority,
  evidence, UI or evaluator contracts.

The choice is therefore not “Gazebo or Unreal for the whole product.” It is
which worker-side provider profile is appropriate for each qualification case.

## Decision

1. Mission Core remains simulation-provider neutral. A worker publishes an
   exact `missioncore.simulation-provider-profile/v1` before it may be used by
   the browser or gateway.
2. A provider profile declares logical providers, roles, capabilities,
   authoritative simulation clock, supported canonical control profiles and
   the fixed `map_enu`/`base_link_flu` boundary.
3. Provider roles are `world`, `physics`, `state`, `controller`, `transport`,
   `sensor` and `traffic`. One process may implement several roles; several
   processes may compose one profile.
4. Component pins and provider roles remain separate:
   component pins prove exact software provenance, while provider descriptors
   explain runtime responsibility and interoperability.
5. Worker status v2 exposes the configured provider profile separately from
   currently active process IDs. `VehicleState` names its source provider.
   Command acceptance v2 names the delivering controller provider and canonical
   control profile.
6. The browser consumes canonical state and evidence. Unreal, Gazebo, PX4,
   ROS 2 and their native windows remain outside React and run on registered
   workers.
7. Gazebo/PX4 remains the frozen, comparatively cheap deterministic regression
   profile until another profile passes the same lifecycle, clock, command,
   safety and evidence gates.
8. Unreal is evaluated as a high-fidelity provider family. Native Unreal,
   CARLA and Project AirSim are separate candidates and are not interchangeable
   labels:
   - native Unreal maximizes project control but requires Mission Core-owned
     vehicle, sensor, clock and bridge work;
   - CARLA is evaluated when road/traffic simulation and its supported vehicle
     model fit the rover case;
   - Project AirSim is evaluated only against its current supported vehicle,
     PX4, ROS 2, platform and maintenance constraints.
9. A Gaussian scene may provide appearance and sensor-rendering context. Every
   qualification world still needs separately versioned physical collision
   meshes, road/drivable surfaces, materials/friction, semantic regions,
   spawn/goal definitions and evaluator truth.
10. Unreal does not block S1 completion or the S2 Gazebo/Nav2 baseline. It
    becomes most valuable in S3 virtual-sensor/perception work and S5
    high-fidelity/digital-twin work. An earlier bounded adapter spike is allowed
    because it reduces architectural risk.
11. PX4 remains a replaceable controller provider. An Unreal profile may use
    PX4 through an admitted external-simulator boundary or may use a different
    virtual controller, but each choice creates a distinct profile and cannot
    inherit the other profile's evidence.
12. No real actuator authority is introduced. All current profiles remain
    `virtual-only`.

## Fidelity ladder

| Level | Purpose | Initial provider |
| --- | --- | --- |
| L0 contract tests | Fast lifecycle, schema and safety regression | In-process fakes |
| L1 dynamics regression | Cheap repeated control/navigation qualification | Gazebo + PX4 SITL |
| L2 sensor/scene fidelity | Camera/LiDAR/perception and difficult visual worlds | Unreal candidate |
| L3 hardware/control integration | Controller-in-loop and HIL | Separate gated profile |
| L4 physical evidence | Shadow and later controlled field qualification | Vehicle Edge Agent |

A higher level does not replace lower-level regression. Evidence is comparable
only when scenario, provider profile, metric profile and reproducibility tier
allow it.

## Unreal evaluation gates

### U0 — selection spike

For native Unreal, CARLA and Project AirSim, record:

- supported rover/Ackermann dynamics and controllable wheel/suspension model;
- fixed-step clock, pause/step/reset and headless execution;
- external command/state bridge and PX4 compatibility;
- camera, depth, LiDAR, IMU, GNSS and ground-truth availability;
- collision/contact and semantic truth;
- Linux/Windows worker placement, GPU/VRAM/RAM and startup time;
- automation, packaging, licensing, upstream activity and version pinning;
- import path for existing Unreal assets and Gaussian reconstructions.

Exit: one candidate or native implementation is selected for a disposable U1
adapter. “Looks better” is not an exit criterion.

### U1 — canonical adapter proof

- publish one provider profile and authoritative fixed-step clock;
- launch/reset/stop through the Simulation Orchestrator;
- map a stock Ackermann pose to `VehicleState`;
- accept `rover-speed-steering/v1` under the existing TTL/watchdog boundary;
- prove straight, turn, reverse, command expiry and clean zero-residue stop;
- retain exact world, provider, host and resource evidence on D.

Exit: the existing React panel and run archive work without Unreal-specific
branches in Mission Core.

### U2 — physical and sensor world

- add reviewed collision/drivable geometry alongside visual assets/Gaussians;
- pin vehicle mass, inertia, wheelbase, steering limits, suspension, friction
  and sensor extrinsics;
- publish evaluator-only truth separately from planner/perception inputs;
- validate camera/LiDAR timing, noise and frame conversion.

Exit: sensor/perception experiments are repeatable and do not consume hidden
ground truth.

### U3 — comparative qualification

- run equivalent scenarios through the Gazebo and Unreal profiles;
- report control, collision, latency, resource and reproducibility differences;
- declare which conclusions are portable across providers and which are not.

Exit: Unreal supplies measurable product value beyond rendering quality.

## Immediate work policy

Continue work that remains valuable across providers:

- provider-neutral orchestration and capability admission;
- run, event, command, artifact and report contracts;
- TTL, heartbeat, watchdog, failsafe and authority gates;
- canonical frames, clocks, telemetry and evaluator metrics;
- scenario/profile registry and browser presentation of canonical state;
- Gazebo regression cases needed to validate those boundaries.

Defer until U0 selects a direction:

- a polished custom Gazebo vehicle;
- large Gazebo world/model libraries;
- simulator-specific UI controls;
- a production Unreal bridge;
- Gaussian collision or road generation assumptions;
- provider-specific perception contracts.

## Consequences

- Existing Polygon work is retained as the control plane and regression tier.
- Unreal experimentation can proceed independently without forking the product
  model or exposing a native engine to the browser.
- The first Unreal work is a measured adapter spike, not a platform migration.
- More explicit provider metadata and compatibility testing is required.
- Two physics providers increase qualification cost, but allow fast regression
  and high-fidelity experiments to coexist.

## References

- [PX4 simulator MAVLink API](https://docs.px4.io/main/en/simulation/)
- [CARLA documentation](https://carla.readthedocs.io/)
- [Project AirSim documentation](https://iamaisim.github.io/ProjectAirSim/)
- [ASAM OpenDRIVE](https://www.asam.net/standards/detail/opendrive/)

