docs(observation): document durable sessions and viewer lifecycle

README.md

@@ -10,9 +10,11 @@ The first proven hardware vertical is the XGRIDS/LixelKity K1 plugin. On firmwar
 3.0.2 the host provisions the scanner onto an existing LAN without LixelGO,
 connects to its MQTT broker, persists each raw frame before preview work, decodes
 point cloud and pose, and renders the real cloud plus trajectory through an
-embedded self-hosted Rerun Web Viewer. Capture files are `fsync`ed on clean
-close; per-frame power-loss durability is not claimed. The former Foxglove
-bridge remains only as a legacy regression module.
+embedded self-hosted Rerun Web Viewer. Native MQTT persistence uses bounded
+group commit (at most 0.5 seconds, 4 MiB or 32 messages), and camera archives
+commit complete fMP4 segments before their index rows. These are explicit
+crash-RPO bounds, not a zero-loss or disk-replication claim. The former
+Foxglove bridge remains only as a legacy regression module.
 
 The repository is intentionally migrating in stages. The current `src/k1link`
 package is the compatibility implementation of the first plugin path; vendor
@@ -124,19 +126,24 @@ revision or content hash. Publishing/vendoring those packages or enforcing an
 immutable donor revision remains a packaging and CI prerequisite.
 
 The Observation spatial workspace embeds the open-source Rerun Web Viewer
-inside the Mission Core shell. It can open a compatible RRD file over HTTP(S) or a
-Rerun gRPC/proxy source such as `rerun+http://127.0.0.1:9876/proxy`. It does not
-use an external hosted viewer UI. Dynamic point-cloud and camera source
-composition, host-owned window layout and the current live-only timeline contract
-are fixed in [`ADR 0006`](docs/adr/0006-vendor-neutral-observation-sources-and-live-only-timeline.md).
+inside the Mission Core shell. It can open a compatible RRD over same-origin
+HTTP or a Rerun gRPC/proxy source such as
+`rerun+http://127.0.0.1:9876/proxy`; no external hosted viewer UI is used.
+Dynamic point-cloud/camera composition and the live source contract are fixed in
+[`ADR 0006`](docs/adr/0006-vendor-neutral-observation-sources-and-live-only-timeline.md).
+The durable session catalog, recorded `session_time` scrubber and versioned
+workspace-layout profile are fixed in
+[`ADR 0008`](docs/adr/0008-durable-observation-sessions-and-workspace-layout.md).
 
-The first K1 live session or replay in a `k1link serve` process creates one local
-Rerun `RecordingStream`, starts its gRPC/proxy server on TCP 9876 and publishes
-the resulting URL through control-plane state. Later sessions reset their
-session-local scene and metrics and reuse that process-wide stream; this avoids
-restarting the native listener while the embedded browser remains connected.
-Unless an operator has entered a manual source, the React application assigns
-that URL to the embedded viewer. The complete runtime path is K1 MQTT → raw-first
+The first K1 live session or adapter file-replay (`.k1mqtt`/reviewed TSV) in a
+`k1link serve` process creates one local Rerun `RecordingStream`, starts its
+gRPC/proxy server on TCP 9876 and publishes the resulting URL through
+control-plane state. Later live/file-replay sessions reset their session-local
+scene and metrics and reuse that process-wide stream. Saved observation sessions
+do not reuse this listener: they open a private digest-bound RRD generation over
+same-origin HTTP through Rerun's native incremental receiver. Unless an operator
+has entered a manual source, the React application assigns the applicable source
+to the embedded viewer. The complete live runtime path is K1 MQTT → raw-first
 evidence capture → bounded latest-wins preview queue → explicitly injected K1
 protobuf/LZ4 normalizer → transport-neutral decoded local views → Rerun
 `Points3D`, `Transform3D` and `LineStrips3D` → embedded Web Viewer. Rerun does
@@ -146,15 +153,21 @@ portable Plugin SDK wire envelopes.
 The default Rerun blueprint shows a 12-second sliding accumulation of real point
 frames. Product controls are connected for point size, intensity/height/distance
 or available RGB coloring, Turbo/Viridis/Plasma/grayscale/custom palettes,
