---
doc_id: PRD-CK8S-PROVIDER-HUB-0001
type: prd
title: kodex — требования домена рабочих сущностей провайдера
status: active
owner_role: PM
created_at: 2026-05-06
updated_at: 2026-05-27
related_issues: [281, 282, 711, 725, 761, 770, 840, 865]
related_prs: []
related_docsets:
  - docs/platform/product/requirements.md
  - docs/platform/product/constraints.md
  - docs/platform/architecture/domain_map.md
  - docs/platform/architecture/provider_integration_model.md
  - docs/platform/architecture/service_boundaries.md
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-05-06-provider-hub-boundaries"
  approved_by: "ai-da-stas"
  approved_at: 2026-05-06
---

# PRD: рабочие сущности провайдера

## TL;DR

- Что строим: домен `provider-hub` для webhook, зеркальных provider-native проекций, сверки, лимитов и операций провайдера.
- Для кого: владелец платформы, операторы, `agent-manager`, `project-catalog`, `package-hub`, `operations-hub`, будущий `integration-gateway` и platform MCP.
- Почему: пользовательский интерфейс, приёмка и быстрый agent-manager не должны ходить в GitHub/GitLab на каждый экран и не должны терять изменения при потере webhook.
- Минимум первой версии: GitHub как первый провайдер, входящий журнал webhook, проекции `Issue` и `PR/MR`, комментарии, связи, курсоры сверки, лимиты и журнал provider-операций.
- Критерии успеха: платформа видит актуальное состояние рабочих артефактов через локальные проекции, а провайдер остаётся источником истины.

## Проблема и цель

Проблема:

- рабочие артефакты живут в GitHub/GitLab, но платформе нужны быстрые списки, фильтры, связи, приёмка и уведомления;
- webhook может не прийти, прийти с задержкой или обработаться с ошибкой;
- постоянное чтение GitHub/GitLab на каждый экран упирается в лимиты и даёт плохой UX;
- slot-агенты могут работать через `gh`, а быстрый agent-manager должен выполнять платформенные операции через MCP и внутренние сервисы;
- внешние аккаунты и их политика принадлежат `access-manager`, но runtime-состояние авторизации и лимитов нужно видеть рядом с provider-операциями.

Цель:

- создать сервис-владелец нормализованного provider-native зеркала;
- разделить внешнюю истину провайдера и платформенную проекцию;
- обеспечить webhook + reconciliation как нормальный путь синхронизации;
- дать agent-manager, MCP и будущему UI безопасные операции провайдера с аудитом и учётом лимитов;
- оставить GitHub первой реализацией без блокировки GitLab.

## Пользователи и роли

| Роль | Главный сценарий |
|---|---|
| Владелец платформы | Видит, какие `Issue` и `PR/MR` связаны с работой, где нужна реакция и что рассинхронизировано. |
| Оператор | Диагностирует webhook, сверку, лимиты и ошибки операций провайдера. |
| `agent-manager` | Получает актуальное provider-native состояние и запускает разрешённые provider-операции через MCP. |
| Ролевой агент в slot | Работает через `gh` или API провайдера и передаёт ускоряющий сигнал об изменённом артефакте. |
| `project-catalog` | Связывает provider-native артефакты с проектом и репозиторием. |
| `package-hub` | Читает provider-репозитории пакетов и отслеживает PR в репозиториях пакетов. |
| `operations-hub` | Строит операторские проекции по рабочим артефактам, рассинхронизации и блокировкам. |

## Функциональные требования

| ID | Требование | Приоритет |
|---|---|---|
| PROV-FR-1 | Домен должен хранить входящий журнал webhook с дедупликацией по delivery id или аналогу провайдера. | Обязательно |
| PROV-FR-2 | Домен должен нормализовать события провайдера и обновлять локальные проекции асинхронно. | Обязательно |
| PROV-FR-3 | Домен должен хранить проекции `Issue`, `PR/MR`, комментариев, mentions, review-сигналов и provider relationships. | Обязательно |
| PROV-FR-4 | Домен должен хранить состояние разбора watermark, открытых разделов, типа задачи, меток, milestones, project fields, assignees и review state. | Обязательно |
| PROV-FR-5 | Домен должен хранить `sync_cursor`, окно перекрытия, приоритеты hot/warm/cold и drift status для incremental reconciliation. | Обязательно |
| PROV-FR-6 | Домен должен принимать ускоряющий сигнал от slot-агента по URL, provider id или `owner/repo/number`, с явно выбранным внешним аккаунтом для будущей сверки. | Обязательно |
| PROV-FR-7 | Домен должен хранить операционное состояние внешнего аккаунта у провайдера: авторизацию, лимиты, последние ошибки и временные блокировки. | Обязательно |
| PROV-FR-8 | Домен должен выполнять provider-операции только после разрешения от `access-manager`. | Обязательно |
| PROV-FR-9 | Домен должен вести журнал provider-операций: инициатор, аккаунт, цель, результат, ошибка и известные limit headers. | Обязательно |
| PROV-FR-10 | Домен должен публиковать `provider.*` события при изменении проекций, связей, статуса сверки, лимитов и результата операций. | Обязательно |
| PROV-FR-11 | Домен должен поддерживать GitHub как первую реализацию через provider adapter interface. | Обязательно |
| PROV-FR-12 | Домен должен оставлять GitLab и других провайдеров подключаемыми без изменения доменной модели. | Обязательно |
| PROV-FR-13 | Домен не должен становиться владельцем проектов, репозиториев как проектных сущностей, flow, ролей, slot, job, уведомлений или пакетного каталога. | Обязательно |
| PROV-FR-14 | Домен не должен реализовывать публичный HTTP webhook endpoint; входящий HTTP принадлежит `integration-gateway`. | Обязательно |
| PROV-FR-15 | Домен должен участвовать в сценариях bootstrap пустого репозитория и adoption существующего репозитория как контур provider-состояния, provider-операций, зеркала и provider-native артефактов; для bootstrap он может создать репозиторий у провайдера, затем принять уже подготовленные файлы и refs, для adoption он может снять lightweight provider-side snapshot существующего репозитория без чтения содержимого файлов, принять готовый набор файлов и refs, после merge фиксировать safe merge signal, а содержательное сканирование, проверку `services.yaml` и импорт проектной политики выполняют соседние контуры. | Обязательно |
| PROV-FR-16 | Домен должен принимать операции записи от `agent-manager` и platform MCP как типизированные инструменты, но внутри проводить их через общий конвейер команд с идемпотентностью, проверкой внешнего аккаунта, контекстом политики по риску и ссылкой на approval/gate, если политика требует подтверждение. | Обязательно |

