---
doc_id: ARC-CK8S-PROVIDER-INTEGRATION-0001
type: api-contract
title: kodex — модель интеграции с провайдерами
status: active
owner_role: SA
created_at: 2026-04-26
updated_at: 2026-05-25
related_issues: [599, 600, 601, 602, 711, 725, 729, 737, 761, 770, 781, 322, 908]
related_prs: []
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-26-platform-architecture-frame"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-26
---

# Модель интеграции с провайдерами

## Кратко

GitHub является первой реализацией контура интеграции с провайдерами, GitLab должен лечь в ту же архитектурную границу. Агенты в слотах могут работать с нативными артефактами провайдера через `gh` или нативный API, а быстрый agent-manager и платформенные операции идут через `platform-mcp-server` и `provider-hub`. Пользовательский интерфейс и приёмка работают по зеркальным проекциям и не читают провайдера на каждый экран.

## Контур интеграции с провайдерами

Контур интеграции с провайдерами покрывает:
- репозитории кода и рабочих артефактов;
- репозитории проектной документации;
- репозитории пакетов и руководящей документации;
- релизные ветки и теги;
- операционное состояние авторизации, лимитов и блокировок по внешним аккаунтам, зарегистрированным в `access-manager`;
- будущие внешние системы, где платформа не хранит истину сама.

`provider-hub` является сервисом-владельцем интеграции с провайдерами. Он изолирует особенности GitHub/GitLab и отдаёт остальным сервисам нормализованные контракты. Канонический реестр внешних аккаунтов, область их применения и политика использования находятся в `access-manager`.

## Категории операций

| Категория | Кто вызывает | Как проходит |
|---|---|---|
| Событие webhook | Провайдер | `integration-gateway` проверяет источник, подпись, размер payload, лимиты и backpressure на границе, затем вызывает `provider-hub.IngestWebhookEvent`; `provider-hub` фиксирует inbox как safe envelope с digest/provider refs и нормализует событие без долговременного хранения raw body. |
| Каноническое чтение | Сервис-владелец или приёмка | `provider-hub` читает провайдера с учётом лимитов и разрешения на использование внешнего аккаунта. |
| Операция провайдера | Agent-manager или платформенный сервис | Через `platform-mcp-server` и `provider-hub`, если операция платформенная или требует политики и аудита. |
| Работа агента в слоте | Ролевой агент | Через `gh`, `glab` или нативный API в слоте по профилю роли. |
| Сверка | `worker` по поручению `provider-hub` | Инкрементальный курсор, окно перекрытия, приоритеты горячих, тёплых и холодных сущностей. |

## Нормализованные объекты

| Объект | Минимальный смысл |
|---|---|
| `ProviderAccountRuntimeState` | Операционное состояние внешнего аккаунта у провайдера: статус авторизации, лимиты, доступность операций и последние ошибки. |
| `ProviderRepository` | Внешний репозиторий, владелец, видимость, идентификатор провайдера, URL и привязка к проекту. |
| `ProviderWorkItem` | Нормализованный `Issue` или `PR/MR` с идентификатором провайдера, номером, состоянием, заголовком, метками, назначенными пользователями, вехой и проектными полями. |
| `ProviderComment` | Комментарий, упоминание или сигнал review, связанный с рабочим артефактом. |
| `ProviderRelationship` | Связь между `Issue`, `PR/MR`, последующей задачей, блокировкой, релизом или артефактом. |
| `ProviderLimit` | Текущее известное состояние лимитов, время сброса, класс ограничения и затронутый аккаунт. |
| `ProviderOperation` | Запись внешней операции, инициатор, аккаунт, цель, результат и ошибка. |

## Синхронизация проекций

### Входящий журнал webhook

Webhook является быстрым входом, но не единственной гарантией актуальности.

Обязательные правила:
- внешний HTTP webhook принимает только `integration-gateway`;
- `integration-gateway` не парсит бизнес-смысл payload глубже edge envelope и не хранит provider projections;
- входящее событие сначала фиксируется во входящем журнале как digest и safe envelope, а не как долговременное raw body;
- дедупликация выполняется по delivery id или аналогу провайдера;
- нормализация и пересчёт проекции идут асинхронно;
- ошибка обработки сохраняет безопасную причину и digest; повторная обработка не читает raw body из БД, а использует safe facts или provider API refetch по stable refs там, где есть согласованный внешний аккаунт;
- каждый пересчёт публикует доменное событие для потребителей.

### Инкрементальная сверка

Инкрементальная сверка обязательна, потому что webhook может потеряться или прийти с задержкой.

Правила:
- хранить `sync_cursor` по области синхронизации: репозиторий, тип артефакта или другая область провайдера;
- фиксировать выбранный внешний аккаунт в `sync_cursor`, чтобы worker подтверждал уже выбранный аккаунт через `access-manager`, а не подбирал его неявно;
- использовать окно перекрытия для пограничных изменений;
- различать горячие, тёплые и холодные сущности;
- при дефиците лимитов сохранять бюджет на горячие сущности;
- повышать `drift_status`, если проекция могла устареть.

