# 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;
- вынести 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.