SILVER
/
NODEDC_MISSION_CORE
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(simulation): accept worker-gated polygon ui

This commit is contained in:
DCCONSTRUCTIONS 2026-07-24 21:29:55 +03:00
parent 60e79160c9
commit 53fd1e3bfc
4 changed files with 107 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
README.md
View File

@ -170,21 +170,24 @@ surface backed by the same append-only qualification repository. It exposes
identity, terminal reason, provider pins, events, command count, artifact identity, terminal reason, provider pins, events, command count, artifact
metadata and the virtual-only authority boundary. Live pause/resume/step/reset, metadata and the virtual-only authority boundary. Live pause/resume/step/reset,
canonical telemetry, PX4 command mapping, watchdog/failsafe evidence and the canonical telemetry, PX4 command mapping, watchdog/failsafe evidence and the
top-level Polygon control surface remain gated. accepted command path remain gated.
S1C commit `b7ccca3` adds the first registered live-worker vertical without S1C commit `b7ccca3` adds the first registered live-worker vertical without
collapsing that boundary. An unprivileged worker agent owns the existing collapsing that boundary. An unprivileged worker agent owns the existing
application service and providers inside a fresh loopback-only network application service and providers inside a fresh loopback-only network
namespace. Mission Core reaches it through a mode-`0600` Unix socket; React namespace. Mission Core reaches it through a mode-`0600` Unix socket; React
reaches only same-origin Polygon API routes. The live browser panel can reaches only same-origin Polygon API routes. The live browser panel can
start/stop the stock rover, show worker/run/provider status and render a bounded start/stop the stock rover and show worker/run/provider status. UI-2 commit
top-down ENU trajectory from Gazebo dynamic-pose ground truth. That pose is `60e7916` adds a worker-gated `Полигон` header root and a browser-native
explicitly `diagnostic`, not accepted PX4/ROS 2 telemetry. Three.js Ackermann Rover scene with orbit, zoom, pan, follow and reset. The
deep-link remains for exact-run review; it is no longer the primary operator
entry. Gazebo dynamic-pose ground truth remains explicitly `diagnostic`, not
accepted PX4/ROS 2 telemetry.
The exact D-only generation passed 21 target tests and a real UI-driven run The exact D-only UI-2 generation passed 35 target tests and a real UI-driven run
`s1c-b7ccca3-20260724t174030z-8e46b3`: both providers reached readiness, the `s1c-60e7916-20260724t182006z-2f164e`: both providers reached readiness, the
browser received live `VehicleState`, the run reached `completed` after browser received live `VehicleState`, the run reached `completed` after
52.836 seconds of Gazebo time, and shutdown left no PX4/Gazebo/XRCE process 27.74 seconds of Gazebo time, and shutdown left no PX4/Gazebo/XRCE process
residue. The run contained zero commands, so this result does not yet prove residue. The run contained zero commands, so this result does not yet prove
rover motion, PX4 command delivery, watchdog/failsafe behavior, navigation or rover motion, PX4 command delivery, watchdog/failsafe behavior, navigation or
safety acceptance. safety acceptance.
@ -195,7 +198,8 @@ Start the worker from the exact immutable D source generation:
sudo simulation/s1/worker-agent.sh <exact-40-character-mission-core-commit> sudo simulation/s1/worker-agent.sh <exact-40-character-mission-core-commit>
``` ```
Then configure the Mission Core backend and open the direct route: Then configure the Mission Core backend. When the worker status is available,
open `Полигон` from the Control Station header:
```bash ```bash
export MISSIONCORE_POLYGON_RUNS_ROOT=/mnt/d/NDC_MISSIONCORE/simulation/artifacts/s1/runs export MISSIONCORE_POLYGON_RUNS_ROOT=/mnt/d/NDC_MISSIONCORE/simulation/artifacts/s1/runs
@ -206,14 +210,16 @@ uv run uvicorn k1link.web.app:app --host 127.0.0.1 --port 8765
``` ```
```text ```text
http://127.0.0.1:8765/?workspace=polygon-run&run=<qualification-run-id> http://127.0.0.1:8765/
``` ```
The archive API remains GET-only. The worker API adds status/live GETs and The direct `?workspace=polygon-run&run=<qualification-run-id>` URL remains a
explicit start/stop POSTs; POSTs remain `403` unless the backend has the compatible evidence deep-link. The archive API remains GET-only. The worker API
`internal-virtual-only` gate and an exact commit. Missing configuration, adds status/live GETs and explicit start/stop POSTs; POSTs remain `403` unless
transport drift and corrupt evidence fail closed. The browser receives no Unix the backend has the `internal-virtual-only` gate and an exact commit. Missing
socket, D root, artifact bytes, PX4 endpoint or direct provider command. configuration, transport drift and corrupt evidence fail closed. The browser
receives no Unix socket, D root, artifact bytes, PX4 endpoint or direct provider
command.
See the [Polygon product/SRS](docs/12_SIMULATION_POLYGON_PRODUCT_AND_SRS.md), See the [Polygon product/SRS](docs/12_SIMULATION_POLYGON_PRODUCT_AND_SRS.md),
[ADR 0015](docs/adr/0015-simulation-polygon-qualification-boundary.md), [ADR 0015](docs/adr/0015-simulation-polygon-qualification-boundary.md),
@ -228,14 +234,16 @@ 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 run headless on a registered simulation worker; and a future field vehicle runs
a headless onboard Linux Edge Agent with local-first evidence and a headless onboard Linux Edge Agent with local-first evidence and
store-and-forward synchronization. Native Gazebo GUI is worker-local store-and-forward synchronization. Native Gazebo GUI is worker-local
diagnostics. Product 3D uses canonical state in browser-native Rerun/WebGL views, diagnostics. The accepted live rover scene uses canonical state in Three.js;
so field execution never depends on streaming a simulator desktop. Rerun remains the recorded spatial-evidence path. Field execution never depends
on streaming a simulator desktop.
## Mission Core Control Station and visualization adapters ## Mission Core Control Station and visualization adapters
The browser application is the universal Mission Core Control Station rather than The browser application is the universal Mission Core Control Station rather than
a K1-specific Foxglove launcher. Its fixed shell contains six architectural a K1-specific Foxglove launcher. Its fixed shell contains Center, Fleet,
sections — Center, Fleet, Observation, Missions, Data and System — while the K1 Observation, Missions, Data and System; a seventh Polygon section is inserted
only while an admitted Simulation Worker is available. The K1
BLE/Wi-Fi/live workflow remains isolated as the first real device adapter. Its BLE/Wi-Fi/live workflow remains isolated as the first real device adapter. Its
React provisioning, acquisition/replay and diagnostic blocks live beside the React provisioning, acquisition/replay and diagnostic blocks live beside the
plugin manifest under `plugins/xgrids-k1/frontend`; the generic application plugin manifest under `plugins/xgrids-k1/frontend`; the generic application
@ -329,12 +337,11 @@ standalone release install. The frontend consumes sibling `file:` packages from
revision or content hash. Publishing/vendoring those packages or enforcing an revision or content hash. Publishing/vendoring those packages or enforcing an
immutable donor revision remains a packaging and CI prerequisite. immutable donor revision remains a packaging and CI prerequisite.
Polygon is planned as a seventh section. The read-only direct UI-0 run view is Polygon is implemented as a capability-gated seventh section. When Mission Core
implemented inside the current shell but intentionally omitted from all confirms an admitted Simulation Worker, its header button opens one direct
top-level and System navigation. It opens only through workspace with live 3D inspection and the server-owned qualification
`?workspace=polygon-run[&run=<id>]` and reads the server-owned qualification repository. `?workspace=polygon-run[&run=<id>]` remains a compatibility
repository. Top-level Polygon navigation and control remain gated on accepted deep-link. Command and safety acceptance remain separate gates.
clock/frame/command/safety behavior.
The Observation spatial workspace embeds the open-source Rerun Web Viewer The Observation spatial workspace embeds the open-source Rerun Web Viewer
inside the Mission Core shell. It can open a compatible RRD over same-origin inside the Mission Core shell. It can open a compatible RRD over same-origin

