---
doc_id: CST-CK8S-PLATFORM-0001
type: constraints
title: kodex — ограничения платформы
status: active
owner_role: PM
created_at: 2026-04-26
updated_at: 2026-04-26
related_issues: [599, 600, 601, 602]
related_prs: []
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-26-platform-product-frame"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-26
---

# Constraints: kodex

## TL;DR

Платформа переписывается с нуля, поддерживает только Kubernetes, не заменяет GitHub/GitLab как рабочий провайдер, не хранит полные технические логи в PostgreSQL и не создаёт конкурирующие внутренние рабочие сущности вместо `Issue`, `PR/MR`, веток, тегов, образов или файловой документации.

## Неизменяемые продуктовые решения

| Ограничение | Следствие |
|---|---|
| Legacy control-plane не поддерживается как продуктовый слой | Старый код и старые документы не дорабатываются, а остаются в `deprecated/**` только как справка; активные миграции, контракты, env/secrets/config и deploy path меняются через live-safe sequence. |
| Новая реализация пишется с нуля | Кодовые реализации создают новые сервисы и каталоги целевой архитектуры. |
| Инициатива является `Issue` | В БД платформы не создаётся отдельная рабочая сущность `Initiative`, но платформа хранит зеркальную проекцию и собственные метаданные, привязанные к нативному `Issue` провайдера. |
| Provider-first модель обязательна | `Issue`, `PR/MR`, комментарии, ветки, теги, review и связи остаются у GitHub/GitLab. |
| Agent-manager является главным входом | UI, голос и внешние каналы ведут пользователя через быстрый agent-manager и платформенный MCP. |
| `flow`, роли и шаблоны живут в БД | Репозиторий содержит только установочные фикстуры, а не runtime-источник истины. |

## Технические ограничения

| Область | Ограничение |
|---|---|
| Runtime | Поддерживается только Kubernetes. |
| Slot | Первая версия использует namespace как базовый контур изоляции slot. |
| Данные сервисов | У каждого owner-сервиса своя БД или своя схема владения без `FOREIGN KEY` и join между БД разных owner-сервисов. |
| Доменные события | Межсервисная синхронизация идёт через доменные события, outbox/inbox и идемпотентную обработку. |
| Секреты платформы | Vault является каноническим хранилищем секретов платформы и её зависимостей; проекты могут использовать свои хранилища секретов. |
| Логи `job` | В PostgreSQL хранится статус, причина ошибки, ссылки и короткий хвост лога, а не полный поток логов. |
| Медиа-вложения | Бинарные голосовые и графические вложения не кладутся в PostgreSQL как каноническое содержимое. |

## Ограничения по рабочим артефактам

- Slot-агент создаёт и обновляет `Issue`, `PR/MR`, комментарии, labels, relationships, assignees, milestone и project fields через `gh` или нативный API провайдера.
- Быстрый agent-manager работает с платформой через платформенный MCP-сервер и может инициировать provider-операции через `provider-hub`.
- Обязательные платформенные признаки в `Issue`, `PR/MR` и структурированных комментариях оформляются через открытые разделы и watermark.
- Acceptance machine не должна молча исправлять артефакты за агента: при недостающих полях она возвращает конкретное замечание в сессию.
- Один `Issue` может иметь несколько связанных `PR/MR` в разных репозиториях; платформа хранит связи и ожидания приёмки, но не создаёт внутренний заменитель такого набора.

## Зеркальные проекции нативных сущностей

Provider-native подход не означает, что UI и фоновые процессы читают GitHub/GitLab на каждый запрос.

Платформа должна хранить в своих БД:
- устойчивые идентификаторы провайдера: тип провайдера, владелец, репозиторий, номер, `node_id` или аналог, URL и текущую версию синхронизации;
- лёгкую зеркальную проекцию `Issue`, `PR/MR`, комментариев, связей, labels, assignees, milestone и project fields, достаточную для списков, поиска, фильтров, уведомлений, приёмки и всех клиентских экранов, кроме полного тела задачи, полного тела `PR/MR` и diff;
- распарсенный watermark, открытые инструкции, обязательные разделы, digest тела и состояние рассинхронизации;
- платформенные метаданные, которых нет или не должно быть у провайдера: состояние приёмки, риск, policy decisions, связи с `run`, `job`, slot, агентной сессией, уведомлениями и операторскими списками.

Ограничения:
- источник истины по рабочему артефакту остаётся у провайдера;
- зеркальная проекция не становится внутренней задачей и не получает собственный независимый жизненный цикл;
- если артефакт изменился у провайдера, webhook и reconciliation обновляют проекцию;
- если пользователь создал `Issue` или `PR/MR` напрямую у провайдера, платформа связывает его с проектом и репозиторием, проверяет тип, watermark и обязательные поля, а agent-manager дозаполняет артефакт или запрашивает решение человека согласно policy;
- лимиты провайдера учитываются как штатное ограничение: UI и acceptance используют локальную проекцию, а API провайдера вызывается для операций, проверки рассинхронизации и восстановления.

## Синхронизация с провайдером

Зеркальные проекции синхронизируются не ручной кнопкой пользователя и не постоянным чтением провайдера из UI.

