Mission SDKTracks and observations

Tracks and observations

Associate durable Track identity with detection observations and typed telemetry.

Give each observed object a stable Mission Track identity. Save its durable context, publish TrackDetected for a detection, and optionally advertise typed telemetry for continuing samples.

Consumers use the entity reference returned after a local save rather than constructing a Track identifier from a source label.

Correlation and ownership

Persist your source-to-Track mapping with the source identity and Mission scope. Two sensors can use the same external label for different objects. A label alone does not prove identity or authorize a merge.

A producer's Track belongs to the selected organization and any applicable Group placement. Select that scope before the first save. Entity, detection, and telemetry authority remain separate decisions.

Track contract

TypeFields used by the integrationMeaning
Trackexternal_id, position, scope, optional namePersistent observation context saved as a Mission entity
Positionlatitude, longitude, optional altitudeDecimal degrees and optional meters under the selected datum
TrackDetectedentity_ref, optional stream_ref, observationA detection associated with the saved Track
TrackTelemetryV1Typed position and sample freshness metadataContinuing producer observations associated with the Track

The detection type identifier is mission.track.detected.v1. The telemetry schema identifier is mission.track.telemetry.v1. The Mission reference defines full fields and Rust and Dart mappings.

Validate finite coordinates and coordinate ranges at the adapter boundary. Record the sensor's observation time separately from receipt time. Do not assume synchronized wall clocks or use the arrival time as proof that an old observation is current.

Publication sequence

  1. Save the Track locally and retain saved.entity_ref.
  2. If telemetry is available, advertise it with TrackTelemetrySchema and retain stream.reference. Supply the approved canonical schema digest, never a sample-derived or invented digest.
  3. Publish TrackDetected with the entity reference, optional stream reference, and a bounded initial observation.
  4. Publish continuing samples if the producer supplies them.
  5. Save durable updates at an explicit application cadence.

If no live telemetry is available, omit stream_ref. Do not advertise a nonexistent producer. If advertisement fails after the save, report the saved Track and unavailable stream separately.

A detection can reach a consumer before durable synchronization. Its observation gives enough context for a notification while entity resolution runs independently. Do not make remote synchronization a prerequisite for publication.

Saved and live views

Keep the latest saved Track alongside the current producer session and latest accepted live sample. Label each view's age. Use the selected stream's sequence and producer session to reject duplicates and older samples.

A restarted producer creates a new stream session. Resolve its current descriptor before subscribing again. Do not compare sequence numbers across unrelated sessions or silently trust a different producer under an old reference.

When samples stop, show stale or unavailable live state. Preserve the saved Track and its age. On reconnect, refresh durable context and discover the current stream. Missed live data does not imply automatic replay.

Platform events and Platform streams own delivery, buffering, and cancellation semantics.