Skip to main content

AEROSIM-TS-21

Project task

Define the shared typed Socket.IO contract

Nebula and Singularity compile against one versioned event map with explicit payload, acknowledgement, ordering, and error contracts.

AEROSIM-TS-21Canonical ID TASK-0021
Verified flow state
Done
Owner
AeroSim Architecture and Delivery
Component
Web Application / Socket.IO client and API Service / Socket.IO gateway — Shared typed application-event contract
Repository
corp-v1-aerosim/corp-v1-aerosim

Delivery scope

Publish one shared Socket.IO event map defining client event flight:command, server event flight:state, acknowledgement CommandAck, monotonic sequence, protocolVersion, and ProblemEvent schemas for both Nebula and Singularity. Primary files: packages/realtime-contract/src/events.ts, packages/realtime-contract/src/schemas.ts, packages/realtime-contract/src/index.ts, packages/realtime-contract/tests/event-contract.test.ts.

Implementation contract

Implementation artifacts

  • packages/realtime-contract/src/events.ts
  • packages/realtime-contract/src/schemas.ts
  • packages/realtime-contract/src/index.ts
  • packages/realtime-contract/tests/event-contract.test.ts

Inputs

  • FlightCommand {commandId,sequence,axes:{pitch,roll,yaw,throttle}}
  • FlightState {sequence,position,rotation,velocity,serverTime} and protocol version constant

Outputs

  • ClientToServerEvents, ServerToClientEvents, InterServerEvents, and SocketData TypeScript interfaces
  • Runtime schema parsers for FlightCommand, FlightState, CommandAck, and ProblemEvent

Failure boundaries

  • Reject non-finite axis values, throttle outside 0..1, missing commandId, and protocolVersion mismatch.
  • Fail compile-time contract tests if Web or API declares a same-named event with a divergent payload.

Excluded scope

  • Transport connection handling, flight-physics calculation, telemetry history, and arbitrary user-defined events are outside the contract package.

Verification steps

  • pnpm --filter @aerosim/realtime-contract typecheck && pnpm --filter @aerosim/realtime-contract test
  • Run the duplicate-event import boundary test and assert applications/web and applications/api import event types only from @aerosim/realtime-contract.

Traceability

Requirements

Dependencies

UI/UX applicability

non_visual

This Task owns technical or behavioral acceptance and does not claim direct visual conformance to the approved UI/UX package.

Acceptance evidence

Verified delivery: application PR #21 reviewed head de6830e6001c5c2dd400c15f06637e767f5f6d6b, exact-head validation task 1800 succeeded, merged as b549ca321ea5d3a8a13b9b792a67c77497f6773b; Wave 4 integrated application head e8bfe781d3295d445cbc46b297874f066cac8301 passed publish task 1832 and validate task 1833. Release completion verified on product 1.0.0.0 at GitOps revision 5d3712d89dfbf7dacd993348e55f497d126c7bf9 with Argo Synced/Healthy, exact image digests, authenticated API/database access, and three-world configured-flight acceptance.

Current evidence boundary

No current implementation, acceptance, release, or deployment evidence is claimed for this planned Task. Any prior implementation may be used only as prototype and discovery evidence.