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