From 2f7caf7546892b818aeeba605d7344c489fa70dd Mon Sep 17 00:00:00 2001 From: Daniel Telschow <48818540+Telschow@users.noreply.github.com> Date: Sat, 7 Nov 2026 07:13:00 +0100 Subject: [PATCH] docs(urbannav): state the #298 mechanism as a hypothesis; draft ADR-0046 on sizing the reacquisition inflation Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_011kcqHScTnnxa1dRawTRkzb --- CONSTRAINTS.md | 2 +- ...-inflation-by-the-innovation-covariance.md | 44 +++++++++++++++++++ docs/adr/index.md | 1 + docs/data/metrics.json | 2 +- docs/urbannav.md | 11 +++-- 5 files changed, 54 insertions(+), 6 deletions(-) create mode 100644 docs/adr/0046-size-the-reacquisition-inflation-by-the-innovation-covariance.md diff --git a/CONSTRAINTS.md b/CONSTRAINTS.md index e047062..766c47c 100644 --- a/CONSTRAINTS.md +++ b/CONSTRAINTS.md @@ -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 | 42 ADRs, all in the index | `scripts/metrics.py --check` | +| Docs | README + architecture + calibration + every ADR | 43 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 | diff --git a/docs/adr/0046-size-the-reacquisition-inflation-by-the-innovation-covariance.md b/docs/adr/0046-size-the-reacquisition-inflation-by-the-innovation-covariance.md new file mode 100644 index 0000000..f464ccf --- /dev/null +++ b/docs/adr/0046-size-the-reacquisition-inflation-by-the-innovation-covariance.md @@ -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. diff --git a/docs/adr/index.md b/docs/adr/index.md index ea61b9e..522e139 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -47,3 +47,4 @@ what it cost, and what was rejected. | [ADR-0040](0040-staleness-of-the-nis-windows.md) | Staleness of the NIS windows | proposed | | [ADR-0041](0041-a-correlated-error-term-for-the-gnss-update.md) | A correlated-error term for the GNSS update | proposed | | [ADR-0042](0042-publishing-rows-derived-from-euroc.md) | Publishing rows derived from EuRoC | accepted | +| [ADR-0046](0046-size-the-reacquisition-inflation-by-the-innovation-covariance.md) | Size the reacquisition inflation by the innovation covariance | proposed | diff --git a/docs/data/metrics.json b/docs/data/metrics.json index a4189bd..7ca998a 100644 --- a/docs/data/metrics.json +++ b/docs/data/metrics.json @@ -1,5 +1,5 @@ { - "adr_count": 42, + "adr_count": 43, "coverage_lines_hit": 15550, "coverage_lines_total": 16379, "coverage_percent": 94.94, diff --git a/docs/urbannav.md b/docs/urbannav.md index e50f658..2041be8 100644 --- a/docs/urbannav.md +++ b/docs/urbannav.md @@ -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).