docs(observation): document durable sessions and viewer lifecycle

apps/control-station/README.md

@@ -7,9 +7,10 @@ device adapter, но структура интерфейса от него не
 
 Внутри пространственной рабочей поверхности встроен открытый Rerun Web Viewer.
 Это self-hosted frontend-компонент из npm-пакета `@rerun-io/web-viewer`, а не
-переход во внешний облачный интерфейс. При запуске K1 live/replay backend сам
-создаёт Rerun gRPC/proxy source; ручной адрес нужен только для другого Rerun
-потока или совместимой RRD-записи.
+переход во внешний облачный интерфейс. Для K1 live и adapter file-replay backend
+сам создаёт Rerun gRPC/proxy source. Saved observation sessions открывают
+проверенную digest-bound RRD generation через same-origin HTTP; ручной адрес
+нужен только для другого совместимого Rerun source.
 
 ## Текущее состояние
 
@@ -20,11 +21,13 @@ device adapter, но структура интерфейса от него не
 | Локальный control plane | Реализован | React получает состояние и выполняет операции через FastAPI REST и WebSocket на loopback. |
 | K1 BLE → Wi-Fi | Реализован | Реальный BLE-поиск всех видимых устройств и одна подтверждённая provisioning-запись выбранному устройству. |
 | K1 live/replay MQTT | Реализован | Read-only приём, raw-first сохранение, декодирование облака точек и позы, реальные метрики. |
-| Автоматический MQTT → Rerun | Реализован | Первый live/replay поднимает process-wide `RecordingStream` и gRPC/proxy на TCP 9876; следующие сессии сбрасывают сцену и метрики и переиспользуют его. |
+| Автоматический MQTT → Rerun | Реализован | Первый live/adapter file-replay поднимает process-wide `RecordingStream` и gRPC/proxy на TCP 9876; следующие такие сессии переиспользуют его. Saved observation replay использует отдельный immutable HTTP RRD path. |
 | Встроенный Rerun Viewer | Реализован | Self-hosted npm-компонент автоматически открывает текущий gRPC source внутри Control Station; внешний viewer не используется. |
-| Контролы сцены → Rerun | Реализованы для текущей геометрии | Работают размер и видимость точек, атрибут цвета, палитра, окно накопления, траектория и сетка. Проекция, собственный timeline и сохранённые layout-профили ещё не подключены. |
+| Контролы сцены → Rerun | Реализованы для текущей геометрии | Работают размер и видимость точек, атрибут цвета, палитра, окно накопления, траектория, сетка, host timeline и сохранение/восстановление spatial layout. Проекция и семантические слои ещё не подключены. |
+| Сохранённые observation sessions | Реализованы для point/pose | Три последние сессии, background preparation, cache v6, generation-bound RRD, atomic admission, autoplay, play/pause/seek и controlled switching больших записей. |
+| K1 camera preview и archive | Live реализован; recorded contract реализован | Обе RTSP/H.264 камеры физически приняты в live UI. Новые acquisition-owned fMP4 archives не зависят от browser windows; recorded player подключён, но реальная архивная K1 camera-session ещё не прошла physical acceptance. |
 | Legacy Foxglove module | Только regression | Модуль и тесты сохранены для сравнения декодирования. Текущий live/replay runtime не запускает Foxglove WebSocket и не использует TCP 8765. |
-| Камеры, карты и миссии | Интерфейс готов | Серверная логика и реальные каналы для этих рабочих поверхностей ещё не подключены. |
+| Карты и миссии | Интерфейсный каркас | Реальные map/mission backends и vehicle control ещё не подключены. |
 
 Приложение не генерирует демонстрационное облако, траекторию, кадры или
 метрики. Если реальных данных нет, область сцены остаётся пустой, а числовые поля
