---
doc_id: REF-CK8S-0020
type: platform-foundation
title: "kodex — расширение платформенного основания в wave 5.1"
status: active
owner_role: SA
created_at: 2026-04-23
updated_at: 2026-04-23
related_issues: [281, 282, 309, 470, 488, 586]
related_prs: []
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-23-refactoring-wave5-1"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-23
---

# Расширение платформенного основания в wave 5.1

## TL;DR
- Это расширение добавляет в канонику платформы шесть обязательных доменных направлений до старта runtime/deploy волны: пакетную платформу, многоорганизационную модель доступа, контур серверов и кластеров, учёт затрат, релизную политику и правила автоматизации.
- Новая модель проектируется сразу на enterprise-уровень, но для каждого направления фиксируется отдельный минимальный объём первой версии, чтобы волны реализации не расползлись.
- Плагины и руководящие пакеты документации рассматриваются как разные виды одного пакетного контракта: первые исполняются в Kubernetes, вторые импортируются в локальный рабочий контур агентов.
- Flow, профили ролей и шаблоны промптов рассматриваются как платформенная конфигурация: канонически они живут в БД, а репозиторий платформы хранит установочные фикстуры для первичной загрузки.
- Проектная документация хранится в репозиториях проекта, описывается в `services.yaml` и загружается агенту в workspace вместе с кодом и руководящими пакетами.
- Один сервер и один кластер остаются стартовой операционной конфигурацией, но документация и кодовая архитектура больше не должны предполагать, что такая топология единственно возможна.
- С этого момента wave 6 и последующие волны реализации обязаны учитывать tenancy, каталоги пакетов, учёт затрат, релизные линии и автоматизацию по триггерам как обязательные точки расширения, а не как расширения когда-нибудь потом.

## 1. Почему понадобилась отдельная wave 5.1
После завершения wave 5 стало понятно, что часть будущих требований относится не к конкретному экрану и не к runtime-деталям, а к самому основанию платформы:
- кто считается субъектом платформы и как делятся права;
- что такое расширение платформы и как оно подключается;
- как платформа работает не только для owner-организации, но и для клиентов, исполнителей и SaaS-арендаторов;
- как учитывать затраты и коммерческий контур;
- как планировать release trains и не терять правила автоматизации;
- как разнести руководящую документацию по репозиториям-источникам, не ломая локальную работу агентов.
- как отделить runtime-истину flow, ролей и шаблонов промптов от установочных фикстур в репозитории платформы;
- как описать проектную документацию для проектов с несколькими репозиториями.

Если не заложить эти заделы сейчас, wave 6 и первые волны реализации зацементируют слишком узкую односерверную и одноорганизационную модель.

## 2. Новые обязательные направления wave 5.1

### 2.1. Пакетная платформа
Платформа должна поддерживать единый пакетный контракт с несколькими видами пакетов:
- `plugin package` — исполняемое расширение платформы;
- `guidance package` — пакет руководящей документации и правил для агентов;
- в будущем допускаются и другие виды пакетов, если они подчиняются тому же общему контракту.

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

### 2.2. Многоорганизационная модель доступа
Платформа должна поддерживать:
- owner-организацию;
- клиентские организации;
- организации внешних исполнителей;
- будущую SaaS-модель с изоляцией по организациям.

Пользователь:
- может состоять в нескольких организациях;
- может состоять в нескольких группах;
- может получать права напрямую и через граф членства.

### 2.3. Контур серверов и кластеров
Runtime-платформа больше не считается привязанной навсегда к одному серверу и одному кластеру.

Нужно сразу заложить:
- каталог серверов;
- каталог Kubernetes-кластеров;
- правила привязки организации, проекта, репозитория или workload к конкретному серверному или кластерному контуру;
- задел на multi-zone и delegated clusters.

### 2.4. Billing и cost accounting
Платформа должна уметь:
- учитывать свои расходы по compute, storage, runtime, использованию пакетов и внешним провайдерам;
- раскладывать их по организациям, проектам и при необходимости по репозиториям и release линиям;
- формировать основу для выставления счетов;
- в будущем поддержать рублёвый и валютный контур оплаты.

### 2.5. Release policy и release trains
Платформа должна различать:
- provider-native ветки и теги;
- platform-owned release policy;
- релизную линию или release train, которой владеет платформа;
- rollout policy: прямой релиз, staged rollout, canary, rollback, hold, recovery.

### 2.6. Automation rules
Flow больше не может считаться только вручную запускаемым.

Нужны:
- расписания;
- привязки триггеров;
- входящие автоматические сигналы;
- правила, создающие `Issue` или запускающие flow по cron и событиям.

### 2.7. Доменные события между сервисами
Доменное событие — обязательный способ сообщить другим сервисам о зафиксированном изменении в owner-сервисе.

