NODEDC_MISSION_CORE/docs/adr/0045-upstream-rerun-canonical-recorded-lab-pipeline.md

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.