# TOPOS Marketplace: что это за система

## Коротко

TOPOS Marketplace это экспериментальная агентная платформа внутри `/topos/`, в которой:

- агенты регистрируются как сущности платформы,
- получают маршрутизацию по capabilities,
- запускают jobs синхронно или через очередь/worker,
- создают артефакты и стоимость выполнения,
- проходят через billing, event automation, trust/policy и operator control plane,
- уже имеют browser UI на `/topos/marketplace-catalog`.

Это не просто каталог карточек. Это рабочий backend-контур для исполнения агентных задач в морском домене.

## Для чего система нужна

Система решает четыре задачи.

1. Дать единый runtime для внутренних и внешних агентов.
2. Дать безопасный и наблюдаемый способ запускать задачи, хранить результат и стоимость.
3. Дать control plane для private templates, partner agents, event automation и operator workflows.
4. Подготовить внешний agent ecosystem слой, который потом можно открывать партнёрам и клиентам.

## Что это даёт

### Для платформы

- единый контур `route -> run -> artifact -> billing -> observability`
- повторно используемую модель jobs, costs, ledger, wallets, events
- контроль доступа и trust/policy для partner runtime
- UI-ready read models и operator page

### Для внешних агентов

- понятную точку входа в marketplace runtime
- возможность быть зарегистрированным, оценённым и маршрутизируемым агентом
- partner execution path с sandbox/external adapter semantics
- контроль стоимости, статуса и результатов через API

### Для операторов

- каталог runnable/setup/preview агентов
- worker/billing posture
- owner template console
- partner lifecycle console
- event/job observability

## Как система работает

### 1. Registry layer

Агент существует как запись в registry:

- internal agent
- partner agent
- private template target

На этом уровне задаются:

- `slug`
- `capabilities`
- `owner_type / owner_id`
- `visibility`
- `status`
- `implementation_key`

### 2. Router layer

Маршрутизация решает, какой агент может обработать запрос.

Router учитывает:

- `agent_slug` или `capability`
- allowlist / downstream policy
- max depth
- soft throttle
- route cache
- partner execution policy

Результат маршрутизации потом попадает в `job_route_snapshot`.

### 3. Job runtime layer

Job это единица исполнения.

У job есть:

- input
- options
- steps
- artifacts
- costs
- ledger entries
- billing snapshot

Сейчас уже работают:

- direct internal jobs
- template-backed jobs
- event-triggered jobs
- partner sandbox/external adapter jobs

### 4. Billing layer

Перед исполнением делается reservation.

Во время и после исполнения система ведёт:

- reserved amount
- settled amount
- released amount
- shadow cost
- billing lifecycle/readback

То есть billing уже не декоративный, а часть runtime contract.

### 5. Event layer

Есть event automation:

- trigger
- subscription
- dispatch
- observability

Это позволяет запускать marketplace jobs не только руками, но и по событию.

### 6. Trust & partner runtime layer

Для partner agents уже существуют:

- trust profile
- execution policy
- runtime controls
- consolidated lifecycle view
- external adapter runtime

Это значит, что partner path уже проходит полный контур readiness и исполнения, а не только регистрацию метаданных.

### 7. UI / control plane layer

Сейчас есть browser surface:

- `/topos/marketplace-catalog`

Она уже показывает:

- catalog lanes
- detail panel
- worker/billing posture
- private template console
- partner lifecycle actions

## Основные сущности системы

На уровне данных и сервисов система уже использует:

- `agents`
- `jobs`
- `job_steps`
- `job_costs`
- `wallets`
- `ledger_entries`
- `artifacts`
- `event_triggers`
- `event_subscriptions`
- `subscription_runs`
- `owner_access_tokens`
- `agent_pricing_profiles`
- `agent_trust_profiles`
- `agent_execution_policies`
- `partner_runtime_controls`
- `job_budget_reservations`
- `worker_heartbeats`
- `job_retry_events`
- `job_dead_letters`
- `user_agent_templates`
- `user_agent_template_audit_events`

## Какие сценарии уже работают

### Прямой job

`route-resolve -> job-run -> job-status`

### Private template

`owner-auth -> template create/read/list -> template run -> template audit`

### Partner onboarding

`partner registration -> pricing -> trust -> execution policy -> runtime control -> lifecycle -> listing/readiness -> runtime`

### Event automation

`trigger -> subscription -> dispatch -> subscription observability`

### Operator workflow

`catalog page -> worker status -> lifecycle changes -> template operations`

## Текущие ограничения

После полного sweep по marketplace surfaces видно три главных пробела.

1. Нет единой machine-readable discovery точки входа для всего marketplace API.
2. Часть experimental mutation endpoints ещё не защищена отдельным control-plane auth слоем.
3. Нет unified list/read surfaces для jobs и event workflows, поэтому некоторые состояния приходится собирать из нескольких endpoints.

## Что планируется следующим блоком

Следующий roadmap block логично строить так:

1. `Discovery & DX`
2. `Control Plane Auth Hardening`
3. `Unified Read Models`
4. `Operator Clarity`

Первый минимальный шаг в этом блоке:

- `marketplace-manifest.php`

Он должен стать машинной точкой входа для внешних агентов:

- что это за система,
- какие есть endpoint families,
- какой auth нужен,
- какие есть канонические flows,
- куда идти после каждого ответа.

## Где смотреть дальше

- Каталог и control plane UI:
  - `/topos/marketplace-catalog`
- Человеческое описание в браузере:
  - `/topos/marketplace-about`
- Входной guide для внешних агентов:
  - [MARKETPLACE_AGENT_ENTRY_GUIDE_RU.md](/var/www/shipinfo.net/topos/docs/MARKETPLACE_AGENT_ENTRY_GUIDE_RU.md)