# Gelios Domain Ontology

Package: `catalog/domain-packages/gelios`

Status: `v1.1.0`, source-evidenced and product-required.

## Purpose and boundary

The package describes Gelios fleet, telemetry, sensor, spatial, report and
command meanings. It is not a provider client, credential store, runtime
database, renderer implementation, NDC L1 agent or NDC L2 workflow.

Gelios is the first live provider used to prove the common provider-package
model. Runtime transport, collection cadence and semantic mapping belong to an
isolated NDC L2 connection instance. External Data Plane persists and delivers
provider-neutral Data Products. Ontology Core describes meaning only.

The current matching contract/data artifact is
`platform/packages/external-provider-contract/providers/gelios/v4`. Adding a
second account creates another connection instance with different opaque
credential references; it does not create another ontology package, Platform
service or custom node.

## Provider authentication boundary

Gelios issues exactly two provider secret artifacts: an access token and a
refresh token. The current rotating credential uses the access token for
requests and keeps refresh inside native NDC L2 Credentials; neither token
value belongs in Ontology, a workflow graph, MCP, Ops or a trace.

A credential label such as `read access` is operator metadata, not a Gelios
token scope. `gelios.units.current.read` and
`gelios.monitoring_config.current.read` are classified as read because the
approved transports are `GET /api/v1/units` and
`GET /api/v1/users/me/monitoring-config`. The label does not create a
separate read token or constrain other rights that Gelios may have granted to
the same access token. The scoped Data Product writer credential later in the
runtime path is an internal NDC/External Data Plane capability, not a third
Gelios token.

## Dynamic connection scope

`gelios.access_scope` is derived from two inputs on every collection run:

1. safe-read capabilities selected in the connection profile;
2. entities currently visible to the bound provider credential.

For `gelios.units.current.read`, NDC L2 processes every valid unit returned by
`GET /api/v1/units`. Static unit IDs, owner allowlists and provider-group business
filters are forbidden at collection boundary. New units visible to the same
credential appear automatically. Foundry and other Data Product consumers own
layer selection, sorting, filtering and visibility.

Technical limits such as a 5000-fact batch ceiling, retry policy and response
validation protect runtime health; they are not business entity filters.

## Canonical value contracts

### Unit and device

`gelios.unit` is a stable provider subject. The published v1 source ID is
`gelios-unit-<sourceUnitId>` inside immutable `(providerId, connectionId)`
scope; a renderer entity ID or display name is never identity. The provider ID
suffix is preserved as an exact string (including leading zeros) and is never
parsed or renumbered. A unit can use a
`gelios.tracker_device`, belong to multiple `gelios.unit_group` records and
expose sensor, fuel, maintenance and custom-field configurations.

Hardware IDs, IMEI, phones, address, decrypt-related fields, raw `params` and
unclassified sensor payloads are excluded by the current field policy. New provider
fields remain dropped until they are evidenced, classified and introduced by a
new package/ontology revision.

### Current telemetry and position

`gelios.telemetry_snapshot` is normalized by the versioned NDC L2 mapping.
`gelios.position_fix` is its time-qualified spatial portion; it is not a pin or
other renderer object.

The current approved output is exactly:

```text
Data Product:       fleet.positions.current.v3
version:            3.0.0
ontology revision:  ontology.map.moving_object.v3
semantic type:      map.moving_object
delivery:           snapshot+patch
history:            sampled, latest entity per 60-second bucket, 90 days
```

Allowed Data Product fields are:

```text
course_degrees
display_name
elevation_meters
geometry
hdop
horizontal_accuracy_meters
movement_state
object_kind
position_source
satellite_count
signal_state
speed_kph
```

All attribute names are snake_case. GeoJSON `geometry` is omitted when valid
coordinates are unavailable, but the unit remains in the product. Missing
geometry is not converted into a Gelios monitoring status. If the provider has
no last-message timestamp, the collection receive time becomes the explicit
`observedAt` fallback so the credential-visible unit is not silently dropped.

### Official monitoring states

Gelios does not return a ready-made operational-status enum from
`GET /api/v1/units`. Its monitoring client derives two independent, closed
value contracts from official source facts and settings:

```text
signal_state:
  active   -> На связи / Active units
  inactive -> Не на связи / Inactive units

movement_state:
  moving -> В движении / Moving units
  stopped -> Неподвижные / Stopped units
```

