feat: finalize corrected-route planning and Rerun recording review

2026-09-22 10:10:03 +03:00
parent c804d89b18
commit 2e5d52521f
132 changed files with 14141 additions and 898 deletions
@@ -0,0 +1,75 @@
+# ADR 0052: Native Rerun grid navigation
+
+Date: 2026-09-21
+Status: implemented and installed; checks and manual acceptance bounds are in the navigation audit
+
+## Decision and authority
+
+The owner accepted the restored recorded cloud quality, then explicitly asked
+to finish navigation: pan the pivot on the grid, orbit around that fixed pivot,
+and zoom independently of the route extent. OPS is updated only after completion.
+
+This is a bounded amendment to ADR 0045's **unmodified web viewer** requirement.
+Rerun SDK, recording format, data, timeline, native renderer and single-viewer
+ownership remain unchanged. The web viewer stays on upstream **0.36.3**, with
+one reproducible, hash-checked source patch. The archived 0.34.1 fork is not
+reactivated. No second camera/renderer, pointer injection or HTTP request per
+gesture is introduced.
+
+## Camera contract
+
+- The native orbital pivot lies on the native `LineGrid3D` plane (XY in the
+  product's world frame). Pan translates the whole camera rig along that plane;
+  orbital rotation leaves the pivot fixed. Scene changes cannot choose a new
+  pivot after operator navigation. The guide grid is not a measured terrain model.
+- Initial fallback height is projected before rendering, not at the start of
+  the first rotation. Active interpolation stops on manual navigation.
+- Zoom changes distance to the pivot. The scene-diagonal zoom-out cap is removed.
+  Upstream's 0.02 m collision-with-pivot guard and a finite 1e17 arithmetic guard
+  remain; these are not route-distance limits. Passing through the pivot would
+  reverse orbital direction, so it is deliberately not implemented.
+- Explicit tracking remains distinct from fixed-pivot inspection. While following,
+  Rerun may move the target with the tracked entity. First-person movement keeps
+  upstream behavior. Reset and plan/3D switches remain explicit preset actions.
+- A read-only native snapshot supplies the last rendered eye to the existing
+  iframe facade. The approximate DOM-input camera journal is removed. Snapshots
+  cross the disposable iframe as copied primitive JSON only; no native handle or
+  listener escapes its lifetime. With no rendered 3D frame, the snapshot is null.
+- Display-only blueprint activation carries that actual native eye. Omitting
+  eye fields resurrects the incoming store's startup camera, as reproduced in
+  browser QA; stable view identity alone is insufficient. This is one snapshot
+  per settings update, not a second input controller or HTTP per gesture.
+- Mission Core admits one active spatial pane per iframe. The snapshot selects
+  the last rendered spatial state of the active recording, ignoring retained
+  states from earlier views. Multiple simultaneous 3D panes would require an
+  explicit view-id argument before that product composition is admitted.
+
+## Build, upgrade and rollback
+
+`vendor/rerun-web-viewer-0.36.3/NODEDC_NAVIGATION.patch` is applied to the pinned
+upstream commit. `scripts/build-rerun-navigation.sh` runs in a bounded temporary
+Worker006 container, not on the 18 GB operator Mac. It tests native camera math,
+uses Rerun's own release/WebAssembly builder and matching JS transformation,
+and emits the paired runtime and declarations. No scanner data enters the build.
+
+`navigation-build.json` binds upstream, source patch, compiler image and artifact
+hashes. The installer validates every input before modifying any package file,
+and rejects an unfamiliar SDK version or wrapper. Fresh installs and production
+builds use that same installer once the candidate is accepted.
+
+An upgrade requires rebasing this patch, native tests, JS/WASM ABI checks,
+frontend contracts and real-browser navigation/regression QA. Do not copy the
+old WASM into a newer SDK. To roll back, disable the installer hooks and restore
+the exact official 0.36.3 package; the facade treats a missing native snapshot as
+unavailable, never fabricates an operator eye. Raw/corrected recordings do not
+need to be regenerated.
+
+## Acceptance
+
+Required: plane/pan/orbit/zoom invariants, different grid plane, top-down and
+first-person regression; exact native snapshot and realm cleanup; normal and
+expanded product views, Escape, explicit reset, layers/point-size updates and
+follow transitions. A successful compile alone is not product acceptance.
+
+The accepted full-fidelity cloud and 30-minute accumulation are outside this
+navigation patch and must not be reduced to make testing cheaper.