# Модель данных

Документ фиксирует текущую Community data model.

## Workspace

Workspace содержит:

- operations;
- agents;
- secrets;
- auth profiles;
- logs;
- usage.
- immutable local ProductEvents.

## Operation

Operation описывает один REST integration contract.

`Operation` хранит identity и availability (`active|archived`), а `OperationVersion` — самостоятельный immutable execution/export snapshot. Каждый изменённый save добавляет monotonic Draft revision; publish переводит только current Draft в Published и никогда не двигает publication pointer назад. Archive меняет только aggregate availability.

Основные поля:

- `id`
- `workspace_id`
- `name`
- `display_name`
- `category`
- `protocol = rest`
- `status`
- `target`
- `input_schema`
- `output_schema`
- `input_mapping`
- `output_mapping`
- `execution_config`
- `tool_description`
- `created_at`
- `updated_at`

Version-local snapshot также хранит name/display/category/protocol/security level и provenance. Версии, созданные до migration v4, честно помечены `legacy_observed`: это migration-time наблюдение, а не выдуманная историческая публикация.

## REST target

REST target содержит:

- `base_url`
- `method`
- `path_template`
- `static_headers`

Поддерживаемые методы:

- `GET`
- `POST`
- `PUT`
- `PATCH`
- `DELETE`

## Agent

Agent определяет MCP endpoint и набор published operations.

Основные поля:

- `id`
- `workspace_id`
- `slug`
- `display_name`
- `description`
- `status`
- `current_draft_version`
- `latest_published_version`
- `catalog_revision`

Agent catalog lifecycle (`agent-catalog-lifecycle-v9`) разделяет mutable aggregate и immutable Published Agent Version:

- Draft/current version можно редактировать до publication;
- Published Agent Version и его bindings являются append-only snapshot и не изменяются in place;
- `published_agents` хранит current published pointer и `catalog_revision`;
- `catalog_revision` монотонно увеличивается при publish/unpublish/archive и связывает MCP search result с последующей `call_tool`;
- Agent binding всегда указывает exact Published Operation Version из того же workspace.

Archive меняет availability Agent aggregate и запрещает новые публикации/bindings через Admin API, но не переписывает уже опубликованные snapshots и historical invocation evidence.

## Secrets и auth profiles

`Secret` хранит encrypted secret material.

`AuthProfile` описывает, как применить secret к REST request:

- bearer token;
- basic auth;
- API key header;
- API key query parameter.

Plaintext secret не возвращается через API после создания.
Rotation добавляет новую encrypted version и делает её текущей для следующего
execution. Operation и Auth Profile продолжают хранить только ссылки; их не
нужно переписывать при rotation.

Master-key identity — отдельный durable security contract. PostgreSQL хранит
только non-secret fingerprint, active epoch и cipher contract. Каждая новая
`secret_versions` row содержит `master_key_epoch`; legacy rows считаются epoch
`1`. Во время operator-controlled master-key rotation target ciphertext
записывается рядом с текущим ciphertext и не становится authoritative до
verification/promotion. Promotion атомарно переводит active epoch и переносит
target ciphertext в основной ciphertext. Abort до promotion оставляет текущий
epoch активным и очищает staged target fields.

## MCP и approval keys

`PlatformApiKey` хранит только metadata, bounded prefix и hash. Raw key
возвращается один раз в create response. Новые Invocation History records могут
безопасно хранить typed exact `platform_api_key_id`, полученный из verified
machine credential; сам credential и hash в history не записываются.

Ключи разделены по назначению:

- `mcp_client` — доступ MCP client к опубликованному Agent catalog;
- `approval` — approval side-channel с отдельным scope и optional
  `allowed_origins`.

Lifecycle статусы:

- `active`;
- `revoked`;
- `deleted`.

`revoke` немедленно прекращает доступ. `delete` переводит revoked key в
terminal metadata state `deleted`, сохраняя provenance. Credential lifecycle
пишет bounded audit events через `AuditSink`; plaintext, raw key, ciphertext и
hash в audit payload не попадают.

## Approval requests

`approval_requests` — PostgreSQL authority для human approval side-channel.
Pending uniqueness задаётся full scope index:
`workspace_id, agent_id, operation_id, operation_version, request_fingerprint`
для `status = 'pending'`. Fingerprint считается по canonical JSON input без
служебных Crank control fields, поэтому retry с новым confirmation token не
создаёт новый pending request. `request_payload_json` хранит bounded safe summary,
а не raw payload; secret-like ключи редактируются до записи.

Execution transitions выполняются conditional update:
`pending → approved|denied|expired`, затем `approved → executing`, затем
terminal `completed|failed`. Повторный terminal approve/deny возвращает текущую
заявку и не запускает второй side effect. Если процесс прервался после dispatch,
recovery не делает автоматический retry mutating operation и сохраняет
`approval_execution_outcome_unknown`.

## Logs и usage

Invocation logs фиксируют:

- workspace;
- agent;
- operation;
- точную версию operation для новых выполнений;
- request id;
- trace id;
- status;
- latency;
- закрытую стадию выполнения;
- стабильный код ошибки, retryability и certainty результата.
- nullable exact MCP key identity для новых scoped machine invocations.

Поля классификации nullable для строк, созданных до migration v5: исторические
значения не восстанавливаются предположениями. Новые Admin Draft Test и MCP
выполнения записывают точную версию и оба correlation ID независимо от
telemetry sampling.

Usage rollups агрегируют вызовы по периодам.
Агрегация использует UTC half-open windows `[start, end)` и не группирует по
Request ID или Trace ID. Для операторского анализа Usage отдельно отдаёт
outcome groups `success`, `upstream`, `client`, `schema`, `crank`, чтобы не
смешивать ошибки внешнего сервиса, входных данных, схемы и самого Crank.

Retention применим только к строкам `invocation_logs` старше effective cutoff.
Effective cutoff вычисляется как минимум из requested cutoff и preservation
floor, который сохраняет последние 90 дней usage-данных для операторской
аналитики. Outcome retention операции typed и observable: `noop` или
`completed`, количество удалённых rows и применённая policy. Retention не
изменяет Published Operation Version, Agent snapshot, approvals или immutable
release evidence.

## Local ProductEvents

`ProductEvent` — локальное immutable versioned событие продукта. В V11 закрытый
словарь состоит из `onboarding_eligible`, `onboarding_started`,
`onboarding_resumed`, `onboarding_dismissed`, `onboarding_abandoned` и
`onboarding_completed`. Событие содержит workspace scope, `schema_version = 1`,
UTC occurrence time и bounded idempotency key; `onboarding_eligible` обязательно
несёт explicit `eligible_since`, поэтому denominator SM-11–SM-13 не выводится
из browser state.

`product_events` append-only: update/delete отклоняются PostgreSQL trigger.
Idempotency уникальна в пределах workspace. `product_event_daily_rollups`
хранит только workspace/event/day counters (`events_total`, `eligible_total`),
без raw user/object identifiers, payload, key material или usage. ProductEvents остаются
локальными и не становятся внешней analytics отправкой без отдельного opt-in.