40
docs/01_IMPLEMENTATION_PLAN.md
View File

@ -24,7 +24,7 @@ Each gate produces evidence and an explicit GO, PAUSE or BLOCKED result.
| Plugin isolation | GO (laboratory control plane) — vendor backend/frontend and optional scene controls are plugin-owned; manifest/runtime descriptor parity, versioned handshake, lifecycle health and transport correlation fail closed while execution remains in-process | | Plugin isolation | GO (laboratory control plane) — vendor backend/frontend and optional scene controls are plugin-owned; manifest/runtime descriptor parity, versioned handshake, lifecycle health and transport correlation fail closed while execution remains in-process |
| K1 application control | GO (physical staged cycle) — after fixing the PCAP-proven `sint64` time field, one explicit UI launch completed all 14 canonical operations on one control session, reached live `SCANNING + project + init_ready`, displayed real points, then one explicit STOP returned K1 to unbound `READY`. No retry or fallback command was sent. Native-project reuse through LixelGO/USB remains an independent verification | | K1 application control | GO (physical staged cycle) — after fixing the PCAP-proven `sint64` time field, one explicit UI launch completed all 14 canonical operations on one control session, reached live `SCANNING + project + init_ready`, displayed real points, then one explicit STOP returned K1 to unbound `READY`. No retry or fallback command was sent. Native-project reuse through LixelGO/USB remains an independent verification |
| Stage 8 product storage | PAUSE — retention, replication, encryption, capacity monitoring and long-run browser/WASM stress remain deployment gates | | Stage 8 product storage | PAUSE — retention, replication, encryption, capacity monitoring and long-run browser/WASM stress remain deployment gates |
| Simulation Polygon | SIM S0 GO; S1A complete; S1B lifecycle PASS; S1C registered live worker/UI PASS — exact commit `b7ccca3` passed 21 focused target tests and a UI-driven D-only PX4/Gazebo run. Mission Core registered the loopback-only unprivileged worker through a private Unix socket, rendered diagnostic ENU `VehicleState`, persisted eight events and stopped both provider groups with zero residue. The run sent zero commands; PX4 command delivery/motion, canonical PX4/ROS 2 telemetry, pause/step/reset, watchdog/failsafe, navigation/safety acceptance, auth/RBAC and real actuator authority remain absent; top-level Polygon remains gated | | Simulation Polygon | SIM S0 GO; S1A complete; S1B lifecycle PASS; S1C registered live worker PASS; UI-2 browser surface PASS — exact commit `60e7916` passed 35 focused tests on the immutable D-only generation, 157 frontend tests and the 705-test backend suite. A capability-gated `Полигон` root now opens one direct workspace with a procedural 3D Ackermann Rover, 360° azimuth orbit, bounded vertical orbit, zoom, pan and live diagnostic ENU state. UI-driven run `s1c-60e7916-20260724t182006z-2f164e` reached `completed` after 27.74 seconds of Gazebo time with eight events, zero commands and zero provider residue. PX4 command delivery/motion, canonical PX4/ROS 2 telemetry, pause/step/reset, watchdog/failsafe, navigation/safety acceptance, shared-deployment auth/RBAC and real actuator authority remain absent |
USB project copying remains optional ground truth rather than a blocker for the USB project copying remains optional ground truth rather than a blocker for the
now-verified network path. Owner-operated LixelGO traffic verifies the MQTT now-verified network path. Owner-operated LixelGO traffic verifies the MQTT
@ -163,27 +163,31 @@ fresh loopback-only namespace, the run reached `completed`, and both provider
groups stopped without residue. S1C commit `b7ccca3` adds a persistent groups stopped without residue. S1C commit `b7ccca3` adds a persistent
unprivileged worker agent in the same isolation boundary, a bounded Unix-socket unprivileged worker agent in the same isolation boundary, a bounded Unix-socket
gateway, an explicit `internal-virtual-only` backend gate and a browser-native gateway, an explicit `internal-virtual-only` backend gate and a browser-native
live panel. The exact D-only generation passed 21 target tests and one live panel. UI-2 commit `60e7916` promotes that panel into a worker-gated
UI-driven provider run with diagnostic Gazebo `VehicleState`, eight persisted top-level product root and replaces the diagnostic 2D marker with a
lifecycle events, terminal `completed` and zero process residue. Its browser-native Three.js Ackermann Rover scene. The exact D-only generation
zero-command stationary rover does not close PX4 command delivery, canonical passed 35 target tests and one UI-driven provider run with diagnostic Gazebo
PX4/ROS 2 telemetry, pause/step/reset, heartbeat/watchdog or failsafe checkers; `VehicleState`, eight persisted lifecycle events, terminal `completed` and zero
these remain the next S1 increments. process residue. Its zero-command stationary rover does not close PX4 command
delivery, canonical PX4/ROS 2 telemetry, pause/step/reset, heartbeat/watchdog or
failsafe checkers; these remain the next S1 increments.
UI-0 now consumes the same append-only run repository through The archival surface consumes the same append-only run repository through
`GET /api/v1/polygon/runs` and `GET /api/v1/polygon/runs` and
`GET /api/v1/polygon/runs/{run-id}`. `QualificationRunStore(read_only=True)` `GET /api/v1/polygon/runs/{run-id}`. `QualificationRunStore(read_only=True)`
does not create, chmod or mutate the configured repository and rejects every does not create, chmod or mutate the configured repository and rejects every
write transition. The Control Station opens the internal write transition. When `/api/v1/polygon/worker` returns an admitted available
`polygon-run-internal` workspace only for the direct worker, the Control Station adds `Полигон` as a seventh header root. One header
`?workspace=polygon-run[&run=<id>]` route; it is filtered out of System click opens the direct `polygon-run` workspace without a System launcher panel.
navigation and adds no seventh top-level section. Browser QA loaded the accepted The old `?workspace=polygon-run[&run=<id>]` URL remains a compatible deep-link
archive and the S1C live worker. The hidden UI-1 panel shows for review and exact-run selection, not the primary operator navigation.
worker/run/provider status, sim time, ENU/FLU pose and a bounded 2D trajectory. Browser QA loaded the accepted archive and the S1C live worker, rotated and
Start/stop stays behind the backend gate and reaches the worker through a local zoomed the 3D rover, observed live run/provider status, Gazebo sim time and
Unix socket; SSH remains qualification bootstrap, never the product data plane. ENU/FLU pose, then completed a clean stop. Start/stop stays behind the backend
A shared operator-facing deployment still requires authentication/RBAC, gate and reaches the worker through a local Unix socket; SSH remains
service supervision and an accepted routed worker transport. qualification bootstrap, never the product data plane. A shared
operator-facing deployment still requires authentication/RBAC, service
supervision and an accepted routed worker transport.
Mission Core remains a distributed web product. React is served by a long-lived Mission Core remains a distributed web product. React is served by a long-lived
Gateway/API and renders canonical state through browser-native components. Gateway/API and renders canonical state through browser-native components.