Обязательная модель:
- webhook является основным быстрым входом: платформа сначала сохраняет сырое событие в `provider_event_inbox`, дедуплицирует его по идентификатору доставки или аналогу и только затем асинхронно пересчитывает проекцию;
- если агент или agent-manager создал или изменил `Issue`, `PR/MR` или комментарий через `gh` или API провайдера, он должен передать платформе идентификатор артефакта как ускоряющий сигнал на обновление, но этот сигнал не заменяет webhook и reconciliation;
- incremental reconciliation является обязательной страховкой от потерянных webhook: для каждой области синхронизации провайдера хранится `sync_cursor`, `last_success_at`, `last_checked_at`, `last_error`, `rate_budget_state` и окно перекрытия;
- reconciliation не обходит весь провайдер постоянно, а запрашивает изменённые сущности по cursor, `updated_at` или другому доступному provider-механизму с перекрытием окна, чтобы поймать задержанные события и пограничные изменения;
- горячие сущности синхронизируются чаще: активные flow, открытые `PR/MR`, Human gate, release line, running `run`, свежие комментарии и задачи с ожидаемой приёмкой;
- холодные сущности синхронизируются редко или только по расписанию: закрытые задачи, завершённые релизы и архивные проекции;
- каждая проекция хранит `source_updated_at`, `source_digest`, `last_verified_at`, `drift_status` и признак необходимости повторной проверки.

Если провайдер недоступен или лимиты близки к исчерпанию, платформа не ломает UI, а показывает состояние последней проверенной проекции, повышает `drift_status`, откладывает холодную синхронизацию и сохраняет лимиты для горячих рабочих контуров.

Ручная синхронизация допустима только как админская аварийная операция для постановки reconciliation `job` в очередь. Она не должна быть обязательным действием пользователя в нормальном UX.

## Учёт лимитов при работе агентов через `gh`

Операции, которые проходят через `provider-hub`, учитываются платформой детерминированно. Slot-агент при прямой работе через `gh` остаётся разрешённым рабочим контуром, но его расход лимитов нельзя считать полностью видимым автоматически.

Правило первой версии:
- перед началом и после завершения agent-run платформа или агент снимает состояние лимитов через `gh api rate_limit` и сохраняет его в платформу;
- для высокообъёмных действий агент обязан отправлять промежуточные снимки лимитов через платформенный MCP;
- если агент использует `gh api`, он может передавать платформе заголовки лимитов, полученные через `gh api --include`;
- эти снимки являются приближённым учётом и помогают видеть риск исчерпания лимитов, но не заменяют детерминированный учёт provider-операций.

Целевое усиление после MVP: операции, где нужен строгий учёт лимитов, принудительное соблюдение лимитного бюджета или централизованная деградация, должны идти через provider proxy или MCP-ручки платформы, которые выполняют вызовы API провайдера от имени разрешённого аккаунта и записывают расход лимитов как часть операции.

## Ограничения по документации

- Активная новая документация живёт в `docs/**` и создаётся по `docs/templates/**`.
- `refactoring/**` остаётся программной каноникой, пока конкретный раздел явно не перенесён в `docs/**`.
- `deprecated/**` не используется как база новой реализации.
- Руководящая документация подключается как отдельные source submodule в `docs/external/**`.
- Шаблоны документации подключаются как source submodule `docs/templates`.
- Проектная документация проекта описывается в `services.yaml`, загружается в workspace агента и остаётся в репозиториях проекта.

## Ограничения по доступу и организациям

- Регистрация пользователей отключена.
- Вход идёт через платформенный SSO/OIDC-контур с матчингом по email, заранее разрешённым администратором.
- Базовый самостоятельно управляемый IdP для первой версии — Keycloak. GitHub, GitLab и другие системы подключаются как внешние поставщики идентичности, а не как прямой обязательный OAuth-контур платформы.
- Слоты и служебные поверхности не требуют отдельного OAuth-приложения у GitHub/GitLab на каждый slot: они защищаются через платформенный gateway/SSO session и внутреннюю матрицу прав.
- Модель доступа должна сразу учитывать организации, группы пользователей, внешние аккаунты, роли агентов и будущие SaaS-контуры.
- Пользователь может состоять в нескольких организациях и группах.
- Группы могут быть глобальными и организационными; более точные контуры допускаются позже, если не ломают наследование прав.

## Ограничения по пакетной платформе

- Пакет является репозиторием-источником с manifest и версионируемым контрактом.
- Плагины запускаются в Kubernetes-контуре установки платформы.
- Пакеты руководящей документации импортируются как локально доступные файлы для агента.
- Магазин доступных пакетов не встраивается в ядро, а поставляется отдельным пакетом из приватного репозитория.
- Платные пакеты не должны попадать в downstream-инсталляции без проверки прав.

## Операционные ограничения

- Runtime, build, deploy, cleanup и housekeeping видны как `job`.
- Реестр образов остаётся владельцем образов; платформа не дублирует каталог образов.
- Сбой регламентной `job` должен быть видим оператору и попадать в уведомления.
- Релиз не считается безопасно завершённым сразу после успешного deploy `job`: нужен postdeploy-контур и решение `continue`, `hold`, `rollback` или `follow_up_required`.

## Ограничения локализации

- Пользовательский интерфейс и документы пишутся в локали, выбранной пользователем, без хаотичной смеси языков.
- В русской локали английский оставляется для имён файлов, API, протоколов, env, model id, code identifiers и устойчивых технических терминов без точного русского аналога.

## Апрув

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