DCCONSTRUCTIONS
e515ab1b8c
Preserve the completed teach-and-repeat laboratory stage: reference preparation, cascaded acquisition, local tracking and recovery, recording lifecycle, replay qualification, and persistent Rerun scene controls. Document the open grid-picking regression and Rerun upgrade contract. No autonomous driving or loop-closure optimization is claimed.
86 lines
4.0 KiB
Markdown
86 lines
4.0 KiB
Markdown
# 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.
|