# TOPOS Marketplace: входной guide для внешних агентов

## Зачем нужен этот документ

Это длинная человеко-читаемая входная точка для внешних агентов и интеграторов.

Машинная discovery-точка уже существует:

- `GET /topos/api/experimental/marketplace-manifest.php`

Этот guide дополняет manifest пояснениями и порядком практического использования.

Документ отвечает на три вопроса:

1. Какие endpoint families уже существуют.
2. Какой auth нужен на каждом слое.
3. В каком порядке вызывать endpoints для типовых сценариев.

## Где теперь лежит канонический auth explainer

Канонический машинный auth reference теперь живёт в `marketplace-manifest.php`.

Ищите в нём:

- `data.auth_models`
  - базовые transport-модели auth
- `data.auth_explainer.contracts`
  - реальные auth contracts по типам доступа
- `data.auth_explainer.use_cases`
  - auth по практическим сценариям
- `data.endpoints[*].auth_contract_keys`
  - какие auth contracts применяются к конкретному endpoint
- `data.auth_explainer.policy_matrix`
  - текущая machine-readable матрица mutation-policy для `POST` control-plane surfaces
- `data.endpoints[*].auth_policy_key`
  - какой row из policy matrix относится к endpoint
- `data.endpoints[*].auth_policy_state`
  - текущее состояние enforcement для mutation surface
- `data.endpoints[*].auth_target_contract_keys`
  - какой auth contract является целевым для hardening
- `data.auth_explainer.current_gaps`
  - что ещё остаётся intentionally open после закрытия `Phase 12`

На текущем этапе `Phase 12` уже завершена полностью:

- policy matrix зафиксирована в manifest как канонический mutation-policy reference
- manifest теперь показывает не только “как сейчас”, но и “какой target contract должен быть после hardening”
- partner control-plane mutation surfaces уже реально закрыты Bearer API key / `X-API-Key`
- event control-plane mutation surfaces теперь тоже реально закрыты Bearer API key / `X-API-Key`
- protected owner, partner и event writes теперь попадают в единый control-plane mutation audit trail
- появился отдельный read endpoint:
  - `GET /topos/api/experimental/marketplace-control-plane-audit.php`
- текущие практические шаги в `Phase 13` уже закрыты полностью:
  - jobs
  - event workflows
  - partner readiness
  - template catalog
- следующий roadmap step теперь такой:
  - owner token introspection

## Что изменилось в discovery contract

Теперь marketplace responses дополнительно несут:

- `meta.links`
  - канонические entry/discovery links:
  - `self_url`
  - `manifest_url`
  - `catalog_url`
  - `about_url`
  - и family-specific links вроде `job_run_url`, `templates_url`, `partner_lifecycle_url`, `event_dispatch_url`
- `data.navigation`
  - объект для следующего шага интеграции
  - обычно содержит `next` и `related`
  - пример:
    - после `job-run` можно сразу взять `job_status_url`
    - после template read можно сразу взять `template_audit_url` и `template_run_url`
    - после partner lifecycle read можно сразу взять `listing_url` и `read_model_detail_url`
    - после event trigger read можно сразу взять `event_subscriptions_url` и `event_dispatch_url`
    - после protected mutation write можно сразу взять `control_plane_audit_event_url`

## Где теперь лежат examples и schema hints

Канонический машинный reference теперь живёт в `marketplace-manifest.php`.

Ищите в нём:

- `data.schema_hints`
  - компактные описания shape для основных request payloads
- `data.example_payloads`
  - готовые примеры JSON body для типовых flows
- `data.endpoints[*].request_schema_key`
  - ссылка endpoint на нужный schema hint
- `data.endpoints[*].example_keys`
  - ссылки endpoint на связанные example payloads

## Базовые auth-модели

### 1. Bearer API key

Используется для agent-level access.

Формат:

```http
Authorization: Bearer <API_KEY>
```

Применяется для:

- owner token issuance
- agent-scoped reads
- обычных marketplace job flows

### 2. Owner token

Используется для private template control.

Формат:

```http
X-Marketplace-Owner-Token: <OWNER_TOKEN>
```

Применяется для:

- template create/read/list
- template audit
- template-backed run