## Критерии приёмки

| ID | Критерий |
|---|---|
| PROV-AC-1 | Если webhook пришёл дважды, входящий журнал не создаёт вторую бизнес-обработку. |
| PROV-AC-2 | Если webhook потерян, incremental reconciliation находит изменение и обновляет проекцию без ручного действия пользователя. |
| PROV-AC-3 | Если slot-агент создал `PR` через `gh`, ускоряющий сигнал приводит к приоритетной сверке этого артефакта. |
| PROV-AC-4 | Если внешний аккаунт потерял авторизацию или подошёл к лимиту, это видно как runtime-состояние provider account. |
| PROV-AC-5 | Если agent-manager создаёт комментарий или задачу через платформу, операция проходит через проверку права, журналируется и отражается в проекции. |
| PROV-AC-6 | Если репозиторий пустой, `provider-hub` выполняет provider write только после решения о controlled direct bootstrap и фиксирует созданные provider-native артефакты в зеркале. |
| PROV-AC-7 | Если репозиторий уже содержит код, `provider-hub` может зафиксировать lightweight provider-side scan snapshot с safe refs, маркерами, digest и bounded warnings без raw file contents; глубокое сканирование, отчёт и проектное решение выполняет агентная или проектная роль через workspace, а `provider-hub` создаёт или обновляет reviewable PR и связанные provider-native артефакты только по результату этого решения. |
| PROV-AC-8 | Если операция записи требует approval/gate по политике риска, `provider-hub` принимает только команду со ссылкой на принятое решение и фиксирует эту ссылку в журнале операций, не становясь владельцем approval-сервиса. |
| PROV-AC-9 | Если bootstrap/adoption PR принят через merge у провайдера, `provider-hub` фиксирует идемпотентный безопасный сигнал с refs/digest/timestamps и публикует `provider.repository.*_merged`, не храня raw payload, provider response или содержимое файлов. |

## Что не входит

- Не хранить проектную политику, `services.yaml`, правила веток и релизную политику как истину домена.
- Не вычислять права доступа и не владеть внешними аккаунтами как субъектами политики.
- Не запускать агентов, слоты, сборку, deploy или cleanup.
- Не доставлять уведомления и не владеть Human gate.
- Не реализовывать публичный HTTP gateway.
- Не копировать полный diff, полную историю review и полные сырые payload без retention.

## Нефункциональные требования

| ID | Категория | Требование |
|---|---|---|
| PROV-NFR-1 | Надёжность | Webhook и reconciliation должны быть идемпотентными и восстанавливаемыми после повторов. |
| PROV-NFR-2 | Производительность | UI и acceptance machine читают локальные проекции, а не провайдера на каждый запрос. |
| PROV-NFR-3 | Лимиты | Сверка должна учитывать лимитный бюджет и отдавать приоритет горячим артефактам. |
| PROV-NFR-4 | Безопасность | Сырые секреты не хранятся в БД `provider-hub`; доступ к ним идёт через общий secret resolver только по разрешённой ссылке после проверки в `access-manager`, а значение живёт в памяти процесса на время операции. |
| PROV-NFR-5 | Наблюдаемость | Webhook, операции, сверка, drift status и limit state должны иметь метрики, логи и трассировку. |
| PROV-NFR-6 | Расширяемость | GitHub-specific поля не должны попадать в доменную модель без нормализованного резервного варианта. |

## Зависимости

| Зависимость | Зачем нужна |
|---|---|
| `access-manager` | Разрешение использования внешнего аккаунта, действия доступа и ссылки на секреты. |
| `project-catalog` | Проектные идентификаторы, repository binding и политика `services.yaml`. |
| `agent-manager` | Запросы provider-операций, приёмка и ускоряющие сигналы после работы агента. |
| `package-hub` | Репозитории-источники пакетов и PR в пакетных репозиториях. |
| `integration-gateway` | Публичный приём webhook и проверка подписи на границе. |
| `operations-hub` | Операторские проекции, ленты и диагностика. |

## Апрув

- request_id: `owner-2026-05-06-provider-hub-boundaries`
- Решение: approved
- Комментарий: требования домена рабочих сущностей провайдера согласованы как целевое состояние.
