feat(simulation): add provider-neutral worker profile

2026-07-25 00:29:00 +03:00
parent 5abd07d2bf
commit 37c24b5fa8
21 changed files with 1275 additions and 121 deletions
@@ -35,9 +35,10 @@ reports easy to misuse.
 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.
+6. Each admitted closed-loop provider profile declares exactly one
+   authoritative simulation clock. The accepted stock profile uses Gazebo
+   `/clock`; ROS 2 uses simulated time and PX4 uXRCE-DDS time synchronization
+   is disabled for that 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
@@ -67,6 +68,10 @@ reports easy to misuse.
    [ADR 0016](0016-distributed-product-edge-and-worker-topology.md). Native
    Gazebo GUI is worker-local diagnostics; the operator product remains the
    browser Control Station over canonical state.
+18. Provider roles, capabilities, clock and canonical frames follow
+    [ADR 0017](0017-provider-neutral-simulation-and-unreal-evaluation.md).
+    Gazebo remains the regression baseline; Unreal is an unevaluated
+    high-fidelity provider family, not a replacement product architecture.

 ## Consequences

@@ -0,0 +1,179 @@
+# 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/)
+