106 lines
7.2 KiB
Markdown
106 lines
7.2 KiB
Markdown
# 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.
|