Нужно поддержать:
- отсутствие `FOREIGN KEY`, cross-database join и каскадных операций между таблицами разных owner-сервисов;
- публикацию событий через outbox после фиксации изменения в БД owner-сервиса;
- идемпотентную обработку через inbox/checkpoint у потребителей;
- версионирование схем событий;
- replay и диагностику зависших обработок;
- запрет на использование доменного события как удалённой команды с навязанным действием.

Пример: удаление организации не должно каскадно удалять данные, принадлежащие другим сервисам. `access-manager` публикует событие, а каждый домен сам применяет свою политику.

### 2.8. Flow, роли и шаблоны промптов
Flow, профили ролей и шаблоны промптов не должны читаться из репозитория при каждом запуске агента.

Нужно поддержать:
- каноническое хранение в БД;
- версии, digest, область применения и аудит изменений;
- UI-редактирование с policy-проверкой и откатом;
- установочные фикстуры в репозитории платформы для встроенных flow, ролей и шаблонов;
- будущий self-improve через отдельный согласуемый контур публикации новой версии.

Это позволяет разным организациям и командам иметь свои flow и роли без runtime-зависимости от структуры репозиториев.

### 2.9. Проектная документация в проектах с несколькими репозиториями
Проектная документация отличается от руководящих пакетов документации.

Нужно поддержать:
- общую продуктовую документацию проекта;
- документацию конкретных сервисов;
- документацию зависимых сервисов;
- документацию, доступную только для чтения;
- документацию, которую агент может менять в рамках задачи;
- загрузку этих источников в workspace по правилам `services.yaml`.

Если задача меняет несколько репозиториев, результатом становится связанный набор `PR/MR`, а не один обязательный `PR/MR`.

## 3. Канонический пакетный подход

### 3.1. Единый каталог пакетов
Вместо отдельного каталога плагинов и отдельного каталога руководящей документации платформа проектируется вокруг единого каталога пакетов.

Каждая запись каталога описывает:
- `package kind`;
- источник пакета: встроенный, каталог платформы, внешний каталог, пользовательский источник;
- repository provider и ссылку на репозиторий;
- версию;
- статус верификации;
- коммерческий статус;
- локализацию названий и описаний;
- право установки и область применения.

Каталог разделяется на два пользовательских представления:
- установленные пакеты — локальное состояние конкретной установки платформы;
- доступные пакеты — данные, полученные через клиентские подключения к одному или нескольким магазинам пакетов.

Магазин пакетов сам является устанавливаемым пакетом, а не жёстко встроенной частью ядра. Авторский магазин `kodex` должен поставляться из приватного репозитория как пакет, который мы устанавливаем в собственную платформу. Другие установки могут использовать этот магазин, свой магазин или только пользовательские источники пакетов.

Отдельный пакет должен поставлять публичный сайт платформы и пользовательскую документацию платформы из отдельного репозитория: API, разработка пакетов, добавление пакетов в магазин и каталог. Такой пакет не должен смешиваться с руководящей документацией для агентов и не должен становиться обязательной частью ядра.

### 3.2. `Plugin package`
`Plugin package` — это пакет, который:
- имеет package manifest в корне репозитория;
- описывает требуемые platform APIs, MCP surface, permissions и runtime-потребности;
- описывает обязательные и желательные secret inputs с локализованными названиями и описаниями;
- поставляет Dockerfile, Kubernetes manifests и другие runtime-зависимости;
- может быть реализован на любом языке и на любом стеке, если соблюдает пакетный контракт платформы.

### 3.3. `Guidance package`
`Guidance package` — это пакет, который:
- живёт в репозитории-источнике;
- поставляет руководящую документацию, шаблоны и правила;
- импортируется в локальный рабочий контур проекта, репозитория, сервиса или самой платформы;
- не требует vector storage и не заменяет локальное чтение файлов агентом;
- допускает self-improve задачи, которые запускаются против самого guidance-repository.

### 3.4. Почему не две разные системы
Разделение на два отдельных каталога дало бы ложное удвоение сущностей:
- два формата метаданных источника;
- две модели версий и верификации;
- две системы лицензий и платности;
- две несовместимые истории установки и импорта.

Это расширение фиксирует общий пакетный слой с разными runtime-путями для разных видов пакетов.

## 4. Минимальный объём первой версии и enterprise target

