LiDAR state estimation foundations

[ddol]

Purpose

LiDAR tracking produces jittery, split, and duplicate-identity boxes on real captures. This PR
is the measurement and reference-data foundation the
state estimation plan calls for, plus the fixes
that could be validated without it. It is large — two agents worked this branch in parallel —
and this description reflects the state as merged, not the sequence it was built in.

Changes

Shipped, on by default

• Heading lock ratchet broken (D1.3): a counter now forces a stuck OBB heading to release
  and snap to measurement after repeated rejections, instead of holding forever.
• Fragment guard (D1.5) and ghost-fade decoupling (D1.6): a sub-metre scrap can no
  longer overwrite a track's dimensions or seed a duplicate track on the same vehicle; a
  deleted track's frozen box now fades in ~500 ms instead of 5 s.
• Deterministic DBSCAN subsampling: the over-cap point subsample used to seed from
  time.Now(); it now seeds from the point content, so replaying the same capture reproduces
  the same clusters. This is load-bearing for every measurement below — nothing is comparable
  run-to-run without it.
• Course-alignment and heading-lock telemetry (D1.1, D1.2): |OBB heading - direction of travel|, folded to [0, 90], plus per-track lock-episode outcomes (none /
  never_recovered / relocked / released), replacing a lifetime-only flag that couldn't
  distinguish a genuine trap from a track that already recovered.

Experimental, off by default

• Axis-selection heading test (D2.1, obb_axis_coherence_enabled): chooses between the
  aligned and quarter-turn-swapped interpretation of an observed rectangle against a
  corroborated-maximum extent belief — the largest span several confidently-assigned
  observations have reached, not a running mean (a mean shrinks the object: most views are
  partial). Measured on two captures: median course error improves (42.3->37.3 deg, 36.3->10.7
  deg) but heading acceptance drops ~23 points on both, so it stays off pending D2.2.
• Bounded association shape cost (D2.2, association_extent_cost_weight): converts the
  hard fragment guard into a finite penalty so a genuine partial view isn't forced into seeding
  a duplicate track. Reduces duplicate-identity candidates (overlapping boxes) on both test
  captures, 9% and 44%, but course error moves in opposite directions between them at sample
  sizes too small to trust — stays at weight 0 pending a physical-object reference indepenent
  of predicted track IDs.

Reference-data foundation

• internal/lidar/annotation/: immutable, content-addressed point packs cut from a VRLOG
  (digest-verified, atomic write, refuses to overwrite), plus a revisable sidecar of
  human-reviewed object/mask/pose records. Exists because a tracker's own track IDs cannot be
  the reference for judging that tracker — they split and merge between runs. velocity lidar annotation-export cuts a pack; round-trip, tamper-detection, and proposal/reviewed
  separation are under test.
• internal/lidar/l4bobserve/: early observation-model types (Phase 1 of the state
  estimation plan) — the first step toward persisting what the sensor actually saw, separately
  from the filter's estimate of it.

Phase 0 measurement instrumentation

• Filter consistency baseline: per-speed-band lateral/longitudinal residuals and NIS
  (normalised innovation squared), computed where the Kalman gain already has the innovation
  and its inverse covariance. Published as tracking_baseline.json beside every replay.
  Measured on two site windows: the fixed scalar measurement noise is underconfident at low
  speed (NIS ~0.2-0.8) and overconfident above 5 m/s (NIS up to 20, small samples) — evidence
  for Phase 3's observation-conditioned uncertainty, not just an assumption.
• Debug collector wired: innovations, gating ellipses, and predictions were implemented
  and never enabled; now reachable.

Performance matrix

• Host class as a first-class benchmark dimension (pi / mac / ci): the baseline
  namespace previously had one slot per capture+profile, so a Pi and a Mac collided on the
  same file and the Pi could not be gated without destroying the Mac baseline. Comparisons
  across host classes are now refused rather than silently reported as a regression, with
  per-class thresholds (20%/30%/50%) and repeat counts reflecting each class's actual noise
  floor.
• Pi benchmark runbook: the manual
  procedure for capturing the one matrix cell that answers "fast enough for the sensor" —
  nothing runs it yet, tracked as a backlog item.

Reference client and operator view

