feat(observatory): add bounded M5.1 session review

2026-08-30 17:29:39 +03:00
parent 81fdf6904a
commit e6a9846167
14 changed files with 1099 additions and 2 deletions
@@ -0,0 +1,93 @@
+# Observatory — product-surface brief
+
+Status: accepted by the product owner for the first M5.1 vertical slice on 2026-08-30.
+
+## Operator and job story
+
+The operator is an engineer qualifying the perception stack before any control authority is put on
+an unmanned platform. After a source session has been recorded, the engineer needs one lightweight
+place to identify that immutable source and see which laboratory results are actually linked to it.
+The first slice is used repeatedly while recordings and results are being produced; it is not a
+mission-planning surface and it never sends navigation, braking or actuation commands.
+
+## Placement decision
+
+The accepted placement is `Тестировочный контур → Обсерватория`, with the operator-facing
+description `Сессии и квалификация`. It is a third workspace alongside the existing
+`Лабораторные контуры` and `Симуляции` entries.
+
+Alternatives considered:
+
+1. Replace or refactor `Лабораторные контуры` in place. Rejected for M5.1 because the current LAB
+   archive is a working, documented legacy projector and rollback reference.
+2. Add an Observatory mode to `Данные → Сессии и записи`. Rejected because that surface owns
+   storage and replay, while Observatory owns the recurring qualification-review job.
+3. Add a dedicated workspace under `Тестировочный контур`. Selected because it creates a clean
+   composition boundary without changing K1, Simulation or the legacy LAB lifecycle.
+
+## Entity, evidence and authority
+
+The source entity is an immutable observation Session. Its visible facts are limited to the
+validated Session catalog contract: identity, timestamps, status, duration, modalities and
+readability. Laboratory evidence is linked only by the typed `lab.sourceSessionId` relationship.
+Source and LAB projections are independent bounded newest-first windows. A LAB result whose source
+is absent from the loaded source window remains unresolved and visible as `вне среза`; it is never
+attached heuristically and its absence is not presented as a broken relationship. Reaching the
+100-item boundary marks historical completeness as unknown until cursor pagination exists.
+
+The presence of a Session or linked LAB result is not a computer-vision pass and is not evidence of
+safe navigation. M5.1 does not infer a verdict from provenance, labels or result kind. The workspace
+is observation-only: command, navigation and safety authority are all absent.
+
+## Viewer-profile boundary
+
+The existing source-specific viewer contracts remain separate and unchanged:
+
+| Source job | Existing profile | Clock / load ownership |
+| --- | --- | --- |
+| Live equipment | `live-acquisition` | `stream_time`; live receiver and recovery authority |
+| Historical Sessions | `recorded-session` | `session_time`; explicit preparation and progressive admission |
+| Legacy LAB evidence | `lab-recorded-evidence` | `source-sequence`; explicit comparison-only loading |
+
+Canonical LAB compositions may configure the recorded Rerun engine inside the bounded LAB slice,
+but that does not make Observatory a LAB or live consumer. The first Observatory slice mounts no
+viewer at all. A later viewer slice may activate only the historical `recorded-session` profile
+after an explicit Session selection and a separate acceptance proof. It must not add a fourth
+profile or silently collapse the three existing lifecycles.
+
+## Information hierarchy and states
+
+1. Catalog authority and refresh state.
+2. Explicit source Session selection.
+3. Selected Session identity, timing, modalities and readability.
+4. Strictly linked immutable LAB evidence.
+5. Fail-visible bounded-window and unresolved-evidence status.
+
+The admitted states are initial loading, ready with items, ready empty, refreshing with the last
+valid snapshot, and unavailable/error with retry. If a selected Session disappears after refresh,
+selection moves to the first valid source or to the empty state. No demo rows, fabricated progress,
+placeholder actions or hidden polling are allowed.
+
+## Design Guideline composition
+
+The existing `ApplicationShell`, `AdminNavigationPanel` and `ApplicationPanel` composition remains
+the owner of navigation and workspace framing. The feature reuses canonical `Select`, `Button`,
+`Icon`, `StatusBadge`, `GlassSurface` and `ActivityIndicator` primitives. The semantic Session and
+evidence projection belongs to `workspaces/observatory`; feature styles own layout only and do not
+introduce a parallel control or surface grammar. The registered `eye` icon identifies the new
+workspace.
+
+## First-slice acceptance
+
+- Polygon navigation order is `Лабораторные контуры → Симуляции → Обсерватория`.
+- Opening Observatory loads only the typed source and laboratory Session catalogs.
+- Opening Observatory mounts no Rerun, canvas, WebGL, RRD, WebSocket or LAB result route.
+- Source and LAB records are joined only by `sourceSessionId`; evidence outside the independently
+  bounded source window remains visible as unresolved and never becomes a false integrity verdict.
+- Reaching either 100-item catalog boundary explicitly marks historical completeness as unknown.
+- The selected source presents at most six newest linked results while retaining the exact total;
+  the historical tail remains in legacy LAB and is never mounted into a long Observatory DOM.
+- Loading, empty, refreshing, error/retry and ready states contain no synthetic data.
+- Linked evidence is never presented as a CV or safety pass.
+- Existing LAB, Simulation, K1 and Data/Sessions code paths remain unchanged.
+- Live, historical Session and legacy LAB viewer-profile contracts remain distinct.