Mission SDKEntities, sites, and assets

Entities, sites, and assets

Represent persistent Mission objects with domain metadata and checked placement.

A Mission entity has persistent identity, type, and organization ownership. Use it for a Track, site, or asset. Optional metadata includes position, ontology, relationships, and quantity.

Local durability and remote arrival are separate outcomes. Platform storage and replication defines those mechanisms.

Select the domain representation

ObjectMission meaningAdditional context
TrackAn observed object whose saved state and live telemetry are distinctExternal correlation, observation position, detection, and telemetry
Cache Management siteA geographic entity with recognized site ontology and team placementSite type, operational lifecycle, instructions, and inventory
AssetAn item or resourceQuantity, owning team, ontology, and containing site
DocumentA schema-bound structured recordForm fields and optional workflow, not an interchangeable entity

Cache Management recognizes a geographic entity as a site through site_type: cache or site_type: bdl, lifecycle, and ownership metadata. Coordinates alone are insufficient.

Create with placement

CreateEntityParams specifies the entity identity, organization, type, name, position, affiliation, and optional initial quantity. CreateEntityWithPlacementParams adds encoded ontology, location_id, and team_id.

atlas.app().entities().create_entity_with_placement(...) returns EntityDetail. Retain the returned identity. A local commit does not prove the entity already arrived on another peer.

Use location_id for containment, such as an inventory item located at a site. Use team_id for assignment. Match the metadata's team identifier to the checked placement. Do not create an unprotected entity and patch its ownership afterward as an admission shortcut.

Supply the verified organization, authorized team, initial position, and canonical encoded_site_ontology bytes. Placement remains part of the checked creation operation.

Separate three kinds of state

  • Entity fields retain persistent context and the latest saved state.
  • Typed Mission notifications report an observation or change through the live event path.
  • Telemetry provides continuing samples from a producer.

A durable entity activity record is also distinct from a live notification. For example, Cache Management records cache.established in site activity. That history entry is not the TrackDetected distribution contract.

See events and telemetry for typed payload meaning and links to canonical delivery behavior.

Entity lifecycle and site lifecycle

Entity lifecycle determines whether the object is active, archived, or deleted. Archive hides it from normal lists, maps, and counts while retaining its values and history. Restore returns an archived entity to Active. Delete is terminal.

Archived entities reject ordinary field, position, ontology, and relationship edits. Restore requires the same authority as Archive. Do not replay an old create operation to restore a deleted entity.

A site's ontology lifecycle is separate. Cache Management uses loaded, accessed, emptied, and compromised. An emptied site is not an archived entity. Show the site's operational state without confusing it with entity retention.

Resolve and update

An entity reference identifies an object, not its snapshot. After an early detection, resolve it with mission.entities.resolve(entity_ref, options) under independent entity-read authority and a bounded deadline. Display the authorized observation while resolution remains pending.

Keep the saved view and live view separate. A newer telemetry sample does not prove the durable entity changed. A late durable read must not overwrite a fresher live position on the screen.

For team-assigned non-geographic entities, modification needs the owning team's authority or administrator authority. Protected data also requires its policy access. The SDK makes the final decision for each operation.

Tracks defines continuous observations.