-point and trajectory visibility, and the scene grid. Projection, custom
-timeline transport and saved layout remain later product work. No synthetic
-point cloud, trajectory, camera frame or latency value is generated.
+point and trajectory visibility, and the scene grid. The first disk action saves
+and restores the versioned spatial layout without mutating sensor evidence.
+Saved native point/pose sessions are materialized losslessly into private,
+digest-bound RRD recordings and can be played, paused and scrubbed on a
+zero-based `session_time` timeline. No synthetic point cloud, trajectory,
+camera frame or latency value is generated.
 
 A powered-device checkpoint passed 80 real MQTT messages through the current
 Rerun runtime: 38 point-cloud frames, 42 pose frames, 2,775 points in the last
-cloud and zero decode errors. The later RTSP camera preview is not yet wired into
-the Rerun/runtime path. Rerun `capture_time` is the Mac receive timestamp, not a
-proven K1 sensor timestamp or photon-to-screen measurement.
+cloud and zero decode errors. The later RTSP camera preview is available through
+the generic floating observation windows and new acquisitions archive its fMP4
+segments independently of browser delivery. Historical sessions recorded before
+that archive contract contain no video. Rerun `capture_time` and the camera
+index use Mac receive/arrival timestamps, not proven K1 sensor timestamps or a
+photon-to-screen measurement.
 
 The old Foxglove implementation is retained only in
 `src/k1link/viewer/foxglove_bridge.py` and its regression tests. The current
@@ -162,6 +175,8 @@ live/replay runtime does not start it or use TCP 8765. The
 [live viewer runbook](docs/06_K1_LIVE_VIEWER.md) records the active Rerun path and
 its timing/security boundaries; the frontend contract is documented in
 [`apps/control-station/README.md`](apps/control-station/README.md).
+The host storage layout, recovery rules, replay API and operator path are in
+[`docs/09_OBSERVATION_SESSIONS.md`](docs/09_OBSERVATION_SESSIONS.md).
 
 The FastAPI application and credential endpoint bind to loopback, but the Rerun
 gRPC server currently binds TCP 9876 on all network interfaces even though its
@@ -214,9 +229,15 @@ present.
 - [Verified MQTT stream profile](docs/05_K1_MQTT_STREAM_PROFILE.md)
 - [Live console and embedded Rerun runbook](docs/06_K1_LIVE_VIEWER.md)
 - [Mission Core monorepo and plugin boundary](docs/07_MISSION_CORE_MONOREPO.md)
+- [Owner-controlled LixelGO/iPhone observation](docs/08_LIXELGO_IPHONE_OBSERVATION.md)
+- [Observation sessions, playback and workspace layout](docs/09_OBSERVATION_SESSIONS.md)
 - [Monorepo architecture decision](docs/adr/0002-mission-core-monorepo.md)
 - [Device plugin UI and runtime boundary](docs/adr/0003-device-plugin-ui-and-runtime-boundary.md)
 - [Plugin SDK v0alpha2 and experimental device lifecycle](docs/adr/0004-plugin-sdk-v0alpha2-and-experimental-device-lifecycle.md)
+- [Owner-controlled LixelGO observation decision](docs/adr/0005-owner-controlled-lixelgo-iphone-observation.md)
+- [Vendor-neutral live observation sources](docs/adr/0006-vendor-neutral-observation-sources-and-live-only-timeline.md)
+- [K1 camera preview copy-remux gateway](docs/adr/0007-k1-camera-preview-copy-remux-gateway.md)
+- [Durable observation sessions and workspace layout](docs/adr/0008-durable-observation-sessions-and-workspace-layout.md)
 - [Redacted live lab report](docs/lab/001_K1_LIVE_MQTT_20260715.redacted.md)
 - [Session manifest schema](schemas/session-manifest.schema.json)
 - [Reference input provenance](docs/reference/README.md)
@@ -240,6 +261,6 @@ reviewed step. Random writes, fuzzing, brute force, firmware operations,
 destructive file access and credential guessing remain out of scope.
 
 Real captures, projects, router metadata, serials, credentials, maps, images,
-and logs are ignored by normal Git. Redacted manifests and SHA-256 inventories
-are committed; encrypted artifact storage will be selected only when real data
-exists.
+and logs under `.runtime/`, canonical evidence roots and legacy `sessions/` are
+ignored by normal Git. Redacted manifests and SHA-256 inventories are committed;
+encrypted/replicated artifact storage remains a deployment decision.