| Направление | Минимальный объём первой версии | Enterprise target |
|---|---|---|
| Пакетная платформа | встроенные пакеты, пользовательские источники пакетов, локальная установка плагина и пакета руководящей документации, каталог установленных пакетов, клиентское подключение к пакету магазина доступных пакетов без открытого биллинга каталога | публичный каталог пакетов через пакет магазина, платные и бесплатные пакеты, профили издателей, верифицированные версии, распределение выручки |
| Организации и группы | owner-организация, клиентские организации, глобальные и организационные группы, базовая иерархия прав | SaaS-модель с изоляцией по организациям, delegated administration, сложные правила наследования и исключений |
| Контур серверов и кластеров | один сервер и один кластер в production, но с явным слоем реестра и политикой размещения | несколько серверов, несколько кластеров, мультизональное размещение, выделенный кластер на организацию или проект |
| Учёт затрат | сбор записей затрат и распределение по проектам и организациям, ручное формирование сводки для биллинга | счета, поставщики платежей, комиссии, тарификация пакетов и SaaS |
| Релизная политика | правила релизных веток, релизная линия, политики canary и staged rollout на уровне модели | полные программы релизов, релизные линии для нескольких контуров, политики выкладки с учётом организаций |
| Правила автоматизации | cron и минимальный набор триггеров событий, включая создание задач по alert | гибкие шины событий, сложные цепочки триггеров, межорганизационные шаблоны автоматизации |
| Доменные события | outbox/inbox для событий owner-сервисов, идемпотентная обработка и базовые проекции чтения | управляемый replay, версионирование схем, расширенная диагностика подписчиков и межорганизационные политики событий |
| Пакеты руководящей документации | импорт из отдельных репозиториев в локальный контур и использование агентом по локальным файлам | каталог пакетов руководящей документации, пакеты правил, управляемые обновления и платный контент |
| Flow, роли и шаблоны промптов | БД как источник истины, UI-редактирование, версии, аудит, установочные фикстуры в репозитории платформы | self-improve через согласуемые версии, delegated administration и расширенная политика областей применения |
| Проектная документация | источники документации в `services.yaml`, загрузка в workspace, связанный набор `PR/MR` | политики доступа и согласованные изменения в нескольких репозиториях |

## 5. Что это меняет для уже принятых волн

### Wave 0
Нужно закрепить:
- каталог пакетов как постоянный домен программы;
- правила ведения документации для репозиториев-источников руководящей документации;
- правила ведения установочных фикстур flow, ролей и шаблонов промптов;
- правила проектной документации для проектов с несколькими репозиториями;
- последовательность, где enterprise target описывается сразу, а минимальные объёмы первой версии делаются поэтапно.

### Wave 1
Нужно добавить в продуктовую модель:
- записи каталога пакетов;
- пакеты-плагины;
- пакеты руководящей документации;
- организации, группы и граф участия пользователей;
- реестр серверов и кластеров;
- биллинговые аккаунты и записи затрат;
- релизную политику и релизную линию;
- правила расписания и привязки триггеров;
- flow, роли и шаблоны промптов в БД;
- источники проектной документации и проверенный состав workspace.

### Wave 2
Нужно добавить архитектурные заделы:
- `package-hub`;
- `fleet-manager`;
- `billing-hub`;
- расширение `access-manager` до tenancy-aware модели;
- расширение `project-catalog` до политики веток, релизов и привязки пакетов;
- расширение `project-catalog` до проверки источников проектной документации и подготовки состава workspace.

### Wave 3
Нужно закрепить:
- owner-сервисы для метаданных пакетов, состояния установки и импорта и схем секретов;
- владение данными для объектов организаций, групп, инфраструктурного контура, биллинга и автоматизации;
- provider-модель для репозиториев-источников пакетов, платёжных провайдеров и семантики веток;
- provider-модель для репозиториев проектной документации и связанного набора `PR/MR` по одной задаче.

### Wave 4
Нужно закрепить:
- модель риска для плагинов, платных пакетов, релизных линий и автоматизации без участия человека;
- политику Human gate для branch rules, релизной политики и high-risk триггеров;
- безопасный контур автоматического запуска flow и фоновой автоматизации.

### Wave 5
Нужно расширить UX-модель и сделать это отдельными итерациями внутри того же PR:
- каталоги пакетов и установка пакетов;
- управление организациями и группами;
- экраны контура серверов и кластеров;
- экраны затрат и использования ресурсов;
- экраны релизной политики и правил автоматизации;
- поверхности версионирования flow, ролей и шаблонов в БД;
- поверхности просмотра источников проектной документации в `services.yaml` и состава workspace задачи.

## 6. Что не должно потеряться дальше
После wave 5.1 любая следующая реализация обязана считать обязательными следующие заделы:
1. каталог пакетов и верификация пакетов;
2. группы пользователей и организации;
3. реестр серверов и кластеров и политика размещения;
4. billing и cost allocation;
5. release line, release policy и branch rules;
6. правила расписания и привязки триггеров;
7. пакеты руководящей документации как отдельный слой, управляемый репозиториями;
8. flow, роли и шаблоны промптов в БД и установочные фикстуры в репозитории платформы;
9. источники проектной документации в `services.yaml` и загрузка источников в workspace.

Если какой-то из этих заделов временно не реализуется в коде, он всё равно должен сохраняться:
- в канонической документации;
- в naming и data ownership;
- в API/DB design без блокирующих тупиков;
- в UI information architecture как минимум на уровне допустимых экранов и разделов.
