mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-22 05:31:14 +00:00
Refactor documentation to replace the Validation Harness with a separate E2E Test Suite, updating references throughout various documents. Adjust the autodev state to reflect the transition from the Decompose phase to the Implement phase, and revise the architecture documentation to clarify system boundaries and component relationships. Enhance risk mitigation documentation to specify affected components and update the component overview diagram accordingly.
This commit is contained in:
@@ -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 |
|
||||
@@ -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 |
|
||||
@@ -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 |
|
||||
Reference in New Issue
Block a user