The official client first marks a unit active while the age of `lastMsg.time`
is below `monitoring-config.signalActiveDuration`, then keeps it active through
the positive `signalSomewhatInactiveDuration` window. A missing message is
inactive. When an account returns empty monitoring durations, the connection
profile may supply an explicit, versioned positive fallback; its provenance is
runtime policy and does not create another ontology state. Without a resolved
positive threshold publication must fail closed. `movement_state=moving` when
the integer `lastMsg.speed` is greater than `2`; otherwise it is `stopped`.
The values and Russian labels are the official Gelios monitoring-client
contract.

There is no `unknown`, `fresh`, `stale`, GPS-quality, position-quality,
`parked`, `no_position` or aggregate `operational_status` value in this
contract. `gelios.operational_status` is retained in the catalog only as a
`tech-debt-noncanonical` marker for retiring old v1/v2 products.

### Sensors and operational semantics

`gelios.sensor_definition`, `gelios.sensor_conversion` and
`gelios.sensor_reading` separate device configuration, calibration and
time-series values. Fuel profile, maintenance plan and custom field are
independent concepts. A sensor meaning cannot enter a Data Product until its
message parameter, unit, conversion, classification and field policy are
approved.

### Spatial binding

Gelios is a source domain. The provider-neutral relation is:

```text
gelios.unit + gelios.position_fix
  -> map.moving_object
  -> fleet.positions.current.v3
  -> Foundry Data Product binding
  -> map layers, selection and telemetry panel
```

The publish boundary contains stable facts only. It cannot contain provider
credentials, tenant/connection claims supplied by the workflow, raw payloads,
pixel values, styles or transient renderer identities. The synthetic contract
fixture is
[`examples/gelios-map-moving-object.fixture.json`](../examples/gelios-map-moving-object.fixture.json).

### Commands

`gelios.command_template` and `gelios.command_group` are read-only catalogue
concepts. `gelios.command_dispatch`, `gelios.command_delivery` and
`gelios.command_audit` are a separate red domain.

No collection run, workflow, map click or autonomous agent may create a
dispatch. A future command path requires explicit human intent, confirmation,
separate authorization, immutable audit and delivery reconciliation. This
ontology and the Gelios v4 provider package expose no command transport.

## Canonical runtime flow

```text
Gelios safe-read API
  -> opaque Gelios access credential in NDC L2 Credentials
  -> isolated NDC L2 connection workflow
  -> versioned semantic mapping
  -> NDC Data Product Publish through a native scoped writer credential
  -> External Data Plane
  -> scoped snapshot + patch stream
  -> Foundry Data Product binding
```

There is no Gelios-specific Platform service or database in this model.
Provider transport never enters External Data Plane or Foundry. `gelios.collection_run`
and `gelios.ingestion_cursor` describe audit and resumability independently of
physical storage.

## Guardrails

- Ontology Core never stores credentials, account state, runtime snapshots,
  full raw telemetry or bulk geometry.
- Gelios authentication has exactly access and refresh artifacts; credential
  labels and workflow classifications must not be reinterpreted as additional
  provider token types or scopes.
- Every safe-read collection includes all valid entities returned for the
  bound credential; unit allowlists and group filters are not collection
  scope.
- A read method alone does not make a capability safe: impersonation,
  temporary credential issuance, configuration mutation and downloads remain
  excluded until separately classified.
- Dynamic provider fields are dropped until evidenced and classified.
- Gelios monitoring filters use only the exact `signal_state` and
  `movement_state` value contracts. L2, Data Products and Foundry cannot add
  fallback state values.
- Geozones and history require bounded loading, paging/cursors, retention and
  volume controls.
- Command send and mutation capabilities remain red even when provider access
  exists.
- Foundry targets stable domain subjects and Data Product fields, not provider
  payloads or renderer identities.

## Evidence and evolution

Evidence is limited to official Gelios API documentation, safe-read results,
historical NDC L2 donor inspection and provider-neutral map contracts. The
Robot2B pilot counts (107 credential-visible units and a 95-unit legacy
snapshot) are retained only as historical evidence of response shape and
cardinality. They do not define canonical IDs, collection allowlists or product
scope.

Extension order is mandatory: establish safe provider evidence, extend
capability/field classification, update ontology and mapping revision, add
synthetic fixtures and contract tests, then deploy an updated NDC L2 workflow.
