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

Version Evolution Policy For Async Event Contracts — Правила версии, совместимости и replay-дисциплины

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

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

Этот документ фиксирует правила эволюции async event contracts платформы.

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

  • как изменяются schema families и event versions;
  • что считается additive change, а что breaking change;
  • когда обязателен version bump;
  • как changes влияют на replay, consumers, observability и downstream operational contours;
  • как удерживать compatibility discipline без торможения развития платформы.

Документ не является чисто технической заметкой про semver. Это policy-документ про безопасную эволюцию async contracts в живой industrial платформе.

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

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

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

  • schema drafts;
  • payload examples;
  • channel catalog;

уже недостаточно просто сказать, что “позже поднимем версию, если что-то сломаем”.

Платформе нужен явный policy-layer, который отвечает:

  • какие изменения допустимы без version bump;
  • какие изменения опасны для replay;
  • как долго old versions живут параллельно;
  • как должны вести себя producers и consumers в compatibility windows;
  • что считается unacceptable semantic drift even when JSON shape формально не меняется.

Без этого event layer почти неизбежно скатывается в хаос несовместимых consumers или silent semantic breakage.

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

Async contract считается совместимым только тогда, когда:

  • existing consumers продолжают корректно читать событие;
  • replay of historical events не разрушает operational truth;
  • semantic meaning bounded codes и critical fields не уходит из-под ног;
  • support, observability и incident analysis не теряют объяснимость.

Формально “JSON ещё парсится” недостаточно.

Versioning Surfaces​

В async layer должны различаться:

1. Event Name Stability​

event_name не должен меняться без очень сильной причины.

Если доменный смысл события остаётся тем же, переименование — это usually avoidable churn.

2. Event Version​

event_version отражает contract evolution конкретного event family.

3. Schema Family Version​

schema_family отражает lineage группы событий, например:

  • quote-lifecycle.v1
  • booking-transitions.v1
  • settlement-reconciliation.v1

4. Consumer Capability Window​

Практически важно не только “какая версия существует”, но и:

  • какие versions consumers обязаны понимать;
  • сколько длится overlap;
  • когда old version can be retired.

Additive Changes​

Обычно Допустимы Без Breaking Version Shift​

  • добавление optional field;
  • добавление optional bounded reference field;
  • добавление optional metadata hint;
  • расширение reason/details block optional fields;
  • добавление новой optional code-bearing field, если old consumers её безопасно игнорируют.

Условия Допустимости​

Такое изменение допустимо только если:

  • existing required fields не меняются;
  • existing meanings не меняются;
  • consumer fallback semantics понятны;
  • replay old events remains valid.

Breaking Changes​

Следующее должно считаться breaking change risk:

1. Removing Required Field​

Если поле было required, его удаление требует new version.

2. Changing Meaning Of Existing Field​

Даже если поле формально осталось того же типа, semantic drift — это breaking change.

Примеры:

  • booking_state начинает значить другую стадию;
  • publication_scope меняет policy meaning;
  • financial_state_class начинает описывать другой accounting момент.

3. Replacing Reference With Heavy Embedded Shape Or Vice Versa​

Если consumer logic была завязана на old shape assumptions, это breaking risk.

4. Changing Bounded Code Semantics​

Нельзя silently менять meaning таких полей:

  • repricing_reason_code
  • support_visibility_class
  • transactional_outcome_class
  • governance_state
  • enforcement_class

5. Changing Ordering Or Causation Assumptions​

Если consumer relied on event ordering, idempotency key logic or causation chain, такое изменение требует отдельной compatibility review.

When Version Bump Is Mandatory​

Version bump обязателен, когда:

  • removed or renamed required field;
  • changed semantic contract of existing required field;
  • changed code semantics in a non-backward-meaningful way;
  • changed payload structure so old consumer assumptions are broken;
  • changed event meaning from domain event to integration signal or vice versa;
  • changed replay interpretation of historical events.

When Additive Evolution Is Allowed​

Additive evolution допустима без major contract shift, если:

  • new field optional;
  • new field ignorable for existing consumers;
  • no semantic drift in existing fields;
  • replay of historical events is unchanged;
  • support and observability interpretation remains stable.

Replay Discipline​

Replay-Sensitive Families​

Особенно осторожны должны быть:

  • quote-lifecycle
  • booking-transitions
  • offer-publication
  • settlement-reconciliation
  • canonical change families

Rule​

Если schema evolution делает ambiguous interpretation of old historical events possible, это не additive change. Это replay-risking change и должно проходить stricter review.

Consumer Compatibility Windows​