• Point-cloud annotation client (tools/visualiser-macos/.../Annotation/): the selection UI
  the annotation packs were always missing. Orthographic lasso and rectangle selection over a
  depth slab against canonical pack indices (never GPU buffer positions), add/subtract,
  stroke-level undo/redo, a second view for the contamination check, operator provenance, and
  dirty-navigation protection. The sidecar writer follows the Go store's revision protocol, so a
  save that cannot prove it edits the snapshot it loaded is refused rather than overwriting
  another writer. 94 Swift tests, with the pack reader tested against bytes the Go writer
  actually produced and pinned on both sides. Selection is through-slab, not hidden-surface
  picking; a radius brush and reviewed propagation remain future work.
• Operator tracks page on the shared scene player: /app/lidar/tracks now renders through
  the same three.js player as the published scenes, driven by a session built over live database
  observations, so seeking, playback and trail reconstruction are one implementation rather than
  two. Track picking and missed-region marking were ported into the 3D view and the 932-line flat
  canvas map deleted, along with the dead background-grid fetch, per-track observation cache and
  overlay-offset controls it had kept alive.

Paper-implementation gap remediation

Three gaps from the gap analysis were
implemented and measured. In each case the measurement contradicted what the gap row
predicted, which is recorded there alongside the numbers.

• Kalman K1 and K2, both opt-in with the shipped defaults unchanged, because neither
  predicted failure mode reproduced. K1's coupled process noise behaves as the maths says but is
  2.7% of the normalised distance to a 2 m/s² manoeuvre against a gate 173x wider, so association
  here is governed by gate width and not the form of Q. K2's premise did not reproduce at all:
  the shipped naive covariance form lost exactly zero symmetry over 10,000 cycles with
  adversarial noise. They are Go-level options rather than tuning keys on purpose — a new tuning
  key moves the config fingerprint and would invalidate the committed perf baselines before
  anyone had measured whether the change helps.
• OBB numerics P1 and P2: the estimator handles every degenerate input correctly, but L5's
  Guard 2 — which exists to refuse an ambiguous heading from a near-square cluster — guarded its
  division with maxDim > 0 and so skipped the check entirely for a zero-extent box, accepting
  the most ambiguous measurement while correctly refusing a 5 cm square. P2's wrong-answer
  fallback branch is removed rather than corrected, by computing the discriminant as the
  non-cancelling (c00-c11)² + 4c01².
• HW1 sensor noise, measured with a new lidar-closeness-audit against 367 deployed
  background snapshots and 24,007,669 settled cells: the sensor beats its own specification in
  situ (median spread 6 mm close in, 47 mm past 100 m), while the modelled noise term supplies
  86-98% of the acceptance window against the measured spread's 1.5-5%. The median effective
  window reaches 1.11 m at 10-20 m and 8.99 m past 100 m. A follow-up ring-elevation pass
  disconfirmed the obvious explanation for the tail: the rings reporting the most foreground
  carry the fewest wide-spread cells, inverting the feedback-loop prediction. The detection
  cost is not measured and is filed as a backlog item.

Phase 2 measurement model

• Synthetic Pandar40P pass promoted into l4perception as the seed of the evaluation corpus,
  so Section 3's evidence is reproducible in the repository rather than living in a scratchpad.
  It records one correction to the plan: §3.1's stated ring band cannot see its own vehicle for
  most of the pass, so the generator fires the real hardware elevation table and reproduces the
  mechanism — the medoid pinned at exactly -0.900 m, W/2, on 20 of 40 frames — rather than
  §3.2's per-frame figures.
• Near-edge measurement model with Section 9.1's variable-rank measurement, which is the
  property the plan identifies as missing: one visible face constrains its own normal and leaves
  the perpendicular direction to the prediction untouched, with a covariance tight along the
  constraint and effectively unbounded across it. Lateral error against the synthetic pass is
  0.0000 m mean and max, against the OBB centre's 0.1391 m and 0.8038 m. Its bias is exactly the
  dimension-prior error one-for-one, which is what makes the solid body's per-dimension sigma and
  provenance load-bearing rather than decorative.
• Solid-body estimate contract (Section 5.4): named physical reference point, the filter's
  own covariance block, a bimodal orientation belief carrying the 180-degree ambiguity explicitly
  rather than resolving it with a guard, per-dimension beliefs with sigma and admissible-frame
  counts, motion class as a posterior, and the estimation lifecycle. ProjectSurface returns
  unavailable — for suppression, never substitution — whenever pose, heading and dimensions
  cannot be bounded together. Seeding states the medoid's known bias, ~0.95 m for a vehicle,
  where the measurement noise would have claimed ~0.22 m about a position that may be a metre
  out. Not yet wired into the live pipeline.