### Сигнал от агента в слоте

Если агент в слоте создал или изменил артефакт через `gh` или API, он передаёт платформе идентификатор провайдера, URL или `owner/repo/number` как ускоряющий сигнал. Этот сигнал не заменяет webhook и сверку, а только помогает быстрее обновить проекцию.

## Лимиты и учёт `gh`

Операции через `provider-hub` учитываются детерминированно: платформа знает аккаунт, операцию, цель, заголовки ответа и итог.

Перед операцией или сверкой `provider-hub` передаёт в `access-manager` выбранный внешний аккаунт, действие и область использования. `access-manager` подтверждает активный аккаунт, активного поставщика, активную привязку, разрешённое действие и возвращает `provider_slug` вместе со ссылкой на секрет. Значение секрета получает уже `provider-hub` через общий resolver-клиент; `access-manager` не выдаёт токены и не становится прокси секретов. Значение используется только в памяти процесса на время операции и не попадает в БД, события, аудит, трассировку, логи или ошибки.

Для прямой работы агента в слоте через `gh` действует приближённый учёт:
- до и после агентного запуска снимается `gh api rate_limit`;
- для высокообъёмных действий агент отправляет промежуточные снимки через MCP;
- если используется `gh api`, агент может передать заголовки ответа, полученные через `gh api --include`;
- высокоуровневые команды `gh issue` и `gh pr` не считаются полным источником телеметрии.

Целевое усиление: операции, где нужен строгий лимитный бюджет, должны идти через прокси провайдера или MCP-инструменты платформы.

## Платформенные операции записи

Платформенные операции записи в провайдера делятся на два уровня:

- снаружи `agent-manager`, platform MCP и внутренние домены вызывают типизированные инструменты: создать репозиторий, создать задачу, обновить задачу, создать или обновить комментарий, создать или обновить `PR/MR`, оставить review-сигнал, обновить связь;
- внутри `provider-hub` все эти инструменты проходят общий конвейер команд с единой идемпотентностью, проверкой доступа, предварительной `in_progress`-записью операции перед внешним side effect, журналом результата и публикацией событий; реальный GitHub write-вызов выполняет provider-адаптер поверх этого конвейера, а GitLab должен подключаться тем же способом.

Создание репозитория у провайдера остаётся provider-native операцией. Для GitHub платформа использует `auto_init=true`, чтобы провайдер создал начальный default branch и безопасный начальный commit, а `provider-hub` вернул `base_branch` для последующего bootstrap PR. Для существующего репозитория `provider-hub` создаёт или обновляет adoption branch/PR только по уже подготовленным файлам и refs. `provider-hub` не генерирует `services.yaml`, не выбирает шаблон, не выполняет adoption scan и не становится владельцем project policy.

Risk-based approval policy не живёт в `provider-hub`. Она зависит от роли, проекта, типа операции, target, стадии и изменяемых полей и владеется `governance-manager`. Вызывающий контур передаёт в команду безопасный `operation_policy_context`; если policy требует подтверждение, он передаёт отдельную ссылку `approval_gate_ref` на уже принятое approval/gate решение. `provider-hub` проверяет наличие этой ссылки, фиксирует её в `ProviderOperation` и не становится владельцем risk/gate decision.

Команды записи не принимают свободный JSON patch. Изменяемые поля перечислены в типизированном запросе и отражены в `changed_fields` контекста политики. Inline comments для review-сигнала передаются через типизированный контракт `ReviewInlineComment`, а не через строковый JSON.

## Нативные поля провайдера

Платформа использует нативные поля провайдера там, где они полезны человеку и не требуют постоянного переписывания быстро меняющегося состояния среды исполнения.

Допустимые поля:
- type;
- метки;
- связи;
- комментарии и упоминания;
- состояние;
- состояние review;
- назначенные пользователи;
- milestone;
- проектные поля;
- ветки и теги для релизной политики.

Не размещать в нативных полях провайдера:
- текущее состояние слота;
- внутренние retry-счётчики;
- полный лог среды исполнения;
- технические детали задания;
- быстро меняющиеся диагностические данные.

## Сначала GitHub, затем GitLab

Первая реализация:
- GitHub webhook;
- `Issue`, `PR`, комментарии, упоминания и review;
- использование GitHub bot/user аккаунтов, зарегистрированных в `access-manager`;
- `gh` в слоте;
- обработка лимитов;
- зеркало провайдера и сверка.

Архитектурные требования для следующего провайдера:
- в доменах нет прямых GitHub REST/GraphQL путей;
- нормализованная модель не содержит обязательных полей, доступных только в GitHub, без резервного варианта;
- `provider-hub` скрывает различия API;
- пользовательский интерфейс использует нормализованные проекции.

## Апрув

- request_id: `owner-2026-04-26-platform-architecture-frame`
- Решение: approved
- Комментарий: модель интеграции с провайдерами входит в сквозной архитектурный каркас платформы.
