crank/docs/database-schema.md

Схема БД

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

Этот документ фиксирует целевую структуру хранения workspace-scoped конфигураций, агентов, ключей доступа и observability-данных. Базовая СУБД - PostgreSQL.

2. Общие принципы хранения

2.1. Версионирование обязательно

Конфигурация operation и agent не хранится только в одной "живой" записи. Каждое существенное изменение создает новую версию.

2.2. Published и draft разделяются логически

• draft может меняться;
• published всегда указывает на конкретную version;
• runtime читает только опубликованные представления.

2.3. Workspace scoping обязателен

Все продуктовые таблицы должны ссылаться на workspaces.

2.4. Артефакты и конфигурация не смешиваются

.proto, descriptor set, sample JSON и YAML payload не хранятся в тех же строках, что runtime-ready configuration.

2.5. Секреты не хранятся в открытом виде

• upstream secrets живут в отдельных таблицах и шифруются;
• agent keys и credentials доверенных клиентов хранятся как hash;
• короткоживущие токены хранятся в форме, пригодной для отзыва и учета использования.

3. Основные таблицы

• workspaces
• users
• user_sessions
• memberships
• invitation_tokens
• secrets
• secret_versions
• operations
• operation_versions
• published_operations
• operation_samples
• descriptors
• auth_profiles
• agents
• agent_versions
• agent_operation_bindings
• published_agents
• agent_keys
• issued_agent_tokens
• platform_client_credentials
• stream_sessions
• async_jobs
• invocation_logs
• usage_rollups
• yaml_import_jobs

4. Operations

operations

• id
• workspace_id
• name
• display_name
• protocol
• status
• security_level
• current_draft_version
• latest_published_version
• created_at
• updated_at
• published_at

Ограничение:

• unique (workspace_id, name)

operation_versions

• operation_id
• version
• status
• target_json
• input_schema_json
• output_schema_json
• input_mapping_json
• output_mapping_json
• execution_config_json
• tool_description_json
• samples_json
• generated_draft_json
• config_export_json
• change_note
• created_at
• created_by

published_operations

• operation_id
• version
• published_at
• published_by

5. Operation artifacts

operation_samples

• id
• operation_id
• version
• sample_kind
• storage_ref
• content_type
• file_name
• created_at

descriptors

• id
• operation_id
• version
• descriptor_kind
• storage_ref
• source_name
• package_index_json
• created_at

descriptor_kind дополнительно поддерживает:

• wsdl_upload
• xsd_upload

package_index_json для wsdl_upload хранит нормализованный inspection result:

• service_name
• port_name
• binding_name
• endpoint
• soap_version
• operations[]

yaml_import_jobs

• id
• source_sample_id
• status
• format_version
• mode
• result_operation_id
• result_version
• error_text
• created_at
• finished_at

6. Upstream secrets and auth

secrets

• id
• workspace_id
• name
• kind
• status
• current_version
• created_at
• updated_at

Ограничение:

• unique (workspace_id, name)

secret_versions

• secret_id
• version
• ciphertext
• key_version
• created_at

auth_profiles

• id
• workspace_id
• name
• kind
• config_json
• created_at
• updated_at

Назначение:

• config_json хранит ссылки на secret_id, а не plaintext значения;
• допустимы bearer, basic, api-key-header, api-key-query профили.

Ограничение:

• unique (workspace_id, name)

agent_keys

• id
• workspace_id
• agent_id
• name
• prefix
• secret_hash
• scopes_json
• status
• expires_at
• created_at
• last_used_at

Ограничения:

• unique (agent_id, name)
• prefix уникален глобально

Назначение:

• длинноживущий ключ принадлежит одному агенту;
• ключ используется как исходное основание для выпуска короткоживущего токена;
• прямой вызов MCP по такому ключу допускается только в переходном режиме.

issued_agent_tokens

• id
• workspace_id
• agent_id
• agent_key_id
• token_kind
• status
• scopes_json
• max_uses
• used_count
• cnf_jkt
• expires_at
• created_at
• used_at

Индексы:

• (agent_id, status, expires_at)
• (workspace_id, status, expires_at)
• (cnf_jkt) при включенной привязке токена к ключевой паре клиента

Назначение:

• учет выданных короткоживущих токенов;
• поддержка одноразовых токенов;
• поддержка отзыва и проверки повторного использования.

stream_sessions

• id
• workspace_id
• agent_id
• operation_id
• mode
• status
• cursor_json
• state_json
• expires_at
• last_poll_at
• created_at
• closed_at

Индексы:

• (workspace_id, status, expires_at)
• (operation_id, status)

async_jobs

• id
• workspace_id
• agent_id
• operation_id
• status
• progress_json
• result_json
• error_json
• expires_at
• created_at
• updated_at
• finished_at

Индексы:

• (workspace_id, status, expires_at)
• (operation_id, status)

7. Workspaces and access layer

workspaces

• id
• slug
• display_name
• status
• settings_json
• created_at
• updated_at

users

• id
• email
• display_name
• password_hash
• status
• created_at

user_sessions

• id
• user_id
• secret_hash
• status
• expires_at
• last_seen_at
• created_at

Ограничения:

• unique (user_id, id)

memberships

• workspace_id
• user_id
• role
• created_at

invitation_tokens

• id
• workspace_id
• email
• role
• status
• token_hash
• expires_at
• created_at

8. Agents

agents

• id
• workspace_id
• slug
• display_name
• description
• status
• current_draft_version
• latest_published_version
• created_at
• updated_at
• published_at

Ограничение:

• unique (workspace_id, slug)

agent_versions

• agent_id
• version
• status
• instructions_json
• tool_selection_policy_json
• created_at

agent_operation_bindings

• agent_id
• agent_version
• operation_id
• operation_version
• tool_name
• tool_title
• tool_description_override
• enabled

published_agents

• agent_id
• version
• published_at
• published_by

9. Machine access and observability

agent_keys

• id
• workspace_id
• agent_id
• name
• prefix
• secret_hash
• scopes_json
• status
• expires_at
• created_at
• last_used_at

issued_agent_tokens

• id
• workspace_id
• agent_id
• agent_key_id
• token_kind
• status
• scopes_json
• max_uses
• used_count
• cnf_jkt
• expires_at
• created_at
• used_at

invocation_logs

• id
• workspace_id
• agent_id
• operation_id
• source
• request_id
• level
• status
• tool_name
• message
• status_code
• duration_ms
• error_kind
• request_preview_json
• response_preview_json
• created_at

usage_rollups

• workspace_id
• agent_id
• operation_id
• period_kind
• period_start
• calls_total
• calls_ok
• calls_error
• p50_ms
• p95_ms
• p99_ms

Замечание:

• в MVP usage read-model может вычисляться напрямую из invocation_logs;
• usage_rollups сохраняется как совместимая таблица под materialized aggregates и дальнейшую оптимизацию.

10. Migration strategy

Переход от текущей схемы к целевой идет так:

1. добавить workspaces и заполнить default workspace;
2. добавить workspace_id в operations и auth_profiles;
3. добавить secrets и secret_versions;
4. перевести auth_profiles на secret-backed config;
5. добавить agents и published_agents;
6. внедрить agent_keys, platform_client_credentials и issued_agent_tokens;
7. добавить invocation_logs и usage_rollups;
8. перевести MCP runtime на published_agents, а не на глобальный список operations.