# Gelios provider package v1

Это versioned contract/data package для первого живого provider connection в
NODE.DC. Он не является runtime service, custom node, account configuration или
хранилищем telemetry. Provider-specific request и mapping исполняются внутри
изолированного NDC L2 workflow; Platform получает только provider-neutral Data
Product.

Package фиксирует:

- manifest `gelios.provider.v1@1.0.0`;
- точный provider token lifecycle: Gelios выдаёт `access` и `refresh`, а
  HTTP request использует `access`;
- safe-read capability `gelios.units.current.read`
  (`GET https://api.geliospro.com/api/v1/units` with an opaque bearer
  credential);
- dynamic scope `all_visible_to_credential` без unit/group allowlist;
- realtime profile с интервалом 10 секунд и manual profile;
- fail-closed field policy: неизвестные и dynamic fields отбрасываются до
  классификации, hardware IDs, phone/address, raw params и sensor payloads не
  публикуются;
- mapping в `map.moving_object`;
- стабильный source ID `gelios-unit-<sourceUnitId>` с точным сохранением
  строкового provider ID;
- explicit derivation rules для `position_valid`, `operational_status` и
  `quality_flags`, включая `no_position` и stale threshold 60 секунд;
- точный Data Product `fleet.positions.current.v1@1.0.0`, revision
  `ontology.map.moving_object.v1`, с 13 разрешёнными snake_case fields;
- provider-neutral NDC L2 template descriptor из пяти boundary steps:
  trigger → request → extract → map → `NDC Data Product Publish`;
- publish credential binding с `management: control_plane_managed`, без
  caller-supplied writer reference;
- synthetic source/publish fixture, включая видимый объект без координат.

## Authentication boundary

Gelios выдаёт ровно два provider secret artifact: access token и refresh
token. Это не отдельные read/write tokens. Текущий NDC L2 HTTP binding типа
`httpBearerAuth` подставляет access token в `Authorization`; автоматический
refresh этим runtime пока не доказан, поэтому package явно фиксирует
`refreshMode: operator_managed`. Ни access, ни refresh value не попадает в
package, graph, fixture, MCP, Ops или trace.

Название native credential, например `Gelios — Robot2B — read access`, является
только операторской меткой. `read` в `gelios.units.current.read` —
классификация разрешённого workflow endpoint `GET /api/v1/units`, а не scope
access token. Метка credential не создаёт отдельный «read token» и не сужает
права, которые фактически выдал Gelios.

Unit без last message не исчезает: mapping использует collection receive time
как `observedAt` fallback и публикует subject без geometry с
`position_valid=false`/`operational_status=no_position`.

Префикс source ID для v1 — строго `gelios-unit-`. Сокращённый `unit-` не
является каноническим: он создал бы второй entity key рядом с уже сохранённым
Gelios subject. Значение provider ID после префикса преобразуется только в
строку; ведущие нули и остальные значимые символы не нормализуются.

`fleet.positions.current.v1` ограничен 5000 current entities. Если credential
видит больше, NDC L2 не должен отбрасывать «лишние» units: package/profile
требует остановить Deploy до новой partitioned Data Product revision. Полное
автоматическое enforcement этого правила остаётся gate будущего
package-to-graph compiler/runtime validator.

Один package обслуживает любое число accounts. Для каждого account вызывается
`instantiateL2Connection` с новым `tenantId`, `connectionId`, provider
credential reference. Это единственная credential reference, которую передаёт
caller: она адресует Gelios access binding в native NDC L2 Credentials.
Внутреннюю capability для публикации в External Data Plane выдаёт и сохраняет
control plane; caller не передаёт writer secret или `writerCredentialRef`.
Результат instantiation содержит только provider ref и декларативный
`systemBindings.publisher` со статусом `unresolved`, который Platform должна
разрешить в native credential binding. Эта capability не выдаётся Gelios, не
является третьим Gelios token и не описывает права provider account. Добавление
account не меняет Platform source.

Расширение Gelios происходит новой версией package: сначала подтверждаются
provider capability/fields, затем обновляются ontology, field policy, mapping,
fixtures и tests. Пользовательские workflow, которые уже покрываются
существующим catalog, не требуют участия разработчика Platform.

Технический runtime type publish boundary остаётся
`n8n-nodes-ndc.ndcDataProductPublish`; это идентификатор общего NDC package, а
не Gelios-specific node.

## Текущая готовность

Package, ontology links и synthetic fixtures проверены в source. Production
Engine L2 target использует зарегистрированный Gelios Bearer credential на
точном safe-read endpoint и managed `ndcDataProductWriterApi` generation g3;
оба binding записаны без раскрытия secret values. Canonical graph содержит
provider read, extraction, mapping и native `NDC Data Product Publish`.

Fresh production execution `881722` завершился успешно и опубликовал
`fleet.positions.current.v1`; managed writer g3 принят и имеет state `current`.
Это доказывает manual provider read → canonical Data Product path. Внутренняя
writer capability остаётся NODE.DC capability и не может быть заменена access
или refresh token Gelios.

Не доказаны: автоматический refresh, Schedule Trigger 10 секунд, несколько
последовательных scheduled cycles, retry/backoff, sampled history/retention на
continuous path и Foundry snapshot/patch → moving pins E2E. Provider package
остаётся declarative: MCP package discovery и package/profile → L2 graph
compiler пока отсутствуют, поэтому первый graph собран через общие Engine MCP
graph tools.