refactor(lab): перевести RAV004 на канонический Rerun pipeline

2026-08-30 12:59:16 +03:00
parent e9ffb829c9
commit f5ee42751d
30 changed files with 1425 additions and 288 deletions
@@ -172,7 +172,7 @@ On the first live or adapter file-replay session, `RerunBridge`:

 At every session start it resets the trajectory, current point count, metrics,
 blueprint and session-local visible time, then feeds the new source through the
-same recording. This process-wide lifecycle is intentional: the Rerun 0.34.1
+same recording. This process-wide lifecycle is intentional: the upstream Rerun 0.36.3
 browser receiver can remain connected after canvas teardown, so restarting the
 native listener on the same port is not a reliable session boundary.

@@ -185,6 +185,15 @@ The evidence slot has two admitted renderers:
 - `diagnostic-model` — a specialized visual result such as the LAB E28 L2.6
  surface/timeline/review viewer.

+ADR 0045 amends the full-session `recorded-replay` transport. A canonical
+recorded LAB uses one unmodified upstream Rerun viewer, recording identity and
+timeline for camera, semantic and spatial evidence. The source RRD owns pose,
+point cloud and trajectory; a digest-bound RRD sidecar may add only immutable
+derived entities which are absent from the source. Model or layer selection is
+a blueprint/profile change, not a new player or renderer. Missing full-route
+TGS, semantic 3D, boxes or cuboids remain disabled instead of being inferred
+from sparse review artifacts.
+
 Recorded camera clips used for review are a frozen sub-contract of the admitted
 viewer, `missioncore.laboratory-recorded-clip-viewer/v1`, implemented by
 `LaboratoryRecordedClipPlayer`. It owns the generation-bound fMP4 manifest,
@@ -197,6 +206,10 @@ Forward frame progression may roll an already-buffered segment target; a
 backward seek or clip loop must perform an explicit decoder seek and remain
 decoder-ready without exposing a per-frame loader.

+That clip contract remains available to historical bounded clip instruments.
+It is legacy comparison transport for a migrated full-session LAB and must not
+be mounted, prefetched or run in parallel with the canonical Rerun profile.
+
 When recorded camera and frame-indexed spatial evidence are both required for
 one review question, the shared player presents them simultaneously on the same
 media clock. The camera remains the clock owner; a bounded experiment-neutral
@@ -160,6 +160,15 @@ history of rejected approaches belong in Ops.

 Primary visual evidence is hosted in one reusable viewer frame.

+For canonical full-session recorded replay, ADR 0045 fixes one native upstream
+Rerun viewer beneath this frame. The accepted product chrome and switching
+logic remain Mission Core UI, while Rerun alone owns playback time, video
+decoding, 2D annotations, point-cloud rendering, trajectory and 3D camera.
+VIDEO/CAMERA, SOURCE POINTS/LOCAL SLAM/TGS COSTMAP/SEMANTICS and 3D/PLAN select
+entities, visible time ranges and blueprints in that mounted viewer. They never
+start independent transports or render loops. A LAB may rename model buttons or
+add an admitted layer button, but it may not change this switching architecture.
+
 ### Frozen Milestone 4 perception instruments

 Milestone 4 admits exactly two operator instruments inside the shared LAB page
@@ -234,6 +243,13 @@ The shared player may retain a rolling target only for the same or a later
 segment. Rewind and clip-loop transitions must seek backward explicitly while
 keeping the admitted generation and decoder owner mounted.

+The preceding fMP4 rule applies to historical bounded clip instruments. A
+migrated full-session recorded LAB instead uses the native Rerun `AssetVideo`
+and `VideoFrameReference` contract from ADR 0045. It must not mount the clip
+player or a custom Three.js scene alongside Rerun. The visual controls and LAB
+template are identical in both cases; the canonical profile determines the one
+active transport.
+
 ### 3D and 2D policy

 Choose the default representation from the operator question:
