NODEDC_PLATFORM/packages/external-provider-contract/providers/gelios/v1/README.md

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.