Experiment E1: the question this branch existed to answer

Run against all three corpus sites: 43,068 scored frames matching the committed Phase 0/1
baseline exactly, 195,389 immutable observations, 160,011 linked estimates, every site
repeat-verified byte-identical.

E1.1, the decisive conditional-mean-by-aspect test, confirms Section 3's hypothesis. The
medoid's lateral offset is near zero end-on and rises monotonically toward broadside, to 0.35-0.41
of the body's half-width, at all three placements; the near-edge candidate stays flat and of
opposite sign. E1.3 agrees independently at 0.58-0.65 of a half-width, needing no fit and no truth.
The trend survives range stratification in every well-populated cell, which is the
discriminator that separates a geometric bias from the P11 grade confound — and it is as strong at
the flattest placement (0.14% grade) as the steepest (4.35%).

So the defect is in the measurement definition and no estimator can filter it out, which is what
Phase 2 was predicated on. A sign bug in the first E1.3 implementation initially inverted its
conclusion by letting vehicles passing on opposite sides cancel; E1.1's independent reference
exposed it, and that is recorded rather than quietly fixed. Full record, including three limits
stated rather than implied — no ground truth in this corpus, the OBB centre's circularity, and an
empty ground-clipped stratum:
E1 lateral-error record.

Known gaps (tracked, not blocking on their own)

• mac/ci perf baselines are stale Resolved. The mac baselines are recaptured and
  make test-perf-all passes both gated profiles. Diagnosed before recapturing, since recapturing
  a refused baseline on sight risks enshrining a regression: the committed file recorded a workload
  the branch does not produce (1,611,256 foreground points against an actual 985,224), and the
  branch's actual workload matches main's baseline to within one cluster, so nothing had
  regressed and the stale file had captured a transient intermediate state. No pi baseline
  exists yet; that is the runbook item below.
• D2.1/D2.2 cannot be finished without a physical-object annotation independent of predicted
  track IDs. The selection UI that blocked this now exists (see the annotation client above), so
  what remains is operator hours rather than engineering: reviewed masks across a site's
  keyframes, then the frozen object-disjoint dataset splits.
• E1.2 (straight-segment residual spectrum with autocorrelation) and E1.4 (stationary noise
  floor, the one place real data supplies an exact expected value) are not yet run; G-GEO-1 needs
  both plus held-out geometry, excursion and fragmentation criteria.
• No dependency-free lidar-bench binary for the Pi (native build only); no scheduled Pi run.
• Two config-schema fixture gaps (missing required keys in config-validate/config-migrate
  test fixtures after schema additions) were found and fixed in this branch's own history —
  flagging the pattern: a strict schema addition needs every inline test fixture updated in
  the same commit, and make test-go alone did not always catch it (stale test cache).

Checklist

• Uses British English spelling/wording where applicable.
• Design is confirmed and aligns with DESIGN.md.
• Any maths/derived values are valid and up to date.
• Version has been bumped where required.
• Documentation is up to date. (plans, backlog and gap analysis current; perf baselines
  recaptured; E1 recorded)
• README.md is up to date.
• docs/DEVLOG.md is up to date.

🤖 Generated with Claude Code

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

🔵 Needs a closer look

It makes safety-relevant state-estimation/tracker behaviour changes across many packages while being labelled documentation-only, so it needs human verification of correctness, tuning safety, and the mislabeled scope.

Review details

• Files reviewed: 52/55 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

The change is large and cross-component (config schema, tracking, clustering, sweep objective, perf harness), the shown diff is only a subset of the actual runtime changes, and the description understates the scope, so it needs human review.

Review details

• Files reviewed: 122/127 changed files
• Comments generated: 1
• Review effort level: Balanced

[github-actions]

🤖 Version Bump Advisory

Warnings

⚠️ Database migration detected

• Files: internal/db/migrations/000047_lidar_observations.up.sql,internal/db/migrations/000048_lidar_track_estimates.up.sql,internal/db/migrations/000049_lidar_track_residuals.up.sql
• Review for breaking changes (MAJOR) vs additive changes (MINOR)

Version Updates

✅ Radar: 0.5.1-pre33 → 0.5.1-pre34

---

📖 See CHANGELOG.md for detailed guidelines.

This is an automated advisory. Review the detected changes and update versions accordingly.