74
docs/12_SIMULATION_POLYGON_PRODUCT_AND_SRS.md
View File

@ -69,20 +69,24 @@ Polygon is now a parallel product branch. As of this document:
lifecycle in a fresh loopback-only namespace: two provider PGIDs, explicit lifecycle in a fresh loopback-only namespace: two provider PGIDs, explicit
world/startup/DDS-writer readiness, eight persisted events, zero commands, world/startup/DDS-writer readiness, eight persisted events, zero commands,
terminal `completed` and zero process residue; terminal `completed` and zero process residue;
- UI-0 is implemented as a hidden direct read-only Control Station workspace - the UI-0 archive contract remains available over GET-only Polygon API routes
over GET-only Polygon API routes. Browser QA loaded the real accepted S1B and as a compatibility deep-link. Browser QA loaded the real accepted S1B
journal and displayed its four provider pins, eight events, zero commands and journal and displayed its four provider pins, eight events, zero commands and
unchanged virtual-only authority boundary; unchanged virtual-only authority boundary;
- S1C exact code generation `b7ccca3` adds a persistent, unprivileged - S1C exact code generation `b7ccca3` adds a persistent, unprivileged
Simulation Worker agent in a fresh loopback-only namespace, a bounded Simulation Worker agent in a fresh loopback-only namespace, a bounded
Unix-socket Mission Core gateway and an explicit `internal-virtual-only` Unix-socket Mission Core gateway and an explicit `internal-virtual-only`
lifecycle gate; lifecycle gate;
- the hidden UI-1 live panel starts/stops the stock rover through Mission Core, - UI-2 exact generation `60e7916` exposes `Полигон` as a dedicated header root
polls canonical worker state and renders a bounded ENU trajectory from only while Mission Core confirms an available Simulation Worker. The header
Gazebo dynamic-pose ground truth. The signal is marked `diagnostic`; opens one direct workspace without a secondary launcher panel;
- the browser-native Three.js scene renders a recognisable procedural Ackermann
Rover, ground grid and ENU trajectory. Orbit supports 360° azimuth, bounded
vertical inspection from overhead to horizon, zoom, pan, follow and camera
reset. The Gazebo dynamic-pose signal remains marked `diagnostic`;
- the UI-driven target run - the UI-driven target run
`s1c-b7ccca3-20260724t174030z-8e46b3` reached `completed` with eight `s1c-60e7916-20260724t182006z-2f164e` reached `completed` with eight
persisted events, 52.836 seconds of Gazebo time and zero provider residue; persisted events, 27.74 seconds of Gazebo time and zero provider residue;
it contained zero commands and therefore does not prove rover motion or PX4 it contained zero commands and therefore does not prove rover motion or PX4
command delivery; command delivery;
- `actuator_authority=false`; - `actuator_authority=false`;
@ -127,7 +131,8 @@ The first delivery does not:
- build a custom physics engine; - build a custom physics engine;
- make `px4-ros2-interface-lib` mandatory for S1; - make `px4-ros2-interface-lib` mandatory for S1;
- overload the observation-session model for qualification runs; - overload the observation-session model for qualification runs;
- implement a top-level UI before the backend S1 gate. - treat the capability-gated top-level UI as proof of the backend S1 command or
safety gate.
## 5. Product and system boundaries ## 5. Product and system boundaries
@ -216,10 +221,12 @@ command authority.
The Polygon browser view consumes bounded canonical state and derived evidence: The Polygon browser view consumes bounded canonical state and derived evidence:
rover pose, route, planned/factual trajectory, footprint, contacts, safety rover pose, route, planned/factual trajectory, footprint, contacts, safety
state, metrics and optional media. Browser-native Rerun/WebGL/canvas components state, metrics and optional media. The accepted live rover scene uses
provide orbit, zoom and layer controls. Full Gazebo pixels are optional browser-native Three.js; Rerun remains available for recorded spatial evidence.
diagnostics through the worker desktop or a separately gated remote-display Both presentation paths consume server-owned contracts rather than worker
capability; they are not required for the product view. processes. 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 ### 6.2 Deployment topologies
@ -698,6 +705,17 @@ and no provider residue. Its `VehicleState` is Gazebo ground truth marked
`diagnostic`; PX4/ROS 2 canonical telemetry and command-induced rover motion `diagnostic`; PX4/ROS 2 canonical telemetry and command-induced rover motion
remain open. remain open.
UI-2 commit `60e7916` accepts the next browser-placement slice. Its exact
source archive SHA-256 is
`d0f343154981c6dc78deb8ac57de4d980388a0d3f80ff7405ff53e52166d2bd3`;
the xattr-free Control Station build archive SHA-256 is
`250898e82ae3c97c1328ea90b5a1fc0fed9aeedcd2c06002b9b5d1e5bfa50f36`.
The exact D-only generation passed 35 focused target tests. Browser QA entered
through the capability-gated header, found no secondary launcher, exercised
orbit and zoom, observed advancing Gazebo time and stopped
`s1c-60e7916-20260724t182006z-2f164e` cleanly at 27.74 seconds of simulation
time with eight events, zero commands and zero provider residue.
### S2 ### S2
- Gazebo LiDAR/odometry feed the ROS 2/Nav2 baseline. - Gazebo LiDAR/odometry feed the ROS 2/Nav2 baseline.
@ -728,10 +746,12 @@ safety policy.
## 20. UI gate ## 20. UI gate
Polygon is planned as the seventh top-level bounded context: Polygon is implemented as a capability-gated seventh top-level bounded context:
```text ```text
Center | Fleet | Observation | Polygon | Missions | Data | System Center | Fleet | Observation | Missions | Data | Polygon* | System
* visible only while Mission Core confirms an admitted available Simulation Worker
``` ```
Two UI gates are intentionally distinct. Two UI gates are intentionally distinct.
@ -758,26 +778,28 @@ GET /api/v1/polygon/runs/{run-id}
Missing/malformed configuration returns `503`; invalid or corrupt evidence Missing/malformed configuration returns `503`; invalid or corrupt evidence
fails closed. Responses never contain the configured root, artifact bytes or fails closed. Responses never contain the configured root, artifact bytes or
command payloads. The UI opens only through command payloads. `?workspace=polygon-run[&run=<run-id>]` remains a compatible
`?workspace=polygon-run[&run=<run-id>]`; its hidden workspace is filtered from deep-link into the same product workspace.
System navigation and no seventh top-level section is added.
UI-0 has no PX4 transport, no lifecycle/command operations and no top-level UI-0 itself has no PX4 transport or lifecycle/command operations. It remains a
Polygon navigation claim. It is a development/acceptance surface backed only read-only evidence contract backed by the server-owned run repository and is
by the server-owned run repository. A shared review deployment requires a composed into UI-2. A shared review deployment requires a reviewed read-only D
reviewed read-only D mount or a co-located backend; SSH is not a product data mount or a co-located backend; SSH is not a product data plane.
plane.
### UI-1 — top-level Polygon ### UI-2 — worker-gated top-level Polygon
Top-level UI implementation begins only after: The full UI-2 control/scenario gate begins only after:
1. this SRS and the clock/frame/authority contracts are accepted; 1. this SRS and the clock/frame/authority contracts are accepted;
2. S1 target backend lifecycle and command authority are proven; 2. S1 target backend lifecycle and command authority are proven;
3. run history is persisted independently of a browser session. 3. run history is persisted independently of a browser session.
UI-1 may present Scenarios, Run, Control, History, Compare and Report. It cannot Commit `60e7916` accepts the presentation/lifecycle slice before all three
own provider processes, bypass authority checks or write directly to PX4. conditions are complete: conditional header root, direct workspace,
virtual-only start/stop, 3D rover inspection, diagnostic ENU pose and read-only
history. It does not claim command authority. Scenarios, pause/step/reset,
canonical rover commands, Compare and Report remain planned. UI-2 cannot own
provider processes, bypass authority checks or write directly to PX4.
## 21. Change control ## 21. Change control

9
docs/runbooks/SIM_S1C_LIVE_WORKER.md
View File

@ -68,13 +68,16 @@ export MISSIONCORE_COMMIT=<exact-40-character-commit>
uv run uvicorn k1link.web.app:app --host 127.0.0.1 --port 8765 uv run uvicorn k1link.web.app:app --host 127.0.0.1 --port 8765
``` ```
Open: Open the Control Station:
```text ```text
http://127.0.0.1:8765/?workspace=polygon-run http://127.0.0.1:8765/
``` ```
The live panel must show `Worker готов`. Start/stop calls require an After Mission Core confirms the worker, `Полигон` must appear in the header and
open the live workspace directly. The
`?workspace=polygon-run[&run=<qualification-run-id>]` URL remains a compatible
deep-link. The live panel must show `Worker готов`. Start/stop calls require an
`Idempotency-Key`; the React client generates one per operator intent. Removing `Idempotency-Key`; the React client generates one per operator intent. Removing
the `internal-virtual-only` environment gate must leave status visible while the `internal-virtual-only` environment gate must leave status visible while
disabling lifecycle actions. disabling lifecycle actions.