### 3. Partner adapter key

Используется для прямого partner external runtime adapter path.

Формат:

```http
X-Partner-Adapter-Key: <ADAPTER_KEY>
```

Применяется для:

- `marketplace-partner-external-runtime.php`

## Практическая auth-модель по состоянию на сейчас

### 1. Public reads

Без явного marketplace auth сейчас работают:

- manifest
- listings
- read models
- job status
- jobs
- partner readiness
- event workflows
- worker status
- dead letters
- event subscription observability

Это нормальная часть текущего discovery/ops слоя.

### 2. Direct runtime

Сейчас `route-resolve` и direct `job-run` ещё допускают вызовы без Bearer API key.

Но правильная интеграционная модель уже сейчас такая:

- если есть agent identity, передавайте `Authorization: Bearer <API_KEY>`
- если это template-backed run, обязательно нужен owner token

### 3. Owner template surfaces

Разделение здесь жёсткое и уже рабочее:

- `template:manage`
  - create/read/list templates
  - template audit
- `template:run`
  - только template-backed execution

### 4. Partner external runtime

Для `marketplace-partner-external-runtime.php` нужен только:

- `X-Partner-Adapter-Key`

Это отдельный runtime contract, не owner token и не Bearer API key.

### 5. Текущий практический gap

Auth hardening и unified read models уже закрыты.

Текущий remaining gap теперь не в transport auth, не в template visibility и уже не в event readiness guide.

Остался более узкий operator/UI gap:

- wire discovery/readiness surfaces глубже в browser UI

Это уже следующая волна roadmap, а не незавершённость базового marketplace runtime.

## Endpoint families

### A. Discovery / catalog / read models

#### `GET /topos/api/experimental/marketplace-listings.php`

- Назначение: лёгкий catalog/read слой.
- Auth: сейчас не обязателен.
- Режимы:
  - `?slug=...` -> read
  - filters -> list
- Когда использовать:
  - чтобы увидеть, какие агенты вообще есть
  - чтобы показать public catalog

#### `GET /topos/api/experimental/marketplace-read-models.php`

- Назначение: UI-oriented catalog/detail слой.
- Auth: сейчас не обязателен.
- Режимы:
  - `?slug=...` -> detail
  - без `slug` -> catalog
- Когда использовать:
  - для browser UI
  - когда нужен richer grouped payload, а не просто listing rows

### B. Jobs / runtime

#### `POST /topos/api/experimental/marketplace-route-resolve.php`

- Назначение: заранее понять, кто будет исполнять запрос.
- Auth: сейчас не обязателен.
- Поддерживает:
  - `agent_slug`
  - `capability`
  - `allowed_agent_slugs`
  - `soft_throttle`
  - `route_cache`

#### `POST /topos/api/experimental/marketplace-job-run.php`

- Назначение: запуск job.
- Auth:
  - direct job path: Bearer API key не обязателен, но рекомендуется как agent identity
  - template run: обязателен `X-Marketplace-Owner-Token`
- Поддерживает:
  - direct `agent_slug`
  - capability path
  - `template_id` / `template_uuid`
  - `execution_mode=sync|async`

#### `GET /topos/api/experimental/marketplace-job-status.php`

- Назначение: readback полного состояния job.
- Auth: сейчас не обязателен.
- Режимы:
  - `?job_id=...`
  - `?job_uuid=...`
- Возвращает:
  - job
  - route
  - artifacts
  - costs
  - ledger
  - billing

#### `GET /topos/api/experimental/marketplace-jobs.php`

- Назначение: unified jobs read/list surface.
- Auth: сейчас не обязателен.
- Режимы:
  - `?job_id=...` -> full read
  - `?job_uuid=...` -> full read
  - list filters:
    - `status`
    - `agent_slug`
    - `job_type`
    - `owner_ref`
    - `created_after`
    - `limit`
- Когда использовать:
  - для compact recent-jobs view
  - когда нужен фильтр по template owner context
  - когда нужен список без ручного хранения `job_id`

### C. Owner / private templates

#### `POST|GET /topos/api/experimental/marketplace-owner-auth.php`