@@ -48,9 +51,16 @@ Mission Core Control Station ←→ REST /api/v1/device-plugins/*
                          + plugin-scoped WebSocket events
                          FastAPI на 127.0.0.1:8000
                          CoreBluetooth + live/replay runtime
+
+sealed/recovered observation session
+└── SQLite catalog + bounded background preparation
+    └── atomic RRD cache v6 + recorded-media manifest v2
+        └── generation-bound same-origin HTTP
+            └── aggregate admission
+                └── Rerun native receiver + recorded fMP4 player
 ```
 
-В момент готовности `RerunBridge` backend публикует адрес вида
+В момент готовности live/file-replay `RerunBridge` backend публикует адрес вида
 `rerun+http://127.0.0.1:9876/proxy`. Frontend автоматически назначает его сцене,
 если оператор не указал ручной source. После остановки приёма URL и встроенный
 viewer остаются активны, а следующая сессия сбрасывает session-local геометрию,
@@ -65,7 +75,7 @@ viewer остаются активны, а следующая сессия сб
 Shell собран из локальных NODE.DC UI packages и сохраняет одну структуру для
 всех функциональных модулей:
 
-1. `AppHeader` — марка NODEDC MISSION CORE, выбор архитектурного раздела и состояние
+1. `AppHeader` — марка NODE DC, выбор архитектурного раздела и состояние
    локального backend.
 2. `AdminNavigationPanel` — контекст аппарата и список рабочих поверхностей
    выбранного раздела.
@@ -78,8 +88,10 @@ Shell собран из локальных NODE.DC UI packages и сохраня
 blueprint-, selection- и time-панели скрыты, чтобы продуктовые действия жили в
 Control Station. Размер точек, способ окрашивания и палитра, 12-секундное по
 умолчанию накопление, видимость облака и траектории и сетка связаны с backend и
-Rerun Blueprint. Кнопки собственного timeline, смена 2D/3D/карты и сохранение
-layout пока остаются интерфейсным контрактом.
+Rerun Blueprint. Host timeline управляет сохранённым `session_time`, а spatial
+layout сохраняет display settings, tool windows и source-window geometry через
+revisioned API. Смена 2D/3D/карты и семантические слои пока остаются
+интерфейсным контрактом.
 
 ## Архитектурные разделы
 
@@ -139,10 +151,15 @@ cd apps/control-station
 npm run dev
 ```
 
-Vite слушает `http://127.0.0.1:5173` и проксирует весь `/api` (включая WebSocket) на
-`http://127.0.0.1:8000`. Другой локальный backend можно указать переменной
-`VITE_API_TARGET`. Preview production-сборки запускается командой
-`npm run preview` на `http://127.0.0.1:4173`.
+Для полного live-viewer контура Vite должен открыться на
+`http://127.0.0.1:5173`: только 5173, production preview 4173 и backend 8000
+входят в текущий Rerun CORS allowlist. Если Vite сообщает fallback на 5174 или
+выше, освободите 5173 и перезапустите `npm run dev`; REST/WebSocket proxy на
+fallback-порту может работать, но прямой browser → Rerun 9876 будет отклонён.
+Vite проксирует весь `/api` (включая WebSocket) на `http://127.0.0.1:8000`.
+Другой локальный backend можно указать переменной `VITE_API_TARGET`. Preview
+production-сборки запускается командой `npm run preview` на
+`http://127.0.0.1:4173`.
 
 ## Операторский путь для текущего K1 adapter
 
@@ -167,6 +184,9 @@ Vite слушает `http://127.0.0.1:5173` и проксирует весь `/a
 9. Открыть **Наблюдение → Пространственная сцена**. Реальные облако и траектория,
    частота, число точек, задержка и пропуски preview появятся после прихода
    сообщений K1.
+10. После нормального stop или recovery открыть **Сохранённые сессии**. Дождаться
+    состояния **Готово**, выбрать запись и использовать host timeline. Evidence
+    сохраняется автоматически; disk action сохраняет только workspace layout.
 
 В проверочном live-сеансе через этот путь прошло 80 реальных MQTT-сообщений:
 38 кадров `lio_pcl`, 42 кадра `lio_pose`, 2 775 точек в последнем облаке и
@@ -203,9 +223,12 @@ Plasma, grayscale и custom, накопление `0–120` секунд, а т
 декодированном формате. Custom/class сейчас означает выбранный сплошной цвет,
 а не готовую семантическую классификацию.
 
-Custom timeline, переключатель 2D/3D/карты, семантические слои и сохранение RBL
-пока не вызывают Blueprint/playback API. Черновик компоновки фиксируется только
-в памяти текущей страницы и не записывается на диск.
+Для saved session host timeline вызывает Rerun play/pause/seek только после
+полного admission. Accumulation и display settings применяются через отдельный
+маленький blueprint RRD и не заменяют основную запись. Versioned
+`observation.spatial` layout сохраняется на host с optimistic revision; он не
+содержит sensor evidence. Переключатель 2D/3D/карты и семантические слои пока не
+вызывают готовый presentation backend.
 
 ## Контракт локального API
 
@@ -216,6 +239,12 @@ Custom timeline, переключатель 2D/3D/карты, семантиче
 | `GET` | `/api/v1/device-models` | Backend-каталог моделей из валидированных manifests; UI-каталог текущей сборки формируется отдельным static composition root. |
 | `POST` | `/api/v1/device-plugins/{pluginId}/actions/{actionId}` | Namespaced действие через host allowlist; тело `{ "input": { ... } }`. |
 | `WS` | `/api/v1/device-plugins/{pluginId}/events` | Plugin-scoped snapshots с `pluginId` и монотонным `sequence`. |
+| `GET` | `/api/v1/observation-sessions` | Последние cataloged sessions и authoritative preparation state. |
+| `POST` | `/api/v1/observation-sessions/{id}/replay` | Verified replay launch либо HTTP 202 preparation handle. |
+| `GET` | `/api/v1/observation-sessions/{id}/recording-preparation` | Exact-job polling с `If-Match`. |
+| `GET` | `/api/v1/observation-sessions/{id}/recording.rrd` | Immutable generation-bound RRD; arbitrary chunked `send_rrd` не используется. |
+| `GET` | `/api/v1/observation-sessions/{id}/media/{artifact}/...` | Manifest/init/segments записанных камер по opaque identifiers. |
+| `GET`, `PUT` | `/api/v1/workspace-layouts/observation.spatial` | Versioned host layout с optimistic revision. |
 
 Frontend XGRIDS-плагина использует только v1alpha namespaced routes. Старые
 `/api/state`, `/api/events`, `/api/ble/scan`, `/api/connect`, `/api/session/*` и
@@ -257,7 +286,12 @@ facts и старые presentation-поля `phase`, `message`, `devices`,
 | `src/workspaces/DeviceWorkspace.tsx` | Generic выбор модели и `device.connection` slot. |
 | `src/device-plugins/xgrids-k1/` | Реальный K1 BLE/Wi-Fi/live/replay UI, client и compatibility mapper. |
 | `src/workspaces/Workspaces.tsx` | Оперативный обзор, spatial viewport и остальные продуктовые поверхности. |
-| `src/components/RerunViewport.tsx` | Жизненный цикл встроенного Rerun Web Viewer и selection events. |
+| `src/components/RerunViewport.tsx` | Live/recorded lifecycle WebViewer, native RRD open, atomic admission, playback и selection events. |
+| `src/components/ObservationSessionSelect.tsx` | Три последние сессии, состояния `Готово` / `Обработка` / `Ошибка`. |
+| `src/components/RecordedFmp4Player.tsx` | Проверенный generation-bound MSE playback архивных камер. |
+| `src/core/observation/sessionArchive.ts` | Строгий wire contract catalog/preparation/replay/media API. |
+| `src/core/observation/recordedSessionAdmission.ts` | Общий RRD/camera gate до публикации recorded workspace. |
+| `src/core/observation/workspaceLayout.ts` | Versioned spatial layout и optimistic revision. |
 | `src/sceneSettings.ts` | Типизированный UI-профиль пространственной сцены. |
 | `src/presentation.ts` | Vendor-neutral подписи lifecycle и форматирование нормализованных метрик. |
 | `src/styles.css`, `src/styles/*` | Компоновка shell и рабочих поверхностей. |
@@ -277,14 +311,17 @@ facts и старые presentation-поля `phase`, `message`, `devices`,
   случайные GATT writes и автоматические повторы запрещены.
 - MQTT live/replay не публикует команды устройству. Запуск и остановка
   физического сканирования остаются за кнопкой K1.
-- Live-сессии сначала сохраняют сырые сообщения, затем формируют preview. При
-  перегрузке preview может быть отброшен, raw evidence сохраняется.
+- Live-сессии сначала сохраняют сырые сообщения и camera segments, затем
+  формируют disposable preview. При перегрузке preview может быть отброшен,
+  native evidence сохраняется. MQTT durability имеет bounded group-commit RPO,
+  camera durability — текущий незавершённый fragment RPO; это не zero-loss claim.
 - Timeline `capture_time` сохраняет Unix-время приёма сообщения Mac, а окно
   накопления viewer использует session-local `stream_time`. `capture_time` — не
   доказанный timestamp сенсора K1 и не photon-to-screen latency.
-- Панорамный камерный поток в наблюдавшихся MQTT report topics отсутствует;
-  текущая Rerun-сцена содержит только облако точек и позу/траекторию, а
-  операционные метрики отображаются внешней оболочкой Mission Core.
-- `sessions/` игнорируется Git и может содержать адреса, идентификаторы,
-  траекторию и карту помещения. В репозиторий попадают только redacted manifests
-  и безопасная документация.
+- Панорамный камерный поток в MQTT report topics отсутствует; отдельные
+  left/right RTSP preview доступны через generic camera windows. LiDAR и camera
+  сейчас синхронизированы только по host arrival, не по доказанным sensor clocks.
+- `.runtime/`, canonical evidence roots и legacy `sessions/` игнорируются Git и
+  могут содержать адреса, изображения, идентификаторы, траекторию и карту
+  помещения. В репозиторий попадают только код, тесты, redacted manifests и
+  безопасная документация.