# План реализации

## 1. Назначение документа

Этот документ фиксирует актуальный порядок подготовки Crank к коммерческой реализации как open-core продукта.

Документ не повторяет уже выполненные исторические этапы. Он описывает только тот план, по которому проект должен двигаться дальше.

## 2. Базовый принцип

Работа делится на два контура:

1. завершение и hardening открытой редакции `Community`;
2. подготовка архитектурных, продуктовых и delivery-границ для `Enterprise` и `Cloud`.

Принцип:

- сначала нужно сделать честную и законченную `Community`-основу;
- затем нужно отделить commercial seams и private delivery;
- только после этого имеет смысл реализовывать коммерческие расширения.

## 3. Этап 1. Open-core product boundary

### Цель

Зафиксировать, что входит в `Community`, а что уходит в `Enterprise` и `Cloud`.

### DoD

- документы `product-editions`, `commercial-boundaries`, `architecture`, `module-decomposition` синхронизированы;
- в кодовой базе определена capability model по редакциям;
- UI и API не обещают Community-функции, которых там не должно быть;
- старые review-файлы не требуются как отдельный источник истины.
- canonical Community deployment manifest и env template вынесены в `deploy/community/*`;
- public CI/CD delivery path использует именно `deploy/community/*` как source of truth для Community поставки.
- `crank-runtime` уже имеет feature seams для premium protocol adapters, так что Community base можно собирать как `REST-only` runtime foundation.

## 4. Этап 2. Community machine access completion

### Цель

Довести базовую модель машинного доступа Community до полностью рабочего состояния.

### DoD

- у AI-агента есть собственный ключ;
- UI умеет выпускать, показывать, отзывать и удалять agent keys;
- `mcp-server` использует agent-scoped machine access;
- Community поддерживает только `security_level = standard`;
- в системе не остается product-facing assumptions про workspace-wide machine key как основной способ вызова.

## 5. Этап 3. Edition capability model

### Цель

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

### DoD

- существует server-side capability model:
  - protocols
  - auth modes
  - security levels
  - workspace/user limits
- `admin-api` возвращает capability flags для UI;
- UI скрывает или честно блокирует premium functionality;
- Community build не содержит ложных "почти доступных" product paths.

## 6. Этап 4. Private auth-service seam

### Цель

Подготовить публичный код к private реализации короткоживущих и одноразовых токенов.

### DoD

- зафиксированы контракты для:
  - `POST /mcp-auth/v1/token`
  - `POST /mcp-auth/v1/token/one-time`
- в `mcp-server` существует abstraction для проверки токенов;
- `admin-api` и `mcp-interface` знают про эти контракты документированно;
- Community при этом остается полностью работоспособной без private token service.

## 7. Этап 5. Commercial protocol split

### Цель

Перестать считать весь текущий protocol surface частью открытой редакции.

### DoD

- определен canonical Community protocol set;
- premium protocol families и premium execution modes вынесены в коммерческий план;
- UI capability-gated по протоколам;
- release model для Community не требует shipping premium flow как рабочей open-source функции.

## 8. Этап 6. Frontend launch readiness

### Цель

Довести UI до коммерчески пригодного состояния для `Community` и подготовить edition-aware product surface.

### DoD

- agent key UX доведен до продукта;
- mobile layouts для data-heavy страниц больше не ломают primary actions;
- terminology и localization согласованы;
- settings и workspace flows не содержат misleading или half-functional sections;
- UI понимает разницу между Community и premium capabilities.

## 9. Этап 7. Enterprise access and governance

### Цель

Реализовать коммерческий access/governance слой в private delivery.

### DoD

- есть `SSO`;
- есть `2FA`;
- есть расширенная `RBAC`;
- есть `audit log`;
- существует private delivery path для self-hosted customers.

## 10. Разделение репозиториев

### Цель

Вести развитие продукта уже в трех отдельных repositories без возврата к модели общего source of truth.

### Текущий статус

Разделение репозиториев уже выполнено:

- `crank-community` — public Community repository;
- `crank-enterprise` — private self-hosted commercial repository;
- `crank-cloud` — private hosted/control-plane repository.

### Следствие

Дальнейшая работа строится так:

1. общие open-core улучшения сначала оформляются в `crank-community`;
2. затем тот же change set переносится в `crank-enterprise`;
3. затем переносится в `crank-cloud`;
4. cleanup и ограничение Community выполняются только в `crank-community`.

### Результат

- `crank-community` остается source base для общей открытой логики;
- private repositories держат только свой delta и коммерческие расширения;
- старый общий репозиторий больше не рассматривается как главный источник изменений.

## 11. Этап 8. Cloud control plane

### Цель

Подготовить hosted-редакцию как отдельный продуктовый контур.

### DoD

- есть metering;
- есть billing integration;
- есть hosted tenant model;
- есть cloud deployment and support tooling;
- capability model синхронизирована с hosted plans.

## 12. Этап 9. Release and distribution hardening

### Цель

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

### DoD

- Community публикуется из `crank-community`;
- Enterprise поставляется через private container registry и private manifests;
- Cloud использует отдельный private operational contour;
- build provenance и подпись артефактов документированы;
- коммерческий код не требуется публиковать в public repository.

## 13. Этап 10. Optional cache and coordination layer

### Цель

Подготовить optional cache/coordination layer так, чтобы платформа могла использовать `Valkey/Redis`,
но не зависела от него для базового запуска, и при этом закрыть первые коммерчески ценные cache hot paths.

### DoD

- определены абстракции для cache/coordination state;
- Community может запускаться без внешнего cache store;
- Community deployment path умеет поднимать optional `Valkey`;
- Cloud использует shared cache layer как default managed runtime component;
- Enterprise может подключать свой `Valkey/Redis` на уровне single-node или cluster deployment.
- cache namespaces документированы так, чтобы:
  - platform / coordination state не смешивался с response cache;
  - response cache по умолчанию изолировался по `workspace + agent + operation + operation version + request fingerprint`;
  - внешний cache backend можно было безопасно шарить между несколькими рабочими областями и агентами.
- shared coordination cache уже применяется не только для rate limiting, но и для multi-instance snapshots published MCP catalogs.
- response cache уже покрывает:
  - `REST GET` как Community baseline;
  - `GraphQL query` как первый коммерчески ценный read-only protocol path.
  - `gRPC unary` для явно read-only операций через `GrpcTarget.read_only`.
- дальнейшее расширение response cache идет только по отдельно обоснованным read-only сценариям, а не как общий cache для всех протоколов подряд.

## 14. Этап 11. Live staging and demo readiness

### Цель

Поддерживать реальный стенд и демонстрационный сценарий в состоянии, пригодном для продажи и демонстрации.

### DoD

- live authenticated staging pass воспроизводим;
- deploy smoke и operator docs совпадают с реальной поставкой;
- demo user flow подтвержден на реальном окружении;
- регрессии в publish/call/auth flow ловятся до релиза.

## 15. Связанные документы

- `docs/product-editions.md`
- `docs/commercial-boundaries.md`
- `docs/community-release-checklist.md`
- `docs/repository-split-map.md`
- `docs/frontend-roadmap.md`
- `docs/refactoring-roadmap.md`
- `docs/agent-auth-model.md`