Oleksandr Bezdieniezhnykh
5156453224
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>
2.5 KiB
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.