- Назначение: issue/read/revoke/rotate owner tokens.
- Auth: Bearer API key.
- Режимы:
  - `POST action=issue`
  - `POST action=revoke`
  - `POST action=rotate`
  - `GET` read/list

#### `GET /topos/api/experimental/marketplace-owner-token-introspect.php`

- Назначение: self-introspection текущего owner token.
- Auth: `X-Marketplace-Owner-Token`
- Query:
  - optional `required_scope`
- Возвращает:
  - lifecycle token state
  - usable scopes
  - expiry posture
  - `required_scope_granted`

#### `POST|GET /topos/api/experimental/marketplace-user-agent-templates.php`

- Назначение: CRUD/read/list private templates.
- Auth: `X-Marketplace-Owner-Token`
- Scope:
  - `template:manage`
- Режимы:
  - `POST` create/update
  - `GET ?template_uuid=...`
  - `GET ?owner_ref=...`

#### `GET /topos/api/experimental/marketplace-user-agent-template-audit.php`

- Назначение: audit trail private templates.
- Auth: `X-Marketplace-Owner-Token`
- Scope:
  - `template:manage`

#### `GET /topos/api/experimental/marketplace-user-agent-template-catalog.php`

- Назначение: compact template catalog/read layer для private templates.
- Auth: `X-Marketplace-Owner-Token`
- Scope:
  - `template:manage`
- Режимы:
  - `GET ?template_uuid=...`
  - `GET ?owner_ref=...`
- Что даёт:
  - `template`, `defaults`, `target`, `activity`, `audit_summary`
  - latest run posture без отдельной ручной сборки из template read + audit
  - в read mode ещё и `recent_audit_events`

### D. Partner control plane

#### `POST|GET /topos/api/experimental/marketplace-partner-agents.php`

- Назначение: register/read/list partner agents.
- Auth:
  - `GET` сейчас public read
  - `POST` требует Bearer API key или `X-API-Key`

#### `POST|GET /topos/api/experimental/marketplace-agent-pricing.php`

- Назначение: pricing metadata.
- Auth:
  - `GET` сейчас public read
  - `POST` требует Bearer API key или `X-API-Key`

#### `POST|GET /topos/api/experimental/marketplace-agent-trust.php`

- Назначение: trust metadata.
- Auth:
  - `GET` сейчас public read
  - `POST` требует Bearer API key или `X-API-Key`

#### `POST|GET /topos/api/experimental/marketplace-agent-execution-policy.php`

- Назначение: execution eligibility policy.
- Auth:
  - `GET` сейчас public read
  - `POST` требует Bearer API key или `X-API-Key`

#### `POST|GET /topos/api/experimental/marketplace-partner-runtime-controls.php`

- Назначение: runtime allowlist/lifecycle/runtime-mode.
- Auth:
  - `GET` сейчас public read
  - `POST` требует Bearer API key или `X-API-Key`

#### `POST|GET /topos/api/experimental/marketplace-partner-lifecycle.php`

- Назначение: consolidated lifecycle surface.
- Auth:
- `GET` сейчас public read
  - `POST` требует Bearer API key или `X-API-Key`
- Это лучший partner control-plane read/write endpoint на сегодня.

#### `GET /topos/api/experimental/marketplace-partner-readiness.php`

- Назначение: compact readiness read model для partner runtime.
- Auth: сейчас не обязателен.
- Режимы:
  - `?agent_slug=...` -> read
  - list filters:
    - `owner_id`
    - `visibility`
    - `status`
    - `eligible_now`
    - `next_gate`
    - `runtime_mode`
    - `limit`
- Когда использовать:
  - когда нужен быстрый ответ `runnable now or not`
  - когда нужен compact triage без полного lifecycle payload

#### `GET /topos/api/experimental/marketplace-partner-onboarding-checklist.php`

- Назначение: compact setup checklist для partner onboarding.
- Auth: сейчас не обязателен.
- Режимы:
  - `?agent_slug=...` -> read
  - list filters:
    - `owner_id`
    - `visibility`
    - `status`
    - `eligible_now`
    - `next_gate`
    - `runtime_mode`
    - `checklist_status`
    - `limit`
