docs: define distributed Mission Core topology
This commit is contained in:
DCCONSTRUCTIONS
parent
b790f29d59
commit
359f0d1d39
14
README.md
14
README.md
|
|
@ -190,9 +190,19 @@ invalid/corrupt evidence fails closed. The browser receives no D root, artifact
|
|||
bytes, command payloads or PX4/process-lifecycle operation.
|
||||
|
||||
See the [Polygon product/SRS](docs/12_SIMULATION_POLYGON_PRODUCT_AND_SRS.md),
|
||||
[ADR 0015](docs/adr/0015-simulation-polygon-qualification-boundary.md) and the
|
||||
[ADR 0015](docs/adr/0015-simulation-polygon-qualification-boundary.md),
|
||||
[ADR 0016](docs/adr/0016-distributed-product-edge-and-worker-topology.md) and the
|
||||
[SIM S0 worker runbook](docs/runbooks/SIM_S0_AI_WORKER.md).
|
||||
|
||||
Mission Core remains a distributed browser product rather than a
|
||||
platform-specific desktop executable. React runs in the operator browser;
|
||||
Gateway/API and Control Plane run as long-lived services; Gazebo/PX4/ROS 2/Nav2
|
||||
run headless on a registered simulation worker; and a future field vehicle runs
|
||||
a headless onboard Linux Edge Agent with local-first evidence and
|
||||
store-and-forward synchronization. Native Gazebo GUI is worker-local
|
||||
diagnostics. Product 3D uses canonical state in browser-native Rerun/WebGL views,
|
||||
so field execution never depends on streaming a simulator desktop.
|
||||
|
||||
## Mission Core Control Station and visualization adapters
|
||||
|
||||
The browser application is the universal Mission Core Control Station rather than
|
||||
|
|
@ -429,6 +439,8 @@ present.
|
|||
- [Plugin-owned frontend device workflows](docs/adr/0010-plugin-owned-frontend-device-workflows.md)
|
||||
- [Laboratory plugin runtime handshake and transport seam](docs/adr/0011-laboratory-plugin-runtime-handshake-and-transport-seam.md)
|
||||
- [Device-bound K1 command authority](docs/adr/0012-device-bound-k1-command-authority.md)
|
||||
- [Simulation Polygon qualification boundary](docs/adr/0015-simulation-polygon-qualification-boundary.md)
|
||||
- [Distributed product, edge and worker topology](docs/adr/0016-distributed-product-edge-and-worker-topology.md)
|
||||
- [Redacted live lab report](docs/lab/001_K1_LIVE_MQTT_20260715.redacted.md)
|
||||
- [Canonical control and durable archive milestone](docs/lab/004_K1_CANONICAL_CONTROL_ARCHIVE_20260719.redacted.md)
|
||||
- [Session manifest schema](schemas/session-manifest.schema.json)
|
||||
|
|
|
|||
|
|
@ -127,7 +127,9 @@ still stops and seals only local reception and reports scanner state as unknown.
|
|||
The Polygon branch follows
|
||||
[`docs/12_SIMULATION_POLYGON_PRODUCT_AND_SRS.md`](12_SIMULATION_POLYGON_PRODUCT_AND_SRS.md)
|
||||
and
|
||||
[`ADR 0015`](adr/0015-simulation-polygon-qualification-boundary.md).
|
||||
[`ADR 0015`](adr/0015-simulation-polygon-qualification-boundary.md). Component
|
||||
placement and field/offline topology follow
|
||||
[`ADR 0016`](adr/0016-distributed-product-edge-and-worker-topology.md).
|
||||
It does not reorder or weaken the K1 physical-evidence gates in this document.
|
||||
Its first gate, SIM S0, is accepted:
|
||||
|
||||
|
|
@ -175,6 +177,14 @@ virtual-only authority boundary. A shared operator-facing deployment still
|
|||
requires a reviewed read-only D mount/source configuration; UI-0 does not use
|
||||
SSH as a product data plane.
|
||||
|
||||
Mission Core remains a distributed web product. React is served by a long-lived
|
||||
Gateway/API and renders canonical state through browser-native components.
|
||||
Gazebo/PX4/ROS 2/Nav2 run headless on a registered Linux simulation worker; the
|
||||
native Gazebo GUI is optional worker-local diagnostics. A future field vehicle
|
||||
runs a headless Linux Edge Agent with local-first evidence and store-and-forward
|
||||
synchronization. The browser never talks directly to PX4, and field
|
||||
execution/failsafe cannot depend on a browser or WAN connection.
|
||||
|
||||
## Stage 0 — repository and host baseline
|
||||
|
||||
Deliverables:
|
||||
|
|
|
|||
|
|
@ -13,9 +13,10 @@ Ops source of truth:
|
|||
- [MISSIONCOR-41](https://ops.nodedc.ru/nodedc/browse/MISSIONCOR-41) is the
|
||||
active S1 lifecycle/authority 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.
|
||||
This document, ADR 0015 and ADR 0016 are the repository truth. A material change
|
||||
to run kinds, authority, clocks, frames, source-of-record, provider boundaries,
|
||||
component placement or phase gates must update the ADR/SRS and MISSIONCOR-39
|
||||
together.
|
||||
|
||||
## 1. Product thesis
|
||||
|
||||
|
|
@ -180,6 +181,86 @@ 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.
|
||||
|
||||
### 6.1 Product form and component placement
|
||||
|
||||
Mission Core is a distributed web product, not a monolithic desktop
|
||||
application:
|
||||
|
||||
| Component | Product placement | Packaging and responsibility |
|
||||
| --- | --- | --- |
|
||||
| Control Station | Any operator browser on macOS, Windows, Linux or tablet | React static assets; interactive planning, live state, history, comparison and reports |
|
||||
| Gateway/API and Control Plane | Control-centre server, laboratory host or offline field kit | Long-lived service; identity, policy, mission/scenario/run state, orchestration and catalogues |
|
||||
| Simulation Worker | Registered Linux GPU worker; currently dedicated WSL2 on the reviewed Windows host | Headless worker service plus Gazebo, PX4 SITL, ROS 2 and Nav2 |
|
||||
| Native Gazebo GUI | Worker desktop only | Optional diagnostic attachment; never product state, authority or source-of-record |
|
||||
| Vehicle Edge Agent | Future onboard or vehicle-adjacent Linux computer | Headless device/runtime adapters, local authority gate, bounded mission state, durable evidence and store-and-forward sync |
|
||||
| PX4 controller | SITL process in simulation or separate controller hardware in the field | Vehicle control loops, constraints and failsafe behind an allowlisted adapter |
|
||||
| Observation/perception worker | Onboard, nearby edge or control-centre worker according to latency/bandwidth profile | Canonical perception outputs; placement does not change contracts |
|
||||
| Archive/evidence storage | Worker/vehicle local-first, then optional central synchronization | Immutable source evidence, derived artifacts and reports |
|
||||
|
||||
The primary deliverable remains the browser application. A PWA, kiosk package
|
||||
or thin Tauri/Electron wrapper may distribute the same assets for an offline
|
||||
field kit, but it is not a second product and never owns provider processes or
|
||||
command authority.
|
||||
|
||||
The Polygon browser view consumes bounded canonical state and derived evidence:
|
||||
rover pose, route, planned/factual trajectory, footprint, contacts, safety
|
||||
state, metrics and optional media. Browser-native Rerun/WebGL/canvas components
|
||||
provide orbit, zoom and layer controls. Full Gazebo pixels are optional
|
||||
diagnostics through the worker desktop or a separately gated remote-display
|
||||
capability; they are not required for the product view.
|
||||
|
||||
### 6.2 Deployment topologies
|
||||
|
||||
Laboratory simulation:
|
||||
|
||||
```text
|
||||
Operator browser
|
||||
-> Mission Core Gateway/API
|
||||
-> Simulation Orchestrator
|
||||
-> registered Linux/WSL2 worker
|
||||
-> Gazebo + PX4 SITL + ROS 2 + Nav2
|
||||
-> canonical live stream + local source/derived artifacts
|
||||
```
|
||||
|
||||
Connected field vehicle:
|
||||
|
||||
```text
|
||||
Operator browser/control centre
|
||||
-> Mission Core Gateway/API
|
||||
<-> Vehicle Edge Agent on onboard Linux
|
||||
-> PX4 hardware boundary
|
||||
-> sensors and actuators
|
||||
```
|
||||
|
||||
Disconnected field vehicle and later review:
|
||||
|
||||
```text
|
||||
Locally admitted mission + Edge Agent + PX4
|
||||
-> accepted local watchdog/failsafe behavior
|
||||
-> append-only onboard evidence
|
||||
-> later idempotent digest-bound synchronization
|
||||
-> browser history/replay/report
|
||||
```
|
||||
|
||||
Field execution and safety never depend on a browser tab or continuous WAN.
|
||||
The Edge Agent writes source evidence locally before upload, retains
|
||||
high-volume data according to storage policy and sends bounded telemetry,
|
||||
events, decisions and previews when connected. Reconnection synchronizes the
|
||||
same immutable run identity; a partial upload is never presented as complete.
|
||||
|
||||
The authority path remains:
|
||||
|
||||
```text
|
||||
Browser intent
|
||||
-> Mission Core API/policy
|
||||
-> Simulation Orchestrator or Vehicle Edge Agent
|
||||
-> allowlisted provider/device adapter
|
||||
-> PX4 boundary
|
||||
```
|
||||
|
||||
The placement decision is specified by
|
||||
[ADR 0016](adr/0016-distributed-product-edge-and-worker-topology.md).
|
||||
|
||||
## 7. Canonical domain model
|
||||
|
||||
### 7.1 Versioned inputs
|
||||
|
|
|
|||
|
|
@ -62,6 +62,11 @@ reports easy to misuse.
|
|||
Micro XRCE-DDS Agent's UDP wildcard bind is acceptable only inside that
|
||||
boundary; no S0 listener may be reachable from the worker LAN or Windows
|
||||
host network.
|
||||
17. Product packaging, simulation-worker placement, the future onboard Edge
|
||||
Agent, local-first field evidence and offline synchronization follow
|
||||
[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.
|
||||
|
||||
## Consequences
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,172 @@
|
|||
# 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.
|
||||
|
||||
### 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.
|
||||
|
||||
Loading…
Reference in New Issue