docs(platform): align connector, EDP, and deploy canon

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

@@ -0,0 +1,105 @@
+# 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.