feat(planning): consolidate recorded-route localization and spatial scene

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.

docs/audits/2026-09-19-entry-acquisition.md

@@ -0,0 +1,169 @@
+# Entry acquisition — protocol fixed before execution
+
+This increment implements a bounded initial search separately from local tracking.
+It preserves the failed causal baseline and GICP policy v1. The owner accepts
+roughly 30 s of preparation, but a stale calculation cannot confer current
+localization. There are no hardware commands or autonomous-control authority.
+
+## Frozen experiment v1
+
+- Existing reference A forward 30.012 m, original B receipt-paced 1× input. The
+  old fitted B transform, correspondence mask and future B poses are forbidden.
+- Initial heading still comes from the already observed first >=3 m displacement.
+  Standing-start heading recognition is not added in this increment.
+- 27 initial hypotheses: along/across-entry offsets {-3,0,3} m in the reference
+  route heading basis, times yaw offsets {-15,0,15} degrees. Yaw is applied around
+  the query entry, not the arbitrary map origin. No vertical search.
+- Each seed runs unchanged local GICP v1 (including its <=3 m patch-center
+  correction gate). A final acquisition must also put the query entry inside a
+  5 m horizontal radius, within 1 m vertically, and within 30 degrees of the
+  route-entry/travel-heading hypothesis. This bounds initial search separately
+  from each local optimization; it does not establish a measured capture radius.
+- Group accepted solutions with pairwise entry-position distance <=0.5 m and
+  rotation <=5 degrees. Rank by overlap, then residual. Require >=3 agreeing
+  hypotheses from >=2 distinct translation grid positions. Multiple seeds are
+  robustness checks, not independent observations or a probability of correctness.
+- If any other solution group has overlap within 5 percentage points and RMSE
+  within 0.03 m of the best solution, reject as ambiguous, even if it has fewer
+  seeds. Never accept a partial/timed-out search as unambiguous.
+- One numeric child / CPU thread, 27 seeds per initial search, total internal
+  search deadline 25 s and external child deadline 30 s. Maximum two acquisition
+  attempts per continuous receipt segment, separated by >=10 s on rejection.
+  Replay remains bounded by 120 s / 40 m and existing point limits.
+- A fresh accepted search is only candidate #1. Tracking still needs three fresh
+  compatible causal windows at >=5 s cadence, with the unchanged 8 s freshness,
+  0.5 m / 5 degree continuity checks. Following fits use the previous fresh
+  candidate. Gap, stale result, ambiguity, end of input or an incompatible fit
+  removes current tracking. Failed results never seed subsequent tracking.
+
+## Acceptance and controls
+
+First prove anchor-preserving seeds, known synthetic transform recovery,
+ambiguous repeated geometry rejection, outside-search-bound rejection, budget
+exhaustion and no partial-search acceptance in focused tests. Then run one real
+positive causal trace and negative searches on the already frozen wrong-region
+snapshot A 130–155 m / B causal step 3 and on a query displaced 1000 m with an
+unchanged entry hypothesis. Preserve all attempts and checksum inputs/outputs.
+The far-seed control represents this displacement by adding 1000 m to each
+translation component of the initial transform, with the actual query unchanged.
+All compute probes run sequentially and are bounded functional checks, not load
+tests or qualification of the future onboard computer. No new field capture.
+
+Record first search, first accepted candidate, first 3-window tracking, time spent
+tracking, losses, worker latency/input age, search clusters, replay lateness and
+integrity. Wrong-region acceptance, unexplained position jumps or ambiguity block
+advancement. Success on this pair does not establish pose accuracy or robustness
+across locations. No parameter adjustment after a failing probe without a new,
+explicitly versioned protocol and retained old result.
+
+## Executed evidence
+
+Reference A: JA-SADOVAYA-001, session `20260911T085226Z_viewer_live`, forward
+30.012 m from the immutable run `820571ba-6076-482b-be34-29ceb5328c80`.
+Query B: JA-SADOVAYA-002, session `20260911T134352Z_viewer_live`, raw MQTT and
+original monotonic receipt metadata. Only the reference cloud/path were read
+from the offline artifact; its fitted B transform and query cloud were not used.
+
+Positive run `20260919-acquisition-001`: 2026-09-19T10:54:19.671Z through
+10:55:22.797Z, start monotonic ns 832936970922333. Darwin arm64, Python 3.12.13,
+small_gicp 1.0.1, one numerical child and one CPU thread; 974 causal pose/cloud
+deliveries in 63.126 s, stopped at 40.038 m. Fixed reference preparation took
+0.033 s from the existing artifact and is not raw-map preparation performance.
+
+- First available heading/window: 30.812 s. The original receipt stream has a
+  9.973 s gap and a 10.407 m pose displacement; it was preserved and fenced.
+  Less than 3 m displacement had been available before this gap.
+- Initial search evaluated all 27 hypotheses in 1.984 s inside the worker
+  (2.208 s full worker wall time). Six accepted seeds formed one solution
+  cluster; no alternative eligible cluster. First fresh candidate at 33.033 s,
+  input age 2.221 s. The search used no previously known fitted transform.
+- Three-window consistency first passed at 42.362 s, at the window whose query
+  path length was 22.046 m. Tracking stayed qualified until input ended at
+  63.126 s, when it was explicitly cleared. There was no post-lock real gap in
+  this trace, so recovery after loss was not physically demonstrated.
+
+| Window | Query distance, m | Input time, s | Overlap | Inlier RMSE, m | Input age at completion, s | Temporal state |
+| --- | ---: | ---: | ---: | ---: | ---: | --- |
+| 1, initial search | 13.268 | 30.812 | 98.72% | 0.146 | 2.221 | acquiring |
+| 2 | 17.470 | 35.950 | 98.86% | 0.154 | 0.837 | acquiring |
+| 3 | 22.046 | 42.015 | 98.68% | 0.153 | 0.346 | tracking |
+| 4 | 26.826 | 47.786 | 98.33% | 0.156 | 0.323 | tracking |
+| 5, beyond reference path end | 31.455 | 52.940 | 97.59% | 0.161 | 0.486 | tracking |
+| 6, beyond reference path end | 36.019 | 58.873 | 92.97% | 0.177 | 0.522 | tracking |
+
+Tracking fits took 0.068–0.117 s numerically, 0.263–0.457 s including the worker.
+Maximum replay delivery lateness was 0.184 s; maximum buffer ingestion 0.00332 s.
+Successive accepted transforms differed at the current scanner position by at
+most 0.01494 m and 0.161 degrees. These are consistency measurements, not ground
+truth pose errors. Overlap counts points within 0.5 m; it is not a correctness
+probability. The last two windows test cloud coverage beyond the reference path
+end and must not extend route acceptance. Only windows 3 and 4 demonstrate the
+qualified tracking state while still within the selected 30 m path.
+
+## Negative controls
+
+`20260919-acquisition-controls-001`, 2026-09-19T10:55:45.043Z through
+10:56:19.476Z, used the previously frozen causal step-003 query.
+
+- Wrong region A 130–155 m: all 27 hypotheses evaluated in 7.294 s, no eligible
+  solution cluster, `no-admissible-entry`. No false acceptance on this control.
+- Far initial translation (+1000 m on all axes): 13 hypotheses in 26.801 s;
+  internal soft budget expired between seeds. `incomplete-search`, no candidate.
+  This proves rejection on budget exhaustion, not full search of all 27 seeds.
+
+The original input digests, all 31 positive and 6 control artifacts, and the
+executed source digests were checked again after completion. Private evidence
+is under `data_dir/missions/causal-replays/`; no geometry entered Git. Exact
+sources and the later live-integration source are copied to
+`20260919-acquisition-executed-source-001` with a manifest. Report SHA-256:
+
+- positive: `bf1a8c44e2a9960d06748d7061c19a3ae47e945242896359c57462bc402d3235`
+- controls: `77cb3ca147105439439560649ad4564266f0a53fac4b280a660525e4fac511b2`
+
+## Implementation and validation
+
+`entry_acquisition.py` separates bounded entry search, complete-link solution
+clustering, ambiguity checks and support gates from unchanged local GICP.
+`entry_acquisition_worker.py` isolates the search with a 30 s hard child deadline.
+The acquisition mode in `causal_replay.py` uses it until a fresh candidate exists,
+then seeds local refinement from that candidate. No rejected fit seeds tracking.
+
+The existing `PlanningLiveTests` profile now uses the same entry search and
+`CausalTracking` evaluator. It retains session/generation ownership, bounds the
+attempt count per receipt segment, and records seed and policy provenance.
+Green correspondences require three fresh consistent windows. Gaps, stale input,
+rejection and input end remove green qualification; a final historical worker
+cannot restore current tracking. It still has no scanner or vehicle commands.
+
+49 focused tests passed: entry/causal/live/projects/registration/viewer replay.
+These include synthetic known-transform recovery, ambiguity with unequal support,
+complete-link clustering, anchor-preserving yaw, region/height/angle limits,
+partial-search rejection, prefix-only input, stale/gap fencing and live controller
+integration (one initializer, then two local fits; green only on the third;
+silence expires the result and releases the consumer lease). Ruff passed on new
+and replay files; `git diff --check` passed. One existing Starlette/httpx
+deprecation warning remains. No frontend code or layout changed this increment.
+
+The canonical service was restarted only after verifying idle source, no physical
+scan and no camera recording. On 2026-09-19T11:04:37.611Z the new backend started
+on 127.0.0.1:8000 (PID 60284); `/` and `/api/health` return 200. Nothing listens on
+8765; no numerical children or replay jobs remain. Docker VM was not started.
+The engineering summary, fixed protocol, controls, limitations and acceptance
+checker were saved in MISSIONCOR-81 (34 preserved/appended structured blocks).
+
+## Decision and next stage
+
+The bounded initial search resolves the observed entry-acquisition failure on
+this A/B pair while preserving the previous local-refinement policy. It supports
+continuing the teach-and-repeat research without another capture for this step.
+It does not establish arbitrary-start localization, stationary calibration,
+independent metric accuracy, a reliable 5 m capture radius, or onboard capacity.
+The 8 s freshness and 5 s cadence are diagnostic settings, not navigation limits.
+
+Next isolate recovery and initialization from travel: test deliberate receipt
+loss after tracking and wrong-start/repeated-geometry cases; then develop a
+stationary accumulation/heading hypothesis protocol. Preserve this successful
+trace as a fixed regression. A fresh physical short pass, concurrent camera/UI
+acceptance and qualification on the actual onboard computer follow separately.
+No need for the operator to repeat the route now. Autonomous steering, collision
+avoidance and vehicle-control authority remain outside this increment.