AsyncAPI Skeletons And Event Envelopes — Первый bounded asynchronous contract artifact

Версия: 1.0
Дата: 24.04.2026
Статус: Готов к обсуждению

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

Этот документ фиксирует первый bounded слой для будущих AsyncAPI-артефактов платформы.

Его задача — определить:

• какие event families и async channels должны первыми получить formal asynchronous contract shape;
• какие envelopes уже нужно стандартизировать;
• какие события являются domain-significant, а какие остаются queue/job contracts;
• как async contracts соотносятся с release units, replay discipline и operational honesty.

Документ не является финальной AsyncAPI-спецификацией. Он является skeleton-layer, по которому уже можно собирать formal channel catalogs, event payload families и delivery semantics.

Опорные документы

• Eventing And Queue Baseline — Событийная шина, очереди и асинхронная дисциплина платформы
• Initial Event Taxonomy — Первичная таксономия событий платформы
• Initial Contract Package — Первый implementation-ready пакет контрактов платформы
• Implementation Ready Breakdown — Первые release units, execution slices и порядок практической реализации
• OpenAPI Skeletons And Resource Families — Первый bounded synchronous contract artifact
• Channel Catalog Drafts By Release Unit — Первые channel families, producers, consumers и delivery expectations
• Payload Family Outlines For High-Value Channels — Первые bounded payload shapes для ключевых async channels
• Payload Examples For Top Critical Events — Первые example payloads для ключевых async событий
• Schema Draft Package For Top Critical Events — Первый полуформальный schema-layer для критичных async событий
• Version Evolution Policy For Async Event Contracts — Правила версии, совместимости и replay-дисциплины
• Retry DLQ Replay Matrix By Schema Family — Исполнительная матрица доставки, повторов и восстановления
• Post-Booking Lifecycle — Изменения, отмены, инциденты и сопровождение после продажи
• Partner Finance And Clearing — Балансы, лимиты, взаиморасчёты и финансовая дисциплина партнёров
• Release Engineering And Migrations — Релизы, совместимость и эволюция схем
• Observability And Incident Response — Наблюдаемость и реагирование на инциденты

Почему Этот Документ Нужен Отдельно

После появления:

• initial contract package;
• openapi skeletons;
• initial event taxonomy;
• eventing baseline;

уже недостаточно просто говорить, что “события нужны”.

Нужен документ, который впервые фиксирует:

• какие async channels реально формализуем первыми;
• какие event envelopes считаются обязательными;
• где проходит граница между domain event, integration event и queue job;
• какие async contracts обязательны для первых release units, а какие пока не должны быть заморожены.

Без этого команда рискует:

• строить события как произвольные payload-ы вокруг брокера;
• смешивать domain transitions и worker commands;
• делать async layer богаче или хаотичнее, чем synchronous surface.

Главный Принцип

Первый AsyncAPI skeleton должен быть:

• domain-significant;
• replay-aware;
• bounded by release units;
• delivery-honest;
• traceable end-to-end;
• small enough to implement without async sprawl.

Async Contract Classes

1. Domain Event Channels

Нужны там, где platform reality уже meaningfully changed.

Примеры:

• canonical.property.updated
• offer.publication.allowed
• quote.invalidated
• booking.confirmed
• reconciliation.case.opened

2. Integration Event Channels

Нужны там, где событие используется для bounded fan-out между execution contours.

Примеры:

• downstream invalidation notifications;
• tenant usage degradation signals;
• operator-facing review escalation signals.

3. Queue Job Contracts

Не должны маскироваться под domain events.

Примеры:

• job.ingestion.replay
• job.quote.expiry.check
• job.booking.confirmation.poll
• job.reconciliation.recompute

First Mandatory Event Families

1. Supplier Intake And Canonicalization

Channel Families

• supplier.intake.*
• supplier.normalization.*
• mapping.*
• canonical.*

Почему Это Нужно Первым

Это backbone replay-aware ingestion path.

2. Offer And Publication

Channel Families

• offer.materialized
• offer.updated
• offer.integrity.blocked
• offer.publication.allowed
• offer.publication.suppressed

Почему Это Нужно Первым

Без этого offer/publication contour не будет иметь bounded invalidation and publication semantics.

3. Quote And Commercial

Channel Families

• quote.created
• quote.expired
• quote.invalidated
• quote.repricing.required
• quote.repriced
• commercial.policy.changed

Почему Это Нужно Первым

Quote lifecycle уже является отдельной truth-bearing and contract-bearing осью платформы.

4. Booking

Channel Families

• booking.intent.created
• booking.confirmation.pending
• booking.confirmed
• booking.partially.failed
• booking.unknown.external.state
• booking.cancel.requested
• booking.cancelled

Почему Это Нужно Первым

Booking требует bounded async semantics для recovery, observability и external state follow-up.

5. Post-Booking, Settlement And Clearing

Channel Families

• postbooking.change.requested
• postbooking.support.case.opened
• settlement.event.posted
• reconciliation.case.opened
• clearing.hold.created
• clearing.balance.blocked

Почему Это Нужно Первым

Платформа должна быть service-capable and financially accountable, а не только sell-capable.

6. Tenant And Usage Governance

Channel Families

• tenant.policy.changed
• tenant.surface.restricted
• usage.quota.nearing_limit
• usage.quota.exhausted
• usage.profile.degraded

Почему Это Нужно Первым

External distribution model требует bounded async visibility around tenant and usage consequences.

Event Envelope Baseline

Каждый first-wave domain-significant event должен уже иметь:

• event_name
• event_version
• event_id
• occurred_at
• producer
• correlation_id
• causation_id, where applicable
• tenant_id, where applicable
• domain object identifiers
• delivery_class
• replay_sensitivity

