crank/docs/module-decomposition.md

# Декомпозиция модулей

## 1. Цель документа

Этот документ фиксирует детальную структуру проекта под целевую модель `workspace -> agent -> operations`.

Основной принцип: каждый crate отвечает за один слой системы. Внутри crate модули маленькие, тематические и с минимальным количеством публичных сущностей.

## 2. Общие архитектурные правила

- `core` содержит только базовую доменную модель, идентификаторы, типы ошибок и общие контракты.
- `registry` отвечает только за хранение и загрузку workspace-scoped конфигурации.
- `runtime` исполняет операции, но не знает о способе их хранения.
- адаптеры знают только свой протокол и общий контракт runtime.
- `admin-api` оркестрирует use case для UI, но не содержит протокольной логики.
- `mcp-server` публикует agent-scoped tools и вызывает runtime.
- `ui` работает только через HTTP API.

## 3. Workspace-структура

```text
  crank/
  apps/
    admin-api/
    mcp-server/
    ui/
  crates/
    crank-core/
    crank-registry/
    crank-runtime/
    crank-adapter-rest/
    crank-adapter-graphql/
    crank-adapter-grpc/
    crank-adapter-websocket/
    crank-adapter-soap/
    crank-mapping/
    crank-schema/
    crank-proto/
```

Поверх существующих crates должны появиться новые логические поддомены:

- workspace/access domain;
- secret management domain;
- agent publishing domain;
- observability domain.
- streaming execution domain.

## 4. Детальная декомпозиция по crate

### 4.1. `crank-core`

Назначение:

- базовые доменные типы;
- идентификаторы;
- метаданные workspace, operation и agent;
- общие контракты и ошибки.

Внутренние модули:

- `ids`
- `protocol`
- `workspace`
- `operation`
- `agent`
- `auth`
- `secret`
- `observability`
- `streaming`
- `errors`

### 4.2. `crank-schema`

Назначение:

- внутренняя модель схем;
- нормализация входа и выхода;
- представление полей для UI и runtime.

### 4.3. `crank-mapping`

Назначение:

- mapping DSL;
- `JSONPath` parsing;
- input/output mapping;
- draft inference из samples.

### 4.4. `crank-proto`

Назначение:

- работа с `.proto` и descriptor set;
- извлечение services, methods и message schemas;
- преобразование protobuf metadata во внутренние типы.

### 4.5. `crank-registry`

Назначение:

- хранение workspace-scoped operations и version snapshots;
- хранение workspace-scoped secrets и secret versions;
- хранение agents и agent versions;
- хранение agent keys и выданных agent tokens;
- хранение stream sessions и async jobs;
- auth profiles;
- platform client credentials;
- logs и usage aggregates;
- metadata по sample artifacts и descriptors.

### 4.6. `crank-runtime`

Назначение:

- исполнение published operation;
- резолв `auth_profile_ref -> secret -> request auth`;
- orchestration window/session/job execution;
- запись invocation events;
- возврат нормализованного результата.

Дополнительное правило для split:

- `crank-runtime` должен собираться как `REST-only` base даже без premium adapter crates;
- premium protocol adapters подключаются через feature seams, а не как безусловная зависимость Community runtime.

### 4.7. Protocol adapters

- `crank-adapter-rest`
- `crank-adapter-graphql`
- `crank-adapter-grpc`
- `crank-adapter-websocket`
- `crank-adapter-soap`

Каждый adapter знает только свой протокол.

Для open-core split это означает:

- `crank-adapter-rest` остается обязательной частью Community runtime;
- `crank-adapter-graphql`, `crank-adapter-grpc`, `crank-adapter-websocket`, `crank-adapter-soap`
  должны подключаться как отделяемые protocol modules.

### 4.8. `apps/admin-api`

Должен содержать сервисные группы:

- `workspaces`
- `secrets`
- `memberships`
- `operations`
- `auth_profiles`
- `agents`
- `agent_keys`
- `platform_clients`
- `logs`
- `usage`
- `streaming`

### 4.9. `apps/mcp-server`

Назначение:

- публикация published agent bindings как MCP tools;
- transport handling;
- JSON-RPC lifecycle;
- SSE lifecycle и `Mcp-Session-Id`;
- tool-family generation для `session` и `async_job`;
- вызов runtime.

Антипаттерн:

не превращать `mcp-server` во второй `admin-api`.

## 5. Разделение open-source и commercial модулей

### 5.1. Что остается в `crank-community`

В этом репозитории должны жить:

- Community domain model;
- Community runtime;
- Community UI;
- extension seams для коммерческих возможностей;
- capability model по редакциям.

### 5.2. Что должно выноситься в private delivery

За пределами `crank-community` должны жить:

- short-lived и one-time token issuers;
- enterprise access services;
- `SSO`, `2FA`, `RBAC`, `audit log`;
- metering и billing;
- cloud control plane;
- premium protocol families, если они не входят в Community edition.

### 5.3. Техническое правило

Public code не должен содержать скрытую private business logic.

Допустимо:

- trait boundaries;
- capability flags;
- edition-aware service contracts.

Недопустимо:

- полноценная коммерческая реализация в open-source исходниках;
- UI, который реально включает premium flow без server-side gating.