From 359f0d1d3961c5b522f795565b9f059c9c8e1a96 Mon Sep 17 00:00:00 2001 From: DCCONSTRUCTIONS Date: Fri, 24 Jul 2026 19:40:59 +0300 Subject: [PATCH] docs: define distributed Mission Core topology --- README.md | 14 +- docs/01_IMPLEMENTATION_PLAN.md | 12 +- docs/12_SIMULATION_POLYGON_PRODUCT_AND_SRS.md | 87 ++++++++- ...mulation-polygon-qualification-boundary.md | 5 + ...ibuted-product-edge-and-worker-topology.md | 172 ++++++++++++++++++ 5 files changed, 285 insertions(+), 5 deletions(-) create mode 100644 docs/adr/0016-distributed-product-edge-and-worker-topology.md diff --git a/README.md b/README.md index ecdb490..b894c4b 100644 --- a/README.md +++ b/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) diff --git a/docs/01_IMPLEMENTATION_PLAN.md b/docs/01_IMPLEMENTATION_PLAN.md index e9a6a73..712fcec 100644 --- a/docs/01_IMPLEMENTATION_PLAN.md +++ b/docs/01_IMPLEMENTATION_PLAN.md @@ -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: diff --git a/docs/12_SIMULATION_POLYGON_PRODUCT_AND_SRS.md b/docs/12_SIMULATION_POLYGON_PRODUCT_AND_SRS.md index 194a340..2c59e50 100644 --- a/docs/12_SIMULATION_POLYGON_PRODUCT_AND_SRS.md +++ b/docs/12_SIMULATION_POLYGON_PRODUCT_AND_SRS.md @@ -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 diff --git a/docs/adr/0015-simulation-polygon-qualification-boundary.md b/docs/adr/0015-simulation-polygon-qualification-boundary.md index 8c333fd..fb519e0 100644 --- a/docs/adr/0015-simulation-polygon-qualification-boundary.md +++ b/docs/adr/0015-simulation-polygon-qualification-boundary.md @@ -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 diff --git a/docs/adr/0016-distributed-product-edge-and-worker-topology.md b/docs/adr/0016-distributed-product-edge-and-worker-topology.md new file mode 100644 index 0000000..4b3b948 --- /dev/null +++ b/docs/adr/0016-distributed-product-edge-and-worker-topology.md @@ -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. +