[AZ-220] Add shared runtime contract models

Implement the shared DTO contract surface with validation so runtime components consume one public model set instead of duplicating shapes.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-03 13:22:50 +03:00
parent 72a9df6b57
commit 5156453224
8 changed files with 361 additions and 3 deletions
@@ -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.