Entities, capabilities, and documents

An entity is something Mainframe can name, observe, and possibly command. Aircraft, controllers, radars, tracks, sites, environments, and the system service are entities. Mainframe gives each one a stable ID and records its source:

source: {
  providerId: "world-sim",
  externalId: "SIM-STG-001"
}

The external ID is the provider’s stable identifier. For an aircraft it is its serial number. A callsign is an editable label; it is unsuitable as an automation identity filter.

Capabilities describe behavior

An entity advertises capabilities such as position, flight, battery, or video. Each capability defines channels it publishes, commands it accepts, and any continuous controls. Core attaches tasking support to entities that can fly.

A position sample includes latitude, longitude, altitude, heading, and speeds. A flight-state sample reports whether the aircraft is docked, charging, flying, returning, or landing. Command policies can further restrict individual commands, require a lease, or allow a lifecycle operation during observation.

An entity with control: "observe" is visible but does not accept ordinary flight control. Registration approval and control authority are separate: approving an entity does not change its observation policy.

Streams and state

Channels belong to a rate class:

Class	Typical use	Storage behavior
State	Position, attitude, battery, flight state	Fold into the latest picture; persist changed values at the configured channel rate
Telemetry	Time-series measurements and operational events	Persist according to the stream contract
Bulk	Spectrum and other large transient payloads	Persist only when the channel declares a storage rate

Mainframe timestamps incoming data and preserves source timestamps when supplied. Channel sequences let clients and storage order updates. Periodic state snapshots support replay without having to reconstruct every entity from the beginning of its history.

Documents describe intent and decisions

Missions, areas, rules, alerts, proposals, review items, and map catalogs are documents. They use a collection name, an ID, and a revision. Updates include expectedRev; a stale write returns HTTP 409 with the current record.

{
  "data": { "id": "patrol-east", "name": "East patrol" },
  "expectedRev": 3
}

That example shows the write envelope, not a complete mission. Use the full collection schema in packages/schema/src/collections/ when constructing a document. Deletions keep a tombstone and revision history, allowing clients to reconcile concurrent edits.