gps-denied-onboard/_docs/02_document/contracts/shared/runtime_contracts.md

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, AZ-243 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
VioProcessingResult	optional VIO state, health report, latency, error envelope	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