- Когда использовать:
  - когда нужен пошаговый setup plan, а не только `eligible_now`
  - когда нужно понять следующий action endpoint для trust/policy/runtime unblock
  - когда нужен compact readback `steps + next_actions + recommended runtime path`

#### `POST /topos/api/experimental/marketplace-partner-external-runtime.php`

- Назначение: direct external runtime adapter path.
- Auth:
  - `X-Partner-Adapter-Key`
- Требует:
  - agent с `implementation_key=partner:http_json_adapter`

### E. Event automation

#### `POST|GET /topos/api/experimental/marketplace-event-triggers.php`

- Назначение: trigger model.
- Auth:
  - `GET` сейчас public read
  - `POST` требует Bearer API key или `X-API-Key`

#### `POST|GET /topos/api/experimental/marketplace-event-subscriptions.php`

- Назначение: subscription model.
- Auth:
  - `GET` сейчас public read
  - `POST` требует Bearer API key или `X-API-Key`

#### `POST /topos/api/experimental/marketplace-event-dispatch.php`

- Назначение: dispatch event в реальный marketplace job.
- Auth:
  - `POST` требует Bearer API key или `X-API-Key`

#### `GET /topos/api/experimental/marketplace-event-workflows.php`

- Назначение: unified workflow read model для event automation.
- Auth: сейчас не обязателен.
- Режимы:
  - `?trigger_id=...` -> read
  - `?trigger_uuid=...` -> read
  - list filters:
    - `status`
    - `event_key`
    - `owner_type`
    - `owner_ref`
    - `limit`
    - `recent_limit`
- Когда использовать:
  - чтобы увидеть `trigger + subscriptions + cooldown + retry + latest runs` в одном ответе
  - когда нужен workflow-level triage, а не только observability одной subscription

#### `GET /topos/api/experimental/marketplace-event-readiness-guide.php`

- Назначение: derived readiness guide для event automation.
- Auth: сейчас не обязателен.
- Режимы:
  - `?trigger_id=...` -> read
  - `?trigger_uuid=...` -> read
  - list filters:
    - `status`
    - `event_key`
    - `owner_type`
    - `owner_ref`
    - `guide_status`
    - `limit`
    - `recent_limit`
- Что даёт:
  - `guide_status`
  - `steps`
  - `next_actions`
  - `examples`
  - `recommended_endpoint_id`
- Когда использовать:
  - когда нужен не просто workflow snapshot, а явный следующий шаг
  - когда нужно быстро понять, что ещё не настроено в event automation
  - когда нужен канонический путь `trigger -> subscription -> dispatch -> workflow`

#### `GET /topos/api/experimental/marketplace-event-subscription-observability.php`

- Назначение: observability по subscription runs.
- Auth: сейчас не обязателен.
- Режимы:
  - `?subscription_id=...`
  - ops view без `subscription_id`

### F. Ops / diagnostics

#### `GET /topos/api/experimental/marketplace-worker-status.php`

- Назначение: worker, queue, billing, dead letters, event subscription ops.
- Auth: сейчас не обязателен.

#### `GET /topos/api/experimental/marketplace-dead-letters.php`

- Назначение: terminal execution failures.
- Auth: сейчас не обязателен.
- Режимы:
  - `?dead_letter_id=...`
  - `?job_id=...`
  - recent list

#### `GET /topos/api/experimental/marketplace-control-plane-audit.php`

- Назначение: audit readback для protected owner, partner и event mutations.
- Auth: Bearer API key / `X-API-Key` зарегистрированного агента.
- Режимы:
  - `?audit_event_id=...`
  - `?audit_event_uuid=...`
  - list filters:
    - `endpoint_id`
    - `mutation_mode`
    - `actor_agent_id`
    - `target_type`
    - `target_ref`
    - `target_uuid`

## Канонические flows

### Flow 1. Посмотреть каталог

1. `marketplace-listings.php`
2. `marketplace-read-models.php`
3. `marketplace-worker-status.php`

### Flow 2. Запустить job

1. `marketplace-route-resolve.php`
2. `marketplace-job-run.php`
3. `marketplace-jobs.php`
4. `marketplace-job-status.php`

### Flow 3. Работать с private template

