Document back-face filter and angular rate gates; add frame-transform test

- back-face-filter-hld.md: HLD for enabling --filter-normal-facingness 0.1
- lighthouse-protocol-intelligence LLD: Stage 1 back-face filter section,
  updated data flow diagram
- tracking-engine LLD: lc-angular-rate-max and kalman-max-pose-angular-rate
  documented; added to design decisions table
- reflection-rejection.md: update test inventory (6 → 7 tests)
- LPI specs: LPI-PROC-060–066 (back-face filter guards and behavior)
- TE specs: TE-PROC-040–042 (input and output angular rate gates)
- normal_filter_props.c: add SensorNormalBodyToWorldTransform test verifying
  that sensor_normals[] are body-frame and quatrotatevector produces correct
  world-frame normals (90°/180°/identity cases)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: rocketmark

docs/back-face-filter-hld.md

@@ -0,0 +1,128 @@
+# Back-Face Hit Rejection — High-Level Design
+
+**Created**: 2026-04-16
+**Feature area**: Reflection artifact rejection in libsurvive tracking pipeline
+
+## Problem Statement
+
+Lighthouse sweep light reflects off hard surfaces (LED walls, monitor bezels, glass, shiny
+floors) and arrives at tracker sensors from the wrong direction. These reflected hits are
+geometrically consistent — they trace a valid optical path — so libsurvive's existing
+Chauvenet outlier filter and sensor variance gates do not reject them. The Kalman filter
+accepts them, its internal state drifts, and the tracker emits bad poses ("wild
+spinning/freezing") before eventually recovering.
+
+The existing stagehand defenses fire too late:
+
+- **Python reflection filter** (`shtp_receiver.py`): gates bad *output* after the Kalman
+  state is already corrupted. Recovery takes several seconds.
+- **Per-LH innovation gate** (`--light-outlier-threshold 5.0`): catches
+  moderate-to-heavy reflection bursts (rms > 0.001) but cannot distinguish mild
+  reflections (rms 0.0001–0.0002) from legitimate noise — both are within 2× of the
+  noise floor.
+- **Angular rate gate** (`--lc-angular-rate-max`): Kalman-level input velocity gate.
+  Once mild reflections corrupt state, the gate defends the *wrong* state and locks out
+  valid data.
+
+None of these gates can catch reflections that are geometrically correct but physically
+impossible given the tracker's current orientation. Only a geometry-based filter can.
+
+## Goals
+
+1. Prevent reflected lighthouse hits from reaching the Kalman filter by rejecting them at
+   the angle-measurement level.
+2. Eliminate the "spinning/freeze" failure mode caused by mild reflections that slip
+   through the innovation gate.
+3. Zero operator configuration — no manual per-environment threshold tuning beyond the
+   initial deployment value.
+4. No regression on clean tracking (healthy room, no reflective surfaces).
+
+## Target Users
+
+Virtual production operators deploying stagehand in studio environments with LED walls,
+monitor arrays, or reflective surfaces. Operators are not sysadmins — any fix requiring
+environment-specific tuning is a design failure.
+
+## System Architecture
+
+The back-face filter sits at the earliest possible interception point in the libsurvive
+pipeline: `SurviveSensorActivations_check_outlier()` in `survive_sensor_activations.c`,
+called before any angle measurement reaches the Kalman tracker or geometric posers.
+
+```
+USB hardware
+    │  raw photon timestamps
+    ▼
+driver_vive (USB driver)
+    │  LightcapElement
+    ▼
+survive_process_gen1/2
+    │  decoded angle measurements
+    ▼
+SurviveSensorActivations_check_outlier()   ← BACK-FACE FILTER FIRES HERE
+    │  (reject if facingness < 0.1)
+    │  (skip if pose confidence < 0.1)
+    │  (skip if LH not yet calibrated)
+    ▼
+survive_kalman_tracker_integrate_saved_light()
+    │  per-LH innovation gate (light-outlier-threshold)
+    ▼
+Kalman measurement update (IEKF)
+    ▼
+survive_kalman_tracker_report_state()
+    │  angular rate gate (lc-angular-rate-max)
+    ▼
+pose hook → stagehand agent → SHTP → Python reflection filter
+```
+
+The filter is **already fully implemented** in the libsurvive fork as
+`--filter-normal-facingness`. It is currently disabled in stagehand with
+`--filter-normal-facingness -1`. This design activates it.
+
+### Filter Geometry
+
+For each incoming sensor hit `(sensor_id, lh, axis)`:
+
+```
+normalInWorld = quatrotatevector(OutPose.Rot, sensor_normals[sensor_id])
+sensorInWorld = ApplyPoseToPoint(OutPose, sensor_locations[sensor_id])
+towardLH      = normalize(bsd[lh].Pose.Pos - sensorInWorld)
+facingness     = dot(normalInWorld, towardLH)
+
+if facingness < threshold:  → reject (physically impossible hit)
+```
+
+A sensor with its face pointing away from the lighthouse cannot receive direct lighthouse
+light. A reflection arriving from behind cannot be a real hit. Threshold = 0.1 rejects
+sensors pointing more than ~84° away from the lighthouse — the last ~6° near the geometric
+horizon where TS4231 sensitivity is negligible in practice.
+
+## Key Design Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Enable existing impl vs. reimplement | Enable existing (`--filter-normal-facingness`) | Zero new code; implementation is correct, documented, and has property tests. Reimplementing at `angle_process_func` hook would duplicate logic with no benefit. |
+| Threshold | `0.1` (~84° acceptance cone) | Preserves all physically plausible hits; rejects TS4231 edge zone (near-90°) where sensitivity degrades anyway. Geometrically motivated — not empirically tuned. |
+| Relationship to existing gates | Layer (keep all gates) | Defense-in-depth. Back-face filter prevents what the innovation gate cannot see. Innovation gate catches non-geometry anomalies (calibration errors, multipath scatter). Both run. Angular rate gate and Python reflection filter remain as downstream backstops. |
+| Confidence guard threshold | `0.1` (existing default) | Prevents the filter from firing during cold-start before pose has converged — ensures filter activates only when it has a reliable world-frame normal to compare against. |
+
+## Non-Goals
+
+- Replacing the per-LH innovation gate or angular rate gate — these catch different failure
+  modes.
+- Eliminating the Python reflection filter — it handles application-layer burst detection.
+- Per-environment threshold tuning — threshold 0.1 is fixed for stagehand deployments.
+- Handling multipath (multiple-bounce reflections from a front-facing direction) —
+  geometry cannot detect these; the innovation gate handles them.
+
+## References
+
+- [docs/reflection-rejection.md](reflection-rejection.md) — full implementation details
+  (Change 1)
+- `src/survive_sensor_activations.c` — filter implementation
+- `src/test_cases/normal_filter_props.c` — 6 property tests for the filter geometry
+- `stagehand/scripts/stagehand-health` — deployment change (one line: `-1` → `0.1`)
+- [docs/llds/tracking-engine.md](llds/tracking-engine.md) — tracking engine LLD
+  (back-face filter section)
+- [docs/llds/lighthouse-protocol-intelligence.md](llds/lighthouse-protocol-intelligence.md)
+  — Protocol Intelligence LLD (filter hooks into this cluster)

docs/llds/lighthouse-protocol-intelligence.md

@@ -92,6 +92,60 @@ the filter maintains:
 - Timecode of last valid reading
 - Motion detection via gyro/accel/light variance thresholds
 
+The filter is the earliest interception point in the pipeline and runs two
+rejection stages in order before any measurement reaches the Kalman tracker.
+
+#### Stage 1 — Back-Face Normal Filter
+
+A geometry-based pre-filter that rejects sensor hits that are physically
+impossible given the tracker's current orientation. Lighthouse sweep light
+cannot illuminate a sensor whose face points away from the lighthouse; such
+hits are almost certainly specular reflections from hard surfaces (LED walls,
+glass, monitor bezels).
+
+For each incoming hit `(sensor_id, lh, axis)`, the filter computes:
+
+```c
+normalInWorld = quatrotatevector(OutPose.Rot, sensor_normals[sensor_id])
+sensorInWorld = ApplyPoseToPoint(OutPose, sensor_locations[sensor_id])
+towardLH      = normalize(bsd[lh].Pose.Pos - sensorInWorld)
+facingness     = dot(normalInWorld, towardLH)
+
+if facingness < filterNormalFacingness: reject
+```
+
+The sensor normal is stored in the object's local frame (`sensor_normals`
+field); `quatrotatevector` maps it to world frame using the current tracker
+pose. `facingness = 1.0` means the sensor faces directly toward the lighthouse;
+`facingness = 0.0` is the geometric horizon; `facingness = -1.0` is directly
+away.
+
+**Guards** (any failing guard skips the filter entirely, passing the hit):
+- `filterNormalFacingness < -0.5` — disabled (threshold below -0.5 disables)
+- `so->sensor_normals == NULL` — device has no normals data (not all trackers)
+- `so->poseConfidence < filterNormalMinConfidence` — pose not yet reliable
+  enough to trust the world-frame normal computation
+- `!ctx->bsd[lh].PositionSet` — lighthouse not yet calibrated
+
+**Config items:**
+
+| Flag | Default | Description |
+|---|---|---|
+| `--filter-normal-facingness` | `0.0` | Min dot product to accept. `< -0.5` disables. Stagehand deploys `0.1` (~84° cone). |
+| `--filter-normal-min-confidence` | `0.1` | Min pose confidence before filter activates. |
+
+**Property tests:** `src/test_cases/normal_filter_props.c` (6 tests) covers
+`FacingnessInRange`, `FacingnessFlipsWithDirection`, `FacingnessKnownAngle`,
+`FacingnessThresholdMonotonic`, `DirectlyFacingAlwaysAccepted`,
+`BackFacingAlwaysRejected`.
+
+**Reference:** Ported from the simulator path at `src/driver_simulator.c:152–163`.
+The same filter exists there for virtual hardware; this change brings it to the
+real hardware path. See `docs/reflection-rejection.md` (Change 1) for full
+implementation details and `docs/back-face-filter-hld.md` for design rationale.
+
+#### Stage 2 — Chauvenet Statistical Outlier Rejection
+
 Outliers are rejected using the Chauvenet criterion: a new measurement is
 discarded if it falls more than N standard deviations from the running mean,
 where the threshold is configured by `angle-reject-outliers`. This prevents
