From 53fd1e3bfc050fcc261d904c21ff8b0cf8d35616 Mon Sep 17 00:00:00 2001 From: DCCONSTRUCTIONS Date: Fri, 24 Jul 2026 21:29:55 +0300 Subject: [PATCH] docs(simulation): accept worker-gated polygon ui --- README.md | 55 ++++++++------ docs/01_IMPLEMENTATION_PLAN.md | 40 +++++----- docs/12_SIMULATION_POLYGON_PRODUCT_AND_SRS.md | 74 ++++++++++++------- docs/runbooks/SIM_S1C_LIVE_WORKER.md | 9 ++- 4 files changed, 107 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index bedcd20..80f217c 100644 --- a/README.md +++ b/README.md @@ -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 ``` -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= +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=` 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=]` 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=]` 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 diff --git a/docs/01_IMPLEMENTATION_PLAN.md b/docs/01_IMPLEMENTATION_PLAN.md index 6e7646b..d5d3afe 100644 --- a/docs/01_IMPLEMENTATION_PLAN.md +++ b/docs/01_IMPLEMENTATION_PLAN.md @@ -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=]` 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=]` 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. diff --git a/docs/12_SIMULATION_POLYGON_PRODUCT_AND_SRS.md b/docs/12_SIMULATION_POLYGON_PRODUCT_AND_SRS.md index cc4e867..bf10a22 100644 --- a/docs/12_SIMULATION_POLYGON_PRODUCT_AND_SRS.md +++ b/docs/12_SIMULATION_POLYGON_PRODUCT_AND_SRS.md @@ -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=]`; its hidden workspace is filtered from -System navigation and no seventh top-level section is added. +command payloads. `?workspace=polygon-run[&run=]` 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 diff --git a/docs/runbooks/SIM_S1C_LIVE_WORKER.md b/docs/runbooks/SIM_S1C_LIVE_WORKER.md index b187acb..2333b8e 100644 --- a/docs/runbooks/SIM_S1C_LIVE_WORKER.md +++ b/docs/runbooks/SIM_S1C_LIVE_WORKER.md @@ -68,13 +68,16 @@ export MISSIONCORE_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=]` 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.