| 1 | # Intercom Wire (open protocol) |
| 2 | |
| 3 | **Канон протокола** Cascade Intercom — в репозитории **cascade-ide** (`wire/intercom-wire/`). Логически отделён от runtime сервера и UI IDE. |
| 4 | |
| 5 | | Слой | Что это | Где | |
| 6 | |------|---------|-----| |
| 7 | | **Wire** | События, payload, extensions (`relates_to`, code/doc) | `schemas/` | |
| 8 | | **Transport profile** | Как доставить wire (HTTP+SSE, Matrix, …) | `profiles/` | |
| 9 | | **Bindings** | DTO/codegen для языков | `bindings/` (опционально) | |
| 10 | |
| 11 | Политика: [ADR 0142](../../docs/adr/0142-intercom-open-wire-pluggable-transports.md) (Accepted). |
| 12 | Governance: [ADR 0146](../../docs/adr/0146-intercom-wire-canonical-protocol-package.md) (Accepted). |
| 13 | Reference server: [intercom-service](../../host/intercom-service/README.md) — profile `reference-http-v1`. |
| 14 | |
| 15 | ## Версионирование |
| 16 | |
| 17 | | Уровень | Поле / путь | Правило | |
| 18 | |---------|-------------|---------| |
| 19 | | **Wire major** | `transport-envelope.schema_version` | `1` — breaking меняет major | |
| 20 | | **Wire minor** | `CHANGELOG.md`, extensions | additive: новые `event_kind`, optional поля, `extensions/*` | |
| 21 | | **HTTP profile** | `/api/v1/…` | новый profile → `profiles/reference-http-v2/` | |
| 22 | |
| 23 | **Совместимость (норма):** |
| 24 | |
| 25 | - Клиенты и серверы **MUST** сохранять неизвестные поля JSON (не отбрасывать). |
| 26 | - Новые `event_kind` — сначала PR в **wire/** , потом реализации. |
| 27 | - Extensions (`relates_to`, `code_doc_link`) — optional на message payload; старые клиенты игнорируют. |
| 28 | |
| 29 | ## Структура `schemas/v1/` |
| 30 | |
| 31 | ``` |
| 32 | schemas/v1/ |
| 33 | transport-envelope.schema.json |
| 34 | event-kinds.json |
| 35 | extension-registry.json |
| 36 | common/attachment-anchor.schema.json |
| 37 | payloads/*.schema.json |
| 38 | extensions/*.schema.json |
| 39 | team-manifest.schema.json |
| 40 | ``` |
| 41 | |
| 42 | ## Потребители |
| 43 | |
| 44 | | Потребитель | Репозиторий | Использование | |
| 45 | |-------------|-------------|----------------| |
| 46 | | [host/intercom-service](../../host/intercom-service/) | **cascade-ide** | HTTP+SSE profile | |
| 47 | | [Features/Intercom/Transport](../../Features/Intercom/Transport/) | **cascade-ide** | CIDE FederatedSync | |
| 48 | | **intercom-web** | **[AI-Guiders/intercom-web](https://github.com/AI-Guiders/intercom-web)** (MIT) | PWA; wire — submodule/copy/raw URL | |
| 49 | | [docs/intercom-wire](../../docs/intercom-wire/README.md) | cascade-ide | Указатель из docs | |
| 50 | |
| 51 | ## Разработка расширений |
| 52 | |
| 53 | 1. JSON Schema в `schemas/v1/extensions/`. |
| 54 | 2. `extension-registry.json` + при необходимости `event-kinds.json`. |
| 55 | 3. `CHANGELOG.md` (minor). |
| 56 | 4. Service / CIDE / web — отдельные PR в том же репо. |
| 57 | |
| 58 | Не смешивать breaking wire и breaking HTTP profile без version bump. |
| 59 | |