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
metadata and the virtual-only authority boundary. Live pause/resume/step/reset,
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
collapsing that boundary. An unprivileged worker agent owns the existing
application service and providers inside a fresh loopback-only network
namespace. Mission Core reaches it through a mode-`0600` Unix socket; React
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
top-down ENU trajectory from Gazebo dynamic-pose ground truth. That pose is
explicitly `diagnostic`, not accepted PX4/ROS 2 telemetry.
start/stop the stock rover and show worker/run/provider status. UI-2 commit
`60e7916` adds a worker-gated `Полигон` header root and a browser-native
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
`s1c-b7ccca3-20260724t174030z-8e46b3`: both providers reached readiness, the
The exact D-only UI-2 generation passed 35 target tests and a real UI-driven run
`s1c-60e7916-20260724t182006z-2f164e`: both providers reached readiness, the
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
rover motion, PX4 command delivery, watchdog/failsafe behavior, navigation or
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>
```
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
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
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
explicit start/stop POSTs; POSTs remain `403` unless the backend has the
`internal-virtual-only` gate and an exact commit. Missing configuration,
transport drift and corrupt evidence fail closed. The browser receives no Unix
socket, D root, artifact bytes, PX4 endpoint or direct provider command.
The direct `?workspace=polygon-run&run=<qualification-run-id>` URL remains a
compatible evidence deep-link. The archive API remains GET-only. The worker API
adds status/live GETs and explicit start/stop POSTs; POSTs remain `403` unless
the backend has the `internal-virtual-only` gate and an exact commit. Missing
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),
[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
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.
diagnostics. The accepted live rover scene uses canonical state in Three.js;
Rerun remains the recorded spatial-evidence path. 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
a K1-specific Foxglove launcher. Its fixed shell contains six architectural
sections — Center, Fleet, Observation, Missions, Data and System — while the K1
a K1-specific Foxglove launcher. Its fixed shell contains Center, Fleet,
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
React provisioning, acquisition/replay and diagnostic blocks live beside the
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
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
implemented inside the current shell but intentionally omitted from all
top-level and System navigation. It opens only through
`?workspace=polygon-run[&run=<id>]` and reads the server-owned qualification
repository. Top-level Polygon navigation and control remain gated on accepted
clock/frame/command/safety behavior.
Polygon is implemented as a capability-gated seventh section. When Mission Core
confirms an admitted Simulation Worker, its header button opens one direct
workspace with live 3D inspection and the server-owned qualification
repository. `?workspace=polygon-run[&run=<id>]` remains a compatibility
deep-link. Command and safety acceptance remain separate gates.
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

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 |
| 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 |
| 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
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
unprivileged worker agent in the same isolation boundary, a bounded Unix-socket
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
UI-driven provider run with diagnostic Gazebo `VehicleState`, eight persisted
lifecycle events, terminal `completed` and zero 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.
live panel. UI-2 commit `60e7916` promotes that panel into a worker-gated
top-level product root and replaces the diagnostic 2D marker with a
browser-native Three.js Ackermann Rover scene. The exact D-only generation
passed 35 target tests and one UI-driven provider run with diagnostic Gazebo
`VehicleState`, eight persisted lifecycle events, terminal `completed` and zero
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/{run-id}`. `QualificationRunStore(read_only=True)`
does not create, chmod or mutate the configured repository and rejects every
write transition. The Control Station opens the internal
`polygon-run-internal` workspace only for the direct
`?workspace=polygon-run[&run=<id>]` route; it is filtered out of System
navigation and adds no seventh top-level section. Browser QA loaded the accepted
archive and the S1C live worker. The hidden UI-1 panel shows
worker/run/provider status, sim time, ENU/FLU pose and a bounded 2D trajectory.
Start/stop stays behind the backend gate and reaches the worker through a local
Unix socket; SSH remains qualification bootstrap, never the product data plane.
A shared operator-facing deployment still requires authentication/RBAC,
service supervision and an accepted routed worker transport.
write transition. When `/api/v1/polygon/worker` returns an admitted available
worker, the Control Station adds `Полигон` as a seventh header root. One header
click opens the direct `polygon-run` workspace without a System launcher panel.
The old `?workspace=polygon-run[&run=<id>]` URL remains a compatible deep-link
for review and exact-run selection, not the primary operator navigation.
Browser QA loaded the accepted archive and the S1C live worker, rotated and
zoomed the 3D rover, observed live run/provider status, Gazebo sim time and
ENU/FLU pose, then completed a clean stop. Start/stop stays behind the backend
gate and reaches the worker through a local Unix socket; SSH remains
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
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
world/startup/DDS-writer readiness, eight persisted events, zero commands,
terminal `completed` and zero process residue;
- UI-0 is implemented as a hidden direct read-only Control Station workspace
over GET-only Polygon API routes. Browser QA loaded the real accepted S1B
- the UI-0 archive contract remains available over GET-only Polygon API routes
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
unchanged virtual-only authority boundary;
- S1C exact code generation `b7ccca3` adds a persistent, unprivileged
Simulation Worker agent in a fresh loopback-only namespace, a bounded
Unix-socket Mission Core gateway and an explicit `internal-virtual-only`
lifecycle gate;
- the hidden UI-1 live panel starts/stops the stock rover through Mission Core,
polls canonical worker state and renders a bounded ENU trajectory from
Gazebo dynamic-pose ground truth. The signal is marked `diagnostic`;
- UI-2 exact generation `60e7916` exposes `Полигон` as a dedicated header root
only while Mission Core confirms an available Simulation Worker. The header
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
`s1c-b7ccca3-20260724t174030z-8e46b3` reached `completed` with eight
persisted events, 52.836 seconds of Gazebo time and zero provider residue;
`s1c-60e7916-20260724t182006z-2f164e` reached `completed` with eight
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
command delivery;
- `actuator_authority=false`;
@ -127,7 +131,8 @@ The first delivery does not:
- build a custom physics engine;
- make `px4-ros2-interface-lib` mandatory for S1;
- 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
@ -216,10 +221,12 @@ 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.
state, metrics and optional media. The accepted live rover scene uses
browser-native Three.js; Rerun remains available for recorded spatial evidence.
Both presentation paths consume server-owned contracts rather than worker
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
@ -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
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
- Gazebo LiDAR/odometry feed the ROS 2/Nav2 baseline.
@ -728,10 +746,12 @@ safety policy.
## 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
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.
@ -758,26 +778,28 @@ GET /api/v1/polygon/runs/{run-id}
Missing/malformed configuration returns `503`; invalid or corrupt evidence
fails closed. Responses never contain the configured root, artifact bytes or
command payloads. The UI opens only through
`?workspace=polygon-run[&run=<run-id>]`; its hidden workspace is filtered from
System navigation and no seventh top-level section is added.
command payloads. `?workspace=polygon-run[&run=<run-id>]` remains a compatible
deep-link into the same product workspace.
UI-0 has no PX4 transport, no lifecycle/command operations and no top-level
Polygon navigation claim. It is a development/acceptance surface backed only
by the server-owned run repository. A shared review deployment requires a
reviewed read-only D mount or a co-located backend; SSH is not a product data
plane.
UI-0 itself has no PX4 transport or lifecycle/command operations. It remains a
read-only evidence contract backed by the server-owned run repository and is
composed into UI-2. A shared review deployment requires a reviewed read-only D
mount or a co-located backend; SSH is not a product data 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;
2. S1 target backend lifecycle and command authority are proven;
3. run history is persisted independently of a browser session.
UI-1 may present Scenarios, Run, Control, History, Compare and Report. It cannot
own provider processes, bypass authority checks or write directly to PX4.
Commit `60e7916` accepts the presentation/lifecycle slice before all three
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

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
```
Open:
Open the Control Station:
```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
the `internal-virtual-only` environment gate must leave status visible while
disabling lifecycle actions.