---
doc_id: REF-CK8S-0010
type: service-boundaries
title: "kodex — границы сервисов и владение во второй волне"
status: active
owner_role: SA
created_at: 2026-04-21
updated_at: 2026-05-05
related_issues: [281, 282, 309, 376, 470, 488]
related_prs: []
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-21-refactoring-wave2"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-21
---

# Границы сервисов и владение во второй волне

## TL;DR
- Эта волна не описывает физическое extraction-by-extraction перемещение файлов. Она фиксирует, кто чем владеет в целевой системе.
- Только сервис-владелец определяет каноническое состояние своего домена.
- Межсервисное чтение канонических данных идёт через контракты сервиса-владельца, а не через SQL к чужой БД.
- `worker` и `agent-runner` не получают собственного бизнесового владения.
- Любой следующий кодовый PR должен ссылаться на этот документ и явно показывать, какое владение он приближает.

## 1. Общие правила границ

### 1.1. Один сервис — один доменный центр
Если два сервиса одинаково "немного владеют" одними и теми же данными, граница определена плохо.

### 1.2. Сервис-владелец владеет и правилами, и состоянием
Нельзя оставить бизнес-правила в одном месте, а каноническое состояние в другом.

### 1.3. Фоновые исполнители не подменяют владельца
`worker` и `agent-runner` не принимают окончательных бизнесовых решений о статусах, переходах и владении.
Они также не ходят напрямую в чужие БД и работают с доменным состоянием только через сервисы-владельцы.

### 1.4. Проекция чтения не равна источнику истины
Проекционные данные для UI, timeline и операторских экранов не становятся первичным доменным состоянием.

## 2. Сервисы-владельцы и их зоны ответственности

### 2.1. `access-manager`
Владеет:
- пользователями платформы;
- организациями;
- группами;
- логином и principal resolution;
- allowlist;
- memberships;
- inheritance и override правилами доступа;
- системными настройками;
- административным аудитом.

Не владеет:
- проектами и репозиториями;
- provider state;
- run/session/job lifecycle;
- интерфейсными проекциями.

### 2.2. `project-catalog`
Владеет:
- проектами;
- репозиториями;
- project/repository config;
- `services.yaml` ссылками и policy;
- project rules и метаинформацией первичной настройки;
- источниками проектной документации и проверенным составом workspace;
- branch rules;
- release policy проекта и репозитория;
- привязками guidance packages и placement policy.

Не владеет:
- provider webhook events;
- статусами run;
- профилями ролей и логикой исполнения шаблонов промптов;
- slot lifecycle;
- approvals и уведомлениями.

### 2.3. `provider-hub`
Владеет:
- provider accounts и их операционным состоянием;
- webhook inbox, normalized provider events, дедупликацией и повторами обработки;
- зеркальными проекциями, состоянием дозаполнения и платформенными метаданными по `Issue/PR/MR/comments/mentions/relationships`;
- `sync_cursor`, incremental reconciliation, `drift_status` и приоритетами синхронизации;
- лимитами провайдера и provider constraints;
- выполнением операций в GitHub/GitLab через интерфейсы провайдера.

Не владеет:
- продуктовой логикой flow;
- выбором роли агента;
- slot/build/deploy jobs;
- операторскими проекциями как источником истины.

Обязательное правило:
- webhook является быстрым путём, но не единственной гарантией актуальности;
- потерянные webhook восстанавливаются через incremental reconciliation;
- ручной refresh не является штатным пользовательским сценарием и допустим только как админская постановка reconciliation job в очередь.

### 2.4. `package-hub`
Владеет:
- каталогом пакетов;
- записями пакетов и их версиями;
- метаданными плагинов и пакетов руководящей документации;
- статусом верификации;
- состоянием установки и импорта пакетов;
- схемами секретов пакетов;
- ценовыми данными пакетов и метаданными каталога.

Не владеет:
- первичным состоянием исходных репозиториев у провайдера;
- жизненным циклом уже установленных slot и job;
- membership-моделью и графом доступа пользователей.

### 2.5. `agent-manager`
Владеет:
- жизненным циклом run;
- агентными сессиями;
- логикой выполнения flow;
- каноническими flow, профилями ролей и шаблонами промптов в БД;
- правилами автоматизации;
- привязками триггеров;
- состоянием выполнения релизной линии;
- каталогом встроенных и пользовательских ролей;
- политикой исполнения профилей ролей;
- ссылками на версии `work`/`revise` шаблонов;
- acceptance machine;
- handover и follow-up решениями;
- wait states, связанные с выполнением agent work.

Не владеет:
- деталями provider API и provider mirror state;
- слотом и build/deploy orchestration;
- отправкой уведомлений как отдельным доменным процессом;
- административными данными пользователей.

### 2.6. `fleet-manager`
Владеет:
- реестром серверов, нод и Kubernetes-кластеров;
- инфраструктурными контурами подключения и проверки здоровья;
- политикой размещения;
- привязками организаций, проектов, репозиториев и runtime-контуров к серверным и кластерным контурам.

Не владеет:
- жизненным циклом run;
- статусом build/deploy job как канонической runtime-истиной;
- нативным состоянием у провайдера;
- UI-проекциями как первичным контуром.

### 2.7. `runtime-manager`
Владеет:
- slot lifecycle;
- build/deploy/mirror/cleanup jobs;
- reuse/prewarm политиками;
- техническим статусом runtime-сред;
- retention и housekeeping policy для среды;
- исполнением runtime на уже выбранном fleet scope.