Для high-value async contracts должен действовать controlled overlap period:

  • producer can emit new version only when critical consumers are ready;
  • during overlap, observability must show which version is flowing;
  • old version retirement must be explicit and documented;
  • replay tooling must know which historical versions can still appear.

Producer Responsibilities​

Producer обязан:

  • объявить schema family and version;
  • задокументировать required/optional changes;
  • указать replay impact;
  • указать whether consumer fallback is safe;
  • не выпускать semantic drift as “minor cleanup”.

Consumer Responsibilities​

Consumer обязан:

  • явно знать supported versions;
  • fail predictably on unsupported critical versions;
  • not silently reinterpret unknown codes as safe success states;
  • log schema/version mismatch in observable form;
  • preserve idempotency behavior across supported versions.

Semantic Drift Is A First-Class Risk​

Даже если:

  • поле осталось string;
  • payload still validates;
  • JSON shape almost identical;

это не означает compatibility, если meaning changed.

Платформа должна считать semantic drift одним из главных источников production regressions in async systems.

Value-Class Governance​

Для bounded code-bearing fields должны действовать правила:

  • adding new code may be additive only if consumer fallback semantics are safe;
  • repurposing existing code is breaking risk;
  • deleting old code meaning requires version evolution note;
  • unknown code must never be silently treated as successful/healthy state in critical consumers.

Observability Requirements For Version Evolution​

При любой значимой эволюции async contract layer должны быть видимы:

  • event version emitted by producer;
  • consumer acceptance/rejection by version;
  • mismatch/error counters;
  • replay jobs touching old versions;
  • backlog split if multiple versions coexist.

Release Discipline For Async Contract Changes​

Изменение async contract не должно выпускаться как isolated schema tweak.

Оно должно идти вместе с:

  • producer change plan;
  • consumer readiness plan;
  • replay impact note;
  • observability watchlist;
  • rollback or forward-fix stance;
  • explicit compatibility window.

What Counts As Safe Forward-Only Evolution​

Forward-only evolution допустима, когда:

  • old events remain interpretable;
  • new optional fields do not redefine meaning;
  • consumers can ignore new fields safely;
  • no old historical replay loses meaning.

What Counts As Unsafe Silent Change​

Unsafe silent change — это когда:

  • producer emits same event_name and version,
  • but consumers now should read old fields differently,
  • or operational/support semantics changed,
  • or replay of historical events now yields different truth implications.

Такое изменение должно считаться policy violation.

First-Wave Policy For Current Schema Families​

quote-lifecycle.v1​

  • additive optional context fields allowed;
  • quote state meaning must remain stable;
  • repricing/invalidation code meanings require strict review.

booking-transitions.v1​

  • operational seriousness fields must remain explicit;
  • support/recovery semantics cannot silently weaken;
  • unknown-state and confirmed transitions must remain clearly distinct.

offer-publication.v1​

  • publication and integrity state meaning must stay bounded;
  • suppression reason catalog may grow;
  • hidden governance internals should not leak into public-facing derivations.

settlement-reconciliation.v1​

  • financial state classes need strict compatibility review;
  • accounting-heavy expansion should not be smuggled into existing shape;
  • reference-based growth preferred over snapshot explosion.

usage-governance.v1​

  • enforcement meaning must remain explicit;
  • governance states cannot silently change severity semantics;
  • metering metrics expansion should remain outside core enforcement event shape.

What Must Stay Out Of Scope​

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

  • закреплять vendor-specific semver scheme;
  • строить universal registry process for every future event family;
  • описывать every approval workflow detail;
  • считать this policy final for all future platform maturity stages.

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

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

Этот документ фиксирует правила безопасной эволюции async contracts и закрывает важный policy gap между schema drafts и production-grade event lifecycle discipline.

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

Эволюция async contracts должна учитывать каноничные структуры событий из reference-документов фаз 4–6.

Обязательные ограничения совместимости при эволюции схем (расширения этого документа):

  • Booking states — нельзя сливать или переименовывать каноничные 14 состояний без major version bump (см. booking-state-machine.md);
  • Payment events — изменения PaymentIntent lifecycle (created/authorized/captured) — major impact на PSP integrations (см. payment-domain.md);
  • Tour saga events — running sagas должны корректно обрабатываться новой логикой (см. tour-builder-operational-model.md);
  • Audit / security events — immutable, эволюция только additive (см. security-architecture.md);
  • Compliance events — regulated, эволюция через compliance review (см. compliance-and-legal.md).

Tier-зависимые deprecation windows (см. api-as-product.md):

  • Free / Starter — 6 месяцев notice;
  • Professional — 12 месяцев;
  • Enterprise — custom (по контракту).

Release engineering integration → release-engineering-and-migrations.md, уточнение под Фазы 4–7.

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