Перейти к основному содержимому

Consumer Compatibility Checklist By Release Unit — Проверка готовности consumers к эволюции async contracts

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

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

Этот документ фиксирует первый release-unit-aware checklist для проверки consumer compatibility при изменении async event contracts.

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

  • что именно должны проверять consumers перед выпуском новой event version или schema-family change;
  • какие проверки общие для всех release units, а какие зависят от доменного контура;
  • как compatibility readiness связывается с replay, DLQ, observability, version windows и operator impact;
  • как превратить policy и matrices в практический gate для release discipline.

Документ не заменяет release plan или schema policy. Он является execution checklist, по которому можно принимать решение, готов ли конкретный release unit к эволюции async contracts.

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

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

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

  • version evolution policy;
  • retry/DLQ/replay matrix;
  • schema drafts;

уже недостаточно просто иметь хорошие правила “в теории”.

Команде нужен практический question-set:

  • consumer вообще поддерживает новую version?
  • умеет ли он безопасно игнорировать новые optional fields?
  • умеет ли он не сломаться на новых codes?
  • корректно ли он ведёт себя при replay и DLQ scenarios?
  • есть ли у него observability на mismatch and failure?

Без этого release discipline остаётся декларативной.

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

Producer change не считается готовым к выпуску, пока critical consumers не прошли compatibility checklist для своего release unit.

Ключевая идея:

compatibility must be demonstrated, not assumed.

Общий Checklist Для Всех Release Units​

Перед выпуском change в async contract consumers должны подтвердить:

  1. Consumer knows supported event_version and schema_family.
  2. Consumer behavior on unknown optional fields is safe.
  3. Consumer behavior on unknown bounded codes is explicit and observable.
  4. Consumer preserves idempotency semantics under retry.
  5. Consumer does not reinterpret old fields with new meaning.
  6. Consumer logs version/schema mismatch in structured form.
  7. Consumer produces operator-visible signal on terminal failure or DLQ path.
  8. Replay of historical events for this family has been assessed.
  9. Compatibility window for old and new versions is documented.
  10. Rollback or forward-fix stance is known.

RU-2 Supplier Intake And Canonicalization​

Relevant Families​

  • canonical-change
  • intake-related queue/job contracts

Consumer Compatibility Checklist​

  1. Consumer can process old and new canonical change payloads without losing entity identity.
  2. Consumer does not assume full snapshot when contract remains reference-heavy.
  3. Consumer preserves ordering assumptions only at documented entity scope.
  4. Replay path for normalization/canonical changes has been tested against consumer logic.
  5. Consumer exposes mismatch between payload shape and mapping/governance expectations.
  6. DLQ/quarantine path is visible to operators.
  7. Consumer does not silently materialize broken canonical updates into downstream offer state.

RU-3 Offer And Publication​

Relevant Families​

  • offer-publication
  • projection rebuild jobs/signals

Consumer Compatibility Checklist​

  1. Consumer understands current publication_state, integrity_state, freshness_state semantics.
  2. New suppression reason codes do not silently downgrade to “safe publish”.
  3. Consumer does not require hidden governance internals if contract says payload is bounded.
  4. Projection consumer can rebuild from replay without producing duplicate or stale external visibility.
  5. Publication mismatch is observable as incident/alert, not just local log noise.
  6. DLQ on publication consumers is operator-visible and linked to affected surface scope.
  7. Consumer compatibility has been checked for scoped replay by entity/surface.

RU-4 Commercial And Quote​

Relevant Families​

  • quote-lifecycle

Consumer Compatibility Checklist​

  1. Consumer understands current quote_state values and safe fallback for unknown future codes.
  2. Consumer does not confuse quote.invalidated with harmless informational signal.
  3. Consumer preserves difference between indicative context and quoted promise.
  4. Consumer handles newly added optional context fields without breaking booking guard.
  5. Replay of quote events has been assessed for repricing and UI drift impact.
  6. Quote expiry/invalidation failures are observable by version and consumer.
  7. DLQ path for quote consumers cannot leave stale quote truth silently alive.

RU-5 Booking Commit​

Relevant Families​

  • booking-transitions

