NODEDC_MISSION_CORE/docs/audits/2026-09-20-planning-browser-presentation-telemetry.md

Planning browser-presentation telemetry — 2026-09-20

Purpose

Instrument the time from a fresh planning cloud package reaching the browser to its admission by the existing native Rerun channel and two subsequent browser animation-frame opportunities. The purpose is to investigate the operator's observation that a new cloud appears substantially slower than an ordinary session cloud, without changing registration, route following, device control, or the visible LAB surface.

Exact boundary

The browser reports one bounded, best-effort sample only after:

1. channel.send_rrd has resolved for a live cloud package;
2. one browser animation frame has run (or timed out after 500 ms); and
3. a second browser animation frame has run (or timed out after 500 ms).

The report stores metric summaries and at most 4,096 in-memory samples for the selected run. Browser posts contain at most eight samples, have no retry queue, and use an exact run_id, display_epoch, cloud revision, and cloud sequence fence. A stale, terminal, or foreign packet is ignored. The final run report receives only the summary.

source_to_second_animation_frame_upper_bound_ms is deliberately conservative: server-reported cloud age + browser request time + Rerun admission duration + post-admission two-frame delay.

This is not proof of a GPU canvas-paint receipt, physical scanner-to-pixel clock synchronization, registration truth, route-following quality, navigation, or safety authority.

Implementation

• apps/control-station/src/core/missions/planningSceneStream.ts forwards the exact live display identity and holds the native cadence until the bounded delivery callback finishes.
• apps/control-station/src/components/missions/PlanningLiveScene.tsx records the browser-side admission/two-frame proxy without adding controls, panels, labels, or debug UI.
• apps/control-station/src/core/missions/planningPresentationTelemetry.ts batches bounded best-effort browser reports.
• src/k1link/web/planning_live_api.py, src/k1link/missions/live_tests.py, and src/k1link/missions/planning_browser_presentation.py validate, fence, and summarize those reports.

Existing physical context

The operator deliberately starts the scanner about 1–3 m away from the prior start and walks an offset trajectory. In the registered reference frame, the two accepted repeat runs do not collapse into one exact line:

Run	Measured path	nearest-route median	nearest-route p95
ja-sun-006	35.30 m	1.12 m	3.11 m
ja-sun-007-100m	102.59 m	0.95 m	1.23 m

The transformed path origins are about 0.79 m and 0.65 m from the reference route start, and about 0.51 m apart in XY. Those figures support that the recorded passes are not identical traces, but they cannot independently survey the operator's physical 1–3 m offset because registration maps each query into the reference frame.

Verification and deployment

• pytest -q tests/test_planning_fast_display.py — 4 passed.
• Focused frontend streaming/reporter tests — 8 passed.
• npm run typecheck — passed.
• npm run test:unit — 871 passed.
• npm run build — passed (only the established chunk-size warning).
• Planning Python suite rerun — 13 passed. One earlier stationary-start timing assertion was repeated successfully; it does not cover this reporter path.
• Canonical LaunchAgent reloaded only after the selected run was terminal. Health is ok, exactly one listener is bound to 127.0.0.1:8000, no listener is bound to 8765, and the new observation endpoint is mounted.

Next physical check

Run a fresh planning pass using the normal deliberate offset; no special placement, UI mode, or debug control is needed. A 30–40 m repeat is enough to validate recording and inspect the new report. Keep the Planning scene open; after the run finishes, review sample count, request/admission/frame percentiles and frame-timeout count alongside the already existing registration evidence.