Queue Job Envelope Baseline

Каждый first-wave queue job contract должен уже иметь:

• job_type
• job_id
• created_at
• attempt
• max_attempts
• correlation_id
• idempotency_key, where applicable
• scheduled_for, where applicable
• payload reference or payload body

Channel Families By Release Unit

RU-2 Supplier Intake And Canonicalization Slice

Нужны:

• supplier intake events;
• normalization and mapping events;
• canonical change events;
• replay job envelopes.

RU-3 Offer And Publication Slice

Нужны:

• offer/publication events;
• invalidation and integrity gating signals.

RU-4 Commercial And Quote Slice

Нужны:

• quote lifecycle events;
• commercial policy change signals;
• quote expiry and refresh job contracts.

RU-5 Booking Commit Slice

Нужны:

• booking transition events;
• confirmation follow-up jobs;
• unknown-state recovery jobs.

RU-6 Post-Booking And Clearing Slice

Нужны:

• post-booking case events;
• settlement and reconciliation events;
• clearing signals;
• recompute and correction jobs.

RU-7 Controlled External Surface Slice

Нужны:

• bounded external-facing integration signals where surface-appropriate;
• tenant/usage governance signals for controlled partner visibility.

Common AsyncAPI-Level Concerns

Каждый первый async channel family должен уже поддерживать:

• explicit channel ownership;
• delivery semantics note;
• replay expectation note;
• retention note;
• idempotency expectation for consumers;
• correlation and causation fields;
• versioning note.

What Must Stay Out Of The First AsyncAPI Skeleton

Пока не нужно:

• строить exhaustive broker catalog для всех возможных внутренних сообщений;
• делать один giant public event catalog;
• обещать external webhooks для всех domain transitions;
• нормализовывать под один vendor-specific broker format;
• prematurely freeze payload schemas for still-evolving secondary contours.

Relationship Between OpenAPI And AsyncAPI Skeletons

Первый bounded synchronous и первый bounded asynchronous layers должны читаться как парные, но не как зеркальные.

OpenAPI skeleton отвечает на вопрос:

• какие bounded resources and mutations существуют на surface level.

AsyncAPI skeleton отвечает на вопрос:

• какие bounded transitions, downstream consequences and coordination signals существуют между execution contours.

Платформа не должна:

• прятать смысл синхронных promises в async noise;
• и не должна тащить в synchronous layer то, что operationally belongs to async coordination.

Что Должно Появиться Следом

Следующий слой после этого документа:

• Channel Catalog Drafts By Release Unit — Первые channel families, producers, consumers и delivery expectations
• first channel catalog drafts by release unit;
• first bounded payload-family outlines for high-value channels;
• first payload-family outlines for high-value event families;
• first concrete payload examples for top critical events;
• first semi-formal schema drafts for those critical events;
• first explicit version-evolution and compatibility policy for async contracts;
• first retry/DLQ/replay matrix by schema family;
• webhook policy for external-facing async notifications;
• queue policy matrix for retry, dead-letter and replay handling.

Этот документ создаёт bounded async foundation для следующего практического шага, но не подменяет собой детальную AsyncAPI спецификацию.

Уточнение под Фазы 4–6 (28.04.2026) — каноничные имена событий и связи

Документ опубликован 24.04.2026 (Фаза 3) как async contract baseline. После Фаз 4–6 каноничные имена событий новых доменов зафиксированы в специализированных источниках. При создании AsyncAPI specs использовать каноничные имена.

Каноничные источники имён событий

Класс события	Источник истины	Документ
Booking state transitions (14 каноничных)	booking-state-machine.md	reference/booking-state-machine.md
Payment events	payment-domain.md	reference/payment-domain.md
Tour Builder saga events	tour-builder-operational-model.md	reference/tour-builder-operational-model.md
Notification / webhook events	notification-and-communication.md	reference/notification-and-communication.md
Search / ranking events	search-and-discovery.md	reference/search-and-discovery.md
A/B testing events	ab-testing-platform.md	reference/ab-testing-platform.md
Tenant isolation events	multi-tenant-isolation-strength.md	reference/multi-tenant-isolation-strength.md
Security / audit events	security-architecture.md	reference/security-architecture.md
DR / capacity / SLA / incident events	operations/*	operations/disaster-recovery-and-capacity.md, operations/sla-and-on-call-model.md, operations/runbooks-incident-playbooks.md
Compliance events	compliance-and-legal.md	reference/compliance-and-legal.md

Сводный каталог имён — reference/initial-event-taxonomy.md (с уточнением под Фазы 4–6).

Расширенная классификация — 6 классов событий

Каноничные 6 классов событий с разными guarantees (см. eventing-and-queue-baseline.md, уточнение):

1. Domain events — at-least-once + ordered per entity, долгий retention;
2. Analytical events — at-least-once с допустимой потерей малой доли;
3. Saga events — exactly-once-effective + ordered;
4. Audit / security events — at-least-once + tamper-evident, 7 лет (Tier 1);
5. Operational events (DR, capacity, incidents, SLA breach) — at-least-once, regulated retention;
6. Compliance events (DSR, consent, breach notification) — at-least-once + immutable, 7+ лет.

При создании AsyncAPI spec — explicit указать класс event и его guarantees.

Связь с OpenAPI-first proposal

development/proposal-openapi-first-polyglot-codegen.md — open proposal: AsyncAPI specs — single source of truth для async contracts; code generation через OpenAPI Generator (rust-server template) для Rust, или native для Go/TypeScript.

Уточнение выполнено через no-destruction.