@@ -226,7 +280,9 @@ survive_disambiguator.c
                    ▼
 
 survive_sensor_activations.c
-    │  outlier rejection, motion detection, validity gating
+    │  Stage 1: back-face normal filter (geometry-based)
+    │  Stage 2: Chauvenet outlier rejection
+    │  validity gating (require both axes per LH)
     ▼
 Tracking Engine (angles + BaseStationCal)
 ```

docs/llds/tracking-engine.md

@@ -257,6 +257,37 @@ the filter from drifting during stationary periods.
 `kalman-light-threshold-var` are rejected before the update step. This prevents
 large outliers (e.g., reflected light, interference) from corrupting the filter.
 
+**Input-level lightcap angular rate gate (`lc-angular-rate-max`):** Before
+accepting a lightcap batch, the filter predicts the pose at the batch timestamp
+and computes the angular distance from the last accepted batch's pose. If the
+implied angular rate (rad/s) exceeds `lc_angular_rate_max`, the batch is
+dropped without updating the Kalman state. This is a pre-update gate — the
+filter state is never touched for rejected batches. After a batch passes, the
+reference rotation and timestamp are updated for use on the next batch.
+
+Config: `--lc-angular-rate-max` (default: disabled). The reference is stored in
+`last_accepted_lc_rot` / `last_accepted_lc_time` in `SurviveKalmanTracker`.
+
+**Note on "defending wrong state":** This gate can lock out valid data if a
+prior reflection batch corrupted the Kalman state before the gate could fire —
+subsequent valid batches appear inconsistent with the corrupted state and are
+themselves rejected. The back-face filter in Protocol Intelligence (`Stage 1`
+of `SurviveSensorActivations_check_outlier`) addresses this by preventing
+reflections from entering the pipeline before the Kalman state can be corrupted.
+
+**Output-level pose angular rate gate (`kalman-max-pose-angular-rate`):** After
+a pose is computed in `report_state()`, the gate compares it to the last
+*emitted* pose. If the angular rate between the two exceeds the threshold, the
+pose is suppressed (not emitted to the application) and `stats.dropped_poses`
+is incremented. Unlike the input gate above, the Kalman internal state is
+already updated when this gate fires — it prevents bad output but does not
+prevent internal state drift.
+
+Config: `--kalman-max-pose-angular-rate` (default: -1, disabled). Reference
+stored in `last_reported_pose_rot` / `last_report_time`.
+
+See `docs/reflection-rejection.md` (Change 2) for implementation details.
+
 **Iterative IEKF updates for light:** Light measurements use the Iterated EKF
 (IEKF) update, which re-linearizes around the current estimate after each step.
 This handles the nonlinearity of the reprojection model and prevents
@@ -469,6 +500,9 @@ Library Infrastructure (pose hooks → application)
 | Adaptive R from residuals | R updated per-measurement from observed residuals | `cnkalman` adaptive R | Sensor noise varies by position, occlusion, reflection; learned R is more accurate than fixed R |
 | Per-LH adaptive R scaling | `lh_var = base_var * max(1.0, lh_res / mean_res)` | `survive_kalman_tracker.c` per-LH batch loop; `light_residuals[lh]` EWMA | Fixed R gives equal Kalman weight to all LHs; miscalibrated LHs pull state proportionally harder with more LHs active, causing jitter that grows with LH count |
 | Per-LH innovation gate disabled by default | `light_outlier_threshold = 0`; threshold of 5.0 recommended | Config item in `survive_kalman_tracker.c` | Gate fires on any anomalous frame; conservative default avoids false positives on new hardware or unusual geometry; opt-in once threshold is calibrated for the environment |
+| Input-level lightcap angular rate gate | `lc_angular_rate_max`; pre-update, drops batch before Kalman touch | `SurviveKalmanTracker.lc_angular_rate_max`, `last_accepted_lc_rot` in header | Prevents high-velocity batches from being applied; pairs with back-face filter — filter prevents the "defending wrong state" failure mode where this gate itself locks out valid data after a corruption |
+| Output-level pose angular rate gate | `max_pose_angular_rate`; post-update, suppresses emission | `survive_kalman_tracker_report_state()`, `stats.dropped_poses` | Guards downstream consumers from sudden pose jumps; Kalman state already updated, so this is a backstop for output quality, not state integrity |
+| Back-face filter as upstream prevention | Geometry check in Protocol Intelligence before Kalman | `SurviveSensorActivations_check_outlier()`, `filterNormalFacingness` | Reflections enter the Kalman pipeline only if the filter misses them; back-face filter eliminates the most common class (impossible geometry) before any downstream gate can be challenged |
 | FLT type (float/double configurable) | All math uses `FLT` typedef | `libs/cnmatrix/include/cnmatrix/cn_flt.h` | Float gives 2× speed on SIMD for acceptable precision; double available for calibration tools |
 
 ## Technical Debt & Inconsistencies

docs/reflection-rejection.md

@@ -280,12 +280,13 @@ Added to the existing `quat_props.c` test suite:
 
 `QuatDistKnownAngle` is the test that caught the swapped-clamp bug.
 
-### `src/test_cases/normal_filter_props.c` — new file (6 tests)
+### `src/test_cases/normal_filter_props.c` — 7 tests
 
 Property tests for the back-facing normal filter geometric invariants:
 
 | Test | Property |
 |---|---|
+| `SensorNormalBodyToWorldTransform` | sensor_normals[] are in body frame: `quatrotatevector(rot, normal_body)` produces the correct world-frame normal for 90°/180°/identity rotations |
 | `FacingnessInRange` | Dot product of unit normal and unit direction is always in `[-1, 1]` |
 | `FacingnessFlipsWithDirection` | `dot(n, d) + dot(n, -d) = 0` |
 | `FacingnessKnownAngle` | Facingness equals `cos(θ)` for sensor at known angle θ from lighthouse |

docs/specs/lighthouse-protocol-intelligence-specs.md

@@ -49,6 +49,16 @@ Prefix: **LPI**
 - [x] **LPI-PROC-052**: The system shall require valid measurements on both X and Y axes for a given lighthouse before passing that lighthouse's data to the Tracking Engine.
 - [x] **LPI-PROC-053**: While the tracked object is in motion (detected via IMU or angle variance), the system shall reset per-sensor running statistics to prevent stale mean values from rejecting valid measurements.
 
+## Back-Face Normal Filter
+
+- [ ] **LPI-PROC-060**: When `filter-normal-facingness` ≥ -0.5, the system shall evaluate each incoming sensor hit against the back-face criterion before any other filtering: compute `facingness = dot(quatrotatevector(OutPose.Rot, sensor_normals[sensor_id]), normalize(bsd[lh].Pose.Pos - sensorInWorld))` and reject the hit if `facingness < filterNormalFacingness`.
+- [ ] **LPI-PROC-061**: When `filter-normal-facingness` < -0.5, the system shall skip the back-face filter entirely and pass the hit to subsequent filtering stages unchanged.
+- [ ] **LPI-PROC-062**: If the tracked object's `sensor_normals` or `sensor_locations` field is NULL, the system shall skip the back-face filter for that object (not all device types carry sensor geometry data).
+- [ ] **LPI-PROC-063**: While `poseConfidence` is below `filter-normal-min-confidence`, the system shall skip the back-face filter (pose not yet reliable enough to compute a trustworthy world-frame normal).
+- [ ] **LPI-PROC-064**: If the lighthouse referenced by the incoming hit does not yet have `PositionSet`, the system shall skip the back-face filter for that hit (lighthouse position needed to compute direction-to-LH).
+- [ ] **LPI-PROC-065**: The back-face filter shall run before the Chauvenet outlier filter so that geometrically impossible hits are rejected upstream, before they influence the per-sensor running statistics.
+- [ ] **LPI-PROC-066**: When `filter-normal-facingness` ≥ -0.5 and a hit is rejected by the back-face filter, the system shall emit a `SV_VERBOSE(105)` log line including the measured facingness, the threshold, and the (lh, sensor_id, axis) triple.
+
 ## Reprojection Model
 
 - [x] **LPI-DATA-060**: The system shall implement the Gen1 reprojection model: `angle = atan2(axis, -Z) - phase - tilt×other_axis - curve×other_axis² - gibmag×sin(angle + gibpha)`.

docs/specs/tracking-engine-specs.md

@@ -40,6 +40,9 @@ Prefix: **TE**
 - [x] **TE-PROC-037**: When tracking is lost (no valid measurements for the configured timeout period), the system shall reset the Kalman state covariance to reflect high uncertainty.
 - [x] **TE-PROC-038**: The system shall scale each lighthouse's observation noise covariance R by the ratio of that lighthouse's EWMA residual to the fleet mean residual, so that lighthouses with above-average residuals receive proportionally less Kalman weight.
 - [x] **TE-PROC-039**: Where `light-outlier-threshold` is > 0, the system shall compute the pre-update RMS innovation for each lighthouse batch and skip that lighthouse's Kalman update for the current sync cycle if the RMS exceeds `light-outlier-threshold × light_residuals_all`.
+- [ ] **TE-PROC-040**: Where `lc-angular-rate-max` is > 0, the system shall predict the Kalman pose at each incoming lightcap batch's timestamp and compute the angular rate implied by the rotation change from the last accepted batch; if the rate exceeds `lc_angular_rate_max` rad/s the entire batch shall be dropped without modifying the Kalman state.
+- [ ] **TE-PROC-041**: When a lightcap batch passes the `lc-angular-rate-max` gate, the system shall update `last_accepted_lc_rot` and `last_accepted_lc_time` to the predicted pose at that batch's timestamp, so subsequent batches are gated against a current reference.
+- [ ] **TE-PROC-042**: Where `kalman-max-pose-angular-rate` is > 0, the system shall compute the angular rate between the current predicted pose and the last emitted pose; if the rate exceeds `kalman-max-pose-angular-rate` rad/s the system shall suppress pose emission for that frame and increment `stats.dropped_poses` without modifying the Kalman state.
 
 ## Kalman Lighthouse Tracker