[AZ-232] Add safety anchor state machine

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-03 19:10:10 +03:00
parent 7819ae7a38
commit 9fb9e4a349
8 changed files with 388 additions and 7 deletions
@@ -1,97 +0,0 @@
# Safety Anchor State Machine
**Task**: AZ-232_safety_anchor_state_machine
**Name**: Safety Anchor State Machine
**Description**: Own authoritative localization state, confidence, anchor fusion, degraded modes, tile-write eligibility, and MAVLink output semantics.
**Complexity**: 5 points
**Dependencies**: AZ-223_camera_ingest_calibration, AZ-224_mavlink_gcs_gateway, AZ-227_fdr_event_recorder, AZ-228_vio_adapter, AZ-231_anchor_verification_matching
**Component**: Safety And Anchor Wrapper
**Tracker**: AZ-232
**Epic**: AZ-216
## Problem
The product needs one safety authority that converts VIO, telemetry, camera quality, and anchor evidence into honest localization outputs and degraded/failsafe behavior.
## Outcome
- Wrapper updates localization state from VIO and anchors.
- Covariance grows honestly in degraded modes.
- `GPS_INPUT` semantics, source labels, and tile-write eligibility are controlled by the wrapper.
## Scope
### Included
- VIO update handling.
- Anchor acceptance/rejection integration.
- IMU-only degraded propagation.
- Covariance/source-label/fix-type behavior.
- Tile-write eligibility decisions.
### Excluded
- VIO backend internals.
- MAVLink transport implementation.
- Generated tile writing.
## Dependencies
### Document Dependencies
- `_docs/02_document/contracts/shared/runtime_contracts.md`
- `_docs/02_document/contracts/shared/geometry_time_sync.md`
- `_docs/02_document/contracts/shared/config_errors_telemetry.md`
## Acceptance Criteria
**AC-1: VIO state updates position estimate**
Given valid VIO state and telemetry context
When the wrapper processes the update
Then it emits an estimate with source label and honest covariance.
**AC-2: Accepted anchor can correct state**
Given an anchor decision that passes safety gates
When the wrapper considers it
Then the state may become `satellite_anchored` with recorded evidence.
**AC-3: Blackout degrades safely**
Given total visual blackout or tracking loss
When degraded propagation runs
Then covariance grows monotonically and failsafe/no-fix semantics occur at thresholds.
**AC-4: Tile-write eligibility is conservative**
Given a frame and current estimate
When tile eligibility is requested
Then only sufficiently trusted poses are eligible for generated tile writes.
## Non-Functional Requirements
**Safety**
- Confidence must not be optimistic relative to known error/covariance.
**Reliability**
- State invariant violations are surfaced and recorded.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Healthy VIO update | Estimate emitted |
| AC-2 | Accepted/rejected anchors | State updates only on accepted evidence |
| AC-3 | Blackout thresholds | `dead_reckoned` then no-fix/failsafe |
| AC-4 | Tile eligibility | Covariance/quality gates enforced |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-3 | Blackout + spoofing SITL | Degraded behavior | QGC/FDR/fix fields match thresholds | Safety |
## Constraints
- The VIO backend is not the safety authority.
- The wrapper does not call Tile Manager directly during anchor acceptance; freshness/provenance arrives through anchor evidence.
## Risks & Mitigation
**Risk 1: Over-trusted dead reckoning**
- *Risk*: IMU-only propagation is believed for too long.
- *Mitigation*: Monotonic covariance growth and no-fix/failsafe thresholds.