@@ -0,0 +1,112 @@
+# ADR 0045: Upstream Rerun as the canonical recorded-LAB pipeline
+
+Date: 2026-08-30
+Status: accepted; RAVNOVES004TREE is the first migrated full-route LAB
+
+## Context
+
+The accepted LAB product composition was repeatedly rebuilt over independent
+camera, semantic, point-cloud and TGS transports. The resulting implementation
+had several clocks, LAB-specific caches, a browser MediaSource decoder and a
+separate Three.js spatial renderer. A camera could continue while segmentation
+or the cloud stopped; rewind could expose evidence from different source
+sequences; switching TGS could block both panes. Low host utilization did not
+make that architecture correct: the bottleneck was duplicated admission,
+decoding, scheduling and state ownership.
+
+The product owner requires the existing LAB UI and interaction grammar to stay
+unchanged. VIDEO/CAMERA, SOURCE POINTS/LOCAL SLAM/TGS COSTMAP/SEMANTICS and
+3D/PLAN remain the canonical controls. Models and evidence providers may
+change, but a LAB may not create another player, clock, splitter, spatial
+renderer, window or status grammar.
+
+The repository state before this migration is retained by the annotated Git
+tag `baseline/custom-legacy-before-canonical-rerun-2026-08-30`. Its Russian
+stage name is **«Этап перехода от самописного legacy-контура к каноническому
+шаблонному Rerun-пайплайну»**.
+
+## Decision
+
+Recorded LAB replay uses the unmodified upstream Rerun SDK and web viewer. The
+first accepted dependency is exactly `rerun-sdk==0.36.3` and
+`@rerun-io/web-viewer@0.36.3`. Mission Core does not patch the package, vendor a
+viewer fork or depend on private viewer source. Product controls are an outer
+adapter which requests an ordinary Rerun blueprint.
+
+One native Rerun viewer owns:
+
+- one `session_time` playback clock;
+- the recorded camera and semantic image-space evidence;
+- `/world/points`, `/world/sensor_pose` and `/world/trajectory`;
+- native 3D orbit and top-down plan presentation;
+- seek, play/pause and frame synchronization.
+
+The canonical K1 RRD remains the source of pose, source points, bounded Local
+SLAM accumulation and trajectory. A LAB may publish one immutable normalized
+RRD sidecar containing only derived evidence absent from that recording, such
+as camera video, semantic masks and diagnostic 2D boxes. The base recording and
+sidecar must have the same application id, recording id and timeline. A sidecar
+does not copy, rotate or re-own world geometry.
+
+RAVNOVES004TREE uses a digest-bound sidecar cache. Its sealed fMP4 fragments are
+verified, concatenated and transcoded once to an upstream-compatible H.264
+`AssetVideo`. Source PTS are preserved. A fragment without a decodable sample
+holds the latest preceding frame; decoded samples are never renumbered to a
+synthetic fixed-rate clock. Each semantic mask and `VideoFrameReference` is
+logged at the exact immutable LAB `session_time`.
+
+Profiles control loading rather than creating different viewers:
+
+- source points use zero accumulation;
+- Local SLAM uses a native five-second visible time range;
+- TGS COSTMAP and 3D SEMANTICS are enabled only when full-route immutable
+  artifacts exist and share the recording clock;
+- semantic model buttons select an entity path in the same sidecar;
+- 3D/PLAN changes native eye controls, never point coordinates;
+- layers missing from an immutable result stay visibly disabled and fail
+  closed; they are not reconstructed from sparse review anchors.
+
+The previous fMP4/Three.js LAB transport remains source-retained only for
+explicit legacy comparison. No canonical route selects it, preloads it or lets
+it start background work. Removal is allowed after migrated results pass the
+same acceptance checks and the rollback tag is no longer operationally needed.
+
+## Acceptance
+
+A migrated recorded LAB is accepted only when:
+
+1. the base RRD identity and sidecar identity match exactly;
+2. camera, semantics, point cloud, pose and trajectory follow one Rerun clock;
+3. play, pause, forward seek and backward seek do not remount the viewer;
+4. SOURCE POINTS and Local SLAM are native views of the same sealed geometry;
+5. unavailable TGS or semantic 3D evidence is disabled rather than simulated;
+6. first materialization is cached by source/result/renderer digests and a
+   cache hit performs no decode or inference;
+7. the existing LAB page, selectors, report mode, controls and expand behavior
+   remain unchanged;
+8. Data replay and live Rerun profiles continue to use their own load policies;
+9. the integrated application remains on `127.0.0.1:8000` and no second Mission
+   Core service is introduced.
+
+The isolated renderer materialized the first real RAVNOVES004TREE sidecar in
+79.5 seconds. Under the live operator service, cold materialization completed
+in approximately seven minutes and produced a 393,203,594-byte RRD; this is too
+slow to treat as an interactive open and should be moved to publication-time
+preparation. With a full SHA-256 recheck on every cache hit, the warm product
+endpoint returned headers in 0.89 seconds and streamed the complete local
+artifact in 2.48 seconds. These measurements establish the local cache behavior,
+not a realtime inference or navigation claim.
+
+## Consequences
+
+- Mission Core keeps its product UI without owning media or spatial playback.
+- Rerun can be upgraded through ordinary dependency updates and regression
+  tests instead of reapplying a local patch.
+- New models publish entities and annotations into the same recording contract;
+  they do not add LAB-specific viewers.
+- SLAM clouds and trajectories stay visible through standard Rerun components.
+- Useful native boxes/cuboids may be added as ordinary entity layers when their
+  immutable full-route evidence exists.
+- The migration does not improve DDRNet quality, prove terrain traversability
+  or grant navigation/actuation authority. Those remain separate model and
+  safety acceptance questions.
@@ -6,7 +6,59 @@ Scope: Mission Core recorded LAB replay, RAVNOVES004TREE, OPS perception state

 Excluded: Gaussian/simulation workers and their artifacts