Не владеет:
- продуктовым смыслом задачи;
- нативным provider state;
- approvals и ответами пользователя;
- операторской проекцией за пределами собственного канонического статуса.

### 2.8. `billing-hub`
Владеет:
- биллинговыми аккаунтами;
- записями затрат;
- распределением потребления;
- основой для выставления счетов;
- ценовыми правилами и правилами распределения выручки для пакетов и SaaS-контуров.

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

### 2.9. `interaction-hub`
Владеет:
- approvals;
- notifications;
- subscriptions;
- delivery attempts;
- события обратных вызовов;
- внешними каналами обратной связи.

Не владеет:
- бизнес-логикой flow;
- каноническими статусами run/job чужих доменов;
- проектами и репозиториями.

### 2.10. `operations-hub`
Владеет:
- read-моделями для UI;
- timeline и агрегированными состояниями;
- операторскими представлениями очередей, ошибок и блокировок;
- query-oriented проекциями по run/job/task.

Не владеет:
- первичными данными пользователя;
- первичными данными проекта;
- provider truth;
- каноническими статусами исполнения.

## 3. Edge и исполнительные компоненты

### Gateway-сервисы
Общий `api-gateway` не создаётся. Входящие HTTP-поверхности разделяются по назначению:
- `staff-gateway` — сценарии сотрудников и администраторов для `web-console`;
- `integration-gateway` — webhook, обратные вызовы и внешние события от провайдеров и интеграций;
- `user-gateway` — сценарии внешних пользователей на границе MVP или после MVP.

Gateway-сервисы отвечают только за:
- приём входящего HTTP-трафика;
- проверку webhook;
- аутентификацию и авторизацию на границе;
- ограничение частоты запросов на границе;
- маршрутизацию.

Нельзя оставлять в них:
- доменные правила;
- SQL к доменным БД;
- собственные проекции бизнесовых состояний.

Порядок реализации определяется потребителем входящего контракта: `staff-gateway` появляется рядом с `web-console`, `integration-gateway` — после базового `provider-hub`, `user-gateway` — только после подтверждения внешних пользовательских сценариев.

### `platform-mcp-server`
Отвечает только за:
- MCP-поверхность платформенных инструментов;
- аутентификацию и авторизацию MCP-клиентов;
- аудит и policy-проверки вызовов;
- маршрутизацию вызовов к сервисам-владельцам;
- запуск approval и feedback-контуров, если это требуется контрактом инструмента.

Нельзя оставлять в нём:
- доменное владение данными;
- SQL к доменным БД;
- собственные канонические статусы run, `job`, проектов или provider state.

### `web-console`
Отвечает только за UI и client-side state.

Нельзя переносить во frontend:
- принятие доменных решений;
- расчёт канонических переходов;
- скрытую workflow-логику, которая должна жить в сервисах-владельцах.

### `worker`
Исполняет фоновые задачи и reconciliations по поручению сервисов-владельцев.

Ему запрещено:
- самостоятельно переопределять владение;
- вводить скрытые статусы вне сервисов-владельцев;
- читать и изменять доменные таблицы чужих owner-контуров напрямую;
- хранить свою "временную правду", которая потом важнее доменной.

### `agent-runner`
Исполняет агентную работу и взаимодействует с runtime/MCP/provider-инструментами.

Ему запрещено:
- быть владельцем run lifecycle;
- принимать финальные решения о переходах без сервиса-владельца;
- читать и изменять доменные таблицы чужих owner-контуров напрямую;
- держать единственную копию важного состояния только внутри session snapshot.

При запуске агент может получить несколько локальных копий источников: кодовые репозитории, проектную документацию и пакеты руководящей документации. Это не даёт `agent-runner` доменного владения этими источниками: он только исполняет задачу в рамках policy и возвращает результат через provider-native `PR/MR` и сервисы-владельцы. Flow и шаблоны промптов приходят агенту как отрендеренный платформой контекст из БД.

## 4. Межсервисное взаимодействие

### Синхронные запросы
Используются для:
- command;
- authoritative read;
- access check;
- точечных служебных выборок.

### Асинхронные события
Используются для:
- построения read-моделей;
- реакции на завершение длительных операций;
- fan-out на несколько доменов;
- построения операторских проекций.

Правило:
- событие не делает подписчика владельцем истины;
- если нужен authoritative ответ, сервис идёт к сервису-владельцу.

Отдельное правило для MCP-контуров:
- `platform-mcp-server` не заменяет прямые межсервисные контракты;
- он даёт инструментальную поверхность для agent-manager и slot-агентов;
- сервисы-владельцы всё равно остаются единственными владельцами данных и бизнес-решений.

## 5. Что запрещено
- SQL к чужой БД;
- cross-database join как часть прикладной логики;
- хранение provider semantics одновременно в `provider-hub` и `agent-manager`;
- хранение run lifecycle одновременно в `agent-manager` и `operations-hub`;
- хранение platform jobs одновременно в `runtime-manager` и `worker`;
- превращение любого gateway-сервиса в новый доменный центр;
- превращение старого `control-plane` в вечный transitional service.

## 6. Порядок extraction-мышления
Следующие кодовые PR должны мыслиться так:
1. сначала определяем owner;
2. затем выделяем его канонический контур;
3. затем переносим use-cases;
4. затем уводим потребителей с legacy-кода;
5. затем удаляем старую ветку логики.

Нельзя делать extraction только транспорта или только README без переноса владения.
