crank/docs/implementation-plan.md

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

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