-## Outcome
+Status: the diagnostic findings and perception conclusions remain evidence, but
+the custom fMP4/Three.js implementation described below is superseded by
+ADR 0045. It is retained here as the failure audit, not as the current replay
+contract.
+
+## Current outcome after ADR 0045
+
+RAVNOVES004TREE now uses one unmodified upstream Rerun 0.36.3 viewer for camera,
+semantic masks, diagnostic boxes, source points, bounded Local SLAM, trajectory,
+3D/PLAN and playback. The canonical source RRD owns world geometry; a verified
+immutable RRD sidecar adds only LAB image-space evidence with the same recording
+id and `session_time`. Source PTS are preserved, so missing decodable video
+samples hold the previous frame instead of shortening the route or drifting
+from masks.
+
+The accepted LAB controls and layout remain unchanged. Full-route TGS and
+point-aligned 3D semantics are still absent and therefore remain visible but
+disabled. The former fMP4/Three.js route is comparison-only legacy and does not
+load on the canonical RAV004 route.
+
+The isolated renderer materialized the sidecar in 79.5 seconds. The canonical
+live service cold-path took approximately seven minutes and produced
+393,203,594 bytes, so publication-time preparation remains required before this
+profile is called immediately openable. With a complete SHA-256 check on every
+cache hit, the warm endpoint returned headers in 0.89 seconds and streamed the
+local artifact in 2.48 seconds. This is a replay/cache measurement, not a
+realtime inference claim.
+
+## Current validation after ADR 0045
+
+- frontend unit suite: 661 passed;
+- TypeScript typecheck and production Vite build: passed;
+- migration-scoped backend/API suite: 60 passed;
+- live canonical blueprint: HTTP 200, 86,343 bytes, 0.185 seconds;
+- warm integrity-checked sidecar: HTTP 200, byte-range `RRF2` confirmed;
+- canonical service restarted and healthy on `127.0.0.1:8000`; no Mission Core
+  listener exists on `8765`.
+
+The repository-wide Python suite completed with ten failures in pre-existing K1
+camera-recovery/scenario-reset tests. No K1 runtime or test file differs from
+the rollback tag in this migration. Nine failures are in the existing active
+acquisition camera-restart contract; one is an existing expected-document
+mismatch after the runtime added reset timing. These do not invalidate the
+Rerun-specific checks, but the repository-wide suite is not represented as
+green.
+
+Automated in-app visual QA could not attach to the local address because the
+browser surface rejected the localhost URL under its URL policy. No alternate
+browser-control bypass was used. The live HTTP/data plane, build and contracts
+were accepted; an operator visual pass remains required for the exact layout,
+seek and toggle experience.
+
+## Superseded implementation outcome

 RAVNOVES004TREE no longer owns a custom LAB viewer. It supplies recording and
 model configuration to the same `M4ReplayThreatVisual` and