docs(observation): document durable sessions and viewer lifecycle

This commit is contained in:
DCCONSTRUCTIONS
2026-07-17 17:55:39 +03:00
parent e94c64eebd
commit f9ffb7bd1c
11 changed files with 904 additions and 100 deletions
+39 -11
View File
@@ -17,6 +17,9 @@ already exist. The accepted device-lifecycle decision is recorded in
| `src/k1link/protocol/` | Firmware-scoped K1 codecs and explicit vendor normalizer | Plugin-owned protocol adapter |
| `src/k1link/data_plane/` | Transport-neutral decoded in-process consumer views | Local projections hydrated from portable SDK envelopes |
| `src/k1link/viewer/` | Rerun consumer, visualization runtime and legacy Foxglove regression module | Replaceable canonical scene sink and presentation adapters |
| `src/k1link/sessions/` | Host-owned SQLite catalog, evidence discovery/recovery, background preparation and derived-cache lifecycle | Device-neutral observation archive service |
| `src/k1link/web/session_api.py` | Opaque saved-session, immutable RRD/media and workspace-layout API | Versioned Control/Edge observation contract |
| `apps/control-station/src/core/observation/` | Session selection, replay admission, recorded-source and layout state | Device-neutral observation UI runtime |
| `docs/domain-model/` | Versioned experimental Mission Core vocabulary | Promotion source for meanings proven across devices/services |
## Implemented boundary
@@ -33,6 +36,17 @@ raw K1 transport
-> embedded local viewer
```
The host-owned recorded path is separate from the disposable live preview:
```text
sealed or recovered native observation session
-> SQLite catalog and bounded single-worker preparation
-> atomic RRD cache v6 + immutable recorded-media manifest v2
-> generation-bound same-origin HTTP
-> aggregate RRD/camera admission
-> native Rerun HTTP receiver + recorded fMP4 player
```
Rerun does not import K1 protocol code, inspect MQTT topics or receive raw
payloads. `VisualizationRuntime` cannot choose a vendor decoder implicitly; its
composition owner injects one. The local `Decoded*View` classes are in-process
@@ -52,6 +66,8 @@ The local vocabulary distinguishes:
```text
model != device != transport alias != device session
acquisition != operation != source/channel != evidence
observation session != preparation job != replay launch != viewer instance
workspace layout != sensor evidence
acknowledgement != completion
raw evidence != decoded data != viewer state
```
@@ -103,10 +119,14 @@ by physical double-click; no modeling request is published.
Left/right camera preview transport, endpoint paths and H.264 framing are now
observed under the exact compatibility profile. The local read-only adapter
copy-remuxes one selected RTSP producer into bounded fMP4/WebSocket delivery for
the generic MSE UI. Portable FFmpeg packaging, fan-out and remote delivery remain
open. Device status and heartbeat remain raw observed channels without semantic
decoders. Device calibration command and sensor-to-vehicle extrinsics are
unavailable.
the generic MSE UI. New acquisitions archive selected-camera init/segments/index
independently of browser delivery. The generic recorded player, manifest-v2
validation and shared `session_time` controls are connected; historical sessions
created before this archive contract contain no recoverable video, so physical
recorded-camera acceptance remains open. Portable FFmpeg packaging, disk-backed
browser buffering, fan-out and remote delivery also remain open. Device status
and heartbeat remain raw observed channels without semantic decoders. Device
calibration command and sensor-to-vehicle extrinsics are unavailable.
The 2026-07-17 physical acceptance gate confirmed continuously updating point
clouds, a matching live trajectory, and both camera selections in the same
@@ -128,14 +148,17 @@ for the measured gate and remaining limits.
5. Replace compatibility routes and singleton state with multi-device session
routing.
6. Split Edge execution from the Control Station behind authenticated transport.
7. Package the read-only RTSP/H.264 camera adapter for each target OS and evolve
same-host MSE delivery toward an authenticated Edge media plane; keep the
modeling-command publisher disabled until its separate safety gate closes.
7. Physically accept a newly archived left/right K1 session, then package the
read-only RTSP/H.264 adapter for each target OS, add disk-backed sealed media
caching and evolve same-host MSE delivery toward an authenticated Edge media
plane; keep the modeling-command publisher disabled until its separate safety
gate closes.
## Invariants
- Raw evidence is persisted before preview work and is never overwritten by a
decode result.
- Raw bytes are appended and OS-flushed before preview work; aligned raw and
metadata become durable together at the bounded group-commit boundary and
are never overwritten by a decode result.
- Mission Core starts when the XGRIDS manifest is absent. Formal installed
plugin quarantine remains a future supervisor feature.
- Core code does not branch on XGRIDS IDs, fields, topics or firmware.
@@ -160,8 +183,13 @@ for the measured gate and remaining limits.
- complete SDK-envelope/EvidenceStore hot-path integration;
- remote Edge split, authenticated WAN relay and fleet orchestration;
- automatic K1 start/stop/calibration commands;
- automatic camera capability discovery, synchronized recording/rewind,
calibration, panoramic stitching and multi-consumer delivery.
- device-reported camera capability discovery beyond the reviewed K1 profile;
- physical acceptance of shared-timeline recorded-camera playback on a newly
archived K1 session;
- frame-accurate camera/LiDAR calibration, panoramic stitching, disk-backed
browser media cache and remote multi-consumer delivery;
- production retention, replication, encryption and long-run WebViewer/WASM
memory acceptance for large observation sessions.
## Workspace-repeatable locked architecture gate