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-структура

  crank/
  apps/
    admin-api/
    mcp-server/
    ui/
  crates/
    crank-core/
    crank-registry/
    crank-runtime/
    crank-adapter-rest/
    crank-mapping/
    crank-schema/

Поверх существующих 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-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.5. 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.6. Protocol adapters

• crank-adapter-rest

Community runtime в этом репозитории поддерживает только REST.

4.7. apps/admin-api

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

• workspaces
• secrets
• memberships
• operations
• auth_profiles
• agents
• agent_keys
• platform_clients
• logs
• usage
• streaming

4.8. 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.