crank/docs/refactoring-roadmap.md

Refactoring roadmap

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

Этот документ фиксирует оставшийся технический backlog после уже выполненных больших backend и frontend refactoring tracks.

Он не повторяет уже завершенные изменения, а описывает то, что еще нужно для product-ready open-core платформы.

2. Что уже считается выполненным

Закрытыми считаются следующие крупные инженерные направления:

• модульное разбиение crank-registry;
• compile-time SQL verification для статических запросов;
• HKDF вместо прямого SHA-256 derivation;
• typed timestamps;
• Display для typed ids;
• explicit PostgreSQL pool configuration;
• structured runtime and registry errors;
• correlation IDs;
• runtime backpressure и request throttling;
• distributed transport session store;
• frontend build pipeline и wizard modularization.

3. Оставшиеся технические треки

3.1. Open-core boundary extraction

Цель:

• отделить Community runtime от будущих commercial implementations.

Что нужно:

• capability model по редакциям;
• protocol gating;
• auth gating;
• extension seams для private implementations;
• отдельные delivery manifests для Community.

Ключевые места:

• crates/crank-core
• apps/admin-api
• apps/mcp-server
• apps/ui
• docs/product-editions.md
• docs/commercial-boundaries.md

3.2. Agent-scoped machine auth completion

Цель:

• довести current docs-first auth model до рабочего Community implementation.

Что нужно:

• полноценный AgentKey lifecycle в admin-api и UI;
• отказ от remaining workspace/platform-key assumptions;
• enforcement security_level = standard в Community flow;
• capability scaffolding для elevated и strict.

3.3. Private token-service seam

Цель:

• подготовить публичный код к private реализации short-lived и one-time token flows.

Что нужно:

• stable HTTP contracts;
• server-side trait boundary;
• token verification abstraction in mcp-server;
• capability-aware UI contract.

3.4. Commercial protocol split

Цель:

• перестать считать все уже написанные protocol families частью Community surface.

Что нужно:

• определить Community-supported protocol set;
• зафиксировать REST как единственный Community protocol surface;
• вынести premium protocols и premium execution modes в private delivery plan;
• синхронизировать UI, docs и release process.

3.5. Release and distribution hardening

Цель:

• подготовить reproducible public Community release и private commercial delivery.

Что нужно:

• public release flow for GitHub;
• private image flow for Enterprise;
• artifact signing / provenance;
• clear packaging split for Community vs commercial.

4. Правила приоритизации

Сначала выполняются треки, которые формируют границу продукта:

1. open-core boundary extraction;
2. Community agent-scoped auth completion;
3. private token-service seam;
4. frontend edition gating;
5. release and distribution hardening.

После этого уже можно безопасно идти в enterprise/cloud-specific implementation.