# 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 |