docs(platform): align connector, EDP, and deploy canon
This commit is contained in:
Codex
@@ -2,108 +2,202 @@
|
||||
|
||||
Package: `catalog/domain-packages/gelios`
|
||||
|
||||
Status: `v0.1.0` source-evidenced and product-required slice for the Robot2B client context and the Gelios provider.
|
||||
Status: `v1.0.0`, source-evidenced and product-required.
|
||||
|
||||
## Purpose and boundary
|
||||
|
||||
The package describes the meaning of Gelios fleet, telemetry, sensor, spatial, report and command concepts. It is not a Gelios client, token store, telemetry database, Cesium implementation or Engine workflow.
|
||||
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.
|
||||
|
||||
The practical audit established a wide REST read surface: 107 currently visible units, 105 with `lastMsg`, a visible administrative account, unit groups, telemetry variants, sensor catalogues, command-template catalogues, geozone groups and report templates. The REST OpenAPI documents 295 operations. This ontology therefore separates three things that must not be conflated:
|
||||
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.
|
||||
|
||||
1. documented provider capability;
|
||||
2. actual runtime read evidence for the current account;
|
||||
3. approved Robot2B product scope.
|
||||
The matching contract/data artifact is
|
||||
`platform/packages/external-provider-contract/providers/gelios/v1`. 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.
|
||||
|
||||
The 95-unit legacy Engine snapshot is a temporary compatibility reference only. It is not the final business scope. The provider's current groups also do not resolve that scope automatically. A Robot2B owner must approve an allowlist or equivalent rule represented by `gelios.access_scope`.
|
||||
## Provider authentication boundary
|
||||
|
||||
Gelios issues exactly two provider secret artifacts: an access token and a
|
||||
refresh token. The current NDC L2 `httpBearerAuth` request binding uses the
|
||||
access token. Automatic refresh has not been proven in the deployed runtime, so
|
||||
the matching provider package records refresh as `operator_managed`; 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` is classified as read because the
|
||||
approved workflow transport is `GET /api/v1/units`. 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 the stable business subject. The durable key is a namespaced provider identity such as `gelios.unit:<sourceUnitId>`, never a renderer entity ID or a display name. A unit can use a `gelios.tracker_device`, belong to multiple `gelios.unit_group` records and expose sensor, fuel, maintenance and custom-field configurations.
|
||||
`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 and decrypt-related fields are restricted or secret-class data. They are not part of the default Studio contract.
|
||||
Hardware IDs, IMEI, phones, address, decrypt-related fields, raw `params` and
|
||||
unclassified sensor payloads are excluded by the v1 field policy. New provider
|
||||
fields remain dropped until they are evidenced, classified and introduced by a
|
||||
new package/ontology revision.
|
||||
|
||||
### Current telemetry
|
||||
### Current telemetry and position
|
||||
|
||||
`gelios.telemetry_snapshot` is the normalized current state produced by the Gateway, with at least:
|
||||
`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 first approved output is exactly:
|
||||
|
||||
```text
|
||||
unitSubjectId
|
||||
observedAt
|
||||
receivedAt
|
||||
position: { latitude, longitude, height?, course?, speed?, satellites? }
|
||||
operationalStatus
|
||||
sensorReadings[]
|
||||
counterValues[]
|
||||
qualityFlags[]
|
||||
source: gelios-rest
|
||||
Data Product: fleet.positions.current.v1
|
||||
version: 1.0.0
|
||||
ontology revision: ontology.map.moving_object.v1
|
||||
semantic type: map.moving_object
|
||||
delivery: snapshot+patch
|
||||
history: sampled, latest entity per 60-second bucket, 90 days
|
||||
```
|
||||
|
||||
The source supports a raw and a pure last-message variant. Pure data may include sensors, counters and accumulated fields. Raw messages and dynamic `params` remain behind restricted policy and may be retained separately for diagnostics only. `gelios.position_fix` is the time-qualified position portion used by spatial consumers; it is not itself a pin.
|
||||
Allowed Data Product fields are:
|
||||
|
||||
```text
|
||||
course_degrees
|
||||
display_name
|
||||
elevation_meters
|
||||
geometry
|
||||
hdop
|
||||
horizontal_accuracy_meters
|
||||
object_kind
|
||||
operational_status
|
||||
position_source
|
||||
position_valid
|
||||
quality_flags
|
||||
satellite_count
|
||||
speed_kph
|
||||
```
|
||||
|
||||
All attribute names are snake_case. GeoJSON `geometry` is omitted when valid
|
||||
coordinates are unavailable, but the unit remains in the product with
|
||||
`position_valid=false`, `operational_status=no_position` and appropriate
|
||||
`quality_flags`. 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.
|
||||
|
||||
### Sensors and operational semantics
|
||||
|
||||
`gelios.sensor_definition`, `gelios.sensor_conversion` and `gelios.sensor_reading` separate stable device configuration, calibration and time-series readings. Fuel profile, maintenance plan and custom field are independent configuration concepts. No assumed sensor meaning should be added to analytics until its message parameter, measure and conversion semantics are approved.
|
||||
`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 and Cesium pins
|
||||
### Spatial binding
|
||||
|
||||
Gelios is a source domain; Cesium is a renderer adapter. The binding is deliberately provider-neutral:
|
||||
Gelios is a source domain. The provider-neutral relation is:
|
||||
|
||||
```text
|
||||
gelios.unit
|
||||
-> map.moving_object (stable spatial subject)
|
||||
gelios.position_fix
|
||||
-> map.moving_object (current position update)
|
||||
map.moving_object
|
||||
-> map.pin + map.label + map.visibility_rule
|
||||
-> map.renderer_adapter (Cesium today, replaceable later)
|
||||
gelios.unit + gelios.position_fix
|
||||
-> map.moving_object
|
||||
-> fleet.positions.current.v1
|
||||
-> Foundry Data Product binding
|
||||
-> map layers, selection and telemetry panel
|
||||
```
|
||||
|
||||
The future map payload selects a stable `subjectId`, position, normalized operational status, observed time and approved label fields. It must not contain Gelios credentials, raw payloads or Cesium transient entity references. This is the replacement boundary for the current M-map node-to-Cesium coupling.
|
||||
|
||||
The Map Page resolves the selected Studio profile to the shared map.pin contract. The initial accepted presentation is an elevated spike — ground anchor, stem, outlined head and label — but that visual configuration remains on the Studio side. Gelios publishes data for a stable subject; it never publishes Cesium primitive settings, pin pixels or a renderer entity ID.
|
||||
|
||||
The proposed renderer-neutral payload is in [`examples/gelios-map-moving-object.fixture.json`](../examples/gelios-map-moving-object.fixture.json). It uses synthetic coordinates only: it specifies the interface between Gateway and Map View, not a live trike position and not a Cesium entity.
|
||||
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.
|
||||
`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 dispatch requires an explicit human action, approved scope, selected unit/group and template/parameters, confirmation, an audit record and delivery-state reconciliation. This ontology package does not grant or test a write permission.
|
||||
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 v1 provider package expose no command transport.
|
||||
|
||||
## Future data plane
|
||||
|
||||
The intended flow is:
|
||||
## Canonical runtime flow
|
||||
|
||||
```text
|
||||
Gelios REST OAuth
|
||||
-> server-side Gelios Gateway
|
||||
-> scope filter + field policy + normalizer
|
||||
-> durable telemetry/configuration storage
|
||||
-> NDC level-2 workflow / internal data contract
|
||||
-> Map View binding / Cesium renderer adapter
|
||||
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
|
||||
```
|
||||
|
||||
`gelios.collection_run` and `gelios.ingestion_cursor` define collection governance independently of the transport implementation. They support bounded incremental history ingestion later: one approved unit scope, limited time window, field whitelist, volume limit and durable checkpoint. They do not imply that all history should be collected now.
|
||||
|
||||
Database technology is intentionally not chosen by Ontology Core. The proposed platform data-plane boundary and its validation gates are documented in [`platform/docs/ADR_GELIOS_DATA_PLANE.md`](../../../docs/ADR_GELIOS_DATA_PLANE.md). The ontology supplies the record boundaries needed by that ADR.
|
||||
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 secrets, runtime snapshots, full raw telemetry or large geometry datasets.
|
||||
- Current provider-account visibility is not the approved Robot2B scope; collection must enforce an owner-approved scope before every run.
|
||||
- GET alone does not make a route safe: login-as, temporary tokens, configuration and WLN download are excluded from telemetry collection.
|
||||
- Geozones require paging, filtering, volume controls and map LOD.
|
||||
- Command send and mutation routes remain red even if the account has documented access.
|
||||
- Map selection and pins target stable domain subjects, not provider payload IDs or renderer objects.
|
||||
- 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.
|
||||
- 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 next implementation decisions
|
||||
## Evidence and evolution
|
||||
|
||||
Evidence is limited to official REST OpenAPI, safe GET results, historical Engine donor inspection and the MAP package. The next decisions outside this ontology package are:
|
||||
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.
|
||||
|
||||
1. owner-approved Robot2B allowlist/rule;
|
||||
2. field policy for Studio, analytics and raw retention;
|
||||
3. data-plane ADR for realtime telemetry and history;
|
||||
4. Gelios Gateway implementation boundary and deployment location;
|
||||
5. fixture and renderer-adapter contract for Map View pins and labels.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user