Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CONSTRAINTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ the floors themselves are enforced by `scripts/coverage_report.py --ratchet`.
| `outage_sweep.py` coverage | 80% | 98.4% | as above |
| `fdir/nis_monitor.py` coverage | 80% | 98.8% | as above |
| `degrade/` coverage | 50% | 78.0% (`config.py`) / 84.2% (`inject.py`) | as above |
| Docs | README + architecture + calibration + every ADR | <!-- metric:adr_count -->45<!-- /metric --> ADRs, all in the index | `scripts/metrics.py --check` |
| Docs | README + architecture + calibration + every ADR | <!-- metric:adr_count -->46<!-- /metric --> ADRs, all in the index | `scripts/metrics.py --check` |
| Documented tables match the generated benchmark | exact | yes | `scripts/check_doc_tables.py` |
| Open blockers documented | all | see ROADMAP | manual |

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# ADR-0046: Size the reacquisition inflation by the innovation covariance

- Status: proposed
- Date: 2026-11
- Related: [ADR-0006](0006-nis-window-monitor.md), [ADR-0007](0007-spoof-permanence-hysteresis.md), [ADR-0026](0026-urbannav-as-a-real-gnss-dataset.md), [ADR-0041](0041-a-correlated-error-term-for-the-gnss-update.md), [issue #298](https://github.com/Telschow/contested-nav/issues/298)

This record has its context and options. The decision section is the maintainer's to write. No code is written until it is.

## Context

**What was observed. MEASUREMENT, in the committed rows.** On Deep-Urban-1, after the long imposed outage, the filter rejects every returning fix, in both variants and every seed, and never takes the GNSS channel back (`docs/data/urbannav_imposed.csv`, the UrbanNav page). One sequence, one receiver, the reference's own error unknown.

**What a one-seed development diagnosis found. HYPOTHESIS, not in the CSV and not reproduced by code in the repository (issue #298).**

- The first returning fix sits only just outside the gate, and each later one is slightly worse, because nothing is fused.
- The second pass adds a variance of `(NIS / gate) * reacq_sigma_m^2`. With `reacq_sigma_m` at 3 m that is about 10 m^2, against a claimed covariance of thousands of m^2, so NIS barely moves and the re-gate (at most `reaccept_margin` times the gate) fails.
- The fault is declared at the fifth rejection. Clearing it needs ten consecutive consistent fixes, which cannot arrive while nothing is fused.
- `auto_recovery_count`, `reaccept_margin`, `max_drift_sigma_mps` and `max_consecutive_rejections`, changed one at a time, changed nothing. `reacq_sigma_m` at 30 m together with `reaccept_margin` at 1.0 recovered, and that same sigma with the default margin did not.

**Why it is a decision.** The inflation cap is described in `config.py` as a security control: it bounds the trust a persistent spoof can buy. Any change to the sizing weakens or reshapes the same control, and the spoof and slow-ramp studies were run with the present rule.

## Options

(a) Keep the rule. Say the mechanism on the UrbanNav page (done as a hypothesis). Cost: none. The long outage on this sequence stays unrecovered.

(b) Size the inflation from the innovation covariance, so that the inflated innovation can reach the gate, bounded by the drift bound `max_drift_sigma_mps * blind_s`. Behind a flag, default unchanged. Cost: a rule change in `nis_monitor.py`, tests, and a re-run of the spoof, slow-ramp and outage studies to show the control still holds.

(c) A probation rule for a declared fault, one that does not need unfused fixes to be consistent: for example, fuse one fix under a bounded inflation and judge the next. Cost: a new state in the channel machine, and the same re-runs.

(d) Reduce the overconfidence through the outage first, so the fix is not just outside the gate. Related to the correlated-error work of ADR-0041. Larger, and it does not by itself change the rule.

## Decision

To be written by the maintainer.

## Consequences

To be confirmed with the decision. If (b) or (c) is chosen:

- It is behind a flag with the default unchanged, and the existing rows stay byte-identical with it off.
- The spoof, slow-ramp and imposed-outage studies are re-run on development seeds, and the overconfident single-anchor case stays as a control row.
- The settings are declared before any run, and are not tuned on the imposed outages they are scored on.
- No held-out seed is run.
- No runtime dependency changes.
1 change: 1 addition & 0 deletions docs/adr/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,3 +50,4 @@ what it cost, and what was rejected.
| [ADR-0043](0043-camera-imu-extrinsic-and-time-offset-sensitivity.md) | Camera-IMU extrinsic and time-offset sensitivity | accepted |
| [ADR-0044](0044-a-protection-level-from-the-calibrated-covariance.md) | A protection level from the calibrated covariance | accepted |
| [ADR-0045](0045-a-dead-reckoning-horizon.md) | A dead-reckoning horizon | accepted |
| [ADR-0046](0046-size-the-reacquisition-inflation-by-the-innovation-covariance.md) | Size the reacquisition inflation by the innovation covariance | proposed |
2 changes: 1 addition & 1 deletion docs/data/metrics.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"adr_count": 45,
"adr_count": 46,
"coverage_lines_hit": 15550,
"coverage_lines_total": 16379,
"coverage_percent": 94.94,
Expand Down
11 changes: 7 additions & 4 deletions docs/urbannav.md
Original file line number Diff line number Diff line change
Expand Up @@ -653,12 +653,15 @@ error is not known.
is declared faulted, no fix is accepted again, and the horizontal error after the outage is far above the error before
it. The filter does not recover on this sequence.
- **The horizontal error at the end of the outage grows with the length of the outage.**
- What these rows do not say is why the long outage is not recovered from. It could be the reacquisition rule, the
size of the drift against the gate, or a property of this sequence, and no run here separates them. Nor do they say
how a receiver's own outages behave. The oracle variants were not run.
- What these rows do not say is why the long outage is not recovered from. HYPOTHESIS, from a one-seed development
diagnosis, recorded in the proposed ADR on sizing the reacquisition inflation, that is not in the CSV and is not
reproduced by code in this repository: the first returning fixes sit only just outside the gate, the inflation the
reacquisition rule may add is small against the covariance the filter already claims, so they stay rejected, the fault
is declared, and the unfused state drifts further from the fixes. No filter setting was changed in any row above. Nor
do these rows say how a receiver's own outages behave. The oracle variants were not run.

## What follows

The attitude is still the next thing to understand: a better start alignment and a held gyroscope bias were run (section
above) and neither removes the excess. A correlated-error term was run on Deep-Urban-1 with one declared setting and
lowers the overconfidence without removing it (section above). Outages imposed on Deep-Urban-1 were run (section above): the long one is not recovered from, and the cause is not established. See [ADR-0026](adr/0026-urbannav-as-a-real-gnss-dataset.md).
lowers the overconfidence without removing it (section above). Outages imposed on Deep-Urban-1 were run (section above): the long one is not recovered from, and the cause is a hypothesis, recorded in a proposed ADR. See [ADR-0026](adr/0026-urbannav-as-a-real-gnss-dataset.md).
Loading