diff --git a/_docs/02_document/FINAL_report.md b/_docs/02_document/FINAL_report.md index 49f6662..f249540 100644 --- a/_docs/02_document/FINAL_report.md +++ b/_docs/02_document/FINAL_report.md @@ -2,7 +2,7 @@ ## Executive Summary -The solution planning phase decomposed the GPS-denied onboard localization service into 9 implementation components, 2 cross-cutting foundation epics, a bootstrap epic, and a blackbox-test epic. The architecture centers on a Jetson-hosted hot path using camera ingest, BASALT VIO, and a project-owned safety/anchor wrapper, with triggered Satellite Service candidate retrieval and ALIKED/DISK-LightGlue anchor verification against an offline PostgreSQL/PostGIS-backed cache. +The solution planning phase decomposed the GPS-denied onboard localization service into 8 runtime implementation components, 2 cross-cutting foundation epics, a bootstrap epic, and separate e2e/blackbox test epics. The architecture centers on a Jetson-hosted hot path using camera ingest, BASALT VIO, and a project-owned safety/anchor wrapper, with triggered Satellite Service candidate retrieval and ALIKED/DISK-LightGlue anchor verification against an offline PostgreSQL/PostGIS-backed cache. Jira epics were created in project `AZ` from AZ-206 through AZ-218. Total estimated effort across epics is approximately 87-141 story points, with large work intentionally decomposed into child tasks of 2, 3, or 5 points where possible. @@ -30,14 +30,14 @@ The system is a trigger-based hybrid estimator. Normal flight uses camera ingest | 06 | Tile Manager | Manage COGs, PostGIS manifests, sidecars, freshness, and orthorectified generated tiles | Bootstrap, shared helpers, config/errors | AZ-211 | | 07 | MAVLink And GCS Integration | Consume FC telemetry and emit v1 `GPS_INPUT`/QGC status | Bootstrap, config/errors | AZ-210 | | 08 | FDR And Observability | Record bounded replayable evidence and status | Bootstrap, config/errors, runtime DTOs | AZ-212 | -| 09 | Validation Harness | Drive blackbox, public replay, SITL, Jetson, and release evidence tests | All runtime components | AZ-217 | +| Test | E2E Test Suite | Separate black-box replay, SITL, Jetson, and release evidence tests; not onboard runtime | All runtime components | AZ-217 | **Implementation order**: 1. Bootstrap and cross-cutting foundations: AZ-206, AZ-207, AZ-208. 2. Independent adapters/stores: AZ-209, AZ-210, AZ-211, AZ-212. 3. Estimation/relocalization: AZ-213, AZ-214, AZ-215. 4. Safety orchestration: AZ-216. -5. Validation and blackbox test implementation: AZ-217, AZ-218. +5. Separate e2e/blackbox test implementation: AZ-217, AZ-218. ## System Flows @@ -79,7 +79,7 @@ See `risk_mitigations.md` for the full register. | Tile Manager | 4 | 1 | 3 | 1 | 10 ACs | | MAVLink And GCS Integration | 6 | 2 | 1 | 1 | 10 ACs | | FDR And Observability | 6 | 1 | 1 | 1 | 11 ACs | -| Validation Harness | 9 | 2 | 1 | 2 | All AC groups | +| E2E Test Suite | 9 | 2 | 1 | 2 | All AC groups | **Overall acceptance criteria coverage**: 39 / 39 acceptance criteria covered (100%). **Restrictions coverage**: 10 / 10 restriction groups covered (100%). @@ -99,7 +99,7 @@ See `risk_mitigations.md` for the full register. | 9 | AZ-214: Satellite Service | Component 04 | L / 8-13 pts | AZ-209, AZ-211 | | 10 | AZ-215: Anchor Verification | Component 05 | L / 8-13 pts | AZ-214, AZ-209, AZ-211 | | 11 | AZ-216: Safety And Anchor Wrapper | Component 03 | XL / 13-21 pts | AZ-209, AZ-210, AZ-213, AZ-215 | -| 12 | AZ-217: Validation Harness | Component 09 | L / 8-13 pts | Component epics | +| 12 | AZ-217: E2E Test Suite | Separate test support | L / 8-13 pts | Component epics | | 13 | AZ-218: Blackbox Tests | System tests | L / 8-13 pts | AZ-217, component epics | **Total estimated effort**: 87-141 story points. diff --git a/_docs/02_document/architecture.md b/_docs/02_document/architecture.md index ca66d9c..4cc4d37 100644 --- a/_docs/02_document/architecture.md +++ b/_docs/02_document/architecture.md @@ -33,7 +33,7 @@ Build a Jetson-hosted onboard localization pipeline for fixed-wing GPS-denied fl **System boundaries**: -- In scope: onboard localization runtime, offline cache consumption, BASALT VIO integration, satellite anchor verification, MAVLink output, QGC status, FDR, generated tile metadata, validation harness. +- In scope: onboard localization runtime, offline cache consumption, BASALT VIO integration, satellite anchor verification, MAVLink output, QGC status, FDR, generated tile metadata, and a separate e2e/black-box test suite. - Out of scope: upstream commercial satellite-provider sourcing, Satellite Service ingest implementation, AI mission-camera detection itself, PX4 support, raw-frame retention as a normal operating mode. **External systems**: diff --git a/_docs/02_document/components/02_basalt_vio_adapter/description.md b/_docs/02_document/components/02_basalt_vio_adapter/description.md index c215fdd..d02d2e2 100644 --- a/_docs/02_document/components/02_basalt_vio_adapter/description.md +++ b/_docs/02_document/components/02_basalt_vio_adapter/description.md @@ -8,7 +8,7 @@ **Upstream dependencies**: Camera ingest/calibration, MAVLink telemetry stream. -**Downstream consumers**: Safety/anchor wrapper, validation harness, FDR. +**Downstream consumers**: Safety/anchor wrapper, FDR, separate e2e test suite. ## 2. Internal Interfaces diff --git a/_docs/02_document/components/03_safety_anchor_wrapper/description.md b/_docs/02_document/components/03_safety_anchor_wrapper/description.md index a955dd7..e9fe8df 100644 --- a/_docs/02_document/components/03_safety_anchor_wrapper/description.md +++ b/_docs/02_document/components/03_safety_anchor_wrapper/description.md @@ -8,7 +8,7 @@ **Upstream dependencies**: BASALT VIO adapter, anchor verification, MAVLink telemetry, camera quality reports. -**Downstream consumers**: MAVLink/GCS integration, FDR, Tile Manager, validation harness. +**Downstream consumers**: MAVLink/GCS integration, FDR, Tile Manager, separate e2e test suite. ## 2. Internal Interfaces diff --git a/_docs/02_document/components/09_validation_harness/description.md b/_docs/02_document/components/09_validation_harness/description.md deleted file mode 100644 index 9e6f217..0000000 --- a/_docs/02_document/components/09_validation_harness/description.md +++ /dev/null @@ -1,86 +0,0 @@ -# Validation Harness - -## 1. High-Level Overview - -**Purpose**: Drive black-box replay, public dataset, SITL, Jetson, and representative validation through the runtime's public interfaces. - -**Architectural Pattern**: Test harness / scenario runner. - -**Upstream dependencies**: Test data fixtures, public datasets, SITL, Jetson environment. - -**Downstream consumers**: CI/CD pipeline, release evidence review. - -## 2. Internal Interfaces - -### Interface: `ScenarioRunner` - -| Method | Input | Output | Async | Error Types | -|--------|-------|--------|-------|-------------| -| `run_scenario` | `ScenarioRequest` | `ScenarioReport` | Yes | `FixtureInvalid`, `RuntimeFailed`, `ThresholdFailed` | -| `validate_fixture` | `FixtureRequest` | `FixtureValidationReport` | No | `FixtureInvalid` | - -**Input DTOs**: - -```yaml -ScenarioRequest: - scenario_id: string - execution_environment: enum(replay, sitl, jetson, representative) - fixture_paths: list[string] -``` - -**Output DTOs**: - -```yaml -ScenarioReport: - scenario_id: string - result: enum(pass, fail, blocked) - metrics: object - artifacts: list[path] - failure_reason: string optional -``` - -## 3. Data Access Patterns - -Reads versioned fixtures and writes reports. Does not import runtime internals. - -## 4. Implementation Details - -**State Management**: Per-run temporary directories and report aggregation. - -**Key Dependencies**: - -| Library | Purpose | -|---------|---------| -| pytest or equivalent | Test orchestration | -| pymavlink/log parser | SITL and output validation | -| Docker/compose runner | Replay/SITL environment | - -**Error Handling Strategy**: -- Fixture gaps are reported as blocked, not passed. -- Threshold failures include metrics and artifacts. - -## 5. Caveats & Edge Cases - -**Known limitations**: -- Public datasets are not final acceptance evidence unless representative and license-compatible. -- Missing synchronized target data remains a final acceptance blocker. - -## 6. Dependency Graph - -**Must be implemented after**: public interfaces are defined. - -**Can be implemented in parallel with**: runtime components using mocks/fixtures only after interfaces are stable. - -**Blocks**: CI/release gates. - -## 7. Logging Strategy - -| Log Level | When | Example | -|-----------|------|---------| -| ERROR | Runtime/test process fails | `scenario_failed id=... reason=...` | -| WARN | Fixture blocked | `fixture_blocked missing=...` | -| INFO | Scenario complete | `scenario_complete id=... result=pass` | - -**Log format**: Test report CSV/Markdown plus structured runner logs. - -**Log storage**: `test-results/`. diff --git a/_docs/02_document/components/09_validation_harness/tests.md b/_docs/02_document/components/09_validation_harness/tests.md deleted file mode 100644 index cdabb5a..0000000 --- a/_docs/02_document/components/09_validation_harness/tests.md +++ /dev/null @@ -1,232 +0,0 @@ -# Test Specification — Validation Harness - -## Acceptance Criteria Traceability - -| AC ID | Acceptance Criterion | Test IDs | Coverage | -|-------|---------------------|----------|----------| -| AC-1.1 through AC-1.4 | Position accuracy, drift, confidence | IT-01, AT-01 | Covered | -| AC-2.1a/b, AC-2.2 | VO and satellite registration | IT-02, IT-03 | Covered | -| AC-3.1 through AC-3.5 | Resilience edge cases | IT-04, IT-05 | Covered | -| AC-4.1 through AC-4.5 | Latency, memory, MAVLink streaming | PT-01, IT-06 | Covered | -| AC-5.1 through AC-5.3 | Startup/failsafe/reboot | IT-07 | Covered | -| AC-6.1 through AC-6.3 | QGC/GCS/WGS84 | IT-06 | Covered | -| AC-7.1, AC-7.2 | Object coordinate contract | IT-08 | Covered at system boundary | -| AC-8.1 through AC-8.6 | Offline cache, freshness, tiles, VPR | IT-03, IT-09, ST-01 | Covered | -| AC-NEW-1 through AC-NEW-8 | Cold start, spoofing, FDR, false-position, thermal, freshness, poisoning, blackout | IT-05, IT-07, PT-02, ST-01, AT-02 | Covered | - -## Blackbox Tests - -### IT-01: Still-Image Accuracy Runner - -**Summary**: Verify project still-image replay reports frame-center accuracy. - -**Traces to**: AC-1.1, AC-1.2, AC-1.4 - -**Input data**: Project mapped images and `expected_results/results_report.md`. - -**Expected result**: Report includes per-image error, aggregate 50 m/20 m pass rates, covariance, source label, and anchor age. - -**Max execution time**: 15 minutes. - ---- - -### IT-02: Synchronized VIO Replay Runner - -**Summary**: Verify Derkachi and public/representative synchronized data can drive BASALT/wrapper tests. - -**Traces to**: AC-1.3, AC-2.1a, AC-2.2 - -**Input data**: Derkachi cropped nadir video + telemetry fixture, MUN-FRL preferred slice, or representative synchronized dataset. - -**Expected result**: Runner validates fixture alignment, trajectory comparison, VIO registration, latency, and covariance calibration where calibration data supports it. - -**Max execution time**: Dataset-dependent. - ---- - -### IT-03: Satellite Anchor Replay Runner - -**Summary**: Verify VPR and anchor verification test scenarios are executable. - -**Traces to**: AC-2.1b, AC-2.2, AC-8.1, AC-8.2, AC-8.6 - -**Input data**: ALTO/AerialVL/representative aerial localization fixture plus cache. - -**Expected result**: Runner reports retrieval recall, MRE, accepted/rejected anchors, and freshness behavior. - -**Max execution time**: Dataset-dependent. - ---- - -### IT-04: Outlier/Sharp-Turn/Disconnected Runner - -**Summary**: Verify resilience scenarios are executable and reported. - -**Traces to**: AC-3.1, AC-3.2, AC-3.3, AC-3.4 - -**Input data**: Synthetic and public disconnected-segment fixtures. - -**Expected result**: Runner validates relocalization and records degraded-mode timelines. - -**Max execution time**: 30 minutes. - ---- - -### IT-05: Blackout And Spoofing Runner - -**Summary**: Verify total blackout plus spoofing scenarios can be driven through SITL/replay. - -**Traces to**: AC-3.5, AC-NEW-2, AC-NEW-8 - -**Input data**: Plane SITL spoofing scenario with 5 s, 15 s, and 35 s blackout windows. - -**Expected result**: Runner measures <=400 ms mode switch, <3 s promotion, monotonic covariance, and failsafe thresholds. - -**Max execution time**: 30 minutes. - ---- - -### IT-06: MAVLink/QGC Contract Runner - -**Summary**: Verify MAVLink output and GCS status assertions are automated. - -**Traces to**: AC-4.3, AC-4.4, AC-4.5, AC-6.1, AC-6.2, AC-6.3 - -**Input data**: Plane SITL, QGC observer/log parser, position fixtures. - -**Expected result**: Runner validates v1 GPS_INPUT-only output, WGS84 coordinates, status rate, and command ingress. - -**Max execution time**: 60 minutes. - ---- - -### IT-07: Startup/Reboot Runner - -**Summary**: Verify cold-start and reboot scenarios are measurable. - -**Traces to**: AC-5.1, AC-5.2, AC-5.3, AC-NEW-1 - -**Input data**: 50 cold-start runs and companion reboot trace. - -**Expected result**: First valid `GPS_INPUT` <30 s p95; reboot reinitializes from FC state. - -**Max execution time**: Runset-dependent. - ---- - -### IT-08: Object Coordinate Contract Runner - -**Summary**: Verify AI-camera object coordinate request contract at system boundary. - -**Traces to**: AC-7.1, AC-7.2 - -**Input data**: Frame-center estimate, object pixel/angle fixture, gimbal angle, altitude. - -**Expected result**: Output coordinate includes frame-center-consistent accuracy and maneuvering-flight projection error bound. - -**Max execution time**: 5 minutes. - ---- - -### IT-09: Tile Manager Runner - -**Summary**: Verify cache, generated tiles, and storage tests are executable. - -**Traces to**: AC-8.3, AC-8.4, AC-8.5, AC-NEW-6, AC-NEW-7 - -**Input data**: Cache integrity fixtures, generated tile scenarios, PostGIS manifest. - -**Expected result**: Runner validates cache load, tile write gates, no raw-frame retention, stale rejection, and poisoning budget evidence. - -**Max execution time**: Dataset-dependent. - -## Performance Tests - -### PT-01: End-To-End Release Gate Runner - -**Summary**: Verify performance and resource tests can run in the proper environment. - -**Traces to**: AC-4.1, AC-4.2, AC-NEW-5 - -**Load scenario**: -- Environments: replay, Jetson hardware, SITL. -- Duration: smoke, nightly, and release-gate profiles. - -| Metric | Target | Failure Threshold | -|--------|--------|-------------------| -| End-to-end p95 | <400 ms | >=400 ms | -| Memory | <8 GB | >=8 GB | -| Thermal throttle | 0 events in release gate | Any throttle event | - ---- - -### PT-02: FDR/Storage Runner - -**Summary**: Verify 8-hour storage/endurance test orchestration. - -**Traces to**: AC-NEW-3 - -| Metric | Target | Failure Threshold | -|--------|--------|-------------------| -| FDR cap | <=64 GB | >64 GB | -| Rollover logging | Complete | Missing rollover event | - -## Security Tests - -### ST-01: Security Fixture Runner - -**Summary**: Verify stale/tampered cache, spoofed MAVLink, and false-anchor scenarios are automated. - -**Traces to**: AC-NEW-4, AC-NEW-6, AC-NEW-7 - -**Attack vector**: Cache tampering, stale imagery, spoofed GPS, impossible anchors. - -**Test procedure**: -1. Load each security fixture. -2. Run scenario through public runtime interfaces. -3. Validate output labels, FDR, and rejection reasons. - -**Expected behavior**: No tampered/stale/spoofed input produces a trusted false fix. - -**Pass criteria**: 0 accepted unsafe anchors or spoofed GPS promotions outside gates. - -## Acceptance Tests - -### AT-01: Traceability Completeness Report - -**Summary**: Verify every AC has executable or explicitly blocked test coverage. - -**Traces to**: All ACs - -| Step | Action | Expected Result | -|------|--------|-----------------| -| 1 | Read traceability matrix | All ACs mapped to tests | -| 2 | Run fixture validation | Missing public/representative data is reported as blocked, not passed | - ---- - -### AT-02: Release Evidence Bundle - -**Summary**: Verify release evidence can be assembled. - -**Traces to**: AC-NEW-1 through AC-NEW-8 - -| Step | Action | Expected Result | -|------|--------|-----------------| -| 1 | Run release profile | Reports, tlogs, FDR summaries, cache reports are produced | -| 2 | Collate artifacts | Bundle contains pass/fail status and residual blockers | - -## Test Data Management - -| Data Set | Description | Source | Size | -|----------|-------------|--------|------| -| `project_60_still_images` | Frame-center geolocation smoke | Project data | Project size | -| `public_dataset_slices` | MUN-FRL/ALTO/Kagaru/EPFL/AerialVL as licensed | Public pinned fixtures | Dataset-dependent | -| `sitl_scenarios` | Plane spoofing/failsafe traces | Generated | Small | -| `security_fixtures` | Stale/tampered/cache poisoning cases | Generated | Small | - -**Setup procedure**: Create isolated run directory, restore PostgreSQL schema, mount fixtures read-only, and start requested environment. - -**Teardown procedure**: Stop environments, archive reports, drop run schema, and delete temp volumes. - -**Data isolation strategy**: Unique run ID, schema, ports, cache staging directory, and FDR directory per scenario. diff --git a/_docs/02_document/contracts/shared/config_errors_telemetry.md b/_docs/02_document/contracts/shared/config_errors_telemetry.md new file mode 100644 index 0000000..fdb669a --- /dev/null +++ b/_docs/02_document/contracts/shared/config_errors_telemetry.md @@ -0,0 +1,51 @@ +# Contract: Config Errors Telemetry + +**Component**: shared/config, shared/errors, shared/telemetry +**Producer task**: AZ-222 — AZ-222_runtime_config_errors_telemetry.md +**Consumer tasks**: AZ-223, AZ-224, AZ-225, AZ-226, AZ-227, AZ-228, AZ-229, AZ-230, AZ-231, AZ-232 +**Version**: 1.0.0 +**Status**: draft +**Last Updated**: 2026-05-03 + +## Purpose + +Defines shared runtime configuration, error/result envelope, health, and telemetry metadata behavior consumed by all runtime components. + +## Shape + +| Contract | Required Behavior | +|----------|-------------------| +| Runtime profile | environment-specific settings loaded and validated before use | +| Error envelope | component, category, message, cause, retryability, severity | +| Health event | liveness/readiness status, dependency state, timestamp, component | +| Metrics labels | bounded component/action/status labels suitable for runtime reports | + +## Invariants + +- Missing required production settings fail startup or readiness loudly. +- Errors are returned or logged with component and category; no silent suppression. +- Secrets are referenced, not serialized into FDR, logs, or metrics. + +## Non-Goals + +- Does not define component-specific business errors. +- Does not replace FDR payload schemas. + +## Versioning Rules + +- Removing required config keys or error categories requires a major version bump. +- Adding optional health fields or metrics labels requires a minor version bump. + +## Test Cases + +| Case | Input | Expected | Notes | +|------|-------|----------|-------| +| missing-required-prod | production profile missing cache dir | readiness/startup failure | Clear error category | +| secret-value | signing key ref present | only key ref logged | No secret leakage | +| component-error | component reports dependency failure | structured envelope emitted | FDR-safe | + +## Change Log + +| Version | Date | Change | Author | +|---------|------|--------|--------| +| 1.0.0 | 2026-05-03 | Initial contract | autodev | diff --git a/_docs/02_document/contracts/shared/geometry_time_sync.md b/_docs/02_document/contracts/shared/geometry_time_sync.md new file mode 100644 index 0000000..be03b4a --- /dev/null +++ b/_docs/02_document/contracts/shared/geometry_time_sync.md @@ -0,0 +1,52 @@ +# Contract: Geometry And Time Sync Helpers + +**Component**: shared/geo_geometry, shared/time_sync +**Producer task**: AZ-221 — AZ-221_shared_geometry_time_sync.md +**Consumer tasks**: AZ-223, AZ-225, AZ-226, AZ-228, AZ-230, AZ-231, AZ-232 +**Version**: 1.0.0 +**Status**: draft +**Last Updated**: 2026-05-03 + +## Purpose + +Defines shared geospatial and timestamp helper behavior used by runtime components to avoid duplicated math and inconsistent frame/IMU alignment. + +## Shape + +| API Area | Shape | Errors | +|----------|-------|--------| +| Coordinate conversion | WGS84/local tangent conversions and distance calculations | invalid CRS, missing origin | +| Camera footprint | intrinsics/extrinsics/attitude/altitude to footprint and GSD | invalid calibration, missing altitude | +| Homography metrics | homography/covariance conversions and MRE support | invalid geometry | +| Time sync | monotonic checks, frame-to-IMU window selection, replay ordering | timestamp mismatch, gap/jitter exceeded | + +## Invariants + +- Helpers are deterministic for the same calibration, pose, and timestamp inputs. +- Time helpers report gaps/jitter instead of silently dropping samples. +- Geometry helpers do not decide safety policy; callers decide degrade/reject behavior. + +## Non-Goals + +- No VIO state estimation. +- No MAVLink parsing beyond normalized timestamp fields. +- No tile freshness or cache policy decisions. + +## Versioning Rules + +- Breaking changes to units, coordinate frames, or timestamp semantics require a major version bump. +- New helper outputs may be added as optional fields in minor versions. + +## Test Cases + +| Case | Input | Expected | Notes | +|------|-------|----------|-------| +| valid-wgs84-local | known WGS84 point and origin | round-trip within tolerance | Uses representative coordinates | +| frame-imu-window | frame timestamp plus IMU samples | correct aligned window | Includes gap metrics | +| invalid-calibration | missing intrinsics/extrinsics | explicit error | No silent fallback | + +## Change Log + +| Version | Date | Change | Author | +|---------|------|--------|--------| +| 1.0.0 | 2026-05-03 | Initial contract | autodev | diff --git a/_docs/02_document/contracts/shared/runtime_contracts.md b/_docs/02_document/contracts/shared/runtime_contracts.md new file mode 100644 index 0000000..cf80353 --- /dev/null +++ b/_docs/02_document/contracts/shared/runtime_contracts.md @@ -0,0 +1,56 @@ +# Contract: Runtime Shared Contracts + +**Component**: shared/contracts +**Producer task**: AZ-220 — AZ-220_shared_runtime_contracts.md +**Consumer tasks**: AZ-223, AZ-224, AZ-225, AZ-226, AZ-227, AZ-228, AZ-229, AZ-230, AZ-231, AZ-232 +**Version**: 1.0.0 +**Status**: draft +**Last Updated**: 2026-05-03 + +## Purpose + +Defines the shared runtime DTO/event contract surface that component implementations consume instead of inventing local shapes. + +## Shape + +| Contract | Required Fields / Methods | Consumers | +|----------|---------------------------|-----------| +| `FramePacket` | frame ID, timestamp, image reference, calibration ID, occlusion, quality, normalization hint | camera, VIO, Satellite Service, Anchor Verification, Tile Manager, FDR | +| `TelemetrySample` | timestamp, IMU, attitude, altitude, airspeed, GPS health | MAVLink, VIO, safety wrapper, FDR | +| `VioStatePacket` | timestamp, relative pose, velocity, bias, tracking quality, covariance hint | VIO, safety wrapper, FDR | +| `PositionEstimate` | WGS84 coordinates, covariance, source label, fix type, horizontal accuracy, anchor age | safety wrapper, MAVLink, Tile Manager, FDR | +| `VprCandidate` | chunk ID, tile ID, score, footprint, freshness status | Satellite Service, Anchor Verification, FDR | +| `AnchorDecision` | candidate ID, acceptance result, estimated pose, inliers, MRE, rejection reason | Anchor Verification, safety wrapper, FDR | +| `CacheTileRecord` | tile ID, CRS, meters per pixel, capture date, signature/hash, trust level | Tile Manager, Satellite Service, Anchor Verification | +| `FdrEvent` | event type, timestamp, component, severity, payload reference, mission/run ID | all runtime components | + +## Invariants + +- Timestamps are normalized to a shared monotonic nanosecond representation before cross-component use. +- Confidence fields must not under-report known uncertainty. +- Raw frame payloads are referenced, not persisted in shared DTOs. +- Generated tile and anchor records must carry provenance/freshness metadata. + +## Non-Goals + +- Does not prescribe internal classes or storage implementation. +- Does not define e2e test runner-only report schemas. + +## Versioning Rules + +- Removing or renaming a field requires a major version bump. +- Adding optional telemetry or diagnostic fields requires a minor version bump. + +## Test Cases + +| Case | Input | Expected | Notes | +|------|-------|----------|-------| +| valid-frame | frame with timestamp, calibration, quality | accepted by consumers | Includes normalization hint | +| invalid-time | non-monotonic timestamp | rejected or marked invalid | Time-sync contract decides details | +| stale-anchor | anchor decision with stale freshness | rejected/down-confidenced | Safety wrapper must not accept blindly | + +## Change Log + +| Version | Date | Change | Author | +|---------|------|--------|--------| +| 1.0.0 | 2026-05-03 | Initial contract | autodev | diff --git a/_docs/02_document/diagrams/component_overview.md b/_docs/02_document/diagrams/component_overview.md index 8aed796..05cad31 100644 --- a/_docs/02_document/diagrams/component_overview.md +++ b/_docs/02_document/diagrams/component_overview.md @@ -10,7 +10,7 @@ flowchart LR cache[06 Tile Manager] mav[07 MAVLink And GCS Integration] fdr[08 FDR And Observability] - tests[09 Validation Harness] + tests[[Separate E2E Test Suite]] navCam[[Nav Camera]] --> camera fc[[ArduPilot Plane FC]] --> mav diff --git a/_docs/02_document/epics.md b/_docs/02_document/epics.md index 8411be2..50fa0a8 100644 --- a/_docs/02_document/epics.md +++ b/_docs/02_document/epics.md @@ -21,8 +21,8 @@ | 9 | AZ-214 | Satellite Service | component | AZ-206, AZ-207, AZ-208, AZ-209, AZ-211 | L / 8-13 pts | | 10 | AZ-215 | Anchor Verification | component | AZ-206, AZ-207, AZ-208, AZ-209, AZ-211, AZ-214 | L / 8-13 pts | | 11 | AZ-216 | Safety And Anchor Wrapper | component | AZ-206, AZ-207, AZ-208, AZ-209, AZ-210, AZ-213, AZ-215 | XL / 13-21 pts | -| 12 | AZ-217 | Validation Harness | component | AZ-206, AZ-207, AZ-208, component epics | L / 8-13 pts | -| 13 | AZ-218 | Blackbox Tests | blackbox-tests | AZ-206, AZ-217, component epics | L / 8-13 pts | +| 12 | AZ-217 | E2E Test Suite | test-support | component epics | L / 8-13 pts | +| 13 | AZ-218 | Blackbox Tests | blackbox-tests | AZ-217, component epics | L / 8-13 pts | ## Component Mapping @@ -40,7 +40,7 @@ | `components/06_cache_tile_lifecycle/` | AZ-211 | | `components/07_mavlink_gcs_integration/` | AZ-210 | | `components/08_fdr_observability/` | AZ-212 | -| `components/09_validation_harness/` | AZ-217 | +| `tests/e2e-test-suite.md`, `tests/blackbox-tests.md`, `tests/environment.md` | AZ-217 | | System blackbox/performance/resilience/security/resource tests | AZ-218 | ## Epic Relationship Diagram @@ -58,7 +58,7 @@ flowchart TD retrieval[AZ-214 Satellite Service] anchor[AZ-215 Anchor Verification] safety[AZ-216 Safety And Anchor Wrapper] - validation[AZ-217 Validation Harness] + validation[AZ-217 E2E Test Suite] blackbox[AZ-218 Blackbox Tests] bootstrap --> geo @@ -96,9 +96,14 @@ flowchart TD safety --> fdr camera --> fdr cache --> fdr - validation --> blackbox safety --> validation fdr --> validation + camera --> validation + mavlink --> validation + retrieval --> validation + anchor --> validation + cache --> validation + validation --> blackbox ``` ## Cross-Cutting Ownership @@ -123,7 +128,7 @@ flowchart TD - AZ-214 — Satellite Service - AZ-215 — Anchor Verification - AZ-216 — Safety And Anchor Wrapper -- AZ-217 — Validation Harness +- AZ-217 — E2E Test Suite - AZ-218 — Blackbox Tests ## Tracker Notes diff --git a/_docs/02_document/module-layout.md b/_docs/02_document/module-layout.md index 3dbad87..d5d6bc2 100644 --- a/_docs/02_document/module-layout.md +++ b/_docs/02_document/module-layout.md @@ -19,6 +19,7 @@ - **Epic**: AZ-209 - **Directory**: `src/camera_ingest_calibration/` +- **Technologies**: Python, OpenCV 4.x, camera SDK/V4L2/GigE adapter boundary, calibration files, shared geometry/time helpers - **Public API**: - `src/camera_ingest_calibration/__init__.py` - `src/camera_ingest_calibration/types.py` @@ -28,13 +29,14 @@ - `src/camera_ingest_calibration/_*.py` - **Owns (exclusive write during implementation)**: `src/camera_ingest_calibration/**` - **Imports from**: shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry -- **Consumed by**: BASALT VIO Adapter, Satellite Service, Anchor Verification, Tile Manager, FDR And Observability, Validation Harness +- **Consumed by**: BASALT VIO Adapter, Satellite Service, Anchor Verification, Tile Manager, FDR And Observability ### Component: BASALT VIO Adapter - **Epic**: AZ-213 - **Directory**: `src/basalt_vio_adapter/` - **Native Directory**: `src/native/basalt_bridge/` +- **Technologies**: Python adapter, C++ native bridge, BASALT, Eigen/Sophus or BASALT math stack, OpenCV 4.x, shared time-sync contracts - **Public API**: - `src/basalt_vio_adapter/__init__.py` - `src/basalt_vio_adapter/types.py` @@ -47,12 +49,13 @@ - `src/basalt_vio_adapter/**` - `src/native/basalt_bridge/**` - **Imports from**: Camera Ingest And Calibration, MAVLink And GCS Integration, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry -- **Consumed by**: Safety And Anchor Wrapper, FDR And Observability, Validation Harness +- **Consumed by**: Safety And Anchor Wrapper, FDR And Observability ### Component: Safety And Anchor Wrapper - **Epic**: AZ-216 - **Directory**: `src/safety_anchor_wrapper/` +- **Technologies**: Python state machine, OpenCV geometry helpers, covariance/gating logic, shared DTO contracts, MAVLink output DTOs - **Public API**: - `src/safety_anchor_wrapper/__init__.py` - `src/safety_anchor_wrapper/types.py` @@ -62,13 +65,14 @@ - `src/safety_anchor_wrapper/_*.py` - **Owns (exclusive write during implementation)**: `src/safety_anchor_wrapper/**` - **Imports from**: BASALT VIO Adapter, Anchor Verification, MAVLink And GCS Integration, Camera Ingest And Calibration, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry -- **Consumed by**: MAVLink And GCS Integration, Tile Manager, FDR And Observability, Validation Harness +- **Consumed by**: MAVLink And GCS Integration, Tile Manager, FDR And Observability ### Component: Satellite Service - **Epic**: AZ-214 - **Directory**: `src/satellite_service/` - **Native Directory**: `src/native/tensor_rt/` +- **Technologies**: Python service adapter, DINOv2-VLAD descriptors, ONNX/TensorRT candidate path, CPU FAISS, offline package sync client - **Public API**: - `src/satellite_service/__init__.py` - `src/satellite_service/types.py` @@ -81,7 +85,7 @@ - `src/satellite_service/**` - `src/native/tensor_rt/**` - **Imports from**: Camera Ingest And Calibration, Tile Manager, Safety And Anchor Wrapper, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry -- **Consumed by**: Anchor Verification, FDR And Observability, Validation Harness +- **Consumed by**: Anchor Verification, FDR And Observability - **Network invariant**: external Satellite Service sync is allowed only pre-flight or post-flight; no mid-flight satellite-provider or suite-service calls. ### Component: Anchor Verification @@ -89,6 +93,7 @@ - **Epic**: AZ-215 - **Directory**: `src/anchor_verification/` - **Native Directory**: `src/native/feature_matching/` +- **Technologies**: Python validation pipeline, ALIKED/DISK + LightGlue, OpenCV RANSAC/USAC, SIFT/ORB baseline, native feature-matching bridge - **Public API**: - `src/anchor_verification/__init__.py` - `src/anchor_verification/types.py` @@ -101,12 +106,13 @@ - `src/anchor_verification/**` - `src/native/feature_matching/**` - **Imports from**: Satellite Service, Camera Ingest And Calibration, Tile Manager, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry -- **Consumed by**: Safety And Anchor Wrapper, FDR And Observability, Validation Harness +- **Consumed by**: Safety And Anchor Wrapper, FDR And Observability ### Component: Tile Manager - **Epic**: AZ-211 - **Directory**: `src/tile_manager/` +- **Technologies**: Python repository/policy layer, PostgreSQL/PostGIS, GDAL/rasterio COG handling, signed JSON sidecars, OpenCV/GDAL orthorectification, hash/signature validation - **Public API**: - `src/tile_manager/__init__.py` - `src/tile_manager/types.py` @@ -119,12 +125,13 @@ - `migrations/postgresql/cache_*.sql` - `migrations/seed/cache_*` - **Imports from**: Camera Ingest And Calibration, Safety And Anchor Wrapper, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry -- **Consumed by**: Satellite Service, Anchor Verification, FDR And Observability, Validation Harness +- **Consumed by**: Satellite Service, Anchor Verification, FDR And Observability ### Component: MAVLink And GCS Integration - **Epic**: AZ-210 - **Directory**: `src/mavlink_gcs_integration/` +- **Technologies**: Python, MAVSDK telemetry subscriptions, pymavlink `GPS_INPUT` emission, MAVLink/QGC status messages - **Public API**: - `src/mavlink_gcs_integration/__init__.py` - `src/mavlink_gcs_integration/types.py` @@ -134,12 +141,13 @@ - `src/mavlink_gcs_integration/_*.py` - **Owns (exclusive write during implementation)**: `src/mavlink_gcs_integration/**` - **Imports from**: Safety And Anchor Wrapper, shared/contracts, shared/time_sync, shared/config, shared/errors, shared/telemetry -- **Consumed by**: BASALT VIO Adapter, Safety And Anchor Wrapper, FDR And Observability, Validation Harness +- **Consumed by**: BASALT VIO Adapter, Safety And Anchor Wrapper, FDR And Observability ### Component: FDR And Observability - **Epic**: AZ-212 - **Directory**: `src/fdr_observability/` +- **Technologies**: Python append/export layer, PostgreSQL event index, CBOR segment payloads, optional Parquet export, structured logging/health events - **Public API**: - `src/fdr_observability/__init__.py` - `src/fdr_observability/types.py` @@ -152,25 +160,7 @@ - `migrations/postgresql/fdr_*.sql` - `migrations/seed/fdr_*` - **Imports from**: shared/contracts, shared/time_sync, shared/config, shared/errors, shared/telemetry -- **Consumed by**: all runtime components, Validation Harness - -### Component: Validation Harness - -- **Epic**: AZ-217 -- **Directory**: `src/validation_harness/` -- **Public API**: - - `src/validation_harness/__init__.py` - - `src/validation_harness/types.py` - - `src/validation_harness/interfaces.py` -- **Internal (do NOT import from other components)**: - - `src/validation_harness/internal/*` - - `src/validation_harness/_*.py` -- **Owns (exclusive write during implementation)**: - - `src/validation_harness/**` - - `e2e/replay/**` - - `e2e/reports/**` -- **Imports from**: public runtime interfaces only, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry -- **Consumed by**: CI/CD pipeline and release evidence review +- **Consumed by**: all runtime components ## Shared / Cross-Cutting @@ -178,6 +168,7 @@ - **Epic**: AZ-206 - **Directory**: `src/shared/contracts/` +- **Technologies**: Python typed DTOs, schema/contract definitions, Markdown API-contract documents - **Purpose**: Shared DTOs, protocol shapes, schemas, and public contract exports. - **Owned by**: initial structure and shared-contract tasks under AZ-206. - **Consumed by**: all components. @@ -186,30 +177,34 @@ - **Epic**: AZ-207 - **Directory**: `src/shared/geo_geometry/` +- **Technologies**: Python geometry utilities, OpenCV 4.x, WGS84/local-frame math, homography/covariance conversions - **Purpose**: WGS84/local conversions, GSD, camera footprint projection, homography/covariance unit conversion, and distance calculations. - **Owned by**: shared geometry task under AZ-207. -- **Consumed by**: Camera Ingest And Calibration, Safety And Anchor Wrapper, Anchor Verification, Tile Manager, Validation Harness. +- **Consumed by**: Camera Ingest And Calibration, Safety And Anchor Wrapper, Anchor Verification, Tile Manager. ### shared/time_sync - **Epic**: AZ-207 - **Directory**: `src/shared/time_sync/` +- **Technologies**: Python timestamp utilities, monotonic-clock validation, MAVLink/camera timestamp normalization, replay ordering checks - **Purpose**: Monotonic timestamp checks, frame-to-IMU alignment, clock-domain metadata, replay ordering, and gap/jitter metrics. - **Owned by**: time-sync task under AZ-207. -- **Consumed by**: Camera Ingest And Calibration, BASALT VIO Adapter, MAVLink And GCS Integration, FDR And Observability, Validation Harness. +- **Consumed by**: Camera Ingest And Calibration, BASALT VIO Adapter, MAVLink And GCS Integration, FDR And Observability. ### shared/config - **Epic**: AZ-208 - **Directory**: `src/shared/config/` +- **Technologies**: Python configuration loader, environment variables, `.env.example`, startup readiness validation - **Purpose**: Runtime profile loading, environment validation, typed settings, and startup readiness inputs. - **Owned by**: runtime configuration task under AZ-208. -- **Consumed by**: all runtime components and Validation Harness. +- **Consumed by**: all runtime components. ### shared/errors - **Epic**: AZ-208 - **Directory**: `src/shared/errors/` +- **Technologies**: Python exception/result envelope types, shared error categories, fail-fast helpers - **Purpose**: Error categories, result envelopes, fail-fast helpers, and non-silent exception contracts. - **Owned by**: runtime error contract task under AZ-208. - **Consumed by**: all components. @@ -218,6 +213,7 @@ - **Epic**: AZ-208 - **Directory**: `src/shared/telemetry/` +- **Technologies**: Python structured logging, metrics labels, health event DTOs, FDR-safe telemetry metadata - **Purpose**: Structured logging, metrics labels, health event shapes, and FDR-safe event metadata helpers. - **Owned by**: observability/config contract task under AZ-208. - **Consumed by**: all components. @@ -228,7 +224,6 @@ Read top-to-bottom; an upper layer may import from a lower layer but never the r | Layer | Components | May import from | |-------|------------|-----------------| -| 5. Validation / Evidence | Validation Harness | 1, 2, 3, 4 public interfaces | | 4. Runtime Output / Coordination | Safety And Anchor Wrapper, MAVLink And GCS Integration, FDR And Observability | 1, 2, 3 public interfaces | | 3. Perception / Satellite Anchor | BASALT VIO Adapter, Satellite Service, Anchor Verification | 1, 2 public interfaces | | 2. Data Ingest / Persistence | Camera Ingest And Calibration, Tile Manager | 1 | @@ -236,9 +231,15 @@ Read top-to-bottom; an upper layer may import from a lower layer but never the r Violations of this table are Architecture findings in code-review Phase 7 and are High severity. +## Out-of-Product E2E Test Suite + +The e2e replay/SITL/Jetson validation suite is not a product component and must not receive Step 6 product implementation tasks. It owns test-support artifacts under `tests/blackbox/**`, `tests/e2e/**`, `e2e/replay/**`, and `e2e/reports/**`, and it exercises the runtime only through public file, MAVLink, cache, status, and FDR interfaces. + +- **Technologies**: Python, pytest-style runner, Docker/compose, pymavlink/log parser, ArduPilot Plane SITL, QGC observer/log parser, CSV/Markdown reports + ## Self-Verification -- Every component under `_docs/02_document/components/` has a mapping entry. +- Every runtime component under `_docs/02_document/components/` has a mapping entry. - Cross-cutting epics AZ-206, AZ-207, and AZ-208 have shared ownership entries. - Layering covers all components and keeps shared code at the bottom. - Component-owned paths do not overlap, except explicitly assigned native directories. diff --git a/_docs/02_document/risk_mitigations.md b/_docs/02_document/risk_mitigations.md index 0430b92..9398d68 100644 --- a/_docs/02_document/risk_mitigations.md +++ b/_docs/02_document/risk_mitigations.md @@ -55,7 +55,7 @@ **Trigger conditions**: Manufacturer documentation or hardware testing contradicts assumed FPS, interface, temperature, or lens characteristics. -**Affected components**: Camera ingest/calibration, BASALT VIO adapter, validation harness, deployment procedures. +**Affected components**: Camera ingest/calibration, BASALT VIO adapter, separate e2e test suite, deployment procedures. **Mitigation strategy**: 1. Make camera specification verification a bootstrap task. @@ -76,7 +76,7 @@ **Trigger conditions**: Public or representative replay shows high drift, frequent tracking loss, or poor initialization. -**Affected components**: BASALT VIO adapter, safety/anchor wrapper, validation harness. +**Affected components**: BASALT VIO adapter, safety/anchor wrapper, separate e2e test suite. **Mitigation strategy**: 1. Run MUN-FRL first for synchronized nadir camera + IMU + ground truth. @@ -160,7 +160,7 @@ **Trigger conditions**: Relocalization exceeds p95 latency, memory budget, or causes thermal throttling. -**Affected components**: Satellite Service, anchor verification, validation harness. +**Affected components**: Satellite Service, anchor verification, separate e2e test suite. **Mitigation strategy**: 1. Keep VPR/local matching trigger-based. @@ -244,7 +244,7 @@ **Trigger conditions**: Plane SITL rejects or mishandles emitted `GPS_INPUT`, or QGC status is insufficient. -**Affected components**: MAVLink/GCS integration, safety/anchor wrapper, validation harness. +**Affected components**: MAVLink/GCS integration, safety/anchor wrapper, separate e2e test suite. **Mitigation strategy**: 1. Use pymavlink for exact `GPS_INPUT` field control. diff --git a/_docs/02_document/system-flows.md b/_docs/02_document/system-flows.md index 0b467df..f837a01 100644 --- a/_docs/02_document/system-flows.md +++ b/_docs/02_document/system-flows.md @@ -10,7 +10,7 @@ | F4 | Visual blackout / spoofing degraded mode | Image-quality failure and GPS health failure | Camera ingest, MAVLink telemetry, safety/anchor wrapper, QGC, FDR | Critical | | F5 | Generated tile lifecycle | High-confidence pose + usable frame | Camera ingest, safety/anchor wrapper, Tile Manager, FDR | Medium | | F6 | Post-flight sync and audit | Landing / operator offload | Tile Manager, Satellite Service, FDR | Medium | -| F7 | Validation replay | Test harness invocation | Validation harness, system runtime, public datasets, SITL | High | +| F7 | E2E validation replay | Test-suite invocation | Separate e2e test suite, system runtime, public datasets, SITL | High | ## Flow Dependencies @@ -298,7 +298,7 @@ After landing, generated tiles and FDR evidence are exported through Satellite S ### Description -The validation harness runs deterministic still-image, public dataset, SITL, Jetson, and representative replay scenarios against public interfaces. +The separate e2e test suite runs deterministic still-image, public dataset, SITL, Jetson, and representative replay scenarios against public interfaces. ### Preconditions @@ -309,9 +309,9 @@ The validation harness runs deterministic still-image, public dataset, SITL, Jet | Step | From | To | Data | Format | |------|------|----|------|--------| -| 1 | Validation harness | Runtime | Images/telemetry/cache fixtures | File/stream/MAVLink | -| 2 | Runtime | Validation harness | GPS_INPUT/FDR/status | MAVLink/log files | -| 3 | Validation harness | Reports | Pass/fail metrics | CSV/Markdown | +| 1 | E2E test suite | Runtime | Images/telemetry/cache fixtures | File/stream/MAVLink | +| 2 | Runtime | E2E test suite | GPS_INPUT/FDR/status | MAVLink/log files | +| 3 | E2E test suite | Reports | Pass/fail metrics | CSV/Markdown | ### Performance Expectations diff --git a/_docs/02_document/tests/e2e-test-suite.md b/_docs/02_document/tests/e2e-test-suite.md new file mode 100644 index 0000000..fe56298 --- /dev/null +++ b/_docs/02_document/tests/e2e-test-suite.md @@ -0,0 +1,81 @@ +# E2E Test Suite + +## Scope + +The e2e test suite is separate test tooling, not part of the onboard runtime. It drives black-box replay, public dataset, SITL, Jetson, and representative validation through public runtime interfaces only. + +## Purpose + +- Feed navigation frames, telemetry traces, cache manifests, and fault triggers into the system under test. +- Validate emitted coordinates, confidence fields, MAVLink `GPS_INPUT`, QGC status, FDR, and generated-tile evidence. +- Produce release evidence without importing runtime internals. + +## Ownership + +- **Epic**: AZ-217 (E2E Test Suite / test-support work, not product runtime) +- **Owns**: + - `tests/blackbox/**` + - `tests/e2e/**` + - `e2e/replay/**` + - `e2e/reports/**` +- **Does not own**: + - `src/**` + - runtime component internals + - production deployment code + +## Public Interfaces Under Test + +| Interface | Protocol / Contract | +|-----------|---------------------| +| Navigation frames | Ordered image/video replay with timestamps | +| FC telemetry | MAVLink replay or generated stream | +| Satellite cache | Local COG + manifest + descriptor fixtures | +| GPS output | MAVLink `GPS_INPUT` | +| Operator status | QGC-visible MAVLink status | +| FDR | Filesystem/database-backed evidence outputs | + +## Runner Contract + +| Method | Input | Output | Error Types | +|--------|-------|--------|-------------| +| `run_scenario` | `ScenarioRequest` | `ScenarioReport` | `FixtureInvalid`, `RuntimeFailed`, `ThresholdFailed` | +| `validate_fixture` | `FixtureRequest` | `FixtureValidationReport` | `FixtureInvalid` | + +```yaml +ScenarioRequest: + scenario_id: string + execution_environment: enum(replay, sitl, jetson, representative) + fixture_paths: list[string] + +ScenarioReport: + scenario_id: string + result: enum(pass, fail, blocked) + metrics: object + artifacts: list[path] + failure_reason: string optional +``` + +## Scenario Coverage + +| Scenario | Purpose | Evidence | +|----------|---------|----------| +| Still-image accuracy runner | Verify project still-image replay reports frame-center accuracy | Per-image error, aggregate pass rates, covariance, source label, anchor age | +| Synchronized VIO replay runner | Verify Derkachi and public/representative synchronized data drive BASALT/wrapper tests | Fixture alignment, trajectory comparison, VIO registration, latency, covariance calibration | +| Satellite anchor replay runner | Verify VPR and anchor verification scenarios are executable | Retrieval recall, MRE, accepted/rejected anchors, freshness behavior | +| Outlier/sharp-turn/disconnected runner | Verify relocalization resilience scenarios are executable | Degraded-mode timelines and relocalization outcomes | +| Blackout and spoofing runner | Verify total blackout plus spoofing through SITL/replay | Mode-switch timing, covariance growth, failsafe thresholds | +| MAVLink/QGC contract runner | Verify MAVLink output and GCS status assertions | `GPS_INPUT`, WGS84 coordinates, status rate, command ingress | +| Startup/reboot runner | Verify cold-start and companion reboot scenarios | First valid `GPS_INPUT` p95 and FC-state reinitialization | +| Object coordinate contract runner | Verify AI-camera object coordinate request at system boundary | Frame-center-consistent coordinate accuracy and projection bound | +| Tile Manager runner | Verify cache, generated tiles, and storage tests | Cache load, tile write gates, no raw-frame retention, stale rejection, poisoning evidence | + +## Release Evidence + +The suite assembles CSV, Markdown, MAVLink tlogs, FDR summaries, cache validation reports, and pass/fail metadata into release evidence bundles. Missing public or representative data is reported as `blocked`, not `passed`. + +## Non-Responsibilities + +- No onboard flight logic. +- No direct estimator, BASALT, wrapper, or tile-manager imports. +- No mutation of runtime internal state. +- No production service APIs. diff --git a/_docs/02_tasks/_dependencies_table.md b/_docs/02_tasks/_dependencies_table.md new file mode 100644 index 0000000..7352fa2 --- /dev/null +++ b/_docs/02_tasks/_dependencies_table.md @@ -0,0 +1,29 @@ +# Dependencies Table + +**Date**: 2026-05-03 +**Total Tasks**: 14 +**Total Complexity Points**: 60 +**Lessons applied**: No `_docs/LESSONS.md` file exists; no prior estimation or dependency lessons were available. + +| Task | Name | Complexity | Dependencies | Epic | +|------|------|------------|--------------|------| +| AZ-219 | initial_structure | 5 | None | AZ-206 | +| AZ-220 | shared_runtime_contracts | 3 | AZ-219 | AZ-206 | +| AZ-221 | shared_geometry_time_sync | 3 | AZ-219, AZ-220 | AZ-207 | +| AZ-222 | runtime_config_errors_telemetry | 3 | AZ-219, AZ-220 | AZ-208 | +| AZ-223 | camera_ingest_calibration | 5 | AZ-220, AZ-221, AZ-222 | AZ-209 | +| AZ-224 | mavlink_gcs_gateway | 3 | AZ-220, AZ-222 | AZ-210 | +| AZ-225 | tile_manager_cache_manifest | 5 | AZ-220, AZ-221, AZ-222 | AZ-211 | +| AZ-226 | generated_tile_orthorectification | 5 | AZ-223, AZ-225 | AZ-211 | +| AZ-227 | fdr_event_recorder | 5 | AZ-220, AZ-222 | AZ-212 | +| AZ-228 | basalt_vio_adapter | 5 | AZ-221, AZ-222, AZ-223, AZ-224 | AZ-213 | +| AZ-229 | satellite_service_sync | 3 | AZ-222, AZ-225, AZ-226 | AZ-214 | +| AZ-230 | satellite_service_vpr_retrieval | 5 | AZ-223, AZ-225, AZ-229 | AZ-214 | +| AZ-231 | anchor_verification_matching | 5 | AZ-223, AZ-225, AZ-230 | AZ-215 | +| AZ-232 | safety_anchor_state_machine | 5 | AZ-223, AZ-224, AZ-227, AZ-228, AZ-231 | AZ-216 | + +## Verification Notes + +- No task exceeds 5 complexity points. +- E2E/blackbox test work remains outside this product implementation task set and is deferred to the greenfield Decompose Tests phase. +- The graph is acyclic: foundations precede adapters/stores, then VIO/retrieval/matching, then safety wrapper orchestration. diff --git a/_docs/02_tasks/todo/AZ-219_initial_structure.md b/_docs/02_tasks/todo/AZ-219_initial_structure.md index 9591531..23a0d68 100644 --- a/_docs/02_tasks/todo/AZ-219_initial_structure.md +++ b/_docs/02_tasks/todo/AZ-219_initial_structure.md @@ -18,12 +18,11 @@ project-root/ │ ├── camera_ingest_calibration/ │ ├── basalt_vio_adapter/ │ ├── safety_anchor_wrapper/ -│ ├── satellite_retrieval/ +│ ├── satellite_service/ │ ├── anchor_verification/ -│ ├── cache_tile_lifecycle/ +│ ├── tile_manager/ │ ├── mavlink_gcs_integration/ │ ├── fdr_observability/ -│ ├── validation_harness/ │ ├── shared/ │ │ ├── contracts/ │ │ ├── geo_geometry/ @@ -43,7 +42,8 @@ project-root/ │ ├── integration/ │ ├── blackbox/ │ ├── fixtures/ -│ └── sitl/ +│ ├── sitl/ +│ └── e2e/ ├── e2e/ │ ├── replay/ │ └── reports/ @@ -85,28 +85,27 @@ The scaffold separates runtime source, migrations, tests, deployment assets, con | DTO Name | Used By Components | Fields Summary | |----------|--------------------|----------------| | `FramePacket` | Camera ingest, BASALT VIO, Satellite Service, anchor verification, Tile Manager, FDR | Frame ID, timestamp, image reference, camera calibration ID, occlusion status, quality metrics | -| `TelemetrySample` | MAVLink/GCS, BASALT VIO, safety wrapper, FDR, validation harness | Timestamp, IMU, attitude, airspeed, altitude, GPS health | -| `VioStatePacket` | BASALT VIO, safety wrapper, FDR, validation harness | Timestamp, relative pose, velocity, bias, tracking quality, covariance hint | -| `PositionEstimate` | Safety wrapper, MAVLink/GCS, Tile Manager, FDR, validation harness | WGS84 coordinates, covariance semi-major axis, source label, fix type, horizontal accuracy, anchor age | +| `TelemetrySample` | MAVLink/GCS, BASALT VIO, safety wrapper, FDR, e2e tests | Timestamp, IMU, attitude, airspeed, altitude, GPS health | +| `VioStatePacket` | BASALT VIO, safety wrapper, FDR, e2e tests | Timestamp, relative pose, velocity, bias, tracking quality, covariance hint | +| `PositionEstimate` | Safety wrapper, MAVLink/GCS, Tile Manager, FDR, e2e tests | WGS84 coordinates, covariance semi-major axis, source label, fix type, horizontal accuracy, anchor age | | `VprCandidate` | Satellite Service, anchor verification, FDR | Chunk ID, tile ID, score, footprint, freshness status | | `AnchorDecision` | Anchor verification, safety wrapper, FDR | Candidate ID, acceptance result, estimated pose, inliers, MRE, rejection reason | | `CacheTileRecord` | Tile Manager, Satellite Service, anchor verification, FDR | Tile ID, type, CRS, meters per pixel, capture date, signature/hash status, trust level | -| `FdrEvent` | All runtime components, validation harness | Event type, timestamp, component, severity, payload reference, mission/run ID | -| `ScenarioReport` | Validation harness, CI/CD, release evidence | Scenario ID, result, metrics, artifacts, failure reason | +| `FdrEvent` | All runtime components, e2e tests | Event type, timestamp, component, severity, payload reference, mission/run ID | +| `ScenarioReport` | Separate e2e test suite, CI/CD, release evidence | Scenario ID, result, metrics, artifacts, failure reason | ### Component Interfaces | Component | Interface | Methods | Exposed To | |-----------|-----------|---------|------------| | Camera ingest/calibration | `FrameProvider` | `next_frame`, `detect_occlusion`, `classify_quality` | BASALT VIO, Satellite Service, anchor verification, Tile Manager | -| BASALT VIO adapter | `VioAdapter` | `initialize`, `process`, `health` | Safety wrapper, validation harness | -| Safety/anchor wrapper | `LocalizationStateMachine` | `update_vio`, `consider_anchor`, `degrade`, `propagate_imu_only`, `tile_write_eligibility` | MAVLink/GCS, Tile Manager, FDR, validation harness | +| BASALT VIO adapter | `VioAdapter` | `initialize`, `process`, `health` | Safety wrapper, e2e tests | +| Safety/anchor wrapper | `LocalizationStateMachine` | `update_vio`, `consider_anchor`, `degrade`, `propagate_imu_only`, `tile_write_eligibility` | MAVLink/GCS, Tile Manager, FDR, e2e tests | | Satellite Service | `SatelliteService` | `import_mission_cache`, `load_index`, `retrieve`, `upload_generated_tiles` | Safety wrapper, anchor verification, Tile Manager | | Anchor verification | `AnchorVerifier` | `verify`, `benchmark_matcher` | Safety wrapper, FDR | | Tile Manager | `TileManager` | `validate_cache`, `get_tile_window`, `orthorectify_frame`, `write_generated_tile`, `package_sync` | Satellite Service, anchor verification, post-flight sync | | MAVLink/GCS integration | `MavlinkGateway` | `subscribe_telemetry`, `emit_gps_input`, `emit_status` | BASALT VIO, safety wrapper, QGC, FDR | -| FDR/observability | `FlightRecorder` | `append_event`, `rollover`, `export` | All runtime components, validation harness | -| Validation harness | `ScenarioRunner` | `validate_fixture`, `run_scenario` | CI/CD, release evidence review | +| FDR/observability | `FlightRecorder` | `append_event`, `rollover`, `export` | All runtime components, e2e tests | ## CI/CD Pipeline @@ -182,7 +181,6 @@ tests/ │ ├── tile_manager/ │ ├── mavlink_gcs_integration/ │ ├── fdr_observability/ -│ └── validation_harness/ ├── integration/ │ ├── contracts/ │ ├── cache_postgis/ @@ -200,10 +198,14 @@ tests/ │ ├── satellite_cache/ │ ├── telemetry/ │ └── public_dataset_slices/ -└── sitl/ - ├── plane_gps_input/ - ├── spoofing_promotion/ - └── failsafe/ +├── sitl/ +│ ├── plane_gps_input/ +│ ├── spoofing_promotion/ +│ └── failsafe/ +└── e2e/ + ├── replay/ + ├── reports/ + └── release_evidence/ ``` ### Test Configuration Notes diff --git a/_docs/02_tasks/todo/AZ-220_shared_runtime_contracts.md b/_docs/02_tasks/todo/AZ-220_shared_runtime_contracts.md new file mode 100644 index 0000000..d0cc71a --- /dev/null +++ b/_docs/02_tasks/todo/AZ-220_shared_runtime_contracts.md @@ -0,0 +1,78 @@ +# Shared Runtime Contracts + +**Task**: AZ-220_shared_runtime_contracts +**Name**: Shared Runtime Contracts +**Description**: Define the shared DTO and event contract surface used across the onboard runtime. +**Complexity**: 3 points +**Dependencies**: AZ-219_initial_structure +**Component**: Bootstrap / Shared Contracts +**Tracker**: AZ-220 +**Epic**: AZ-206 + +## Problem + +Runtime components need common shapes for frames, telemetry, VIO state, position estimates, candidates, anchors, cache tiles, and FDR events. + +## Outcome + +- Components consume one documented shared contract surface. +- Cross-component DTO drift is prevented before implementation begins. + +## Scope + +### Included +- Shared runtime DTO names, fields, invariants, versioning rules, and contract tests. +- Public contract document for consumers. + +### Excluded +- Component-specific algorithms. +- E2E runner-only report schemas. + +## Acceptance Criteria + +**AC-1: Shared contract exists** +Given runtime components need common DTOs +When the shared contracts are implemented +Then each runtime component can import or reference the same contract surface. + +**AC-2: Contract validation exists** +Given a malformed shared DTO +When validation runs +Then the input is rejected with a structured error. + +## Non-Functional Requirements + +**Compatibility** +- Contract changes follow documented versioning rules. + +**Reliability** +- Invalid or missing required fields are not silently ignored. + +## Unit Tests + +| AC Ref | What to Test | Required Outcome | +|--------|--------------|------------------| +| AC-1 | DTO construction for valid minimal values | Accepted | +| AC-2 | Missing required timestamp or ID | Rejected with structured error | + +## Blackbox Tests + +| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References | +|--------|-------------------------|--------------|-------------------|----------------| +| AC-1 | Runtime started with contract consumers | Public interfaces exchange typed records | No component-specific duplicate shape required | Compatibility | + +## Constraints + +- Contracts are shared API surface and must be consumed through documented public modules. +- Raw frame payloads are referenced, not retained in shared DTOs. + +## Risks & Mitigation + +**Risk 1: Contract drift** +- *Risk*: Consumers create local incompatible DTOs. +- *Mitigation*: Contract file is required dependency for consuming tasks. + +## Contract + +This task produces/implements the contract at `_docs/02_document/contracts/shared/runtime_contracts.md`. +Consumers MUST read that file — not this task spec — to discover the interface. diff --git a/_docs/02_tasks/todo/AZ-221_shared_geometry_time_sync.md b/_docs/02_tasks/todo/AZ-221_shared_geometry_time_sync.md new file mode 100644 index 0000000..932a446 --- /dev/null +++ b/_docs/02_tasks/todo/AZ-221_shared_geometry_time_sync.md @@ -0,0 +1,78 @@ +# Shared Geometry And Time Sync + +**Task**: AZ-221_shared_geometry_time_sync +**Name**: Shared Geometry And Time Sync +**Description**: Provide shared geospatial and timestamp helper behavior for runtime components. +**Complexity**: 3 points +**Dependencies**: AZ-219_initial_structure, AZ-220_shared_runtime_contracts +**Component**: Shared Geometry And Time Sync +**Tracker**: AZ-221 +**Epic**: AZ-207 + +## Problem + +Camera, VIO, Tile Manager, Satellite Service, Anchor Verification, safety, and FDR need consistent coordinate, footprint, homography, and timestamp behavior. + +## Outcome + +- Shared helpers provide deterministic geometry and time-sync behavior. +- Components do not duplicate geospatial or timestamp alignment logic. + +## Scope + +### Included +- WGS84/local conversions, distance/GSD helpers, footprint projection, homography/covariance conversion support. +- Monotonic timestamp checks, frame-to-IMU window selection, replay ordering, gap/jitter metrics. + +### Excluded +- VIO estimation. +- Cache policy and safety degrade decisions. + +## Acceptance Criteria + +**AC-1: Geometry helpers are deterministic** +Given the same calibration, attitude, altitude, and coordinates +When geometry helpers run +Then they return repeatable footprint and metric outputs. + +**AC-2: Time-sync violations are explicit** +Given frame and telemetry timestamps with a gap or mismatch +When alignment runs +Then the result reports the violation instead of dropping data silently. + +## Non-Functional Requirements + +**Performance** +- Helpers are suitable for hot-path use under the system latency budget. + +**Reliability** +- Invalid calibration, CRS, or timestamp inputs fail explicitly. + +## Unit Tests + +| AC Ref | What to Test | Required Outcome | +|--------|--------------|------------------| +| AC-1 | WGS84/local round-trip | Error within tolerance | +| AC-2 | Non-monotonic timestamps | Explicit mismatch result | + +## Blackbox Tests + +| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References | +|--------|-------------------------|--------------|-------------------|----------------| +| AC-1 | Derkachi/replay frame metadata | Footprint and ordering evidence | Deterministic helper outputs in reports | Performance | + +## Constraints + +- Shared helpers do not own policy decisions. +- Timestamp units must match the shared runtime contract. + +## Risks & Mitigation + +**Risk 1: Coordinate-frame confusion** +- *Risk*: Components interpret helper outputs differently. +- *Mitigation*: Contract documents units, frames, and error semantics. + +## Contract + +This task produces/implements the contract at `_docs/02_document/contracts/shared/geometry_time_sync.md`. +Consumers MUST read that file — not this task spec — to discover the interface. diff --git a/_docs/02_tasks/todo/AZ-222_runtime_config_errors_telemetry.md b/_docs/02_tasks/todo/AZ-222_runtime_config_errors_telemetry.md new file mode 100644 index 0000000..f9612bf --- /dev/null +++ b/_docs/02_tasks/todo/AZ-222_runtime_config_errors_telemetry.md @@ -0,0 +1,80 @@ +# Runtime Config Errors And Telemetry + +**Task**: AZ-222_runtime_config_errors_telemetry +**Name**: Runtime Config Errors And Telemetry +**Description**: Provide shared configuration, error envelope, health, and telemetry behavior for runtime components. +**Complexity**: 3 points +**Dependencies**: AZ-219_initial_structure, AZ-220_shared_runtime_contracts +**Component**: Runtime Configuration And Errors +**Tracker**: AZ-222 +**Epic**: AZ-208 + +## Problem + +Runtime components need common configuration loading, readiness validation, error handling, and telemetry metadata. + +## Outcome + +- Environment profiles are validated before runtime use. +- Errors and health events are structured and FDR-safe. +- Secrets are referenced without leaking into logs or reports. + +## Scope + +### Included +- Runtime profile validation. +- Shared error/result envelopes. +- Health and metrics metadata. + +### Excluded +- Component-specific business logic. +- FDR storage implementation. + +## Acceptance Criteria + +**AC-1: Required settings are validated** +Given a production profile is missing a required setting +When startup/readiness validation runs +Then the component reports a structured failure. + +**AC-2: Errors are not silent** +Given a dependency failure occurs +When a component reports it +Then the error includes component, category, severity, and retryability. + +## Non-Functional Requirements + +**Reliability** +- Missing configuration and dependency failures are never silently ignored. + +**Compatibility** +- Error categories and config keys follow the contract versioning rules. + +## Unit Tests + +| AC Ref | What to Test | Required Outcome | +|--------|--------------|------------------| +| AC-1 | Missing production cache dir | Readiness failure | +| AC-2 | Dependency error envelope | Structured fields present | + +## Blackbox Tests + +| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References | +|--------|-------------------------|--------------|-------------------|----------------| +| AC-1 | Invalid env profile | Runtime readiness | Service refuses ready state | Reliability | + +## Constraints + +- Secrets must not be serialized into logs, FDR, or metrics. +- Error handling must not use silent suppression. + +## Risks & Mitigation + +**Risk 1: Environment-specific behavior drifts** +- *Risk*: Development and production profiles behave differently in unsafe ways. +- *Mitigation*: Profile validation is shared and tested. + +## Contract + +This task produces/implements the contract at `_docs/02_document/contracts/shared/config_errors_telemetry.md`. +Consumers MUST read that file — not this task spec — to discover the interface. diff --git a/_docs/02_tasks/todo/AZ-223_camera_ingest_calibration.md b/_docs/02_tasks/todo/AZ-223_camera_ingest_calibration.md new file mode 100644 index 0000000..5382420 --- /dev/null +++ b/_docs/02_tasks/todo/AZ-223_camera_ingest_calibration.md @@ -0,0 +1,89 @@ +# Camera Ingest Calibration And Frame Quality + +**Task**: AZ-223_camera_ingest_calibration +**Name**: Camera Ingest Calibration And Frame Quality +**Description**: Ingest navigation frames, attach calibration/timestamp metadata, classify quality, detect occlusion, and provide north-up normalization hints. +**Complexity**: 5 points +**Dependencies**: AZ-220_shared_runtime_contracts, AZ-221_shared_geometry_time_sync, AZ-222_runtime_config_errors_telemetry +**Component**: Camera Ingest And Calibration +**Tracker**: AZ-223 +**Epic**: AZ-209 + +## Problem + +Downstream VIO, retrieval, anchor verification, Tile Manager, and FDR need trustworthy frame metadata and quality decisions before using image data. + +## Outcome + +- Replay and live-source frames are exposed with timestamps, calibration ID, quality, occlusion, and normalization hints. +- Total occlusion/blackout frames are marked unusable for VIO and anchor paths. + +## Scope + +### Included +- Frame source abstraction for replay/live camera boundary. +- Calibration metadata loading and validation. +- Quality and occlusion reports. +- North-up/orthorectification hints as metadata, not unconditional frame mutation. + +### Excluded +- Tile writing and generated COG persistence. +- BASALT processing. + +## 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: Usable frame packet emitted** +Given a valid replay frame and calibration +When the frame is ingested +Then a frame packet includes timestamp, calibration ID, quality report, occlusion report, and normalization hint. + +**AC-2: Blackout bypass signal emitted** +Given an unreadable, covered, or total-occlusion frame +When quality classification runs +Then the frame is marked unusable for VIO and anchor matching. + +**AC-3: Raw frames are not retained** +Given normal runtime operation +When a frame is processed +Then only allowed metadata/references are retained outside explicit fixture/test paths. + +## Non-Functional Requirements + +**Performance** +- Frame preprocessing must fit within the system p95 latency budget. + +**Reliability** +- Missing calibration blocks production readiness. + +## Unit Tests + +| AC Ref | What to Test | Required Outcome | +|--------|--------------|------------------| +| AC-1 | Valid frame with calibration | Frame packet contains required metadata | +| AC-2 | Total occlusion input | `usable_for_vio=false` and `usable_for_anchor=false` | +| AC-3 | Processed frame cleanup | No raw-frame persistence | + +## Blackbox Tests + +| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References | +|--------|-------------------------|--------------|-------------------|----------------| +| AC-1 | Derkachi replay fixture | Frame/telemetry alignment | Accepted frame packets are timestamped | Performance | +| AC-2 | Blackout fixture | Occlusion handling | Visual path degrades safely | Reliability | + +## Constraints + +- Do not rotate every frame in ingest; emit normalization hints for downstream use. +- ADTi hardware assumptions remain blocked until exact specs are verified. + +## Risks & Mitigation + +**Risk 1: False-negative occlusion** +- *Risk*: Bad frames enter VIO or matching. +- *Mitigation*: Conservative occlusion gate and explicit quality flags. diff --git a/_docs/02_tasks/todo/AZ-224_mavlink_gcs_gateway.md b/_docs/02_tasks/todo/AZ-224_mavlink_gcs_gateway.md new file mode 100644 index 0000000..4e3a616 --- /dev/null +++ b/_docs/02_tasks/todo/AZ-224_mavlink_gcs_gateway.md @@ -0,0 +1,84 @@ +# MAVLink GCS Gateway + +**Task**: AZ-224_mavlink_gcs_gateway +**Name**: MAVLink GCS Gateway +**Description**: Subscribe to FC telemetry, emit `GPS_INPUT`, and publish QGC-visible status/failsafe messages. +**Complexity**: 3 points +**Dependencies**: AZ-220_shared_runtime_contracts, AZ-222_runtime_config_errors_telemetry +**Component**: MAVLink And GCS Integration +**Tracker**: AZ-224 +**Epic**: AZ-210 + +## Problem + +The runtime needs a strict protocol boundary for ArduPilot Plane telemetry in and GPS-denied estimates/status out. + +## Outcome + +- FC telemetry is normalized into shared samples. +- `GPS_INPUT` is emitted only from validated position estimates. +- QGC status is rate-limited and safety-relevant. + +## Scope + +### Included +- Telemetry subscription behavior. +- `GPS_INPUT` field validation and emission result. +- QGC status/failsafe message emission. + +### Excluded +- Safety policy and covariance calculation. +- SITL test runner implementation. + +## Dependencies + +### Document Dependencies +- `_docs/02_document/contracts/shared/runtime_contracts.md` +- `_docs/02_document/contracts/shared/config_errors_telemetry.md` + +## Acceptance Criteria + +**AC-1: Telemetry sample emitted** +Given a valid FC telemetry stream +When the gateway subscribes +Then normalized telemetry samples are available to consumers. + +**AC-2: Invalid GPS_INPUT is rejected** +Given a malformed or unsafe position estimate +When emission is requested +Then no invalid `GPS_INPUT` packet is emitted. + +**AC-3: Operator status is rate-limited** +Given repeated mode changes or warnings +When status is emitted +Then QGC-visible messages stay within the configured rate. + +## Non-Functional Requirements + +**Reliability** +- Connection loss is surfaced to wrapper/FDR. + +## Unit Tests + +| AC Ref | What to Test | Required Outcome | +|--------|--------------|------------------| +| AC-1 | Telemetry normalization | Shared sample emitted | +| AC-2 | Invalid fix type/accuracy | Emission rejected | +| AC-3 | Status burst | Rate limit enforced | + +## Blackbox Tests + +| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References | +|--------|-------------------------|--------------|-------------------|----------------| +| AC-2 | Plane SITL | `GPS_INPUT` output | Fields match ArduPilot expectations | Reliability | + +## Constraints + +- v1 emits `GPS_INPUT` only. +- Do not hide MAVLink disconnects or invalid output errors. + +## Risks & Mitigation + +**Risk 1: ArduPilot parameter mismatch** +- *Risk*: Plane ignores or mishandles emitted estimates. +- *Mitigation*: SITL validation remains a release gate. diff --git a/_docs/02_tasks/todo/AZ-225_tile_manager_cache_manifest.md b/_docs/02_tasks/todo/AZ-225_tile_manager_cache_manifest.md new file mode 100644 index 0000000..4c17d99 --- /dev/null +++ b/_docs/02_tasks/todo/AZ-225_tile_manager_cache_manifest.md @@ -0,0 +1,89 @@ +# Tile Manager Cache Manifest + +**Task**: AZ-225_tile_manager_cache_manifest +**Name**: Tile Manager Cache Manifest +**Description**: Validate local cache manifests, signed sidecars, tile freshness, and spatial/descriptor metadata access. +**Complexity**: 5 points +**Dependencies**: AZ-220_shared_runtime_contracts, AZ-221_shared_geometry_time_sync, AZ-222_runtime_config_errors_telemetry +**Component**: Tile Manager +**Tracker**: AZ-225 +**Epic**: AZ-211 + +## Problem + +The runtime must trust only preloaded offline cache tiles with valid signatures, hashes, freshness, resolution, and spatial metadata. + +## Outcome + +- Mission cache validation blocks invalid cache usage. +- Tile windows and descriptor metadata are queryable through local PostGIS-backed metadata. +- Stale or tampered tiles cannot become trusted anchor inputs. + +## Scope + +### Included +- Cache package validation. +- Signed sidecar/hash/freshness checks. +- Tile window and descriptor metadata lookup. +- Cache validation report events. + +### Excluded +- Satellite Service package transfer. +- Generated tile orthorectification/write-back. + +## 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: Valid cache activates** +Given a cache package with valid manifests, sidecars, hashes, freshness, and spatial coverage +When cache validation runs +Then the cache becomes available to retrieval and anchor paths. + +**AC-2: Invalid cache is rejected** +Given a stale, unsigned, or hash-mismatched tile +When validation runs +Then the tile is rejected and an auditable reason is recorded. + +**AC-3: Tile metadata is queryable** +Given a candidate footprint or chunk ID +When a consumer requests tile metadata +Then the Tile Manager returns a valid local record or explicit rejection. + +## Non-Functional Requirements + +**Performance** +- Indexed tile lookups meet relocalization-path latency needs. + +**Reliability** +- Local PostgreSQL/PostGIS unavailability blocks mission cache activation. + +## Unit Tests + +| AC Ref | What to Test | Required Outcome | +|--------|--------------|------------------| +| AC-1 | Valid fixture | Cache available | +| AC-2 | Tampered sidecar | Tile rejected | +| AC-3 | Chunk metadata lookup | Correct record or explicit error | + +## Blackbox Tests + +| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References | +|--------|-------------------------|--------------|-------------------|----------------| +| AC-2 | Stale/unsigned fixtures | Cache security gate | No invalid tile reaches retrieval | Reliability | + +## Constraints + +- Runtime never fetches satellite data mid-flight. +- Large imagery/descriptors stay as files, not DB blobs. + +## Risks & Mitigation + +**Risk 1: Cache poisoning** +- *Risk*: Bad cache entries influence anchor decisions. +- *Mitigation*: Signature, hash, freshness, and provenance gates are mandatory. diff --git a/_docs/02_tasks/todo/AZ-226_generated_tile_orthorectification.md b/_docs/02_tasks/todo/AZ-226_generated_tile_orthorectification.md new file mode 100644 index 0000000..76b0098 --- /dev/null +++ b/_docs/02_tasks/todo/AZ-226_generated_tile_orthorectification.md @@ -0,0 +1,88 @@ +# Generated Tile Orthorectification And Sync Package + +**Task**: AZ-226_generated_tile_orthorectification +**Name**: Generated Tile Orthorectification And Sync Package +**Description**: Convert eligible nadir frames into generated orthorectified COG tiles and prepare post-flight sync packages. +**Complexity**: 5 points +**Dependencies**: AZ-223_camera_ingest_calibration, AZ-225_tile_manager_cache_manifest +**Component**: Tile Manager +**Tracker**: AZ-226 +**Epic**: AZ-211 + +## Problem + +Generated tiles must be written only when pose, frame quality, and provenance gates make them safe to retain for post-flight Satellite Service review. + +## Outcome + +- Eligible nadir frames can become generated COG candidates with sidecars. +- Unsafe or over-confident tile writes are rejected. +- Post-flight generated-tile packages carry enough metadata for Satellite Service ingest/voting. + +## Scope + +### Included +- Orthorectification request handling. +- Generated COG + sidecar metadata creation. +- Covariance/quality gates and trust level assignment. +- Sync package preparation. + +### Excluded +- Satellite Service upload transport. +- Promotion to trusted basemap onboard. + +## Dependencies + +### Document Dependencies +- `_docs/02_document/contracts/shared/runtime_contracts.md` +- `_docs/02_document/contracts/shared/geometry_time_sync.md` + +## Acceptance Criteria + +**AC-1: Eligible frame writes generated tile** +Given a high-confidence pose and usable frame +When tile generation runs +Then a generated COG candidate and sidecar are staged. + +**AC-2: Unsafe frame is rejected** +Given high covariance or unusable frame quality +When tile generation runs +Then no trusted tile is written. + +**AC-3: Sync package is auditable** +Given generated candidate tiles exist +When a package is prepared +Then it includes manifest delta, sidecars, parent covariance, and trust level. + +## Non-Functional Requirements + +**Reliability** +- Generated tiles are never promoted directly to trusted basemap onboard. + +**Performance** +- Tile generation must not block localization output. + +## Unit Tests + +| AC Ref | What to Test | Required Outcome | +|--------|--------------|------------------| +| AC-1 | Valid tile request | COG + sidecar staged | +| AC-2 | Covariance too high | Write rejected | +| AC-3 | Package creation | Required metadata present | + +## Blackbox Tests + +| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References | +|--------|-------------------------|--------------|-------------------|----------------| +| AC-2 | Poisoning fixture | Generated tile gate | No direct trusted promotion | Reliability | + +## Constraints + +- Tile Manager performs generated tile writes; camera ingest only provides metadata/hints. +- Missing sidecars make generated tiles ineligible for upload. + +## Risks & Mitigation + +**Risk 1: Misaligned generated tile** +- *Risk*: Wrong pose creates harmful future anchor data. +- *Mitigation*: Parent covariance, frame quality, and post-flight validation gates. diff --git a/_docs/02_tasks/todo/AZ-227_fdr_event_recorder.md b/_docs/02_tasks/todo/AZ-227_fdr_event_recorder.md new file mode 100644 index 0000000..d4e7c33 --- /dev/null +++ b/_docs/02_tasks/todo/AZ-227_fdr_event_recorder.md @@ -0,0 +1,88 @@ +# FDR Event Recorder And Export Surface + +**Task**: AZ-227_fdr_event_recorder +**Name**: FDR Event Recorder And Export Surface +**Description**: Record bounded replayable mission evidence and expose exportable post-flight summaries. +**Complexity**: 5 points +**Dependencies**: AZ-220_shared_runtime_contracts, AZ-222_runtime_config_errors_telemetry +**Component**: FDR And Observability +**Tracker**: AZ-227 +**Epic**: AZ-212 + +## Problem + +The system needs compact, bounded, queryable evidence for estimates, inputs, health, anchors, tile writes, and safety transitions. + +## Outcome + +- Runtime components can append structured FDR events. +- Storage rollover and health behavior are explicit. +- Post-flight exports are available for analysis and release evidence. + +## Scope + +### Included +- Append event behavior. +- PostgreSQL event index and CBOR segment payload contract. +- Rollover and storage-full handling. +- Export request/result behavior. + +### Excluded +- Component-specific event payload generation. +- E2E report collation. + +## Dependencies + +### Document Dependencies +- `_docs/02_document/contracts/shared/runtime_contracts.md` +- `_docs/02_document/contracts/shared/config_errors_telemetry.md` + +## Acceptance Criteria + +**AC-1: Events are appendable** +Given a valid FDR event +When a component appends it +Then metadata is indexed and payload is stored within bounds. + +**AC-2: Storage pressure is handled** +Given segment or storage limits are reached +When append continues +Then rollover or critical status behavior is explicit. + +**AC-3: Export produces evidence** +Given a completed run +When export is requested +Then queryable evidence and optional analytics artifacts are produced. + +## Non-Functional Requirements + +**Performance** +- FDR appends must not block hot-path localization. + +**Reliability** +- Append failures are surfaced to callers and health state. + +## Unit Tests + +| AC Ref | What to Test | Required Outcome | +|--------|--------------|------------------| +| AC-1 | Valid event append | Indexed metadata and payload reference | +| AC-2 | Rollover threshold | Rollover event recorded | +| AC-3 | Export request | Evidence artifact produced | + +## Blackbox Tests + +| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References | +|--------|-------------------------|--------------|-------------------|----------------| +| AC-2 | 8-hour synthetic load | FDR cap and rollover | <=64 GB or explicit rollover evidence | Performance | + +## Constraints + +- Raw frames are not retained by default. +- Secrets are not logged in FDR payloads. + +## Risks & Mitigation + +**Risk 1: FDR affects latency** +- *Risk*: Append pressure slows localization. +- *Mitigation*: Bounded segments and async-friendly append semantics. diff --git a/_docs/02_tasks/todo/AZ-228_basalt_vio_adapter.md b/_docs/02_tasks/todo/AZ-228_basalt_vio_adapter.md new file mode 100644 index 0000000..aae7a7d --- /dev/null +++ b/_docs/02_tasks/todo/AZ-228_basalt_vio_adapter.md @@ -0,0 +1,89 @@ +# BASALT VIO Adapter + +**Task**: AZ-228_basalt_vio_adapter +**Name**: BASALT VIO Adapter +**Description**: Wrap BASALT as a replaceable relative VIO component with health and error behavior. +**Complexity**: 5 points +**Dependencies**: AZ-221_shared_geometry_time_sync, AZ-222_runtime_config_errors_telemetry, AZ-223_camera_ingest_calibration, AZ-224_mavlink_gcs_gateway +**Component**: BASALT VIO Adapter +**Tracker**: AZ-228 +**Epic**: AZ-213 + +## Problem + +The safety wrapper needs relative VIO state from calibrated frames and FC IMU without inheriting BASALT-specific internals. + +## Outcome + +- BASALT initialization, processing, and health behavior are exposed through a replaceable adapter. +- Tracking loss and timestamp mismatch are explicit. +- The adapter never emits WGS84 coordinates or safety decisions. + +## Scope + +### Included +- Initialization and runtime health. +- Frame + IMU processing behavior. +- Relative pose/velocity/bias output and quality metadata. +- Native bridge boundary. + +### Excluded +- Absolute anchor fusion and covariance authority. +- Satellite matching fallback implementation. + +## 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 emitted** +Given synchronized frame and IMU samples +When processing succeeds +Then a relative VIO state packet with tracking quality is emitted. + +**AC-2: Timestamp mismatch is explicit** +Given frame/IMU timestamps are inconsistent +When processing is requested +Then the adapter rejects the packet with a timestamp mismatch error. + +**AC-3: Health is observable** +Given initialization or tracking quality changes +When health is requested +Then the adapter reports current VIO readiness and degradation state. + +## Non-Functional Requirements + +**Performance** +- Adapter processing must be profiled against Jetson latency/memory limits. + +**Reliability** +- BASALT failures are surfaced, not hidden. + +## Unit Tests + +| AC Ref | What to Test | Required Outcome | +|--------|--------------|------------------| +| AC-1 | Valid synchronized packet | VIO state emitted | +| AC-2 | Bad timestamp window | Explicit error | +| AC-3 | Tracking loss | Health reports degraded | + +## Blackbox Tests + +| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References | +|--------|-------------------------|--------------|-------------------|----------------| +| AC-1 | Derkachi/public replay | Relative VIO path | Continuous estimates where data supports it | Performance | + +## Constraints + +- BASALT is not the safety authority. +- GPL VIO dependencies remain reference-only unless explicitly approved. + +## Risks & Mitigation + +**Risk 1: Nadir fixed-wing fit** +- *Risk*: BASALT underperforms on low-parallax terrain. +- *Mitigation*: Representative replay and reference comparisons gate acceptance. diff --git a/_docs/02_tasks/todo/AZ-229_satellite_service_sync.md b/_docs/02_tasks/todo/AZ-229_satellite_service_sync.md new file mode 100644 index 0000000..0d771b8 --- /dev/null +++ b/_docs/02_tasks/todo/AZ-229_satellite_service_sync.md @@ -0,0 +1,87 @@ +# Satellite Service Sync Boundary + +**Task**: AZ-229_satellite_service_sync +**Name**: Satellite Service Sync Boundary +**Description**: Import mission cache packages before flight and upload generated-tile packages after flight. +**Complexity**: 3 points +**Dependencies**: AZ-222_runtime_config_errors_telemetry, AZ-225_tile_manager_cache_manifest, AZ-226_generated_tile_orthorectification +**Component**: Satellite Service +**Tracker**: AZ-229 +**Epic**: AZ-214 + +## Problem + +The onboard runtime needs a clear boundary for Satellite Service package exchange without allowing mid-flight network calls. + +## Outcome + +- Pre-flight cache packages can be imported and handed to Tile Manager validation. +- Post-flight generated-tile packages can be uploaded/retried. +- Mid-flight provider or Satellite Service calls are explicitly blocked. + +## Scope + +### Included +- Pre-flight import behavior. +- Post-flight generated-tile upload behavior. +- Package status and retry/error reporting. + +### Excluded +- In-flight retrieval ranking. +- Tile manifest validation and generated tile creation. + +## Dependencies + +### Document Dependencies +- `_docs/02_document/contracts/shared/runtime_contracts.md` +- `_docs/02_document/contracts/shared/config_errors_telemetry.md` + +## Acceptance Criteria + +**AC-1: Pre-flight package import succeeds** +Given a valid Satellite Service mission cache package +When import runs before flight +Then the package is available for Tile Manager validation. + +**AC-2: Post-flight upload is auditable** +Given a generated-tile package exists after landing +When upload runs +Then success, rejection, or retryable failure is recorded. + +**AC-3: Mid-flight network calls are blocked** +Given the runtime is in flight mode +When cache data is missing +Then the component does not call a satellite provider or suite service. + +## Non-Functional Requirements + +**Reliability** +- Upload failures retain packages for retry. + +**Security** +- Signing credentials are never logged. + +## Unit Tests + +| AC Ref | What to Test | Required Outcome | +|--------|--------------|------------------| +| AC-1 | Valid import package | Package ready for validation | +| AC-2 | Upload unavailable | Retryable failure recorded | +| AC-3 | Flight-mode missing data | No network call | + +## Blackbox Tests + +| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References | +|--------|-------------------------|--------------|-------------------|----------------| +| AC-3 | Network disabled in replay | Relocalization missing data | Degraded/no-candidate behavior, no fetch | Security | + +## Constraints + +- No in-flight Satellite Service or satellite-provider network dependency. +- Package sync is before takeoff or after landing only. + +## Risks & Mitigation + +**Risk 1: Boundary confusion** +- *Risk*: Retrieval code starts fetching provider data mid-flight. +- *Mitigation*: Flight-mode invariant is acceptance-tested. diff --git a/_docs/02_tasks/todo/AZ-230_satellite_service_vpr_retrieval.md b/_docs/02_tasks/todo/AZ-230_satellite_service_vpr_retrieval.md new file mode 100644 index 0000000..715e2e6 --- /dev/null +++ b/_docs/02_tasks/todo/AZ-230_satellite_service_vpr_retrieval.md @@ -0,0 +1,89 @@ +# Satellite Service Local VPR Retrieval + +**Task**: AZ-230_satellite_service_vpr_retrieval +**Name**: Satellite Service Local VPR Retrieval +**Description**: Retrieve local VPR candidates from preloaded descriptors and FAISS indexes. +**Complexity**: 5 points +**Dependencies**: AZ-223_camera_ingest_calibration, AZ-225_tile_manager_cache_manifest, AZ-229_satellite_service_sync +**Component**: Satellite Service +**Tracker**: AZ-230 +**Epic**: AZ-214 + +## Problem + +Relocalization needs ranked satellite/cache candidates, but retrieval must be trigger-based and use only local preloaded cache/index data. + +## Outcome + +- DINOv2-VLAD descriptor extraction and CPU FAISS top-K candidate retrieval are available. +- Candidate freshness and dynamic top-K policy are carried forward. +- No-candidate/index failures produce degraded behavior rather than unsafe anchors. + +## Scope + +### Included +- Index load/readiness behavior. +- Query descriptor and top-K candidate retrieval. +- Freshness tagging and retrieval result metadata. +- Descriptor fidelity gate for optimized engines. + +### Excluded +- Local matching/RANSAC. +- In-flight network fetches. + +## 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: Index loads before retrieval** +Given a valid local descriptor/index package +When index loading runs +Then retrieval readiness is reported. + +**AC-2: Top-K candidates returned** +Given a relocalization request and loaded local index +When retrieval runs +Then bounded candidates include tile/chunk IDs, scores, footprints, and freshness status. + +**AC-3: Missing candidates degrade safely** +Given no valid candidates or index failure +When retrieval runs +Then the result is explicit no-candidate/degraded behavior. + +## Non-Functional Requirements + +**Performance** +- Retrieval is trigger-based and profiled against Jetson limits. + +**Security** +- Retrieval never performs mid-flight provider calls. + +## Unit Tests + +| AC Ref | What to Test | Required Outcome | +|--------|--------------|------------------| +| AC-1 | Valid index | Ready status | +| AC-2 | Query frame | Candidate list with freshness | +| AC-3 | Missing index | Explicit degraded/no-candidate result | + +## Blackbox Tests + +| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References | +|--------|-------------------------|--------------|-------------------|----------------| +| AC-2 | Public/cache fixture | VPR recall and top-K policy | Correct candidate bounds and freshness | Performance | + +## Constraints + +- Retrieval is not per-frame steady-state work. +- TensorRT/ONNX path is accepted only after descriptor-fidelity tests pass. + +## Risks & Mitigation + +**Risk 1: Trigger path exceeds Jetson budget** +- *Risk*: Descriptor extraction or FAISS query is too slow. +- *Mitigation*: CPU-first FAISS, bounded top-K, and profiling gates. diff --git a/_docs/02_tasks/todo/AZ-231_anchor_verification_matching.md b/_docs/02_tasks/todo/AZ-231_anchor_verification_matching.md new file mode 100644 index 0000000..176f306 --- /dev/null +++ b/_docs/02_tasks/todo/AZ-231_anchor_verification_matching.md @@ -0,0 +1,88 @@ +# Anchor Verification Matching And Geometry Gates + +**Task**: AZ-231_anchor_verification_matching +**Name**: Anchor Verification Matching And Geometry Gates +**Description**: Verify retrieved candidates with ALIKED/DISK + LightGlue and geometric safety gates. +**Complexity**: 5 points +**Dependencies**: AZ-223_camera_ingest_calibration, AZ-225_tile_manager_cache_manifest, AZ-230_satellite_service_vpr_retrieval +**Component**: Anchor Verification +**Tracker**: AZ-231 +**Epic**: AZ-215 + +## Problem + +VPR candidates are not trusted fixes; they require local feature matching, RANSAC geometry, provenance checks, and measurable rejection evidence. + +## Outcome + +- Anchor candidates are accepted or rejected with MRE, inlier count, homography, freshness/provenance, and reason metadata. +- Matcher profiles can be benchmarked without making learned matching a per-frame VIO hot path. + +## Scope + +### Included +- ALIKED/DISK + LightGlue matching profile behavior. +- SIFT/ORB baseline profile. +- OpenCV RANSAC/USAC geometry checks. +- Anchor decision output and rejection reasons. + +### Excluded +- VPR retrieval ranking. +- Safety wrapper anchor fusion. + +## 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: Candidate verification emits evidence** +Given retrieved candidates and a usable frame +When verification runs +Then each result includes acceptance state, MRE, inlier count, and rejection/acceptance reason. + +**AC-2: Unsafe candidates are rejected** +Given low inliers, high MRE, stale provenance, or geometry failure +When verification runs +Then no accepted anchor decision is emitted for that candidate. + +**AC-3: Matcher benchmark is reportable** +Given configured matcher profiles +When benchmark runs +Then profile runtime and quality metrics are reported. + +## Non-Functional Requirements + +**Performance** +- Learned matching is trigger-based and profiled separately from BASALT. + +**Reliability** +- SuperPoint is excluded from production unless legal approval exists. + +## Unit Tests + +| AC Ref | What to Test | Required Outcome | +|--------|--------------|------------------| +| AC-1 | Valid matching fixture | Evidence fields present | +| AC-2 | Bad geometry fixture | Rejected decision | +| AC-3 | Benchmark profiles | Metrics emitted | + +## Blackbox Tests + +| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References | +|--------|-------------------------|--------------|-------------------|----------------| +| AC-1 | Aerial/cache fixture | Anchor verification path | Accepted anchors meet MRE/inlier gates | Performance | + +## Constraints + +- ALIKED/DISK + LightGlue supplies correspondences, not full VIO. +- Anchor verification does not decide final safety fusion. + +## Risks & Mitigation + +**Risk 1: False anchor acceptance** +- *Risk*: Cross-domain match looks plausible but is wrong. +- *Mitigation*: Geometry, freshness, provenance, and downstream Mahalanobis gates. diff --git a/_docs/02_tasks/todo/AZ-232_safety_anchor_state_machine.md b/_docs/02_tasks/todo/AZ-232_safety_anchor_state_machine.md new file mode 100644 index 0000000..9b099b5 --- /dev/null +++ b/_docs/02_tasks/todo/AZ-232_safety_anchor_state_machine.md @@ -0,0 +1,97 @@ +# 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_basalt_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 +- BASALT 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 + +- BASALT 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. diff --git a/_docs/_autodev_state.md b/_docs/_autodev_state.md index 2b60499..145d500 100644 --- a/_docs/_autodev_state.md +++ b/_docs/_autodev_state.md @@ -2,13 +2,13 @@ ## Current Step flow: greenfield -step: 6 -name: Decompose +step: 7 +name: Implement status: in_progress tracker: jira sub_step: - phase: 2 - name: module-layout - detail: "Module layout revised for Satellite Service and Tile Manager; awaiting confirmation before product task decomposition" + phase: 0 + name: awaiting-invocation + detail: "" retry_count: 0 cycle: 1