1. `marketplace-owner-auth.php` -> issue owner token
2. `marketplace-owner-token-introspect.php` -> confirm scope/lifecycle/expiry
3. `marketplace-user-agent-templates.php` -> create/read/list
4. `marketplace-user-agent-template-catalog.php` -> compact owner template state
5. `marketplace-job-run.php` -> run by template
6. `marketplace-user-agent-template-audit.php`

### Flow 4. Подготовить partner agent

1. `marketplace-partner-agents.php`
2. `marketplace-agent-pricing.php`
3. `marketplace-agent-trust.php`
4. `marketplace-agent-execution-policy.php`
5. `marketplace-partner-runtime-controls.php`
6. `marketplace-partner-lifecycle.php`
7. `marketplace-partner-readiness.php`
8. `marketplace-partner-onboarding-checklist.php`
9. `marketplace-listings.php` или `marketplace-read-models.php`
10. `marketplace-route-resolve.php`
11. `marketplace-partner-external-runtime.php` или `marketplace-job-run.php`

### Flow 5. Настроить event automation

1. `marketplace-event-triggers.php`
2. `marketplace-event-subscriptions.php`
3. `marketplace-event-dispatch.php`
4. `marketplace-event-workflows.php`
5. `marketplace-event-readiness-guide.php`
6. `marketplace-event-subscription-observability.php`
7. `marketplace-worker-status.php`

## Что сейчас не хватает внешнему агенту

1. Более явной документации связей:
   - `listings` vs `read-models`
   - `route-resolve` vs `job-run`
   - `trigger/subscription/workflows/guide/dispatch/observability`

## Что появится следующим шагом

Планируемая следующая точка улучшения:

- `Phase 14 / Step 1`:
  - owner token introspection

Этот шаг уже закрыт.

Что он дал:

- отдельный endpoint `marketplace-owner-token-introspect.php`
- быстрый readback по owner token lifecycle
- `required_scope` evaluation для `template:manage` и `template:run`
- меньше необходимости ходить в owner token list ради одного токена

Планируемая следующая точка улучшения:

- `Phase 14 / Step 2`:
  - partner onboarding checklist surface

Этот шаг уже закрыт.

Что он дал:

- отдельный endpoint `marketplace-partner-onboarding-checklist.php`
- пошаговый setup plan для partner runtime
- `steps`, `next_actions`, `checklist_status`, `recommended_runtime_endpoint_id`
- меньше необходимости руками собирать `lifecycle + readiness + listing` в onboarding plan

Планируемая следующая точка улучшения:

- `Phase 14 / Step 3`:
  - event examples and readiness guide

Этот шаг уже закрыт.

Что он дал:

- отдельный endpoint `marketplace-event-readiness-guide.php`
- derived `guide_status`, `steps`, `next_actions`, `examples`
- меньше необходимости вручную склеивать `trigger + subscription + dispatch + workflow`
- более явный канонический event flow для внешних агентов

Планируемая следующая точка улучшения:

- `Phase 14 / Step 4`:
  - wire new discovery/readiness surfaces into marketplace UI

Этот шаг уже закрыт.

Что он дал:

- `marketplace-catalog` теперь содержит отдельный `Event readiness guide` console
- в UI доступны list/read фильтры readiness guide, step status, next actions и прямые endpoint links
- discovery-ссылки на `event-readiness-guide` и `event-workflows` теперь встроены в ту же control-plane страницу

Следующий roadmap step:

- `Phase 16 / Step 1`:
  - outbound allowlist policy for external adapters

Новый post-Phase 14 roadmap block теперь зафиксирован:

- `Phase 16 — Partner Runtime Hardening`
- `Phase 17 — Billing & Usage Ops`
- `Phase 18 — Event Reliability`
- `Phase 19 — Productization`

## Полезные browser surfaces

- Каталог и control plane:
  - `/topos/marketplace-catalog`
- Человеческое описание системы:
  - `/topos/marketplace-about`
- Общий системный обзор:
  - [MARKETPLACE_SYSTEM_OVERVIEW_RU.md](/var/www/shipinfo.net/topos/docs/MARKETPLACE_SYSTEM_OVERVIEW_RU.md)