Consumer Compatibility Checklist​

  1. Consumer distinguishes booking.confirmed and booking.unknown.external.state without ambiguity.
  2. New optional fields do not weaken support or incident semantics.
  3. Consumer does not treat unknown bounded code as safe success.
  4. Recovery jobs and domain event consumers keep separate logic and idempotency behavior.
  5. Replay of booking events is explicitly reviewed and gated.
  6. Mismatch between event semantics and support-facing state is observable immediately.
  7. DLQ on booking consumers is escalated as incident-grade signal.

RU-6 Post-Booking And Clearing​

Relevant Families​

  • post-booking-case
  • settlement-reconciliation

Consumer Compatibility Checklist​

  1. Service-case consumer preserves case ownership and SLA semantics across versions.
  2. Financial consumer preserves strict distinction between booking truth and settlement/reconciliation truth.
  3. Consumer does not blindly retry duplicate-sensitive financial processing.
  4. New optional fields do not alter discrepancy meaning or clearing effect silently.
  5. Replay of settlement/reconciliation families has explicit finance review stance.
  6. DLQ on settlement or reconciliation path is visible to finance/ops contours.
  7. Consumer version mismatch on financial events is treated as serious operational risk, not warning-level noise.

RU-7 Controlled External Surface​

Relevant Families​

  • usage-governance
  • externally visible integration signals derived from internal families

Consumer Compatibility Checklist​

  1. Gateway/enforcement consumer correctly handles current governance_state and enforcement_class.
  2. Unknown future governance codes do not default to permissive behavior.
  3. Consumer can ignore additive optional fields without losing enforcement correctness.
  4. Compatibility window for partner-facing behavior is documented.
  5. Version mismatch is observable in external-surface operations.
  6. DLQ or enforcement failure produces operator-visible contradiction signal.
  7. Replay of governance signals is evaluated for tenant-facing consequence drift.

Cross-Cutting Replay Checklist​

Для любой release unit change необходимо подтвердить:

  1. Historical replay affected or not affected?
  2. If affected, which consumers were revalidated?
  3. Can replay produce different external or support-facing outcome?
  4. Are replay flows observable separately from live flows?
  5. Is operator/finance/support escalation needed for replay of this family?

Cross-Cutting DLQ Checklist​

Для любой release unit change необходимо подтвердить:

  1. What pushes consumer into DLQ?
  2. Is DLQ terminal state observable?
  3. Who owns DLQ triage?
  4. Can DLQ accumulation create false-safe platform state?
  5. Is there a documented recovery path from DLQ back to valid processing?

Cross-Cutting Version Window Checklist​

Для любой release unit change необходимо подтвердить:

  1. Which old versions remain supported during overlap?
  2. Which consumers are lagging?
  3. How long does compatibility window remain open?
  4. What telemetry proves old/new version coexistence safely?
  5. What is retirement condition for old version?

Release Gate Use​

Этот checklist должен использоваться как release gate в следующих случаях:

  • schema-family change;
  • event_version bump;
  • new bounded code introduction in critical families;
  • replay-sensitive consumer logic change;
  • new consumer onboarding on high-value family.

What Must Stay Out Of Scope​

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

  • превращать checklist в low-level QA test cases;
  • описывать every implementation detail by runtime language;
  • считать, что one release unit checklist covers all future maturity stages.

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

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

Этот документ делает async compatibility operationally checkable и закрывает важный gap между policy, matrix и реальным выпуском изменений.

Уточнение под Фазы 4–6 (28.04.2026)​

Consumer compatibility checklist должен покрывать каноничные новые domain events фаз 4–6:

  • Booking state transitions (14 каноничных) — consumer обязан корректно обрабатывать unknown_external_state;
  • Payment events — consumer обрабатывает payment.intent.*, payment.refund.*, payment.chargeback.*;
  • Tour saga events — consumer обрабатывает saga compensation flow;
  • Webhook signing — обязательная HMAC verification (см. security-architecture.md);
  • Tier-зависимое certification (см. api-as-product.md).

Каноничные имена событий per домен — initial-event-taxonomy.md.

Связь с release engineering → release-engineering-and-migrations.md, уточнение под Фазы 4–7 (release gates с error budget check).

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