# ADR 0016: Distributed web product, edge runtime and worker topology

## Status

Accepted for architecture on 2026-07-24. It defines placement and packaging,
not field actuator acceptance. The current Windows/WSL2 simulation worker is a
laboratory deployment of this topology; the future onboard Edge Agent and its
physical command authority remain separate gates.

## Context

Mission Core has a React Control Station, a Python control plane, native
simulation providers and future onboard components. Treating all of them as one
application creates two misleading alternatives:

1. embed Gazebo, PX4, ROS 2 and Nav2 inside the browser; or
2. make Mission Core a Windows/macOS/Linux desktop executable.

Neither matches the system.

Gazebo Harmonic has a native Qt GUI, PX4 SITL and ROS 2 are Linux processes, and
Nav2 is a runtime graph. A browser cannot own those processes or preserve their
state when its tab closes. Conversely, a field vehicle must keep bounded
autonomy, safety behavior and durable local evidence when the operator browser,
WAN or control centre is unavailable.

The operator still needs one coherent product: plan a mission, inspect a live
or historical vehicle, run a simulation, compare outcomes and review evidence
from a browser on macOS, Windows, Linux or a tablet.

## Decision

### Product form

1. The primary Mission Core operator product remains the React Control Station
   served as static web assets by a Mission Core Gateway/API. It is not a
   platform-specific desktop executable.
2. An optional PWA, kiosk shell or thin Tauri/Electron wrapper may package the
   same web assets for offline distribution. Such a wrapper is not a second
   product, does not own authority and is not required for the core topology.
3. Native provider GUIs are diagnostic tools. Gazebo GUI, QGroundControl and
   similar tools do not become product navigation or a source-of-record.

### Runtime roles

4. Mission Core Control Plane owns users, missions, scenarios, policy,
   qualification-run identity, authority admission, orchestration, catalogues,
   comparison and reports.
5. Simulation Worker is a separately registered Linux execution target. It runs
   Simulation Orchestrator worker components plus Gazebo, PX4 SITL, ROS 2 and
   Nav2. Normal product operation is headless. A native Gazebo GUI may attach
   locally for laboratory diagnosis without becoming the control plane.
6. Vehicle Edge Agent is a future headless Linux service on the onboard
   computer or a vehicle-adjacent edge computer. It owns device adapters,
   bounded local mission state, health, canonical telemetry, local evidence,
   store-and-forward synchronization and the server-side physical authority
   boundary accepted for that vehicle.
7. The flight/rover controller remains a separate PX4 hardware boundary. A
   browser never talks to PX4 directly.
8. Observation/perception workers may run onboard, on a nearby edge computer or
   in a control-centre worker according to latency and bandwidth budgets. Their
   placement does not change canonical contracts or authority ownership.

### Browser presentation

9. The browser receives bounded canonical state, events, metrics, maps,
   trajectories, perception layers and optional media previews. It renders
   interactive product views through browser-native components such as Rerun
   Web Viewer, WebGL/canvas and ordinary React controls.
10. A Polygon run view shows the canonical rover pose, route, planned/factual
    trajectory, footprint, safety state and derived scene. It does not require
    remote pixels from Gazebo GUI.
11. Full native Gazebo rendering may be exposed only as an explicitly
    diagnostic remote-desktop/WebRTC capability. It is optional, isolated from
    command authority and never the only representation of run state.

### Connectivity and evidence

12. Field safety and bounded mission execution cannot depend on a browser tab,
    a WAN connection or continuous connectivity to a central Mission Core
    instance.
13. The Edge Agent persists raw/source evidence and the canonical event/state
    journal locally before optional upload. High-volume sensor data remains on
    vehicle storage until retention and connectivity policy permits transfer.
14. Connected mode sends bounded live telemetry, health, decisions and previews
    outward. Disconnected mode continues the locally admitted policy, applies
    the accepted loss/failsafe behavior and queues evidence for later sync.
15. Reconnection performs idempotent, digest-bound store-and-forward
    synchronization. The central archive never rewrites the vehicle's original
    run identity or presents a partial upload as complete.
16. A field kit may host the Gateway/API and React assets locally on an operator
    laptop or edge hub. The same deployment can later synchronize with a
    control-centre instance; no Internet connection is required to render the
    UI.

### Authority path

17. The authority path is always:

    ```text
    Browser intent
      -> Mission Core API/policy
      -> Orchestrator or Vehicle Edge Agent
      -> allowlisted provider/device adapter
      -> PX4 boundary
    ```

18. Losing the browser affects presentation only. Losing upstream connectivity
    invokes the locally accepted watchdog/failsafe policy; it does not grant a
    new command source.

## Supported deployment topologies

### Laboratory simulation

```text
Operator browser
  -> Mission Core Gateway/API
  -> Simulation Orchestrator
  -> registered Linux/WSL2 GPU worker
  -> Gazebo + PX4 SITL + ROS 2 + Nav2
  -> local source evidence + canonical/derived streams
```

The current `MissionCore-Sim` WSL2 distribution on the D drive is this
topology's first qualified worker. Its native Gazebo window is local diagnostics;
the product view remains browser-native.

The first implemented registration slice is S1C commit `b7ccca3`. Mission Core
and the worker share only a private mode-`0600` Unix socket in the WSL mount
namespace. PX4, Gazebo and Micro XRCE-DDS stay inside the worker's
loopback-only network namespace and run as the unprivileged `missioncore`
identity. Run artifacts and provider logs remain under the admitted D-only
roots. The React client calls same-origin Mission Core endpoints and never
receives the socket path or a provider endpoint. Remote/routed worker
registration is intentionally not inferred from this local laboratory
transport; it requires an authenticated contract of its own.

### Connected field vehicle

```text
Operator browser/control centre
  -> Mission Core Gateway/API
  <-> Vehicle Edge Agent on onboard Linux
  -> PX4 hardware boundary
  -> sensors and actuators
```

Bounded telemetry and previews can be live. Raw/high-volume evidence is written
locally first and uploaded according to policy.

### Disconnected field vehicle and later review

```text
Approved local mission + Edge Agent + PX4
  -> local execution/failsafe
  -> local append-only evidence
  -> later digest-bound synchronization
  -> browser history/replay/report
```

The historical/replay product is therefore not a fallback or a separate
application. It is the review side of the same distributed system.

## Consequences

- Operators use one browser product across simulation, field monitoring,
  planning, archive and comparison.
- Native Linux dependencies do not force a Windows-only or macOS-only Mission
  Core executable.
- Gazebo is not installed on field vehicles unless a specific lab/HIL profile
  requires it.
- The product needs explicit Gateway, worker-registration, Edge Agent,
  store-and-forward and capability-discovery contracts.
- Live 3D is a canonical-state presentation problem, not a remote-Gazebo-window
  dependency.
- A thin desktop wrapper remains possible for distribution or kiosk use, but it
  cannot widen authority or hide missing offline server components.
- Field hardware, storage budgets, network-loss policy, physical e-stop,
  operator takeover and real actuator authority still require separate
  acceptance.
